release-skill 0.9.4 → 0.9.5

package/src/core/plan.mjs

@@ -34,7 +34,7 @@ import { digestReleaseAssetIdentities, normalizeReleaseAssets } from './release-
 // function bodies (after the import graph has settled), never at plan.mjs
 // module-init time — a top-level read would hit the registry's
 // not-yet-initialized bindings when the cycle is entered registry-first.
-import { PLATFORMS } from '../platforms/registry.mjs';
+import { PLATFORMS, buildExpectedStandaloneIndexInstallIdentity } from '../platforms/registry.mjs';
 
 // ---------------------------------------------------------------------------
 // Schema loaded from the authoritative JSON file (single source of truth)
@@ -1278,6 +1278,7 @@ export function validatePlanActionCompleteness(plan, options = {}) {
         // 也不得接受"用 null 表示存在"的方案。
         if (production && externalMarketplace && dist.marketplaceSourceType === 'standalone-index') {
           const params = action.parameters;
+          const bootstrap = dist.firstReleaseBootstrap === 'manual-index-checkpoint';
           if (params) {
             if (!params.marketplaceIndexPath) {
               failures.push(
@@ -1294,6 +1295,41 @@ export function validatePlanActionCompleteness(plan, options = {}) {
                 `unit "${unitId}", action "${action.id}": parameters.selectedEntry is required for production standalone-index`,
               );
             }
+            if (bootstrap) {
+              if (params.firstReleaseBootstrap !== 'manual-index-checkpoint') {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": parameters.firstReleaseBootstrap must be manual-index-checkpoint for a bootstrap distribution`,
+                );
+              }
+              if (params.marketplaceIndexSha !== null) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": parameters.marketplaceIndexSha must remain null until the manual index checkpoint`,
+                );
+              }
+              let expectedEntry = null;
+              try {
+                expectedEntry = buildExpectedStandaloneIndexInstallIdentity(platform, {
+                  name: plugin,
+                  version: targetVersion,
+                  repo: publicRepo,
+                  tag: expectedTag,
+                  sha: frozen?.commit,
+                });
+              } catch {
+                // Missing frozen identity is reported by the surrounding
+                // production-field checks; do not turn completeness into an
+                // uncaught implementation error.
+              }
+              if (!expectedEntry || canonicalJson(params.selectedEntry) !== canonicalJson(expectedEntry)) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": bootstrap selectedEntry does not match the frozen plugin repository, tag, commit, and version`,
+                );
+              }
+            } else if (params.firstReleaseBootstrap !== undefined || params.marketplaceIndexSha !== undefined) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": bootstrap-only fields are not allowed without firstReleaseBootstrap`,
+              );
+            }
           }
         }
 
