@clipbus/plugin-sdk 0.7.0 → 0.8.2

package/README.md

@@ -460,6 +460,53 @@ import type {
 
 For the exhaustive type list, run `cd protocol/plugin && npm run codegen` and read the synced `data.generated.ts` next to this file.
 
+## Manifest validation (`@clipbus/plugin-sdk/validate`)
+
+The `./validate` entry point provides a manifest validator that stays aligned with the
+host's manifest validation rules. Use it in CI or `npm run verify` to catch errors at
+development time — the same errors the host reports at install time.
+
+```js
+const { validateManifest, MANIFEST_VALIDATION_CODES } = require('@clipbus/plugin-sdk/validate');
+
+const manifest = JSON.parse(require('fs').readFileSync('manifest.json', 'utf8'));
+const issues = validateManifest(manifest, { phase: 'manifestOnly' });
+// issues: Array<{ code: string; message: string }>
+```
+
+### `validateManifest(manifest, options?)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `manifest` | `unknown` | Parsed `manifest.json` content (`JSON.parse` output). |
+| `options.phase` | `'manifestOnly' \| 'runtimeLoadable'` | `'manifestOnly'` (default): pure JSON rules only. `'runtimeLoadable'`: also checks file existence and path containment; requires `rootDir`. |
+| `options.rootDir` | `string` | Absolute path to the plugin root. Required for `'runtimeLoadable'`. |
+
+Returns `ManifestValidationIssue[]`. An empty array means the manifest is valid.
+
+Unlike the host validator (which stops at the first error), this function collects
+**all** issues in a single pass — better DX for development.
+
+### `MANIFEST_VALIDATION_CODES`
+
+`readonly string[]` — all 26 error code strings, each a verbatim camelCase name that
+matches the corresponding host error. Use for exhaustive handling or parity checks.
+
+### CLI: `clipbus-validate-manifest`
+
+Installed automatically when `@clipbus/plugin-sdk` is a dependency:
+
+```sh
+npx clipbus-validate-manifest [pluginDir] [--runtime]
+```
+
+- `pluginDir` — path to the plugin directory containing `manifest.json` (default: cwd).
+- `--runtime` — use `runtimeLoadable` phase (checks file existence in addition to JSON rules).
+
+Exits 0 on success, 1 if any issues are found.
+
+---
+
 ## See also
 
 - [API.md](./API.md) — autoritative API reference, regenerated from `protocol/plugin/src/catalog.ts`

package/bin/validate-manifest.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * clipbus-validate-manifest — CLI wrapper for validateManifest.
+ *
+ * Usage: clipbus-validate-manifest [pluginDir] [--runtime]
+ *
+ *   pluginDir   Path to the plugin root directory containing manifest.json.
+ *               Defaults to the current working directory.
+ *   --runtime   Use 'runtimeLoadable' phase (checks file existence + path
+ *               containment in addition to JSON rules). Default is 'manifestOnly'.
+ *
+ * Exit code 0 = valid, 1 = issues found or error.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { validateManifest } from '../dist/validate/index.js';
+
+const args = process.argv.slice(2);
+const flags = args.filter((a) => a.startsWith('--'));
+const positional = args.filter((a) => !a.startsWith('--'));
+
+const pluginDir = positional[0] ? path.resolve(positional[0]) : process.cwd();
+const phase = flags.includes('--runtime') ? 'runtimeLoadable' : 'manifestOnly';
+
+const manifestPath = path.join(pluginDir, 'manifest.json');
+let manifest;
+try {
+  const raw = readFileSync(manifestPath, 'utf8');
+  manifest = JSON.parse(raw);
+} catch (err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`clipbus-validate-manifest: cannot read ${manifestPath}: ${msg}\n`);
+  process.exit(1);
+}
+
+const issues = validateManifest(manifest, { phase, rootDir: pluginDir });
+
+if (issues.length === 0) {
+  process.stdout.write(`manifest OK (${phase})\n`);
+  process.exit(0);
+} else {
+  for (const iss of issues) {
+    process.stdout.write(`${iss.code}: ${iss.message}\n`);
+  }
+  process.exit(1);
+}

package/dist/validate/index.cjs

