release-skill 0.1.1

package/src/core/errors.mjs

@@ -0,0 +1,113 @@
+// Stable error codes and exit codes for the release-skill system.
+// Error codes are grouped by phase; each maps to a unique stable exit code.
+
+/** @type {Readonly<Record<string, number>>} */
+const EXIT_CODE_MAP = Object.freeze({
+  CONFIG_INVALID: 10,
+  BASELINE_CHANGED: 11,
+  DIRTY_SCOPE_CONFLICT: 12,
+  GATE_FAILED: 13,
+  AUTH_MISSING: 14,
+  REMOTE_CONFLICT: 15,
+  HOOK_TIMEOUT: 16,
+  PARTIAL_RELEASE: 17,
+  POST_PUBLISH_VERIFY_FAILED: 18,
+  INVALID_STATE_TRANSITION: 19,
+  PLAN_DIGEST_MISMATCH: 20,
+  SECRET_DETECTED: 21,
+  PUBLIC_PATH_FORBIDDEN: 22,
+  STALE_BUILD_ARTIFACT: 23,
+  MISSING_PARAMETERS: 24,
+  PUBLIC_FILE_MISSING: 25,
+  SNAPSHOT_FIDELITY_FAILED: 26,
+  FORBIDDEN_CONTENT_DETECTED: 27,
+  PATH_UNSAFE: 28,
+  STRUCTURE_INVALID: 29,
+  LOCK_MIGRATION_REQUIRED: 30,
+  ARTIFACT_POLICY_INVALID: 31,
+  BASE_UNAVAILABLE: 32,
+  PRODUCER_NONDETERMINISTIC: 33,
+  PRODUCER_SCOPE_VIOLATION: 34,
+  ADOPTION_AMBIGUOUS: 35,
+  PLAN_STALE: 36,
+  SENSITIVE_CONFLICT: 37,
+  TRANSACTION_INCOMPLETE: 38,
+  SAFE_WRITE_UNAVAILABLE: 39,
+});
+
+// ---- Error code constants ----
+
+export const CONFIG_INVALID = 'CONFIG_INVALID';
+export const BASELINE_CHANGED = 'BASELINE_CHANGED';
+export const DIRTY_SCOPE_CONFLICT = 'DIRTY_SCOPE_CONFLICT';
+export const GATE_FAILED = 'GATE_FAILED';
+export const AUTH_MISSING = 'AUTH_MISSING';
+export const REMOTE_CONFLICT = 'REMOTE_CONFLICT';
+export const HOOK_TIMEOUT = 'HOOK_TIMEOUT';
+export const PARTIAL_RELEASE = 'PARTIAL_RELEASE';
+export const POST_PUBLISH_VERIFY_FAILED = 'POST_PUBLISH_VERIFY_FAILED';
+export const INVALID_STATE_TRANSITION = 'INVALID_STATE_TRANSITION';
+export const PLAN_DIGEST_MISMATCH = 'PLAN_DIGEST_MISMATCH';
+export const SECRET_DETECTED = 'SECRET_DETECTED';
+export const PUBLIC_PATH_FORBIDDEN = 'PUBLIC_PATH_FORBIDDEN';
+export const STALE_BUILD_ARTIFACT = 'STALE_BUILD_ARTIFACT';
+export const MISSING_PARAMETERS = 'MISSING_PARAMETERS';
+export const PUBLIC_FILE_MISSING = 'PUBLIC_FILE_MISSING';
+export const SNAPSHOT_FIDELITY_FAILED = 'SNAPSHOT_FIDELITY_FAILED';
+export const FORBIDDEN_CONTENT_DETECTED = 'FORBIDDEN_CONTENT_DETECTED';
+export const PATH_UNSAFE = 'PATH_UNSAFE';
+export const STRUCTURE_INVALID = 'STRUCTURE_INVALID';
+export const LOCK_MIGRATION_REQUIRED = 'LOCK_MIGRATION_REQUIRED';
+export const ARTIFACT_POLICY_INVALID = 'ARTIFACT_POLICY_INVALID';
+export const BASE_UNAVAILABLE = 'BASE_UNAVAILABLE';
+export const PRODUCER_NONDETERMINISTIC = 'PRODUCER_NONDETERMINISTIC';
+export const PRODUCER_SCOPE_VIOLATION = 'PRODUCER_SCOPE_VIOLATION';
+export const ADOPTION_AMBIGUOUS = 'ADOPTION_AMBIGUOUS';
+export const PLAN_STALE = 'PLAN_STALE';
+export const SENSITIVE_CONFLICT = 'SENSITIVE_CONFLICT';
+export const TRANSACTION_INCOMPLETE = 'TRANSACTION_INCOMPLETE';
+export const SAFE_WRITE_UNAVAILABLE = 'SAFE_WRITE_UNAVAILABLE';
+
+/**
+ * Typed error for release-skill operations.
+ *
+ * @param {string} code   One of the exported error-code constants.
+ * @param {string} message  Human-readable description.
+ * @param {Record<string, unknown>} [details]  Machine-readable context (must not contain secrets).
+ * @param {number} [exitCode]  Override exit code; defaults to the stable mapping for `code`.
+ */
+export class ReleaseError extends Error {
+  constructor(code, message, details = {}, exitCode) {
+    super(message);
+    this.name = 'ReleaseError';
+    this.code = code;
+    this.details = details;
+    this.exitCode = exitCode ?? EXIT_CODE_MAP[code] ?? 1;
+
+    // Maintain proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ReleaseError);
+    }
+  }
+
+  /**
+   * Serialise the error to a plain JSON-safe object.
+   * Intentionally omits the stack trace and any raw secret values.
+   *
+   * @returns {{ code: string, message: string, details: Record<string, unknown>, exitCode: number }}
+   */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      exitCode: this.exitCode,
+    };
+  }
+}
+
+/** All known error codes as a frozen array. */
+export const ALL_ERROR_CODES = Object.freeze(Object.keys(EXIT_CODE_MAP));
+
+/** The stable exit-code map, keyed by error code. */
+export { EXIT_CODE_MAP };

