@motrix/plugin-cli 2.0.0 → 2.1.0

package/README.md

@@ -35,7 +35,16 @@ motrix-plugin validate
 ```
 Validate `motrix-plugin.json` against
 [`@motrix/plugin-manifest-schema`](https://www.npmjs.com/package/@motrix/plugin-manifest-schema) —
-the same schema the Motrix host uses when installing a plugin.
+the same schema the Motrix host uses when installing a plugin. Beyond the
+schema this also applies the rules a schema cannot express:
+
+- **hooks ⇒ hostPermissions** — contributing any hook requires at least one
+  `hostPermissions` entry, or the host refuses to install the plugin
+- **locale coverage** — every `%key%` the manifest interpolates must exist in
+  `en-US`, including the ones under `contributes.configuration`
+
+`pack` runs this identical gate, so the two commands can never disagree about
+whether a plugin is shippable.
 
 ### Schema versioning
 
@@ -49,22 +58,39 @@ staying current on the CLI keeps you current on the schema too.
 ```bash
 motrix-plugin lint
 ```
-Static checks beyond schema validation: locale coverage
-(`contributes`/UI strings present in every declared locale) and
-top-level side-effect detection (guest code must not run effectful code at
-module scope).
+Static checks on the **packed bundle**, so run `pack` first: top-level
+side-effect detection (guest code must not run effectful code at module
+scope), a size warning as the bundle approaches the 1 MiB cap, and advisories
+for `invokesCommands` entries whose callee may not be installed.
 
 ```bash
 motrix-plugin validate-host-permissions
 ```
-Sanity-check `hostPermissions` match patterns and warn on overly broad grants
-(e.g. `<all_urls>`).
+Reviews `hostPermissions` in more depth than `validate` does: each pattern is
+parsed with the host's own match-pattern grammar, and broad grants
+(`<all_urls>`, `https://*/*`) are reported as warnings so you can narrow them.
 
 ```bash
 motrix-plugin pack
 ```
