@pareto4/pp-core 1.17.1 → 1.19.0

package/pp-core/bin/lib/vault-standards-promote.cjs

@@ -0,0 +1,577 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * src/vault-standards-promote.cts — `vault standards promote`: add a standards
+ * document written in this project to the client vault, together with its
+ * INDEX.md entry, after an explicit confirmation (FORK-ONLY, the standards-only
+ * vault).
+ *
+ * Two runs, so the confirmation works the same for a person and for an agent
+ * shell:
+ *   - without `--confirmed` it clones the client vault into a disposable
+ *     directory, writes the document and the INDEX.md change there, and asks
+ *     git for the diff. It returns that diff and an opaque `expect` token that
+ *     pins the local document, the entry, and what the vault held for both
+ *     files. Nothing is committed or pushed.
+ *   - with `--confirmed --expect <token>` it re-runs every guard, clones again,
+ *     fast-forwards, refuses when the local document or either vault file
+ *     changed since the preview, then commits both files once and pushes once,
+ *     with no force flag on any path. It then refreshes the local vault cache.
+ *
+ * Guards, in order, each refusing with the uniform refusal envelope:
+ *   1. activation    — the vault gate is on for this project;
+ *   2. input         — an existing `.md` file;
+ *   3. validation    — the document has a level-1 heading and is not empty or
+ *                      oversized; the vault path is a safe, displayable `.md`
+ *                      path that is not INDEX.md or SUMMARY.md; the INDEX entry
+ *                      text is one display-safe line with a description and a
+ *                      `; used when …` clause (required for a new document);
+ *   4. secret_scan   — no line of the document or the entry looks like a
+ *                      credential (the matched text is never echoed);
+ *   5. write_target  — `client.vaultRepo` is configured, not flag-shaped, and
+ *                      passes `assertVaultWriteTarget` (the shared vault is
+ *                      read-only).
+ * The transport and concurrent-edit refusals belong to the preview and the
+ * confirmed run.
+ *
+ * The INDEX.md line is written in the grammar `src/vault-index.cts` owns
+ * (`- \`path\` — what it is; used when …`), and the edited INDEX is parsed back
+ * before anything is staged: the new entry must read back as written and no
+ * other entry may change.
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/vault-standards-promote.cjs`.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const git_provider_cjs_1 = require("./git-provider.cjs");
+const vault_coordinates_cjs_1 = require("./vault-coordinates.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultIndexLeaf = require("./vault-index.cjs");
+const { ERROR_REASON } = io;
+// ─── Guard identity ──────────────────────────────────────────────────────────
+const PROMOTE_GUARD = Object.freeze({
+    ACTIVATION: 'activation',
+    INPUT: 'input',
+    VALIDATION: 'validation',
+    SECRET_SCAN: 'secret_scan',
+    WRITE_TARGET: 'write_target',
+    CONCURRENT_EDIT: 'concurrent_edit',
+    TRANSPORT: 'transport',
+});
+/** The vault directory a document goes to when no `--path` is given. */
+const DEFAULT_VAULT_DIR = 'standards';
+/** The largest document this command promotes: the INDEX read cap, 256 KiB. */
+const DOCUMENT_BYTE_CAP = vaultIndexLeaf.VAULT_INDEX_BYTE_CAP;
+/** Files the vault engine owns or writes, never a promotion destination. */
+const RESERVED_VAULT_FILES = new Set([vaultIndexLeaf.VAULT_INDEX_FILENAME.toLowerCase(), 'summary.md']);
+// ─── Secret-content scanner ──────────────────────────────────────────────────
+//
+// The labelled shapes of scripts/secret-scan.sh, plus the GitLab `glpat-`
+// token. Order is load-bearing: the Anthropic shape precedes the OpenAI one so
+// an `sk-ant-` key is never reported under the OpenAI label. No override and no
+// placeholder carve-out: a false positive costs a re-run, a missed credential
+// is pushed to every machine that fetches the vault.
+const SECRET_SHAPES = Object.freeze([
+    { label: 'AWS Access Key', re: /AKIA[0-9A-Z]{16}/ },
+    { label: 'AWS Secret Key', re: /aws_secret_access_key\s*=\s*[A-Za-z0-9/+=]{40}/ },
+    { label: 'Anthropic API Key', re: /sk-ant-[A-Za-z0-9_-]{20,}/ },
+    { label: 'OpenAI API Key', re: /sk-[A-Za-z0-9]{20,}/ },
+    { label: 'GitHub PAT', re: /ghp_[A-Za-z0-9]{36}/ },
+    { label: 'GitHub OAuth', re: /gho_[A-Za-z0-9]{36}/ },
+    { label: 'GitHub App Token', re: /ghs_[A-Za-z0-9]{36}/ },
+    { label: 'GitHub Fine-grained PAT', re: /github_pat_[A-Za-z0-9_]{20,}/ },
+    { label: 'GitLab access token', re: /glpat-[A-Za-z0-9_-]{20,}/ },
+    { label: 'Stripe Secret Key', re: /sk_live_[A-Za-z0-9]{24,}/ },
+    { label: 'Stripe Publishable Key', re: /pk_live_[A-Za-z0-9]{24,}/ },
+    { label: 'Private Key Header', re: /-----BEGIN\s+(RSA|EC|DSA|OPENSSH)?\s*PRIVATE\s+KEY-----/ },
+    { label: 'Slack Bot Token', re: /xoxb-[0-9]{10,}-[A-Za-z0-9]{20,}/ },
+    { label: 'Slack Webhook', re: /hooks\.slack\.com\/services\/T[A-Z0-9]{8,}\/B[A-Z0-9]{8,}\/[A-Za-z0-9]{24}/ },
+    { label: 'Google API Key', re: /AIza[A-Za-z0-9_-]{35}/ },
+    { label: 'NPM Token', re: /npm_[A-Za-z0-9]{36}/ },
+    {
+        label: 'Env Variable Leak',
+        re: /(DATABASE_URL|DB_PASSWORD|REDIS_URL|MONGO_URI|JWT_SECRET|SESSION_SECRET|ENCRYPTION_KEY)\s*=\s*[^\s]{8,}/,
+    },
+    { label: 'Generic API Key Assignment', re: /api[_-]?key\s*[:=]\s*['"][A-Za-z0-9_-]{20,}['"]/i },
+    { label: 'Generic Secret Assignment', re: /secret\s*[:=]\s*['"][A-Za-z0-9_-]{20,}['"]/i },
+    { label: 'Generic Token Assignment', re: /token\s*[:=]\s*['"][A-Za-z0-9_-]{20,}['"]/i },
+    { label: 'Generic Password Assignment', re: /password\s*[:=]\s*['"][^'"]{8,}['"]/i },
+]);
+/** The first line that looks like a credential, by name and 1-based line; never the matched text. */
+function scanForSecrets(content) {
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        for (const shape of SECRET_SHAPES) {
+            if (shape.re.test(lines[i]))
+                return { label: shape.label, line: i + 1 };
+        }
+    }
+    return null;
+}
+// ─── Refusal contract ────────────────────────────────────────────────────────
+/** A uniform refusal; the message is collapsed to one line so no value can forge a second. */
+function refusal(guard, reason, message, extra = {}) {
+    return { status: 'refused', guard, reason, message: message.replace(/[\r\n]+/g, ' '), ...extra };
+}
+/** Bound a value before it is echoed into a message. */
+function boundedToken(v, max = 80) {
+    let s;
+    try {
+        s = typeof v === 'string' ? v : JSON.stringify(v);
+    }
+    catch {
+        s = String(v);
+    }
+    s = s.replace(/[\r\n]+/g, ' ');
+    return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+const NOT_PROMOTED = 'This standards document was not promoted:';
+const NOT_PUSHED = 'This standards document was not pushed:';
+// ─── Validation ──────────────────────────────────────────────────────────────
+/** Why a vault destination path is refused, or null when it is usable. */
+function vaultPathProblem(p) {
+    const cls = vaultIndexLeaf.classifyVaultPath(p);
+    if (!cls.ok)
+        return `the vault path ${vaultIndexLeaf.displayVaultPath(p)} is not a safe vault path (${cls.reason})`;
+    if (!vaultIndexLeaf.isDisplaySafeVaultPath(p)) {
+        return `the vault path ${vaultIndexLeaf.displayVaultPath(p)} cannot be shown as written`;
+    }
+    if (!p.toLowerCase().endsWith('.md'))
+        return `the vault path ${p} does not end in .md`;
+    if (RESERVED_VAULT_FILES.has(node_path_1.default.posix.basename(p).toLowerCase())) {
+        return `${p} is a file the vault engine owns, not a standards document`;
+    }
+    return null;
+}
+/** Why an INDEX entry text is refused, or null when it is usable. */
+function entryProblem(entry) {
+    if (entry.trim() === '')
+        return 'the INDEX entry text is empty';
+    if (/[\r\n]/.test(entry))
+        return 'the INDEX entry text must be one line';
+    if (entry.includes('`'))
+        return 'the INDEX entry text may not contain a backtick';
+    if (vaultIndexLeaf.DISPLAY_UNSAFE_TEXT_CHAR_RE.test(entry) || vaultIndexLeaf.sanitiseVaultText(entry) !== entry.trim()) {
+        return 'the INDEX entry text carries a control, invisible or over-long run of characters';
+    }
+    const m = vaultIndexLeaf.VAULT_USED_WHEN_RE.exec(entry);
+    if (!m)
+        return `the INDEX entry text needs a "${vaultIndexLeaf.VAULT_USED_WHEN_MARKER.trim()} …" clause saying when the document applies`;
+    if (entry.slice(0, m.index).trim() === '')
+        return 'the INDEX entry text needs a description before the used-when clause';
+    if (entry.slice(m.index + m[0].length).trim() === '')
+        return 'the used-when clause of the INDEX entry text is empty';
+    return null;
+}
+/** Why a section title is refused, or null when it is usable. */
+function sectionProblem(section) {
+    if (section.trim() === '')
+        return 'the INDEX section title is empty';
+    if (/[\r\n]/.test(section) || section.includes('#'))
+        return 'the INDEX section title must be one line without "#"';
+    if (vaultIndexLeaf.sanitiseVaultText(section) !== section.trim())
+        return 'the INDEX section title carries a control or invisible character';
+    return null;
+}
+/** Why a document body is refused, or null when it is usable. */
+function documentProblem(raw) {
+    if (raw.trim() === '')
+        return 'the document is empty';
+    if (Buffer.byteLength(raw, 'utf-8') > DOCUMENT_BYTE_CAP)
+        return `the document is larger than ${DOCUMENT_BYTE_CAP} bytes`;
+    if (raw.includes('\u0000'))
+        return 'the document contains a NUL byte';
+    if (!/^# \S/m.test(raw))
+        return 'the document has no level-1 heading ("# Title")';
+    return null;
+}
+// ─── Preflight guard chain ───────────────────────────────────────────────────
+/**
+ * The guard chain, strictly in order, refusing at the first failing stage.
+ * Makes no network access and spawns no subprocess. Whether the entry is
+ * REQUIRED (a document the vault does not list yet) can only be known after
+ * the clone, so the preview and the confirmed run check that themselves.
+ */
+function promotePreflight({ cwd, filePath, vaultPath, entry, section }, vault) {
+    // 1. Activation — from the REAL vault leaf, never a test seam, so a mocked
+    // config read cannot switch promotion on.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const gate = require('./vault.cjs');
+    if (!gate.isVaultGateActive(cwd)) {
+        return refusal(PROMOTE_GUARD.ACTIVATION, ERROR_REASON.VAULT_PROMOTE_DISABLED, `${NOT_PROMOTED} the vault is switched off for this project. Set vault.enabled to true in .planning/config.json and run the promotion again.`);
+    }
+    // 2. Input — an already-written document; this command never composes one.
+    if (typeof filePath !== 'string' || filePath.length === 0 || !filePath.toLowerCase().endsWith('.md')
+        || !node_fs_1.default.existsSync(filePath) || !node_fs_1.default.statSync(filePath).isFile()) {
+        return refusal(PROMOTE_GUARD.INPUT, ERROR_REASON.SDK_MISSING_ARG, `${NOT_PROMOTED} ${boundedToken(filePath)} is not an existing .md file. Point at the standards document and run the promotion again.`);
+    }
+    const raw = node_fs_1.default.readFileSync(filePath, 'utf-8');
+    // 3. Validation — the document, the destination, the entry, the section.
+    const destination = typeof vaultPath === 'string' && vaultPath !== ''
+        ? vaultPath
+        : node_path_1.default.posix.join(DEFAULT_VAULT_DIR, node_path_1.default.basename(filePath));
+    const invalid = documentProblem(raw)
+        ?? vaultPathProblem(destination)
+        ?? (typeof entry === 'string' ? entryProblem(entry) : null)
+        ?? (typeof section === 'string' ? sectionProblem(section) : null);
+    if (invalid !== null) {
+        return refusal(PROMOTE_GUARD.VALIDATION, ERROR_REASON.VAULT_PROMOTE_INVALID_DOCUMENT, `${NOT_PROMOTED} ${invalid}. Fix it and run the promotion again.`);
+    }
+    // 4. Secret scan — over the document AND the entry text, which both reach
+    // the vault. Name and line only.
+    const docHit = scanForSecrets(raw);
+    const entryHit = typeof entry === 'string' ? scanForSecrets(entry) : null;
+    if (docHit || entryHit) {
+        const where = docHit ? `line ${docHit.line} of the document` : 'the INDEX entry text';
+        const label = (docHit ?? entryHit)?.label ?? '';
+        return refusal(PROMOTE_GUARD.SECRET_SCAN, ERROR_REASON.VAULT_PROMOTE_SECRET_DETECTED, `${NOT_PUSHED} ${where} looks like ${label}. Remove it and run the promotion again.`, { label, ...(docHit ? { line: docHit.line } : {}) });
+    }
+    // 5. Write target — the client vault, never the shared one.
+    const bindings = vault.readBindings(cwd);
+    const client = bindings && typeof bindings.client === 'object' && bindings.client !== null
+        ? bindings.client
+        : null;
+    const repo = client && typeof client.vaultRepo === 'string' ? client.vaultRepo : null;
+    if (!repo) {
+        return refusal(PROMOTE_GUARD.WRITE_TARGET, ERROR_REASON.VAULT_PROMOTE_TARGET_REFUSED, `${NOT_PROMOTED} no client vault repository is configured. Check client.vaultRepo in .platform-bindings.json and run the promotion again.`);
+    }
+    const rawRef = client && typeof client.vaultRef === 'string' ? client.vaultRef : '';
+    const flagShaped = [['client.vaultRepo', repo], ['client.vaultRef', rawRef]].find(([, v]) => v.trim().startsWith('-'));
+    if (flagShaped) {
+        return refusal(PROMOTE_GUARD.WRITE_TARGET, ERROR_REASON.VAULT_PROMOTE_TARGET_REFUSED, `${NOT_PROMOTED} ${flagShaped[0]} starts with "-", which git would read as an option. Fix it in .platform-bindings.json and run the promotion again.`);
+    }
+    const ref = rawRef.trim() !== '' ? rawRef.trim() : 'main';
+    const providerResolution = (0, git_provider_cjs_1.resolveProvider)(cwd);
+    const provider = providerResolution.provider;
+    const notes = providerResolution.warnings.slice();
+    const clientCoord = (0, vault_coordinates_cjs_1.resolveClientCoordinates)(cwd, provider);
+    const host = clientCoord.host;
+    notes.push(...clientCoord.warnings);
+    if (!(0, git_provider_cjs_1.isLiteralCloneTarget)(repo.trim()))
+        notes.push(...(0, git_provider_cjs_1.composeCloneTarget)(provider, repo, host).warnings);
+    try {
+        vault.assertVaultWriteTarget(cwd, repo, host);
+    }
+    catch (e) {
+        const msg = (e instanceof Error ? e.message : String(e)).replace(/^vault write refused:\s*/, '');
+        return refusal(PROMOTE_GUARD.WRITE_TARGET, ERROR_REASON.VAULT_PROMOTE_TARGET_REFUSED, `${NOT_PROMOTED} ${msg} Check client.vaultRepo in .platform-bindings.json and run the promotion again.`);
+    }
+    return {
+        status: 'ok',
+        raw,
+        destination,
+        entry: typeof entry === 'string' ? entry.trim() : null,
+        section: typeof section === 'string' ? section.trim() : null,
+        repo,
+        ref,
+        host,
+        provider,
+        notes,
+    };
+}
+// ─── The INDEX.md edit ───────────────────────────────────────────────────────
+/** The INDEX line for one document, in the grammar vault-index owns. */
+function formatIndexEntry(destination, entry) {
+    return `${vaultIndexLeaf.VAULT_ENTRY_PREFIX}${destination}\`${vaultIndexLeaf.VAULT_ENTRY_SEPARATOR}${entry}`;
+}
+/**
+ * The INDEX.md text after this promotion, decided from the vault's current
+ * INDEX (`null` when the vault has none). A listed document keeps its line
+ * unless a new entry text is given, which replaces it in place. An unlisted
+ * document needs an entry text: its line is appended after the last entry of
+ * `section` (a new `## section` at the end when that section does not exist),
+ * or at the end of the file when no section is named. The result is parsed
+ * back: the new line must read back as written and every other entry must be
+ * unchanged, or nothing is written.
+ */
+function editIndex(current, destination, entry, section) {
+    const before = vaultIndexLeaf.parseVaultIndex(current ?? '');
+    const listed = before.entries.filter((e) => e.path === destination);
+    if (listed.length > 1) {
+        return { ok: false, message: `INDEX.md lists ${destination} ${listed.length} times; fix the vault's INDEX.md first` };
+    }
+    const eol = current !== null && current.includes('\r\n') ? '\r\n' : '\n';
+    const lines = current === null ? [] : current.split(/\r?\n/);
+    let change;
+    if (listed.length === 1) {
+        if (entry === null)
+            return { ok: true, text: current, change: 'unchanged' };
+        const line = formatIndexEntry(destination, entry);
+        if (lines[listed[0].line - 1] === line)
+            return { ok: true, text: current, change: 'unchanged' };
+        lines[listed[0].line - 1] = line;
+        change = 'replaced';
+    }
+    else {
+        if (entry === null) {
+            return {
+                ok: false,
+                message: `the vault's INDEX.md does not list ${destination} yet, so --entry "<what it is>; used when <…>" is required`,
+            };
+        }
+        const line = formatIndexEntry(destination, entry);
+        if (lines.length === 0)
+            lines.push('# Index', '');
+        while (lines.length > 0 && lines[lines.length - 1] === '')
+            lines.pop();
+        const inSection = section === null ? [] : before.entries.filter((e) => e.section === section);
+        if (inSection.length > 0) {
+            lines.splice(inSection[inSection.length - 1].line, 0, line);
+        }
+        else if (section !== null) {
+            lines.push('', `${vaultIndexLeaf.VAULT_SECTION_HEADING_PREFIX}${section}`, '', line);
+        }
+        else {
+            lines.push(line);
+        }
+        lines.push('');
+        change = 'added';
+    }
+    const text = lines.join(eol);
+    const after = vaultIndexLeaf.parseVaultIndex(text);
+    const mine = after.entries.filter((e) => e.path === destination);
+    const others = (p) => JSON.stringify(p.entries.filter((e) => e.path !== destination)
+        .map((e) => [e.section, e.path, e.description, e.usedWhen ?? null]));
+    const expectedEntry = entry ?? '';
+    const readsBack = mine.length === 1
+        && (entry === null || `${mine[0].description}${vaultIndexLeaf.VAULT_USED_WHEN_MARKER}${mine[0].usedWhen ?? ''}` === normaliseEntry(expectedEntry))
+        && others(after) === others(before)
+        && after.diagnostics.length <= before.diagnostics.length;
+    if (!readsBack) {
+        return { ok: false, message: 'the edited INDEX.md would not read back as written; fix the vault\'s INDEX.md or the entry text' };
+    }
+    return { ok: true, text, change };
+}
+/** An entry text in the parser's own normal form: description, the canonical marker, the clause. */
+function normaliseEntry(entry) {
+    const m = vaultIndexLeaf.VAULT_USED_WHEN_RE.exec(entry);
+    if (!m)
+        return entry.trim();
+    return `${entry.slice(0, m.index).trim()}${vaultIndexLeaf.VAULT_USED_WHEN_MARKER}${entry.slice(m.index + m[0].length).trim()}`;
+}
+// ─── The two runs ────────────────────────────────────────────────────────────
+const sha256 = (s) => (s === null ? 'absent' : node_crypto_1.default.createHash('sha256').update(s).digest('hex'));
+/**
+ * The opaque `expect` token: what was confirmed locally (the document, the
+ * entry and the section) and what the vault held for the document and for
+ * INDEX.md at preview time. Four hashes, dot-separated; callers treat it as
+ * opaque.
+ */
+function buildExpectToken(pre, remoteDocument, remoteIndex) {
+    const local = sha256(`${pre.raw}\u0000${pre.entry ?? ''}\u0000${pre.section ?? ''}\u0000${pre.destination}`);
+    return `${local}.${sha256(remoteDocument)}.${sha256(remoteIndex)}`;
+}
+function transportRefusal(res) {
+    const cause = boundedToken((res.stderr || '').split(/\r?\n/)[0] || 'unknown error');
+    return refusal(PROMOTE_GUARD.TRANSPORT, ERROR_REASON.VAULT_PROMOTE_TRANSPORT_FAILED, `${NOT_PUSHED} git could not reach the vault (${cause}). Check your access to the vault and run the promotion again.`);
+}
+function readOrNull(abs) {
+    return node_fs_1.default.existsSync(abs) ? node_fs_1.default.readFileSync(abs, 'utf-8') : null;
+}
+/** Clone the client vault at its ref into a fresh disposable directory. */
+function cloneVault(gitExec, pre, prefix) {
+    const dir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), prefix));
+    const cl = gitExec(['clone', '--branch', pre.ref, '--single-branch', '--', (0, git_provider_cjs_1.composeCloneTarget)(pre.provider, pre.repo, pre.host).url, dir], { timeout: 120_000 });
+    if (cl.exitCode !== 0) {
+        node_fs_1.default.rmSync(dir, { recursive: true, force: true });
+        return transportRefusal(cl);
+    }
+    return { dir };
+}
+/** Write the document and the INDEX change into a clone; the planned index text comes from `editIndex`. */
+function applyToClone(dir, pre, indexText) {
+    const docAbs = node_path_1.default.join(dir, pre.destination);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(docAbs), { recursive: true });
+    node_fs_1.default.writeFileSync(docAbs, pre.raw, 'utf-8');
+    if (indexText !== null)
+        node_fs_1.default.writeFileSync(node_path_1.default.join(dir, vaultIndexLeaf.VAULT_INDEX_FILENAME), indexText, 'utf-8');
+}
+function previewPromotion(opts, vault) {
+    const gitExec = opts._exec ?? shell_command_projection_cjs_1.execGitLocal;
+    const pre = promotePreflight(opts, vault);
+    if (pre.status !== 'ok')
+        return pre;
+    const cloned = cloneVault(gitExec, pre, 'pp-vault-promote-');
+    if ('status' in cloned)
+        return cloned;
+    try {
+        const docAbs = node_path_1.default.join(cloned.dir, pre.destination);
+        const remoteDocument = readOrNull(docAbs);
+        const remoteIndex = readOrNull(node_path_1.default.join(cloned.dir, vaultIndexLeaf.VAULT_INDEX_FILENAME));
+        const edit = editIndex(remoteIndex, pre.destination, pre.entry, pre.section);
+        if (!edit.ok) {
+            return refusal(PROMOTE_GUARD.VALIDATION, ERROR_REASON.VAULT_PROMOTE_INVALID_DOCUMENT, `${NOT_PROMOTED} ${edit.message}.`);
+        }
+        applyToClone(cloned.dir, pre, edit.change === 'unchanged' ? null : edit.text);
+        // A new file shows in the diff only once git knows its path.
+        gitExec(['add', '--intent-to-add', '--', pre.destination, vaultIndexLeaf.VAULT_INDEX_FILENAME], { cwd: cloned.dir });
+        const diffRes = gitExec(['-c', 'core.quotepath=off', 'diff', '--', pre.destination, vaultIndexLeaf.VAULT_INDEX_FILENAME], { cwd: cloned.dir });
+        return {
+            status: 'preview',
+            repo: vault.redactCloneTarget(pre.repo),
+            ref: pre.ref,
+            destination: pre.destination,
+            mode: remoteDocument === null ? 'create' : 'update',
+            indexChange: edit.change,
+            diff: diffRes.stdout,
+            expect: buildExpectToken(pre, remoteDocument, remoteIndex),
+            notes: pre.notes,
+        };
+    }
+    finally {
+        node_fs_1.default.rmSync(cloned.dir, { recursive: true, force: true });
+    }
+}
+function confirmPromotion(opts, vault) {
+    const gitExec = opts._exec ?? shell_command_projection_cjs_1.execGitLocal;
+    // Never trust the preview: every guard runs again.
+    const pre = promotePreflight(opts, vault);
+    if (pre.status !== 'ok')
+        return pre;
+    const expect = opts.expect;
+    if (typeof expect !== 'string' || expect === '') {
+        return refusal(PROMOTE_GUARD.CONCURRENT_EDIT, ERROR_REASON.VAULT_PROMOTE_CONCURRENT_EDIT, `${NOT_PUSHED} the confirmation is missing the preview token. Run the promotion without --confirmed first, then pass the token it prints.`);
+    }
+    const [pinnedLocal, pinnedDocument, pinnedIndex] = expect.split('.');
+    if (pinnedLocal !== sha256(`${pre.raw}\u0000${pre.entry ?? ''}\u0000${pre.section ?? ''}\u0000${pre.destination}`)) {
+        return refusal(PROMOTE_GUARD.CONCURRENT_EDIT, ERROR_REASON.VAULT_PROMOTE_CONCURRENT_EDIT, `${NOT_PUSHED} the document, the entry text or the vault path changed after the preview. Run the promotion again to preview the new version.`);
+    }
+    const cloned = cloneVault(gitExec, pre, 'pp-vault-confirm-');
+    if ('status' in cloned)
+        return cloned;
+    try {
+        const dir = cloned.dir;
+        const ft = gitExec(['fetch', 'origin', pre.ref], { cwd: dir, timeout: 120_000 });
+        if (ft.exitCode !== 0)
+            return transportRefusal(ft);
+        const pull = gitExec(['pull', '--ff-only', 'origin', pre.ref], { cwd: dir, timeout: 120_000 });
+        if (pull.exitCode !== 0)
+            return transportRefusal(pull);
+        // Byte-exact reads from the working tree, never trimmed git stdout.
+        const remoteDocument = readOrNull(node_path_1.default.join(dir, pre.destination));
+        const remoteIndex = readOrNull(node_path_1.default.join(dir, vaultIndexLeaf.VAULT_INDEX_FILENAME));
+        if (sha256(remoteDocument) !== pinnedDocument || sha256(remoteIndex) !== pinnedIndex) {
+            return refusal(PROMOTE_GUARD.CONCURRENT_EDIT, ERROR_REASON.VAULT_PROMOTE_CONCURRENT_EDIT, `${NOT_PUSHED} someone changed ${boundedToken(pre.destination)} or INDEX.md in the vault since the preview. Run the promotion again to see their version before you push.`);
+        }
+        const edit = editIndex(remoteIndex, pre.destination, pre.entry, pre.section);
+        if (!edit.ok) {
+            return refusal(PROMOTE_GUARD.VALIDATION, ERROR_REASON.VAULT_PROMOTE_INVALID_DOCUMENT, `${NOT_PROMOTED} ${edit.message}.`);
+        }
+        applyToClone(dir, pre, edit.change === 'unchanged' ? null : edit.text);
+        const add = gitExec(['add', '--', pre.destination, vaultIndexLeaf.VAULT_INDEX_FILENAME], { cwd: dir });
+        if (add.exitCode !== 0)
+            return transportRefusal(add);
+        const idCheck = gitExec(['config', 'user.email'], { cwd: dir });
+        if (idCheck.exitCode !== 0 || !idCheck.stdout.trim()) {
+            gitExec(['config', 'user.email', 'pp-core-vault-promote@pareto.local'], { cwd: dir });
+            gitExec(['config', 'user.name', 'pp-core vault promote'], { cwd: dir });
+        }
+        const mode = remoteDocument === null ? 'create' : 'update';
+        const message = `standards(${mode}): ${boundedToken(pre.destination)}\n\nPromoted from a project with pp-tools vault standards promote.`;
+        const commitRes = gitExec(['commit', '-m', message], { cwd: dir });
+        if (commitRes.exitCode !== 0)
+            return transportRefusal(commitRes);
+        // One push, no force flag on any path; a non-fast-forward is the backstop.
+        const push = gitExec(['push', 'origin', `HEAD:${pre.ref}`], { cwd: dir, timeout: 120_000 });
+        if (push.exitCode !== 0) {
+            return refusal(PROMOTE_GUARD.TRANSPORT, ERROR_REASON.VAULT_PROMOTE_TRANSPORT_FAILED, `${NOT_PUSHED} the vault moved ahead while the push was running. Run the promotion again to preview against the current version.`);
+        }
+        const commit = gitExec(['rev-parse', '--short', 'HEAD'], { cwd: dir }).stdout.trim();
+        // Refresh the local cache: clear only the staleness marker so the fetch
+        // cannot short-circuit on the pre-promotion manifest.
+        try {
+            node_fs_1.default.rmSync(node_path_1.default.join(opts.cwd, '.planning', 'vault', '.manifest.json'), { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+        let cacheRefreshed = false;
+        try {
+            const manifest = vault.vaultFetch(opts.cwd);
+            cacheRefreshed = !!manifest && manifest.source === 'fetched';
+        }
+        catch {
+            cacheRefreshed = false;
+        }
+        const notes = pre.notes.slice();
+        if (!cacheRefreshed)
+            notes.push('the local copy could not be refreshed; the next fetch will pick it up');
+        return {
+            status: 'pushed',
+            repo: vault.redactCloneTarget(pre.repo),
+            ref: pre.ref,
+            destination: pre.destination,
+            mode,
+            indexChange: edit.change,
+            commit,
+            cacheRefreshed,
+            notes,
+        };
+    }
+    finally {
+        node_fs_1.default.rmSync(cloned.dir, { recursive: true, force: true });
+    }
+}
+/** The one entry point the router calls: the preview, or the confirmed push. */
+function promoteStandard(opts) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const vault = opts._vault ?? require('./vault.cjs');
+    return opts.confirmed ? confirmPromotion(opts, vault) : previewPromotion(opts, vault);
+}
+// ─── Report rendering ────────────────────────────────────────────────────────
+/**
+ * Plain-English rendering for the non-`--raw` CLI path. A preview states the
+ * vault, the destination, what changes in INDEX.md, the secret-scan result,
+ * the token line, and the COMPLETE diff, never elided: the operator confirms
+ * exactly these bytes. The token is printed unbounded because it must be
+ * copied verbatim.
+ */
+function renderPromoteReport(verdict) {
+    if (verdict.status === 'refused')
+        return verdict.message;
+    const indexLine = {
+        added: 'INDEX.md gains a line for it.',
+        replaced: 'Its INDEX.md line is replaced with the new entry text.',
+        unchanged: 'INDEX.md already lists it and stays as it is.',
+    };
+    if (verdict.status === 'preview') {
+        const lines = [
+            `This promotes ${boundedToken(verdict.destination)} to ${boundedToken(verdict.repo)} (${boundedToken(verdict.ref)}).`,
+            `It ${verdict.mode === 'create' ? 'creates a new' : 'updates an existing'} standards document. ${indexLine[verdict.indexChange]}`,
+            'The secret scan found nothing to flag.',
+            `To push this, run the promotion again with --confirmed --expect ${verdict.expect}.`,
+            ...verdict.notes.map((n) => `Note: ${boundedToken(n, 200)}`),
+            '',
+            '## Full diff',
+            verdict.diff.length > 0 ? verdict.diff : '(no changes)',
+        ];
+        return lines.join('\n');
+    }
+    return [
+        `Pushed ${boundedToken(verdict.destination)} to ${boundedToken(verdict.repo)} (${boundedToken(verdict.ref)}) — commit ${boundedToken(verdict.commit)}. ${indexLine[verdict.indexChange]}`,
+        verdict.cacheRefreshed
+            ? 'Your local copy was refreshed with the new content.'
+            : 'Your local copy was not refreshed automatically; the next fetch will pick it up.',
+        ...verdict.notes.map((n) => `Note: ${boundedToken(n, 200)}`),
+    ].join('\n');
+}
+module.exports = {
+    SECRET_SHAPES,
+    scanForSecrets,
+    PROMOTE_GUARD,
+    DEFAULT_VAULT_DIR,
+    promotePreflight,
+    editIndex,
+    formatIndexEntry,
+    buildExpectToken,
+    promoteStandard,
+    renderPromoteReport,
+};