release-skill 0.2.1 → 0.2.3

package/src/platforms/registry.mjs

@@ -1,6 +1,6 @@
 /**
  * Platform registry — the single source of truth for consumer-platform
- * knowledge (claude / codex / kimi).
+ * knowledge (claude / codex / kimi / codebuddy).
  *
  * T2.2 converges platform facts that were scattered across plugin-marketplace.mjs,
  * build-adapters.mjs, prepare.mjs, plan.mjs and project.yaml into this module.
@@ -23,6 +23,8 @@
  * file; kimi's side-effecting manual-requirement and manifest-reading
  * strategies live in ./kimi.mjs (§4.2's per-platform-module option — the only
  * non-trivial strategies) and are referenced from the kimi descriptor below.
+ * codebuddy's analogous human-attestation strategies live in ./codebuddy.mjs
+ * and are referenced from the codebuddy descriptor below.
  * plugin-marketplace.mjs consumes every platform difference through this
  * registry; see the t2-2 deviation record for the step-2 wiring details.
  *
@@ -36,6 +38,10 @@ import {
   readKimiManifest,
   KIMI_MANIFEST_CANDIDATES,
 } from './kimi.mjs';
+import {
+  executeCodeBuddyManualRequirement,
+  readCodeBuddyManifest,
+} from './codebuddy.mjs';
 
 // --- claude strategy -------------------------------------------------------
 
@@ -131,6 +137,12 @@ const CLAUDE = Object.freeze({
   // actionType -> adapter map from it (T2.2 step 3).
   adapter: 'plugin-marketplace',
   automatable: true,
+  // --- capability contract (平台能力契约) ------------------------------------
+  installMethod: 'structured-cli',
+  refStrength: 'name-ref',
+  outputProtocol: 'text',
+  identityEvidence: 'list-record',
+  degradationPolicy: 'block',
   cli: Object.freeze({
     binary: 'claude',
     marketplaceAdd: (repo, ref) => ['plugin', 'marketplace', 'add', `${repo}@${ref}`],
@@ -155,6 +167,10 @@ const CLAUDE = Object.freeze({
   // Claude carries the authoritative version in the marketplace entry: the
   // preflight binds entry.version to the action version.
   marketplaceEntryCarriesVersion: true,
+  // External marketplace form: `claude plugin marketplace add repo@<ref>` can
+  // only pin a branch/tag NAME (a bare commit sha fails to clone and the
+  // resolved sha is not recorded locally) — name-form weak freeze.
+  marketplaceRefForm: 'name',
   knownHostArtifacts: Object.freeze(['.in_use']),
   schemaRequiredFields: Object.freeze(['plugin', 'marketplace', 'entrySkill']),
   skillRendering: Object.freeze({ mode: 'verbatim', preamble: null, placeholder: '${CLAUDE_PLUGIN_ROOT}' }),
@@ -180,6 +196,12 @@ const CODEX = Object.freeze({
   actionType: 'codex-marketplace-install',
   adapter: 'plugin-marketplace',
   automatable: true,
+  // --- capability contract (平台能力契约) ------------------------------------
+  installMethod: 'structured-cli',
+  refStrength: 'commit-sha',
+  outputProtocol: 'structured',
+  identityEvidence: 'install-output',
+  degradationPolicy: 'block',
   cli: Object.freeze({
     binary: 'codex',
     marketplaceAdd: (repo, ref) => ['plugin', 'marketplace', 'add', repo, '--ref', ref, '--json'],
@@ -204,6 +226,9 @@ const CODEX = Object.freeze({
   // Codex keeps the authoritative version in .codex-plugin/plugin.json; the
   // marketplace entry version is not bound to the action version.
   marketplaceEntryCarriesVersion: false,
+  // External marketplace form: `codex plugin marketplace add repo --ref <ref>`
+  // accepts a bare commit sha — sha-form strong freeze.
+  marketplaceRefForm: 'sha',
   knownHostArtifacts: Object.freeze(['.git', '.codex-plugin/migrated-command-skills']),
   schemaRequiredFields: Object.freeze(['plugin', 'marketplace', 'entrySkill']),
   skillRendering: Object.freeze({ mode: 'substitute', preamble: 'codex', placeholder: '${CLAUDE_PLUGIN_ROOT}' }),
@@ -229,6 +254,12 @@ const KIMI = Object.freeze({
   actionType: 'kimi-marketplace-install',
   adapter: 'plugin-marketplace',
   automatable: false,
+  // --- capability contract (平台能力契约) ------------------------------------
+  installMethod: 'interactive-only',
+  refStrength: 'unfixable',
+  outputProtocol: 'none',
+  identityEvidence: 'filesystem-payload',
+  degradationPolicy: 'human-attestation',
   cli: null,
   jsonProtocol: Object.freeze({
     listOutput: null,
@@ -251,6 +282,9 @@ const KIMI = Object.freeze({
   // apply (null = N/A, never consulted: kimi preflight reads its manifest via
   // strategy.readManifest).
   marketplaceEntryCarriesVersion: null,
+  // kimi has no marketplace add at all, so the marketplace ref form does not
+  // apply (null = N/A, never consulted).
+  marketplaceRefForm: null,
   knownHostArtifacts: Object.freeze(['.git']),
   schemaRequiredFields: Object.freeze(['plugin', 'entrySkill']),
   skillRendering: Object.freeze({ mode: 'substitute', preamble: 'kimi', placeholder: '${CLAUDE_PLUGIN_ROOT}' }),
@@ -272,15 +306,102 @@ const KIMI = Object.freeze({
   }),
 });
 
-/** Ordered platform registry. Order is significant (claude, codex, kimi). */
-export const PLATFORMS = Object.freeze([CLAUDE, CODEX, KIMI]);
+// CodeBuddy (desktop product WorkBuddy) is a NON-automatable human-attestation
+// platform like kimi: the codebuddy CLI's marketplace add/install cannot pin a
+// frozen ref (no ref option; the install tracks the default branch / latest),
+// so an automated install checkpoint cannot guarantee frozen-artifact identity.
+// Install state has a stable on-disk layout, so the closed loop is proven by a
+// human attestation + read-only verification (./codebuddy.mjs), fail-closed at
+// the same severity as kimi.
+//
+// NAMING MAPPING: the platform id is `codebuddy`, but its BUILD adapter keeps
+// the historical directory name `workbuddy` (`adapters/workbuddy/`, manifest
+// `.codebuddy-plugin/plugin.json`). `buildAdapter.name = 'workbuddy'` drives
+// the build-adapters producer + public-file collection; the pipeline identity
+// (distributionType/actionType/consumer) stays `codebuddy`.
+const CODEBUDDY = Object.freeze({
+  id: 'codebuddy',
+  distributionType: 'codebuddy-plugin',
+  actionType: 'codebuddy-marketplace-install',
+  adapter: 'plugin-marketplace',
+  automatable: false,
+  // --- capability contract (平台能力契约) ------------------------------------
+  installMethod: 'human-attestation',
+  refStrength: 'unfixable',
+  outputProtocol: 'none',
+  identityEvidence: 'human-attestation',
+  degradationPolicy: 'human-attestation',
+  cli: null,
+  jsonProtocol: Object.freeze({
+    listOutput: null,
+    installPathSource: null,
+    marketplaceAddOutput: null,
+    pluginInstallOutput: null,
+  }),
+  // The closed loop never execs the codebuddy CLI; HOME is the only isolation
+  // input and exists solely so the attestation's isolated cli-channel home has
+  // a base. No unverified host env vars are fabricated.
+  isolationEnv: (home) => ({ HOME: home }),
+  // codebuddy never execs a CLI; its isolated cli home is created by the
+  // manual-requirement strategy under the attestation authority.
+  isolationSubdirs: Object.freeze([]),
+  manifestPaths: Object.freeze({
+    // Single authoritative manifest (no precedence chain, unlike kimi).
+    plugin: '.codebuddy-plugin/plugin.json',
+    marketplace: null,
+  }),
+  marketplaceSourceForm: null,
+  // codebuddy installs from a unified marketplace but carries no marketplace
+  // identity in the action (the marketplace is a fixed constant in
+  // ./codebuddy.mjs); the entry-version binding does not apply (null = N/A).
+  marketplaceEntryCarriesVersion: null,
+  // codebuddy has no marketplace add that can pin a frozen ref (attestation
+  // loop instead), so the marketplace ref form does not apply (null = N/A).
+  marketplaceRefForm: null,
+  knownHostArtifacts: Object.freeze(['.git']),
+  schemaRequiredFields: Object.freeze(['plugin', 'entrySkill']),
+  // Declarative rendering intent (the build-adapters producer keys on
+  // buildAdapter.name = 'workbuddy'): pure ${CLAUDE_PLUGIN_ROOT} ->
+  // ${CODEBUDDY_PLUGIN_ROOT} substitution, no entry-resolution preamble
+  // (CodeBuddy expands the variable inline in skill content).
+  skillRendering: Object.freeze({ mode: 'substitute', preamble: null, placeholder: '${CODEBUDDY_PLUGIN_ROOT}' }),
+  buildAdapter: Object.freeze({
+    // Build adapter keeps the historical `workbuddy` directory name; the fields
+    // are byte-for-byte the legacy BUILD_ONLY workbuddy entry so the generated
+    // adapters/workbuddy/ tree is unchanged.
+    name: 'workbuddy',
+    pluginDirName: '.codebuddy-plugin',
+    templateFileName: 'plugin.json',
+    marketplaceFileName: null,
+    hasMarketplace: false,
+  }),
+  strategy: Object.freeze({
+    parseListOutput: null,
+    extractInstallPath: null,
+    extractListIdentity: null,
+    crossValidateListEntry: null,
+    // codebuddy's side-effecting manual-requirement builder and manifest reader
+    // live in ./codebuddy.mjs (per-platform-module option, mirroring kimi).
+    buildManualRequirement: executeCodeBuddyManualRequirement,
+    readManifest: readCodeBuddyManifest,
+  }),
+});
 