-Bundle the plugin with esbuild and zip it into a `.moext` distributable,
-enforcing the per-bundle and total package size limits.
+Produce the `.moext` distributable at `dist/<id>-<version>.moext`.
+
+Every gate — schema, hooks ⇒ hostPermissions, locale coverage — runs *before*
+esbuild writes anything, so a rejected plugin leaves no half-built bundle
+behind and a `.moext` the host would refuse to install cannot be created in the
+first place. The bundle is then checked against the 1 MiB cap and the archive
+against 5 MiB.
+
+The archive is **reproducible**: entries are written in sorted order with
+pinned timestamps and modes, so the same source tree always yields the same
+bytes, on any machine and in any timezone. `pack` prints the resulting sha256 —
+that is the value a registry entry's `package.sha256` needs, and re-packing an
+unchanged tree must reprint it.
+
+```
+Packed → …/dist/acme.demo-1.0.0.moext (4540 bytes)
+sha256   5d69eaf3bb44992952beafc67d818ff376b8478de4b32b936ce5e603b963605d
+```
 
 ```bash
 pnpm create motrix-plugin my-plugin [template]

package/dist/bin/motrix-plugin.js

@@ -14954,6 +14954,73 @@ var ManifestSchema = external_exports.object({
   contributes: ContributesSchema,
   l10n: external_exports.string().max(256).optional()
 }).strict();
+var HOST_PERMISSIONS_REQUIRED_FOR_HOOKS = "plugin.manifest.host_permissions_required_for_hooks";
+var LOCALE_MISSING_EN_US = "plugin.manifest.locale.missing_en_us";
+var LOCALE_MISSING_KEYS = "plugin.manifest.locale.missing_keys";
+function requireHostPermissionsForHooks(manifest, id = "<unknown>") {
+  const hooks = manifest.contributes?.hooks;
+  const hasHooks = hooks != null && Object.keys(hooks).length > 0;
+  if (!hasHooks) return;
+  const hostPermissions = Array.isArray(manifest.hostPermissions) ? manifest.hostPermissions : [];
+  if (hostPermissions.length === 0) {
+    throw new Error(
+      `${id}: ${HOST_PERMISSIONS_REQUIRED_FOR_HOOKS}: declared hooks require at least one hostPermissions entry`
+    );
+  }
+}
+function validateManifest(manifest, id) {
+  const label = id ?? (typeof manifest?.id === "string" ? manifest.id : "<unknown>");
+  let parsed;
+  try {
+    parsed = ManifestSchema.parse(manifest);
+  } catch (err) {
+    const issues = err.issues;
+    const detail = Array.isArray(issues) ? issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ") : err?.message ?? String(err);
+    throw new Error(`${label}: invalid motrix-plugin.json \u2014 ${detail}`);
+  }
+  requireHostPermissionsForHooks(parsed, label);
+  return parsed;
+}
+function flattenLocaleKeys(source, prefix = "", out = /* @__PURE__ */ new Set()) {
+  for (const [key, value] of Object.entries(source)) {
+    const path9 = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === "string") out.add(path9);
+    else if (value && typeof value === "object") {
+      flattenLocaleKeys(value, path9, out);
+    }
+  }
+  return out;
+}
+function collectLocaleRefs(manifest) {
+  const found = /* @__PURE__ */ new Set();
+  const walk = (node) => {
+    if (typeof node === "string") {
+      const m = node.match(/^%([^%]+)%$/);
+      if (m) found.add(m[1]);
+      return;
+    }
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item);
+      return;
+    }
+    if (node && typeof node === "object") {
+      for (const value of Object.values(node)) walk(value);
+    }
+  };
+  walk(manifest);
+  return [...found];
+}
+function checkLocaleCoverage(manifest, baseLocale) {
+  if (!manifest.l10n) return;
+  if (baseLocale == null) throw new Error(LOCALE_MISSING_EN_US);
+  const refs = collectLocaleRefs(manifest);
+  if (refs.length === 0) return;
+  const available = flattenLocaleKeys(baseLocale);
+  const missing = refs.filter((key) => !available.has(key));
+  if (missing.length > 0) {
+    throw new Error(`${LOCALE_MISSING_KEYS}: ${missing.sort().join(", ")}`);
+  }
+}
 
 // src/commands/lint.ts
 async function lint(projectDir) {
@@ -14992,6 +15059,7 @@ async function lint(projectDir) {
 }
 
 // src/commands/pack.ts
+import { createHash } from "crypto";
 import { createWriteStream } from "fs";
 import { mkdir as mkdir2, readdir as readdir2, readFile as readFile4, stat as stat3, unlink } from "fs/promises";
 import path6 from "path";
@@ -15003,52 +15071,32 @@ import { readFile as readFile3 } from "fs/promises";
 import path5 from "path";
 async function validateLocaleCoverage(projectDir, manifest) {
   if (!manifest.l10n) return;
-  const dir = path5.join(projectDir, manifest.l10n);
-  let enUS;
+  let baseLocale = null;
   try {
-    enUS = JSON.parse(await readFile3(path5.join(dir, "en-US.json"), "utf8"));
-  } catch {
-    throw new Error("plugin.manifest.locale.missing_en_us");
-  }
-  const keys = /* @__PURE__ */ new Set();
-  function walk(o, prefix = "") {
-    for (const [k, v] of Object.entries(o)) {
-      const p = prefix ? `${prefix}.${k}` : k;
-      if (typeof v === "string") keys.add(p);
-      else if (v && typeof v === "object") walk(v, p);
-    }
-  }
-  walk(enUS);
-  const collected = [];
-  const visit = (s) => {
-    if (typeof s === "string") {
-      const m = s.match(/^%([^%]+)%$/);
-      if (m) collected.push(m[1]);
-    }
-  };
-  visit(manifest.name);
-  visit(manifest.description);
-  for (const c of manifest.contributes?.commands ?? []) visit(c.title);
-  const missing = collected.filter((k) => !keys.has(k));
-  if (missing.length > 0) {
-    throw new Error(
-      `plugin.manifest.locale.missing_keys: ${missing.join(", ")}`
+    baseLocale = JSON.parse(
+      await readFile3(path5.join(projectDir, manifest.l10n, "en-US.json"), "utf8")
     );
+  } catch {
+    baseLocale = null;
   }
+  checkLocaleCoverage(manifest, baseLocale);
 }
 
 // src/commands/pack.ts
 var BUNDLE_MAX = 1024 * 1024;
 var TOTAL_MAX = 5 * 1024 * 1024;
+var DOS_EPOCH = new Date(1980, 0, 1, 0, 0, 0);
+var ENTRY_MODE = 33188;
 async function pack(opts) {
   const projectDir = path6.resolve(opts.projectDir);
   const manifestPath = path6.join(
     projectDir,
     opts.manifest ?? "motrix-plugin.json"
   );
-  const manifest = ManifestSchema.parse(
+  const manifest = validateManifest(
     JSON.parse(await readFile4(manifestPath, "utf8"))
   );
+  await validateLocaleCoverage(projectDir, manifest);
   const entry = opts.entry ?? "src/index.ts";
   const outDir = path6.join(projectDir, opts.outDir ?? "dist");
   await mkdir2(outDir, { recursive: true });
@@ -15072,41 +15120,54 @@ async function pack(opts) {
       `bundle ${bundle.byteLength} bytes > ${BUNDLE_MAX} byte cap`
     );
   }
-  await validateLocaleCoverage(projectDir, manifest);
   const moextOut = path6.join(outDir, `${manifest.id}-${manifest.version}.moext`);
-  const z2 = new yazl.ZipFile();
-  z2.addFile(manifestPath, "motrix-plugin.json");
-  z2.addFile(bundlePath, "dist/plugin.js");
+  const entries = [
+    { abs: manifestPath, rel: "motrix-plugin.json" },
+    { abs: bundlePath, rel: "dist/plugin.js" }
+  ];
   for (const f of ["icon.png", "LICENSE", "CHANGELOG.md"]) {
     try {
       await stat3(path6.join(projectDir, f));
-      z2.addFile(path6.join(projectDir, f), f);
+      entries.push({ abs: path6.join(projectDir, f), rel: f });
     } catch {
     }
   }
   if (manifest.l10n) {
+    const localeDir = path6.join(projectDir, manifest.l10n);
+    let localeEntries = [];
     try {
-      const localeDir = path6.join(projectDir, manifest.l10n);
-      const entries = await readdir2(localeDir, { withFileTypes: true });
-      for (const e of entries) {
-        if (!e.isFile()) continue;
-        z2.addFile(path6.join(localeDir, e.name), `${manifest.l10n}/${e.name}`);
-      }
-    } catch {
+      localeEntries = await readdir2(localeDir);
+    } catch (err) {
+      if (err?.code !== "ENOENT") throw err;
+    }
+    for (const name of localeEntries) {
+      const abs = path6.join(localeDir, name);
+      if (!(await stat3(abs)).isFile()) continue;
+      entries.push({ abs, rel: `${manifest.l10n}/${name}` });
     }
   }
+  entries.sort((a, b) => a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0);
+  const z2 = new yazl.ZipFile();
+  for (const { abs, rel } of entries) {
+    z2.addFile(abs, rel, { mtime: DOS_EPOCH, mode: ENTRY_MODE });
+  }
   z2.end();
   await new Promise((res, rej) => {
     z2.on("error", rej);
     const ws = createWriteStream(moextOut);
     z2.outputStream.pipe(ws).on("close", () => res()).on("error", rej);
   });
-  const total = (await stat3(moextOut)).size;
-  if (total > TOTAL_MAX) {
+  const archive = await readFile4(moextOut);
+  if (archive.byteLength > TOTAL_MAX) {
     await unlink(moextOut);
-    throw new Error(`moext ${total} bytes > ${TOTAL_MAX} byte cap`);
+    throw new Error(`moext ${archive.byteLength} bytes > ${TOTAL_MAX} byte cap`);
   }
-  return { outFile: moextOut, bundleSize: bundle.byteLength, totalSize: total };
+  return {
+    outFile: moextOut,
+    bundleSize: bundle.byteLength,
+    totalSize: archive.byteLength,
+    sha256: createHash("sha256").update(archive).digest("hex")
+  };
 }
 
 // src/commands/validate.ts
@@ -15119,7 +15180,7 @@ async function validate(projectDir) {
       path7.join(projectDir, "motrix-plugin.json"),
       "utf8"
     );
-    const m = ManifestSchema.parse(JSON.parse(raw));
+    const m = validateManifest(JSON.parse(raw));
     if (isReservedPublisher(m.id)) {
       throw new Error(`publisher name is reserved: "${m.id}"`);
     }
@@ -15192,7 +15253,7 @@ async function validateHostPermissions(projectDir) {
 }
 
 // src/bin/motrix-plugin.ts
-var program = new Command().name("motrix-plugin").description("Motrix plugin developer tools").version("2.0.0");
+var program = new Command().name("motrix-plugin").description("Motrix plugin developer tools").version("2.1.0");
 program.command("init <name>").addOption(
   new Option("-t, --template <id>", "template").choices(["basic-resolver", "post-action"]).default("basic-resolver")
 ).option("-p, --publisher <pub>", "publisher name", "me").action(
@@ -15207,8 +15268,14 @@ program.command("init <name>").addOption(
   }
 );
 program.command("pack").action(async () => {
-  const r = await pack({ projectDir: process.cwd() });
-  console.log(`Packed \u2192 ${r.outFile} (${r.totalSize} bytes)`);
+  try {
+    const r = await pack({ projectDir: process.cwd() });
+    console.log(`Packed \u2192 ${r.outFile} (${r.totalSize} bytes)`);
+    console.log(`sha256   ${r.sha256}`);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
 });
 program.command("validate").action(async () => {
   const r = await validate(process.cwd());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motrix/plugin-cli",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "bin": {
     "motrix-plugin": "dist/bin/motrix-plugin.js",
@@ -18,6 +18,11 @@
     "directory": "packages/plugin-cli"
   },
   "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
   "dependencies": {
     "chokidar": "^4",
     "commander": "^12",
@@ -25,16 +30,11 @@
     "yazl": "^2"
   },
   "devDependencies": {
+    "@motrix/plugin-manifest-schema": "workspace:*",
     "@types/node": "^24",
     "tsup": "^8",
     "typescript": "^5.6",
     "vitest": "^3",
-    "zod": "^4",
-    "@motrix/plugin-manifest-schema": "2.0.0"
-  },
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "zod": "^4"
   }
-}
+}