mirror of
https://github.com/binaricat/Netcatty.git
synced 2026-11-21 07:32:54 +00:00
feat(plugins): add versioned offline brand icons and author guidance
This commit is contained in:
1 parent
614b7c997a
commit
f4a6b205ad
43 files changed
+546
-42
No files matched your search
@@ -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/);
|
||||
});
|
||||
@@ -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",
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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),
|
||||
|
||||
Reference in new issue
Block a user