package/src/core/evidence.mjs

@@ -0,0 +1,167 @@
+/**
+ * Structured evidence writer for release-skill.
+ *
+ * Creates append-only JSONL evidence streams with automatic redaction
+ * of sensitive keys and known token/credential prefixes.
+ *
+ * @module evidence
+ */
+
+import { open, mkdir, writeFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+
+/** Schema version for evidence events. */
+const SCHEMA_VERSION = 1;
+
+/**
+ * Key-name pattern that indicates a sensitive value requiring redaction.
+ * Matches: token, secret, password, authorization, cookie (case-insensitive).
+ */
+const SENSITIVE_KEY_PATTERN = /token|secret|password|authorization|cookie/i;
+
+/**
+ * Known credential prefixes. Order matters for longest-prefix-first matching.
+ * Each entry maps a prefix string to its display label.
+ */
+const CREDENTIAL_PREFIXES = [
+  { prefix: 'github_pat_', label: 'github_pat_' },
+  { prefix: 'ghp_',       label: 'ghp_' },
+  { prefix: 'npm_',       label: 'npm_' },
+  { prefix: 'AKIA',       label: 'AKIA' },
+];
+
+const REDACTED = '[REDACTED]';
+
+/**
+ * Recursively redact sensitive values in an object.
+ *
+ * Redaction rules:
+ * 1. If a key name matches `SENSITIVE_KEY_PATTERN`, its value is replaced
+ *    with `[REDACTED]`.
+ * 2. If a string value starts with a known credential prefix, it is replaced
+ *    with `[REDACTED:<PREFIX>]`.
+ *
+ * @param {*} obj - The value to redact (object, array, string, or primitive).
+ * @returns {*} A new value with sensitive data redacted.
+ */
+export function redact(obj) {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => redact(item));
+  }
+
+  if (typeof obj === 'object') {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if (SENSITIVE_KEY_PATTERN.test(key)) {
+        result[key] = REDACTED;
+      } else {
+        result[key] = redact(value);
+      }
+    }
+    return result;
+  }
+
+  if (typeof obj === 'string') {
+    for (const { prefix, label } of CREDENTIAL_PREFIXES) {
+      if (obj.startsWith(prefix)) {
+        return `[REDACTED:${label}]`;
+      }
+    }
+  }
+
+  return obj;
+}
+
+/**
+ * Create an evidence writer that appends structured JSONL events and
+ * produces a summary JSON file.
+ *
+ * @param {Object} options
+ * @param {string} options.runDir - Absolute path to the run directory. The
+ *   directory name (last segment) is used as the `runId`.
+ * @param {string} options.command - The top-level command being executed
+ *   (e.g. "prepare", "publish").
+ * @param {() => string} [options.clock] - Optional clock function returning
+ *   an ISO-8601 timestamp string. Defaults to `() => new Date().toISOString()`.
+ * @returns {{ append: (event: Object) => Promise<void>, finish: (summary: Object) => Promise<void> }}
+ */
+export function createEvidenceWriter({ runDir, command, clock }) {
+  const clockFn = typeof clock === 'function' ? clock : () => new Date().toISOString();
+  const runId = basename(runDir);
+  const evidencePath = `${runDir}/evidence.jsonl`;
+  const summaryPath = `${runDir}/summary.json`;
+
+  let sequence = 0;
+  let handle = null;
+
+  /**
+   * Lazily open the evidence file for appending.
+   * Creates the run directory if it does not exist.
+   */
+  async function ensureHandle() {
+    if (handle === null) {
+      await mkdir(runDir, { recursive: true });
+      handle = await open(evidencePath, 'a');
+    }
+  }
+
+  /**
+   * Append a single event to the evidence JSONL stream.
+   *
+   * The event is enriched with automatic metadata:
+   * - `schemaVersion`: always 1
+   * - `runId`: extracted from the run directory name
+   * - `sequence`: auto-incrementing integer starting at 0
+   * - `timestamp`: ISO-8601 string from the clock
+   * - `command`: the command passed at creation time
+   *
+   * The entire event object is redacted before writing.
+   *
+   * @param {Object} event - The event data. Must include `phase` and `status`;
+   *   may include `error` and any other fields.
+   */
+  async function append(event) {
+    await ensureHandle();
+
+    const enriched = {
+      schemaVersion: SCHEMA_VERSION,
+      runId,
+      sequence,
+      timestamp: clockFn(),
+      command,
+      ...event,
+    };
+
+    sequence += 1;
+
+    const redacted = redact(enriched);
+    const line = JSON.stringify(redacted);
+
+    await handle.write(`${line}\n`, null, 'utf8');
+  }
+
+  /**
+   * Write the final summary file and close the evidence stream.
+   *
+   * The summary is redacted before writing.
+   *
+   * @param {Object} summary - The run summary object.
+   */
+  async function finish(summary) {
+    await ensureHandle();
+
+    const redacted = redact(summary);
+    await writeFile(summaryPath, JSON.stringify(redacted, null, 2), 'utf8');
+
+    if (handle !== null) {
+      await handle.close();
+      handle = null;
+    }
+  }
+
+  return { append, finish };
+}

