release-skill 0.1.3 → 0.1.5

package/src/commands/verify.mjs

@@ -669,7 +669,10 @@ export async function verifyRelease(options) {
     }
 
     // Validate plan action completeness before checkpoint mapping
-    const completenessResult = validatePlanActionCompleteness(plan);
+    // Use legacyCompatibility: old plans (pre-v0.1.5) lack
+    // parameters.timeoutMs. Verify must still pass these plans,
+    // while strict mode (prepare/approve/publish) rejects them.
+    const completenessResult = validatePlanActionCompleteness(plan, { legacyCompatibility: true });
     if (!completenessResult.passed) {
       throw new ReleaseError(
         GATE_FAILED,

package/src/core/approval.mjs

@@ -19,16 +19,14 @@ import { computePlanDigest } from './plan.mjs';
 import { sha256Hex } from './digest.mjs';
 import { readFile } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import { WORKSPACE_DIGEST_ALGORITHM } from './baseline.mjs';
+import { readTrustedPackageResource } from './trusted-resource.mjs';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const approvalSchema = JSON.parse(await readFile(
-  join(__dirname, '..', '..', 'schemas', 'approval-record.schema.json'),
-  'utf8',
-));
+const approvalSchema = JSON.parse((await readTrustedPackageResource(
+  'schemas/approval-record.schema.json',
+)).toString('utf8'));
 const approvalAjv = new Ajv({ allErrors: true, strict: false });
 addFormats(approvalAjv);
 const validateApprovalSchema = approvalAjv.compile(approvalSchema);

package/src/core/config.mjs

@@ -17,8 +17,7 @@
  */
 
 import { readFile } from 'node:fs/promises';
-import { resolve, isAbsolute, relative, normalize, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { resolve, isAbsolute, relative, normalize } from 'node:path';
 import YAML, { Alias } from 'yaml';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
@@ -26,6 +25,7 @@ import { canonicalJson, sha256Hex } from './digest.mjs';
 import { ReleaseError, CONFIG_INVALID } from './errors.mjs';
 import { canonicalPublicPath, publicPathCollisionKey } from '../snapshot/public-path.mjs';
 import { isReservedReleaseControlPath } from './baseline.mjs';
+import { readTrustedPackageResource } from './trusted-resource.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -38,19 +38,19 @@ const DEFAULT_CONFIG_REL = '.release-skill/project.yaml';
 // Load the formal release-project JSON Schema (single source of truth)
 // ---------------------------------------------------------------------------
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const FORMAL_SCHEMA_PATH = resolve(__dirname, '..', '..', 'schemas', 'release-project.schema.json');
-
 let RELEASE_PROJECT_SCHEMA;
 try {
-  const schemaRaw = await readFile(FORMAL_SCHEMA_PATH, 'utf8');
+  const schemaRaw = (await readTrustedPackageResource(
+    'schemas/release-project.schema.json',
+  )).toString('utf8');
   RELEASE_PROJECT_SCHEMA = JSON.parse(schemaRaw);
 } catch (err) {
+  if (err instanceof ReleaseError) throw err;
   // Fail closed: if the formal schema cannot be loaded, refuse to operate.
   throw new ReleaseError(
     CONFIG_INVALID,
-    `cannot load formal release-project schema: ${err.message}`,
-    { schemaPath: FORMAL_SCHEMA_PATH, cause: err.code },
+    'cannot parse formal release-project schema',
+    { resource: 'schemas/release-project.schema.json', cause: err.code ?? 'PARSE_FAILED' },
   );
 }
 

package/src/core/pkg-root.mjs

@@ -0,0 +1,22 @@
+/**
+ * Package root resolution for bundled and unbundled execution.
+ *
+ * In development (unbundled) mode, `import.meta.url` points to the source
+ * file under `src/core/`, so `../..` reaches the package root.
+ *
+ * In bundled mode, the esbuild banner defines `__bundlePkgRoot` before the
+ * module body executes, derived deterministically from the bundle's own
+ * file path. The env-var override path has been removed to prevent
+ * callers from hijacking schema/native resolution.
+ *
+ * @module core/pkg-root
+ */
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// In bundled mode, __bundlePkgRoot is set by the esbuild banner.
+// In development mode, resolve from this source file's location.
+export const PKG_ROOT = typeof __bundlePkgRoot !== 'undefined'
+  ? __bundlePkgRoot
+  : resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');

package/src/core/plan.mjs

@@ -17,19 +17,19 @@
 
 import { readFile, writeFile, rename, mkdir, open, link, unlink, lstat } from 'node:fs/promises';
 import { basename, dirname, join, resolve, parse, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import { canonicalJson, sha256Hex } from './digest.mjs';
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
+import { readTrustedPackageResource } from './trusted-resource.mjs';
 
 // ---------------------------------------------------------------------------
 // Schema loaded from the authoritative JSON file (single source of truth)
 // ---------------------------------------------------------------------------
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const SCHEMA_PATH = join(__dirname, '..', '..', 'schemas', 'release-plan.schema.json');
-const RELEASE_PLAN_SCHEMA = JSON.parse(await readFile(SCHEMA_PATH, 'utf8'));
+const RELEASE_PLAN_SCHEMA = JSON.parse((await readTrustedPackageResource(
+  'schemas/release-plan.schema.json',
+)).toString('utf8'));
 
 // ---------------------------------------------------------------------------
 // Schema validator (compiled once at module init)
@@ -312,9 +312,13 @@ const REQUIRED_ACTION_TYPES = ['push-snapshot', 'create-tag', 'github-release'];
  * (e.g. v0.0.10 must not match expected version 0.0.1).
  *
  * @param {object} plan - A validated release plan object.
+ * @param {object} [options]
+ * @param {boolean} [options.legacyCompatibility] - When true, relax
+ *   timeoutMs requirement for old plans (reconcile/verify paths).
+ *   New prepare/approve/publish must not set this flag.
  * @returns {{ passed: boolean, details: { failures: string[], expectedCount: number, actualCount: number } }}
  */
-export function validatePlanActionCompleteness(plan) {
+export function validatePlanActionCompleteness(plan, options = {}) {
   const failures = [];
 
   if (!plan || typeof plan !== 'object') {
@@ -386,6 +390,11 @@ export function validatePlanActionCompleteness(plan) {
       if (frozen.branchStrategy !== branchStrategy) {
         failures.push(`unit "${unitId}" frozenSnapshot.branchStrategy does not match productionConfig.branchStrategy`);
       }
+      if (!frozen.commitTimestamp || typeof frozen.commitTimestamp !== 'string') {
+        failures.push(`unit "${unitId}" frozenSnapshot.commitTimestamp is missing; legacy production plans without a freeze timestamp are rejected, never silently backfilled`);
+      } else if (plan.createdAt !== frozen.commitTimestamp) {
+        failures.push(`unit "${unitId}" frozenSnapshot.commitTimestamp must equal plan.createdAt`);
+      }
       if (['advance-existing-branch', 'initialize-default-branch'].includes(branchStrategy)) {
         if (unit.previousPublicBaseline?.mode !== 'bound') {
           failures.push(`unit "${unitId}" branch strategy "${branchStrategy}" requires a bound previous public baseline`);
@@ -665,6 +674,33 @@ export function validatePlanActionCompleteness(plan) {
           _checkRequired(action, 'parameters.ref', action.parameters?.ref, expectedTag, unitId, failures);
           _checkRequired(action, 'parameters.manifestDigest', action.parameters?.manifestDigest, frozen?.manifestDigest, unitId, failures);
         }
+        // timeoutMs is mandatory for all marketplace install actions.
+        // Legacy plans (pre-v0.1.5) lack this field; legacyCompatibility
+        // relaxes the check for reconcile/verify paths only, and only when
+        // the property is genuinely absent (undefined). An explicit null is
+        // NOT "absent" -- it is an invalid value and always fails closed,
+        // like strings or out-of-range numbers, even in legacyCompatibility.
+        {
+          const raw = action.parameters?.timeoutMs;
+          if (raw === undefined) {
+            if (!options.legacyCompatibility) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs is missing, expected a valid timeout (30000-900000)`,
+              );
+            }
+          } else {
+            // Field is present -- always validate range/type, even in legacy mode
+            if (typeof raw !== 'number' || !Number.isFinite(raw) || !Number.isInteger(raw)) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs must be a finite integer, got: ${JSON.stringify(raw)}`,
+              );
+            } else if (raw < 30000 || raw > 900000) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs must be between 30000 and 900000, got: ${raw}`,
+              );
+            }
+          }
+        }
 
         // Expected checks
         _checkRequired(action, 'expected.installed', action.expected?.installed, true, unitId, failures);
@@ -741,6 +777,33 @@ export function validatePlanActionCompleteness(plan) {
           _checkRequired(action, 'parameters.ref', action.parameters?.ref, expectedTag, unitId, failures);
           _checkRequired(action, 'parameters.manifestDigest', action.parameters?.manifestDigest, frozen?.manifestDigest, unitId, failures);
         }
+        // timeoutMs is mandatory for all marketplace install actions.
+        // Legacy plans (pre-v0.1.5) lack this field; legacyCompatibility
+        // relaxes the check for reconcile/verify paths only, and only when
+        // the property is genuinely absent (undefined). An explicit null is
+        // NOT "absent" -- it is an invalid value and always fails closed,
+        // like strings or out-of-range numbers, even in legacyCompatibility.
+        {
+          const raw = action.parameters?.timeoutMs;
+          if (raw === undefined) {
+            if (!options.legacyCompatibility) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs is missing, expected a valid timeout (30000-900000)`,
+              );
+            }
+          } else {
+            // Field is present -- always validate range/type, even in legacy mode
+            if (typeof raw !== 'number' || !Number.isFinite(raw) || !Number.isInteger(raw)) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs must be a finite integer, got: ${JSON.stringify(raw)}`,
+              );
+            } else if (raw < 30000 || raw > 900000) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs must be between 30000 and 900000, got: ${raw}`,
+              );
+            }
+          }
+        }
 
         // Expected checks
         _checkRequired(action, 'expected.installed', action.expected?.installed, true, unitId, failures);

package/src/core/run.mjs

@@ -15,17 +15,17 @@
 import { link, lstat, mkdir, open, readFile, unlink } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import { dirname, join, resolve, basename, relative, isAbsolute } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 
 import { assertImmutablePlanAuthority, computePlanDigest } from './plan.mjs';
 import { sha256Hex } from './digest.mjs';
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
+import { readTrustedPackageResource } from './trusted-resource.mjs';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const RUN_SCHEMA_PATH = join(__dirname, '..', '..', 'schemas', 'release-run.schema.json');
-const RELEASE_RUN_SCHEMA = JSON.parse(await readFile(RUN_SCHEMA_PATH, 'utf8'));
+const RELEASE_RUN_SCHEMA = JSON.parse((await readTrustedPackageResource(
+  'schemas/release-run.schema.json',
+)).toString('utf8'));
 
 // ---------------------------------------------------------------------------
 // Default runDir resolution

package/src/core/trusted-resource.mjs

@@ -0,0 +1,96 @@
+/**
+ * Read package-owned runtime resources without following untrusted links.
+ * Installed adapters use this for schemas and native manifests.
+ */
+
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { CONFIG_INVALID, ReleaseError } from './errors.mjs';
+import { PKG_ROOT } from './pkg-root.mjs';
+
+function fail(code, resource, reason) {
+  throw new ReleaseError(
+    code,
+    `package resource is untrusted or unavailable: ${resource}`,
+    { resource, reason },
+  );
+}
+
+function lexicalPath(resource, code) {
+  if (typeof resource !== 'string' || resource.length === 0 || isAbsolute(resource)) {
+    fail(code, String(resource), 'INVALID_RESOURCE_PATH');
+  }
+  const path = resolve(PKG_ROOT, resource);
+  const rel = relative(PKG_ROOT, path);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    fail(code, resource, 'RESOURCE_PATH_ESCAPE');
+  }
+  return path;
+}
+
+function assertStat(stat, resource, code) {
+  if (stat.isSymbolicLink()) fail(code, resource, 'SYMLINK');
+  if (!stat.isFile()) fail(code, resource, 'NOT_REGULAR_FILE');
+  if (stat.nlink !== 1) fail(code, resource, 'UNEXPECTED_HARDLINK_COUNT');
+}
+
+function assertPhysicalContainment(physicalRoot, physicalPath, resource, code) {
+  const rel = relative(physicalRoot, physicalPath);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    fail(code, resource, 'PHYSICAL_PATH_ESCAPE');
+  }
+}
+
+export function readTrustedPackageResourceSync(resource, { code = CONFIG_INVALID } = {}) {
+  const path = lexicalPath(resource, code);
+  let stat;
+  try {
+    stat = lstatSync(path);
+  } catch {
+    fail(code, resource, 'MISSING');
+  }
+  assertStat(stat, resource, code);
+
+  let physicalRoot;
+  let physicalPath;
+  try {
+    physicalRoot = realpathSync(PKG_ROOT);
+    physicalPath = realpathSync(path);
+  } catch {
+    fail(code, resource, 'REALPATH_FAILED');
+  }
+  assertPhysicalContainment(physicalRoot, physicalPath, resource, code);
+  try {
+    return readFileSync(physicalPath);
+  } catch {
+    fail(code, resource, 'READ_FAILED');
+  }
+}
+
+export async function readTrustedPackageResource(resource, { code = CONFIG_INVALID } = {}) {
+  const path = lexicalPath(resource, code);
+  let stat;
+  try {
+    stat = await lstat(path);
+  } catch {
+    fail(code, resource, 'MISSING');
+  }
+  assertStat(stat, resource, code);
+
+  let physicalRoot;
+  let physicalPath;
+  try {
+    physicalRoot = await realpath(PKG_ROOT);
+    physicalPath = await realpath(path);
+  } catch {
+    fail(code, resource, 'REALPATH_FAILED');
+  }
+  assertPhysicalContainment(physicalRoot, physicalPath, resource, code);
+  try {
+    return await readFile(physicalPath);
+  } catch {
+    fail(code, resource, 'READ_FAILED');
+  }
+}

package/src/docs/version-gate.mjs

@@ -0,0 +1,164 @@
+/**
+ * Release docs version consistency gate.
+ *
+ * README, INSTALL, and CHANGELOG are human-maintained content. A release
+ * freezes only the current truth: prepare/publish never rewrite or refresh
+ * these docs. Maintainers must update the docs first, then prepare, review,
+ * and approve. This gate makes version drift fail closed before release:
+ *
+ *   - the English README, Chinese README, English INSTALL, and Chinese
+ *     INSTALL each carry a machine-readable current release version marker
+ *     whose value equals package.json.version exactly;
+ *   - CHANGELOG.md carries a formal `## [<version>]` heading for the current
+ *     package version (a body mention or an internal candidate note does not
+ *     substitute for the heading).
+ *
+ * The gate is a pure read-only check; it never edits files. It is wired into
+ * the package test suite so `pnpm test:release` blocks a prepare when docs
+ * have drifted from the package version.
+ *
+ * @module src/docs/version-gate
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** The machine-readable marker tag carried by every public doc file. */
+export const RELEASE_VERSION_MARKER_TAG = 'release-skill:release-version';
+
+/**
+ * Marker pattern. The value is captured; e.g.
+ *   <!-- release-skill:release-version: 0.1.4 -->
+ * Global: every occurrence is validated so a stale duplicate cannot hide.
+ */
+const MARKER_PATTERN = new RegExp(
+  `<!--\\s*${RELEASE_VERSION_MARKER_TAG}:\\s*([^\\s>]+)\\s*-->`,
+  'g',
+);
+
+/** Public docs that must carry the marker, in both languages. */
+export const VERSIONED_DOC_FILES = [
+  'README.md',
+  'README.zh-CN.md',
+  'INSTALL.md',
+  'INSTALL.zh-CN.md',
+];
+
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/**
+ * Escape a string for literal use inside a RegExp.
+ * @param {string} text
+ * @returns {string}
+ */
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Extract every release-version marker value from doc content.
+ * @param {string} content
+ * @returns {string[]}
+ */
+export function extractReleaseVersionMarkers(content) {
+  return [...String(content ?? '').matchAll(MARKER_PATTERN)].map((match) => match[1]);
+}
+
+/**
+ * Render the canonical marker line for a version.
+ * @param {string} version
+ * @returns {string}
+ */
+export function renderReleaseVersionMarker(version) {
+  return `<!-- ${RELEASE_VERSION_MARKER_TAG}: ${version} -->`;
+}
+
+/**
+ * Validate that the human-maintained release docs in `packageDir` agree with
+ * package.json.version. Read-only; never writes.
+ *
+ * @param {object} options
+ * @param {string} options.packageDir Directory containing package.json and
+ *   the public docs.
+ * @returns {Promise<{
+ *   passed: boolean,
+ *   version: string | null,
+ *   markers: Record<string, string[]>,
+ *   changelogHeading: boolean,
+ *   failures: string[],
+ * }>}
+ */
+export async function validateDocsVersionConsistency({ packageDir }) {
+  const failures = [];
+  const markers = {};
+  let changelogHeading = false;
+  let version = null;
+
+  try {
+    const pkg = JSON.parse(await readFile(join(packageDir, 'package.json'), 'utf8'));
+    if (typeof pkg.version === 'string' && pkg.version.length > 0) {
+      version = pkg.version;
+    }
+  } catch (error) {
+    failures.push(`package.json: cannot read package version (${error?.code ?? error?.message ?? 'unknown error'})`);
+  }
+  if (version === null) {
+    failures.push('package.json: version is missing; docs version gate fails closed');
+  } else if (!SEMVER_PATTERN.test(version)) {
+    failures.push(`package.json: version "${version}" is not a valid semver value`);
+  }
+
+  if (version !== null) {
+    for (const file of VERSIONED_DOC_FILES) {
+      let content;
+      try {
+        content = await readFile(join(packageDir, file), 'utf8');
+      } catch {
+        failures.push(`${file}: missing; release docs must ship in both languages`);
+        continue;
+      }
+      const found = extractReleaseVersionMarkers(content);
+      markers[file] = found;
+      if (found.length === 0) {
+        failures.push(
+          `${file}: missing machine-readable release version marker "${renderReleaseVersionMarker(version)}"`,
+        );
+      }
+      for (const value of found) {
+        if (value !== version) {
+          failures.push(
+            `${file}: release version marker "${value}" does not match package version "${version}"; ` +
+            'update the docs first, then prepare, review, and approve',
+          );
+        }
+      }
+    }
+
+    let changelog;
+    try {
+      changelog = await readFile(join(packageDir, 'CHANGELOG.md'), 'utf8');
+    } catch {
+      failures.push('CHANGELOG.md: missing');
+    }
+    if (changelog !== undefined) {
+      // A formal heading starts a line: "## [0.1.4]" optionally followed by a
+      // date. A body mention ("0.1.4 was an internal candidate...") does not
+      // substitute for the heading.
+      changelogHeading = new RegExp(`^##\\s*\\[${escapeRegExp(version)}\\](?:\\s|$)`, 'm').test(changelog);
+      if (!changelogHeading) {
+        failures.push(
+          `CHANGELOG.md: missing formal "## [${version}]" heading for the current package version; ` +
+          'internal unreleased candidates may be explained in the body but cannot replace the entry',
+        );
+      }
+    }
+  }
+
+  return {
+    passed: failures.length === 0,
+    version,
+    markers,
+    changelogHeading,
+    failures,
+  };
+}