@pareto4/pp-core 1.12.0 → 1.13.0

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

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * src/vault-update.cts — `pp-tools vault update [<tag>] [--yes]`.
+ *
+ * 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.
+ *
+ * With no `<tag>` it proposes the newest stable `vX.Y.Z` tag of the configured
+ * vault repository, listed with `git ls-remote` at the same clone target the
+ * fetch uses (`resolveClientCoordinates` + `composeCloneTarget`). Nothing here
+ * reads an org profile for a version: the vault version is the project's.
+ *
+ * Every repository coordinate it prints goes through `redactCloneTarget`, and
+ * every value it echoes from the bindings file or the command line is
+ * bounded to one short line.
+ *
+ * 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");
+// 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;
+}
+/** A value from the bindings file or the command line, made safe to print: one line, at most 80 characters. */
+function shown(v) {
+    const flat = v.replace(/[\u0000-\u001F\u007F]+/g, ' ').trim();
+    return flat.length > 80 ? `${flat.slice(0, 80)}…` : flat;
+}
+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,
+        tier: typeof manifest.tier === 'string' ? manifest.tier : 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;
+        // The same host chain the fetch uses (client.vaultHost, platform host, provider default).
+        const host = (0, vault_coordinates_cjs_1.resolveClientCoordinates)(root, provider).host;
+        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 "${shown(requested ?? "")}". Available (newest first): ${result.available.join(', ')}.`);
+    }
+    result.to = to;
+    const fromLabel = result.from === null ? 'main (unpinned)' : shown(result.from);
+    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, tier: 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) {
+        if (r.fetch.tier !== null && r.fetch.tier !== 'client' && r.fetch.source !== 'error') {
+            // A fallback-tier fetch is not the client vault at the new version, and
+            // must not read as if it were.
+            lines.push(`The client vault at ${r.to ?? 'the new version'} was NOT loaded: the fetch fell back to the ${r.fetch.tier} tier` +
+                `${r.fetch.ref ? ` at ${r.fetch.ref}` : ''}. Check access to the client vault, then run "pp-tools vault fetch".`);
+        }
+        else {
+            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

@@ -242,6 +242,25 @@ 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. Write-side strictness is deliberate: the read
+    // side keeps a practice it does not fully understand, because it already
+    // governs work and dropping it would silently un-govern that work; promoting
+    // it would push the defect into the shared vault every machine fetches. Both
+    // consumers of DOCUMENTED_FRONTMATTER_KEYS move in the one change that
+    // widened it — 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. The reader reports this defect on its own
+    // channel (`practice.checkInvalid`), which is neither `!parsed.ok` nor
+    // `degradedWarnings` — discovery folds it into `degraded[]`, but this path
+    // never calls discovery — so both rungs above miss it.
+    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.