-const VALID_DISTRIBUTION_TYPES = new Set(['claude-plugin', 'codex-plugin', 'kimi-plugin']);
-const VALID_ACTION_TYPES = new Set(['claude-marketplace-install', 'codex-marketplace-install', 'kimi-marketplace-install']);
+/** Ordered platform registry. Order is significant (claude, codex, kimi, codebuddy). */
+export const PLATFORMS = Object.freeze([CLAUDE, CODEX, KIMI, CODEBUDDY]);
+
+const VALID_DISTRIBUTION_TYPES = new Set(['claude-plugin', 'codex-plugin', 'kimi-plugin', 'codebuddy-plugin']);
+const VALID_ACTION_TYPES = new Set(['claude-marketplace-install', 'codex-marketplace-install', 'kimi-marketplace-install', 'codebuddy-marketplace-install']);
 const VALID_SOURCE_FORMS = new Set(['string', 'local-path-object', null]);
+const VALID_MARKETPLACE_REF_FORMS = new Set(['sha', 'name', null]);
 const VALID_LIST_OUTPUTS = new Set(['array', 'installed-object', null]);
 const VALID_CLI_OUTPUTS = new Set(['json', null]);
 const VALID_ENTRY_VERSION_BINDING = new Set([true, false, null]);
+const VALID_INSTALL_METHODS = new Set(['structured-cli', 'interactive-only', 'human-attestation']);
+const VALID_REF_STRENGTHS = new Set(['commit-sha', 'name-ref', 'unfixable']);
+const VALID_OUTPUT_PROTOCOLS = new Set(['structured', 'text', 'none']);
+const VALID_IDENTITY_EVIDENCE = new Set(['list-record', 'install-output', 'filesystem-payload', 'human-attestation']);
+const VALID_DEGRADATION_POLICIES = new Set(['block', 'human-attestation']);
 
 /**
  * Look up a platform descriptor by id.
@@ -333,6 +454,9 @@ export function assertRegistry(registry = PLATFORMS) {
     if (!VALID_SOURCE_FORMS.has(platform.marketplaceSourceForm)) {
       throw new Error(`platform registry: ${label} has illegal marketplaceSourceForm "${platform.marketplaceSourceForm}"`);
     }
+    if (!VALID_MARKETPLACE_REF_FORMS.has(platform.marketplaceRefForm)) {
+      throw new Error(`platform registry: ${label} has illegal marketplaceRefForm "${platform.marketplaceRefForm}"`);
+    }
     if (!Array.isArray(platform.knownHostArtifacts)) {
       throw new Error(`platform registry: ${label} knownHostArtifacts must be an array`);
     }
@@ -358,6 +482,23 @@ export function assertRegistry(registry = PLATFORMS) {
       throw new Error(`platform registry: ${label} isolationSubdirs must be an array`);
     }
 
+    // --- capability contract validation (能力契约验证) -----------------------
+    if (!VALID_INSTALL_METHODS.has(platform.installMethod)) {
+      throw new Error(`platform registry: ${label} has illegal installMethod "${platform.installMethod}"`);
+    }
+    if (!VALID_REF_STRENGTHS.has(platform.refStrength)) {
+      throw new Error(`platform registry: ${label} has illegal refStrength "${platform.refStrength}"`);
+    }
+    if (!VALID_OUTPUT_PROTOCOLS.has(platform.outputProtocol)) {
+      throw new Error(`platform registry: ${label} has illegal outputProtocol "${platform.outputProtocol}"`);
+    }
+    if (!VALID_IDENTITY_EVIDENCE.has(platform.identityEvidence)) {
+      throw new Error(`platform registry: ${label} has illegal identityEvidence "${platform.identityEvidence}"`);
+    }
+    if (!VALID_DEGRADATION_POLICIES.has(platform.degradationPolicy)) {
+      throw new Error(`platform registry: ${label} has illegal degradationPolicy "${platform.degradationPolicy}"`);
+    }
+
     if (platform.automatable) {
       if (!platform.cli || typeof platform.cli.marketplaceAdd !== 'function'
           || typeof platform.cli.install !== 'function' || typeof platform.cli.list !== 'function') {
@@ -386,8 +527,120 @@ export function assertRegistry(registry = PLATFORMS) {
         throw new Error(`platform registry: non-automatable platform ${label} needs strategy.readManifest`);
       }
     }
+
+    // --- capability contract consistency rules (能力契约一致性规则) -----------
+    // automatable === true 必须有 installMethod === 'structured-cli'
+    if (platform.automatable === true && platform.installMethod !== 'structured-cli') {
+      throw new Error(`platform registry: ${label} is automatable but installMethod is "${platform.installMethod}" (expected "structured-cli")`);
+    }
+    // automatable === false 必须有 installMethod !== 'structured-cli'
+    if (platform.automatable === false && platform.installMethod === 'structured-cli') {
+      throw new Error(`platform registry: ${label} is not automatable but installMethod is "structured-cli"`);
+    }
+    // installMethod === 'structured-cli' 必须有 refStrength !== 'unfixable'
+    if (platform.installMethod === 'structured-cli' && platform.refStrength === 'unfixable') {
+      throw new Error(`platform registry: ${label} has structured-cli install but unfixable refStrength`);
+    }
+    // installMethod === 'human-attestation' 必须有 identityEvidence === 'human-attestation'
+    if (platform.installMethod === 'human-attestation' && platform.identityEvidence !== 'human-attestation') {
+      throw new Error(`platform registry: ${label} has human-attestation install but identityEvidence is "${platform.identityEvidence}"`);
+    }
   }
 }
 
 // Self-validate at import time: a malformed registry never reaches runtime.
 assertRegistry();
+
+// --- capability-driven routing & conflict detection (能力驱动路由与矛盾检测) --
+
+/**
+ * 根据平台描述符的 installMethod 决定执行路由。
+ *
+ * @param {object} platform - 平台描述符
+ * @returns {{ route: string, reason: string }}
+ * @throws {Error} 无法路由时抛出
+ */
+export function resolvePlatformRoute(platform) {
+  const { installMethod } = platform;
+  if (installMethod === 'structured-cli') {
+    return { route: 'structured-cli', reason: `installMethod is structured-cli` };
+  }
+  if (installMethod === 'interactive-only' || installMethod === 'human-attestation') {
+    return { route: 'human-attestation', reason: `installMethod is ${installMethod}` };
+  }
+  throw new Error(
+    `platform "${platform?.id ?? '<unknown>'}" with installMethod="${installMethod}" cannot be routed`,
+  );
+}
+
+/**
+ * 检测平台能力描述符中的矛盾。
+ *
+ * @param {object} platform - 平台描述符
+ * @returns {{ hasConflict: boolean, conflicts: string[] }}
+ * @throws {Error} 发现矛盾时抛出
+ */
+export function resolveCapabilityConflicts(platform) {
+  const conflicts = [];
+  const { id, automatable, installMethod, refStrength, identityEvidence, cli, strategy } = platform;
+
+  // automatable <-> installMethod 一致性
+  if (automatable === true && installMethod !== 'structured-cli') {
+    conflicts.push(`automatable=true but installMethod="${installMethod}"`);
+  }
+  if (automatable === false && installMethod === 'structured-cli') {
+    conflicts.push(`automatable=false but installMethod="structured-cli"`);
+  }
+
+  // installMethod <-> refStrength 一致性
+  if (installMethod === 'structured-cli' && refStrength === 'unfixable') {
+    conflicts.push(`structured-cli with unfixable refStrength`);
+  }
+
+  // installMethod <-> identityEvidence 一致性
+  if (installMethod === 'human-attestation' && identityEvidence !== 'human-attestation') {
+    conflicts.push(`human-attestation install but identityEvidence="${identityEvidence}"`);
+  }
+
+  // 自动化平台必须有 cli 和策略解析函数
+  if (automatable === true) {
+    if (!cli || typeof cli !== 'object') {
+      conflicts.push(`automatable=true but cli is missing`);
+    }
+    if (!strategy || typeof strategy.parseListOutput !== 'function') {
+      conflicts.push(`automatable=true but strategy.parseListOutput is missing`);
+    }
+    if (!strategy || typeof strategy.extractInstallPath !== 'function') {
+      conflicts.push(`automatable=true but strategy.extractInstallPath is missing`);
+    }
+  }
+
+  // 非自动化平台必须 cli === null，且有手动策略函数
+  if (automatable === false) {
+    if (cli !== null) {
+      conflicts.push(`automatable=false but cli is not null`);
+    }
+    if (!strategy || typeof strategy.buildManualRequirement !== 'function') {
+      conflicts.push(`automatable=false but strategy.buildManualRequirement is missing`);
+    }
+    if (!strategy || typeof strategy.readManifest !== 'function') {
+      conflicts.push(`automatable=false but strategy.readManifest is missing`);
+    }
+  }
+
+  if (conflicts.length > 0) {
+    throw new Error(`capability conflict in platform "${id}": ${conflicts.join('; ')}`);
+  }
+
+  return { hasConflict: false, conflicts: [] };
+}
+
+/**
+ * 从 installMethod 派生 automatable 标志。
+ *
+ * @param {object} platform - 平台描述符
+ * @returns {boolean}
+ */
+export function deriveAutomatable(platform) {
+  return platform.installMethod === 'structured-cli';
+}

