release-skill 0.1.9 → 0.2.0

package/src/core/hook-cache.mjs

@@ -0,0 +1,254 @@
+/**
+ * Incremental hook result cache (T3.2).
+ *
+ * A hook that opts in with `cacheable: true` and a `cacheInputs` glob list is
+ * keyed by the fingerprint of its full configuration plus the content of every
+ * file its inputs match. When the key is unchanged and the last run succeeded,
+ * prepare replays the cached outcome instead of re-executing the hook.
+ *
+ * Safety contract (see t3-2-incremental-hooks.md §4.8):
+ * - Failures are never cached. Only an `exitCode === 0` result is written; a
+ *   non-zero exit or HOOK_TIMEOUT leaves no record, so the next run re-executes.
+ * - The cache only ever skips execution. It runs AFTER the hook authorization
+ *   gate and never bypasses any GATE; hook order and failure semantics are
+ *   untouched.
+ * - Fail-closed inputs: if any declared `cacheInputs` glob matches no file, the
+ *   input set is considered a declaration error and caching aborts with
+ *   GATE_FAILED before the hook runs (no execution, no cache).
+ * - Default zero change: a hook without `cacheable: true` never touches the
+ *   cache directory at all.
+ *
+ * The cache is a pure local optimisation under `.release-skill/cache` (a
+ * registered control-plane prefix, excluded from workspaceDigest and
+ * .gitignore). Deleting it is equivalent to a cold miss for every hook.
+ *
+ * @module hook-cache
+ */
+
+import { readdir, readFile, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { canonicalJson, sha256Hex } from './digest.mjs';
+import { ReleaseError, GATE_FAILED } from './errors.mjs';
+
+/** Control-plane location of hook cache records: `.release-skill/cache/hooks`. */
+const CACHE_BASE = ['.release-skill', 'cache', 'hooks'];
+
+/** Bounded tail length stored per stream (matches prepare's evidence tails). */
+const TAIL_LENGTH = 4000;
+
+/**
+ * Directory names never walked when enumerating hook inputs. `.git` and
+ * `node_modules` are VCS/dependency internals; `.release-skill` is the control
+ * plane and MUST stay excluded so cache records never fingerprint themselves
+ * (which would destabilise every subsequent key).
+ */
+const SKIPPED_DIRS = new Set(['.git', 'node_modules', '.release-skill']);
+
+/**
+ * Translate a `cacheInputs` glob into an anchored RegExp.
+ *
+ * Supported syntax (sufficient for input declarations):
+ * - `**`  matches any run of characters, including `/` (crosses directories)
+ * - `*`   matches any run of characters except `/`
+ * - `?`   matches a single character except `/`
+ * - every other character matches literally (regex metacharacters escaped)
+ *
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+function globToRegExp(glob) {
+  let source = '';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        source += '.*';
+        i += 2;
+      } else {
+        source += '[^/]*';
+        i += 1;
+      }
+    } else if (c === '?') {
+      source += '[^/]';
+      i += 1;
+    } else {
+      source += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+      i += 1;
+    }
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/**
+ * Recursively list every regular file under `root` as a `/`-separated relative
+ * path, skipping VCS/dependency/control-plane directories and symlinks (inputs
+ * are real files; symlink handling stays deterministic by not following them).
+ *
+ * @param {string} root - Absolute project root.
+ * @returns {Promise<string[]>} Sorted relative paths.
+ */
+async function listInputFiles(root) {
+  const out = [];
+
+  async function walk(dirAbs, dirRel) {
+    let entries;
+    try {
+      entries = await readdir(dirAbs, { withFileTypes: true });
+    } catch {
+      return; // Unreadable directory: treat as no inputs there.
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (SKIPPED_DIRS.has(entry.name)) continue;
+        const rel = dirRel ? `${dirRel}/${entry.name}` : entry.name;
+        await walk(join(dirAbs, entry.name), rel);
+      } else if (entry.isFile()) {
+        out.push(dirRel ? `${dirRel}/${entry.name}` : entry.name);
+      }
+    }
+  }
+
+  await walk(root, '');
+  out.sort();
+  return out;
+}
+
+/**
+ * Compute the cache key for a cacheable hook.
+ *
+ * `cacheKey = sha256( canonicalJSON(hook config) + canonicalJSON(sorted matched
+ * files [{ path, sha256(content) }]) )`
+ *
+ * The full hook configuration (command/cwd/timeoutMs/envAllowlist/cacheInputs/
+ * cacheable) is part of the key, so any config change switches the key. Matched
+ * files are sorted by path before hashing for determinism.
+ *
+ * @param {Object} hook - A hook descriptor with a non-empty `cacheInputs`.
+ * @param {string} root - Absolute project root.
+ * @returns {Promise<{ cacheKey: string, matchedFiles: string[] }>}
+ * @throws {ReleaseError} GATE_FAILED when any declared glob matches no file.
+ */
+export async function computeHookCacheKey(hook, root) {
+  const globs = Array.isArray(hook.cacheInputs) ? hook.cacheInputs : [];
+  const matchers = globs.map((glob) => ({ glob, re: globToRegExp(glob) }));
+
+  const allFiles = await listInputFiles(root);
+  const matched = [];
+  const hitPerGlob = matchers.map(() => false);
+  for (const relPath of allFiles) {
+    let hit = false;
+    for (let i = 0; i < matchers.length; i += 1) {
+      if (matchers[i].re.test(relPath)) {
+        hitPerGlob[i] = true;
+        hit = true;
+      }
+    }
+    if (hit) matched.push(relPath);
+  }
+
+  // Fail-closed: a glob that matches nothing is a declaration error (a typo or
+  // a missing input). Refuse to cache rather than risk a false hit.
+  for (let i = 0; i < matchers.length; i += 1) {
+    if (!hitPerGlob[i]) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `hook cacheInputs glob "${matchers[i].glob}" matched no files; refusing to cache`,
+        { glob: matchers[i].glob },
+      );
+    }
+  }
+
+  matched.sort();
+  const fileEntries = [];
+  for (const relPath of matched) {
+    const content = await readFile(join(root, relPath));
+    fileEntries.push({ path: relPath, sha256: sha256Hex(content) });
+  }
+
+  const cacheKey = sha256Hex(canonicalJson(hook) + canonicalJson(fileEntries));
+  return { cacheKey, matchedFiles: matched };
+}
+
+/**
+ * Resolve the cache directory for a named hook.
+ *
+ * @param {string} root
+ * @param {string} hookName
+ * @returns {string} Absolute path to `.release-skill/cache/hooks/<hookName>`.
+ */
+export function hookCacheDir(root, hookName) {
+  return join(root, ...CACHE_BASE, hookName);
+}
+
+/**
+ * Resolve the cache record path for a hook + key.
+ *
+ * @param {string} root
+ * @param {string} hookName
+ * @param {string} cacheKey
+ * @returns {string} Absolute path to the `<cacheKey>.json` record.
+ */
+export function hookCachePath(root, hookName, cacheKey) {
+  return join(hookCacheDir(root, hookName), `${cacheKey}.json`);
+}
+
+/**
+ * Read a cached hook result. Returns the record only when it exists, its key
+ * matches, and it recorded a successful (`exitCode === 0`) run; anything else
+ * (missing, corrupt, or non-zero) is a miss.
+ *
+ * @param {string} root
+ * @param {string} hookName
+ * @param {string} cacheKey
+ * @returns {Promise<Object | null>}
+ */
+export async function readHookCache(root, hookName, cacheKey) {
+  try {
+    const raw = await readFile(hookCachePath(root, hookName, cacheKey), 'utf8');
+    const record = JSON.parse(raw);
+    if (record && record.cacheKey === cacheKey && record.exitCode === 0) {
+      return record;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write a successful hook result to the cache. Never throws: a write failure
+ * returns `{ ok: false, error }` so the caller can record a warning without
+ * aborting prepare (the cache is an optimisation, not a gate).
+ *
+ * @param {string} root
+ * @param {string} hookName
+ * @param {string} cacheKey
+ * @param {Object} result
+ * @param {number} result.exitCode - Must be 0; non-zero results are not cached.
+ * @param {string} [result.stdoutTail] - Already truncated to TAIL_LENGTH.
+ * @param {string} [result.stderrTail] - Already truncated to TAIL_LENGTH.
+ * @param {string} [result.createdAt] - ISO timestamp (defaults to now).
+ * @returns {Promise<{ ok: true } | { ok: false, error: string }>}
+ */
+export async function writeHookCache(root, hookName, cacheKey, result) {
+  // Defence in depth: a failure must never be persisted, even if a caller
+  // mistakenly passes a non-zero exit code.
+  if (!result || result.exitCode !== 0) {
+    return { ok: false, error: 'refusing to cache a non-zero exit result' };
+  }
+  try {
+    await mkdir(hookCacheDir(root, hookName), { recursive: true });
+    const record = {
+      cacheKey,
+      exitCode: 0,
+      stdoutTail: String(result.stdoutTail ?? '').slice(-TAIL_LENGTH),
+      stderrTail: String(result.stderrTail ?? '').slice(-TAIL_LENGTH),
+      createdAt: result.createdAt ?? new Date().toISOString(),
+    };
+    await writeFile(hookCachePath(root, hookName, cacheKey), `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}

package/src/core/hooks.mjs

@@ -54,7 +54,7 @@ function validateHook(hook) {
     throw new ReleaseError('INVALID_HOOK', 'hook must be a non-null object');
   }
 
-  const { command, cwd, timeoutMs, envAllowlist } = hook;
+  const { command, cwd, timeoutMs, envAllowlist, cacheable, cacheInputs } = hook;
 
   // command: required, non-empty array of strings
   if (!Array.isArray(command) || command.length === 0) {
@@ -92,6 +92,40 @@ function validateHook(hook) {
       }
     }
   }
+
+  // cacheable: optional boolean opting the hook into the incremental result
+  // cache (T3.2). Absence means the hook always runs in full (default).
+  if (cacheable !== undefined && typeof cacheable !== 'boolean') {
+    throw new ReleaseError('INVALID_HOOK', 'hook.cacheable must be a boolean when provided');
+  }
+
+  // cacheInputs: optional non-empty array of non-empty glob strings declaring
+  // the hook's full input set (used to fingerprint the cache key).
+  if (cacheInputs !== undefined) {
+    if (!Array.isArray(cacheInputs) || cacheInputs.length === 0) {
+      throw new ReleaseError(
+        'INVALID_HOOK',
+        'hook.cacheInputs must be a non-empty array of glob strings when provided',
+      );
+    }
+    for (const glob of cacheInputs) {
+      if (typeof glob !== 'string' || glob.length === 0) {
+        throw new ReleaseError(
+          'INVALID_HOOK',
+          'every element of hook.cacheInputs must be a non-empty string',
+        );
+      }
+    }
+  }
+
+  // A cacheable hook MUST declare its inputs: a cache without an input
+  // declaration is untrustworthy (any unseen change could cause a false hit).
+  if (cacheable === true && (!Array.isArray(cacheInputs) || cacheInputs.length === 0)) {
+    throw new ReleaseError(
+      'INVALID_HOOK',
+      'hook.cacheable=true requires a non-empty hook.cacheInputs',
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -146,6 +180,8 @@ function buildFilteredEnv(envAllowlist, contextEnv) {
  * @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 {boolean}    [hook.cacheable]    - Opt into the incremental result cache.
+ * @param {string[]}   [hook.cacheInputs]  - Input globs fingerprinting the cache key.
  *
  * @param {Object} context
  * @param {string} context.root           - Absolute project root.

package/src/core/observe-retry.mjs

@@ -0,0 +1,223 @@
+/**
+ * Bounded observe-with-retry for transient (PROPAGATING) remote states.
+ *
+ * After an `execute` writes to a remote system, the write may not be
+ * immediately observable: package registries have eventual consistency
+ * (e.g. `npm publish` succeeds but `npm view` cannot find the new
+ * version for tens of seconds), and transient network errors happen.
+ *
+ * This module retries ONLY read-only `observe` calls while the remote
+ * state is "information-insufficient" (missing / empty / threw). The
+ * moment a concrete observation is read back, the caller classifies it
+ * (CONSISTENT / CONFLICTING / TERMINAL_MISSING). A present-but-
+ * mismatched observation (CONFLICTING) is NEVER retried: a conflict
+ * is a real, authoritative disagreement that must fail closed and be
+ * resolved by a human. This is exactly the safety semantics required by
+ * the release-skill governance (fail-closed, observe stays read-only,
+ * no execute retry, no auto-overwrite of remote state).
+ *
+ * Callers wire this into the four observe call sites (publish executeCheckpoint
+ * and the three reconcile observation points). The retry policy is fixed and
+ * not user-configurable on purpose: it never enters the frozen plan or the
+ * approval record, so changing it cannot invalidate an approved release.
+ *
+ * @module core/observe-retry
+ */
+
+/**
+ * Default retry policy.
+ *
+ * The first observe call happens immediately; each subsequent retry waits
+ * the corresponding delay. With `maxAttempts: 5` and four delays the
+ * total worst-case retry window is ~150s (10+20+40+80). That is the
+ * cost of avoiding a manual reconcile loop (minutes of human time).
+ *
+ * @type {{ maxAttempts: number, delaysMs: ReadonlyArray<number> }}
+ */
+export const DEFAULT_OBSERVE_RETRY_POLICY = Object.freeze({
+  maxAttempts: 5,
+  delaysMs: Object.freeze([10_000, 20_000, 40_000, 80_000]),
+});
+
+/**
+ * Reduce a retry policy so its total delay window fits inside a hard
+ * timeout (e.g. a marketplace action's `timeoutMs`, valid range 30s-900s).
+ *
+ * If the policy already fits, it is returned unchanged. Otherwise delays are
+ * dropped from the end (longest first) until the remaining sum fits, and
+ * `maxAttempts` is recomputed as `delays.length + 1` (one immediate
+ * observe plus one per remaining delay). Always leaves at least one attempt.
+ *
+ * @param {{ maxAttempts: number, delaysMs: ReadonlyArray<number> }} policy
+ * @param {number|null|undefined} timeoutMs - Hard ceiling in milliseconds.
+ * @returns {{ maxAttempts: number, delaysMs: number[] }}
+ */
+export function clampPolicyToTimeout(policy, timeoutMs) {
+  if (timeoutMs == null || typeof timeoutMs !== 'number' || timeoutMs <= 0) {
+    return policy;
+  }
+  const delays = [...policy.delaysMs];
+  let total = delays.reduce((sum, ms) => sum + ms, 0);
+  // Already fits the timeout: return the SAME policy object, unchanged.
+  if (total <= timeoutMs) {
+    return policy;
+  }
+  while (delays.length > 0 && total > timeoutMs) {
+    const dropped = delays.pop();
+    const newTotal = total - dropped;
+    if (newTotal <= timeoutMs) {
+      total = newTotal;
+      break;
+    }
+    total = newTotal;
+  }
+  const maxAttempts = Math.max(1, delays.length + 1);
+  return { maxAttempts, delaysMs: delays };
+}
+
+function defaultClock() {
+  return new Date().toISOString();
+}
+
+/**
+ * Default inter-attempt delay.
+ *
+ * Test escape hatch: when `RELEASE_SKILL_OBSERVE_RETRY_NO_WAIT=1` is set,
+ * the delay resolves immediately. This ONLY skips the wall-clock wait for
+ * spawned-CLI test sandboxes (in-process tests inject a sleep instead);
+ * attempt counts, ordering, and PROPAGATING/CONFLICTING classification are
+ * unchanged, so it cannot weaken any fail-closed decision.
+ */
+function defaultSleep(ms) {
+  if (process.env.RELEASE_SKILL_OBSERVE_RETRY_NO_WAIT === '1') {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Decide whether an observe/verify result is "information-insufficient"
+ * (PROPAGATING) and therefore a candidate for retry.
+ *
+ * Returns `true` when the remote state is unknown or explicitly absent:
+ * - the call threw (no result at all)
+ * - the observation is missing or an empty object
+ * - an explicit absence marker is present (`exists:false`, `published:false`,
+ *   `installed:false`, empty commit strings)
+ *
+ * Returns `false` when a concrete observation was read back. A present
+ * observation — even if it does NOT match the expected state — is a
+ * CONFLICTING signal, not a propagation delay, and must NOT be retried.
+ *
+ * @param {{ observation?: Object|null, error?: string|null }|null} result
+ * @returns {boolean}
+ */
+export function isPropagatingMissing(result) {
+  if (result == null) return true;
+  const { observation } = result;
+  if (observation == null) return true;
+  if (Object.keys(observation).length === 0) return true;
+  if (observation.exists === false) return true;
+  if (observation.remoteCommit === '') return true;
+  if (observation.commit === '') return true;
+  if (observation.published === false) return true;
+  if (observation.installed === false) return true;
+  // NOTE: a thrown observe surfaces as `error` with a null-ish observation,
+  // which is already covered by the `observation == null` / empty checks above.
+  return false;
+}
+
+/**
+ * Retry a read-only `observe` (or `verify`, which is observe+match) while
+ * the remote state is information-insufficient.
+ *
+ * @param {Object} options
+ * @param {Function} options.observe - `(action, context) => Promise<result>`.
+ *   The result must expose `.observation` and `.error` (the `createResult`
+ *   shape). Throwing is treated as a propagating miss and retried.
+ * @param {Object} options.action - Adapter action passed through to `observe`.
+ * @param {Object} options.context - Adapter context passed through to `observe`.
+ * @param {Function} [options.isMissing] - Override for the missing check
+ *   (defaults to {@link isPropagatingMissing}).
+ * @param {Object} [options.policy] - Retry policy (defaults to
+ *   {@link DEFAULT_OBSERVE_RETRY_POLICY}).
+ * @param {Function} [options.clock] - `() => string` timestamp for evidence.
+ * @param {Function} [options.sleep] - `(ms) => Promise` delay (injected in tests).
+ * @param {Function} [options.onAttempt] - `async (info) => void` evidence hook,
+ *   called once per attempt with `{ attempt, maxAttempts, missing, delayMs,
+ *   threw, observation, error, timestamp }`.
+ * @returns {Promise<{ result: Object|null, missing: boolean, attempts: number, exhausted: boolean, threw: boolean }>}
+ *   `result` is the last raw observe/verify result (or a normalized
+ *   `{ observation: null, error }` when the final attempt threw). It is
+ *   handed back to the caller so the caller can run its own
+ *   CONSISTENT/CONFLICTING/TERMINAL_MISSING classification unchanged.
+ */
+export async function observeWithRetry({
+  observe,
+  action,
+  context,
+  isMissing = isPropagatingMissing,
+  policy = DEFAULT_OBSERVE_RETRY_POLICY,
+  clock = defaultClock,
+  sleep = defaultSleep,
+  onAttempt,
+} = {}) {
+  const delays = [...(policy.delaysMs ?? [])];
+  const maxAttempts = policy.maxAttempts ?? delays.length + 1;
+
+  let lastResult = null;
+  let lastThrew = false;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    let result;
+    let threw = false;
+    try {
+      result = await observe(action, context);
+    } catch (error) {
+      threw = true;
+      lastThrew = true;
+      result = { observation: null, error: error?.message ?? String(error) };
+    }
+    lastResult = result;
+
+    const missing = isMissing(result);
+    // The delay that will actually be applied AFTER this attempt: only when
+    // the state is still missing and a delay remains. On the final attempt
+    // (or a resolved attempt) this is 0, reported truthfully.
+    const willSleep = missing && attempt < delays.length;
+    const delayMs = willSleep ? delays[attempt] : 0;
+
+    if (onAttempt) {
+      await onAttempt({
+        attempt: attempt + 1,
+        maxAttempts,
+        missing,
+        delayMs,
+        threw,
+        observation: result?.observation ?? null,
+        error: result?.error ?? null,
+        timestamp: clock(),
+      });
+    }
+
+    // A concrete observation was read back: not a propagation delay.
+    // Return immediately so the caller can classify it (including a real
+    // CONFLICTING mismatch, which must never be retried).
+    if (!missing) {
+      return { result, missing: false, attempts: attempt + 1, exhausted: false, threw: false };
+    }
+
+    // Still missing: wait before the next attempt (unless this was the last).
+    if (willSleep) {
+      await sleep(delays[attempt]);
+    }
+  }
+
+  return {
+    result: lastResult,
+    missing: true,
+    attempts: maxAttempts,
+    exhausted: true,
+    threw: lastThrew,
+  };
+}