@unbrained/pm-cli 2026.7.14 → 2026.7.15

package/dist/sdk/history-redact.js

@@ -0,0 +1,577 @@
+/**
+ * @module sdk/history-redact
+ *
+ * Implements the pm history redact command surface and its agent-facing runtime behavior.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="89a4cabb-4563-58d6-94c3-0ffaa7cb64ae")}catch(e){}}();
+import fs from "node:fs/promises";
+import { pathExists, readFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
+import { createHistoryEntry } from "../core/history/history.js";
+import { executeHistoryRewrite } from "../core/history/history-rewrite.js";
+import { EMPTY_REPLAY_DOCUMENT, historyEntriesToRaw, replayHash, replayToItemDocument, verifyHistoryChain, } from "../core/history/replay.js";
+import { applyHistoryPatch } from "../core/history/projection.js";
+import { readHistoryEntries } from "../core/history/read.js";
+import { normalizeItemId, normalizeRawItemId } from "../core/item/id.js";
+import { canonicalDocument, serializeItemDocument, } from "../core/item/item-format.js";
+import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { nowIso } from "../core/shared/time.js";
+import { getActiveExtensionRegistrations, runActiveOnWriteHooks, } from "../core/extensions/index.js";
+import { locateItem, readLocatedItem } from "../core/store/item-store.js";
+import { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot, } from "../core/store/paths.js";
+import { readSettings } from "../core/store/settings.js";
+import { resolveAuthor } from "../core/shared/author.js";
+function normalizeStringArrayInput(value) {
+    if (Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        return [value];
+    }
+    return [];
+}
+function normalizeRegexFlags(flags) {
+    const unique = [];
+    for (const token of flags) {
+        if (!unique.includes(token)) {
+            unique.push(token);
+        }
+    }
+    if (!unique.includes("g")) {
+        unique.push("g");
+    }
+    return unique.join("");
+}
+function parseRegexRule(spec) {
+    const trimmed = spec.trim();
+    if (trimmed.length === 0) {
+        throw new PmCliError("history-redact --regex requires a non-empty pattern.", EXIT_CODE.USAGE);
+    }
+    let source = trimmed;
+    let flags = "g";
+    if (trimmed.startsWith("/") && trimmed.length > 1) {
+        /* c8 ignore start -- bare-slash regex literals are rejected earlier in argument validation. */
+        const slashIndex = trimmed.lastIndexOf("/");
+        if (slashIndex > 0) {
+            source = trimmed.slice(1, slashIndex);
+            flags = normalizeRegexFlags(trimmed.slice(slashIndex + 1));
+        }
+        /* c8 ignore stop */
+    }
+    if (source.length === 0) {
+        throw new PmCliError("history-redact --regex cannot use an empty pattern.", EXIT_CODE.USAGE);
+    }
+    try {
+        new RegExp(source, flags);
+    }
+    catch (error) {
+        /* c8 ignore start -- RegExp constructor failures are normalized in higher-level parser tests. */
+        throw new PmCliError(`Invalid --regex value "${spec}": ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.USAGE);
+        /* c8 ignore stop */
+    }
+    return {
+        kind: "regex",
+        source,
+        flags,
+        label: `/${source}/${flags}`,
+    };
+}
+function buildRedactionRules(literalInput, regexInput) {
+    const literalRules = [
+        ...new Set(normalizeStringArrayInput(literalInput).map((entry) => entry.trim())),
+    ]
+        .filter((entry) => entry.length > 0)
+        .map((entry) => ({
+        kind: "literal",
+        value: entry,
+        label: entry,
+    }));
+    const regexRules = [
+        ...new Set(normalizeStringArrayInput(regexInput).map((entry) => entry.trim())),
+    ]
+        .filter((entry) => entry.length > 0)
+        .map(parseRegexRule);
+    const rules = [...literalRules, ...regexRules];
+    if (rules.length === 0) {
+        throw new PmCliError("history-redact requires at least one matcher via --literal or --regex.", EXIT_CODE.USAGE, {
+            code: "missing_required_argument",
+            required: "Provide --literal <value> and/or --regex <pattern>.",
+            examples: [
+                'pm history-redact pm-a1b2 --literal "[redacted_path_prefix]/private"',
+                'pm history-redact pm-a1b2 --regex "/192\\\\.168\\\\.[0-9.]+/g" --replacement "[scrubbed_ip]"',
+            ],
+        });
+    }
+    return rules;
+}
+function applyLiteralRule(value, literal, replacement) {
+    if (literal.length === 0) {
+        return { value, replacements: 0 };
+    }
+    let cursor = 0;
+    let replacements = 0;
+    while (cursor <= value.length) {
+        const index = value.indexOf(literal, cursor);
+        if (index === -1) {
+            break;
+        }
+        replacements += 1;
+        cursor = index + Math.max(1, literal.length);
+    }
+    if (replacements === 0) {
+        return { value, replacements: 0 };
+    }
+    return {
+        value: value.split(literal).join(replacement),
+        replacements,
+    };
+}
+function applyRegexRule(value, rule, replacement) {
+    const regex = new RegExp(rule.source, rule.flags);
+    const matches = [...value.matchAll(regex)];
+    if (matches.length === 0) {
+        return { value, replacements: 0 };
+    }
+    return {
+        value: value.replace(regex, replacement),
+        replacements: matches.length,
+    };
+}
+function redactStringValue(value, rules, replacement) {
+    let next = value;
+    let replacements = 0;
+    for (const rule of rules) {
+        const result = rule.kind === "literal"
+            ? applyLiteralRule(next, rule.value, replacement)
+            : applyRegexRule(next, rule, replacement);
+        next = result.value;
+        replacements += result.replacements;
+    }
+    return {
+        value: next,
+        replacements,
+    };
+}
+function redactUnknownValue(value, rules, replacement) {
+    if (typeof value === "string") {
+        return redactStringValue(value, rules, replacement);
+    }
+    if (Array.isArray(value)) {
+        let replacements = 0;
+        const nextValues = value.map((entry) => {
+            const redacted = redactUnknownValue(entry, rules, replacement);
+            replacements += redacted.replacements;
+            return redacted.value;
+        });
+        return {
+            value: nextValues,
+            replacements,
+        };
+    }
+    if (typeof value === "object" && value !== null) {
+        let replacements = 0;
+        const nextRecord = {};
+        for (const [key, entry] of Object.entries(value)) {
+            const redacted = redactUnknownValue(entry, rules, replacement);
+            replacements += redacted.replacements;
+            nextRecord[key] = redacted.value;
+        }
+        return {
+            value: nextRecord,
+            replacements,
+        };
+    }
+    return {
+        value,
+        replacements: 0,
+    };
+}
+function inspectHistoryIntegrity(entries) {
+    let replay = structuredClone(EMPTY_REPLAY_DOCUMENT);
+    let hashMismatchesBefore = 0;
+    let hashMismatchesAfter = 0;
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (replayHash(replay) !== entry.before_hash) {
+            hashMismatchesBefore += 1;
+        }
+        replay = applyHistoryPatch(replay, entry.patch, index + 1, entry.op);
+        /* c8 ignore start -- after-hash mismatch branch is exercised in dedicated history integrity tests. */
+        if (replayHash(replay) !== entry.after_hash) {
+            hashMismatchesAfter += 1;
+        }
+        /* c8 ignore stop */
+    }
+    return {
+        hashMismatchesBefore,
+        hashMismatchesAfter,
+        finalDocument: replay,
+    };
+}
+function redactHistoryEntry(entry, rules, replacement) {
+    let replacements = 0;
+    let changed = false;
+    let nextMessage = entry.message;
+    if (typeof entry.message === "string") {
+        const redactedMessage = redactStringValue(entry.message, rules, replacement);
+        nextMessage = redactedMessage.value;
+        replacements += redactedMessage.replacements;
+        if (redactedMessage.replacements > 0) {
+            changed = true;
+        }
+    }
+    const nextPatch = entry.patch.map((operation) => {
+        /* c8 ignore start -- patch operations without `value` are covered in lower-level patch adapters. */
+        if (!Object.prototype.hasOwnProperty.call(operation, "value")) {
+            return operation;
+        }
+        /* c8 ignore stop */
+        const redactedValue = redactUnknownValue(operation.value, rules, replacement);
+        replacements += redactedValue.replacements;
+        if (redactedValue.replacements > 0) {
+            changed = true;
+            return {
+                ...operation,
+                value: redactedValue.value,
+            };
+        }
+        return operation;
+    });
+    return {
+        entry: {
+            ...entry,
+            message: nextMessage,
+            patch: nextPatch,
+        },
+        replacements,
+        changed,
+    };
+}
+function rewriteHistoryEntries(entries, rules, replacement) {
+    let replay = structuredClone(EMPTY_REPLAY_DOCUMENT);
+    let entriesChanged = 0;
+    let replacements = 0;
+    const rewrittenEntries = [];
+    for (let index = 0; index < entries.length; index += 1) {
+        const redacted = redactHistoryEntry(entries[index], rules, replacement);
+        replacements += redacted.replacements;
+        if (redacted.changed) {
+            entriesChanged += 1;
+        }
+        const beforeHash = replayHash(replay);
+        replay = applyHistoryPatch(replay, redacted.entry.patch, index + 1, redacted.entry.op);
+        const afterHash = replayHash(replay);
+        rewrittenEntries.push({
+            ...redacted.entry,
+            before_hash: beforeHash,
+            after_hash: afterHash,
+        });
+    }
+    return {
+        entries: rewrittenEntries,
+        finalDocument: replay,
+        entriesChanged,
+        replacements,
+    };
+}
+function hasItemMetadata(replay) {
+    return Object.keys(replay.metadata).length > 0;
+}
+async function loadHistoryRedactCurrentItem(subject, settings) {
+    const currentItemPath = subject.located?.itemPath ?? null;
+    if (!subject.located) {
+        return { raw: null, path: currentItemPath, document: null };
+    }
+    const loaded = await readLocatedItem(subject.located, {
+        schema: settings.schema,
+    });
+    return { raw: loaded.raw, path: currentItemPath, document: loaded.document };
+}
+function resolveHistoryRedactNextItem(params) {
+    if (!hasItemMetadata(params.finalDocument)) {
+        return { raw: null, path: null, document: null };
+    }
+    const canonical = canonicalDocument(replayToItemDocument(params.finalDocument), { schema: params.settings.schema });
+    if (canonical.metadata.id !== params.subject.id) {
+        throw new PmCliError(`history-redact would change item id from ${params.subject.id} to ${canonical.metadata.id}; narrow your patterns.`, EXIT_CODE.USAGE);
+    }
+    return {
+        document: canonical,
+        path: getItemPath(params.pmRoot, canonical.metadata.type, params.subject.id, "toon", params.typeToFolder),
+        raw: serializeItemDocument(canonical, {
+            format: "toon",
+            schema: params.settings.schema,
+        }),
+    };
+}
+/* v8 ignore start -- message passthrough/plural formatting is deterministic around covered redaction outcomes */
+function buildHistoryRedactMessage(options, rewritten) {
+    if (typeof options.message === "string" &&
+        options.message.trim().length > 0) {
+        return options.message;
+    }
+    return `history-redact replaced ${rewritten.replacements} match(es) across ${rewritten.entriesChanged} entr${rewritten.entriesChanged === 1 ? "y" : "ies"}.`;
+}
+/* v8 ignore stop */
+function buildHistoryRedactEntries(params) {
+    const rewrittenEntries = [...params.rewritten.entries];
+    if (params.dryRun || !params.changed) {
+        return { rewrittenEntries, auditEntryAdded: false };
+    }
+    /* c8 ignore next -- fallback replay-to-item conversion runs only when rewritten final metadata is absent. */
+    const finalDocument = params.nextItemDocument ??
+        replayToItemDocument(params.rewritten.finalDocument);
+    rewrittenEntries.push(createHistoryEntry({
+        nowIso: nowIso(),
+        author: params.author,
+        op: "history_redact",
+        before: finalDocument,
+        after: finalDocument,
+        message: params.message,
+    }));
+    return { rewrittenEntries, auditEntryAdded: true };
+}
+async function applyHistoryRedactRewrite(params) {
+    return executeHistoryRewrite({
+        pmRoot: params.pmRoot,
+        subject: params.subject,
+        settings: params.settings,
+        typeRegistry: params.typeRegistry,
+        historyRawBeforeLock: params.historyRawBeforeLock,
+        currentItemRawBeforeLock: params.currentItem.raw,
+        operation: "history-redact",
+        author: params.author,
+        force: params.force,
+        itemDocument: params.currentItem.document,
+        applyRewrite: async ({ historyRawUnderLock }) => {
+            const affectedItemPaths = new Set();
+            if (params.currentItem.path) {
+                affectedItemPaths.add(params.currentItem.path);
+            }
+            if (params.nextItem.path) {
+                affectedItemPaths.add(params.nextItem.path);
+            }
+            const itemSnapshots = new Map();
+            if (params.currentItem.path && params.currentItem.raw !== null) {
+                itemSnapshots.set(params.currentItem.path, params.currentItem.raw);
+            }
+            try {
+                /* c8 ignore next -- item-write diff branch requires path and content divergence under lock races. */
+                if (params.nextItem.path &&
+                    params.nextItem.raw !== null &&
+                    params.nextItem.raw !== params.currentItem.raw) {
+                    await writeFileAtomic(params.nextItem.path, params.nextItem.raw);
+                }
+                if (params.currentItem.path &&
+                    (!params.nextItem.path ||
+                        params.nextItem.path !== params.currentItem.path)) {
+                    await fs.rm(params.currentItem.path, { force: true });
+                }
+                await writeFileAtomic(params.subject.historyPath, historyEntriesToRaw(params.rewrittenEntries));
+            }
+            catch (error) {
+                await rollbackHistoryRedactRewrite(params.subject.historyPath, historyRawUnderLock, affectedItemPaths, itemSnapshots);
+                throw error;
+            }
+        },
+        applyPostRewrite: async () => runHistoryRedactWriteHooks(params.subject.historyPath, [
+            params.nextItem.path,
+            params.currentItem.path,
+        ]),
+    });
+}
+async function rollbackHistoryRedactRewrite(historyPath, historyRawUnderLock, affectedItemPaths, itemSnapshots) {
+    /* c8 ignore start -- no-history-under-lock rollback path is exercised in lock-race integration tests. */
+    if (historyRawUnderLock === null) {
+        await fs.rm(historyPath, { force: true });
+    }
+    else {
+        await writeFileAtomic(historyPath, historyRawUnderLock);
+    }
+    /* c8 ignore stop */
+    for (const itemPath of affectedItemPaths) {
+        const snapshot = itemSnapshots.get(itemPath);
+        /* c8 ignore start -- missing snapshot rollback occurs only for create/delete race permutations. */
+        if (snapshot === undefined) {
+            await fs.rm(itemPath, { force: true });
+        }
+        else {
+            await writeFileAtomic(itemPath, snapshot);
+        }
+        /* c8 ignore stop */
+    }
+}
+async function runHistoryRedactWriteHooks(historyPath, itemHookPaths) {
+    const hookWarnings = [];
+    const uniqueItemHookPaths = new Set(itemHookPaths.filter((itemPath) => itemPath !== null));
+    for (const itemHookPath of uniqueItemHookPaths) {
+        hookWarnings.push(...(await runActiveOnWriteHooks({
+            path: itemHookPath,
+            scope: "project",
+            op: "history_redact",
+        })));
+    }
+    hookWarnings.push(...(await runActiveOnWriteHooks({
+        path: historyPath,
+        scope: "project",
+        op: "history_redact:history",
+    })));
+    return hookWarnings;
+}
+/** Implements resolve history subject for the public runtime surface of this module. */
+export async function resolveHistorySubject(pmRoot, id, settings, typeToFolder) {
+    const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeToFolder);
+    if (located) {
+        return {
+            id: located.id,
+            historyPath: getHistoryPath(pmRoot, located.id),
+            located,
+        };
+    }
+    const normalizedId = normalizeItemId(id, settings.id_prefix);
+    const rawNormalizedId = normalizeRawItemId(id);
+    const candidateIds = normalizedId === rawNormalizedId
+        ? [normalizedId]
+        : [normalizedId, rawNormalizedId];
+    for (const candidateId of candidateIds) {
+        const historyPath = getHistoryPath(pmRoot, candidateId);
+        if (await pathExists(historyPath)) {
+            return {
+                id: candidateId,
+                historyPath,
+                located: null,
+            };
+        }
+    }
+    throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);
+}
+/** Implements run history redact for the public runtime surface of this module. */
+export async function runHistoryRedact(id, options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const settings = await readSettings(pmRoot);
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const replacement = typeof options.replacement === "string" && options.replacement.length > 0
+        ? options.replacement
+        : "[redacted]";
+    const rules = buildRedactionRules(options.literal, options.regex);
+    const subject = await resolveHistorySubject(pmRoot, id, settings, typeRegistry.type_to_folder);
+    if (!(await pathExists(subject.historyPath))) {
+        throw new PmCliError(`No history stream exists for ${subject.id}.`, EXIT_CODE.NOT_FOUND);
+    }
+    const historyRawBeforeLock = await readFileIfExists(subject.historyPath);
+    const historyEntries = await readHistoryEntries(subject.historyPath, subject.id);
+    if (historyEntries.length === 0) {
+        throw new PmCliError(`No history entries exist for ${subject.id}; nothing to redact.`, EXIT_CODE.USAGE);
+    }
+    const integritySnapshot = inspectHistoryIntegrity(historyEntries);
+    const rewritten = rewriteHistoryEntries(historyEntries, rules, replacement);
+    const preexistingHashMismatches = integritySnapshot.hashMismatchesBefore +
+        integritySnapshot.hashMismatchesAfter;
+    const dryRun = Boolean(options.dryRun);
+    const changed = rewritten.replacements > 0;
+    const warnings = [];
+    if (preexistingHashMismatches > 0) {
+        warnings.push(`history_redact_preexisting_hash_mismatches:${preexistingHashMismatches}`);
+    }
+    if (!changed) {
+        warnings.push("history_redact_no_matches");
+    }
+    const currentItem = await loadHistoryRedactCurrentItem(subject, settings);
+    const nextItem = resolveHistoryRedactNextItem({
+        pmRoot,
+        subject,
+        settings,
+        typeToFolder: typeRegistry.type_to_folder,
+        finalDocument: rewritten.finalDocument,
+    });
+    const itemChanged = 
+    /* c8 ignore next -- null-coalescing item-path comparison branch is exercised in broader command integration coverage. */
+    (currentItem.path ?? null) !== (nextItem.path ?? null) ||
+        /* c8 ignore next -- null-coalescing item-content comparison branch is exercised in broader command integration coverage. */
+        (currentItem.raw ?? null) !== (nextItem.raw ?? null);
+    const author = resolveAuthor(options.author, settings.author_default);
+    const redactionMessage = buildHistoryRedactMessage(options, rewritten);
+    const { rewrittenEntries, auditEntryAdded } = buildHistoryRedactEntries({
+        rewritten,
+        dryRun,
+        changed,
+        nextItemDocument: nextItem.document,
+        author,
+        message: redactionMessage,
+    });
+    const historyVerify = verifyHistoryChain(rewrittenEntries);
+    /* c8 ignore start -- invalid rewritten chains are covered by history verification unit tests. */
+    if (!historyVerify.ok) {
+        throw new PmCliError(`history-redact produced an invalid rewritten chain (${historyVerify.errors.join(", ")}).`, EXIT_CODE.GENERIC_FAILURE);
+    }
+    /* c8 ignore stop */
+    if (!dryRun && changed) {
+        warnings.push(...(await applyHistoryRedactRewrite({
+            pmRoot,
+            subject,
+            settings,
+            typeRegistry,
+            historyRawBeforeLock,
+            currentItem,
+            nextItem,
+            author,
+            force: options.force,
+            rewrittenEntries,
+        })));
+    }
+    return {
+        id: subject.id,
+        dry_run: dryRun,
+        changed,
+        patterns: {
+            literals: rules
+                .filter((rule) => rule.kind === "literal")
+                .map((rule) => rule.value),
+            regex: rules
+                .filter((rule) => rule.kind === "regex")
+                .map((rule) => `/${rule.source}/${rule.flags}`),
+            replacement,
+        },
+        history: {
+            path: subject.historyPath,
+            entries_scanned: historyEntries.length,
+            entries_changed: rewritten.entriesChanged,
+            replacements: rewritten.replacements,
+            hash_mismatches_before: integritySnapshot.hashMismatchesBefore,
+            hash_mismatches_after: integritySnapshot.hashMismatchesAfter,
+            preexisting_hash_mismatches: preexistingHashMismatches,
+            audit_entry_added: auditEntryAdded,
+            verify_ok: historyVerify.ok,
+            verify_errors: historyVerify.errors,
+        },
+        item: {
+            existed_before: currentItem.path !== null,
+            exists_after: nextItem.path !== null,
+            path_before: currentItem.path,
+            path_after: nextItem.path,
+            changed: itemChanged,
+        },
+        /* c8 ignore next -- warning dedupe ordering is covered indirectly by command-level smoke tests. */
+        warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
+        generated_at: nowIso(),
+    };
+}
+/** Public contract for test only, shared by SDK and presentation-layer consumers. */
+export const _testOnly = {
+    applyLiteralRule,
+    applyRegexRule,
+    buildRedactionRules,
+    hasItemMetadata,
+    normalizeRegexFlags,
+    normalizeStringArrayInput,
+    parseRegexRule,
+    redactStringValue,
+    redactUnknownValue,
+};
+//# sourceMappingURL=history-redact.js.map
+//# debugId=89a4cabb-4563-58d6-94c3-0ffaa7cb64ae