package/src/producers/build-adapters.mjs

@@ -197,8 +197,15 @@ export function computeBuildAdaptersDigest(sourceBytes) {
 // of platform knowledge). The build shape mirrors the legacy inline table
 // byte-for-byte: marketplaceFileName is present only when the platform
 // co-locates a marketplace manifest in its plugin dir (claude).
+//
+// The build adapter NAME defaults to the platform id, but a platform may keep a
+// historical directory name distinct from its pipeline id via
+// `buildAdapter.name`: codebuddy (pipeline id) builds the `workbuddy` adapter
+// tree (adapters/workbuddy/, manifest .codebuddy-plugin/plugin.json). This is
+// what lets codebuddy join the publish pipeline WITHOUT changing a single byte
+// of the generated workbuddy adapter (the former BUILD_ONLY workbuddy entry).
 const REGISTRY_PLATFORMS = PLATFORM_REGISTRY.map((platform) => ({
-  name: platform.id,
+  name: platform.buildAdapter?.name ?? platform.id,
   pluginDirName: platform.buildAdapter.pluginDirName,
   templateFileName: platform.buildAdapter.templateFileName,
   ...(platform.buildAdapter.hasMarketplace
@@ -216,18 +223,16 @@ const REGISTRY_PLATFORMS = PLATFORM_REGISTRY.map((platform) => ({
  * until then a build-only entry lets the build emit an installable adapter
  * tree without fabricating an unverified install protocol.
  *
- * workbuddy: CodeBuddy/WorkBuddy plugin (official plugin reference:
- * `.codebuddy-plugin/plugin.json`, components at the plugin root,
- * `${CODEBUDDY_PLUGIN_ROOT}` expanded inline in skill content).
+ * Currently EMPTY: every platform the build emits now has a full registry
+ * descriptor. workbuddy (the CodeBuddy/WorkBuddy plugin, manifest
+ * `.codebuddy-plugin/plugin.json`, `${CODEBUDDY_PLUGIN_ROOT}` expanded inline
+ * in skill content) moved into the registry as the `codebuddy` platform with
+ * `buildAdapter.name = 'workbuddy'`, so its adapter tree is still produced —
+ * byte-for-byte unchanged — via REGISTRY_PLATFORMS. This constant is retained
+ * (still exported and consumed below) for future build-only hosts that have an
+ * installable adapter tree but no verified install protocol yet.
  */
-export const BUILD_ONLY_ADAPTERS = Object.freeze([
-  Object.freeze({
-    name: 'workbuddy',
-    pluginDirName: '.codebuddy-plugin',
-    templateFileName: 'plugin.json',
-    hasMarketplace: false,
-  }),
-]);
+export const BUILD_ONLY_ADAPTERS = Object.freeze([]);
 
 export const PLATFORMS = Object.freeze([...REGISTRY_PLATFORMS, ...BUILD_ONLY_ADAPTERS]);
 
@@ -427,12 +432,22 @@ async function generateAdapterFiles(platform, skills, templateJson, root, market
   const adapted = JSON.parse(JSON.stringify(templateJson));
 
   // Preserve platform-supported directory auto-discovery in generated adapters.
+  // The CodeBuddy server-side validator (`codebuddy plugin validate`) requires
+  // `skills` to be an array of component paths, so the workbuddy adapter emits
+  // ["./skills/"]; claude/codex/kimi hosts keep the directory-string form.
   if (typeof adapted.skills === 'string') {
-    adapted.skills = './skills/';
+    adapted.skills = platform.name === 'workbuddy' ? ['./skills/'] : './skills/';
   } else if (Array.isArray(adapted.skills)) {
-    for (const skill of adapted.skills) {
+    // Handle both string array and object array forms
+    adapted.skills = adapted.skills.map((skill) => {
+      if (typeof skill === 'string') {
+        // String array: transform to relative path for the adapter
+        return platform.name === 'workbuddy' ? './skills/' : skill;
+      }
+      // Object array: preserve existing behavior
       skill.source = `../skills/${skill.name}/SKILL.md`;
-    }
+      return skill;
+    });
   }
 
   const pluginJsonContent = JSON.stringify(adapted, null, 2) + '\n';