release-skill 0.2.9 → 0.4.0

package/src/commands/ship.mjs

@@ -0,0 +1,334 @@
+import { readFile, lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import {
+  ReleaseError,
+  GATE_FAILED,
+  PLAN_DIGEST_MISMATCH,
+  CONSUMER_VERIFICATION_DEFERRED,
+} from '../core/errors.mjs';
+
+async function writeJsonAtomic(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  const { stateDigest: _oldDigest, ...body } = value;
+  const sealed = {
+    ...body,
+    stateDigest: sha256Hex(canonicalJson(body)),
+  };
+  try {
+    await writeFile(temp, `${JSON.stringify(sealed, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+      flag: 'wx',
+    });
+    await rename(temp, path);
+  } catch (error) {
+    await rm(temp, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function readState(path) {
+  try {
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      throw new Error('ship state must be a regular non-symlink file');
+    }
+    const state = JSON.parse(await readFile(path, 'utf8'));
+    const { stateDigest, ...body } = state;
+    if (
+      typeof stateDigest !== 'string'
+      || stateDigest !== sha256Hex(canonicalJson(body))
+      || body.statePath !== path
+    ) {
+      throw new Error('ship state digest or authority path does not match');
+    }
+    return state;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw new ReleaseError(GATE_FAILED, `cannot read ship state: ${error.message}`, { statePath: path });
+  }
+}
+
+async function defaultDependencies() {
+  const [
+    configModule,
+    prepareModule,
+    approveModule,
+    publishModule,
+    reconcileModule,
+    verifyModule,
+    transportModule,
+    metadataModule,
+  ] = await Promise.all([
+    import('../core/config.mjs'),
+    import('./prepare.mjs'),
+    import('./approve.mjs'),
+    import('./publish.mjs'),
+    import('./reconcile.mjs'),
+    import('./verify.mjs'),
+    import('../core/git-transport.mjs'),
+    import('../core/release-metadata.mjs'),
+  ]);
+  return {
+    loadProjectConfig: configModule.loadProjectConfig,
+    prepareRelease: prepareModule.prepareRelease,
+    approvePlan: approveModule.approvePlan,
+    publishRelease: publishModule.publishRelease,
+    reconcileRelease: reconcileModule.reconcileRelease,
+    verifyRelease: verifyModule.verifyRelease,
+    preflightGitTransports: transportModule.preflightGitTransports,
+    updatePreviousPublicBaselines: metadataModule.updatePreviousPublicBaselines,
+  };
+}
+
+function publicState(state) {
+  return {
+    command: 'ship',
+    status: state.status,
+    statePath: state.statePath,
+    targetVersion: state.targetVersion,
+    ...(state.hooks && state.hooks.length > 0 ? {
+      hooks: state.hooks,
+    } : {}),
+    ...(state.planPath ? {
+      planPath: state.planPath,
+      planDigest: state.planDigest,
+      evidenceDir: state.evidenceDir,
+      warnings: state.warnings ?? [],
+    } : {}),
+    ...(state.approvalSummary ? { approvalSummary: state.approvalSummary } : {}),
+    ...(state.approvalPath ? { approvalPath: state.approvalPath } : {}),
+    ...(state.sourceRunPath ? { sourceRunPath: state.sourceRunPath } : {}),
+    ...(state.requirements ? { requirements: state.requirements } : {}),
+    ...(state.manualFollowUps ? { manualFollowUps: state.manualFollowUps } : {}),
+    ...(state.metadataUpdate ? { metadataUpdate: state.metadataUpdate } : {}),
+    verificationGateAuthorizationIncludedInPlanApproval: true,
+    postVerifyMetadataUpdateIncludedInPlanApproval: true,
+  };
+}
+
+/**
+ * Build a human-readable approval summary from the frozen plan.
+ * Lists each unit's version and every external action's id/type/unitId.
+ * Returns an empty summary when the plan file is not yet available (e.g., in tests).
+ *
+ * @param {string} planPath - Path to the frozen release plan.
+ * @returns {Promise<object>} The approval summary.
+ */
+async function buildApprovalSummary(planPath) {
+  try {
+    const plan = JSON.parse(await readFile(planPath, 'utf8'));
+    const units = (plan.units ?? []).map((unit) => ({
+      id: unit.id,
+      targetVersion: unit.targetVersion ?? unit.version,
+    }));
+    const actions = (plan.externalActions ?? []).map((action) => ({
+      id: action.id,
+      type: action.type,
+      unitId: action.unitId,
+    }));
+    return { units, actions };
+  } catch {
+    return { units: [], actions: [] };
+  }
+}
+
+/**
+ * Advance one durable production release. Re-running is safe: the state file
+ * carries the immutable plan, approval and source-run paths so the command
+ * resumes instead of reconstructing authority from terminal/chat output.
+ *
+ * New flow (v0.4+): ship directly runs configured hooks and verification gates
+ * without a separate hook authorization step. The only human gate is plan
+ * approval. Kimi/CodeBuddy installations are non-blocking manual follow-up
+ * tasks when the plan declares humanConsumersStrategy: 'manualFollowUps'.
+ */
+export async function advanceShip(options = {}, injected = {}) {
+  const root = resolve(options.root ?? process.cwd());
+  const statePath = resolve(
+    options.statePath ?? resolve(root, '.release-skill', 'ships', 'current.json'),
+  );
+  const deps = Object.keys(injected).length > 0
+    ? injected
+    : await defaultDependencies();
+  let state = await readState(statePath);
+  if (state?.gitTransport) {
+    process.env.RELEASE_SKILL_GIT_TRANSPORT = state.gitTransport;
+  }
+
+  if (!state) {
+    const loaded = await deps.loadProjectConfig({ root });
+    const hooks = Object.keys(loaded.config.hooks ?? {}).sort();
+    state = {
+      schemaVersion: 2,
+      root,
+      statePath,
+      targetVersion: options.targetVersion ?? null,
+      configDigest: loaded.configDigest,
+      hooks,
+      status: 'NEW',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJsonAtomic(statePath, state);
+  }
+
+  // Backward compatibility: auto-recover from legacy NEEDS_HOOK_AUTHORIZATION
+  // state. Old state files may have this status from the previous two-gate
+  // flow; the new flow runs hooks directly so we advance to NEW immediately.
+  if (state.status === 'NEEDS_HOOK_AUTHORIZATION') {
+    state.status = 'NEW';
+    state.updatedAt = new Date().toISOString();
+    await writeJsonAtomic(statePath, state);
+  }
+
+  if (state.status === 'NEW') {
+    const loaded = await deps.loadProjectConfig({ root });
+    if (loaded.configDigest !== state.configDigest) {
+      const hooks = Object.keys(loaded.config.hooks ?? {}).sort();
+      state = {
+        ...state,
+        configDigest: loaded.configDigest,
+        hooks,
+        status: 'NEW',
+        updatedAt: new Date().toISOString(),
+      };
+      await writeJsonAtomic(statePath, state);
+    }
+    const prepared = await deps.prepareRelease({
+      root,
+      version: state.targetVersion ?? undefined,
+      offline: false,
+      production: true,
+      hooksAuthorized: true,
+      verificationGatesAuthorized: true,
+      hookCache: true,
+    });
+    let transportPreflight = null;
+    if (deps.preflightGitTransports) {
+      const frozenPlan = JSON.parse(await readFile(prepared.planPath, 'utf8'));
+      transportPreflight = await deps.preflightGitTransports(frozenPlan);
+      process.env.RELEASE_SKILL_GIT_TRANSPORT = transportPreflight.transport;
+    }
+    const approvalSummary = await buildApprovalSummary(prepared.planPath);
+    state = {
+      ...state,
+      status: 'NEEDS_PLAN_APPROVAL',
+      planPath: prepared.planPath,
+      planDigest: prepared.planDigest,
+      evidenceDir: prepared.evidenceDir,
+      warnings: prepared.warnings,
+      approvalSummary,
+      ...(transportPreflight ? {
+        gitTransport: transportPreflight.transport,
+        gitTransportPreflight: transportPreflight.repositories,
+      } : {}),
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJsonAtomic(statePath, state);
+  }
+
+  if (state.status === 'NEEDS_PLAN_APPROVAL') {
+    // Boolean --approve: auto-use the stored planDigest (no user digest input needed).
+    // Legacy --approve-plan <digest>: explicit digest must match.
+    const approveRequested = options.approve === true
+      || (typeof options.planApprovalDigest === 'string' && options.planApprovalDigest.length > 0);
+    if (!approveRequested) return publicState(state);
+    if (options.approve === true) {
+      // Boolean approve: no digest input; the stored planDigest is authoritative.
+    } else if (options.planApprovalDigest !== state.planDigest) {
+      throw new ReleaseError(PLAN_DIGEST_MISMATCH, 'ship plan approval digest does not match the frozen plan');
+    }
+    if (!options.actor) {
+      throw new ReleaseError(GATE_FAILED, 'ship plan approval requires --actor <person>');
+    }
+    const approval = await deps.approvePlan({
+      planPath: state.planPath,
+      expectedDigest: state.planDigest,
+      actor: options.actor,
+    });
+    state = {
+      ...state,
+      status: 'APPROVED',
+      approvalPath: approval.approvalPath,
+      verificationGatesAuthorized: true,
+      approvedBy: options.actor,
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJsonAtomic(statePath, state);
+  }
+
+  if (state.status === 'APPROVED' || state.status === 'PUBLISHING') {
+    if (!options.adapterRegistry) {
+      throw new ReleaseError(GATE_FAILED, 'ship requires an adapter registry to publish');
+    }
+    state.status = 'PUBLISHING';
+    await writeJsonAtomic(statePath, state);
+    const published = await deps.publishRelease({
+      planPath: state.planPath,
+      approvalPath: state.approvalPath,
+      adapterRegistry: options.adapterRegistry,
+      root,
+      productionMode: true,
+    });
+    state = {
+      ...state,
+      status: published.status,
+      sourceRunPath: published.runPath,
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJsonAtomic(statePath, state);
+  }
+
+  if (state.status === 'PARTIAL') {
+    const reconciled = await deps.reconcileRelease({
+      planPath: state.planPath,
+      sourceRunPath: state.sourceRunPath,
+      approvalPath: state.approvalPath,
+      adapterRegistry: options.adapterRegistry,
+      root,
+    });
+    state = {
+      ...state,
+      status: reconciled.status,
+      sourceRunPath: reconciled.runPath,
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJsonAtomic(statePath, state);
+  }
+
+  if (state.status === 'PUBLISHED' || state.status === 'NEEDS_MANUAL_ATTESTATIONS') {
+    try {
+      const verified = await deps.verifyRelease({
+        planPath: state.planPath,
+        sourceRunPath: state.sourceRunPath,
+        adapterRegistry: options.adapterRegistry,
+        root,
+        verificationGatesAuthorized: state.verificationGatesAuthorized === true,
+      });
+      state = {
+        ...state,
+        status: verified.status,
+        verifyRunPath: verified.runPath,
+        requirements: undefined,
+        manualFollowUps: verified.manualFollowUps ?? undefined,
+        updatedAt: new Date().toISOString(),
+      };
+      await writeJsonAtomic(statePath, state);
+    } catch (error) {
+      if (error?.code !== CONSUMER_VERIFICATION_DEFERRED) throw error;
+      state = {
+        ...state,
+        status: 'NEEDS_MANUAL_ATTESTATIONS',
+        requirements: error.details?.requirements ?? [],
+        updatedAt: new Date().toISOString(),
+      };
+      await writeJsonAtomic(statePath, state);
+    }
+  }
+
+  return publicState(state);
+}

package/src/commands/verify.mjs

@@ -43,6 +43,7 @@ import {
   GATE_FAILED,
   CONFIG_MISSING,
   POST_PUBLISH_VERIFY_FAILED,
+  CONSUMER_VERIFICATION_DEFERRED,
 } from '../core/errors.mjs';
 import { verifySourceAuthorityReceipt } from '../core/source-authority.mjs';
 import { assertTransition, PUBLISHED, VERIFIED } from '../core/state-machine.mjs';
@@ -67,6 +68,20 @@ import {
   buildDirectoryFileIndex,
   checkNpmEntryClosure,
 } from '../npm/npm-entry-closure.mjs';
+import {
+  KIMI_ATTESTATION_FILE,
+  KIMI_REQUIREMENT_FILE,
+  kimiAuthorityDir,
+  resolveBoundPlanDigest,
+  validateKimiAttestation,
+} from '../platforms/kimi.mjs';
+import {
+  CODEBUDDY_ATTESTATION_FILE,
+  CODEBUDDY_REQUIREMENT_FILE,
+  codebuddyAuthorityDir,
+  resolveCodeBuddyBoundPlanDigest,
+  validateCodeBuddyAttestation,
+} from '../platforms/codebuddy.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -120,6 +135,103 @@ function isValidDigest(digest) {
   return typeof digest === 'string' && /^[a-f0-9]{64}$/.test(digest);
 }
 
+/**
+ * Generate every manual consumer requirement before any expensive automatic
+ * consumer install starts. This turns a sequence of "install Kimi, rerun,
+ * then discover CodeBuddy" failures into one actionable response.
+ */
+async function collectMissingManualAttestations({
+  actions,
+  adapterRegistry,
+  plan,
+  root,
+  runDir,
+  clockFn,
+}) {
+  const manual = actions.filter((action) => (
+    action.type === 'kimi-marketplace-install'
+    || action.type === 'codebuddy-marketplace-install'
+  ));
+  if (manual.length === 0) return [];
+
+  const missing = [];
+  for (const action of manual) {
+    const adapterActionType = ADAPTER_ACTION_TYPE_MAP[action.type];
+    const adapter = adapterRegistry.getAdapter(adapterActionType);
+    // Tests and embedders may intentionally register a fully automatic
+    // adapter for these action types. Only the real platform adapter owns the
+    // interactive manual-install protocol and its stable authority files.
+    if (adapter.name !== 'plugin-marketplace') continue;
+    const context = {
+      externalWritesAuthorized: false,
+      isolatedConsumerWritesAuthorized: true,
+      plan,
+      baseline: plan.baseline,
+      root,
+      runDir,
+    };
+    const actionInput = { actionType: adapterActionType, ...action.parameters };
+    const preflight = await adapter.preflight(actionInput, context);
+    if (preflight.status !== 'PREFLIGHT_PASSED') {
+      throw new ReleaseError(
+        POST_PUBLISH_VERIFY_FAILED,
+        `manual consumer preflight did not pass for action "${action.id}": ${preflight.error}`,
+        { actionId: action.id, platform: action.type.split('-')[0] },
+      );
+    }
+    const executed = await adapter.execute(actionInput, context);
+    if (executed.status !== 'EXECUTED') {
+      throw new ReleaseError(
+        POST_PUBLISH_VERIFY_FAILED,
+        `cannot generate manual consumer requirement for action "${action.id}": ${executed.error}`,
+        { actionId: action.id, platform: action.type.split('-')[0] },
+      );
+    }
+
+    const isKimi = action.type === 'kimi-marketplace-install';
+    const planDigest = isKimi
+      ? resolveBoundPlanDigest(context)
+      : await resolveCodeBuddyBoundPlanDigest(context);
+    const authorityDir = isKimi
+      ? kimiAuthorityDir(context, planDigest, action.parameters.plugin)
+      : codebuddyAuthorityDir(context, planDigest, action.parameters.plugin);
+    const requirementPath = join(
+      authorityDir,
+      isKimi ? KIMI_REQUIREMENT_FILE : CODEBUDDY_REQUIREMENT_FILE,
+    );
+    const attestationPath = join(
+      authorityDir,
+      isKimi ? KIMI_ATTESTATION_FILE : CODEBUDDY_ATTESTATION_FILE,
+    );
+
+    let valid = false;
+    let reason = 'attestation file is missing';
+    try {
+      const attestation = JSON.parse(await readFile(attestationPath, 'utf8'));
+      const validation = isKimi
+        ? validateKimiAttestation(attestation, action.parameters, clockFn(), planDigest)
+        : validateCodeBuddyAttestation(attestation, action.parameters, clockFn(), planDigest);
+      valid = validation.valid;
+      reason = validation.error;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') reason = `attestation cannot be read: ${error.message}`;
+    }
+    if (!valid) {
+      missing.push({
+        actionId: action.id,
+        platform: isKimi ? 'kimi' : 'codebuddy',
+        plugin: action.parameters.plugin,
+        version: action.parameters.version,
+        planDigest,
+        requirementPath,
+        attestationPath,
+        reason,
+      });
+    }
+  }
+  return missing;
+}
+
 // ---------------------------------------------------------------------------
 // Smoke test
 // ---------------------------------------------------------------------------
@@ -643,7 +755,7 @@ export async function verifyRelease(options) {
     runDir: runDirOpt,
     clock: clockOpt,
     npmExecutor,
-    verificationGatesAuthorized,
+    verificationGatesAuthorized: _verificationGatesAuthorized,
     gateEnv,
     previousVerifyRun,
   } = options ?? {};
@@ -714,16 +826,9 @@ export async function verifyRelease(options) {
         .filter((distribution) => distribution.type === 'npm' && distribution.smokeBin)
         .map((distribution) => ({ unitId: unit.id, smokeBin: distribution.smokeBin }))
     ));
-    if ((consumerGates.length > 0 || configuredSmokeBins.length > 0) && verificationGatesAuthorized !== true) {
-      throw new ReleaseError(
-        GATE_FAILED,
-        `plan declares ${consumerGates.length} consumer verification gate(s) and ` +
-        `${configuredSmokeBins.length} npm CLI smoke process(es). ` +
-        'They execute installed project code without an OS or network sandbox. ' +
-        'To proceed, pass --acknowledge-gate-side-effects (CLI) or verificationGatesAuthorized=true (API).',
-        { gateIds: consumerGates.map((gate) => gate.id), configuredSmokeBins },
-      );
-    }
+    // The command invocation itself authorizes execution of configured
+    // verification gates and smoke processes. Old --acknowledge-gate-side-effects
+    // is accepted as a no-effect compatibility input.
 
     await evidence.append({ phase: 'verify', step: 'plan-load', status: 'passed' });
 
@@ -1000,7 +1105,43 @@ export async function verifyRelease(options) {
       }
     }
 
-    for (const action of actions) {
+    // When the plan declares humanConsumersStrategy: 'manualFollowUps',
+    // Kimi/CodeBuddy installations are non-blocking post-release manual tasks.
+    // Skip attestation collection and blocking for these platforms.
+    const isHumanConsumerFollowUp = plan.humanConsumersStrategy === 'manualFollowUps';
+
+    const missingManualAttestations = isHumanConsumerFollowUp
+      ? []
+      : await collectMissingManualAttestations({
+          actions,
+          adapterRegistry,
+          plan,
+          root,
+          runDir,
+          clockFn,
+        });
+    if (missingManualAttestations.length > 0) {
+      await evidence.append({
+        phase: 'verify',
+        step: 'manual-attestations',
+        status: 'needs-input',
+        requirements: missingManualAttestations,
+      });
+      throw new ReleaseError(
+        CONSUMER_VERIFICATION_DEFERRED,
+        `${missingManualAttestations.length} manual consumer attestation(s) are required`,
+        { requirements: missingManualAttestations },
+      );
+    }
+
+    // Collect non-blocking manual follow-up tasks for human consumer platforms
+    const manualFollowUps = [];
+
+    // Every action is identity-bound and adapters receive read-only or
+    // per-action isolated consumer paths. Run independent checks concurrently;
+    // the evidence writer serializes append operations and result arrays are
+    // sorted afterwards for deterministic receipts.
+    const actionResults = await Promise.allSettled(actions.map(async (action) => {
       const adapterActionType = ADAPTER_ACTION_TYPE_MAP[action.type];
 
       // Skip meta-checkpoints
@@ -1011,7 +1152,7 @@ export async function verifyRelease(options) {
           status: 'SKIPPED',
           reason: 'meta-checkpoint',
         });
-        continue;
+        return;
       }
 
       let adapter;
@@ -1027,6 +1168,38 @@ export async function verifyRelease(options) {
       }
 
       if (isMarketplaceAction(action.type)) {
+        // When humanConsumersStrategy is 'manualFollowUps', Kimi/CodeBuddy
+        // installations are non-blocking manual follow-up tasks. Skip adapter
+        // processing and collect them as manualFollowUps.
+        const isHumanConsumerPlatform = action.type === 'kimi-marketplace-install'
+          || action.type === 'codebuddy-marketplace-install';
+        if (isHumanConsumerFollowUp && isHumanConsumerPlatform) {
+          const platform = action.type === 'kimi-marketplace-install' ? 'kimi' : 'codebuddy';
+          manualFollowUps.push({
+            actionId: action.id,
+            platform,
+            plugin: action.parameters?.plugin,
+            version: action.parameters?.version,
+            unitId: action.unitId,
+            verifiedBySystem: false,
+            reason: 'human consumer platform — installation is a manual post-release task; not verified by system',
+          });
+          adapterChecks.push({
+            actionId: action.id,
+            actionType: action.type,
+            status: 'SKIPPED',
+            reason: 'manual-follow-up',
+          });
+          await evidence.append({
+            phase: 'verify-marketplace',
+            actionId: action.id,
+            actionType: action.type,
+            status: 'SKIPPED',
+            reason: 'manual-follow-up',
+          });
+          return;
+        }
+
         // --- Marketplace: fresh consumer verification in verify's own runDir ---
         // Context: isolatedConsumerWritesAuthorized allows writing to verify's
         // runDir/consumers/ directory; externalWritesAuthorized stays false.
@@ -1142,7 +1315,7 @@ export async function verifyRelease(options) {
               installationContractDigest: currentDigest,
             });
 
-            continue;
+            return;
           }
         }
 
@@ -1305,7 +1478,12 @@ export async function verifyRelease(options) {
           );
         }
       }
-    }
+    }));
+    adapterChecks.sort((a, b) => a.actionId.localeCompare(b.actionId));
+    consumerVerificationReceipts.sort((a, b) => a.actionId.localeCompare(b.actionId));
+    consumerGateResults.sort((a, b) => a.id.localeCompare(b.id));
+    const rejectedAction = actionResults.find((result) => result.status === 'rejected');
+    if (rejectedAction) throw rejectedAction.reason;
 
     await evidence.append({ phase: 'verify', step: 'adapter-verify', status: 'completed' });
 
@@ -1494,6 +1672,7 @@ export async function verifyRelease(options) {
       gateResults: consumerGateResults,
       consumerVerificationReceipts,
       skillResourceClosureReceipts,
+      ...(manualFollowUps.length > 0 ? { manualFollowUps } : {}),
       startedAt: clockFn(),
       finishedAt: clockFn(),
     };
@@ -1517,6 +1696,7 @@ export async function verifyRelease(options) {
       adapterChecks,
       smokeTest,
       gateResults: consumerGateResults,
+      ...(manualFollowUps.length > 0 ? { manualFollowUps } : {}),
     };
   } catch (err) {
     await evidence.append({