@pareto4/pp-core 1.12.1 → 1.17.1

package/pp-core/bin/lib/vault-update.cjs

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * src/vault-update.cts — `pp-tools vault update [<tag>] [--yes]` (PBI 74316).
+ *
+ * FORK-ONLY. Moves a project to another version of its client vault. The
+ * vault version is a PROJECT property: `client.vaultRef` in the committed
+ * `.platform-bindings.json` is the one place it lives, so no pp-core release
+ * can move it — changing it is a deliberate act, and this is its command.
+ *
+ * Distinct from its neighbours:
+ *   - `pp-tools vault fetch` re-reads the vault at the version the project is
+ *     already pinned to; it never changes `client.vaultRef`.
+ *   - `/pp-update` updates pp-core itself, not a project's vault.
+ *
+ * Two steps, so the confirmation is explicit and works the same for a person
+ * and for an agent shell: without `--yes` it only reports the plan
+ * (current → target) and writes nothing; with `--yes` it writes
+ * `client.vaultRef`, fetches the vault at the new version, and reports any
+ * practice whose `schemaVersion` is newer than this pp-core supports (the
+ * vault version a project picks implies a minimum pp-core, never the reverse).
+ * It never commits: the command it prints is the operator's to run.
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/vault-update.cjs`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AVAILABLE_TAGS_CAP = void 0;
+exports.vaultUpdate = vaultUpdate;
+exports.renderVaultUpdate = renderVaultUpdate;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const project_root_cjs_1 = require("./project-root.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const semver_compare_cjs_1 = require("./semver-compare.cjs");
+const compose_bindings_cjs_1 = require("./compose-bindings.cjs");
+const git_provider_cjs_1 = require("./git-provider.cjs");
+const vault_coordinates_cjs_1 = require("./vault-coordinates.cjs");
+const platform_bindings_cjs_1 = require("./platform-bindings.cjs");
+// VAULT-EGRESS-1 (quick 261005-8py): the one coordinate redactor. Cycle-free — src/vault.cts imports
+// nothing from this module; the lazy `require` in runFetch exists for the `_fetch` seam default.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultModule = require("./vault.cjs");
+const { redactCloneTarget } = vaultModule;
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** How many tags a report lists — enough to pick from, bounded for a long history. */
+exports.AVAILABLE_TAGS_CAP = 10;
+const BINDINGS_FILE = '.platform-bindings.json';
+/** Matches the degrade warning `parsePracticeFile` emits for a newer schemaVersion. */
+const NEWER_SCHEMA_WARNING_RE = /schemaVersion \d+ is newer than this pp-core supports/;
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function isObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function usableString(v) {
+    return typeof v === 'string' && v.trim() !== '' ? v.trim() : null;
+}
+function resolveRoot(cwd) {
+    try {
+        return (0, project_root_cjs_1.findProjectRoot)(cwd) || cwd;
+    }
+    catch {
+        return cwd;
+    }
+}
+/** Resolve a requested tag against the available list; accepts a missing `v`. */
+function matchRequestedTag(requested, tags) {
+    const trimmed = requested.trim();
+    if (tags.includes(trimmed))
+        return trimmed;
+    if (!trimmed.startsWith('v') && tags.includes(`v${trimmed}`))
+        return `v${trimmed}`;
+    return null;
+}
+function runFetch(root, opts) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const fetchFn = opts._fetch ?? require('./vault.cjs').vaultFetch;
+    const manifest = fetchFn(root);
+    const warnings = [];
+    if (typeof manifest.warning === 'string')
+        warnings.push(manifest.warning);
+    if (Array.isArray(manifest.warnings)) {
+        for (const w of manifest.warnings)
+            if (typeof w === 'string' && !warnings.includes(w))
+                warnings.push(w);
+    }
+    return {
+        source: typeof manifest.source === 'string' ? manifest.source : 'unknown',
+        ref: typeof manifest.ref === 'string' ? manifest.ref : null,
+        warnings,
+    };
+}
+function findNewerSchemaPractices(root, opts) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const discover = opts._discover ?? require('./vault-practices.cjs').discoverPracticeFiles;
+    const discovery = discover(root);
+    const ids = [];
+    for (const entry of discovery.degraded ?? []) {
+        if (entry.warnings.some((w) => NEWER_SCHEMA_WARNING_RE.test(w)) && !ids.includes(entry.id))
+            ids.push(entry.id);
+    }
+    return ids;
+}
+// ─── vaultUpdate ─────────────────────────────────────────────────────────────
+/**
+ * Plan — and with `apply` perform — a move of the project's client vault to
+ * another stable tag. Never throws: every fault is a result with `ok: false`
+ * and a `reason`. Writes exactly one field (`client.vaultRef`) of an existing
+ * `.platform-bindings.json`, and only after the whole document still passes
+ * `validateBindings`.
+ */
+function vaultUpdate(cwd, opts = {}) {
+    const root = resolveRoot(cwd);
+    const bindingsPath = node_path_1.default.join(root, BINDINGS_FILE);
+    const result = {
+        ok: false,
+        applied: false,
+        reason: null,
+        message: '',
+        bindingsPath,
+        repo: null,
+        from: null,
+        to: null,
+        latest: null,
+        available: [],
+        fetch: null,
+        newerSchemaPractices: [],
+        nextStep: null,
+    };
+    const fail = (reason, message) => ({
+        ...result,
+        ok: false,
+        reason,
+        message,
+    });
+    if (!node_fs_1.default.existsSync(bindingsPath)) {
+        return fail('no_bindings', `No ${BINDINGS_FILE} in ${root} — run "pp-tools init" first; the vault version lives there.`);
+    }
+    let bindings;
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(bindingsPath, 'utf-8'));
+        if (!isObject(parsed))
+            throw new Error('not an object');
+        bindings = parsed;
+    }
+    catch {
+        return fail('bindings_unreadable', `${BINDINGS_FILE} could not be read as a JSON object — fix it before updating the vault.`);
+    }
+    const client = isObject(bindings.client) ? bindings.client : null;
+    const repo = client ? usableString(client.vaultRepo) : null;
+    if (!client || !repo) {
+        return fail('no_client_vault', `${BINDINGS_FILE} names no client vault (client.vaultRepo) — there is no vault version to update.`);
+    }
+    result.repo = redactCloneTarget(repo);
+    result.from = usableString(client.vaultRef);
+    let tags;
+    try {
+        const provider = (0, git_provider_cjs_1.resolveProvider)(root).provider;
+        const host = usableString(client.vaultHost) ?? (0, vault_coordinates_cjs_1.resolvePlatformHost)(root).host ?? (0, vault_coordinates_cjs_1.defaultHostForProvider)(provider);
+        const target = (0, git_provider_cjs_1.composeCloneTarget)(provider, repo, host);
+        tags = (0, compose_bindings_cjs_1.listStableTagsAt)(target.url, { _lsRemote: opts._lsRemote });
+    }
+    catch {
+        return fail('tag_lookup_failed', `The tags of the vault repo "${redactCloneTarget(repo)}" could not be listed — check your network and git access to it.`);
+    }
+    tags = [...new Set(tags)].sort((a, b) => (0, semver_compare_cjs_1.compareSemverCore)(b, a));
+    result.available = tags.slice(0, exports.AVAILABLE_TAGS_CAP);
+    result.latest = tags[0] ?? null;
+    if (tags.length === 0) {
+        return fail('no_tags', `The vault repo "${redactCloneTarget(repo)}" has no stable vX.Y.Z tag to pin to.`);
+    }
+    const requested = usableString(opts.target);
+    const to = requested ? matchRequestedTag(requested, tags) : tags[0];
+    if (!to) {
+        return fail('unknown_tag', `The vault repo has no tag "${requested}". Available (newest first): ${result.available.join(', ')}.`);
+    }
+    result.to = to;
+    const fromLabel = result.from ?? 'main (unpinned)';
+    if (result.from === to) {
+        return { ...result, ok: true, message: `The project is already on vault ${to}.` };
+    }
+    if (opts.apply !== true) {
+        return {
+            ...result,
+            ok: true,
+            message: `The project would move from vault ${fromLabel} to ${to}. Nothing was changed.`,
+            nextStep: `pp-tools vault update ${to} --yes`,
+        };
+    }
+    const updated = { ...bindings, client: { ...client, vaultRef: to } };
+    const validation = (0, platform_bindings_cjs_1.validateBindings)(updated);
+    if (!validation.valid) {
+        return fail('invalid_bindings', `The updated ${BINDINGS_FILE} would not be valid: ${validation.errors.join('; ')}. Nothing was changed.`);
+    }
+    try {
+        (0, shell_command_projection_cjs_1.platformWriteSync)(bindingsPath, JSON.stringify(updated, null, 2) + '\n');
+    }
+    catch {
+        return fail('write_failed', `${BINDINGS_FILE} could not be written. Nothing was changed.`);
+    }
+    const applied = {
+        ...result,
+        ok: true,
+        applied: true,
+        message: `The project moved from vault ${fromLabel} to ${to}.`,
+        nextStep: `git add ${BINDINGS_FILE} && git commit -m "chore(vault): update client vault to ${to}"`,
+    };
+    try {
+        applied.fetch = runFetch(root, opts);
+    }
+    catch {
+        applied.fetch = { source: 'error', ref: null, warnings: ['The vault could not be fetched at the new version — run "pp-tools vault fetch" to retry.'] };
+    }
+    try {
+        applied.newerSchemaPractices = findNewerSchemaPractices(root, opts);
+    }
+    catch {
+        applied.newerSchemaPractices = [];
+    }
+    return applied;
+}
+/** Plain-text rendering of a `vaultUpdate` result for the non-`--raw` CLI path. */
+function renderVaultUpdate(r) {
+    const lines = [r.message];
+    if (r.ok && r.latest && r.to !== r.latest) {
+        lines.push(`Newest available: ${r.latest}.`);
+    }
+    if (r.fetch) {
+        lines.push(`Fetched the vault: ${r.fetch.source}${r.fetch.ref ? ` at ${r.fetch.ref}` : ''}.`);
+        for (const w of r.fetch.warnings)
+            lines.push(w);
+    }
+    if (r.newerSchemaPractices.length > 0) {
+        lines.push(`${r.newerSchemaPractices.length} practice(s) in this vault version were written for a newer pp-core and apply only in degraded form: ${r.newerSchemaPractices.join(', ')}. Update pp-core to apply them fully.`);
+    }
+    if (r.nextStep) {
+        lines.push(r.applied ? `Commit the change: ${r.nextStep}` : `To apply: ${r.nextStep}`);
+    }
+    return lines.join('\n');
+}

package/pp-core/bin/lib/vault-write-back.cjs

@@ -103,6 +103,8 @@ const PROMOTE_GUARD = Object.freeze({
     WRITE_TARGET: 'write_target',
     CONCURRENT_EDIT: 'concurrent_edit',
     TRANSPORT: 'transport',
+    // 13-07 (D-14): standards mode — write-back has no practice layer to write to.
+    MODE: 'mode',
 });
 // ─── Secret-content scanner (WRB-03 / D-13 / D-14) ──────────────────────────────
 //
@@ -200,7 +202,7 @@ function boundedToken(v, max = 80) {
 }
 // ─── Preflight guard chain ───────────────────────────────────────────────────────
 /**
- * Run the promote preflight guard chain: activation, input, format
+ * Run the promote preflight guard chain: activation, mode (13-07), input, format
  * validation (D-03), secret scan (D-13/D-14), target resolution, and the
  * write-target guard (D-05) — strictly in that order, refusing at the
  * first failing stage and never continuing past it. Makes no network
@@ -211,16 +213,37 @@ function promotePreflight({ cwd, filePath, _vault, _practices }) {
     const vault = _vault ?? require('./vault.cjs');
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
     const practices = _practices ?? require('./vault-practices.cjs');
-    // 1. Activation — both vault.enabled and vault.practices_enabled must be
-    // strictly true. Runs before any filesystem access; rides the two
-    // existing default-false config keys (no new config key, no capability
-    // surface widening).
-    const enabled = vault.cfgGet(cwd, 'vault.enabled', false);
-    const practicesEnabled = vault.cfgGet(cwd, 'vault.practices_enabled', false);
-    if (enabled !== true || practicesEnabled !== true) {
+    // 1. Activation — the vault-practices capability must be on. Runs before
+    // any filesystem access; rides the two existing default-false config keys
+    // (no new config key, no capability surface widening). Phase 15 D-24/D-25:
+    // asked of the ONE practices-switch reader, `isPracticesGateActive`, which
+    // resolves both keys exactly as the vault-practices gates' `when` does. The
+    // `cfgGet` pair it replaces read only the root config, so a workstream-scoped
+    // switch refused here while the gates rendered (15-RESEARCH C-1). Read from
+    // the REAL vault leaf, not the `_vault` seam, like the mode guard below: a
+    // mocked config read must not be able to switch promotion on.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const switchOwner = require('./vault.cjs');
+    if (!switchOwner.isPracticesGateActive(cwd)) {
         return refusal(PROMOTE_GUARD.ACTIVATION, ERROR_REASON.VAULT_PROMOTE_DISABLED, 'This practice was not promoted: vault write-back is switched off for this project. ' +
             'Set both vault.enabled and vault.practices_enabled to true in .planning/config.json and run the promotion again.');
     }
+    // 1b. Mode (13-07, D-14, PARK-03) — in standards mode the vault carries
+    // standards documents maintained through its INDEX.md, not practice files,
+    // so there is nothing a promotion could write. Refused here, after the
+    // activation guard and BEFORE the input guard reads `filePath` or any clone
+    // runs, so the preview and `--confirmed` share it (both call this chain
+    // first). Read from the REAL vault leaf, not the `_vault` seam: a governance
+    // decision must not be switchable by a test mock (the 13-06 precedent). The
+    // envelope carries NO mode key — a promote verdict already uses that key for
+    // create/update — so the mode is named in the message only.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const modeOwner = require('./vault.cjs');
+    if (modeOwner.isStandardsModeActive(cwd)) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { notApplicablePromoteMessage } = require('./vault-mode.cjs');
+        return refusal(PROMOTE_GUARD.MODE, ERROR_REASON.VAULT_PROMOTE_NOT_APPLICABLE, notApplicablePromoteMessage());
+    }
     // 2. Input — a path to an already-authored practice file (D-02); this
     // module never composes, rewrites, reformats, or extracts a practice.
     if (typeof filePath !== 'string' ||
@@ -242,6 +265,44 @@ function promotePreflight({ cwd, filePath, _vault, _practices }) {
         const cause = parsed.warning.replace(/^.*?\s+skipped:\s*/, '');
         return refusal(PROMOTE_GUARD.VALIDATION, ERROR_REASON.VAULT_PROMOTE_INVALID_PRACTICE, `This practice was not promoted: ${cause} Fix the practice file and run the promotion again.`);
     }
+    // 3b. Degraded-parse refusal (CHECK-02e, 05-01).
+    //
+    // WRITE-SIDE STRICTNESS IS DELIBERATE, and the asymmetry with the read side
+    // is the point. On the READ side a practice the engine does not fully
+    // understand is retained: it came from the vault, it already governs work,
+    // and dropping it would silently un-govern that work (ADR-71924 §5). On the
+    // WRITE side the same practice is refused, because promoting it pushes the
+    // defect INTO the fleet-wide vault that every developer machine and CI runner
+    // fetches — one unreviewed key becomes everyone's degraded warning. The read
+    // side tolerates what the write side refuses.
+    //
+    // Both consumers of DOCUMENTED_FRONTMATTER_KEYS therefore moved in the one
+    // change that widened it (T-4-49): had only the reader moved, an unknown key
+    // would have quietly become promotable.
+    if (parsed.degradedWarnings !== undefined && parsed.degradedWarnings.length > 0) {
+        const cause = parsed.degradedWarnings[0].replace(/^.*?\s+degraded:\s*/, '');
+        return refusal(PROMOTE_GUARD.VALIDATION, ERROR_REASON.VAULT_PROMOTE_INVALID_PRACTICE, `This practice was not promoted: ${cause} Fix the practice file and run the promotion again.`);
+    }
+    // 3c. Invalid-check-block refusal (CR-05 / G-3, 05-11).
+    //
+    // An invalid `check:` block is refused on the write side for the same reason
+    // 3b refuses a degraded parse, and the consequence here is worse. The reader
+    // reports this defect on a THIRD channel — `practice.checkInvalid` — which is
+    // neither `!parsed.ok` nor `degradedWarnings`, so both rungs above miss it;
+    // and the folding of `checkInvalid` into `degraded[]` happens inside
+    // `discoverPracticeFiles`, which this path never calls.
+    //
+    // Once such a practice is in the fleet vault the defect is not a warning for
+    // the next reader: `verdictForPractice`'s FIRST rung maps `checkInvalid` to a
+    // fail-closed FAIL(check_invalid), so it becomes `block: true` at ship:pre and
+    // verify:post on every machine that fetches the vault. One typo would stop the
+    // whole fleet's builds. The refusal covers ANY invalid block regardless of
+    // which assertion kind it declared (D-05-05), because `checkInvalid` is the
+    // single fail-closed signal for both.
+    if (typeof parsed.practice.checkInvalid === 'string' && parsed.practice.checkInvalid.length > 0) {
+        return refusal(PROMOTE_GUARD.VALIDATION, ERROR_REASON.VAULT_PROMOTE_INVALID_PRACTICE, `This practice was not promoted: ${parsed.practice.checkInvalid} ` +
+            'Fix the practice file and run the promotion again.');
+    }
     // 4. Secret scan — a hit refuses hard, no override (D-14). The matched
     // text is never carried, quoted, echoed, logged, or truncated into the
     // refusal — a truncated secret is still a partial disclosure.
@@ -402,7 +463,9 @@ function buildExpectToken(localRaw, remoteBaseline) {
 // reading) — duplicating the fix a second time is exactly how that class of
 // bug recurs.
 function previewPromotion({ cwd, filePath, _exec, _vault, _practices }) {
-    const gitExec = _exec ?? shell_command_projection_cjs_1.execGit;
+    const gitExec = _exec ?? shell_command_projection_cjs_1.execGitLocal;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const vault = _vault ?? require('./vault.cjs');
     // 1. Run the full preflight guard chain; refuse unchanged with no clone.
     const pre = promotePreflight({ cwd, filePath, _vault, _practices });
     if (pre.status !== 'ok')
@@ -440,7 +503,7 @@ function previewPromotion({ cwd, filePath, _exec, _vault, _practices }) {
             cloneDir,
         ], { timeout: 120_000 });
         if (cl.exitCode !== 0) {
-            const cause = shownCause(cl.stderr);
+            const cause = boundedToken((cl.stderr || '').split(/\r?\n/)[0] || 'unknown error');
             return refusal(PROMOTE_GUARD.TRANSPORT, ERROR_REASON.VAULT_PROMOTE_TRANSPORT_FAILED, `This practice was not pushed: git could not reach the vault (${cause}). Check your access to the vault and run the promotion again.`);
         }
         // 3. Capture the baseline BEFORE writing — an id already present in the
@@ -552,13 +615,13 @@ function previewPromotion({ cwd, filePath, _exec, _vault, _practices }) {
         // sentence (plan 03); this note additionally explains why, in the
         // read-only preview an operator reads before confirming.
         if (pre.sharedSuppressed && pre.sharedSuppressedKind === 'provider-default-unavailable') {
-            notes.push(`No shared vault is configured for the ${pre.provider} provider — the built-in Pareto shared default applies only to the gitlab provider. Set vault.fallback_repo to enable the shared tier.`);
+            notes.push(`No shared vault is configured for the ${pre.provider} provider — the built-in Pareto shared default applies only to the github provider. Set vault.fallback_repo to enable the shared tier.`);
         }
         // 7 & 8. Pin both sides in the opaque expect token, then return.
         const expect = buildExpectToken(pre.raw, baseline);
         return {
             status: 'preview',
-            repo: shownRepo(pre.repo),
+            repo: vault.redactCloneTarget(pre.repo),
             ref: pre.ref,
             destination: pre.destination,
             mode,
@@ -577,25 +640,9 @@ function previewPromotion({ cwd, filePath, _exec, _vault, _practices }) {
     }
 }
 // ─── Confirm (write half of the write path) ──────────────────────────────────────
-/**
- * Pack 6 D-07: the display-safe forms used in every verdict and refusal this
- * module EMITS — the one owner in src/vault.cts, lazily required (the
- * module's `_vault` seam stays the fetch seam; redaction is never mocked).
- * Comparisons, the expect token and every git invocation keep the RAW values.
- */
-function shownRepo(repo) {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const v = require('./vault.cjs');
-    return v.redactCloneTarget(repo) ?? repo;
-}
-function shownCause(stderr) {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const v = require('./vault.cjs');
-    return boundedToken(v.redactRemoteText((stderr || '').split(/\r?\n/)[0] || 'unknown error'));
-}
 /** Build a TRANSPORT refusal from a failed git invocation's stderr (first line only). */
 function transportRefusal(res) {
-    const cause = shownCause(res.stderr);
+    const cause = boundedToken((res.stderr || '').split(/\r?\n/)[0] || 'unknown error');
     return refusal(PROMOTE_GUARD.TRANSPORT, ERROR_REASON.VAULT_PROMOTE_TRANSPORT_FAILED, `This practice was not pushed: git could not reach the vault (${cause}). Check your access to the vault and run the promotion again.`);
 }
 /**
@@ -617,7 +664,7 @@ function transportRefusal(res) {
  * for free, so no separate `git show`/`cat-file` call is needed.
  */
 function confirmPromotion({ cwd, filePath, expect, _exec, _vault, _practices }) {
-    const gitExec = _exec ?? shell_command_projection_cjs_1.execGit;
+    const gitExec = _exec ?? shell_command_projection_cjs_1.execGitLocal;
     // 1. Full preflight re-run — never trust the preview. Re-derives repo,
     // ref, host, and destination from scratch; never accepts a caller-
     // supplied id/destination/repo/ref.
@@ -755,7 +802,7 @@ function confirmPromotion({ cwd, filePath, expect, _exec, _vault, _practices })
         }
         return {
             status: 'pushed',
-            repo: shownRepo(pre.repo),
+            repo: vault.redactCloneTarget(pre.repo),
             ref: pre.ref,
             destination: pre.destination,
             mode,