@@ -1329,6 +1365,14 @@ export function validatePlanActionCompleteness(plan, options = {}) {
             _checkRequired(action, 'expected.ref', action.expected?.ref, action.parameters?.ref, unitId, failures);
             _checkRequired(action, 'expected.marketplaceLocation', action.expected?.marketplaceLocation, 'external', unitId, failures);
             _checkRequired(action, 'expected.marketplaceCommitSha', action.expected?.marketplaceCommitSha, action.parameters?.marketplaceCommitSha, unitId, failures);
+            if (dist.firstReleaseBootstrap === 'manual-index-checkpoint') {
+              _checkRequired(action, 'expected.firstReleaseBootstrap', action.expected?.firstReleaseBootstrap, 'manual-index-checkpoint', unitId, failures);
+              if (action.expected?.marketplaceIndexSha !== null) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": expected.marketplaceIndexSha must be null until the manual index checkpoint`,
+                );
+              }
+            }
           } else {
             _checkRequired(action, 'expected.repo', action.expected?.repo, publicRepo, unitId, failures);
             _checkRequired(action, 'expected.ref', action.expected?.ref, expectedTag, unitId, failures);

package/src/platforms/registry.mjs

@@ -438,6 +438,103 @@ export function getPlatform(id) {
   return platform;
 }
 
+const STANDALONE_SHA_RE = /^[0-9a-f]{40}$/u;
+
+function standaloneIdentityCore(platformOrId, fields) {
+  const platform = typeof platformOrId === 'string' ? getPlatform(platformOrId) : platformOrId;
+  const id = platform?.id;
+  if (id !== 'claude' && id !== 'codex') {
+    throw new Error(`standalone-index install identity is unsupported for platform "${id ?? '<unknown>'}"`);
+  }
+  const { name, source, version } = fields;
+  if (typeof name !== 'string' || name.length === 0
+    || !source || typeof source !== 'object' || Array.isArray(source)
+    || typeof source.source !== 'string'
+    || typeof source.ref !== 'string' || source.ref.length === 0
+    || typeof source.sha !== 'string' || !STANDALONE_SHA_RE.test(source.sha)) {
+    throw new Error(`${id} standalone-index install identity has invalid owned fields`);
+  }
+  if (id === 'claude') {
+    if (source.source !== 'github' || typeof source.repo !== 'string' || source.repo.length === 0
+      || typeof version !== 'string' || version.length === 0) {
+      throw new Error('Claude standalone-index install identity requires github repo, ref, sha, and version');
+    }
+    return {
+      name,
+      source: { source: 'github', repo: source.repo, ref: source.ref, sha: source.sha },
+      version,
+    };
+  }
+  if (source.source !== 'url' || typeof source.url !== 'string' || source.url.length === 0) {
+    throw new Error('Codex standalone-index install identity requires url, ref, and sha');
+  }
+  return {
+    name,
+    source: { source: 'url', url: source.url, ref: source.ref, sha: source.sha },
+  };
+}
+
+/** Build the expected install identity from the frozen plugin contract. */
+export function buildExpectedStandaloneIndexInstallIdentity(platformOrId, frozenIdentity = {}) {
+  const platform = typeof platformOrId === 'string' ? getPlatform(platformOrId) : platformOrId;
+  const id = platform?.id;
+  const { name, repo, tag, sha, version } = frozenIdentity;
+  if (typeof repo !== 'string' || repo.length === 0 || typeof tag !== 'string' || tag.length === 0) {
+    throw new Error('standalone-index expected identity requires a plugin repository and tag');
+  }
+  if (id === 'claude') {
+    return standaloneIdentityCore(platform, {
+      name,
+      version,
+      source: { source: 'github', repo, ref: tag, sha },
+    });
+  }
+  if (id === 'codex') {
+    return standaloneIdentityCore(platform, {
+      name,
+      source: { source: 'url', url: `https://github.com/${repo}.git`, ref: `refs/tags/${tag}`, sha },
+    });
+  }
+  return standaloneIdentityCore(platform, { name, source: {}, version });
+}
+
+/** Project only the actual remote entry; frozen plan fields are never accepted. */
+export function projectObservedStandaloneIndexInstallIdentity(platformOrId, entry) {
+  const platform = typeof platformOrId === 'string' ? getPlatform(platformOrId) : platformOrId;
+  const id = platform?.id;
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new Error('standalone-index observed identity requires an entry object');
+  }
+  const source = entry.source;
+  if (!source || typeof source !== 'object' || Array.isArray(source)) {
+    throw new Error('standalone-index observed identity requires a source object');
+  }
+  if (id === 'claude') {
+    return standaloneIdentityCore(platform, {
+      name: entry.name,
+      version: entry.version,
+      source: {
+        source: source.source,
+        repo: source.repo,
+        ref: source.ref,
+        sha: source.sha,
+      },
+    });
+  }
+  if (id === 'codex') {
+    return standaloneIdentityCore(platform, {
+      name: entry.name,
+      source: {
+        source: source.source,
+        url: source.url,
+        ref: source.ref,
+        sha: source.sha,
+      },
+    });
+  }
+  return standaloneIdentityCore(platform, { name: entry.name, source });
+}
+
 /**
  * Resolve a declared skill projection surface to its public host name.
  * The host is always derived from the descriptor's authoritative

package/src/readme/contract.mjs

@@ -169,6 +169,28 @@ function findSkillNames(content, manifestSkillNames) {
   return manifestSkillNames.filter((name) => content.includes(name));
 }
 
+/**
+ * Determine whether README content contains a supported installation command.
+ *
+ * npm and npx remain compatible with the original whole-document check. The
+ * platform plugin commands are checked only inside Markdown code so that a
+ * marketplace-source explanation cannot be mistaken for an installation.
+ * @param {string} content
+ * @returns {boolean}
+ */
+function hasInstallCommand(content) {
+  if (/npm\s+install|npx\s+release-skill|npm\s+i\s+release-skill/i.test(content)) {
+    return true;
+  }
+
+  const codeBlocks = [
+    ...[...content.matchAll(/```[^\n]*\n([\s\S]*?)```/g)].map((match) => match[1]),
+    ...[...content.matchAll(/`([^`\n]+)`/g)].map((match) => match[1]),
+  ];
+  const pluginInstall = /^(?:[$>]\s*)?(?:codex\s+plugin\s+add|claude\s+plugin\s+install)\s+\S+/i;
+  return codeBlocks.some((block) => block.split('\n').some((line) => pluginInstall.test(line.trim())));
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -250,9 +272,7 @@ export async function evaluateReadme({ snapshotDir, pluginManifest }) {
 
   // Readability checks: installation, minimal example, failure diagnosis
   const readabilityChecks = {
-    hasInstall: enContent
-      ? /npm\s+install|npx\s+release-skill|npm\s+i\s+release-skill/i.test(enContent)
-      : false,
+    hasInstall: enContent ? hasInstallCommand(enContent) : false,
     hasMinimalExample: enContent
       ? /```[\s\S]*?(release-skill|assess|prepare|help)[\s\S]*?```/i.test(enContent)
       : false,