@pareto4/pp-core 1.12.0 → 1.13.0

package/pp-core/bin/lib/loop-gates.cjs

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Loop gate runner — the one owner of the generic `check.query` gate contract.
+ *
+ * Command surface: pp-tools loop run-gates <point> [--phase <N>] [--tier light|standard|heavy] [--query <q>] [--raw]
+ *
+ * Resolves the active hooks at <point> through the loop resolver (the same
+ * owner `loop render-hooks` uses, so an unreadable config refuses here too),
+ * then runs every active gate in registry order and applies the two-step gate
+ * contract execute-phase states for `execute:wave:post` / `execute:post`:
+ *
+ *   Step 1 — did the check COMMAND succeed? (`pp-tools check <query> [<phase>]
+ *   [<check.args>…] --raw` exits 0 with a JSON object). If not: `onError: halt` halts,
+ *   `onError: skip` (or absent) warns and moves on; `block` is never read.
+ *   Step 2 — read `block`. A blocking gate (`blocking: true`) halts on
+ *   `block: true`; that halt is never bypassed by `onError`. An advisory gate
+ *   (`blocking` not true) reports `block: true` or a non-empty `message` as an
+ *   advisory and never halts. `block: false` with no message passes silently;
+ *   a blocking gate that passes WITH a message (a note) passes with an `ℹ` line.
+ *
+ * `check.args` (optional) are literal tokens the gate declaration appends after
+ * the phase — the gate's own policy, stated where the gate is declared (e.g.
+ * `--stage plan`). `--query <q>` runs only the gates whose `check.query` is `q`,
+ * so a host can run one gate in code beside a loop that handles the others.
+ *
+ * A gate this runner cannot run (no `check.query`, or a query that is not a
+ * check name) halts when it is blocking and is reported when it is advisory:
+ * a blocking gate is never passed having checked nothing.
+ *
+ * Output: the verdict JSON on stdout (`{ point, phase, halt, gates[], lines[] }`),
+ * every line of `lines` also on stderr so a host capturing `$(…)` still shows
+ * them, and exit 1 when `halt` is true. A host therefore writes
+ * `X=$(pp_run loop run-gates <point> …) || exit 1` and the halt stops it.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { output: coreOutput, error: coreError, ERROR_REASON } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const loopResolverModule = require("./loop-resolver.cjs");
+const { resolveProjectLoopHooks } = loopResolverModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderModule = require("./config-loader.cjs");
+const { unreadableConfigFiles } = configLoaderModule;
+const phase_tier_cjs_1 = require("./phase-tier.cjs");
+/** A check name as `routeCheckCommand` accepts it (dotted or hyphenated); never an option or a path. */
+const CHECK_QUERY_RE = /^[a-z0-9][a-z0-9.-]*$/i;
+/** A declared `check.args` token: a flag or a plain word — never a path, a quote or a shell metacharacter. */
+const CHECK_ARG_RE = /^(?:--[a-z][a-z0-9-]*|[a-z0-9][a-z0-9._-]*)$/i;
+const CHECK_ARGS_MAX = 8;
+const CHECK_TIMEOUT_MS = 300_000;
+/** A check's operator message is relayed whole (line breaks kept), up to this many characters. */
+const MESSAGE_CAP = 16_000;
+function boundMessage(v) {
+    if (typeof v !== 'string')
+        return null;
+    const flat = v.replace(/\r\n?/g, '\n').replace(/[\u0000-\u0008\u000B-\u001F\u007F]+/g, ' ').trim();
+    if (flat === '')
+        return null;
+    return flat.length > MESSAGE_CAP ? `${flat.slice(0, MESSAGE_CAP)}…` : flat;
+}
+/** The declared `check.args`, or null when the declaration carries an argument this runner will not pass. */
+function declaredCheckArgs(check) {
+    const args = check ? check['args'] : undefined;
+    if (args === undefined)
+        return [];
+    if (!Array.isArray(args) || args.length > CHECK_ARGS_MAX)
+        return null;
+    return args.every((a) => typeof a === 'string' && CHECK_ARG_RE.test(a)) ? args : null;
+}
+/** Run `pp-tools check <query> [<phase>] [<args>…] --raw` in a child process (check handlers exit the process). */
+const defaultCheckRunner = (query, phase, cwd, checkArgs) => {
+    const tools = node_path_1.default.join(__dirname, '..', 'pp-tools.cjs');
+    const args = [tools, 'check', query, ...(phase ? [phase] : []), ...checkArgs, '--raw'];
+    const r = (0, shell_command_projection_cjs_1.execTool)(process.execPath, args, { cwd, timeout: CHECK_TIMEOUT_MS });
+    if (r.exitCode !== 0 || r.signal) {
+        const why = r.signal ? `killed by ${r.signal}` : `exit ${r.exitCode}`;
+        return { ok: false, result: null, error: `${why}${r.stderr ? `: ${r.stderr.split('\n')[0]}` : ''}` };
+    }
+    if (r.stdout === '')
+        return { ok: false, result: null, error: 'empty output' };
+    try {
+        const parsed = JSON.parse(r.stdout);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return { ok: false, result: null, error: 'output is not a JSON object' };
+        return { ok: true, result: parsed, error: null };
+    }
+    catch {
+        return { ok: false, result: null, error: 'output is not JSON' };
+    }
+};
+/**
+ * Run every active gate at `point` (already resolved) under the two-step
+ * contract. Pure apart from `runCheck`.
+ */
+function runGates(point, phase, activeHooks, cwd, runCheck = defaultCheckRunner) {
+    const gates = [];
+    const lines = [];
+    let halt = false;
+    for (const h of activeHooks) {
+        if (h.kind !== 'gate')
+            continue;
+        const blocking = h.blocking === true;
+        const onError = typeof h.onError === 'string' ? h.onError : 'skip';
+        const check = h.check && typeof h.check === 'object' ? h.check : null;
+        const query = check && typeof check['query'] === 'string' ? check['query'] : null;
+        const checkArgs = declaredCheckArgs(check);
+        const run = { capId: h.capId, query, blocking, onError, outcome: 'pass', block: null, message: null };
+        if (query === null || !CHECK_QUERY_RE.test(query) || checkArgs === null) {
+            run.outcome = 'unrunnable';
+            run.message = query === null
+                ? 'the gate declares no check.query'
+                : checkArgs === null ? 'check.args is not a list of plain flags and words' : 'check.query is not a check name';
+            if (blocking) {
+                halt = true;
+                lines.push(`⛔ ${point} blocked: capability gate (${h.capId}) cannot be run (${run.message}). Fix the capability declaration before continuing.`);
+            }
+            else {
+                lines.push(`⚠ ${h.capId} advisory (${point}): gate not run — ${run.message}.`);
+            }
+            gates.push(run);
+            continue;
+        }
+        // Step 1 — did the check command itself succeed?
+        const r = runCheck(query, phase, cwd, checkArgs);
+        if (!r.ok || r.result === null) {
+            run.message = boundMessage(r.error) ?? 'command error';
+            if (onError === 'halt') {
+                run.outcome = 'error-halt';
+                halt = true;
+                lines.push(`⛔ ${point} blocked: gate check command failed (${h.capId}: check ${query}): ${run.message}. Resolve before continuing.`);
+            }
+            else {
+                run.outcome = 'error-skip';
+                lines.push(`⚠ ${point} gate check command failed (${h.capId}: check ${query}): ${run.message} — skipped (onError: ${onError}).`);
+            }
+            gates.push(run);
+            continue;
+        }
+        // Step 2 — read block (only reached when the command succeeded).
+        const block = r.result['block'] === true;
+        run.block = block;
+        run.message = boundMessage(r.result['message']) ?? boundMessage(r.result['reason']);
+        if (blocking && block) {
+            run.outcome = 'blocked';
+            halt = true;
+            lines.push(`⛔ ${point} blocked by capability gate (${h.capId}): ${run.message ?? `check ${query} reported block`}. Resolve before continuing.`);
+        }
+        else if (!blocking && (block || boundMessage(r.result['message']) !== null)) {
+            run.outcome = 'advisory';
+            lines.push(`⚠ ${h.capId} advisory (${point}): ${run.message ?? `check ${query} reported block`}`);
+        }
+        else {
+            run.outcome = 'pass';
+            const note = blocking ? boundMessage(r.result['message']) : null;
+            if (note !== null)
+                lines.push(`ℹ ${h.capId} (${point}): ${note}`);
+        }
+        gates.push(run);
+    }
+    return { point, phase, halt, gates, lines };
+}
+/**
+ * `loop run-gates <point> [--phase <N>] [--tier <t>]`. Exit 1 on a halt or a
+ * refusal; the verdict JSON is on stdout either way except on a refusal.
+ */
+function cmdLoopRunGates(cwd, point, raw, options = {}) {
+    if (!point) {
+        coreError('loop run-gates requires a <point> argument (e.g. verify:post)', ERROR_REASON.USAGE);
+        return;
+    }
+    const phase = typeof options['phase'] === 'string' && options['phase'] !== '' ? options['phase'] : null;
+    const tierCli = typeof options['tier'] === 'string' && options['tier'] !== '' ? options['tier'] : null;
+    if (tierCli !== null && !['light', 'standard', 'heavy'].includes(tierCli)) {
+        coreError('--tier needs one of light, standard, heavy', ERROR_REASON.USAGE);
+        return;
+    }
+    const phaseTier = (phase !== null || tierCli !== null) && unreadableConfigFiles(cwd).length === 0
+        ? (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, phase, tierCli)
+        : null;
+    const outcome = resolveProjectLoopHooks(cwd, point, { phaseTier, what: `loop run-gates ${point}` });
+    if (!outcome.ok) {
+        coreError(outcome.message, outcome.reason === 'config_unreadable' ? ERROR_REASON.CONFIG_PARSE_FAILED : undefined);
+        return;
+    }
+    const onlyQuery = typeof options['query'] === 'string' && options['query'] !== '' ? options['query'] : null;
+    const hooks = onlyQuery === null
+        ? outcome.resolved.activeHooks
+        : outcome.resolved.activeHooks.filter((h) => {
+            const c = h.check && typeof h.check === 'object' ? h.check : null;
+            return c !== null && c['query'] === onlyQuery;
+        });
+    const verdict = runGates(point, phase, hooks, cwd);
+    if (verdict.lines.length > 0) {
+        try {
+            process.stderr.write(verdict.lines.join('\n') + '\n');
+        }
+        catch {
+            /* stderr closed */
+        }
+    }
+    coreOutput(verdict, raw);
+    if (verdict.halt)
+        process.exitCode = 1;
+}
+module.exports = {
+    runGates,
+    cmdLoopRunGates,
+};