@@ -0,0 +1,324 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/validate/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MANIFEST_VALIDATION_CODES: () => MANIFEST_VALIDATION_CODES,
+  validateManifest: () => validateManifest
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_fs = require("node:fs");
+var import_node_path = __toESM(require("node:path"), 1);
+var MANIFEST_VALIDATION_CODES = [
+  "unsupportedSchemaVersion",
+  "missingManifest",
+  "missingRuntimeEntry",
+  "missingUIRoot",
+  "legacyFieldNotSupported",
+  "duplicateAttachmentRendererID",
+  "duplicateDetectorID",
+  "duplicateActionID",
+  "emptyPluginID",
+  "emptyPluginTitle",
+  "installEntryMissing",
+  "installEntryOutsideRoot",
+  "rendererTitleEmpty",
+  "detectorTitleEmpty",
+  "actionTitleEmpty",
+  "detectorMissingSupportedInputKinds",
+  "detectorAttachmentTypesEmpty",
+  "detectorAttachmentTypeNotRenderable",
+  "detectorAttachmentTypeOutsideNamespace",
+  "rendererUIEntryMissing",
+  "rendererUIEntryOutsideRoot",
+  "actionMissingSupportedItemTypes",
+  "actionUIEntryMissing",
+  "actionUIEntryOutsideRoot",
+  "detectorInvalidSupportedInputKind",
+  "actionInvalidSupportedItemType"
+];
+var CANONICAL_ITEM_TYPES = ["text", "image", "path_reference"];
+function asRecord(val) {
+  if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+    return val;
+  }
+  return void 0;
+}
+function asString(val) {
+  return typeof val === "string" ? val : void 0;
+}
+function asStringArray(val) {
+  if (!Array.isArray(val)) return [];
+  return val.filter((v) => typeof v === "string");
+}
+function asRecordArray(val) {
+  if (!Array.isArray(val)) return [];
+  return val.filter((v) => asRecord(v) !== void 0);
+}
+function issue(code, message) {
+  return { code, message };
+}
+function isInsideRoot(entryRelative, rootAbsolute) {
+  const resolvedEntry = import_node_path.default.resolve(rootAbsolute, entryRelative);
+  return resolvedEntry === rootAbsolute || resolvedEntry.startsWith(rootAbsolute + import_node_path.default.sep);
+}
+function validateSchemaVersion(raw, issues) {
+  const version = typeof raw["schemaVersion"] === "number" ? raw["schemaVersion"] : 0;
+  if (version !== 2) {
+    issues.push(issue("unsupportedSchemaVersion", `Unsupported plugin schema version: ${version}`));
+  }
+}
+var LEGACY_RENDERER_FIELDS = ["displayName", "defaultEnabled", "defaultOrderKey", "actions"];
+var LEGACY_DETECTOR_FIELDS = ["displayName", "capabilityID", "defaultEnabled", "timeoutMs"];
+var LEGACY_ACTION_FIELDS = ["displayName", "actionID", "defaultEnabled", "defaultOrderKey", "revealButtons"];
+function validateLegacyFields(raw, issues) {
+  const plugin = asRecord(raw["plugin"]);
+  if (plugin && "displayName" in plugin) {
+    issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: plugin.displayName`));
+  }
+  const renderers = asRecordArray(raw["attachmentRenderers"]);
+  for (let i = 0; i < renderers.length; i++) {
+    for (const field of LEGACY_RENDERER_FIELDS) {
+      if (field in renderers[i]) {
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: attachmentRenderers[${i}].${field}`));
+      }
+    }
+  }
+  const detectors = asRecordArray(raw["detectors"]);
+  for (let i = 0; i < detectors.length; i++) {
+    for (const field of LEGACY_DETECTOR_FIELDS) {
+      if (field in detectors[i]) {
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: detectors[${i}].${field}`));
+      }
+    }
+  }
+  const actions = asRecordArray(raw["actions"]);
+  for (let i = 0; i < actions.length; i++) {
+    for (const field of LEGACY_ACTION_FIELDS) {
+      if (field in actions[i]) {
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: actions[${i}].${field}`));
+      }
+    }
+  }
+}
+function validateCanonicalItemTypeSpellings(raw, issues) {
+  for (const detector of asRecordArray(raw["detectors"])) {
+    const detectorID = asString(detector["id"]) ?? "";
+    for (const value of asStringArray(detector["supportedInputKinds"])) {
+      if (!CANONICAL_ITEM_TYPES.includes(value)) {
+        issues.push(issue("detectorInvalidSupportedInputKind", `Detector supported input kinds contain unsupported value: ${detectorID} -> ${value}`));
+      }
+    }
+  }
+  for (const action of asRecordArray(raw["actions"])) {
+    const actionID = asString(action["id"]) ?? "";
+    for (const value of asStringArray(action["supportedItemTypes"])) {
+      if (!CANONICAL_ITEM_TYPES.includes(value)) {
+        issues.push(issue("actionInvalidSupportedItemType", `Action supported item types contain unsupported value: ${actionID} -> ${value}`));
+      }
+    }
+  }
+}
+function validateDetectors(detectors, pluginID, renderableAttachmentTypes, issues) {
+  const seenIDs = /* @__PURE__ */ new Set();
+  const prefix = pluginID + ".";
+  for (const detector of detectors) {
+    const id = asString(detector["id"]) ?? "";
+    if (seenIDs.has(id)) {
+      issues.push(issue("duplicateDetectorID", `Duplicate detector id: ${id}`));
+    } else {
+      seenIDs.add(id);
+    }
+    const title = asString(detector["title"]) ?? "";
+    if (title.trim().length === 0) {
+      issues.push(issue("detectorTitleEmpty", `Detector title is empty: ${id}`));
+    }
+    const supportedInputKinds = asStringArray(detector["supportedInputKinds"]);
+    if (supportedInputKinds.length === 0) {
+      issues.push(issue("detectorMissingSupportedInputKinds", `Detector is missing supported input kinds: ${id}`));
+    }
+    const attachmentTypes = asStringArray(detector["attachmentTypes"]);
+    if (attachmentTypes.length === 0) {
+      issues.push(issue("detectorAttachmentTypesEmpty", `Detector attachment types are empty: ${id}`));
+    }
+    for (const attachmentType of attachmentTypes) {
+      if (!attachmentType.startsWith(prefix)) {
+        issues.push(issue("detectorAttachmentTypeOutsideNamespace", `Detector attachment type is outside plugin namespace: ${id} -> ${attachmentType}`));
+      } else if (!renderableAttachmentTypes.has(attachmentType)) {
+        issues.push(issue("detectorAttachmentTypeNotRenderable", `Detector attachment type is not renderable: ${id} -> ${attachmentType}`));
+      }
+    }
+  }
+}
+function validateActions(actions, issues) {
+  const seenIDs = /* @__PURE__ */ new Set();
+  for (const action of actions) {
+    const id = asString(action["id"]) ?? "";
+    if (seenIDs.has(id)) {
+      issues.push(issue("duplicateActionID", `Duplicate action id: ${id}`));
+    } else {
+      seenIDs.add(id);
+    }
+    const title = asString(action["title"]) ?? "";
+    if (title.trim().length === 0) {
+      issues.push(issue("actionTitleEmpty", `Action title is empty: ${id}`));
+    }
+    const supportedItemTypes = asStringArray(action["supportedItemTypes"]);
+    if (supportedItemTypes.length === 0) {
+      issues.push(issue("actionMissingSupportedItemTypes", `Action is missing supported item types: ${id}`));
+    }
+  }
+}
+function validateRootEntry(rawEntry, rootDir, issues, missingCode, missingMessage, outsideCode, outsideMessage) {
+  const trimmed = rawEntry.trim();
+  if (trimmed.length === 0) {
+    issues.push(issue(missingCode, missingMessage(rawEntry)));
+    return;
+  }
+  if (!isInsideRoot(trimmed, rootDir)) {
+    issues.push(issue(outsideCode, outsideMessage(trimmed)));
+    return;
+  }
+  if (!(0, import_node_fs.existsSync)(import_node_path.default.resolve(rootDir, trimmed))) {
+    issues.push(issue(missingCode, missingMessage(trimmed)));
+  }
+}
+function validateUIEntry(uiEntry, uiRootDir, issues, missingCode, missingMessage, outsideCode, outsideMessage) {
+  if (!uiEntry || uiEntry.trim().length === 0) {
+    return;
+  }
+  const trimmed = uiEntry.trim();
+  if (!isInsideRoot(trimmed, uiRootDir)) {
+    issues.push(issue(outsideCode, outsideMessage(trimmed)));
+    return;
+  }
+  if (!(0, import_node_fs.existsSync)(import_node_path.default.resolve(uiRootDir, trimmed))) {
+    issues.push(issue(missingCode, missingMessage(trimmed)));
+  }
+}
+function validateManifest(manifest, options = {}) {
+  const issues = [];
+  const phase = options.phase ?? "manifestOnly";
+  const rootDir = import_node_path.default.resolve(options.rootDir ?? process.cwd());
+  const raw = asRecord(manifest);
+  if (!raw) {
+    issues.push(issue("missingManifest", "Missing manifest.json"));
+    return issues;
+  }
+  validateSchemaVersion(raw, issues);
+  validateLegacyFields(raw, issues);
+  validateCanonicalItemTypeSpellings(raw, issues);
+  const plugin = asRecord(raw["plugin"]) ?? {};
+  const pluginID = asString(plugin["id"]) ?? "";
+  const pluginTitle = asString(plugin["title"]) ?? "";
+  if (pluginID.trim().length === 0) {
+    issues.push(issue("emptyPluginID", "Plugin id is empty"));
+  }
+  if (pluginTitle.trim().length === 0) {
+    issues.push(issue("emptyPluginTitle", "Plugin title is empty"));
+  }
+  const renderers = asRecordArray(raw["attachmentRenderers"]);
+  const renderableAttachmentTypes = /* @__PURE__ */ new Set();
+  const seenRendererIDs = /* @__PURE__ */ new Set();
+  for (const renderer of renderers) {
+    const id = asString(renderer["id"]) ?? "";
+    const attachmentType = asString(renderer["attachmentType"]) ?? "";
+    if (attachmentType) renderableAttachmentTypes.add(attachmentType);
+    if (seenRendererIDs.has(id)) {
+      issues.push(issue("duplicateAttachmentRendererID", `Duplicate attachment renderer id: ${id}`));
+    } else {
+      seenRendererIDs.add(id);
+    }
+    const title = asString(renderer["title"]) ?? "";
+    if (title.trim().length === 0) {
+      issues.push(issue("rendererTitleEmpty", `Attachment renderer title is empty: ${id}`));
+    }
+  }
+  validateDetectors(asRecordArray(raw["detectors"]), pluginID, renderableAttachmentTypes, issues);
+  validateActions(asRecordArray(raw["actions"]), issues);
+  if (phase !== "runtimeLoadable") {
+    return issues;
+  }
+  const install = asRecord(raw["install"]);
+  if (install) {
+    const rawEntry = install["entry"] !== void 0 ? asString(install["entry"]) ?? "" : "";
+    validateRootEntry(
+      rawEntry.trim(),
+      rootDir,
+      issues,
+      "installEntryMissing",
+      (p) => `Missing install hook entry: ${p}`,
+      "installEntryOutsideRoot",
+      (p) => `Install hook entry is outside plugin root: ${p}`
+    );
+  }
+  const runtime = asRecord(raw["runtime"]) ?? {};
+  const nodeEntry = asString(runtime["nodeEntry"]) ?? "";
+  const uiRoot = asString(runtime["uiRoot"]) ?? "";
+  if (!(0, import_node_fs.existsSync)(import_node_path.default.resolve(rootDir, nodeEntry))) {
+    issues.push(issue("missingRuntimeEntry", `Missing runtime entry: ${nodeEntry}`));
+  }
+  const uiRootAbs = import_node_path.default.resolve(rootDir, uiRoot);
+  const declaresUISurface = renderers.length > 0 || asRecordArray(raw["actions"]).some((a) => {
+    const entry = asString(a["uiEntry"])?.trim();
+    return entry !== void 0 && entry.length > 0;
+  });
+  if (declaresUISurface && !(0, import_node_fs.existsSync)(uiRootAbs)) {
+    issues.push(issue("missingUIRoot", `Missing UI root: ${uiRoot}`));
+  }
+  for (const renderer of renderers) {
+    validateUIEntry(
+      asString(renderer["uiEntry"]),
+      uiRootAbs,
+      issues,
+      "rendererUIEntryMissing",
+      (p) => `Missing renderer UI entry: ${p}`,
+      "rendererUIEntryOutsideRoot",
+      (p) => `Renderer UI entry is outside uiRoot: ${p}`
+    );
+  }
+  for (const action of asRecordArray(raw["actions"])) {
+    validateUIEntry(
+      asString(action["uiEntry"]),
+      uiRootAbs,
+      issues,
+      "actionUIEntryMissing",
+      (p) => `Missing action UI entry: ${p}`,
+      "actionUIEntryOutsideRoot",
+      (p) => `Action UI entry is outside uiRoot: ${p}`
+    );
+  }
+  return issues;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MANIFEST_VALIDATION_CODES,
+  validateManifest
+});

