release-skill 0.9.3 → 0.9.5

package/bin/release-skill-cli.mjs

@@ -91,6 +91,39 @@ async function exitAfterFlush(exitCode) {
   process.exit(exitCode);
 }
 
+/**
+ * Keep command-line error JSON useful without exposing internal error objects,
+ * process envelopes, or filesystem details.  Local-finish evidence errors
+ * intentionally expose only their stable cause and executable next steps.
+ *
+ * @param {unknown} error
+ * @returns {Record<string, unknown>}
+ */
+function publicErrorDetails(error) {
+  const details = error?.details;
+  if (!details || typeof details !== 'object' || Array.isArray(details)) return {};
+  const output = {};
+  if (details.cause && typeof details.cause === 'object' && !Array.isArray(details.cause)) {
+    const cause = {};
+    if (typeof details.cause.code === 'string') cause.code = details.cause.code;
+    if (typeof details.cause.message === 'string') cause.message = details.cause.message;
+    if (Object.keys(cause).length > 0) output.cause = cause;
+  }
+  if (Array.isArray(details.nextSteps)) {
+    const nextSteps = details.nextSteps
+      .filter((step) => step && typeof step === 'object' && !Array.isArray(step))
+      .map((step) => ({
+        ...(typeof step.code === 'string' ? { code: step.code } : {}),
+        ...(typeof step.message === 'string' ? { message: step.message } : {}),
+        ...(Array.isArray(step.argv) && step.argv.every((arg) => typeof arg === 'string')
+          ? { argv: [...step.argv] } : {}),
+      }))
+      .filter((step) => Object.keys(step).length > 0);
+    if (nextSteps.length > 0) output.nextSteps = nextSteps;
+  }
+  return output;
+}
+
 /**
  * Check if a command is available and get its version.
  *
@@ -351,7 +384,7 @@ Options:
                    performs an append-only hooks edit of an existing config (create-once is untouched)
   --select-hooks <ids> Comma-separated proposal ids to adopt (propose-hooks mode)
   --foundation-profile <path> Explicit foundation postPublish profile JSON (proposal input only; never auto-applied)
-  --unit <id>      Release unit whose declared release documents are refreshed (docs refresh)
+  --unit <id>      Select a release unit for prepare/ship (repeatable); docs refresh accepts one unit
   --confirm-refresh <sha256:...> Confirm the exact dry-run refreshDigest before any document write
   --ack-local-document-write Acknowledge the explicit local release-document write (docs refresh --write)
   --platform <id>   Legacy attestation platform: kimi or codebuddy
@@ -559,6 +592,7 @@ if (command === 'ship' && (args.includes('--help') || args.includes('-h'))) {
       options: {
         targetVersion: '--target-version <version>',
         state: '--state <path>',
+        unit: '--unit <id> (repeatable before plan freeze)',
         approve: '--approve --actor <name>',
       },
       message: 'Repeat the same command to resume from the same state. For parallel or cross-session versions, use .release-skill/ships/<version>.json.',
@@ -572,6 +606,7 @@ Usage:
 Options:
   --target-version <version>  Specify the target version
   --state <path>              Specify the durable state file
+  --unit <id>                 Select a release unit before plan freeze (repeatable)
   --approve --actor <name>    Approve the plan bound to the current state
 
 Repeat the same command to resume from the same state.
@@ -787,6 +822,7 @@ function printShipApprovalSummary(result) {
   const summary = result.approvalSummary;
   if (!summary) return;
   console.log('Approval summary:');
+  console.log(`  This approval covers only these release units: ${(summary.units ?? []).map((unit) => unit.id).join(', ') || 'none'}`);
   for (const unit of summary.units ?? []) {
     console.log(`  Unit ${unit.id} ${unit.targetVersion}`);
     console.log(`    Public repo: ${unit.publicRepo}`);
@@ -817,6 +853,13 @@ if (command === 'ship') {
     return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
   };
   const root = resolve(value('--root') ?? process.cwd());
+  const hasUnitSelection = args.includes('--unit');
+  const unitIds = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--unit') {
+      unitIds.push(args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : '');
+    }
+  }
   // Repeatable --hook-approval <path>: checkpoint approvals for
   // requiresApproval postPublish hooks (same convention as distribute;
   // review major-1 — without this the ship flow can never complete a
@@ -862,6 +905,7 @@ if (command === 'ship') {
       planApprovalDigest: value('--approve-plan'),
       actor: value('--actor'),
       adapterRegistry,
+      ...(hasUnitSelection ? { unitIds } : {}),
       ...(postpublishApprovalPaths.length > 0 ? { postpublishApprovalPaths } : {}),
     });
     if (hasJson) {
@@ -892,9 +936,15 @@ if (command === 'ship') {
         } else {
           console.log('Post-release: branch advancement was already included; skip the merge question.');
         }
-        if (result.postRelease.localHostUpdate?.promptRequired) {
+        const localHostUpdate = result.postRelease.localHostUpdate;
+        if (localHostUpdate?.available === true && typeof localHostUpdate.runPath === 'string') {
           console.log(`Post-release: ask whether to update local host plugins (${result.postRelease.localHostUpdate.hosts.join(', ')}).`);
-          console.log(`Post-release command: release-skill post-release --plan ${result.planPath} --run ${result.verifyRunPath}`);
+          console.log(`Post-release command: release-skill post-release --plan ${result.planPath} --run ${localHostUpdate.runPath}`);
+          console.log('Choose --hosts before adding --update-local-hosts to perform a local update.');
+        } else {
+          for (const step of localHostUpdate?.nextSteps ?? []) {
+            console.log(`Next [${step.code}] ${step.message} (${step.argv.join(' ')})`);
+          }
         }
       }
       for (const followUp of result.manualFollowUps ?? []) {
@@ -996,6 +1046,13 @@ if (command === 'prepare') {
   const output = outputIdx !== -1 && args[outputIdx + 1] ? resolve(args[outputIdx + 1]) : undefined;
   const runDirIdx = args.indexOf('--run-dir');
   const runDir = runDirIdx !== -1 && args[runDirIdx + 1] ? resolve(args[runDirIdx + 1]) : undefined;
+  const hasUnitSelection = args.includes('--unit');
+  const unitIds = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--unit') {
+      unitIds.push(args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : '');
+    }
+  }
 
   try {
     const { prepareRelease } = await import('../src/commands/prepare.mjs');
@@ -1012,6 +1069,7 @@ if (command === 'prepare') {
       testSelection,
       output,
       runDir,
+      ...(hasUnitSelection ? { unitIds } : {}),
     });
 
     // Keep stdout compact and stable. The immutable plan remains the single
@@ -1041,6 +1099,7 @@ if (command === 'prepare') {
         })),
         warnings: result.warnings,
         nextSteps: result.nextSteps ?? [],
+        ...(result.releaseScope ? { releaseScope: result.releaseScope } : {}),
       }, null, 2));
     } else {
       for (const warning of result.warnings) {
@@ -1050,7 +1109,11 @@ if (command === 'prepare') {
       console.log(`Plan digest: ${result.planDigest}`);
       console.log(`Evidence: ${result.evidenceDir}`);
       for (const step of result.nextSteps ?? []) {
-        console.log(`Next [${step.code}] ${step.message}`);
+        console.log(`Next [${step.code}] ${step.message}${step.argv ? ` (${step.argv.join(' ')})` : ''}`);
+      }
+      if (result.releaseScope) {
+        console.log(`Release scope: ${result.releaseScope.selectedUnitIds.join(', ')}`);
+        console.log(`Deferred units: ${result.releaseScope.deferredUnitIds.join(', ') || 'none'}`);
       }
       if (plan.workflowKind && plan.workflowKind !== 'full') {
         console.log(`Workflow: ${plan.workflowKind}`);
@@ -1269,14 +1332,13 @@ if (command === 'post-release') {
   const planPath = value('--plan') ? resolve(value('--plan')) : undefined;
   const runPath = value('--run') ? resolve(value('--run')) : undefined;
   if (!planPath || !runPath) {
-    const message = 'post-release requires --plan <path> and --run <verified-run-path>';
+    const message = 'post-release requires --plan <path> and --run <verify-or-postverify-run-path>';
     if (hasJson) console.log(JSON.stringify({ error: 'MISSING_PARAMETERS', message, exitCode: 1 }));
     else console.error(`Error: ${message}`);
     await exitAfterFlush(1);
   }
   try {
     const {
-      assertVerifiedReleaseRun,
       derivePostReleaseChecklist,
       updateLocalHostPlugins,
     } = await import('../src/commands/post-release-local.mjs');
@@ -1284,24 +1346,26 @@ if (command === 'post-release') {
     const {
       loadRun,
       resolveRunPath,
-      validateRunLineage,
     } = await import('../src/core/run.mjs');
     const plan = JSON.parse(await readFile(planPath, 'utf8'));
     validatePlan(plan);
+    const updateRequested = args.includes('--update-local-hosts');
     const resolvedRunPath = await resolveRunPath(runPath);
     const runRecord = await loadRun(resolvedRunPath, {
       requireDigest: true,
       authorityPlanPath: planPath,
     });
-    await validateRunLineage(runRecord, {
-      plan,
-      planPath,
-      runPath: resolvedRunPath,
-      production: Boolean(plan.production),
-    });
-    assertVerifiedReleaseRun(plan, runRecord);
-
-    const updateRequested = args.includes('--update-local-hosts');
+    if (!updateRequested) {
+      const { assertLocalFinishRun } = await import('../src/commands/post-release-local.mjs');
+      await assertLocalFinishRun({
+        plan,
+        planPath,
+        runPath: resolvedRunPath,
+        runRecord,
+        production: Boolean(plan.production),
+        root: resolve(value('--root') ?? process.cwd()),
+      });
+    }
     const hostsIndex = args.indexOf('--hosts');
     const rawHosts = hostsIndex !== -1
       && args[hostsIndex + 1]
@@ -1314,12 +1378,19 @@ if (command === 'post-release') {
       .filter(Boolean);
     const result = updateRequested
       ? await updateLocalHostPlugins({
-        plan,
+        planPath,
+        runPath: resolvedRunPath,
         root: resolve(value('--root') ?? process.cwd()),
         confirmPlanDigest: value('--confirm-plan'),
         selectedHosts,
       })
-      : derivePostReleaseChecklist(plan);
+      : derivePostReleaseChecklist(plan, {
+        runPath: runRecord.command === 'postverify' && runRecord.status === 'DISTRIBUTED'
+          ? resolvedRunPath
+          : runRecord.command === 'verify' ? resolvedRunPath : undefined,
+        root: resolve(value('--root') ?? process.cwd()),
+        postVerifyComplete: runRecord.command === 'postverify' && runRecord.status === 'DISTRIBUTED',
+      });
 
     if (hasJson) {
       console.log(JSON.stringify(result, null, 2));
@@ -1327,8 +1398,14 @@ if (command === 'post-release') {
       console.log(`Post-release status: ${result.status}`);
       if (result.merge.promptRequired) console.log('Ask whether the user wants to merge the remaining branch.');
       else console.log('Branch advancement was already included in the release workflow; skip the merge question.');
-      if (result.localHostUpdate.promptRequired) {
+      if (result.localHostUpdate.available === true && typeof result.localHostUpdate.runPath === 'string') {
         console.log(`Ask whether to update local host plugins: ${result.localHostUpdate.hosts.join(', ')}`);
+        console.log(`Post-release command: release-skill post-release --plan ${planPath} --run ${result.localHostUpdate.runPath}`);
+        console.log('Choose --hosts before adding --update-local-hosts to perform a local update.');
+      } else {
+        for (const step of result.localHostUpdate.nextSteps ?? []) {
+          console.log(`Next [${step.code}] ${step.message} (${step.argv.join(' ')})`);
+        }
       }
     } else {
       console.log(`Local host update: ${result.status}`);
@@ -1344,9 +1421,15 @@ if (command === 'post-release') {
       console.log(JSON.stringify({
         error: err.code ?? 'POST_RELEASE_FAILED',
         message: err.message,
+        details: publicErrorDetails(err),
         exitCode: err.exitCode ?? 1,
       }));
-    } else console.error(`Error: ${err.message}`);
+    } else {
+      console.error(`Error: ${err.message}`);
+      for (const step of err.details?.nextSteps ?? []) {
+        console.error(`Next [${step.code}] ${step.message} (${step.argv.join(' ')})`);
+      }
+    }
     await exitAfterFlush(err.exitCode ?? 1);
   }
 }
@@ -1401,7 +1484,7 @@ if (command === 'verify') {
       } = await import('../src/commands/post-release-local.mjs');
       const plan = JSON.parse(await readFile(planPath, 'utf8'));
       try {
-        result.postRelease = derivePostReleaseChecklist(plan);
+        result.postRelease = derivePostReleaseChecklist(plan, { root, runPath: result.runPath });
       } catch (error) {
         result.postRelease = unavailablePostReleaseChecklist(plan, error);
       }
@@ -1427,8 +1510,15 @@ if (command === 'verify') {
       } else if (result.postRelease?.merge.promptRequired) {
         console.log('Post-release: ask whether to merge the remaining branch.');
       }
-      if (result.postRelease?.localHostUpdate.promptRequired) {
+      if (result.postRelease?.localHostUpdate?.available === true
+        && typeof result.postRelease.localHostUpdate.runPath === 'string') {
         console.log(`Post-release: ask whether to update local host plugins (${result.postRelease.localHostUpdate.hosts.join(', ')}).`);
+        console.log(`Post-release command: release-skill post-release --plan ${planPath} --run ${result.postRelease.localHostUpdate.runPath}`);
+        console.log('Choose --hosts before adding --update-local-hosts to perform a local update.');
+      } else {
+        for (const step of result.postRelease?.localHostUpdate?.nextSteps ?? []) {
+          console.log(`Next [${step.code}] ${step.message} (${step.argv.join(' ')})`);
+        }
       }
     }
 
@@ -1438,6 +1528,7 @@ if (command === 'verify') {
       const errOutput = {
         error: err.code ?? 'UNKNOWN_ERROR',
         message: err.message,
+        details: err.details ?? {},
         exitCode: err.exitCode ?? 1,
       };
       console.log(JSON.stringify(errOutput));