release-skill 0.9.0 → 0.9.3

package/src/commands/prepare.mjs

@@ -25,7 +25,7 @@ import { promisify } from 'node:util';
 
 const execFile = promisify(execFileCb);
 
-import { classifyPathInput, writeFileAtomic } from 'skill-family-harness-node';
+import { classifyPathInput, writeFileAtomic, withTemporaryWorkspace } from 'skill-family-harness-node';
 import { loadProjectConfig } from '../core/config.mjs';
 import { captureBaseline } from '../core/baseline.mjs';
 import { runHook } from '../core/hooks.mjs';
@@ -57,7 +57,11 @@ import {
 } from '../snapshot/frozen.mjs';
 import { ReleaseError, GATE_FAILED, CONFIG_INVALID, CONFIG_MISSING, FORBIDDEN_CONTENT_DETECTED, RELEASE_DOCS_STALE, DIRTY_SOURCE_INPUT, BUNDLE_STALE } from '../core/errors.mjs';
 import { assertBundleFreshness } from '../core/bundle-freshness.mjs';
-import { assertAdapterFreshness, assertSelfBootstrapFacts } from '../core/derived-artifact-gates.mjs';
+import {
+  assertAdapterFreshness,
+  assertPlatformManifestFreshness,
+  assertSelfBootstrapFacts,
+} from '../core/derived-artifact-gates.mjs';
 import { isFoundationPluginVerificationEligible } from '../core/foundation-plugin-verification.mjs';
 import { PKG_ROOT } from '../core/pkg-root.mjs';
 import { writeFrozenMarker, FROZEN_MARKER_FILENAME } from '../core/frozen-marker.mjs';
@@ -319,9 +323,16 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
 
     // --- Incremental cache lookup (opt-in only; default zero change) ---
     let cacheKey;