package/dist/validate/index.d.cts

@@ -0,0 +1,49 @@
+/**
+ * @clipbus/plugin-sdk — manifest validation
+ *
+ * JavaScript mirror of the native PluginManifestValidator (Swift).
+ * Authority: platform/macos/Sources/Services/Impl/Plugins/PluginManifestValidator.swift
+ *
+ * Parity: scripts/checks/check-plugin-manifest-validator-parity.sh enforces that
+ *   MANIFEST_VALIDATION_CODES equals the Swift ValidationError case set, and that
+ *   CANONICAL_ITEM_TYPES equals ClipboardItemType.swift enum case raw values.
+ *
+ * Design difference from native: native throws on the first error (fail-fast); this
+ * function collects ALL issues and returns them — better DX for development so that
+ * authors see the full picture in one pass.
+ */
+/** A single manifest validation issue, analogous to Swift ValidationError. */
+export interface ManifestValidationIssue {
+    /** Error code — verbatim Swift ValidationError case name (camelCase). */
+    code: string;
+    /** Human-readable message — verbatim mirror of Swift errorDescription. */
+    message: string;
+}
+/** Options for validateManifest. */
+export interface ValidateManifestOptions {
+    /**
+     * 'manifestOnly' (default): pure JSON rules, no filesystem access required.
+     * 'runtimeLoadable': additionally checks file existence and path containment;
+     *   rootDir must be provided.
+     */
+    phase?: 'manifestOnly' | 'runtimeLoadable';
+    /** Absolute path to the plugin root directory. Required for 'runtimeLoadable'. */
+    rootDir?: string;
+}
+/**
+ * All 26 validation error codes, verbatim camelCase mirror of Swift ValidationError cases.
+ * Parity with native is enforced by scripts/checks/check-plugin-manifest-validator-parity.sh.
+ */
+export declare const MANIFEST_VALIDATION_CODES: readonly ["unsupportedSchemaVersion", "missingManifest", "missingRuntimeEntry", "missingUIRoot", "legacyFieldNotSupported", "duplicateAttachmentRendererID", "duplicateDetectorID", "duplicateActionID", "emptyPluginID", "emptyPluginTitle", "installEntryMissing", "installEntryOutsideRoot", "rendererTitleEmpty", "detectorTitleEmpty", "actionTitleEmpty", "detectorMissingSupportedInputKinds", "detectorAttachmentTypesEmpty", "detectorAttachmentTypeNotRenderable", "detectorAttachmentTypeOutsideNamespace", "rendererUIEntryMissing", "rendererUIEntryOutsideRoot", "actionMissingSupportedItemTypes", "actionUIEntryMissing", "actionUIEntryOutsideRoot", "detectorInvalidSupportedInputKind", "actionInvalidSupportedItemType"];
+/**
+ * Validate a parsed manifest JSON object against the Clipbus plugin manifest rules.
+ *
+ * Mirrors the validation rules in PluginManifestValidator.swift. Unlike native
+ * (which throws on the first error), this function collects ALL issues and
+ * returns them as an array — authors see the full picture in one pass.
+ *
+ * @param manifest - Parsed manifest.json content (result of JSON.parse).
+ * @param options  - Validation options.
+ * @returns        Array of issues; empty array means the manifest is valid.
+ */
+export declare function validateManifest(manifest: unknown, options?: ValidateManifestOptions): ManifestValidationIssue[];

