release-skill 0.6.2 → 0.7.0

package/src/core/run.mjs

@@ -12,7 +12,7 @@
  * @module core/run
  */
 
-import { lstat, mkdir, readFile } from 'node:fs/promises';
+import { lstat, mkdir, readFile, stat } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import { dirname, join, resolve, basename, relative, isAbsolute } from 'node:path';
 import Ajv from 'ajv';
@@ -120,22 +120,107 @@ export function validateRun(run, options = {}) {
   }
 }
 
+/**
+ * Resolve a run path that may point at a run DIRECTORY (O6, 2026-08-18
+ * release-cycle investigation §3.2): verify `--run` ergonomically accepts a
+ * run directory and binds its `release-run.json`; a regular file input is
+ * returned unchanged so every existing file-path caller keeps its exact
+ * behaviour (compat).
+ *
+ * Fail-closed rules for the directory form:
+ * - a symlinked directory input is rejected (never silently dereferenced);
+ * - a directory without `release-run.json` names the expected file.
+ * A missing path is returned unchanged so the legacy readFile error surfaces.
+ *
+ * @param {string} runPath - Run file or run directory path.
+ * @returns {Promise<string>} The resolved run FILE path.
+ * @throws {ReleaseError} GATE_FAILED for symlinked or release-run.json-less
+ *   directory inputs.
+ */
+export async function resolveRunPath(runPath) {
+  let stats;
+  try {
+    stats = await lstat(runPath);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return runPath; // legacy readFile error path
+    throw new ReleaseError(
+      GATE_FAILED,
+      `cannot inspect release run path: ${err.message}`,
+      { runPath, cause: err.code },
+    );
+  }
+
+  if (stats.isFile()) return runPath; // unchanged file behaviour (compat)
+
+  if (stats.isSymbolicLink()) {
+    // A symlink that ultimately points at a directory would otherwise surface
+    // a raw EISDIR; resolve the target type and fail closed for directories.
+    let targetStats;
+    try {
+      targetStats = await stat(runPath);
+    } catch (err) {
+      if (err?.code === 'ENOENT') return runPath; // dangling: legacy error
+      throw new ReleaseError(
+        GATE_FAILED,
+        `cannot inspect release run path: ${err.message}`,
+        { runPath, cause: err.code },
+      );
+    }
+    if (targetStats.isDirectory()) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        'release run path is a symlinked directory; pass the run file (release-run.json) or the real run directory',
+        { runPath },
+      );
+    }
+    return runPath; // symlinked FILE keeps the legacy readFile behaviour
+  }
+
+  if (stats.isDirectory()) {
+    const candidate = join(runPath, 'release-run.json');
+    try {
+      const candidateStats = await lstat(candidate);
+      if (!candidateStats.isFile()) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `release run directory does not contain a regular release-run.json: ${runPath}`,
+          { runPath, expected: 'release-run.json' },
+        );
+      }
+    } catch (err) {
+      if (err instanceof ReleaseError) throw err;
+      throw new ReleaseError(
+        GATE_FAILED,
+        `release run directory must contain release-run.json: ${err.message}`,
+        { runPath, expected: 'release-run.json', cause: err.code },
+      );
+    }
+    return candidate;
+  }
+
+  return runPath; // anything else keeps the legacy readFile error path
+}
+
 /**
  * Load, parse, and validate a run file from disk.
  *
- * @param {string} runPath - Absolute path to the run file.
+ * Accepts either the run file itself or its containing run directory (O6);
+ * a directory input resolves to `<dir>/release-run.json` via resolveRunPath.
+ *
+ * @param {string} runPath - Absolute path to the run file or run directory.
  * @returns {Promise<Object>} The validated run object.
  * @throws {ReleaseError} GATE_FAILED if the file cannot be read, parsed, or validated.
  */
 export async function loadRun(runPath, options = {}) {
+  const resolvedRunPath = await resolveRunPath(runPath);
   let raw;
   try {
-    raw = await readFile(runPath, 'utf8');
+    raw = await readFile(resolvedRunPath, 'utf8');
   } catch (err) {
     throw new ReleaseError(
       GATE_FAILED,
       `cannot read release run: ${err.message}`,
-      { runPath, cause: err.code },
+      { runPath: resolvedRunPath, cause: err.code },
     );
   }
 
@@ -146,13 +231,13 @@ export async function loadRun(runPath, options = {}) {
     throw new ReleaseError(
       GATE_FAILED,
       `release run is not valid JSON: ${err.message}`,
-      { runPath },
+      { runPath: resolvedRunPath },
     );
   }
 
   validateRun(run, options);
   if (options.authorityPlanPath) {
-    assertImmutableRunAuthority(runPath, options.authorityPlanPath, run);
+    assertImmutableRunAuthority(resolvedRunPath, options.authorityPlanPath, run);
   }
   return run;
 }

