@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/core/history/workspace-history.js

@@ -1,434 +1,3 @@
-/**
- * @module core/history/workspace-history
- *
- * Records singleton workspace documents in the same append-only, hash-chained
- * HistoryEntry format used by item mutations.
- */
-
-!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]="4df21a17-43c0-5b63-adf3-657699e6a058")}catch(e){}}();
-import fs from "node:fs/promises";
-import path from "node:path";
-import { readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
-import { acquireLock } from "../lock/lock.js";
-import { EMPTY_CANONICAL_DOCUMENT, EXIT_CODE } from "../shared/constants.js";
-import { PmCliError } from "../shared/errors.js";
-import { stableStringify } from "../shared/serialization.js";
-import { nowIso } from "../shared/time.js";
-import { appendHistoryEntry, createHistoryEntry } from "./history.js";
-import { readHistoryEntries } from "./read.js";
-import { cloneEmptyReplayDocument, replayToItemDocument, tryApplyReplayPatch, verifyHistoryChain, } from "./replay.js";
-/** Synthetic item id used to expose the singleton workspace audit stream. */
-export const WORKSPACE_HISTORY_ID = "_workspace";
-/** Return the canonical workspace history stream path. */
-export function getWorkspaceHistoryPath(pmRoot) {
-    return path.join(pmRoot, "history", `${WORKSPACE_HISTORY_ID}.jsonl`);
-}
-function workspaceDocument(documents, timestamp) {
-    const metadata = {
-        id: WORKSPACE_HISTORY_ID,
-        title: "Workspace state",
-        description: "Audited singleton workspace document state.",
-        type: "Chore",
-        status: "open",
-        priority: 2,
-        tags: ["workspace-history"],
-        created_at: timestamp,
-        updated_at: timestamp,
-        documents,
-    };
-    return { metadata, body: "" };
-}
-function replayWorkspaceEntries(entries, count = entries.length) {
-    let replay = cloneEmptyReplayDocument();
-    for (const entry of entries.slice(0, count)) {
-        const applied = tryApplyReplayPatch(replay, entry.patch);
-        replay = applied.document;
-    }
-    return replayToItemDocument(replay);
-}
-/** Read the governed document map from one replayed workspace document. */
-function workspaceDocuments(document) {
-    return "documents" in document.metadata &&
-        typeof document.metadata.documents === "object" &&
-        document.metadata.documents !== null &&
-        !Array.isArray(document.metadata.documents)
-        ? document.metadata.documents
-        : {};
-}
-/** Refuse a workspace mutation or replay whose append-only chain is invalid. */
-function throwWorkspaceHistoryVerificationFailure(errors) {
-    throw new PmCliError(`Workspace history verification failed: ${errors.join(", ")}`, EXIT_CODE.CONFLICT, {
-        code: "workspace_history_chain_invalid",
-        reason: "workspace_history_chain_verification_failed",
-        verification_errors: [...errors],
-        required: "Repair the _workspace history chain before reading, reconciling, restoring, or appending audited singleton state.",
-        why: "Continuing against an unverifiable append-only stream could hide or compound workspace state corruption.",
-        examples: [
-            "pm history _workspace --verify --json",
-            "pm validate --check-history-drift --fix-hints --json",
-        ],
-        nextSteps: [
-            "Inspect the exact verification_errors and preserve the corrupt stream as evidence.",
-            "Use the history-drift remediation returned by validate before retrying the refused operation.",
-        ],
-        recovery: {
-            recovery_mode: "compact",
-            next_best_command: "pm history _workspace --verify --json",
-        },
-    });
-}
-/** Resolve a governed singleton path and reject paths outside the tracker root. */
-function resolveGovernedDocumentPath(pmRoot, filePath) {
-    const absolutePath = path.resolve(filePath);
-    const documentPath = path.relative(pmRoot, absolutePath).replaceAll("\\", "/");
-    if (documentPath.length === 0 ||
-        documentPath === ".." ||
-        documentPath.startsWith("../") ||
-        path.isAbsolute(documentPath)) {
-        throw new TypeError("Workspace history document path must stay inside the tracker root");
-    }
-    return { documentPath, absolutePath };
-}
-/**
- * Compare every singleton represented by the verified workspace stream with
- * its current on-disk JSON. Hash-chain verification proves recorded ordering;
- * this state-agreement check separately proves that every current singleton
- * mutation is represented by that chain.
- */
-export async function inspectWorkspaceHistoryState(pmRoot) {
-    const entries = await readHistoryEntries(getWorkspaceHistoryPath(pmRoot), WORKSPACE_HISTORY_ID);
-    const verification = verifyHistoryChain(entries);
-    if (!verification.ok) {
-        throwWorkspaceHistoryVerificationFailure(verification.errors);
-    }
-    const documents = workspaceDocuments(entries.length === 0
-        ? EMPTY_CANONICAL_DOCUMENT
-        : replayWorkspaceEntries(entries));
-    const matching = [];
-    const mismatched = [];
-    const missing = [];
-    const unreadable = [];
-    for (const documentPath of Object.keys(documents).sort()) {
-        let raw;
-        try {
-            const resolved = resolveGovernedDocumentPath(pmRoot, path.resolve(pmRoot, documentPath));
-            raw = await readFileIfExists(resolved.absolutePath);
-            if (raw === null) {
-                missing.push(documentPath);
-                continue;
-            }
-            const current = JSON.parse(raw);
-            (stableStringify(current) === stableStringify(documents[documentPath])
-                ? matching
-                : mismatched).push(documentPath);
-        }
-        catch {
-            unreadable.push(documentPath);
-        }
-    }
-    return {
-        ok: mismatched.length === 0 &&
-            missing.length === 0 &&
-            unreadable.length === 0,
-        document_count: Object.keys(documents).length,
-        matching_documents: matching,
-        mismatched_documents: mismatched,
-        missing_documents: missing,
-        unreadable_documents: unreadable,
-    };
-}
-/**
- * Append one workspace document mutation while the caller holds the dedicated
- * workspace-history lock.
- */
-async function appendWorkspaceHistoryChangeLocked(change) {
-    const historyPath = getWorkspaceHistoryPath(change.pmRoot);
-    const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
-    const verification = verifyHistoryChain(entries);
-    if (!verification.ok) {
-        throwWorkspaceHistoryVerificationFailure(verification.errors);
-    }
-    const idempotentEntry = change.idempotencyKey === undefined
-        ? undefined
-        : entries.find((entry) => entry.op === `${change.op}:${change.idempotencyKey}`);
-    if (idempotentEntry) {
-        return { entry: idempotentEntry, historyPath };
-    }
-    const timestamp = nowIso();
-    const beforeDocument = entries.length === 0
-        ? EMPTY_CANONICAL_DOCUMENT
-        : replayWorkspaceEntries(entries);
-    const priorDocuments = workspaceDocuments(beforeDocument);
-    const recordedBefore = priorDocuments[change.documentPath];
-    if (recordedBefore !== undefined &&
-        stableStringify(recordedBefore) !== stableStringify(change.before)) {
-        throw new PmCliError(`Workspace history state for "${change.documentPath}" changed outside the audited mutation path.`, EXIT_CODE.CONFLICT, {
-            code: "workspace_history_state_conflict",
-            reason: "out_of_band_workspace_state",
-            required: "Reconcile the singleton document with its matching _workspace history state before retrying the mutation.",
-            why: "Accepting the write would make the append-only audit stream describe a state that was not actually observed.",
-            examples: [
-                "pm history _workspace --verify",
-                "pm validate --check-history-drift --fix-hints",
-            ],
-            nextSteps: [
-                "Review the version-control change that altered the singleton and preserve the intended document plus its matching workspace history.",
-                "Rerun the original mutation only after the on-disk singleton agrees with the latest audited workspace state.",
-            ],
-            recovery: {
-                recovery_mode: "compact",
-                next_best_command: "pm history _workspace --verify",
-            },
-        });
-    }
-    const afterDocument = workspaceDocument({ ...priorDocuments, [change.documentPath]: change.after }, entries.length === 0 ? timestamp : beforeDocument.metadata.created_at);
-    const entry = createHistoryEntry({
-        nowIso: timestamp,
-        author: change.author,
-        op: change.idempotencyKey === undefined
-            ? change.op
-            : `${change.op}:${change.idempotencyKey}`,
-        before: beforeDocument,
-        after: afterDocument,
-        message: change.message,
-    });
-    await appendHistoryEntry(historyPath, entry);
-    return { entry, historyPath };
-}
-/**
- * Append one workspace document mutation under the dedicated workspace-history
- * lock. Existing history is verified and replayed before the new entry is
- * derived, so concurrent writers cannot fork the chain.
- */
-export async function appendWorkspaceHistoryChange(change) {
-    const release = await acquireLock(change.pmRoot, "workspace-history", change.lockTtlSeconds, change.author, false, false, change.lockWaitMs);
-    try {
-        return await appendWorkspaceHistoryChangeLocked(change);
-    }
-    finally {
-        await release();
-    }
-}
-/** Append a verified no-state-change event to the workspace audit stream. */
-export async function appendWorkspaceAuditEvent(options) {
-    const release = await acquireLock(options.pmRoot, "workspace-history", options.lockTtlSeconds, options.author, false, false, options.lockWaitMs);
-    try {
-        const historyPath = getWorkspaceHistoryPath(options.pmRoot);
-        const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
-        const verification = verifyHistoryChain(entries);
-        if (!verification.ok) {
-            throwWorkspaceHistoryVerificationFailure(verification.errors);
-        }
-        const beforeDocument = entries.length === 0
-            ? EMPTY_CANONICAL_DOCUMENT
-            : replayWorkspaceEntries(entries);
-        const entry = createHistoryEntry({
-            nowIso: nowIso(),
-            author: options.author,
-            op: options.op,
-            before: beforeDocument,
-            after: beforeDocument,
-            message: options.message,
-            context: options.context,
-        });
-        await appendHistoryEntry(historyPath, entry);
-        return { entry, historyPath };
-    }
-    finally {
-        await release();
-    }
-}
-/**
- * Atomically serialize a JSON singleton snapshot, write, history append, and
- * compensation under the workspace-history lock.
- */
-async function writeWorkspaceJsonWithHistoryLocked(params, beforeRaw) {
-    if (beforeRaw === params.raw)
-        return false;
-    const before = beforeRaw === null ? null : JSON.parse(beforeRaw);
-    const after = JSON.parse(params.raw);
-    await writeFileAtomic(params.filePath, params.raw);
-    try {
-        if (beforeRaw !== null || params.recordCreation !== false) {
-            await appendWorkspaceHistoryChangeLocked({
-                pmRoot: params.pmRoot,
-                documentPath: path
-                    .relative(params.pmRoot, params.filePath)
-                    .replaceAll("\\", "/"),
-                before,
-                after,
-                op: params.op,
-                author: params.author,
-                lockTtlSeconds: params.lockTtlSeconds,
-                lockWaitMs: params.lockWaitMs,
-                message: params.message,
-            });
-        }
-    }
-    catch (error) {
-        if (beforeRaw === null) {
-            await fs.rm(params.filePath, { force: true });
-        }
-        else {
-            await writeFileAtomic(params.filePath, beforeRaw);
-        }
-        throw error;
-    }
-    return true;
-}
-/**
- * Derive and persist an audited singleton mutation from one lock-protected
- * before-state, preventing read-modify-write callers from losing updates.
- */
-export async function mutateWorkspaceJsonWithHistory(params) {
-    const release = await acquireLock(params.pmRoot, "workspace-history", params.lockTtlSeconds, params.author, false, false, params.lockWaitMs);
-    try {
-        const beforeRaw = await readFileIfExists(params.filePath);
-        const mutation = await params.mutate(beforeRaw);
-        return {
-            changed: await writeWorkspaceJsonWithHistoryLocked({ ...params, raw: mutation.raw }, beforeRaw),
-            result: mutation.result,
-        };
-    }
-    finally {
-        await release();
-    }
-}
-/**
- * Atomically persist one caller-serialized JSON singleton and its audit entry
- * under the workspace-history lock, with compensation if history append fails.
- */
-export async function writeWorkspaceJsonWithHistory(params) {
-    const release = await acquireLock(params.pmRoot, "workspace-history", params.lockTtlSeconds, params.author, false, false, params.lockWaitMs);
-    try {
-        return await writeWorkspaceJsonWithHistoryLocked(params, await readFileIfExists(params.filePath));
-    }
-    finally {
-        await release();
-    }
-}
-/**
- * Append an authorized reconciliation event that adopts a reviewed on-disk
- * singleton after an out-of-band change. The existing stream is never edited:
- * its latest replayed state becomes the event before-state and the reviewed
- * singleton becomes the after-state, with the authorizing Decision recorded in
- * structured context.
- */
-export async function reconcileWorkspaceJsonHistory(options) {
-    const authorizationDecision = options.authorizationDecision.trim();
-    if (!authorizationDecision) {
-        throw new TypeError("Workspace history reconciliation requires an authorization decision");
-    }
-    const release = await acquireLock(options.pmRoot, "workspace-history", options.lockTtlSeconds, options.author, false, false, options.lockWaitMs);
-    try {
-        const { documentPath, absolutePath } = resolveGovernedDocumentPath(options.pmRoot, options.filePath);
-        const historyPath = getWorkspaceHistoryPath(options.pmRoot);
-        const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
-        const verification = verifyHistoryChain(entries);
-        if (!verification.ok) {
-            throwWorkspaceHistoryVerificationFailure(verification.errors);
-        }
-        const beforeDocument = replayWorkspaceEntries(entries);
-        const priorDocuments = workspaceDocuments(beforeDocument);
-        if (!Object.hasOwn(priorDocuments, documentPath)) {
-            throw new TypeError(`Workspace history does not govern document ${documentPath}`);
-        }
-        const raw = await readFileIfExists(absolutePath);
-        if (raw === null) {
-            throw new TypeError(`Workspace history document is missing: ${documentPath}`);
-        }
-        const current = JSON.parse(raw);
-        if (stableStringify(priorDocuments[documentPath]) === stableStringify(current)) {
-            return { changed: false, historyPath };
-        }
-        const timestamp = nowIso();
-        const entry = createHistoryEntry({
-            nowIso: timestamp,
-            author: options.author,
-            op: options.op,
-            before: beforeDocument,
-            after: workspaceDocument({ ...priorDocuments, [documentPath]: current }, beforeDocument.metadata.created_at),
-            message: options.message,
-            context: {
-                reason: "out_of_band_workspace_state_reconciliation",
-                document_path: documentPath,
-                authorization_decision: authorizationDecision,
-            },
-        });
-        await appendHistoryEntry(historyPath, entry);
-        return { changed: true, entry, historyPath };
-    }
-    finally {
-        await release();
-    }
-}
-/**
- * Restore one governed JSON singleton to the value recorded at a one-based
- * workspace history version, then append the restore as a new history state so
- * replay remains forward-only and independently verifiable.
- */
-export async function restoreWorkspaceJsonFromHistory(options) {
-    const release = await acquireLock(options.pmRoot, "workspace-history", options.lockTtlSeconds, options.author, false, false, options.lockWaitMs);
-    try {
-        const { documentPath, absolutePath } = resolveGovernedDocumentPath(options.pmRoot, options.filePath);
-        const entries = await readHistoryEntries(getWorkspaceHistoryPath(options.pmRoot), WORKSPACE_HISTORY_ID);
-        const verification = verifyHistoryChain(entries);
-        if (!verification.ok) {
-            throwWorkspaceHistoryVerificationFailure(verification.errors);
-        }
-        if (!Number.isInteger(options.targetVersion) ||
-            options.targetVersion < 1 ||
-            options.targetVersion > entries.length) {
-            throw new TypeError(`Invalid workspace history target version: ${String(options.targetVersion)}`);
-        }
-        const target = workspaceDocuments(replayWorkspaceEntries(entries, options.targetVersion))[documentPath];
-        if (target === undefined) {
-            throw new TypeError(`Workspace history version ${options.targetVersion} does not contain ${documentPath}`);
-        }
-        const beforeRaw = await readFileIfExists(absolutePath);
-        const targetRaw = `${JSON.stringify(target, null, 2)}\n`;
-        if (beforeRaw === targetRaw)
-            return {
-                document_path: documentPath,
-                restored_from_version: options.targetVersion,
-                changed: false,
-            };
-        const beforeDocument = replayWorkspaceEntries(entries);
-        const timestamp = nowIso();
-        const entry = createHistoryEntry({
-            nowIso: timestamp,
-            author: options.author,
-            op: options.op,
-            before: beforeDocument,
-            after: workspaceDocument({ ...workspaceDocuments(beforeDocument), [documentPath]: target }, beforeDocument.metadata.created_at),
-            message: options.message,
-            context: {
-                reason: "workspace_state_restore",
-                document_path: documentPath,
-                restored_from_version: options.targetVersion,
-                replaced_out_of_band_state: true,
-            },
-        });
-        await writeFileAtomic(absolutePath, targetRaw);
-        try {
-            await appendHistoryEntry(getWorkspaceHistoryPath(options.pmRoot), entry);
-        }
-        catch (error) {
-            if (beforeRaw === null)
-                await fs.rm(absolutePath, { force: true });
-            else
-                await writeFileAtomic(absolutePath, beforeRaw);
-            throw error;
-        }
-        return {
-            document_path: documentPath,
-            restored_from_version: options.targetVersion,
-            changed: true,
-        };
-    }
-    finally {
-        await release();
-    }
-}
+!(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]="e2a2001e-b162-599e-b262-76d2223a343c")}catch(e2){}})();import fs from"node:fs/promises";import path from"node:path";import{readFileIfExists,writeFileAtomic}from"../fs/fs-utils.js";import{acquireLock}from"../lock/lock.js";import{EMPTY_CANONICAL_DOCUMENT,EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";import{stableStringify}from"../shared/serialization.js";import{nowIso}from"../shared/time.js";import{appendHistoryEntry,createHistoryEntry}from"./history.js";import{readHistoryEntries}from"./read.js";import{cloneEmptyReplayDocument,replayToItemDocument,tryApplyReplayPatch,verifyHistoryChain}from"./replay.js";const WORKSPACE_HISTORY_ID="_workspace";function getWorkspaceHistoryPath(pmRoot){return path.join(pmRoot,"history",`${WORKSPACE_HISTORY_ID}.jsonl`)}function workspaceDocument(documents,timestamp){const metadata={id:WORKSPACE_HISTORY_ID,title:"Workspace state",description:"Audited singleton workspace document state.",type:"Chore",status:"open",priority:2,tags:["workspace-history"],created_at:timestamp,updated_at:timestamp,documents};return{metadata,body:""}}function replayWorkspaceEntries(entries,count=entries.length){let replay=cloneEmptyReplayDocument();for(const entry of entries.slice(0,count)){const applied=tryApplyReplayPatch(replay,entry.patch);replay=applied.document}return replayToItemDocument(replay)}function workspaceDocuments(document){return"documents"in document.metadata&&typeof document.metadata.documents==="object"&&document.metadata.documents!==null&&!Array.isArray(document.metadata.documents)?document.metadata.documents:{}}function throwWorkspaceHistoryVerificationFailure(errors){throw new PmCliError(`Workspace history verification failed: ${errors.join(", ")}`,EXIT_CODE.CONFLICT,{code:"workspace_history_chain_invalid",reason:"workspace_history_chain_verification_failed",verification_errors:[...errors],required:"Repair the _workspace history chain before reading, reconciling, restoring, or appending audited singleton state.",why:"Continuing against an unverifiable append-only stream could hide or compound workspace state corruption.",examples:["pm history _workspace --verify --json","pm validate --check-history-drift --fix-hints --json"],nextSteps:["Inspect the exact verification_errors and preserve the corrupt stream as evidence.","Use the history-drift remediation returned by validate before retrying the refused operation."],recovery:{recovery_mode:"compact",next_best_command:"pm history _workspace --verify --json"}})}function resolveGovernedDocumentPath(pmRoot,filePath){const absolutePath=path.resolve(filePath);const documentPath=path.relative(pmRoot,absolutePath).replaceAll("\\","/");if(documentPath.length===0||documentPath===".."||documentPath.startsWith("../")||path.isAbsolute(documentPath)){throw new TypeError("Workspace history document path must stay inside the tracker root")}return{documentPath,absolutePath}}async function inspectWorkspaceHistoryState(pmRoot){const entries=await readHistoryEntries(getWorkspaceHistoryPath(pmRoot),WORKSPACE_HISTORY_ID);const verification=verifyHistoryChain(entries);if(!verification.ok){throwWorkspaceHistoryVerificationFailure(verification.errors)}const documents=workspaceDocuments(entries.length===0?EMPTY_CANONICAL_DOCUMENT:replayWorkspaceEntries(entries));const matching=[];const mismatched=[];const missing=[];const unreadable=[];for(const documentPath of Object.keys(documents).sort()){let raw;try{const resolved=resolveGovernedDocumentPath(pmRoot,path.resolve(pmRoot,documentPath));raw=await readFileIfExists(resolved.absolutePath);if(raw===null){missing.push(documentPath);continue}const current=JSON.parse(raw);(stableStringify(current)===stableStringify(documents[documentPath])?matching:mismatched).push(documentPath)}catch{unreadable.push(documentPath)}}return{ok:mismatched.length===0&&missing.length===0&&unreadable.length===0,document_count:Object.keys(documents).length,matching_documents:matching,mismatched_documents:mismatched,missing_documents:missing,unreadable_documents:unreadable}}async function appendWorkspaceHistoryChangeLocked(change){const historyPath=getWorkspaceHistoryPath(change.pmRoot);const entries=await readHistoryEntries(historyPath,WORKSPACE_HISTORY_ID);const verification=verifyHistoryChain(entries);if(!verification.ok){throwWorkspaceHistoryVerificationFailure(verification.errors)}const idempotentEntry=change.idempotencyKey===void 0?void 0:entries.find(entry2=>entry2.op===`${change.op}:${change.idempotencyKey}`);if(idempotentEntry){return{entry:idempotentEntry,historyPath}}const timestamp=nowIso();const beforeDocument=entries.length===0?EMPTY_CANONICAL_DOCUMENT:replayWorkspaceEntries(entries);const priorDocuments=workspaceDocuments(beforeDocument);const recordedBefore=priorDocuments[change.documentPath];if(recordedBefore!==void 0&&stableStringify(recordedBefore)!==stableStringify(change.before)){throw new PmCliError(`Workspace history state for "${change.documentPath}" changed outside the audited mutation path.`,EXIT_CODE.CONFLICT,{code:"workspace_history_state_conflict",reason:"out_of_band_workspace_state",required:"Reconcile the singleton document with its matching _workspace history state before retrying the mutation.",why:"Accepting the write would make the append-only audit stream describe a state that was not actually observed.",examples:["pm history _workspace --verify","pm validate --check-history-drift --fix-hints"],nextSteps:["Review the version-control change that altered the singleton and preserve the intended document plus its matching workspace history.","Rerun the original mutation only after the on-disk singleton agrees with the latest audited workspace state."],recovery:{recovery_mode:"compact",next_best_command:"pm history _workspace --verify"}})}const afterDocument=workspaceDocument({...priorDocuments,[change.documentPath]:change.after},entries.length===0?timestamp:beforeDocument.metadata.created_at);const entry=createHistoryEntry({nowIso:timestamp,author:change.author,op:change.idempotencyKey===void 0?change.op:`${change.op}:${change.idempotencyKey}`,before:beforeDocument,after:afterDocument,message:change.message});await appendHistoryEntry(historyPath,entry);return{entry,historyPath}}async function appendWorkspaceHistoryChange(change){const release=await acquireLock(change.pmRoot,"workspace-history",change.lockTtlSeconds,change.author,false,false,change.lockWaitMs);try{return await appendWorkspaceHistoryChangeLocked(change)}finally{await release()}}async function appendWorkspaceAuditEvent(options){const release=await acquireLock(options.pmRoot,"workspace-history",options.lockTtlSeconds,options.author,false,false,options.lockWaitMs);try{const historyPath=getWorkspaceHistoryPath(options.pmRoot);const entries=await readHistoryEntries(historyPath,WORKSPACE_HISTORY_ID);const verification=verifyHistoryChain(entries);if(!verification.ok){throwWorkspaceHistoryVerificationFailure(verification.errors)}const beforeDocument=entries.length===0?EMPTY_CANONICAL_DOCUMENT:replayWorkspaceEntries(entries);const entry=createHistoryEntry({nowIso:nowIso(),author:options.author,op:options.op,before:beforeDocument,after:beforeDocument,message:options.message,context:options.context});await appendHistoryEntry(historyPath,entry);return{entry,historyPath}}finally{await release()}}async function writeWorkspaceJsonWithHistoryLocked(params,beforeRaw){if(beforeRaw===params.raw)return false;const before=beforeRaw===null?null:JSON.parse(beforeRaw);const after=JSON.parse(params.raw);await writeFileAtomic(params.filePath,params.raw);try{if(beforeRaw!==null||params.recordCreation!==false){await appendWorkspaceHistoryChangeLocked({pmRoot:params.pmRoot,documentPath:path.relative(params.pmRoot,params.filePath).replaceAll("\\","/"),before,after,op:params.op,author:params.author,lockTtlSeconds:params.lockTtlSeconds,lockWaitMs:params.lockWaitMs,message:params.message})}}catch(error){if(beforeRaw===null){await fs.rm(params.filePath,{force:true})}else{await writeFileAtomic(params.filePath,beforeRaw)}throw error}return true}async function mutateWorkspaceJsonWithHistory(params){const release=await acquireLock(params.pmRoot,"workspace-history",params.lockTtlSeconds,params.author,false,false,params.lockWaitMs);try{const beforeRaw=await readFileIfExists(params.filePath);const mutation=await params.mutate(beforeRaw);return{changed:await writeWorkspaceJsonWithHistoryLocked({...params,raw:mutation.raw},beforeRaw),result:mutation.result}}finally{await release()}}async function writeWorkspaceJsonWithHistory(params){const release=await acquireLock(params.pmRoot,"workspace-history",params.lockTtlSeconds,params.author,false,false,params.lockWaitMs);try{return await writeWorkspaceJsonWithHistoryLocked(params,await readFileIfExists(params.filePath))}finally{await release()}}async function reconcileWorkspaceJsonHistory(options){const authorizationDecision=options.authorizationDecision.trim();if(!authorizationDecision){throw new TypeError("Workspace history reconciliation requires an authorization decision")}const release=await acquireLock(options.pmRoot,"workspace-history",options.lockTtlSeconds,options.author,false,false,options.lockWaitMs);try{const{documentPath,absolutePath}=resolveGovernedDocumentPath(options.pmRoot,options.filePath);const historyPath=getWorkspaceHistoryPath(options.pmRoot);const entries=await readHistoryEntries(historyPath,WORKSPACE_HISTORY_ID);const verification=verifyHistoryChain(entries);if(!verification.ok){throwWorkspaceHistoryVerificationFailure(verification.errors)}const beforeDocument=replayWorkspaceEntries(entries);const priorDocuments=workspaceDocuments(beforeDocument);if(!Object.hasOwn(priorDocuments,documentPath)){throw new TypeError(`Workspace history does not govern document ${documentPath}`)}const raw=await readFileIfExists(absolutePath);if(raw===null){throw new TypeError(`Workspace history document is missing: ${documentPath}`)}const current=JSON.parse(raw);if(stableStringify(priorDocuments[documentPath])===stableStringify(current)){return{changed:false,historyPath}}const timestamp=nowIso();const entry=createHistoryEntry({nowIso:timestamp,author:options.author,op:options.op,before:beforeDocument,after:workspaceDocument({...priorDocuments,[documentPath]:current},beforeDocument.metadata.created_at),message:options.message,context:{reason:"out_of_band_workspace_state_reconciliation",document_path:documentPath,authorization_decision:authorizationDecision}});await appendHistoryEntry(historyPath,entry);return{changed:true,entry,historyPath}}finally{await release()}}async function restoreWorkspaceJsonFromHistory(options){const release=await acquireLock(options.pmRoot,"workspace-history",options.lockTtlSeconds,options.author,false,false,options.lockWaitMs);try{const{documentPath,absolutePath}=resolveGovernedDocumentPath(options.pmRoot,options.filePath);const entries=await readHistoryEntries(getWorkspaceHistoryPath(options.pmRoot),WORKSPACE_HISTORY_ID);const verification=verifyHistoryChain(entries);if(!verification.ok){throwWorkspaceHistoryVerificationFailure(verification.errors)}if(!Number.isInteger(options.targetVersion)||options.targetVersion<1||options.targetVersion>entries.length){throw new TypeError(`Invalid workspace history target version: ${String(options.targetVersion)}`)}const target=workspaceDocuments(replayWorkspaceEntries(entries,options.targetVersion))[documentPath];if(target===void 0){throw new TypeError(`Workspace history version ${options.targetVersion} does not contain ${documentPath}`)}const beforeRaw=await readFileIfExists(absolutePath);const targetRaw=`${JSON.stringify(target,null,2)}
+`;if(beforeRaw===targetRaw)return{document_path:documentPath,restored_from_version:options.targetVersion,changed:false};const beforeDocument=replayWorkspaceEntries(entries);const timestamp=nowIso();const entry=createHistoryEntry({nowIso:timestamp,author:options.author,op:options.op,before:beforeDocument,after:workspaceDocument({...workspaceDocuments(beforeDocument),[documentPath]:target},beforeDocument.metadata.created_at),message:options.message,context:{reason:"workspace_state_restore",document_path:documentPath,restored_from_version:options.targetVersion,replaced_out_of_band_state:true}});await writeFileAtomic(absolutePath,targetRaw);try{await appendHistoryEntry(getWorkspaceHistoryPath(options.pmRoot),entry)}catch(error){if(beforeRaw===null)await fs.rm(absolutePath,{force:true});else await writeFileAtomic(absolutePath,beforeRaw);throw error}return{document_path:documentPath,restored_from_version:options.targetVersion,changed:true}}finally{await release()}}export{WORKSPACE_HISTORY_ID,appendWorkspaceAuditEvent,appendWorkspaceHistoryChange,getWorkspaceHistoryPath,inspectWorkspaceHistoryState,mutateWorkspaceJsonWithHistory,reconcileWorkspaceJsonHistory,restoreWorkspaceJsonFromHistory,writeWorkspaceJsonWithHistory};
 //# sourceMappingURL=workspace-history.js.map
-//# debugId=4df21a17-43c0-5b63-adf3-657699e6a058

package/dist/core/io/body-file.js

@@ -1,63 +1,2 @@
-/**
- * @module core/io/body-file
- *
- * Reads command body content from files, stdin, and inline arguments.
- */
-
-!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]="a97ee152-4d20-54f1-add9-fdb991ab6b33")}catch(e){}}();
-import { readFile } from "node:fs/promises";
-import { EXIT_CODE } from "../shared/constants.js";
-import { PmCliError } from "../shared/errors.js";
-import { createStdinTokenResolver } from "../item/parse.js";
-const defaultBodyFileReader = (path) => readFile(path, "utf8");
-/** Implements resolve body file content for the public runtime surface of this module. */
-export async function resolveBodyFileContent(bodyFile, inlineBody, readFileImpl = defaultBodyFileReader) {
-    // Mutual exclusion: --body and --body-file both define the body, so accepting
-    // both silently would hide which one wins. Fail with an actionable message.
-    if (inlineBody !== undefined) {
-        throw new PmCliError("--body and --body-file are mutually exclusive; provide the body inline with --body or from a file with --body-file, not both.", EXIT_CODE.USAGE, {
-            code: "body_file_conflicts_with_body",
-            required: "Choose exactly one body source.",
-            why: "Both --body and --body-file set the item body; allowing both would make the effective body ambiguous.",
-            nextSteps: [
-                "Re-run with only --body <text> or only --body-file <path>.",
-            ],
-        });
-    }
-    const path = bodyFile.trim();
-    if (path.length === 0) {
-        throw new PmCliError("--body-file requires a file path.", EXIT_CODE.USAGE, {
-            code: "body_file_missing_path",
-            required: "Pass a readable file path: --body-file <path>.",
-            why: "An empty --body-file value has no file to read the body from.",
-        });
-    }
-    if (path === "-") {
-        return (await createStdinTokenResolver().resolveValue("-", "--body-file"));
-    }
-    try {
-        return await readFileImpl(path);
-    }
-    catch (error) {
-        // Preserve the underlying errno (ENOENT/EACCES/EISDIR/...) so the failure
-        // is debuggable, and tailor the directory case (a real footgun: pointing
-        // --body-file at a folder) to an exact message instead of a generic one.
-        const errno = error?.code;
-        const isDirectory = errno === "EISDIR";
-        const detail = errno ? ` (${errno})` : "";
-        throw new PmCliError(isDirectory
-            ? `--body-file "${path}" is a directory, not a file. Point it at a readable file.`
-            : `--body-file could not read "${path}"${detail}. Check that the file exists and is readable.`, EXIT_CODE.NOT_FOUND, {
-            code: "body_file_unreadable",
-            required: "Point --body-file at an existing, readable file.",
-            why: `The body content is loaded from the file at the supplied path, so an unreadable path cannot produce a body${errno ? ` (underlying error: ${errno})` : ""}.`,
-            nextSteps: [
-                `Verify the path: ls -l "${path}"`,
-                "Or pipe the body with --body-file -.",
-                "Or pass the body inline with --body <text>.",
-            ],
-        });
-    }
-}
+!(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]="e6571e4b-c436-5af7-be01-c3fce3a9c5d3")}catch(e2){}})();import{readFile}from"node:fs/promises";import{EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";import{createStdinTokenResolver}from"../item/parse.js";const defaultBodyFileReader=path=>readFile(path,"utf8");async function resolveBodyFileContent(bodyFile,inlineBody,readFileImpl=defaultBodyFileReader){if(inlineBody!==void 0){throw new PmCliError("--body and --body-file are mutually exclusive; provide the body inline with --body or from a file with --body-file, not both.",EXIT_CODE.USAGE,{code:"body_file_conflicts_with_body",required:"Choose exactly one body source.",why:"Both --body and --body-file set the item body; allowing both would make the effective body ambiguous.",nextSteps:["Re-run with only --body <text> or only --body-file <path>."]})}const path=bodyFile.trim();if(path.length===0){throw new PmCliError("--body-file requires a file path.",EXIT_CODE.USAGE,{code:"body_file_missing_path",required:"Pass a readable file path: --body-file <path>.",why:"An empty --body-file value has no file to read the body from."})}if(path==="-"){return await createStdinTokenResolver().resolveValue("-","--body-file")}try{return await readFileImpl(path)}catch(error){const errno=error?.code;const isDirectory=errno==="EISDIR";const detail=errno?` (${errno})`:"";throw new PmCliError(isDirectory?`--body-file "${path}" is a directory, not a file. Point it at a readable file.`:`--body-file could not read "${path}"${detail}. Check that the file exists and is readable.`,EXIT_CODE.NOT_FOUND,{code:"body_file_unreadable",required:"Point --body-file at an existing, readable file.",why:`The body content is loaded from the file at the supplied path, so an unreadable path cannot produce a body${errno?` (underlying error: ${errno})`:""}.`,nextSteps:[`Verify the path: ls -l "${path}"`,"Or pipe the body with --body-file -.","Or pass the body inline with --body <text>."]})}}export{resolveBodyFileContent};
 //# sourceMappingURL=body-file.js.map
-//# debugId=a97ee152-4d20-54f1-add9-fdb991ab6b33

package/dist/core/io/bulk-ids-input.js

@@ -1,113 +1,2 @@
-/**
- * @module core/io/bulk-ids-input
- *
- * Normalizes bulk item-id selectors supplied inline, through stdin, or from an
- * argv-referenced file. Presentation layers can share the parser while MCP and
- * embedded SDK callers keep passing transport-native arrays.
- */
-
-!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]="411f4336-eb02-5167-9dce-ea99822a8a14")}catch(e){}}();
-import { readFile } from "node:fs/promises";
-import { createStdinTokenResolver } from "../item/parse.js";
-import { EXIT_CODE } from "../shared/constants.js";
-import { PmCliError } from "../shared/errors.js";
-const defaultFileReader = (path) => readFile(path, "utf8");
-const defaultStdinReader = async (optionName) => (await createStdinTokenResolver().resolveValue("-", optionName));
-/** Parse comma- or line-delimited item IDs with stable first-seen deduplication. */
-export function parseBulkIdsText(raw) {
-    return [
-        ...new Set(raw
-            .split(/[,\r\n]+/)
-            .map((entry) => entry.trim())
-            .filter((entry) => entry.length > 0)),
-    ];
-}
-function normalizeBulkIdsArray(value) {
-    const entries = [];
-    for (const entry of value) {
-        if (typeof entry === "string") {
-            entries.push(entry);
-        }
-        else if (typeof entry === "number" && Number.isFinite(entry)) {
-            entries.push(String(entry));
-        }
-        else {
-            return "";
-        }
-    }
-    const ids = parseBulkIdsText(entries.join("\n"));
-    return ids.length > 0 ? ids.join(",") : "";
-}
-/** Normalize SDK/MCP scalar-or-array ID input into the list query's CSV form. */
-export function normalizeBulkIdsValue(value) {
-    if (value === undefined) {
-        return undefined;
-    }
-    if (typeof value === "number") {
-        // Preserve an explicitly supplied but invalid numeric selector as blank so
-        // the bulk lifecycle's fail-closed empty-ID guard rejects it. Returning
-        // undefined here would erase the allowlist and could broaden a mutation to
-        // every item matched by the remaining filters.
-        return Number.isFinite(value) ? String(value) : "";
-    }
-    if (Array.isArray(value)) {
-        return normalizeBulkIdsArray(value);
-    }
-    if (typeof value !== "string") {
-        return "";
-    }
-    const ids = parseBulkIdsText(value);
-    return ids.length > 0 ? ids.join(",") : "";
-}
-/**
- * Resolve one CLI `--ids` value. `-` reads newline/comma-delimited stdin and
- * `@path` reads the same grammar from a UTF-8 file; ordinary argv text accepts
- * the grammar inline. The return value is canonical CSV for existing list
- * filtering and unmatched-id accounting.
- */
-export async function resolveCliBulkIdsInput(value, optionName = "--ids", readers = {}) {
-    if (value === undefined) {
-        return undefined;
-    }
-    const trimmed = value.trim();
-    let raw = value;
-    try {
-        if (trimmed === "-") {
-            raw = await (readers.readStdin ?? defaultStdinReader)(optionName);
-        }
-        else if (trimmed.startsWith("@")) {
-            const path = trimmed.slice(1).trim();
-            if (path.length === 0) {
-                throw new PmCliError(`${optionName} @path requires a non-empty file path.`, EXIT_CODE.USAGE, {
-                    code: "bulk_ids_input_missing_path",
-                    required: `Pass ${optionName} @<path>, ${optionName} -, or inline IDs.`,
-                });
-            }
-            raw = await (readers.readFile ?? defaultFileReader)(path);
-        }
-    }
-    catch (error) {
-        if (error instanceof PmCliError) {
-            throw error;
-        }
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new PmCliError(`${optionName} could not read ${trimmed === "-" ? "stdin" : `"${trimmed.slice(1).trim()}"`}: ${detail}`, EXIT_CODE.NOT_FOUND, {
-            code: "bulk_ids_input_unreadable",
-            required: `Provide readable newline/comma-delimited IDs via ${optionName} -, ${optionName} @<path>, or inline argv text.`,
-            nextSteps: [
-                `Retry with inline IDs: ${optionName} pm-a1b2,pm-c3d4`,
-                `Or pipe IDs: pm list --id-only | pm update-many ${optionName} - --dry-run`,
-            ],
-        });
-    }
-    const normalized = normalizeBulkIdsValue(raw);
-    if (normalized !== "") {
-        return normalized;
-    }
-    throw new PmCliError(`${optionName} requires at least one non-empty item ID.`, EXIT_CODE.USAGE, {
-        code: "bulk_ids_input_empty",
-        required: `Provide one or more comma- or newline-delimited IDs through argv, stdin, or @path.`,
-    });
-}
+!(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]="854a0596-b0ec-5d2e-85b1-5444d8d7b622")}catch(e2){}})();import{readFile}from"node:fs/promises";import{createStdinTokenResolver}from"../item/parse.js";import{EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";const defaultFileReader=path=>readFile(path,"utf8");const defaultStdinReader=async optionName=>await createStdinTokenResolver().resolveValue("-",optionName);function parseBulkIdsText(raw){return[...new Set(raw.split(/[,\r\n]+/).map(entry=>entry.trim()).filter(entry=>entry.length>0))]}function normalizeBulkIdsArray(value){const entries=[];for(const entry of value){if(typeof entry==="string"){entries.push(entry)}else if(typeof entry==="number"&&Number.isFinite(entry)){entries.push(String(entry))}else{return""}}const ids=parseBulkIdsText(entries.join("\n"));return ids.length>0?ids.join(","):""}function normalizeBulkIdsValue(value){if(value===void 0){return void 0}if(typeof value==="number"){return Number.isFinite(value)?String(value):""}if(Array.isArray(value)){return normalizeBulkIdsArray(value)}if(typeof value!=="string"){return""}const ids=parseBulkIdsText(value);return ids.length>0?ids.join(","):""}async function resolveCliBulkIdsInput(value,optionName="--ids",readers={}){if(value===void 0){return void 0}const trimmed=value.trim();let raw=value;try{if(trimmed==="-"){raw=await(readers.readStdin??defaultStdinReader)(optionName)}else if(trimmed.startsWith("@")){const path=trimmed.slice(1).trim();if(path.length===0){throw new PmCliError(`${optionName} @path requires a non-empty file path.`,EXIT_CODE.USAGE,{code:"bulk_ids_input_missing_path",required:`Pass ${optionName} @<path>, ${optionName} -, or inline IDs.`})}raw=await(readers.readFile??defaultFileReader)(path)}}catch(error){if(error instanceof PmCliError){throw error}const detail=error instanceof Error?error.message:String(error);throw new PmCliError(`${optionName} could not read ${trimmed==="-"?"stdin":`"${trimmed.slice(1).trim()}"`}: ${detail}`,EXIT_CODE.NOT_FOUND,{code:"bulk_ids_input_unreadable",required:`Provide readable newline/comma-delimited IDs via ${optionName} -, ${optionName} @<path>, or inline argv text.`,nextSteps:[`Retry with inline IDs: ${optionName} pm-a1b2,pm-c3d4`,`Or pipe IDs: pm list --id-only | pm update-many ${optionName} - --dry-run`]})}const normalized=normalizeBulkIdsValue(raw);if(normalized!==""){return normalized}throw new PmCliError(`${optionName} requires at least one non-empty item ID.`,EXIT_CODE.USAGE,{code:"bulk_ids_input_empty",required:`Provide one or more comma- or newline-delimited IDs through argv, stdin, or @path.`})}export{normalizeBulkIdsValue,parseBulkIdsText,resolveCliBulkIdsInput};
 //# sourceMappingURL=bulk-ids-input.js.map
-//# debugId=411f4336-eb02-5167-9dce-ea99822a8a14