@pareto4/pp-core 1.21.1 → 1.23.1

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

@@ -13,6 +13,7 @@ exports.readVaultRequiredState = readVaultRequiredState;
 exports.buildInitQuestions = buildInitQuestions;
 exports.deriveSlug = deriveSlug;
 exports.readProfileInitAnswers = readProfileInitAnswers;
+exports.collectInvariantViolations = collectInvariantViolations;
 exports.verifyInitInvariants = verifyInitInvariants;
 exports.armVaultKeysWhereAbsent = armVaultKeysWhereAbsent;
 exports.recordProbeOutcome = recordProbeOutcome;
@@ -21,6 +22,7 @@ exports.initSessionNext = initSessionNext;
 exports.initSessionAnswer = initSessionAnswer;
 exports.initSessionReset = initSessionReset;
 exports.armVaultFromProfile = armVaultFromProfile;
+exports.withoutDisplay = withoutDisplay;
 exports.cmdInitContract = cmdInitContract;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -34,6 +36,7 @@ const org_profile_cjs_1 = require("./org-profile.cjs");
 const platform_bindings_cjs_1 = require("./platform-bindings.cjs");
 const compose_bindings_cjs_1 = require("./compose-bindings.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const messages_cjs_1 = require("./messages.cjs");
 // ─── Constants ───────────────────────────────────────────────────────────────
 /** Set when the operator declines `compose_confirm` — the only way to tell "declined" from "never ran". */
 exports.INIT_COMPOSE_DECLINED_KEY = 'init.compose_declined';
@@ -234,30 +237,30 @@ function buildInitQuestions(cwd, opts = {}) {
         preselected = git_provider_cjs_1.DEFAULT_PROVIDER;
     }
     const providerOptions = Object.freeze([...git_provider_cjs_1.PROVIDERS, ...IDENTITY_ONLY_PROVIDER_OPTIONS]);
+    const ask = (id, params = {}, code = `init.step.${id}`) => ({
+        prompt: (0, messages_cjs_1.msgDeveloper)(code, params),
+        display: { prompt: { code, params } },
+    });
     return [
-        { id: 'project_name', prompt: 'Project name (human-readable, e.g. "Acme Dashboard")', optionalAnswer: false },
-        { id: 'project_slug', prompt: 'Project slug (kebab-case, e.g. "acme-dashboard")', optionalAnswer: false },
-        {
-            id: 'client_name',
-            prompt: 'Client name (company / team, e.g. "Acme Corp") — type "internal" if none',
-            optionalAnswer: false,
-        },
-        {
-            id: 'client_slug',
-            prompt: 'Client slug (kebab-case, e.g. "acme") — type "internal" if none',
-            optionalAnswer: false,
-        },
+        { id: 'project_name', ...ask('project_name'), optionalAnswer: false },
+        { id: 'project_slug', ...ask('project_slug'), optionalAnswer: false },
+        { id: 'client_name', ...ask('client_name'), optionalAnswer: false },
+        { id: 'client_slug', ...ask('client_slug'), optionalAnswer: false },
         ...clientVaultQuestion(cwd, opts),
-        { id: 'description', prompt: 'One-line description (what this project does)', optionalAnswer: false },
+        { id: 'description', ...ask('description'), optionalAnswer: false },
         {
             id: 'provider',
-            prompt: 'Provider (gitlab / azure / github / other / none)',
+            prompt: (0, messages_cjs_1.msgDeveloper)('init.step.provider'),
             optionalAnswer: false,
             options: providerOptions,
             preselected,
-            preselectedLabel: `${preselected} (resolved default)`,
+            preselectedLabel: (0, messages_cjs_1.msgDeveloper)('init.chrome.resolved_default', { provider: preselected }),
+            display: {
+                prompt: { code: 'init.step.provider', params: {} },
+                preselectedLabel: { code: 'init.chrome.resolved_default', params: { provider: preselected } },
+            },
         },
-        { id: 'visibility', prompt: 'Visibility (private / public / internal)', optionalAnswer: false },
+        { id: 'visibility', ...ask('visibility'), optionalAnswer: false },
     ];
 }
 /** The client-vault question, asked while no vault is bound and a binding can be composed (`clientVaultChoice`).
@@ -267,13 +270,14 @@ function clientVaultQuestion(cwd, opts) {
     const choice = (0, compose_bindings_cjs_1.clientVaultChoice)(cwd, opts);
     if (!choice.offered)
         return [];
+    const code = choice.defaultRepo === null ? 'init.step.client_vault' : 'init.step.client_vault_default';
+    const params = choice.defaultRepo === null ? {} : { repo: choice.defaultRepo };
     return [
         {
             id: 'client_vault',
-            prompt: choice.defaultRepo === null
-                ? 'Client vault repo ("owner/name" or a full clone URL) — type "none" to bind no client vault'
-                : `Client vault repo ("owner/name" or a full clone URL) — type "none" to use the default vault (${choice.defaultRepo})`,
+            prompt: (0, messages_cjs_1.msgDeveloper)(code, params),
             optionalAnswer: true,
+            display: { prompt: { code, params } },
         },
     ];
 }
@@ -380,9 +384,10 @@ function readConfigFile(cwd) {
         return { exists, parsed: {} };
     }
 }
-/** Report every invariant the project's state at `cwd` violates. Read-only and never throws;
- * each check needs a positive signal that init was attempted, so an empty directory is ok. */
-function verifyInitInvariants(cwd, opts = {}) {
+/** Report every invariant the project's state at `cwd` violates, each with the params its message was built from.
+ * Read-only and never throws; each check needs a positive signal that init was attempted, so an empty directory is ok.
+ * The three in-scope messages are the catalog's developer text; the rest keep their literals with no params. */
+function collectInvariantViolations(cwd, opts = {}) {
     const violations = [];
     const { exists: configExists, parsed } = readConfigFile(cwd);
     // INIT_IDENTITY_MISSING — only meaningful once a config file exists at
@@ -394,7 +399,8 @@ function verifyInitInvariants(cwd, opts = {}) {
             if (!hasProjectBlock) {
                 violations.push({
                     code: INVARIANT_CODE.IDENTITY_MISSING,
-                    message: 'No "project" block found in .planning/config.json — Step 2 identity capture did not complete.',
+                    message: (0, messages_cjs_1.msgDeveloper)(INVARIANT_CODE.IDENTITY_MISSING),
+                    params: {},
                 });
             }
         }
@@ -407,9 +413,11 @@ function verifyInitInvariants(cwd, opts = {}) {
         const projectProvider = getDotted(parsed, 'project.provider');
         const vaultProvider = getDotted(parsed, 'vault.provider');
         if (git_provider_cjs_1.PROVIDERS.includes(projectProvider) && !isUsableString(vaultProvider)) {
+            const params = { provider: String(projectProvider) };
             violations.push({
                 code: INVARIANT_CODE.VAULT_PROVIDER_UNSET,
-                message: `project.provider is "${String(projectProvider)}" but vault.provider is unset — the D-13 provisioning gate is disabled.`,
+                message: (0, messages_cjs_1.msgDeveloper)(INVARIANT_CODE.VAULT_PROVIDER_UNSET, params),
+                params,
             });
         }
     }
@@ -426,8 +434,8 @@ function verifyInitInvariants(cwd, opts = {}) {
             if (dryRun.composable === true) {
                 violations.push({
                     code: INVARIANT_CODE.COMPOSITION_NOT_RUN,
-                    message: 'A binding is composable from the org profile and project answers, but .platform-bindings.json was never written and no decline was recorded — Step 2.5 appears to have been skipped. ' +
-                        'Run "pp-tools init --reset" to redo the question set and reach the compose confirmation (init-friction F3: a completed session never re-offers composition on a bare re-run).',
+                    message: (0, messages_cjs_1.msgDeveloper)(INVARIANT_CODE.COMPOSITION_NOT_RUN),
+                    params: {},
                 });
             }
         }
@@ -458,6 +466,7 @@ function verifyInitInvariants(cwd, opts = {}) {
                         'Store the boolean with "pp-tools config-set vault.enabled true" (which accepts only ' +
                         'true or false, and refuses any other spelling), or "pp-tools config-set vault.enabled ' +
                         'false" to turn the capability off.',
+                    params: {},
                 });
             }
         }