package/pp-core/bin/lib/loop-resolver.cjs

@@ -30,10 +30,10 @@
  */
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
-const { output: coreOutput, error: coreError } = ioMod;
+const { output: coreOutput, error: coreError, ERROR_REASON } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoaderModule = require("./config-loader.cjs");
-const { loadConfig } = configLoaderModule;
+const { loadConfig, unreadableConfigFiles, describeUnreadableConfig } = configLoaderModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityStateModule = require("./capability-state.cjs");
 const { resolveCapabilityRuntimeState } = capabilityStateModule;
@@ -382,6 +382,80 @@ function renderLoopHooks(resolved) {
     return lines.join('\n');
 }
 // ─── I/O command handler ───────────────────────────────────────────────────────
+/**
+ * The refusal text for a caller that resolves hooks over an unreadable config.
+ * One wording for every such caller (`loop render-hooks`, `phase.dispatch-plan`).
+ */
+function unreadableConfigRefusal(what, unreadable) {
+    return (`${what} refused: the project config cannot be read, so no hook can be resolved ` +
+        `(rendering anyway would silently drop every hook the config switches on, a required client vault among them). ` +
+        `${describeUnreadableConfig(unreadable)}. Repair or remove the file, then re-run. Stop this workflow here.`);
+}
+/**
+ * Resolve the active hooks at `point` for the project at `cwd`, exactly as
+ * `loop render-hooks` does: refuse an unreadable config, load the config
+ * snapshot once, overlay the phase tier's gate booleans when one is given,
+ * resolve capability state over the same snapshot, then resolve the hooks.
+ * The ONE owner of "which hooks are active here" for every caller that needs
+ * the answer in code (`loop render-hooks`, `phase.dispatch-plan`'s executor
+ * contributions). Never exits; the caller decides how to report a refusal.
+ */
+function resolveProjectLoopHooks(cwd, point, opts = {}) {
+    // Fail closed on a config that exists but cannot be read. Every hook's `when`
+    // and activation key is read from it, and both readers below swallow a parse
+    // failure into the defaults, so rendering anyway drops exactly the hooks the
+    // project switched on — a required client vault's fetch and blocking gate
+    // among them. A MISSING config is not refused: that is a fresh project, and
+    // the defaults are its real settings.
+    const unreadable = unreadableConfigFiles(cwd);
+    if (unreadable.length > 0) {
+        return { ok: false, reason: 'config_unreadable', message: unreadableConfigRefusal(opts.what ?? `loop render-hooks ${point}`, unreadable) };
+    }
+    // Load the config snapshot ONCE and share it with both the capability-state
+    // resolver (via configOverride) and loop-hook resolution, so federated keys
+    // present in loadConfig resolve identically for `active` and for hook when/
+    // configValues. Keys absent from loadConfig still fall through to raw
+    // .planning/config.json reads (precedence levels 2-3) in each pass.
+    let config;
+    try {
+        config = loadConfig(cwd);
+    }
+    catch {
+        config = {};
+    }
+    if (opts.phaseTier)
+        config = (0, phase_tier_cjs_1.overlayTierGates)(config, opts.phaseTier);
+    const state = resolveCapabilityRuntimeState(cwd, opts.configDir, config);
+    // Registry is the static generated module — same object capability-state uses internally.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const registry = require('./capability-registry.cjs');
+    const capabilityStatesById = new Map();
+    for (const cap of state.capabilities || []) {
+        capabilityStatesById.set(cap.id, cap);
+    }
+    try {
+        const resolved = resolveLoopHooks({ point, registry, config, cwd, capabilityStatesById });
+        return { ok: true, resolved, warnings: state.warnings ?? [] };
+    }
+    catch (err) {
+        return { ok: false, reason: 'invalid_point', message: (err instanceof Error) ? err.message : String(err) };
+    }
+}
+/**
+ * The `fragment.inline` text of every active contribution into `role`, in
+ * resolved order, with the capability that contributed it.
+ */
+function contributionsInto(resolved, role) {
+    const out = [];
+    for (const h of resolved.activeHooks) {
+        if (h.kind !== 'contribution' || h.into !== role)
+            continue;
+        if (typeof h.fragment?.inline !== 'string')
+            continue;
+        out.push({ capId: h.capId, fragment: h.fragment.inline });
+    }
+    return out;
+}
 /**
  * Command entry point: load registry + config, resolve + render, emit envelope.
  *
@@ -396,6 +470,10 @@ function renderLoopHooks(resolved) {
  * pre-cutover keys like `workflow.ui_phase` that live in config.json but are not
  * yet exposed through loadConfig's whitelist.
  *
+ * Unreadable config: when any project config file exists but cannot be parsed
+ * (`unreadableConfigFiles`), every mode refuses before rendering — exit 1,
+ * empty stdout, one stderr line naming each file and its parse error.
+ *
  * --active-cap <capId>: when present, resolves hooks for <point> exactly as the
  * normal path does, then prints exactly `true` (if any resolved activeHook has
  * capId === <capId>) or `false` followed by a single newline, and exits 0.
@@ -403,6 +481,13 @@ function renderLoopHooks(resolved) {
  * Missing <capId> value → coreError + non-zero exit.
  * Unknown/inactive capId → `false` (not an error).
  *
+ * --into <role>: resolves exactly as the normal path does, then prints the
+ * `fragment.inline` text of each active contribution whose `into` equals
+ * <role>, in resolved order, separated by one blank line, with a trailing
+ * newline when anything printed. Nothing at all (empty stdout, exit 0) when no
+ * contribution matches. No JSON envelope; `--raw` is ignored. `--active-cap`
+ * takes precedence: given both, `--into` is ignored.
+ *
  * --phase <N> [--tier light|standard|heavy] (pack 9): resolve the phase's
  * ceremony tier (src/phase-tier.cts) and overlay its gate booleans
  * (`workflow.research`, `workflow.pattern_mapper`, …) on the config snapshot
@@ -422,23 +507,15 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
         coreError('--active-cap requires a <capId> value (e.g. --active-cap tdd)');
         return;
     }
+    // --into <role> mode: emit matching contribution fragment text only
+    const intoRole = typeof options['into'] === 'string' ? options['into'] : undefined;
+    if (activeCapId === undefined && intoRole !== undefined && intoRole.trim() === '') {
+        coreError('Missing value for --into (e.g. --into executor)', ERROR_REASON.USAGE);
+        return;
+    }
     const runtimeConfigDir = typeof options['configDir'] === 'string'
         ? options['configDir']
         : undefined;
-    // Load the config snapshot ONCE and share it with both the capability-state
-    // resolver (via configOverride) and loop-hook resolution, so federated keys
-    // present in loadConfig resolve identically for `active` and for hook when/
-    // configValues — eliminating the previous double loadConfig() call. Note: keys
-    // absent from loadConfig still fall through to raw .planning/config.json reads
-    // (precedence levels 2-3) in each pass; that residual re-read window is
-    // pre-existing (unchanged by this consolidation), not introduced here.
-    let config;
-    try {
-        config = loadConfig(cwd);
-    }
-    catch {
-        config = {};
-    }
     const tierPhase = typeof options['phase'] === 'string' && options['phase'] !== '' ? options['phase'] : null;
     const tierCli = typeof options['tier'] === 'string' && options['tier'] !== '' ? options['tier'] : null;
     let phaseTier = null;
@@ -447,32 +524,29 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
             coreError('--tier needs one of light, standard, heavy');
             return;
         }
-        phaseTier = (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, tierPhase, tierCli);
-        config = (0, phase_tier_cjs_1.overlayTierGates)(config, phaseTier);
+        // The refusal below must come first: never resolve a tier from a config it cannot read.
+        if (unreadableConfigFiles(cwd).length === 0)
+            phaseTier = (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, tierPhase, tierCli);
     }
-    const state = resolveCapabilityRuntimeState(cwd, runtimeConfigDir, config);
-    // Registry is the static generated module — same object capability-state uses internally.
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const registry = require('./capability-registry.cjs');
-    const capabilityStatesById = new Map();
-    for (const cap of state.capabilities || []) {
-        capabilityStatesById.set(cap.id, cap);
-    }
-    let resolved;
-    try {
-        resolved = resolveLoopHooks({ point, registry, config, cwd, capabilityStatesById });
-    }
-    catch (err) {
-        const msg = (err instanceof Error) ? err.message : String(err);
-        coreError(msg);
+    const outcome = resolveProjectLoopHooks(cwd, point, { configDir: runtimeConfigDir, phaseTier });
+    if (!outcome.ok) {
+        coreError(outcome.message, outcome.reason === 'config_unreadable' ? ERROR_REASON.CONFIG_PARSE_FAILED : undefined);
         return;
     }
+    const resolved = outcome.resolved;
     // --active-cap mode: print exactly 'true' or 'false' with no envelope
     if (activeCapId !== undefined) {
         const isActive = resolved.activeHooks.some((h) => h.capId === activeCapId);
         process.stdout.write(isActive ? 'true\n' : 'false\n');
         return;
     }
+    // --into mode: fragment text of the active contributions targeting <role>
+    if (intoRole !== undefined) {
+        const texts = contributionsInto(resolved, intoRole).map((c) => c.fragment);
+        if (texts.length > 0)
+            process.stdout.write(texts.join('\n\n') + '\n');
+        return;
+    }
     const rendered = renderLoopHooks(resolved);
     const envelope = {
         point: resolved.point,
@@ -482,8 +556,8 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     if (phaseTier) {
         envelope.phase_tier = { phase: tierPhase, tier: phaseTier.tier, source: phaseTier.source, suppressed: phaseTier.suppressed };
     }
-    if (state.warnings && state.warnings.length > 0) {
-        envelope.warnings = state.warnings;
+    if (outcome.warnings.length > 0) {
+        envelope.warnings = outcome.warnings;
     }
     // No rawValue third argument, so --raw emits the JSON envelope rather than
     // plain text. This is deliberate and load-bearing: 23 workflow call sites do
@@ -497,6 +571,8 @@ module.exports = {
     resolveLoopHooks,
     renderLoopHooks,
     cmdLoopRenderHooks,
+    resolveProjectLoopHooks,
+    contributionsInto,
     // Exported for tests
     _getNestedConfigValue,
     _resolveActivationValue,