release-skill 0.2.8 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"

package/skills/release-help/SKILL.md

@@ -12,7 +12,7 @@ description: "Discoverable entry point for release-skill: dependency and environ
 ## 职责
 
 - 依赖和环境检查：Node.js >= 22、Git 决定本地准备就绪度；npm/gh 另行决定生产依赖就绪度
-- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；已有公开版本的生产闭环是显式的 `prepare --online --production → approve → publish → verify`
+- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`
 - 最小示例：展示从 release-help 到 release-assess 的最短路径
 - 只读诊断：运行 dry-run 检查，不修改任何文件
 - 故障引导：根据错误码指向对应的修复 Skill
@@ -35,6 +35,14 @@ description: "Discoverable entry point for release-skill: dependency and environ
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root <path> --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
+# 日常发布快速路径：最多两个授权摘要，状态文件可恢复
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-version <version> --json
+# 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" hooks validate --root <path> \
+  --acknowledge-hook-side-effects --json
+# Kimi/CodeBuddy 安装完成后记录人工事实，不手改 JSON
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" attest --root <path> \
+  --platform <kimi|codebuddy> --plugin <id> --result <passed|failed> --actor <person> --json
 # 发布文档刷新：默认只读演练
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --json
 # 摘要确认后的本地写入（三项绑定缺一不可）

package/skills-src/release-help/SKILL.md

@@ -12,7 +12,7 @@ description: "Discoverable entry point for release-skill: dependency and environ
 ## 职责
 
 - 依赖和环境检查：Node.js >= 22、Git 决定本地准备就绪度；npm/gh 另行决定生产依赖就绪度
-- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；已有公开版本的生产闭环是显式的 `prepare --online --production → approve → publish → verify`
+- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`
 - 最小示例：展示从 release-help 到 release-assess 的最短路径
 - 只读诊断：运行 dry-run 检查，不修改任何文件
 - 故障引导：根据错误码指向对应的修复 Skill
@@ -35,6 +35,14 @@ description: "Discoverable entry point for release-skill: dependency and environ
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root <path> --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
+# 日常发布快速路径：最多两个授权摘要，状态文件可恢复
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-version <version> --json
+# 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" hooks validate --root <path> \
+  --acknowledge-hook-side-effects --json
+# Kimi/CodeBuddy 安装完成后记录人工事实，不手改 JSON
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" attest --root <path> \
+  --platform <kimi|codebuddy> --plugin <id> --result <passed|failed> --actor <person> --json
 # 发布文档刷新：默认只读演练
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --json
 # 摘要确认后的本地写入（三项绑定缺一不可）

package/src/adapters/plugin-marketplace.mjs

@@ -476,7 +476,7 @@ async function resolveInstalledPayloadSubpath(snapshotDir, sourceEntries, action
   return extractDeclaredPluginSource(consumer, matches[0]);
 }
 