package/src/core/hooks.mjs

@@ -0,0 +1,241 @@
+/**
+ * Secure hook execution for the release-skill system.
+ *
+ * Design constraints:
+ * - Uses `execFile` exclusively; never `exec` or `shell: true`.
+ * - Resolves cwd through `realpath` and rejects any path that escapes root.
+ * - Builds a minimal environment: platform-required vars plus only those
+ *   explicitly listed in `envAllowlist` that exist in `context.env`.
+ * - Kills the child process on timeout and returns `HOOK_TIMEOUT`.
+ * - Never leaks unallowlisted environment variables to the child process.
+ *
+ * @module hooks
+ */
+
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolve, relative, isAbsolute } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { ReleaseError } from './errors.mjs';
+
+const execFileAsync = promisify(execFileCb);
+
+// ---------------------------------------------------------------------------
+// Platform-required environment variables
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimum environment variables needed for child processes.
+ * PATH is always included; HOME/USER are needed for temporary directories and
+ * user detection; LANG/LC_* support locale on POSIX; SystemRoot/COMSPEC/PATHEXT
+ * are required on Windows.
+ */
+const PLATFORM_REQUIRED_VARS = (() => {
+  const posix = ['PATH', 'HOME', 'USER', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM'];
+  const win32 = ['PATH', 'HOME', 'USER', 'SystemRoot', 'SYSTEMROOT', 'COMSPEC', 'PATHEXT', 'TEMP', 'TMP'];
+  return new Set(process.platform === 'win32' ? win32 : posix);
+})();
+
+/** Pattern that every envAllowlist key must satisfy. */
+const ENV_KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate the shape of a hook descriptor against the project contract.
+ *
+ * @param {unknown} hook
+ * @throws {ReleaseError} INVALID_HOOK on any contract violation.
+ */
+function validateHook(hook) {
+  if (!hook || typeof hook !== 'object' || Array.isArray(hook)) {
+    throw new ReleaseError('INVALID_HOOK', 'hook must be a non-null object');
+  }
+
+  const { command, cwd, timeoutMs, envAllowlist } = hook;
+
+  // command: required, non-empty array of strings
+  if (!Array.isArray(command) || command.length === 0) {
+    throw new ReleaseError('INVALID_HOOK', 'hook.command must be a non-empty array');
+  }
+  for (const c of command) {
+    if (typeof c !== 'string') {
+      throw new ReleaseError('INVALID_HOOK', 'every element of hook.command must be a string');
+    }
+  }
+
+  // cwd: optional string
+  if (cwd !== undefined && typeof cwd !== 'string') {
+    throw new ReleaseError('INVALID_HOOK', 'hook.cwd must be a string when provided');
+  }
+
+  // timeoutMs: optional positive integer (minimum 1 to avoid accidental zero)
+  if (timeoutMs !== undefined) {
+    if (typeof timeoutMs !== 'number' || !Number.isInteger(timeoutMs) || timeoutMs < 1) {
+      throw new ReleaseError('INVALID_HOOK', 'hook.timeoutMs must be a positive integer');
+    }
+  }
+
+  // envAllowlist: optional array of uppercase key names
+  if (envAllowlist !== undefined) {
+    if (!Array.isArray(envAllowlist)) {
+      throw new ReleaseError('INVALID_HOOK', 'hook.envAllowlist must be an array');
+    }
+    for (const key of envAllowlist) {
+      if (typeof key !== 'string' || !ENV_KEY_PATTERN.test(key)) {
+        throw new ReleaseError(
+          'INVALID_HOOK',
+          `hook.envAllowlist key "${key}" must match /^[A-Z_][A-Z0-9_]*$/`,
+        );
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Environment building
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a filtered environment for a child process.
+ *
+ * Included keys:
+ * 1. Platform-required vars (from `process.env`).
+ * 2. Allowlisted vars (from `context.env` only).
+ *
+ * Everything else is stripped.
+ *
+ * @param {string[]} envAllowlist - Keys to forward from context.env.
+ * @param {Record<string, string>} [contextEnv] - Caller-provided env map.
+ * @returns {Record<string, string>}
+ */
+function buildFilteredEnv(envAllowlist, contextEnv) {
+  const env = {};
+
+  // 1. Platform-required variables
+  for (const key of PLATFORM_REQUIRED_VARS) {
+    const val = process.env[key];
+    if (val !== undefined) {
+      env[key] = val;
+    }
+  }
+
+  // 2. Allowlisted variables from context.env
+  if (contextEnv && envAllowlist) {
+    for (const key of envAllowlist) {
+      if (key in contextEnv) {
+        env[key] = contextEnv[key];
+      }
+    }
+  }
+
+  return env;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a hook command in a controlled subprocess.
+ *
+ * @param {Object} hook
+ * @param {string[]}   hook.command       - [executable, ...args].
+ * @param {string}     [hook.cwd]         - Relative (to root) working directory.
+ * @param {number}     [hook.timeoutMs]   - Kill child after this many ms.
+ * @param {string[]}   [hook.envAllowlist] - Extra env keys to pass through.
+ *
+ * @param {Object} context
+ * @param {string} context.root           - Absolute project root.
+ * @param {Record<string, string>} [context.env] - Extra env variables.
+ *
+ * @returns {Promise<{ exitCode: number, stdout: string, stderr: string }>}
+ *
+ * @throws {ReleaseError} HOOK_TIMEOUT - when timeoutMs expires.
+ * @throws {ReleaseError} INVALID_HOOK - when hook shape is invalid or cwd escapes root.
+ */
+export async function runHook(hook, context) {
+  // --- Validate inputs ---
+  validateHook(hook);
+
+  if (!context || typeof context !== 'object' || Array.isArray(context)) {
+    throw new ReleaseError('INVALID_HOOK', 'context must be a non-null object');
+  }
+  if (typeof context.root !== 'string' || !isAbsolute(context.root)) {
+    throw new ReleaseError('INVALID_HOOK', 'context.root must be an absolute path');
+  }
+
+  const { command, cwd, timeoutMs, envAllowlist = [] } = hook;
+
+  // --- Resolve and validate cwd ---
+  const rootReal = await realpath(context.root);
+  const resolvedCwd = cwd
+    ? await realpath(resolve(rootReal, cwd))
+    : rootReal;
+
+  const rel = relative(rootReal, resolvedCwd);
+  if (rel.startsWith('..') || rel === '..') {
+    throw new ReleaseError(
+      'INVALID_HOOK',
+      `hook.cwd "${cwd}" resolves outside project root`,
+    );
+  }
+
+  // --- Build safe environment ---
+  const env = buildFilteredEnv(envAllowlist, context.env);
+
+  // --- Set up timeout ---
+  const executable = command[0];
+  const args = command.slice(1);
+
+  /** @type {AbortController | undefined} */
+  let timeoutController;
+  /** @type {NodeJS.Timeout | undefined} */
+  let timeoutHandle;
+
+  if (timeoutMs && timeoutMs > 0) {
+    timeoutController = new AbortController();
+    timeoutHandle = setTimeout(() => timeoutController.abort(), timeoutMs);
+  }
+
+  try {
+    const { stdout, stderr } = await execFileAsync(executable, args, {
+      cwd: resolvedCwd,
+      env,
+      shell: false,
+      maxBuffer: 10 * 1024 * 1024, // 10 MiB
+      signal: timeoutController?.signal,
+    });
+
+    return { exitCode: 0, stdout: stdout ?? '', stderr: stderr ?? '' };
+  } catch (err) {
+    // Two timeout indicators:
+    //   1. AbortError — direct result of AbortController.abort()
+    //   2. err.killed && err.signal === 'SIGTERM' — child was killed
+    if (err.name === 'AbortError' || (err.killed && err.signal === 'SIGTERM')) {
+      throw new ReleaseError(
+        'HOOK_TIMEOUT',
+        `hook timed out after ${timeoutMs}ms: ${executable} ${args.join(' ')}`,
+        { command, timeoutMs },
+      );
+    }
+
+    // Non-zero exit code: return the result so callers can inspect exitCode.
+    if ('stdout' in err) {
+      return {
+        exitCode: typeof err.code === 'number' ? err.code : 1,
+        stdout: err.stdout ?? '',
+        stderr: err.stderr ?? '',
+      };
+    }
+
+    // Unexpected errors bubble up.
+    throw err;
+  } finally {
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+    }
+  }
+}

package/src/core/node-version.mjs

@@ -0,0 +1,64 @@
+/**
+ * Node.js 版本解析、最低版本检查和 readiness 状态纯函数。
+ *
+ * @module core/node-version
+ */
+
+/**
+ * 解析 Node.js --version 输出（如 "v24.0.0"），返回主版本号。
+ * @param {string} versionString
+ * @returns {number|null} major version number, or null if unparseable
+ */
+export function parseNodeMajor(versionString) {
+  if (!versionString || typeof versionString !== 'string') return null;
+  const match = versionString.trim().match(/^v(\d+)\./);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+/**
+ * 判断给定的 Node.js 主版本号是否满足最低要求。
+ * @param {number|null} major
+ * @param {number} minimum
+ * @returns {boolean}
+ */
+export function meetsMinimum(major, minimum = 22) {
+  if (major == null || typeof major !== 'number') return false;
+  return major >= minimum;
+}
+
+/**
+ * 计算环境就绪状态。
+ *
+ * Required（不满足 → NOT_READY）：
+ * - Node.js >= 22
+ * - Git
+ *
+ * Optional（不影响 READY/NOT_READY）：
+ * - pnpm / npm / gh
+ *
+ * @param {object} checks - 环境检查结果（来自 performEnvironmentChecks）
+ * @param {boolean} checks.nodeAvailable - Node.js 是否可用
+ * @param {boolean} checks.nodeMeetsMinimum - Node.js 版本 >= 22
+ * @param {boolean} checks.gitAvailable - Git 是否可用
+ * @returns {{ status: 'READY'|'NOT_READY', requiredMet: boolean, missingRequired: string[] }}
+ */
+export function computeReadinessStatus(checks) {
+  const missingRequired = [];
+
+  if (!checks.nodeAvailable) {
+    missingRequired.push('node');
+  } else if (!checks.nodeMeetsMinimum) {
+    missingRequired.push('node>=22');
+  }
+
+  if (!checks.gitAvailable) {
+    missingRequired.push('git');
+  }
+
+  const requiredMet = missingRequired.length === 0;
+  return {
+    status: requiredMet ? 'READY' : 'NOT_READY',
+    requiredMet,
+    missingRequired,
+  };
+}