feat(plugins): add versioned offline brand icons and author guidance

This commit is contained in:
Codex committed 2026-10-26 05:26:25 +00:00
1 parent 614b7c997a
commit f4a6b205ad
43 files changed
+546 -42

No files matched your search

+21 -1
View File
@@ -14,6 +14,7 @@ import {
import path from "node:path";
import { once } from "node:events";
import { inspectPluginBrandIcon, PLUGIN_BRAND_ICON_MAX_BYTES } from "@netcatty/plugin-contract";
import type { IconReference, PluginManifest } from "@netcatty/plugin-contract";
import yauzl, { type Entry, type ZipFile } from "yauzl";
@@ -292,6 +293,7 @@ async function scanPackageDirectory(
const packagedPaths = new Set(files.map(({ packagePath }) => packagePath));
const requiredPaths = [
"netcatty.plugin.json",
...packageIconPaths(manifest.icon),
manifest.main.browser,
manifest.main.node,
...(manifest.contributes?.views ?? []).map(({ entry }) => entry),
@@ -305,6 +307,18 @@ async function scanPackageDirectory(
throw new Error(`Manifest references a missing package file: ${requiredPath}`);
}
}
for (const iconPath of packageIconPaths(manifest.icon)) {
const file = files.find((entry) => entry.packagePath === iconPath)!;
if (file.size > PLUGIN_BRAND_ICON_MAX_BYTES) throw new Error('Plugin brand icon exceeds size limit');
const handle = await open(file.absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
try {
const stats = await handle.stat();
if (!stats.isFile() || stats.size !== file.size) throw new Error('Brand icon changed during packaging');
const bytes = await handle.readFile();
if (createHash('sha256').update(bytes).digest('hex') !== file.sha256) throw new Error('Brand icon changed during packaging');
inspectPluginBrandIcon(bytes, iconPath);
} finally { await handle.close(); }
}
return files.sort(sortPackagePaths);
}
@@ -697,7 +711,7 @@ async function inspectPluginPackage(
const result = await readEntry(
zipFile,
entry,
packagePath === "netcatty.plugin.json",
packagePath === "netcatty.plugin.json" || (/\.(png|webp)$/.test(packagePath) && entry.uncompressedSize <= PLUGIN_BRAND_ICON_MAX_BYTES),
extractionDirectory ? path.join(extractionDirectory, ...packagePath.split("/")) : undefined,
);
if (result.bytes !== entry.uncompressedSize || result.crc32 !== entry.crc32) {
@@ -733,6 +747,7 @@ async function inspectPluginPackage(
}
}
const requiredPaths = [
...packageIconPaths(manifest.icon),
manifest.main.browser,
manifest.main.node,
...(manifest.contributes?.views ?? []).map(({ entry }) => entry),
@@ -745,6 +760,11 @@ async function inspectPluginPackage(
throw new Error(`Manifest references a missing package file: ${requiredPath}`);
}
}
for (const iconPath of packageIconPaths(manifest.icon)) {
const contents = entries.get(iconPath)?.contents;
if (!contents) throw new Error('Brand icon is missing or exceeds size limit');
inspectPluginBrandIcon(contents, iconPath);
}
for (const [companionPath, companion] of declaredCompanions) {
const entry = entries.get(companionPath);
if (!entry) throw new Error(`Manifest references a missing companion: ${companionPath}`);
@@ -0,0 +1,57 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { mkdtemp, mkdir, readFile, writeFile, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { inspectPluginBrandIcon } from '@netcatty/plugin-contract';
import { validateManifestValue } from './manifest.js';
import { checkPluginCompatibility } from './compatibility.js';
import { buildPluginPackage, validatePluginDirectory, validatePluginPackage } from './archive.js';
const example = new URL('../../../examples/plugins/starter-netcatty/', import.meta.url);
const manifest = JSON.parse(await readFile(new URL('netcatty.plugin.json', example), 'utf8'));
const png = await readFile(new URL('assets/logo-light.png', example));
test('brand metadata requires the new API and feature; legacy exact API remains supported', () => {
assert.equal(validateManifestValue(manifest).valid, true);
assert.equal(validateManifestValue({ ...manifest, features: {} }).valid, false);
assert.equal(validateManifestValue({ ...manifest, engines: { ...manifest.engines, api: '0.1.0-internal' } }).valid, false);
for (const light of ['../outside.png', '/tmp/logo.png', 'https://example.com/logo.png', 'assets/a.svg', 'a\\b.png']) {
assert.equal(validateManifestValue({ ...manifest, icon: { kind: 'package', light } }).valid, false, light);
}
assert.equal(checkPluginCompatibility(manifest, { netcattyVersion: '1.0.0', apiVersion: '0.1.0-internal', features: [] }).compatible, false);
assert.equal(checkPluginCompatibility(manifest, { netcattyVersion: '1.0.0', features: ['metadata.brand-icon'] }).compatible, true);
const { icon: _icon, features: _features, ...legacy } = manifest;
const result = checkPluginCompatibility({ ...legacy, engines: { ...legacy.engines, api: '0.1.0-internal' } }, { netcattyVersion: '1.0.0' });
assert.equal(result.compatible, true);
assert.equal(result.apiVersion, '0.1.0-internal');
});
test('brand raster inspection rejects oversized, animated, truncated and disguised inputs', () => {
assert.equal(inspectPluginBrandIcon(png, 'logo.png').width, 128);
const webp = Buffer.from('UklGRhwAAABXRUJQVlA4TA8AAAAvD8ADAAcQ0f/+ByKi/wEA', 'base64');
assert.equal(inspectPluginBrandIcon(webp, 'logo.webp').width, 16);
const animatedWebp = Buffer.from(webp); animatedWebp.write('ANIM', 12);
assert.throws(() => inspectPluginBrandIcon(animatedWebp, 'logo.webp'), /Animated/);
assert.throws(() => inspectPluginBrandIcon(png, 'logo.webp'));
assert.throws(() => inspectPluginBrandIcon(Buffer.alloc(256 * 1024 + 1), 'logo.png'));
const huge = Buffer.from(png); huge.writeUInt32BE(513, 16);
assert.throws(() => inspectPluginBrandIcon(huge, 'logo.png'), /dimensions/);
assert.throws(() => inspectPluginBrandIcon(png.subarray(0, 32), 'logo.png'));
const animated = Buffer.from(png); const idat = animated.indexOf('IDAT'); animated.write('acTL', idat);
assert.throws(() => inspectPluginBrandIcon(animated, 'logo.png'), /Animated/);
});
test('directory validation, packing and archive validation include both brand resources', async (t) => {
const root = await mkdtemp(path.join(tmpdir(), 'netcatty-brand-'));
t.after(() => rm(root, { recursive: true, force: true }));
const dir = path.join(root, 'plugin'); await mkdir(path.join(dir, 'assets'), { recursive: true });
await writeFile(path.join(dir, 'index.js'), 'export function activate() {}');
const m = { ...manifest, main: { browser: 'index.js' }, contributes: undefined, activationEvents: [] };
await writeFile(path.join(dir, 'netcatty.plugin.json'), JSON.stringify(m));
await writeFile(path.join(dir, 'assets/logo-light.png'), png);
await assert.rejects(validatePluginDirectory(dir), /missing package file/);
await writeFile(path.join(dir, 'assets/logo-dark.png'), png);
const archive = path.join(root, 'plugin.ncpkg');
await buildPluginPackage(dir, archive);
assert.deepEqual((await validatePluginPackage(archive)).manifest.icon, m.icon);
await writeFile(path.join(dir, 'assets/logo-dark.png'), Buffer.alloc(256 * 1024 + 1));
await assert.rejects(validatePluginDirectory(dir), /size limit/);
});
+1 -1
View File
@@ -61,7 +61,7 @@ export async function initPlugin(
private: true,
type: "module",
scripts: { build: "tsc -p tsconfig.json" },
dependencies: { "@netcatty/plugin-sdk": "0.1.0-internal" },
dependencies: { "@netcatty/plugin-sdk": "0.1.0-internal.1" },
devDependencies: { typescript: "^5.9.0" },
}, null, 2)}\n`,
"utf8",
+8 -2
View File
@@ -3,7 +3,7 @@ import {
} from "@netcatty/plugin-contract";
import { satisfies, valid, validRange } from "semver";
const DEFAULT_PLUGIN_API_VERSION = "0.1.0-internal";
const DEFAULT_PLUGIN_API_VERSION = "0.1.0-internal.1";
export interface PluginCompatibilityTarget {
readonly netcattyVersion: string;
@@ -43,7 +43,13 @@ export function checkPluginCompatibility(
manifest: PluginManifest,
target: PluginCompatibilityTarget,
): PluginCompatibilityResult {
const apiVersion = target.apiVersion ?? DEFAULT_PLUGIN_API_VERSION;
let apiVersion = target.apiVersion ?? DEFAULT_PLUGIN_API_VERSION;
// This host still offers the previous, unchanged wire contract to legacy packages.
// Never negotiate new brand metadata down to a host revision that cannot validate it.
if (apiVersion === DEFAULT_PLUGIN_API_VERSION && !manifest.icon
&& !satisfies(apiVersion, manifest.engines.api) && satisfies('0.1.0-internal', manifest.engines.api)) {
apiVersion = '0.1.0-internal';
}
const errors: string[] = [];
checkEngineVersion("Netcatty", target.netcattyVersion, manifest.engines.netcatty, errors);
checkEngineVersion("plugin API", apiVersion, manifest.engines.api, errors);
+9 -1
View File
@@ -15,7 +15,7 @@ import type {
} from "@netcatty/plugin-contract";
import Ajv2020, { type ErrorObject } from "ajv/dist/2020.js";
import addFormats from "ajv-formats";
import { valid, validRange } from "semver";
import { satisfies, valid, validRange } from "semver";
import { PACKAGE_LIMITS } from "./constants.js";
import { assertSafePackagePath } from "./packagePath.js";
@@ -367,6 +367,13 @@ function validateSemantics(manifest: PluginManifest): string[] {
}
const requiredFeatures = new Set(manifest.features?.required ?? []);
if (manifest.icon) {
if (!requiredFeatures.has('metadata.brand-icon')) errors.push('Brand icons require metadata.brand-icon');
if (!validRange(manifest.engines.api) || !satisfies('0.1.0-internal.1', manifest.engines.api) || satisfies('0.1.0-internal', manifest.engines.api)) errors.push('Brand icons require API >=0.1.0-internal.1 excluding the legacy revision');
for (const iconPath of packageIconPaths(manifest.icon)) {
if (!/\.(png|webp)$/.test(iconPath)) errors.push('Brand icons require PNG or WebP paths');
}
}
for (const feature of manifest.features?.optional ?? []) {
if (requiredFeatures.has(feature)) {
errors.push(`Feature cannot be both required and optional: ${feature}`);
@@ -672,6 +679,7 @@ function validateSemantics(manifest: PluginManifest): string[] {
}
for (const entryPath of [
...packageIconPaths(manifest.icon),
manifest.main.browser,
manifest.main.node,
...(manifest.contributes?.views ?? []).map(({ entry }) => entry),