-async function verifyInstalledMarketplacePayload(action, context, installPath, consumer) {
+export async function verifyInstalledMarketplacePayload(action, context, installPath, consumer) {
   const sourcePath = await resolveFrozenPath(
     context.root,
     action.snapshotPath,

package/src/adapters/push-snapshot.mjs

@@ -32,7 +32,9 @@ export function githubRepositoryUrl(repo, host = 'github.com') {
   ) {
     throw new Error('githubHost must be a valid hostname');
   }
-  return `https://${host}/${repo}.git`;
+  return process.env.RELEASE_SKILL_GIT_TRANSPORT === 'ssh'
+    ? `git@${host}:${repo}.git`
+    : `https://${host}/${repo}.git`;
 }
 
 function validateOid(value, label) {

package/src/commands/assess.mjs

@@ -23,6 +23,7 @@ import { promisify } from 'node:util';
 
 import { loadProjectConfig } from '../core/config.mjs';
 import { ReleaseError, CONFIG_INVALID, GATE_FAILED } from '../core/errors.mjs';
+import { collectExpectedPublicSurfaceAdoptionWarnings } from '../core/public-surface.mjs';
 
 const execFile = promisify(execFileCb);
 
@@ -880,23 +881,35 @@ export async function assessProject(options) {
   // --- 2. Topology identification ---
   const topology = identifyTopology(config);
 
-  // --- 3. Common docs check ---
+  // --- 3. Expected public-surface adoption ---
+  for (const warning of collectExpectedPublicSurfaceAdoptionWarnings(config)) {
+    allGaps.push(createGap({
+      scope: GapScope.PROJECT,
+      category: GapCategory.POLICY,
+      severity: Severity.WARNING,
+      code: warning.code,
+      message: warning.message,
+      file: '.release-skill/project.yaml',
+    }));
+  }
+
+  // --- 4. Common docs check ---
   const docGaps = await checkCommonDocs(root, config);
   allGaps.push(...docGaps);
 
-  // --- 4. Plugin manifest check ---
+  // --- 5. Plugin manifest check ---
   const manifestGaps = await checkPluginManifests(root, config);
   allGaps.push(...manifestGaps);
 
-  // --- 5. Package metadata check ---
+  // --- 6. Package metadata check ---
   const metadataGaps = await checkPackageMetadata(root, config);
   allGaps.push(...metadataGaps);
 
-  // --- 6. Remote prerequisites ---
+  // --- 7. Remote prerequisites ---
   const remoteGaps = await checkRemotePrerequisites(root, config, offline);
   allGaps.push(...remoteGaps);
 
-  // --- 7. README structure check ---
+  // --- 8. README structure check ---
   const readmeGaps = await checkReadmeStructure(root, config);
   allGaps.push(...readmeGaps);
 

package/src/commands/attest.mjs

@@ -0,0 +1,195 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+
+import { SAFE_ID_RE, writeEvidenceAtomic } from '../adapters/contract.mjs';
+import { ReleaseError, GATE_FAILED, MISSING_PARAMETERS } from '../core/errors.mjs';
+
+const PLATFORM = Object.freeze({
+  kimi: {
+    directory: 'kimi-attestations',
+    requirementFile: 'release-skill-kimi-manual-install.json',
+  },
+  codebuddy: {
+    directory: 'codebuddy-attestations',
+    requirementFile: 'release-skill-codebuddy-manual-install.json',
+  },
+});
+
+async function validateInstalledConsumerClosure({
+  root,
+  platform,
+  requirement,
+  installPath,
+}) {
+  const planPath = resolve(root, '.release-skill', 'plans', `${requirement.planDigest}.json`);
+  const [
+    { validatePlan, computePlanDigest, assertImmutablePlanAuthority },
+    { createPluginMarketplaceAdapter, verifyInstalledMarketplacePayload },
+  ] = await Promise.all([
+    import('../core/plan.mjs'),
+    import('../adapters/plugin-marketplace.mjs'),
+  ]);
+  let plan;
+  try {
+    plan = JSON.parse(await readFile(planPath, 'utf8'));
+  } catch (error) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `cannot read the frozen plan required to verify the installed ${platform} payload: ${error.message}`,
+    );
+  }
+  validatePlan(plan);
+  assertImmutablePlanAuthority(planPath, plan);
+  if (computePlanDigest(plan) !== requirement.planDigest) {
+    throw new ReleaseError(GATE_FAILED, 'manual requirement planDigest does not match the frozen plan');
+  }
+  const actionType = `${platform}-marketplace-install`;
+  const action = (plan.externalActions ?? []).find((candidate) => (
+    candidate.type === actionType
+    && candidate.parameters?.plugin === requirement.plugin
+    && candidate.parameters?.version === requirement.version
+  ));
+  if (!action) {
+    throw new ReleaseError(GATE_FAILED, `frozen plan has no matching ${platform} install action`);
+  }
+  const adapter = createPluginMarketplaceAdapter();
+  const context = {
+    externalWritesAuthorized: false,
+    isolatedConsumerWritesAuthorized: false,
+    plan,
+    baseline: plan.baseline,
+    root,
+  };
+  const actionInput = { actionType, ...action.parameters };
+  const preflight = await adapter.preflight(actionInput, context);
+  if (preflight.status !== 'PREFLIGHT_PASSED') {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `${platform} installed-payload preflight failed: ${preflight.error}`,
+    );
+  }
+  const binding = await verifyInstalledMarketplacePayload(
+    actionInput,
+    context,
+    installPath,
+    platform,
+  );
+  return {
+    payloadDigest: action.parameters.manifestDigest,
+    manifestDigest: binding.manifestDigest,
+    extraInstalledPaths: binding.extraInstalledPaths ?? [],
+  };
+}
+
+/**
+ * Record the human fact needed by an interactive-only consumer. Identity
+ * fields come exclusively from the generated requirement; the operator only
+ * supplies the result, actor and optional observed install facts.
+ */
+export async function recordManualAttestation(options = {}, injected = {}) {
+  const {
+    root = process.cwd(),
+    platform,
+    plugin,
+    actor,
+    result,
+    installPath,
+    installChannel,
+    note,
+    clock = () => new Date().toISOString(),
+  } = options;
+  const descriptor = PLATFORM[platform];
+  if (!descriptor || !SAFE_ID_RE.test(plugin ?? '')) {
+    throw new ReleaseError(
+      MISSING_PARAMETERS,
+      'attest requires --platform <kimi|codebuddy> and a safe --plugin <id>',
+    );
+  }
+  if (typeof actor !== 'string' || actor.trim() === '') {
+    throw new ReleaseError(MISSING_PARAMETERS, 'attest requires --actor <person>');
+  }
+  if (result !== 'passed' && result !== 'failed') {
+    throw new ReleaseError(MISSING_PARAMETERS, 'attest requires --result <passed|failed>');
+  }
+
+  const authorityDir = resolve(root, '.release-skill', descriptor.directory, plugin);
+  const requirementPath = join(authorityDir, descriptor.requirementFile);
+  let requirement;
+  try {
+    requirement = JSON.parse(await readFile(requirementPath, 'utf8'));
+  } catch (error) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `cannot read generated ${platform} requirement: ${error.message}`,
+      { platform, plugin, requirementPath },
+    );
+  }
+  if (
+    requirement.platform !== platform
+    || requirement.plugin !== plugin
+    || typeof requirement.version !== 'string'
+    || !/^[a-f0-9]{64}$/.test(requirement.planDigest ?? '')
+    || typeof requirement.attestationFile !== 'string'
+  ) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `generated ${platform} requirement has invalid identity fields`,
+      { platform, plugin, requirementPath },
+    );
+  }
+  if (result === 'passed' && (typeof installPath !== 'string' || installPath === '')) {
+    throw new ReleaseError(
+      MISSING_PARAMETERS,
+      `${platform} passed attestation requires --install-path for installed payload verification`,
+    );
+  }
+  const needsInstallChannel = Object.hasOwn(requirement.attestationTemplate ?? {}, 'installChannel');
+  if (
+    result === 'passed'
+    && needsInstallChannel
+    && installChannel !== 'desktop'
+    && installChannel !== 'cli'
+  ) {
+    throw new ReleaseError(
+      MISSING_PARAMETERS,
+      `${platform} passed attestation requires --install-channel <desktop|cli>`,
+    );
+  }
+
+  const installBinding = result === 'passed'
+    ? await (injected.validateInstalledConsumerClosure ?? validateInstalledConsumerClosure)({
+        root,
+        platform,
+        requirement,
+        installPath,
+      })
+    : null;
+  const receipt = {
+    platform,
+    version: requirement.version,
+    planDigest: requirement.planDigest,
+    result,
+    actor: actor.trim(),
+    confirmedAt: clock(),
+    ...(installPath ? { installPath } : {}),
+    ...(installChannel ? { installChannel } : {}),
+    ...(note ? { note } : {}),
+    ...(installBinding ? {
+      payloadDigest: installBinding.payloadDigest,
+      installedClosureVerified: true,
+      extraInstalledPaths: installBinding.extraInstalledPaths,
+    } : {}),
+  };
+  const attestationPath = join(authorityDir, requirement.attestationFile);
+  await writeEvidenceAtomic(attestationPath, receipt);
+  return {
+    command: 'attest',
+    status: 'RECORDED',
+    platform,
+    plugin,
+    version: requirement.version,
+    planDigest: requirement.planDigest,
+    requirementPath,
+    attestationPath,
+  };
+}