@@ -491,6 +500,7 @@ function verifyInitInvariants(cwd, opts = {}) {
                     message: `The reachability proof recorded FAILED on ${when} by ${who}: ${note}. ` +
                         'Re-run "/pp-init" after fixing the remote, or record an attributed deferral with ' +
                         '"pp-tools query init-contract --defer-probe <reason>".',
+                    params: {},
                 });
             }
             else if (vaultArmed && status === exports.INIT_PROBE_STATUS.DEFERRED) {
@@ -499,6 +509,7 @@ function verifyInitInvariants(cwd, opts = {}) {
                     code: INVARIANT_CODE.PROBE_DEFERRED,
                     message: `The reachability proof was deferred by ${who} on ${when} for reason: ${note}. ` +
                         'Init remains unproven until a re-run of "/pp-init" records a passing probe.',
+                    params: {},
                 });
             }
             else if (owesAProof) {
@@ -510,6 +521,7 @@ function verifyInitInvariants(cwd, opts = {}) {
                     message: `The org profile "${profile}" resolves, vault.enabled is true and .platform-bindings.json ` +
                         `is present, but ${clause} — /pp-init Step 2.6 appears not to have run.` +
                         notRunRemedy,
+                    params: {},
                 });
                 if (status === exports.INIT_PROBE_STATUS.PASSED) {
                     // Only an attributed, timestamped pass clears the check.
@@ -530,7 +542,12 @@ function verifyInitInvariants(cwd, opts = {}) {
     catch {
         // fail open — one check's fault must not suppress the others
     }
-    return { ok: violations.length === 0, violations };
+    return violations;
+}
+/** The public invariant check: `{ code, message }` per violation, with no params (the `--verify` JSON is unchanged). */
+function verifyInitInvariants(cwd, opts = {}) {
+    const collected = collectInvariantViolations(cwd, opts);
+    return { ok: collected.length === 0, violations: collected.map(({ code, message }) => ({ code, message })) };
 }
 // ─── Session state machine: one step at a time, every side effect performed by the CLI ───
 function sessionFilePath(cwd) {
@@ -596,13 +613,14 @@ function loadSession(cwd) {
         return { malformed: true };
     }
 }
-/** Format an unexpected write failure as a bounded message — never a raw stack trace. */
-function writeFailedMessage(err) {
+/** An unexpected write failure as a bounded message (never a raw stack trace) plus the catalog handle the driver words it from. */
+function writeFailed(err) {
     const detail = err instanceof Error ? err.message : String(err);
-    return (`A filesystem write inside the init session failed (${detail}). ` +
-        'This project\'s .planning directory (or .platform-bindings.json) may not be writable ' +
-        '(permissions, a read-only mount, a full disk). Nothing further was recorded for this step — ' +
-        'fix the underlying filesystem issue and try the same step again.');
+    const ref = { code: exports.INIT_SESSION_WRITE_FAILED, params: { detail } };
+    return { message: (0, messages_cjs_1.msgDeveloper)(ref.code, ref.params), ref };
+}
+function writeFailedMessage(err) {
+    return writeFailed(err).message;
 }
 function persistSession(cwd, session) {
     const dir = node_path_1.default.join(cwd, '.planning');
@@ -838,24 +856,30 @@ function computeCurrentStep(cwd, session, opts) {
             persistSession(cwd, session);
         }
         // Three different nothing-written end states, each with its own message.
-        const skippedComposeInfo = session.composeDecision === 'skipped'
-            ? 'Nothing was composable from the org profile and project answers — no compose_confirm step was shown and nothing was written (the inert path, INIT-02).'
+        const skippedCode = session.composeDecision === 'skipped'
+            ? 'init.done.skipped'
             : session.composeDecision === 'unchanged'
-                ? 'The existing .platform-bindings.json is already up to date with what the org profile and project answers would produce — no compose_confirm step was needed and nothing was written.'
+                ? 'init.done.unchanged'
                 : undefined;
+        const skippedComposeInfo = skippedCode === undefined ? undefined : { text: (0, messages_cjs_1.msgDeveloper)(skippedCode), ref: { code: skippedCode, params: {} } };
         // The session verify skips only the INIT_PROBE_* check: Step 2.6 records the proof after init returns.
-        const verifyResult = verifyInitInvariants(cwd, { _globalRoot: opts._globalRoot, scope: 'session' });
-        if (verifyResult.ok) {
+        const collected = collectInvariantViolations(cwd, { _globalRoot: opts._globalRoot, scope: 'session' });
+        if (collected.length === 0) {
             if (!session.doneAt) {
                 session.doneAt = new Date().toISOString();
                 persistSession(cwd, session);
             }
             return { kind: 'done', skippedComposeInfo };
         }
-        return { kind: 'verify', violations: verifyResult.violations, skippedComposeInfo };
+        return {
+            kind: 'verify',
+            violations: collected.map(({ code, message }) => ({ code, message })),
+            refs: collected.map(({ code, params }) => ({ code, params })),
+            skippedComposeInfo,
+        };
     }
     catch (err) {
-        return { kind: 'write_failed', message: writeFailedMessage(err) };
+        return { kind: 'write_failed', ...writeFailed(err) };
     }
 }
 function currentStepToState(step) {
@@ -869,15 +893,18 @@ function currentStepToState(step) {
                 state.preselected = q.preselected;
             if (q.preselectedLabel !== undefined)
                 state.preselectedLabel = q.preselectedLabel;
+            if (q.display !== undefined)
+                state.display = q.display;
             return state;
         }
         case 'compose_confirm':
             return {
                 done: false,
                 step: 'compose_confirm',
-                prompt: 'A binding can be composed from the org profile and project answers. Compose and write .platform-bindings.json now? (yes/no)',
+                prompt: (0, messages_cjs_1.msgDeveloper)('init.step.compose_confirm'),
                 optionalAnswer: false,
                 info: step.info,
+                display: { prompt: { code: 'init.step.compose_confirm', params: {} } },
             };
         case 'verify':
             return {
@@ -885,14 +912,20 @@ function currentStepToState(step) {
                 step: 'verify',
                 prompt: null,
                 violations: step.violations,
-                ...(step.skippedComposeInfo !== undefined ? { info: step.skippedComposeInfo } : {}),
+                ...(step.skippedComposeInfo !== undefined ? { info: step.skippedComposeInfo.text } : {}),
+                display: {
+                    violations: step.refs,
+                    ...(step.skippedComposeInfo !== undefined ? { info: step.skippedComposeInfo.ref } : {}),
+                },
             };
         case 'done':
             return {
                 done: true,
                 step: 'done',
                 prompt: null,
-                ...(step.skippedComposeInfo !== undefined ? { info: step.skippedComposeInfo } : {}),
+                ...(step.skippedComposeInfo !== undefined
+                    ? { info: step.skippedComposeInfo.text, display: { info: step.skippedComposeInfo.ref } }
+                    : {}),
             };
         case 'write_failed':
             return {
@@ -901,9 +934,14 @@ function currentStepToState(step) {
                 prompt: null,
                 error: exports.INIT_SESSION_WRITE_FAILED,
                 message: step.message,
+                display: { message: step.ref },
             };
     }
 }
+/** A refusal whose text is the catalog's developer wording and whose handle lets the driver word it for the person. */
+function refusal(reason, ref) {
+    return { ok: false, reason, message: (0, messages_cjs_1.msgDeveloper)(ref.code, ref.params), display: { message: ref } };
+}
 /** Return the ONE next step of the session; malformed session state fails closed (recover with `--session-reset`). */
 function initSessionNext(cwd, opts = {}) {
     const loaded = loadSession(cwd);
@@ -913,8 +951,8 @@ function initSessionNext(cwd, opts = {}) {
             step: null,
             prompt: null,
             error: exports.INIT_SESSION_MALFORMED,
-            message: 'The init session file at .planning/.init-session.json exists but is malformed or unreadable. ' +
-                'Run "pp_run query init-contract --session-reset" to start over — it is never resumed silently into an unknown state.',
+            message: (0, messages_cjs_1.msgDeveloper)(exports.INIT_SESSION_MALFORMED),
+            display: { message: { code: exports.INIT_SESSION_MALFORMED, params: {} } },
         };
     }
     const session = loaded.session;
@@ -926,19 +964,14 @@ function initSessionNext(cwd, opts = {}) {
 function initSessionAnswer(cwd, stepId, value, opts = {}) {
     const loaded = loadSession(cwd);
     if (loaded.malformed) {
-        return {
-            ok: false,
-            reason: 'session_malformed',
-            message: 'The init session file at .planning/.init-session.json exists but is malformed or unreadable. ' +
-                'Run "pp_run query init-contract --session-reset" to start over.',
-        };
+        return refusal('session_malformed', { code: 'init.answer.session_malformed', params: {} });
     }
     const session = loaded.session;
     // Any write failure in this function degrades to `write_failed` instead of throwing.
     try {
         const step = computeCurrentStep(cwd, session, opts);
         if (step.kind === 'write_failed') {
-            return { ok: false, reason: 'write_failed', message: step.message };
+            return { ok: false, reason: 'write_failed', message: step.message, display: { message: step.ref } };
         }
         if (step.kind === 'done') {
             return {
@@ -956,13 +989,13 @@ function initSessionAnswer(cwd, stepId, value, opts = {}) {
                 };
             }
             if (!step.question.optionalAnswer && (typeof value !== 'string' || value.trim() === '')) {
-                return { ok: false, reason: 'answer_required', message: `Question "${stepId}" requires a non-blank answer.` };
+                return refusal('answer_required', { code: 'init.answer.answer_required', params: { step: stepId } });
             }
             const answerValue = typeof value === 'string' ? value : '';
             if (stepId === 'client_vault') {
                 const checked = (0, compose_bindings_cjs_1.validateClientVaultAnswer)(answerValue);
                 if (!checked.ok) {
-                    return { ok: false, reason: 'invalid_answer', message: `Question "client_vault": ${checked.reason}` };
+                    return refusal('invalid_answer', { code: 'init.answer.invalid_client_vault', params: { detail: checked.reason } });
                 }
             }
             session.answers[stepId] = answerValue;
@@ -979,11 +1012,7 @@ function initSessionAnswer(cwd, stepId, value, opts = {}) {
             }
             const normalized = normalizeYesNo(value);
             if (normalized === null) {
-                return {
-                    ok: false,
-                    reason: 'invalid_answer',
-                    message: 'compose_confirm requires "yes" or "no" (also accepts approve/decline, y/n, true/false).',
-                };
+                return refusal('invalid_answer', { code: 'init.answer.invalid_compose_confirm', params: {} });
             }
             if (normalized === true) {
                 // Check the write result before recording "approved": the file can change between the dry run and this write.
@@ -995,14 +1024,9 @@ function initSessionAnswer(cwd, stepId, value, opts = {}) {
                 });
                 if (writeResult.composable !== true || writeResult.wrote !== true) {
                     // Leave the decision unset so the next call re-evaluates and can re-offer compose_confirm.
-                    return {
-                        ok: false,
-                        reason: 'compose_write_failed',
-                        message: 'compose_confirm was approved, but the write to .platform-bindings.json did not succeed — ' +
-                            'this was NOT recorded as skipped or declined.' +
-                            (writeResult.warnings.length > 0 ? ` Warnings: ${writeResult.warnings.join('; ')}.` : '') +
-                            ' Call --session-next to see the current state and try again.',
-                    };
+                    return refusal('compose_write_failed', writeResult.warnings.length > 0
+                        ? { code: 'init.answer.compose_write_failed_warnings', params: { warnings: writeResult.warnings.join('; ') } }
+                        : { code: 'init.answer.compose_write_failed', params: {} });
                 }
                 session.composeDecision = 'approved';
                 armVaultKeysWhereAbsent(cwd);
@@ -1022,7 +1046,8 @@ function initSessionAnswer(cwd, stepId, value, opts = {}) {
         };
     }
     catch (err) {
-        return { ok: false, reason: 'write_failed', message: writeFailedMessage(err) };
+        const failed = writeFailed(err);
+        return { ok: false, reason: 'write_failed', message: failed.message, display: { message: failed.ref } };
     }
 }
 /** Delete the session file (the recovery from a malformed session). Never throws. */
@@ -1141,20 +1166,35 @@ function armVaultFromProfile(cwd, opts = {}) {
         };
     }
 }
+/** A copy of `value` without its own top-level `display` handle; an array gets that per item (D-08).
+ * The session JSON is a machine channel the /pp-init fallback path parses; the in-process catalog handles never reach it.
+ * The handles are only ever attached at the top level of a session state, an answer result or a question. Nested data
+ * (compose `info`, org-profile and binding values, auto-answers) is user data and passes through untouched, even a key
+ * named `display`. */
+function withoutDisplay(value) {
+    if (Array.isArray(value))
+        return value.map((item) => withoutDisplay(item));
+    if (typeof value === 'object' && value !== null && Object.hasOwn(value, 'display')) {
+        const copy = { ...value };
+        delete copy.display;
+        return copy;
+    }
+    return value;
+}
 // ─── cmdInitContract ────────────────────────────────────────────────────────
 /** CLI adapter for `pp-tools query init-contract`: the session, record, arm-vault, verify and questions flags.
  * Data verdicts set `exitCode = 1` when not ok, but the JSON result is always printed. */
 function cmdInitContract(cwd, options, raw) {
     if (options.sessionReset === true) {
         const result = initSessionReset(cwd);
-        output(result, raw);
+        output(withoutDisplay(result), raw);
         return;
     }
     if (options.sessionAnswer !== undefined) {
         const result = initSessionAnswer(cwd, options.sessionAnswer.stepId, options.sessionAnswer.value, {
             offline: options.offline === true,
         });
-        output(result, raw);
+        output(withoutDisplay(result), raw);
         if (!result.ok) {
             process.exitCode = 1;
         }
@@ -1162,7 +1202,7 @@ function cmdInitContract(cwd, options, raw) {
     }
     if (options.sessionNext === true) {
         const state = initSessionNext(cwd, { offline: options.offline === true });
-        output(state, raw);
+        output(withoutDisplay(state), raw);
         if (state.error !== undefined) {
             process.exitCode = 1;
         }
@@ -1171,7 +1211,7 @@ function cmdInitContract(cwd, options, raw) {
     // Record writes run before `--verify`, so a combined call verifies the written state.
     if (options.recordProbe !== undefined) {
         const result = recordProbeOutcome(cwd, options.recordProbe);
-        output(result, raw);
+        output(withoutDisplay(result), raw);
         if (!result.ok) {
             process.exitCode = 1;
         }
@@ -1179,7 +1219,7 @@ function cmdInitContract(cwd, options, raw) {
     }
     if (options.deferProbe !== undefined) {
         const result = recordProbeDeferral(cwd, options.deferProbe);
-        output(result, raw);
+        output(withoutDisplay(result), raw);
         if (!result.ok) {
             process.exitCode = 1;
         }
@@ -1188,7 +1228,7 @@ function cmdInitContract(cwd, options, raw) {
     // An inert `armed: false` is a data verdict on exit 0, like the inert init path; only `ok: false` exits 1.
     if (options.armVault === true) {
         const result = armVaultFromProfile(cwd, { offline: options.offline === true });
-        output(result, raw);
+        output(withoutDisplay(result), raw);
         if (result.ok === false) {
             process.exitCode = 1;
         }
@@ -1196,11 +1236,11 @@ function cmdInitContract(cwd, options, raw) {
     }
     if (options.verify === true) {
         const result = verifyInitInvariants(cwd);
-        output(result, raw);
+        output(withoutDisplay(result), raw);
         if (!result.ok) {
             process.exitCode = 1;
         }
         return;
     }
-    output({ questions: buildInitQuestions(cwd) }, raw);
+    output({ questions: buildInitQuestions(cwd).map(withoutDisplay) }, raw);
 }