release-skill 0.2.9 → 0.4.0

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,42 @@
+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';
+// ReleaseError and GATE_FAILED removed: no authorization gate remains.
+
+/**
+ * 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: _hooksAuthorized,
+    hookCache = true,
+    runDir = resolve(root, '.release-skill', 'runs', `hooks-${Date.now()}`),
+  } = options;
+  // The command invocation itself authorizes execution of configured hooks.
+  // Old --acknowledge-hook-side-effects is accepted as a no-effect compatibility input.
+  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

@@ -1809,41 +1809,16 @@ export async function prepareRelease(options) {
         cwd: hook.cwd ?? '.',
       }));
 
+    // Hook and gate authorization: the command invocation itself authorizes
+    // execution of configured commands. Old acknowledgement parameters
+    // (--acknowledge-hook-side-effects, --acknowledge-gate-side-effects) are
+    // accepted as no-effect compatibility inputs but are not required.
     if (declaredHooks.length > 0) {
-      await evidence.append({
-        phase: 'hook-authorization',
-        status: 'started',
-        hookCount: declaredHooks.length,
-        hooks: declaredHooks.map((h) => `${h.name}: ${h.executable} ${h.args.join(' ')}`),
-      });
-
-      if (hooksAuthorized !== true) {
-        const hookList = declaredHooks
-          .map((h) => `  - ${h.name}: executable="${h.executable}", args=[${h.args.join(', ')}], cwd="${h.cwd}"`)
-          .join('\n');
-
-        await evidence.append({
-          phase: 'hook-authorization',
-          status: 'denied',
-          reason: 'hooks not explicitly authorized',
-        });
-
-        throw new ReleaseError(
-          GATE_FAILED,
-          `project declares ${declaredHooks.length} hook(s) that will be executed as arbitrary local processes.\n` +
-          `These hooks are NOT sandboxed — they may write to the filesystem outside the project, ` +
-          `access local credentials, or make network calls.\n` +
-          `The following hooks will run:\n${hookList}\n\n` +
-          `To proceed, pass --acknowledge-hook-side-effects (CLI) or hooksAuthorized=true (API). ` +
-          `Authorization means you accept hook side-effect risks; it does NOT make hooks safe.`,
-          { hookNames: declaredHooks.map((h) => h.name), hookCount: declaredHooks.length },
-        );
-      }
-
       await evidence.append({
         phase: 'hook-authorization',
         status: 'authorized',
         hookCount: declaredHooks.length,
+        hooks: declaredHooks.map((h) => `${h.name}: ${h.executable} ${h.args.join(' ')}`),
       });
     }
 
@@ -1851,7 +1826,7 @@ export async function prepareRelease(options) {
     if (declaredVerificationGates.length > 0) {
       await evidence.append({
         phase: 'verification-gate-authorization',
-        status: 'started',
+        status: 'authorized',
         gateCount: declaredVerificationGates.length,
         gates: declaredVerificationGates.map((gate) => ({
           id: gate.id,
@@ -1863,25 +1838,6 @@ export async function prepareRelease(options) {
           cwd: gate.cwd,
         })),
       });
-      if (verificationGatesAuthorized !== true) {
-        await evidence.append({
-          phase: 'verification-gate-authorization',
-          status: 'denied',
-          gateCount: declaredVerificationGates.length,
-        });
-        throw new ReleaseError(
-          GATE_FAILED,
-          `project declares ${declaredVerificationGates.length} verification gate(s). ` +
-          'They run local project commands without a network sandbox. ' +
-          'To proceed, pass --acknowledge-gate-side-effects (CLI) or verificationGatesAuthorized=true (API).',
-          { gateIds: declaredVerificationGates.map((gate) => gate.id) },
-        );
-      }
-      await evidence.append({
-        phase: 'verification-gate-authorization',
-        status: 'authorized',
-        gateCount: declaredVerificationGates.length,
-      });
     }
 
     // --- Step 3: Run declared hooks ---
@@ -2848,6 +2804,12 @@ export async function prepareRelease(options) {
     // Compute overall snapshot digest
     const overallSnapshotDigest = sha256Hex(snapshotDigests.join(':'));
 
+    // Detect human consumer platforms (Kimi/CodeBuddy) in the plan.
+    // When present, new plans mark them as non-blocking manual follow-up tasks.
+    const hasHumanConsumerActions = externalActions.some(
+      (a) => a.type === 'kimi-marketplace-install' || a.type === 'codebuddy-marketplace-install',
+    );
+
     const plan = {
       planVersion: 2,
       status: 'PREPARED',
@@ -2870,6 +2832,7 @@ export async function prepareRelease(options) {
       },
       verificationGates: config.verificationGates ?? [],
       snapshotDigest: overallSnapshotDigest,
+      ...(hasHumanConsumerActions ? { humanConsumersStrategy: 'manualFollowUps' } : {}),
       ...(production ? {
         production: {
           mode: 'github-npm-v1',

package/src/commands/publish.mjs

@@ -465,7 +465,6 @@ export async function publishRelease(options) {
     clock: clockOpt,
     captureBaselineFn,
     productionMode = false,
-    productionConfirmation,
     observePreviousPublicBaselineFn,
     observeRetrySleep,
   } = options ?? {};
@@ -544,13 +543,6 @@ export async function publishRelease(options) {
       if (!plan.production.assetRoot || plan.production.assetRoot === '.') {
         throw new ReleaseError(GATE_FAILED, 'production plan requires a dedicated assetRoot');
       }
-      if (!productionConfirmation || productionConfirmation !== actualDigest) {
-        throw new ReleaseError(
-          GATE_FAILED,
-          'production confirmation must exactly match the current plan digest',
-          { planDigest: actualDigest },
-        );
-      }
     }
 
     // =======================================================================

package/src/commands/reconcile.mjs

@@ -91,7 +91,6 @@ function defaultClock() {
  * @param {string} options.planPath - Absolute path to the frozen release plan.
  * @param {string} options.sourceRunPath - Absolute path to the source run (publish or prior reconcile).
  * @param {string} [options.approvalPath] - Path to the approval record (required if any action needs retry).
- * @param {string} [options.productionConfirmation] - Exact plan digest required before retrying production writes.
  * @param {Object} options.adapterRegistry - Adapter registry for action execution.
  * @param {string} [options.runDir] - Evidence directory. Defaults to `<planDir>/runs/reconcile-<ts>`.
  * @param {string} [options.root] - Project root for baseline capture.
@@ -114,7 +113,6 @@ export async function reconcileRelease(options) {
     root = process.cwd(),
     clock: clockOpt,
     captureBaselineFn,
-    productionConfirmation,
     observePreviousPublicBaselineFn,
     observeRetrySleep,
   } = options ?? {};
@@ -332,29 +330,6 @@ export async function reconcileRelease(options) {
       );
     }
 
-    // A production retry authority must be confirmed before any remote
-    // observation can influence whether a permanent write will be retried.
-    // Isolated marketplace consumer checks remain outside this requirement.
-    const planActionsById = new Map(
-      (plan.externalActions ?? []).map((action) => [action.id, action]),
-    );
-    const hasNonMarketplaceRetryCandidate = sourceRun.checkpoints.some((checkpoint) => {
-      if (checkpoint.status === 'succeeded') return false;
-      const action = planActionsById.get(checkpoint.actionId);
-      return action && !isMarketplaceAction(action.type);
-    });
-    if (
-      plan.production?.mode === 'github-npm-v1' &&
-      hasNonMarketplaceRetryCandidate &&
-      productionConfirmation !== actualDigest
-    ) {
-      throw new ReleaseError(
-        GATE_FAILED,
-        'production reconcile confirmation must exactly match the current plan digest before retry',
-        { planDigest: actualDigest },
-      );
-    }
-
     await evidence.append({
       phase: 'safety-gate',
       gate: 'source-run-load',
@@ -918,7 +893,7 @@ export async function reconcileRelease(options) {
     // --- Phase 2: Validate approval and global preflight before retrying ---
     //
     // Marketplace recovery is deferred to phase 4 and does NOT require
-    // approval or productionConfirmation; marketplace actions are isolated
+    // approval; marketplace actions are isolated
     // consumer checks, not permanent remote writes. Only non-marketplace
     // retries require approval.
     // =======================================================================
@@ -926,17 +901,8 @@ export async function reconcileRelease(options) {
     const nonMarketplaceRetries = actionsToRetry.filter((a) => !isMarketplaceAction(a.type));
 
     if (nonMarketplaceRetries.length > 0) {
-      // Non-marketplace retries require approval and productionConfirmation
-      if (
-        plan.production?.mode === 'github-npm-v1' &&
-        productionConfirmation !== actualDigest
-      ) {
-        throw new ReleaseError(
-          GATE_FAILED,
-          'production reconcile confirmation must exactly match the current plan digest before retry',
-          { planDigest: actualDigest, actionsToRetry: nonMarketplaceRetries.map((action) => action.id) },
-        );
-      }
+      // Non-marketplace retries require a current immutable approval. The
+      // approval already binds the exact plan digest and action set.
       if (!approval) {
         throw new ReleaseError(
           GATE_FAILED,