package/dist/validate/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @clipbus/plugin-sdk — manifest validation
+ *
+ * JavaScript mirror of the native PluginManifestValidator (Swift).
+ * Authority: platform/macos/Sources/Services/Impl/Plugins/PluginManifestValidator.swift
+ *
+ * Parity: scripts/checks/check-plugin-manifest-validator-parity.sh enforces that
+ *   MANIFEST_VALIDATION_CODES equals the Swift ValidationError case set, and that
+ *   CANONICAL_ITEM_TYPES equals ClipboardItemType.swift enum case raw values.
+ *
+ * Design difference from native: native throws on the first error (fail-fast); this
+ * function collects ALL issues and returns them — better DX for development so that
+ * authors see the full picture in one pass.
+ */
+/** A single manifest validation issue, analogous to Swift ValidationError. */
+export interface ManifestValidationIssue {
+    /** Error code — verbatim Swift ValidationError case name (camelCase). */
+    code: string;
+    /** Human-readable message — verbatim mirror of Swift errorDescription. */
+    message: string;
+}
+/** Options for validateManifest. */
+export interface ValidateManifestOptions {
+    /**
+     * 'manifestOnly' (default): pure JSON rules, no filesystem access required.
+     * 'runtimeLoadable': additionally checks file existence and path containment;
+     *   rootDir must be provided.
+     */
+    phase?: 'manifestOnly' | 'runtimeLoadable';
+    /** Absolute path to the plugin root directory. Required for 'runtimeLoadable'. */
+    rootDir?: string;
+}
+/**
+ * All 26 validation error codes, verbatim camelCase mirror of Swift ValidationError cases.
+ * Parity with native is enforced by scripts/checks/check-plugin-manifest-validator-parity.sh.
+ */
+export declare const MANIFEST_VALIDATION_CODES: readonly ["unsupportedSchemaVersion", "missingManifest", "missingRuntimeEntry", "missingUIRoot", "legacyFieldNotSupported", "duplicateAttachmentRendererID", "duplicateDetectorID", "duplicateActionID", "emptyPluginID", "emptyPluginTitle", "installEntryMissing", "installEntryOutsideRoot", "rendererTitleEmpty", "detectorTitleEmpty", "actionTitleEmpty", "detectorMissingSupportedInputKinds", "detectorAttachmentTypesEmpty", "detectorAttachmentTypeNotRenderable", "detectorAttachmentTypeOutsideNamespace", "rendererUIEntryMissing", "rendererUIEntryOutsideRoot", "actionMissingSupportedItemTypes", "actionUIEntryMissing", "actionUIEntryOutsideRoot", "detectorInvalidSupportedInputKind", "actionInvalidSupportedItemType"];
+/**
+ * Validate a parsed manifest JSON object against the Clipbus plugin manifest rules.
+ *
+ * Mirrors the validation rules in PluginManifestValidator.swift. Unlike native
+ * (which throws on the first error), this function collects ALL issues and
+ * returns them as an array — authors see the full picture in one pass.
+ *
+ * @param manifest - Parsed manifest.json content (result of JSON.parse).
+ * @param options  - Validation options.
+ * @returns        Array of issues; empty array means the manifest is valid.
+ */
+export declare function validateManifest(manifest: unknown, options?: ValidateManifestOptions): ManifestValidationIssue[];