package/src/commands/hooks.mjs

@@ -0,0 +1,46 @@
+import { mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { loadProjectConfig } from '../core/config.mjs';
+import { createEvidenceWriter } from '../core/evidence.mjs';
+import { runDeclaredHooks } from './prepare.mjs';
+import { ReleaseError, GATE_FAILED } from '../core/errors.mjs';
+
+/**
+ * Run the declared development gates and populate the exact same content-bound
+ * hook receipts consumed by prepare. A later ship/prepare reuses only
+ * cacheable hooks whose declared input closure is byte-identical.
+ */
+export async function validateDeclaredHooks(options = {}) {
+  const {
+    root = process.cwd(),
+    hooksAuthorized,
+    hookCache = true,
+    runDir = resolve(root, '.release-skill', 'runs', `hooks-${Date.now()}`),
+  } = options;
+  if (hooksAuthorized !== true) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      'hooks validate executes declared project commands; pass --acknowledge-hook-side-effects',
+    );
+  }
+  const { config, configDigest } = await loadProjectConfig({ root });
+  await mkdir(runDir, { recursive: true });
+  const evidence = createEvidenceWriter({
+    runDir,
+    command: 'hooks-validate',
+    clock: () => new Date().toISOString(),
+  });
+  const startedAt = new Date().toISOString();
+  await runDeclaredHooks(config, root, evidence, undefined, { hookCache });
+  return {
+    command: 'hooks validate',
+    status: 'PASSED',
+    configDigest,
+    hooks: Object.keys(config.hooks ?? {}).sort(),
+    cacheEnabled: hookCache,
+    evidenceDir: runDir,
+    startedAt,
+    finishedAt: new Date().toISOString(),
+  };
+}