package/src/producers/build-adapters.mjs

@@ -394,8 +394,16 @@ function renderSkillForPlatform(content, platformName) {
 /**
  * Collect binary file paths from a source directory recursively.
  * Returns array of relative paths.
+ *
+ * `excludedTopDirs` names top-level directories that are skipped entirely.
+ * It only exists for subtrees that are already excluded from the shipped
+ * output (see the native/safe-write build/ exclusion below): their contents
+ * are never read and never shipped, so descending into them would only let
+ * transient, regeneratable artifacts (node-gyp creates a
+ * build/node_gyp_bins/python3 symlink while a rebuild is running) fail the
+ * collection without protecting any shipped byte.
  */
-async function collectBinaryFiles(baseDir, physicalRoot, relPrefix = '') {
+async function collectBinaryFiles(baseDir, physicalRoot, relPrefix = '', excludedTopDirs) {
   const results = [];
   const physicalDir = await assertTrustedDirectory(
     baseDir,
@@ -409,6 +417,7 @@ async function collectBinaryFiles(baseDir, physicalRoot, relPrefix = '') {
       throw new Error(`SECURITY: symlink in resource tree: ${relPath}`);
     }
     if (entry.isDirectory()) {
+      if (relPrefix === '' && excludedTopDirs?.has(entry.name)) continue;
       results.push(...await collectBinaryFiles(join(physicalDir, entry.name), physicalRoot, relPath));
     } else if (entry.isFile()) {
       results.push({ relPath, sourcePath: join(physicalDir, entry.name) });
@@ -495,23 +504,24 @@ async function generateAdapterFiles(platform, skills, templateJson, root, market
   // Copy bin/ entry point and bundle (text files). The self-contained
   // bundle ships runtime sidecars next to it (JSON resources read via
   // new URL(<rel>, import.meta.url) by inlined Foundation modules, e.g.
-  // error-codes.json); enumerate the directory so every sidecar is
-  // replicated deterministically. The source CLI (release-skill-cli.mjs)
-  // is never shipped into adapters. The wrapper and the bundle are
-  // required entries: a missing one fails closed before any write.
-  const binFiles = (await readdir(join(root, 'bin')))
-    .filter((name) => name !== 'release-skill-cli.mjs')
-    .sort();
+  // error-codes.json; since F-06/T6 the inlined Engineering Kit also
+  // carries license-text sidecars under bin/license-texts/); enumerate
+  // the directory recursively so every sidecar is replicated
+  // deterministically. The source CLI (release-skill-cli.mjs) is never
+  // shipped into adapters. The wrapper and the bundle are required
+  // entries: a missing one fails closed before any write.
+  const binFileEntries = await collectBinaryFiles(join(root, 'bin'), root);
+  const binRelPaths = binFileEntries.map(({ relPath }) => relPath);
   for (const required of ['release-skill.mjs', 'release-skill.bundle.mjs']) {
-    if (!binFiles.includes(required)) {
+    if (!binRelPaths.includes(required)) {
       throw new Error(`SECURITY: required bundle entry is missing: bin/${required}`);
     }
   }
-  for (const name of binFiles) {
-    const srcPath = join(root, 'bin', name);
-    const content = await readTrustedFile(srcPath, root, `bin/${name}`);
+  for (const { relPath: rel, sourcePath } of binFileEntries) {
+    if (rel === 'release-skill-cli.mjs') continue;
+    const content = await readTrustedFile(sourcePath, root, `bin/${rel}`);
     files.push({
-      relPath: join('bin', name),
+      relPath: join('bin', rel),
       content,
       isBinary: false,
     });
@@ -537,8 +547,12 @@ async function generateAdapterFiles(platform, skills, templateJson, root, market
   // Copy native/safe-write/ directory (prebuilds.json, prebuilds/, src/).
   // Exclude build/ — it contains platform-specific build artifacts that are
   // regenerated by node-gyp and should not be in the published adapter.
+  // Collection never descends into build/: it is output-excluded anyway, and
+  // a concurrent node-gyp rebuild transiently places symlinked helper bins
+  // there (node_gyp_bins/python3) that must not fail the derived-artifact
+  // gates.
   const nativeBase = join(root, 'native', 'safe-write');
-  const nativeFiles = await collectBinaryFiles(nativeBase, root);
+  const nativeFiles = await collectBinaryFiles(nativeBase, root, '', new Set(['build']));
   if (!nativeFiles.some(({ relPath }) => relPath === 'prebuilds.json')) {
     throw new Error('SECURITY: required native resource is missing: native/safe-write/prebuilds.json');
   }