package/dist/validate/index.js

@@ -0,0 +1,288 @@
+// src/validate/index.ts
+import { existsSync } from "node:fs";
+import path from "node:path";
+var MANIFEST_VALIDATION_CODES = [
+  "unsupportedSchemaVersion",
+  "missingManifest",
+  "missingRuntimeEntry",
+  "missingUIRoot",
+  "legacyFieldNotSupported",
+  "duplicateAttachmentRendererID",
+  "duplicateDetectorID",
+  "duplicateActionID",
+  "emptyPluginID",
+  "emptyPluginTitle",
+  "installEntryMissing",
+  "installEntryOutsideRoot",
+  "rendererTitleEmpty",
+  "detectorTitleEmpty",
+  "actionTitleEmpty",
+  "detectorMissingSupportedInputKinds",
+  "detectorAttachmentTypesEmpty",
+  "detectorAttachmentTypeNotRenderable",
+  "detectorAttachmentTypeOutsideNamespace",
+  "rendererUIEntryMissing",
+  "rendererUIEntryOutsideRoot",
+  "actionMissingSupportedItemTypes",
+  "actionUIEntryMissing",
+  "actionUIEntryOutsideRoot",
+  "detectorInvalidSupportedInputKind",
+  "actionInvalidSupportedItemType"
+];
+var CANONICAL_ITEM_TYPES = ["text", "image", "path_reference"];
+function asRecord(val) {
+  if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+    return val;
+  }
+  return void 0;
+}
+function asString(val) {
+  return typeof val === "string" ? val : void 0;
+}
+function asStringArray(val) {
+  if (!Array.isArray(val)) return [];
+  return val.filter((v) => typeof v === "string");
+}
+function asRecordArray(val) {
+  if (!Array.isArray(val)) return [];
+  return val.filter((v) => asRecord(v) !== void 0);
+}
+function issue(code, message) {
+  return { code, message };
+}
+function isInsideRoot(entryRelative, rootAbsolute) {
+  const resolvedEntry = path.resolve(rootAbsolute, entryRelative);
+  return resolvedEntry === rootAbsolute || resolvedEntry.startsWith(rootAbsolute + path.sep);
+}
+function validateSchemaVersion(raw, issues) {
+  const version = typeof raw["schemaVersion"] === "number" ? raw["schemaVersion"] : 0;
+  if (version !== 2) {
+    issues.push(issue("unsupportedSchemaVersion", `Unsupported plugin schema version: ${version}`));
+  }
+}
+var LEGACY_RENDERER_FIELDS = ["displayName", "defaultEnabled", "defaultOrderKey", "actions"];
+var LEGACY_DETECTOR_FIELDS = ["displayName", "capabilityID", "defaultEnabled", "timeoutMs"];
+var LEGACY_ACTION_FIELDS = ["displayName", "actionID", "defaultEnabled", "defaultOrderKey", "revealButtons"];
+function validateLegacyFields(raw, issues) {
+  const plugin = asRecord(raw["plugin"]);
+  if (plugin && "displayName" in plugin) {
+    issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: plugin.displayName`));
+  }
+  const renderers = asRecordArray(raw["attachmentRenderers"]);
+  for (let i = 0; i < renderers.length; i++) {
+    for (const field of LEGACY_RENDERER_FIELDS) {
+      if (field in renderers[i]) {
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: attachmentRenderers[${i}].${field}`));
+      }
+    }
+  }
+  const detectors = asRecordArray(raw["detectors"]);
+  for (let i = 0; i < detectors.length; i++) {
+    for (const field of LEGACY_DETECTOR_FIELDS) {
+      if (field in detectors[i]) {
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: detectors[${i}].${field}`));
+      }
+    }
+  }
+  const actions = asRecordArray(raw["actions"]);
+  for (let i = 0; i < actions.length; i++) {
+    for (const field of LEGACY_ACTION_FIELDS) {
+      if (field in actions[i]) {
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: actions[${i}].${field}`));
+      }
+    }
+  }
+}
+function validateCanonicalItemTypeSpellings(raw, issues) {
+  for (const detector of asRecordArray(raw["detectors"])) {
+    const detectorID = asString(detector["id"]) ?? "";
+    for (const value of asStringArray(detector["supportedInputKinds"])) {
+      if (!CANONICAL_ITEM_TYPES.includes(value)) {
+        issues.push(issue("detectorInvalidSupportedInputKind", `Detector supported input kinds contain unsupported value: ${detectorID} -> ${value}`));
+      }
+    }
+  }
+  for (const action of asRecordArray(raw["actions"])) {
+    const actionID = asString(action["id"]) ?? "";
+    for (const value of asStringArray(action["supportedItemTypes"])) {
+      if (!CANONICAL_ITEM_TYPES.includes(value)) {
+        issues.push(issue("actionInvalidSupportedItemType", `Action supported item types contain unsupported value: ${actionID} -> ${value}`));
+      }
+    }
+  }
+}
+function validateDetectors(detectors, pluginID, renderableAttachmentTypes, issues) {
+  const seenIDs = /* @__PURE__ */ new Set();
+  const prefix = pluginID + ".";
+  for (const detector of detectors) {
+    const id = asString(detector["id"]) ?? "";
+    if (seenIDs.has(id)) {
+      issues.push(issue("duplicateDetectorID", `Duplicate detector id: ${id}`));
+    } else {
+      seenIDs.add(id);
+    }
+    const title = asString(detector["title"]) ?? "";
+    if (title.trim().length === 0) {
+      issues.push(issue("detectorTitleEmpty", `Detector title is empty: ${id}`));
+    }
+    const supportedInputKinds = asStringArray(detector["supportedInputKinds"]);
+    if (supportedInputKinds.length === 0) {
+      issues.push(issue("detectorMissingSupportedInputKinds", `Detector is missing supported input kinds: ${id}`));
+    }
+    const attachmentTypes = asStringArray(detector["attachmentTypes"]);
+    if (attachmentTypes.length === 0) {
+      issues.push(issue("detectorAttachmentTypesEmpty", `Detector attachment types are empty: ${id}`));
+    }
+    for (const attachmentType of attachmentTypes) {
+      if (!attachmentType.startsWith(prefix)) {
+        issues.push(issue("detectorAttachmentTypeOutsideNamespace", `Detector attachment type is outside plugin namespace: ${id} -> ${attachmentType}`));
+      } else if (!renderableAttachmentTypes.has(attachmentType)) {
+        issues.push(issue("detectorAttachmentTypeNotRenderable", `Detector attachment type is not renderable: ${id} -> ${attachmentType}`));
+      }
+    }
+  }
+}
+function validateActions(actions, issues) {
+  const seenIDs = /* @__PURE__ */ new Set();
+  for (const action of actions) {
+    const id = asString(action["id"]) ?? "";
+    if (seenIDs.has(id)) {
+      issues.push(issue("duplicateActionID", `Duplicate action id: ${id}`));
+    } else {
+      seenIDs.add(id);
+    }
+    const title = asString(action["title"]) ?? "";
+    if (title.trim().length === 0) {
+      issues.push(issue("actionTitleEmpty", `Action title is empty: ${id}`));
+    }
+    const supportedItemTypes = asStringArray(action["supportedItemTypes"]);
+    if (supportedItemTypes.length === 0) {
+      issues.push(issue("actionMissingSupportedItemTypes", `Action is missing supported item types: ${id}`));
+    }
+  }
+}
+function validateRootEntry(rawEntry, rootDir, issues, missingCode, missingMessage, outsideCode, outsideMessage) {
+  const trimmed = rawEntry.trim();
+  if (trimmed.length === 0) {
+    issues.push(issue(missingCode, missingMessage(rawEntry)));
+    return;
+  }
+  if (!isInsideRoot(trimmed, rootDir)) {
+    issues.push(issue(outsideCode, outsideMessage(trimmed)));
+    return;
+  }
+  if (!existsSync(path.resolve(rootDir, trimmed))) {
+    issues.push(issue(missingCode, missingMessage(trimmed)));
+  }
+}
+function validateUIEntry(uiEntry, uiRootDir, issues, missingCode, missingMessage, outsideCode, outsideMessage) {
+  if (!uiEntry || uiEntry.trim().length === 0) {
+    return;
+  }
+  const trimmed = uiEntry.trim();
+  if (!isInsideRoot(trimmed, uiRootDir)) {
+    issues.push(issue(outsideCode, outsideMessage(trimmed)));
+    return;
+  }
+  if (!existsSync(path.resolve(uiRootDir, trimmed))) {
+    issues.push(issue(missingCode, missingMessage(trimmed)));
+  }
+}
+function validateManifest(manifest, options = {}) {
+  const issues = [];
+  const phase = options.phase ?? "manifestOnly";
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const raw = asRecord(manifest);
+  if (!raw) {
+    issues.push(issue("missingManifest", "Missing manifest.json"));
+    return issues;
+  }
+  validateSchemaVersion(raw, issues);
+  validateLegacyFields(raw, issues);
+  validateCanonicalItemTypeSpellings(raw, issues);
+  const plugin = asRecord(raw["plugin"]) ?? {};
+  const pluginID = asString(plugin["id"]) ?? "";
+  const pluginTitle = asString(plugin["title"]) ?? "";
+  if (pluginID.trim().length === 0) {
+    issues.push(issue("emptyPluginID", "Plugin id is empty"));
+  }
+  if (pluginTitle.trim().length === 0) {
+    issues.push(issue("emptyPluginTitle", "Plugin title is empty"));
+  }
+  const renderers = asRecordArray(raw["attachmentRenderers"]);
+  const renderableAttachmentTypes = /* @__PURE__ */ new Set();
+  const seenRendererIDs = /* @__PURE__ */ new Set();
+  for (const renderer of renderers) {
+    const id = asString(renderer["id"]) ?? "";
+    const attachmentType = asString(renderer["attachmentType"]) ?? "";
+    if (attachmentType) renderableAttachmentTypes.add(attachmentType);
+    if (seenRendererIDs.has(id)) {
+      issues.push(issue("duplicateAttachmentRendererID", `Duplicate attachment renderer id: ${id}`));
+    } else {
+      seenRendererIDs.add(id);
+    }
+    const title = asString(renderer["title"]) ?? "";
+    if (title.trim().length === 0) {
+      issues.push(issue("rendererTitleEmpty", `Attachment renderer title is empty: ${id}`));
+    }
+  }
+  validateDetectors(asRecordArray(raw["detectors"]), pluginID, renderableAttachmentTypes, issues);
+  validateActions(asRecordArray(raw["actions"]), issues);
+  if (phase !== "runtimeLoadable") {
+    return issues;
+  }
+  const install = asRecord(raw["install"]);
+  if (install) {
+    const rawEntry = install["entry"] !== void 0 ? asString(install["entry"]) ?? "" : "";
+    validateRootEntry(
+      rawEntry.trim(),
+      rootDir,
+      issues,
+      "installEntryMissing",
+      (p) => `Missing install hook entry: ${p}`,
+      "installEntryOutsideRoot",
+      (p) => `Install hook entry is outside plugin root: ${p}`
+    );
+  }
+  const runtime = asRecord(raw["runtime"]) ?? {};
+  const nodeEntry = asString(runtime["nodeEntry"]) ?? "";
+  const uiRoot = asString(runtime["uiRoot"]) ?? "";
+  if (!existsSync(path.resolve(rootDir, nodeEntry))) {
+    issues.push(issue("missingRuntimeEntry", `Missing runtime entry: ${nodeEntry}`));
+  }
+  const uiRootAbs = path.resolve(rootDir, uiRoot);
+  const declaresUISurface = renderers.length > 0 || asRecordArray(raw["actions"]).some((a) => {
+    const entry = asString(a["uiEntry"])?.trim();
+    return entry !== void 0 && entry.length > 0;
+  });
+  if (declaresUISurface && !existsSync(uiRootAbs)) {
+    issues.push(issue("missingUIRoot", `Missing UI root: ${uiRoot}`));
+  }
+  for (const renderer of renderers) {
+    validateUIEntry(
+      asString(renderer["uiEntry"]),
+      uiRootAbs,
+      issues,
+      "rendererUIEntryMissing",
+      (p) => `Missing renderer UI entry: ${p}`,
+      "rendererUIEntryOutsideRoot",
+      (p) => `Renderer UI entry is outside uiRoot: ${p}`
+    );
+  }
+  for (const action of asRecordArray(raw["actions"])) {
+    validateUIEntry(
+      asString(action["uiEntry"]),
+      uiRootAbs,
+      issues,
+      "actionUIEntryMissing",
+      (p) => `Missing action UI entry: ${p}`,
+      "actionUIEntryOutsideRoot",
+      (p) => `Action UI entry is outside uiRoot: ${p}`
+    );
+  }
+  return issues;
+}
+export {
+  MANIFEST_VALIDATION_CODES,
+  validateManifest
+};