package/src/commands/prepare.mjs

@@ -29,7 +29,10 @@ import { loadProjectConfig } from '../core/config.mjs';
 import { captureBaseline } from '../core/baseline.mjs';
 import { runHook } from '../core/hooks.mjs';
 import { computeHookCacheKey, readHookCache, writeHookCache } from '../core/hook-cache.mjs';
-import { assertExpectedPublicSurface } from '../core/public-surface.mjs';
+import {
+  assertExpectedPublicSurface,
+  collectExpectedPublicSurfaceAdoptionWarnings,
+} from '../core/public-surface.mjs';
 import { runSnapshotVerificationGates } from '../core/verification-gates.mjs';
 import { createEvidenceWriter } from '../core/evidence.mjs';
 import { computePlanDigest, writePlanAtomic, writePlanImmutable } from '../core/plan.mjs';
@@ -1670,7 +1673,7 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
  *   every declared hook runs in full and the incremental hook cache is neither
  *   read nor written.
  *
- * @returns {Promise<{ planPath: string, planDigest: string, evidenceDir: string }>}
+ * @returns {Promise<{ planPath: string, planDigest: string, evidenceDir: string, warnings: ReadonlyArray<object> }>}
  *
  * @throws {ReleaseError} on any gate failure. No PREPARED plan is written.
  */
@@ -1750,6 +1753,7 @@ export async function prepareRelease(options) {
     await evidence.append({ phase: 'config', status: 'started' });
 
     const { config, configPath, configDigest } = await loadProjectConfig({ root: realRoot });
+    const adoptionWarnings = collectExpectedPublicSurfaceAdoptionWarnings(config);
 
     await evidence.append({
       phase: 'config',
@@ -1757,6 +1761,13 @@ export async function prepareRelease(options) {
       configPath: relative(realRoot, configPath),
       configDigest,
     });
+    for (const warning of adoptionWarnings) {
+      await evidence.append({
+        phase: 'public-surface-adoption',
+        status: 'warning',
+        ...warning,
+      });
+    }
 
     // --- Step 1b: Resolve authoritative versions and gate release-document
     //     freshness BEFORE hook authorization ---
@@ -2913,6 +2924,7 @@ export async function prepareRelease(options) {
       planPath: writtenPath,
       planDigest,
       evidenceDir,
+      warnings: adoptionWarnings,
     };
   } catch (err) {
     // Record failure evidence