@pareto4/pp-core 1.10.0 → 1.11.0

package/pp-core/bin/lib/init-interactive.cjs

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * src/init-interactive.cts — drives the 34-08 `/pp-init` session state
+ * machine against an injectable prompt seam (milestone v1.11.0, Phase
+ * 34-09, gap closure).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/init-interactive.cjs`; do NOT
+ * hand-edit the compiled output. Behaviour is locked by
+ * `tests/init-interactive.test.cjs`.
+ *
+ * Born from a documented failure, not a speculative hardening. Four human
+ * UAT walks of `/pp-init` on 2026-07-31 (`34-VALIDATION.md` § Manual-Only
+ * Verifications) all failed at the identical point, across four escalating
+ * enforcement strategies — prose, hardened prose, a data-supplying CLI arm
+ * (34-07), and 34-08's one-step-at-a-time session state machine. The agent
+ * executed every pure-bash step reliably in all four walks and completed
+ * Step 3 remote wiring every time; the ONLY step it never once performed as
+ * written is the one whose job is to ask the user a structured question
+ * set — at that boundary it substitutes its own `AskUserQuestion` wizard
+ * and discards the document. 34-08 gave the CLI the sequence but left the
+ * agent the interaction; this module gives the CLI the interaction itself.
+ *
+ * `runInitInteractive` reimplements NOTHING from `src/init-contract.cts` —
+ * it only sequences calls into `initSessionNext`/`initSessionAnswer`, which
+ * remain the sole authority for the question set, the identity/provider
+ * writes, and the compose-and-write decision. The `prompter` parameter is
+ * the seam: an object with `ask()`/`print()` that the CLI (pp-tools.cjs)
+ * implements with `node:readline` against a real terminal, and that tests
+ * implement with a scripted fake. This module deliberately never imports
+ * `node:readline` itself — that is what keeps the whole interactive flow
+ * testable by `node:test` with no pty (see the plan's own design hazards).
+ *
+ * Residual risk, stated plainly (see the plan's threat register): nothing
+ * here compels a user to run `pp-tools init`. What it removes is the
+ * failure mode that actually bit four times — `/pp-init` appearing to
+ * complete while silently producing no binding.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInitInteractive = runInitInteractive;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const init_contract_cjs_1 = require("./init-contract.cjs");
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** Defensive circuit breaker against a runaway loop (a misbehaving
+ * prompter or an unexpected session state that never reaches `done` or
+ * `verify`). The real session never exceeds ~10 steps (8 questions +
+ * `compose_confirm` + `done`); this is headroom, not a real budget. */
+const MAX_SESSION_STEPS = 100;
+// ─── Small local helpers ───────────────────────────────────────────────────
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function bindingsPathFor(cwd) {
+    return node_path_1.default.join(cwd, '.platform-bindings.json');
+}
+/** Snapshot `.platform-bindings.json`'s content (`null` when absent) — used
+ * to compute `wroteBinding` from an actual pre/post diff rather than a bare
+ * post-hoc `existsSync`, which reads a pre-existing file (predating this
+ * run) as "we wrote it" (WR-01). Read failures degrade to `null` — this is
+ * a diagnostic snapshot, not a source of truth `initSessionAnswer` itself
+ * relies on, so it must never throw. */
+function readBindingsContent(cwd) {
+    try {
+        return node_fs_1.default.readFileSync(bindingsPathFor(cwd), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** Render `compose_confirm`'s provenance table, drift list and action to
+ * the prompter, BEFORE the caller asks for approval — plan Task 1's own
+ * ordering requirement. */
+function renderComposeConfirm(prompter, info) {
+    if (!isRecord(info))
+        return;
+    const typed = info;
+    prompter.print('A binding can be composed from the org profile and project answers:');
+    for (const entry of typed.provenance ?? []) {
+        prompter.print(`  ${entry.field} = ${JSON.stringify(entry.value)} (from ${entry.source})`);
+    }
+    const drift = typed.drift ?? [];
+    if (drift.length > 0) {
+        prompter.print('Drift (the already-committed file wins — nothing here is a proposed change):');
+        for (const d of drift) {
+            prompter.print(`  the profile would have supplied ${JSON.stringify(d.profileValue)} for "${d.key}"; ` +
+                `the file already says ${JSON.stringify(d.effectiveValue)}, and ${JSON.stringify(d.effectiveValue)} wins.`);
+        }
+    }
+    for (const warning of typed.warnings ?? []) {
+        prompter.print(`  warning: ${warning}`);
+    }
+    prompter.print(`Action: ${typed.action ?? 'unknown'}`);
+}
+// ─── runInitInteractive ─────────────────────────────────────────────────────
+/**
+ * Drive the `/pp-init` session at `cwd` to completion, asking `prompter`
+ * for exactly one answer per step and submitting it back to the session.
+ * Reimplements no session logic — `initSessionNext`/`initSessionAnswer`
+ * remain the sole authority for sequencing, validation and every write.
+ *
+ * Loop, per session step:
+ *  - `error` (malformed session file) → print and stop, `ok: false`.
+ *  - `done` → print a short summary (what was written, or that nothing was
+ *    composed and why) and stop, `ok: true`.
+ *  - `verify` (unresolved invariant violations) → print every violation
+ *    and stop, `ok: false` — this is the intentional "visibly unfinished"
+ *    outcome the session design is built around, never a crash.
+ *  - `question` / `compose_confirm` → render (provenance/drift/action for
+ *    `compose_confirm`, BEFORE asking), then `ask` the prompter and submit
+ *    the answer. A REJECTED answer (`initSessionAnswer` returns `ok:
+ *    false`) is re-asked with the session's own `message`, in a bounded
+ *    inner loop — never swallowed, never silently treated as accepted.
+ */
+async function runInitInteractive(cwd, prompter, opts = {}) {
+    const sessionOpts = { offline: opts.offline === true, _globalRoot: opts._globalRoot };
+    let wroteBinding = false;
+    for (let steps = 1; steps <= MAX_SESSION_STEPS; steps++) {
+        const state = (0, init_contract_cjs_1.initSessionNext)(cwd, sessionOpts);
+        if (state.error !== undefined) {
+            prompter.print(`Error: ${state.message ?? state.error}`);
+            return { ok: false, wroteBinding, steps, violations: [] };
+        }
+        if (state.done) {
+            if (wroteBinding) {
+                prompter.print('Done — .platform-bindings.json was composed and written.');
+            }
+            else if (typeof state.info === 'string') {
+                prompter.print(state.info);
+            }
+            else {
+                prompter.print('Done — nothing was composed (declined, or nothing was composable).');
+            }
+            return { ok: true, wroteBinding, steps, violations: [] };
+        }
+        if (state.step === 'verify') {
+            const violations = state.violations ?? [];
+            prompter.print('The session could not reach a clean end state:');
+            for (const v of violations) {
+                prompter.print(`  - [${v.code}] ${v.message}`);
+            }
+            return { ok: false, wroteBinding, steps, violations };
+        }
+        if (state.step === null) {
+            // Defensive: the session contract never returns a null step outside
+            // `done`/`verify`/`error` above. Fail closed rather than crash.
+            prompter.print('Unexpected session state: no step id was returned.');
+            return { ok: false, wroteBinding, steps, violations: [] };
+        }
+        const stepId = state.step;
+        if (stepId === 'compose_confirm') {
+            renderComposeConfirm(prompter, state.info);
+        }
+        // Ask, re-asking on rejection — never swallowed (T-34-73).
+        for (;;) {
+            // WR-01: capture the pre-answer state of the binding file BEFORE
+            // submitting the answer, so a true write can be told apart from a
+            // pre-existing file that predates this run (a bare post-hoc
+            // `existsSync` cannot make that distinction).
+            const preBindings = stepId === 'compose_confirm' ? readBindingsContent(cwd) : null;
+            const answer = await prompter.ask({
+                prompt: state.prompt ?? '',
+                options: state.options,
+                preselected: state.preselected,
+                preselectedLabel: state.preselectedLabel,
+                optionalAnswer: state.optionalAnswer,
+            });
+            const result = (0, init_contract_cjs_1.initSessionAnswer)(cwd, stepId, answer, sessionOpts);
+            if (result.ok) {
+                if (stepId === 'compose_confirm') {
+                    wroteBinding = readBindingsContent(cwd) !== preBindings;
+                }
+                break;
+            }
+            prompter.print(result.message ?? `Rejected (${result.reason ?? 'unknown reason'}) — please answer again.`);
+        }
+    }
+    prompter.print('init session exceeded the maximum step count — aborting to avoid an infinite loop.');
+    return { ok: false, wroteBinding, steps: MAX_SESSION_STEPS, violations: [] };
+}

package/pp-core/bin/lib/io.cjs

@@ -177,6 +177,8 @@ const ERROR_REASON = Object.freeze({
     SECURITY_SCAN_FAILED: 'security_scan_failed',
     // platform-bindings
     PLATFORM_BINDINGS_PARSE_FAILED: 'platform_bindings_parse_failed',
+    // init (Phase 34-09 gap closure: `pp-tools init` interactive command)
+    INIT_NON_INTERACTIVE: 'init_non_interactive',
     // vault write-back promote arm (Phase 29 WRB-01/03)
     VAULT_PROMOTE_DISABLED: 'vault_promote_disabled',
     VAULT_PROMOTE_INVALID_PRACTICE: 'vault_promote_invalid_practice',