package/docs/manifest.md

@@ -47,6 +47,8 @@
 | `runtime.nodeEntry` | `string` | 是 | Node runtime 入口（编译后 `.cjs`） |
 | `runtime.uiRoot` | `string` | 是 | UI 根目录；所有 `uiEntry` 相对此目录 |
 
+> **关于 `uiRoot` 目录存在性**：`uiRoot` 是必填*声明*，但其指向目录（如 `dist/ui`）只在插件声明 UI 面时才需在磁盘存在——即有任意 `attachmentRenderers`，或任意带 `uiEntry` 的 `action`。纯 auto-run-action 插件（无 renderer / detector / action uiEntry）构建后无需产出 `dist/ui`，`clipbus-validate-manifest --runtime` 与宿主加载期都不会因其缺失而失败。
+
 ---
 
 ## `permissions`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipbus/plugin-sdk",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "type": "module",
   "description": "Typed SDK for authoring Clipbus plugins — runtime (Node.js) and UI (WebView) helpers generated from the Clipbus plugin wire contract.",
   "keywords": [
@@ -48,8 +48,21 @@
         "types": "./dist/dom/index.d.cts",
         "default": "./dist/dom/index.cjs"
       }
+    },
+    "./validate": {
+      "import": {
+        "types": "./dist/validate/index.d.ts",
+        "default": "./dist/validate/index.js"
+      },
+      "require": {
+        "types": "./dist/validate/index.d.cts",
+        "default": "./dist/validate/index.cjs"
+      }
     }
   },
+  "bin": {
+    "clipbus-validate-manifest": "bin/validate-manifest.mjs"
+  },
   "scripts": {
     "prepare": "node ./scripts/build.mjs",
     "build": "node ./scripts/build.mjs",
@@ -59,6 +72,7 @@
   },
   "files": [
     "dist",
+    "bin",
     "SPECIFICATION.md",
     "README.md",
     "API.md",