+    let cacheReceipt;
+    let cacheRootBinding;
     if (cacheEnabled && hook.cacheable === true) {
       try {
-        ({ cacheKey } = await computeHookCacheKey(hook, root));
+        ({ cacheKey, receipt: cacheReceipt, projectRootBinding: cacheRootBinding } = await computeHookCacheKey(hook, root, {
+          env: options.env ?? process.env,
+          ...(typeof options.observeExecutableIdentityFn === 'function'
+            ? { observeExecutableIdentityFn: options.observeExecutableIdentityFn }
+            : {}),
+        }));
       } catch (err) {
         await evidence.append({
           phase: 'hooks',
@@ -332,7 +343,9 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
         throw err;
       }
 
-      const cached = await readHookCache(root, name, cacheKey);
+      const cached = cacheKey ? await readHookCache(root, name, cacheKey, {
+        rootBinding: cacheRootBinding,
+      }) : null;
       if (cached) {
         // Cache hit: skip execution. The authorization gate already passed and
         // no GATE is bypassed — ordering and failure semantics are untouched.
@@ -403,12 +416,13 @@ export async function runDeclaredHooks(config, root, evidence, hookFn = runHook,
     }
 
     // --- Write cache on success only; failures are never cached ---
-    if (cacheEnabled && hook.cacheable === true && cacheKey) {
+    if (cacheEnabled && hook.cacheable === true && cacheKey && cacheReceipt) {
       const written = await writeHookCache(root, name, cacheKey, {
         exitCode: 0,
         stdoutTail: result.stdout.slice(-4000),
         stderrTail: result.stderr.slice(-4000),
-      });
+        receipt: cacheReceipt,
+      }, { rootBinding: cacheRootBinding });
       if (!written.ok) {
         // The cache is an optimisation, not a gate: a write failure must not
         // abort prepare. Surface it as a warning-level evidence event.
@@ -2790,6 +2804,119 @@ async function runPrepareSkillResourceClosureGate({
   return skillResourceClosureResults;
 }
 
+/**
+ * R93-01: optionally inspect the public surface before the first declared
+ * hook. The staging and closure checks are deliberately ephemeral: their
+ * result is an execution gate, not a plan/approval/publish receipt. The
+ * normal post-hook snapshot and closure gate remains authoritative.
+ */
+async function runPreHookPublicSurfaceGate({
+  config,
+  root,
+  resolvedVersions,
+  evidence,
+  skipDeclaredHooks,
+  workflow,
+}) {
+  if (config.policy?.preHookPublicSurfaceCheck !== true) return;
+
+  const declaredHookCount = Object.values(config.hooks ?? {})
+    .filter((hook) => hook && hook.command).length;
+  if (skipDeclaredHooks || declaredHookCount === 0) {
+    await evidence.append({
+      phase: 'pre-hook-public-surface',
+      status: 'skipped',
+      reason: skipDeclaredHooks
+        ? `workflow "${workflow}" trims code-class hooks`
+        : 'no declared hooks',
+    });
+    return;
+  }
+
+  await evidence.append({ phase: 'pre-hook-public-surface', status: 'started' });
+  let currentUnitId = null;
+  let unitCount = 0;
+  try {
+    await withTemporaryWorkspace(async (workspace) => {
+      const stagingRoot = workspace.root;
+      const unitResults = [];
+      for (const unit of config.releaseUnits ?? []) {
+        currentUnitId = unit.id;
+        const outputDir = resolveUnitScopedPath(stagingRoot, unit.id);
+        const publicManifest = await buildPublicStaging({
+          sourceRoot: root,
+          unit,
+          outputDir,
+        });
+        unitResults.push({
+          unit,
+          manifest: {
+            entries: publicManifest.entries,
+            files: publicManifest.entries.map((entry) => entry.path).sort(),
+            totalSize: publicManifest.totalSize,
+            fileCount: publicManifest.fileCount,
+            contentHash: publicManifest.contentHash,
+            snapshotDigest: publicManifest.contentHash,
+            source: unit.source,
+            outputDir: publicManifest.outputDir,
+          },
+        });
+      }
+
+      const { frozenManifestByDist } = await resolveDistributionManifestFacts(
+        unitResults,
+        resolvedVersions,
+      );
+      unitCount = unitResults.length;
+      // Reuse the production closure/host-surface implementation, but do not
+      // append its ordinary phase events or retain its receipt in the plan.
+      await runPrepareSkillResourceClosureGate({
+        unitResults,
+        frozenManifestByDist,
+        freezeTimestamp: null,
+        evidence: { append: async () => undefined },
+        skipSkillResourceClosure: false,
+        workflow: 'pre-hook-public-surface',
+      });
+    });
+    await evidence.append({
+      phase: 'pre-hook-public-surface',
+      status: 'passed',
+      unitCount,
+    });
+  } catch (error) {
+    const details = {
+      ...(error instanceof ReleaseError ? error.details : {}),
+      phase: 'pre-hook-public-surface',
+      unitId: error?.details?.unitId ?? currentUnitId,
+    };
+    if (Array.isArray(details.findings)) {
+      details.findings = details.findings.slice(0, 50);
+    }
+    await evidence.append({
+      phase: 'pre-hook-public-surface',
+      status: 'failed',
+      error: { code: error.code ?? GATE_FAILED, message: error.message },
+    });
+    if (error instanceof ReleaseError) {
+      throw new ReleaseError(
+        error.code,
+        `pre-hook public surface check failed before hooks: ${error.message}`,
+        details,
+        error.exitCode,
+      );
+    }
+    throw new ReleaseError(
+      GATE_FAILED,
+      `pre-hook public surface check failed before hooks: ${error.message}`,
+      details,
+    );
+  } finally {
+    // withTemporaryWorkspace disposes the Foundation-managed staging root on
+    // both success and failure; no project run artifact is retained.
+  }
+}
+
 export async function prepareRelease(options) {
   const {
     root,
@@ -3025,8 +3152,9 @@ export async function prepareRelease(options) {
     // --- Step 1b-fast: version-sensitive derived-artifact fast pre-gates (O1) ---
     // 2026-08-18 investigation §3.2: adapter drift and stale self-bootstrap
     // fact pins used to surface only deep inside the ~80s full test hook.
-    // Promote the two exact canonical checks (build-adapters --check and the
-    // release-docs-self-bootstrap single-file test) to prepare's earliest
+    // Promote the three exact canonical checks (build-adapters --check,
+    // generate-platform-manifest --check, and the release-docs-self-bootstrap
+    // single-file test) to prepare's earliest
     // stage so the same drift fails closed in seconds, before any hook. Like
     // the bundle freshness gate this is artifact-integrity class: workflow
     // trimming never exempts it. Installed layouts record not-applicable.
@@ -3034,7 +3162,8 @@ export async function prepareRelease(options) {
     // the CLI, plain function calls, and the node:test harness — no
     // environment variable may exempt them (a test seam is never a
     // production switch). Tests that need lightweight fixtures inject the
-    // adapterFreshnessFn/selfBootstrapFactsFn seams explicitly in-process.
+    // adapterFreshnessFn/platformManifestFreshnessFn/selfBootstrapFactsFn
+    // seams explicitly in-process.
     await evidence.append({ phase: 'adapter-freshness', status: 'started' });
     const adapterFreshnessFn = options.adapterFreshnessFn ?? assertAdapterFreshness;
     let adapterFreshness;
@@ -3063,6 +3192,35 @@ export async function prepareRelease(options) {
       });
     }
 
+    await evidence.append({ phase: 'platform-manifest-freshness', status: 'started' });
+    const platformManifestFreshnessFn = options.platformManifestFreshnessFn
+      ?? assertPlatformManifestFreshness;
+    let platformManifestFreshness;
+    try {
+      platformManifestFreshness = await platformManifestFreshnessFn(PKG_ROOT);
+    } catch (err) {
+      await evidence.append({
+        phase: 'platform-manifest-freshness',
+        status: 'blocking',
+        reason: err.details?.reason ?? null,
+        error: { code: err.code, message: err.message },
+      });
+      throw err;
+    }
+    if (platformManifestFreshness?.applicable === false) {
+      await evidence.append({
+        phase: 'platform-manifest-freshness',
+        status: 'not-applicable',
+        reason: platformManifestFreshness.reason,
+      });
+    } else {
+      await evidence.append({
+        phase: 'platform-manifest-freshness',
+        status: 'completed',
+        durationMs: platformManifestFreshness?.durationMs ?? null,
+      });
+    }
+
     await evidence.append({ phase: 'self-bootstrap-facts', status: 'started' });
     const selfBootstrapFactsFn = options.selfBootstrapFactsFn ?? assertSelfBootstrapFacts;
     let selfBootstrapFacts;
@@ -3274,6 +3432,17 @@ export async function prepareRelease(options) {
       });
     }
 
+    // R93-01: optional ephemeral public-surface check immediately before the
+    // first hook. Its staging and closure receipt never enter the plan.
+    await runPreHookPublicSurfaceGate({
+      config,
+      root: realRoot,
+      resolvedVersions,
+      evidence,
+      skipDeclaredHooks,
+      workflow,
+    });
+
     // --- Step 3: Run declared hooks ---
     let hookRecords = [];
     if (skipDeclaredHooks) {