@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/guide.js

@@ -1,280 +1,2 @@
-/**
- * @module cli/commands/guide
- *
- * Implements the pm guide 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]="27be0fa5-1c6a-53de-a0e8-179aab7c795a")}catch(e){}}();
-import { isFileAbsentError } from "../core/fs/fs-utils.js";
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { resolveConfiguredPmPackageRoot, EXIT_CODE, PmCliError, } from "./runtime-primitives.js";
-import { listGuideTopicIds, listGuideTopics, resolveGuideTopic, } from "./guide-topics.js";
-/** Supported values accepted by the guide output contract. */
-export const GUIDE_OUTPUT_VALUES = ["markdown", "toon", "json"];
-/** Supported values accepted by the guide depth contract. */
-export const GUIDE_DEPTH_VALUES = ["brief", "standard", "deep"];
-function parseGuideOutputFormat(raw) {
-    if (!raw) {
-        return undefined;
-    }
-    const normalized = raw.trim().toLowerCase();
-    if (!GUIDE_OUTPUT_VALUES.includes(normalized)) {
-        throw new PmCliError("Guide format must be one of markdown|toon|json", EXIT_CODE.USAGE);
-    }
-    return normalized;
-}
-/** Implements resolve guide output format for the public runtime surface of this module. */
-export function resolveGuideOutputFormat(options, global) {
-    const commandFormat = parseGuideOutputFormat(options.format);
-    if (global.json && commandFormat && commandFormat !== "json") {
-        throw new PmCliError("Cannot combine --json with --format markdown|toon", EXIT_CODE.USAGE);
-    }
-    if (global.json) {
-        return "json";
-    }
-    return commandFormat ?? "toon";
-}
-function parseGuideDepth(raw) {
-    if (!raw) {
-        return "brief";
-    }
-    const normalized = raw.trim().toLowerCase();
-    if (!GUIDE_DEPTH_VALUES.includes(normalized)) {
-        throw new PmCliError("Guide depth must be one of brief|standard|deep", EXIT_CODE.USAGE);
-    }
-    return normalized;
-}
-function resolvePackageRoot() {
-    return resolveConfiguredPmPackageRoot(process.env, "PM_CLI_PACKAGE_ROOT", import.meta.url, ["..", "..", ".."]);
-}
-function normalizeLineEndings(value) {
-    return value.replaceAll("\r\n", "\n");
-}
-function toExcerpt(content, maxLines, maxCharacters) {
-    const normalized = normalizeLineEndings(content);
-    const lines = normalized.split("\n");
-    const lineSlice = lines.slice(0, maxLines);
-    let excerpt = lineSlice.join("\n");
-    let truncated = lines.length > maxLines;
-    if (excerpt.length > maxCharacters) {
-        excerpt = excerpt.slice(0, maxCharacters);
-        truncated = true;
-    }
-    return {
-        excerpt: excerpt.trimEnd(),
-        truncated,
-        lineCount: lines.length,
-    };
-}
-async function renderGuideDocs(topic, depth, packageRoot) {
-    const includeContent = depth !== "brief";
-    const contentMode = includeContent
-        ? depth === "deep"
-            ? "full"
-            : "excerpt"
-        : "none";
-    const docs = [];
-    for (const doc of topic.docs) {
-        const absolutePath = path.resolve(packageRoot, doc.path);
-        if (!includeContent) {
-            docs.push({
-                path: doc.path,
-                purpose: doc.purpose,
-                optional: doc.optional === true,
-                exists: true,
-                line_count: null,
-                content_mode: "none",
-                content: null,
-                truncated: false,
-            });
-            continue;
-        }
-        try {
-            const rawContent = await readFile(absolutePath, "utf8");
-            if (depth === "deep") {
-                const normalized = normalizeLineEndings(rawContent).trimEnd();
-                docs.push({
-                    path: doc.path,
-                    purpose: doc.purpose,
-                    optional: doc.optional === true,
-                    exists: true,
-                    line_count: normalized.length === 0 ? 0 : normalized.split("\n").length,
-                    content_mode: "full",
-                    content: normalized,
-                    truncated: false,
-                });
-            }
-            else {
-                const excerpt = toExcerpt(rawContent, 120, 12_000);
-                docs.push({
-                    path: doc.path,
-                    purpose: doc.purpose,
-                    optional: doc.optional === true,
-                    exists: true,
-                    line_count: excerpt.lineCount,
-                    content_mode: contentMode,
-                    content: excerpt.excerpt,
-                    truncated: excerpt.truncated,
-                });
-            }
-        }
-        catch (error) {
-            const missing = isFileAbsentError(error);
-            docs.push({
-                path: doc.path,
-                purpose: doc.purpose,
-                optional: doc.optional === true,
-                exists: false,
-                line_count: null,
-                content_mode: "none",
-                content: null,
-                truncated: false,
-            });
-            if (!missing) {
-                throw new PmCliError(`Failed to read guide document "${doc.path}".`, EXIT_CODE.GENERIC_FAILURE);
-            }
-        }
-    }
-    return docs;
-}
-function buildGuideIndex(depth) {
-    const topics = listGuideTopics().map((topic) => ({
-        id: topic.id,
-        aliases: topic.aliases,
-        title: topic.title,
-        summary: topic.summary,
-        intent: topic.intent,
-        quick_commands: depth === "brief"
-            ? topic.commands.slice(0, 3)
-            : topic.commands.slice(0, 6),
-        docs: topic.docs.map((doc) => ({ path: doc.path, purpose: doc.purpose })),
-        related: topic.related,
-    }));
-    return {
-        output_default: "toon",
-        mode: "index",
-        depth,
-        topics,
-        suggested_next_steps: [
-            "pm guide <topic>",
-            "pm guide <topic> --depth standard",
-            "pm guide <topic> --depth deep --format markdown",
-            "pm guide <topic> --json",
-        ],
-    };
-}
-function ensureGuideTopic(topic) {
-    const resolved = resolveGuideTopic(topic);
-    if (resolved) {
-        return resolved;
-    }
-    const available = listGuideTopicIds().join(", ");
-    throw new PmCliError(`Unknown guide topic "${topic}". Available topics: ${available}. Use "pm guide --list" to browse.`, EXIT_CODE.USAGE);
-}
-/** Implements run guide for the public runtime surface of this module. */
-export async function runGuide(options, global) {
-    const depth = parseGuideDepth(typeof options.depth === "string" ? options.depth : undefined);
-    const listRequested = options.list === true;
-    const topicRaw = typeof options.topic === "string" ? options.topic : undefined;
-    if (listRequested || !topicRaw) {
-        return buildGuideIndex(depth);
-    }
-    const topic = ensureGuideTopic(topicRaw);
-    const packageRoot = resolvePackageRoot();
-    const docs = await renderGuideDocs(topic, depth, packageRoot);
-    const warnings = docs
-        .filter((doc) => !doc.exists && !doc.optional)
-        .map((doc) => `Missing required guide document: ${doc.path}`);
-    return {
-        output_default: "toon",
-        mode: "topic",
-        depth,
-        requested_topic: topicRaw,
-        topic,
-        docs,
-        warnings,
-    };
-}
-/** Public contract for test only guide, shared by SDK and presentation-layer consumers. */
-export const _testOnlyGuide = {
-    ensureGuideTopic,
-};
-function markdownCodeFence(content) {
-    return content.replaceAll("```", "``\\`");
-}
-/** Implements render guide markdown for the public runtime surface of this module. */
-export function renderGuideMarkdown(result) {
-    if (result.mode === "index") {
-        const lines = [
-            "# pm guide",
-            "",
-            "Token-efficient local documentation index for agent and maintainer workflows.",
-            "",
-            "## Topics",
-        ];
-        for (const topic of result.topics) {
-            lines.push(`- \`${topic.id}\` - ${topic.summary}`);
-            if (result.depth !== "brief") {
-                lines.push(`  - intent: ${topic.intent}`);
-                lines.push(`  - docs: ${topic.docs.map((doc) => `\`${doc.path}\``).join(", ")}`);
-            }
-        }
-        lines.push("", "## Next steps");
-        for (const step of result.suggested_next_steps) {
-            lines.push(`- \`${step}\``);
-        }
-        return lines.join("\n");
-    }
-    const lines = [
-        `# pm guide ${result.topic.id}`,
-        "",
-        result.topic.summary,
-        "",
-        "## Intent",
-        result.topic.intent,
-        "",
-        "## Key commands",
-        ...result.topic.commands.map((command) => `- \`${command}\``),
-        "",
-        "## Workflow prompts",
-    ];
-    for (const workflow of result.topic.workflows) {
-        lines.push(`### ${workflow.name}`);
-        lines.push(`goal: ${workflow.goal}`);
-        lines.push(`prompt: ${workflow.prompt}`);
-        lines.push("commands:");
-        lines.push(...workflow.commands.map((command) => `- \`${command}\``));
-        lines.push("");
-    }
-    lines.push("## Documents");
-    for (const doc of result.docs) {
-        const status = doc.exists
-            ? "available"
-            : doc.optional
-                ? "missing (optional)"
-                : "missing (required)";
-        lines.push(`- \`${doc.path}\` - ${doc.purpose} (${status})`);
-        if (doc.exists && doc.content_mode !== "none" && doc.content) {
-            lines.push("");
-            lines.push(`### Excerpt: \`${doc.path}\``);
-            if (doc.truncated) {
-                lines.push("_truncated for context efficiency_");
-            }
-            lines.push("```markdown");
-            lines.push(markdownCodeFence(doc.content));
-            lines.push("```");
-        }
-    }
-    if (result.topic.related.length > 0) {
-        lines.push("", "## Related topics");
-        lines.push(...result.topic.related.map((topic) => `- \`${topic}\``));
-    }
-    if (result.warnings.length > 0) {
-        lines.push("", "## Warnings");
-        lines.push(...result.warnings.map((warning) => `- ${warning}`));
-    }
-    return lines.join("\n");
-}
+!(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]="3a7cf539-2663-5265-90e8-c2aa9926a62a")}catch(e2){}})();import{isFileAbsentError}from"../core/fs/fs-utils.js";import{readFile}from"node:fs/promises";import path from"node:path";import{resolveConfiguredPmPackageRoot,EXIT_CODE,PmCliError}from"./runtime-primitives.js";import{listGuideTopicIds,listGuideTopics,resolveGuideTopic}from"./guide-topics.js";const GUIDE_OUTPUT_VALUES=["markdown","toon","json"];const GUIDE_DEPTH_VALUES=["brief","standard","deep"];function parseGuideOutputFormat(raw){if(!raw){return void 0}const normalized=raw.trim().toLowerCase();if(!GUIDE_OUTPUT_VALUES.includes(normalized)){throw new PmCliError("Guide format must be one of markdown|toon|json",EXIT_CODE.USAGE)}return normalized}function resolveGuideOutputFormat(options,global2){const commandFormat=parseGuideOutputFormat(options.format);if(global2.json&&commandFormat&&commandFormat!=="json"){throw new PmCliError("Cannot combine --json with --format markdown|toon",EXIT_CODE.USAGE)}if(global2.json){return"json"}return commandFormat??"toon"}function parseGuideDepth(raw){if(!raw){return"brief"}const normalized=raw.trim().toLowerCase();if(!GUIDE_DEPTH_VALUES.includes(normalized)){throw new PmCliError("Guide depth must be one of brief|standard|deep",EXIT_CODE.USAGE)}return normalized}function resolvePackageRoot(){return resolveConfiguredPmPackageRoot(process.env,"PM_CLI_PACKAGE_ROOT",import.meta.url,["..","..",".."])}function normalizeLineEndings(value){return value.replaceAll("\r\n","\n")}function toExcerpt(content,maxLines,maxCharacters){const normalized=normalizeLineEndings(content);const lines=normalized.split("\n");const lineSlice=lines.slice(0,maxLines);let excerpt=lineSlice.join("\n");let truncated=lines.length>maxLines;if(excerpt.length>maxCharacters){excerpt=excerpt.slice(0,maxCharacters);truncated=true}return{excerpt:excerpt.trimEnd(),truncated,lineCount:lines.length}}async function renderGuideDocs(topic,depth,packageRoot){const includeContent=depth!=="brief";const contentMode=includeContent?depth==="deep"?"full":"excerpt":"none";const docs=[];for(const doc of topic.docs){const absolutePath=path.resolve(packageRoot,doc.path);if(!includeContent){docs.push({path:doc.path,purpose:doc.purpose,optional:doc.optional===true,exists:true,line_count:null,content_mode:"none",content:null,truncated:false});continue}try{const rawContent=await readFile(absolutePath,"utf8");if(depth==="deep"){const normalized=normalizeLineEndings(rawContent).trimEnd();docs.push({path:doc.path,purpose:doc.purpose,optional:doc.optional===true,exists:true,line_count:normalized.length===0?0:normalized.split("\n").length,content_mode:"full",content:normalized,truncated:false})}else{const excerpt=toExcerpt(rawContent,120,12e3);docs.push({path:doc.path,purpose:doc.purpose,optional:doc.optional===true,exists:true,line_count:excerpt.lineCount,content_mode:contentMode,content:excerpt.excerpt,truncated:excerpt.truncated})}}catch(error){const missing=isFileAbsentError(error);docs.push({path:doc.path,purpose:doc.purpose,optional:doc.optional===true,exists:false,line_count:null,content_mode:"none",content:null,truncated:false});if(!missing){throw new PmCliError(`Failed to read guide document "${doc.path}".`,EXIT_CODE.GENERIC_FAILURE)}}}return docs}function buildGuideIndex(depth){const topics=listGuideTopics().map(topic=>({id:topic.id,aliases:topic.aliases,title:topic.title,summary:topic.summary,intent:topic.intent,quick_commands:depth==="brief"?topic.commands.slice(0,3):topic.commands.slice(0,6),docs:topic.docs.map(doc=>({path:doc.path,purpose:doc.purpose})),related:topic.related}));return{output_default:"toon",mode:"index",depth,topics,suggested_next_steps:["pm guide <topic>","pm guide <topic> --depth standard","pm guide <topic> --depth deep --format markdown","pm guide <topic> --json"]}}function ensureGuideTopic(topic){const resolved=resolveGuideTopic(topic);if(resolved){return resolved}const available=listGuideTopicIds().join(", ");throw new PmCliError(`Unknown guide topic "${topic}". Available topics: ${available}. Use "pm guide --list" to browse.`,EXIT_CODE.USAGE)}async function runGuide(options,global2){const depth=parseGuideDepth(typeof options.depth==="string"?options.depth:void 0);const listRequested=options.list===true;const topicRaw=typeof options.topic==="string"?options.topic:void 0;if(listRequested||!topicRaw){return buildGuideIndex(depth)}const topic=ensureGuideTopic(topicRaw);const packageRoot=resolvePackageRoot();const docs=await renderGuideDocs(topic,depth,packageRoot);const warnings=docs.filter(doc=>!doc.exists&&!doc.optional).map(doc=>`Missing required guide document: ${doc.path}`);return{output_default:"toon",mode:"topic",depth,requested_topic:topicRaw,topic,docs,warnings}}const _testOnlyGuide={ensureGuideTopic};function markdownCodeFence(content){return content.replaceAll("```","``\\`")}function renderGuideMarkdown(result){if(result.mode==="index"){const lines2=["# pm guide","","Token-efficient local documentation index for agent and maintainer workflows.","","## Topics"];for(const topic of result.topics){lines2.push(`- \`${topic.id}\` - ${topic.summary}`);if(result.depth!=="brief"){lines2.push(`  - intent: ${topic.intent}`);lines2.push(`  - docs: ${topic.docs.map(doc=>`\`${doc.path}\``).join(", ")}`)}}lines2.push("","## Next steps");for(const step of result.suggested_next_steps){lines2.push(`- \`${step}\``)}return lines2.join("\n")}const lines=[`# pm guide ${result.topic.id}`,"",result.topic.summary,"","## Intent",result.topic.intent,"","## Key commands",...result.topic.commands.map(command=>`- \`${command}\``),"","## Workflow prompts"];for(const workflow of result.topic.workflows){lines.push(`### ${workflow.name}`);lines.push(`goal: ${workflow.goal}`);lines.push(`prompt: ${workflow.prompt}`);lines.push("commands:");lines.push(...workflow.commands.map(command=>`- \`${command}\``));lines.push("")}lines.push("## Documents");for(const doc of result.docs){const status=doc.exists?"available":doc.optional?"missing (optional)":"missing (required)";lines.push(`- \`${doc.path}\` - ${doc.purpose} (${status})`);if(doc.exists&&doc.content_mode!=="none"&&doc.content){lines.push("");lines.push(`### Excerpt: \`${doc.path}\``);if(doc.truncated){lines.push("_truncated for context efficiency_")}lines.push("```markdown");lines.push(markdownCodeFence(doc.content));lines.push("```")}}if(result.topic.related.length>0){lines.push("","## Related topics");lines.push(...result.topic.related.map(topic=>`- \`${topic}\``))}if(result.warnings.length>0){lines.push("","## Warnings");lines.push(...result.warnings.map(warning=>`- ${warning}`))}return lines.join("\n")}export{GUIDE_DEPTH_VALUES,GUIDE_OUTPUT_VALUES,_testOnlyGuide,renderGuideMarkdown,resolveGuideOutputFormat,runGuide};
 //# sourceMappingURL=guide.js.map
-//# debugId=27be0fa5-1c6a-53de-a0e8-179aab7c795a

package/dist/sdk/history/maintenance.d.ts

@@ -0,0 +1,71 @@
+import { type VerifiedHistoryRewriteState } from "../../core/history/history-rewrite.js";
+import { verifyHistoryChain } from "../../core/history/replay.js";
+import type { ItemTypeRegistry } from "../../core/item/type-registry.js";
+import { readLocatedItem } from "../../core/store/item-store.js";
+import type { HistoryEntry, PmSettings } from "../../types/index.js";
+import type { HistorySubject } from "./subject.js";
+/** Built-in maintenance policies; each keeps its established diagnostics and hook names. */
+export type HistoryMaintenanceOperation = "history-redact" | "history-repair" | "history-compact";
+/** Shared execution controls for a preview or audited stream rewrite. */
+export interface HistoryMaintenanceOptions {
+    /** Compute and verify the plan without acquiring a write lock or persisting it. */
+    dryRun?: boolean;
+    /** Explicit principal override; otherwise use the workspace identity policy. */
+    author?: string;
+    /** Explicit ownership or stale-lock override passed through the existing governance checks. */
+    force?: boolean;
+}
+/** Inputs captured before a transform, bound to the later under-lock drift checks. */
+export interface HistoryMaintenanceSnapshot {
+    /** Original bytes used to decode `entries`, never a second independent read. */
+    raw: string;
+    /** Original stream, including historical anchors and immutable record evidence. */
+    entries: HistoryEntry[];
+    /** Chain verdict for the original entries; repair may deliberately accept drift. */
+    verification: ReturnType<typeof verifyHistoryChain>;
+    /** Current item bytes and document, or null for a deleted item's retained history. */
+    loadedItem: Awaited<ReturnType<typeof readLocatedItem>> | null;
+    /** Resolved identity shared by audit entry construction and lock ownership. */
+    author: string;
+}
+/** Verified outcome supplied to the operation's existing public result renderer. */
+export interface HistoryMaintenanceOutcome {
+    /** Verification of the exact planned entries before persistence. */
+    verification: ReturnType<typeof verifyHistoryChain>;
+    /** Governance and write-hook warnings, empty for a preview or unchanged plan. */
+    warnings: string[];
+}
+/** Operation-owned transform with optional transactional item changes and receipt checks. */
+export interface HistoryMaintenancePlan<Result> {
+    /** Whether the transformation warrants persistence when not previewing. */
+    changed: boolean;
+    /** Final stream including any operation-specific baseline or audit marker. */
+    rewrittenEntries: HistoryEntry[];
+    /** Additional evidence check executed under the lock before any write. */
+    beforeWrite?: () => Promise<void>;
+    /** Override only when history and item bytes must share a rollback transaction. */
+    applyRewrite?: (verified: VerifiedHistoryRewriteState) => Promise<void>;
+    /** Override when the operation must also dispatch item hooks or derived-index warnings. */
+    afterWrite?: () => Promise<string[]>;
+    /** Preserve the operation's public report shape after preview or application completes. */
+    report: (outcome: HistoryMaintenanceOutcome) => Result;
+}
+/** Resolved workspace and transform supplied by built-ins or SDK integrations. */
+export interface HistoryMaintenanceParams<Result> {
+    /** Initialized tracker root whose settings and subject were resolved by the caller. */
+    pmRoot: string;
+    /** Live item or retained deleted-item history selected for maintenance. */
+    subject: HistorySubject;
+    /** Workspace policy used consistently for the snapshot and locked write. */
+    settings: PmSettings;
+    /** Active item-folder mapping, including package-provided types. */
+    typeRegistry: ItemTypeRegistry;
+    /** Maintenance policy whose diagnostic and hook compatibility must be preserved. */
+    operation: HistoryMaintenanceOperation;
+    /** Preview and ownership controls. */
+    options: HistoryMaintenanceOptions;
+    /** Pure planning or evidence reads; persistence belongs in the returned transaction callbacks. */
+    transform: (snapshot: HistoryMaintenanceSnapshot) => HistoryMaintenancePlan<Result> | Promise<HistoryMaintenancePlan<Result>>;
+}
+/** Verify every transform before writing and reject concurrent item or stream changes under the lock. */
+export declare function runHistoryMaintenance<Result>(params: HistoryMaintenanceParams<Result>): Promise<Result>;

package/dist/sdk/history/maintenance.js

@@ -0,0 +1,2 @@
+!(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]="7bab0f96-b67f-5523-9d1f-7426e1d58fbd")}catch(e2){}})();import{runActiveOnWriteHooks}from"../../core/extensions/index.js";import{readHistorySnapshot}from"../../core/history/read.js";import{executeHistoryRewrite,writeHistoryRawWithRollback}from"../../core/history/history-rewrite.js";import{historyEntriesToRaw,verifyHistoryChain}from"../../core/history/replay.js";import{resolveAuthor}from"../../core/shared/author.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{readLocatedItem}from"../../core/store/item-store.js";async function runHistoryMaintenance(params){const{subject,settings,operation,options}=params;const snapshot=await readHistorySnapshot(subject.historyPath,subject.id);if(snapshot.raw===null){throw new PmCliError(`No history stream exists for ${subject.id}.`,EXIT_CODE.NOT_FOUND)}if(snapshot.entries.length===0){throw new PmCliError(`No history entries exist for ${subject.id}; nothing to ${operation.slice("history-".length)}.`,EXIT_CODE.USAGE)}const loadedItem=subject.located?await readLocatedItem(subject.located,{schema:settings.schema}):null;const author=resolveAuthor(options.author,settings.author_default);const plan=await params.transform({raw:snapshot.raw,entries:snapshot.entries,verification:verifyHistoryChain(snapshot.entries),loadedItem,author});const verification=verifyHistoryChain(plan.rewrittenEntries);if(!verification.ok){throw new PmCliError(`${operation} produced an invalid rewritten chain (${verification.errors.join(", ")}).`,EXIT_CODE.GENERIC_FAILURE)}const warnings=plan.changed&&!options.dryRun?await executeHistoryRewrite({pmRoot:params.pmRoot,subject,settings,typeRegistry:params.typeRegistry,historyRawBeforeLock:snapshot.raw,currentItemRawBeforeLock:loadedItem?.raw??null,operation,author,force:options.force,itemDocument:loadedItem?.document??null,applyRewrite:async verified=>{await plan.beforeWrite?.();if(plan.applyRewrite){await plan.applyRewrite(verified)}else{await writeHistoryRawWithRollback({historyPath:subject.historyPath,nextHistoryRaw:historyEntriesToRaw(plan.rewrittenEntries),historyRawUnderLock:verified.historyRawUnderLock})}},applyPostRewrite:plan.afterWrite??(async()=>runActiveOnWriteHooks({path:subject.historyPath,scope:"project",op:`${operation.replace("-","_")}:history`}))}):[];return plan.report({verification,warnings})}export{runHistoryMaintenance};
+//# sourceMappingURL=maintenance.js.map

package/dist/sdk/history/salvage.js

@@ -1,248 +1,3 @@
-/**
- * @module sdk/history/salvage
- * Recover an invalid JSONL suffix while preserving every verified prefix byte.
- */
-
-!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]="49af8ec4-dd6b-56ef-8833-9c776fa35c85")}catch(e){}}();
-import { isUtf8 } from "node:buffer";
-import { readFile } from "node:fs/promises";
-import { isFileMissingError, readFileIfExists, } from "../../core/fs/fs-utils.js";
-import { acquireLock } from "../../core/lock/lock.js";
-import { createHistoryEntry, sealHistoryRecord, } from "../../core/history/history.js";
-import { checkHistoryRewriteOwnership, writeHistoryRawWithRollback, } from "../../core/history/history-rewrite.js";
-import { replayHistoryToTarget } from "../../core/history/projection.js";
-import { replayToItemDocument, verifyHistoryChainWithVersion, } from "../../core/history/replay.js";
-import { findFirstMergeConflictMarker } from "../../core/shared/conflict-markers.js";
-import { EXIT_CODE } from "../../core/shared/constants.js";
-import { PmCliError } from "../../core/shared/errors.js";
-import { sha256Hex } from "../../core/shared/serialization.js";
-import { nowIso } from "../../core/shared/time.js";
-import { runActiveOnReadHooks, runActiveOnWriteHooks, } from "../../core/extensions/index.js";
-import { locateItem, readLocatedItemSnapshot, } from "../../core/store/item-store.js";
-/** Decode a whole record or identify an invalid suffix without hiding a valid record. */
-function decodeSalvageLine(line) {
-    let parsed;
-    try {
-        parsed = JSON.parse(line);
-    }
-    catch {
-        // A complete record followed by crash padding is not a disposable line.
-        // Refuse instead of silently dropping that record along with the padding.
-        if (line.trimStart().startsWith("{") && line.includes("}")) {
-            throw new PmCliError("History salvage cannot discard a potentially complete record with trailing corruption.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
-        }
-        return null;
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new PmCliError("History salvage would conceal interior corruption or a malformed record.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
-    }
-    const entry = parsed;
-    if (!Array.isArray(entry.patch) ||
-        ![
-            entry.ts,
-            entry.author,
-            entry.op,
-            entry.before_hash,
-            entry.after_hash,
-        ].every((field) => typeof field === "string")) {
-        throw new PmCliError("History salvage requires complete history records before the invalid tail.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
-    }
-    return entry;
-}
-/**
- * Select a hash-verified prefix. Any parseable JSON after the first invalid
- * line makes the corruption interior and therefore unsalvageable by truncation.
- */
-export function inspectHistoryTail(raw) {
-    if (findFirstMergeConflictMarker(raw)) {
-        throw new PmCliError("Resolve history merge conflicts before salvage.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
-    }
-    const entries = [];
-    let offset = 0;
-    let invalidOffset;
-    let invalidLine = 0;
-    for (const [index, line] of raw.split("\n").entries()) {
-        if (!line.trim()) {
-            offset += line.length + 1;
-            continue;
-        }
-        const parsed = decodeSalvageLine(line);
-        if (parsed === null) {
-            if (invalidOffset === undefined) {
-                invalidOffset = offset;
-                invalidLine = index + 1;
-            }
-            offset += line.length + 1;
-            continue;
-        }
-        if (invalidOffset !== undefined) {
-            throw new PmCliError("History salvage would discard a record or conceal interior corruption.", EXIT_CODE.CONFLICT, {
-                code: "history_salvage_refused",
-                required: "Recover the damaged record from version control or a backup; no bytes were changed.",
-            });
-        }
-        entries.push(parsed);
-        offset += line.length + 1;
-    }
-    const verification = verifyHistoryChainWithVersion(entries);
-    if (!verification.ok || verification.item_hash_version === undefined) {
-        throw new PmCliError("History salvage requires a nonempty verified prefix.", EXIT_CODE.CONFLICT, {
-            code: "history_salvage_refused",
-            verification_errors: verification.errors,
-            required: "Recover an intact history prefix from version control or a backup.",
-        });
-    }
-    return {
-        entries,
-        itemHashVersion: verification.item_hash_version,
-        prefix: invalidOffset === undefined ? raw : raw.slice(0, invalidOffset),
-        receipt: invalidOffset === undefined
-            ? null
-            : {
-                first_invalid_line: invalidLine,
-                discarded_bytes: Buffer.byteLength(raw.slice(invalidOffset)),
-                discarded_sha256: sha256Hex(raw.slice(invalidOffset)),
-                retained_entries: entries.length,
-            },
-    };
-}
-/** Prefer the live item's owner; history supplies ownership only when its file is unreadable. */
-async function readSalvageOwnership(subject, settings, fallback) {
-    if (!subject.located)
-        return { itemRaw: null, document: fallback };
-    const snapshot = await readLocatedItemSnapshot(subject.located, {
-        schema: settings.schema,
-    });
-    return { itemRaw: snapshot.raw, document: snapshot.document ?? fallback };
-}
-/** Refuse lossy decoding so suffix receipts and rollback always describe original bytes. */
-async function readSalvageStream(historyPath) {
-    let bytes;
-    try {
-        bytes = await readFile(historyPath);
-    }
-    catch (error) {
-        if (isFileMissingError(error))
-            return null;
-        throw error;
-    }
-    if (!isUtf8(bytes)) {
-        throw new PmCliError("History salvage requires UTF-8 input; recover binary corruption from a byte-preserving backup.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
-    }
-    return bytes.toString("utf8");
-}
-/** Salvage one explicitly selected stream under its normal ownership and lock policy. */
-export async function salvageHistoryTail(params) {
-    const { subject, settings, options, author } = params;
-    if ([
-        options.normalizeProvenance,
-        options.auditOperation,
-        options.auditContext,
-        options.auditContextById,
-        options.forceAuditEntry,
-        options.mergeReceiptProof,
-        options.mergeReceiptProofById,
-    ].some(Boolean)) {
-        throw new PmCliError("Tail salvage cannot be combined with other repair modes.", EXIT_CODE.USAGE);
-    }
-    const raw = await readSalvageStream(subject.historyPath);
-    if (raw === null)
-        throw new PmCliError(`No history stream exists for ${subject.id}.`, EXIT_CODE.NOT_FOUND);
-    await runActiveOnReadHooks({ path: subject.historyPath, scope: "project" });
-    const selected = inspectHistoryTail(raw);
-    const replay = replayHistoryToTarget(selected.entries, selected.entries.length - 1);
-    const document = replayToItemDocument(replay);
-    if (typeof replay.metadata.id === "string" &&
-        replay.metadata.id !== subject.id) {
-        throw new PmCliError("History belongs to another item; salvage refused.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
-    }
-    const ownership = await readSalvageOwnership(subject, settings, document);
-    const warnings = checkHistoryRewriteOwnership({
-        itemDocument: ownership.document,
-        subjectId: subject.id,
-        author,
-        force: options.force,
-        settings,
-    });
-    const version = selected.itemHashVersion;
-    const dryRun = options.dryRun === true;
-    const changed = selected.receipt !== null;
-    if (changed && !dryRun) {
-        const release = await acquireLock(params.pmRoot, subject.id, settings.locks.ttl_seconds, author, Boolean(options.force), settings.governance.force_required_for_stale_lock, settings.locks.wait_ms);
-        try {
-            const currentRaw = await readSalvageStream(subject.historyPath);
-            const located = await locateItem(params.pmRoot, subject.id, settings.id_prefix, settings.item_format, params.typeRegistry.type_to_folder);
-            const currentItem = located
-                ? await readFileIfExists(located.itemPath)
-                : null;
-            if (currentRaw !== raw || currentItem !== ownership.itemRaw) {
-                throw new PmCliError("History or item changed while waiting for salvage lock; retry.", EXIT_CODE.CONFLICT);
-            }
-            const audit = sealHistoryRecord({
-                ...createHistoryEntry({
-                    nowIso: nowIso(),
-                    author,
-                    op: "history_salvage",
-                    before: document,
-                    after: document,
-                    message: options.message,
-                    context: { history_salvage: selected.receipt },
-                }),
-                before_hash: selected.entries.at(-1).after_hash,
-                after_hash: selected.entries.at(-1).after_hash,
-                item_hash_version: version,
-            });
-            await writeHistoryRawWithRollback({
-                historyPath: subject.historyPath,
-                historyRawUnderLock: raw,
-                nextHistoryRaw: `${selected.prefix}${JSON.stringify(audit)}\n`,
-            });
-            warnings.push(...(await runActiveOnWriteHooks({
-                path: subject.historyPath,
-                scope: "project",
-                op: "history_salvage:history",
-            })));
-        }
-        finally {
-            await release();
-        }
-    }
-    return {
-        id: subject.id,
-        dry_run: dryRun,
-        changed,
-        history: {
-            path: subject.historyPath,
-            entries_scanned: selected.entries.length,
-            chain_drift_before: false,
-            entries_rehashed: 0,
-            entries_patch_repaired: 0,
-            converted_replace_to_add: 0,
-            skipped_ops: 0,
-            reconciled_with_item: false,
-            audit_entry_added: changed && !dryRun,
-            verify_ok: true,
-            verify_errors: [],
-            item_hash_version_before: version,
-            item_hash_version_after: version,
-            version_disposition: "preserved",
-        },
-        item: {
-            exists: subject.located !== null,
-            path: subject.located?.itemPath ?? null,
-            matched_chain_before: null,
-        },
-        provenance_normalization: {
-            requested: false,
-            changed: false,
-            events_changed: 0,
-            observations_removed: 0,
-            invalid_values: [],
-        },
-        ...(selected.receipt ? { salvage: selected.receipt } : {}),
-        warnings,
-        generated_at: nowIso(),
-    };
-}
+!(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]="dc2b27fd-1e6e-5651-b2b3-642ee4bd1d79")}catch(e2){}})();import{isUtf8}from"node:buffer";import{readFile}from"node:fs/promises";import{isFileMissingError,readFileIfExists}from"../../core/fs/fs-utils.js";import{acquireLock}from"../../core/lock/lock.js";import{createHistoryEntry,sealHistoryRecord}from"../../core/history/history.js";import{checkHistoryRewriteOwnership,writeHistoryRawWithRollback}from"../../core/history/history-rewrite.js";import{replayHistoryToTarget}from"../../core/history/projection.js";import{replayToItemDocument,verifyHistoryChainWithVersion}from"../../core/history/replay.js";import{findFirstMergeConflictMarker}from"../../core/shared/conflict-markers.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{sha256Hex}from"../../core/shared/serialization.js";import{nowIso}from"../../core/shared/time.js";import{runActiveOnReadHooks,runActiveOnWriteHooks}from"../../core/extensions/index.js";import{locateItem,readLocatedItemSnapshot}from"../../core/store/item-store.js";function decodeSalvageLine(line){let parsed;try{parsed=JSON.parse(line)}catch{if(line.trimStart().startsWith("{")&&line.includes("}")){throw new PmCliError("History salvage cannot discard a potentially complete record with trailing corruption.",EXIT_CODE.CONFLICT,{code:"history_salvage_refused"})}return null}if(typeof parsed!=="object"||parsed===null||Array.isArray(parsed)){throw new PmCliError("History salvage would conceal interior corruption or a malformed record.",EXIT_CODE.CONFLICT,{code:"history_salvage_refused"})}const entry=parsed;if(!Array.isArray(entry.patch)||![entry.ts,entry.author,entry.op,entry.before_hash,entry.after_hash].every(field=>typeof field==="string")){throw new PmCliError("History salvage requires complete history records before the invalid tail.",EXIT_CODE.CONFLICT,{code:"history_salvage_refused"})}return entry}function inspectHistoryTail(raw){if(findFirstMergeConflictMarker(raw)){throw new PmCliError("Resolve history merge conflicts before salvage.",EXIT_CODE.CONFLICT,{code:"history_salvage_refused"})}const entries=[];let offset=0;let invalidOffset;let invalidLine=0;for(const[index,line]of raw.split("\n").entries()){if(!line.trim()){offset+=line.length+1;continue}const parsed=decodeSalvageLine(line);if(parsed===null){if(invalidOffset===void 0){invalidOffset=offset;invalidLine=index+1}offset+=line.length+1;continue}if(invalidOffset!==void 0){throw new PmCliError("History salvage would discard a record or conceal interior corruption.",EXIT_CODE.CONFLICT,{code:"history_salvage_refused",required:"Recover the damaged record from version control or a backup; no bytes were changed."})}entries.push(parsed);offset+=line.length+1}const verification=verifyHistoryChainWithVersion(entries);if(!verification.ok||verification.item_hash_version===void 0){throw new PmCliError("History salvage requires a nonempty verified prefix.",EXIT_CODE.CONFLICT,{code:"history_salvage_refused",verification_errors:verification.errors,required:"Recover an intact history prefix from version control or a backup."})}return{entries,itemHashVersion:verification.item_hash_version,prefix:invalidOffset===void 0?raw:raw.slice(0,invalidOffset),receipt:invalidOffset===void 0?null:{first_invalid_line:invalidLine,discarded_bytes:Buffer.byteLength(raw.slice(invalidOffset)),discarded_sha256:sha256Hex(raw.slice(invalidOffset)),retained_entries:entries.length}}}async function readSalvageOwnership(subject,settings,fallback){if(!subject.located)return{itemRaw:null,document:fallback};const snapshot=await readLocatedItemSnapshot(subject.located,{schema:settings.schema});return{itemRaw:snapshot.raw,document:snapshot.document??fallback}}async function readSalvageStream(historyPath){let bytes;try{bytes=await readFile(historyPath)}catch(error){if(isFileMissingError(error))return null;throw error}if(!isUtf8(bytes)){throw new PmCliError("History salvage requires UTF-8 input; recover binary corruption from a byte-preserving backup.",EXIT_CODE.CONFLICT,{code:"history_salvage_refused"})}return bytes.toString("utf8")}async function salvageHistoryTail(params){const{subject,settings,options,author}=params;if([options.normalizeProvenance,options.auditOperation,options.auditContext,options.auditContextById,options.forceAuditEntry,options.mergeReceiptProof,options.mergeReceiptProofById].some(Boolean)){throw new PmCliError("Tail salvage cannot be combined with other repair modes.",EXIT_CODE.USAGE)}const raw=await readSalvageStream(subject.historyPath);if(raw===null)throw new PmCliError(`No history stream exists for ${subject.id}.`,EXIT_CODE.NOT_FOUND);await runActiveOnReadHooks({path:subject.historyPath,scope:"project"});const selected=inspectHistoryTail(raw);const replay=replayHistoryToTarget(selected.entries,selected.entries.length-1);const document=replayToItemDocument(replay);if(typeof replay.metadata.id==="string"&&replay.metadata.id!==subject.id){throw new PmCliError("History belongs to another item; salvage refused.",EXIT_CODE.CONFLICT,{code:"history_salvage_refused"})}const ownership=await readSalvageOwnership(subject,settings,document);const warnings=checkHistoryRewriteOwnership({itemDocument:ownership.document,subjectId:subject.id,author,force:options.force,settings});const version=selected.itemHashVersion;const dryRun=options.dryRun===true;const changed=selected.receipt!==null;if(changed&&!dryRun){const release=await acquireLock(params.pmRoot,subject.id,settings.locks.ttl_seconds,author,Boolean(options.force),settings.governance.force_required_for_stale_lock,settings.locks.wait_ms);try{const currentRaw=await readSalvageStream(subject.historyPath);const located=await locateItem(params.pmRoot,subject.id,settings.id_prefix,settings.item_format,params.typeRegistry.type_to_folder);const currentItem=located?await readFileIfExists(located.itemPath):null;if(currentRaw!==raw||currentItem!==ownership.itemRaw){throw new PmCliError("History or item changed while waiting for salvage lock; retry.",EXIT_CODE.CONFLICT)}const audit=sealHistoryRecord({...createHistoryEntry({nowIso:nowIso(),author,op:"history_salvage",before:document,after:document,message:options.message,context:{history_salvage:selected.receipt}}),before_hash:selected.entries.at(-1).after_hash,after_hash:selected.entries.at(-1).after_hash,item_hash_version:version});await writeHistoryRawWithRollback({historyPath:subject.historyPath,historyRawUnderLock:raw,nextHistoryRaw:`${selected.prefix}${JSON.stringify(audit)}
+`});warnings.push(...await runActiveOnWriteHooks({path:subject.historyPath,scope:"project",op:"history_salvage:history"}))}finally{await release()}}return{id:subject.id,dry_run:dryRun,changed,history:{path:subject.historyPath,entries_scanned:selected.entries.length,chain_drift_before:false,entries_rehashed:0,entries_patch_repaired:0,converted_replace_to_add:0,skipped_ops:0,reconciled_with_item:false,audit_entry_added:changed&&!dryRun,verify_ok:true,verify_errors:[],item_hash_version_before:version,item_hash_version_after:version,version_disposition:"preserved"},item:{exists:subject.located!==null,path:subject.located?.itemPath??null,matched_chain_before:null},provenance_normalization:{requested:false,changed:false,events_changed:0,observations_removed:0,invalid_values:[]},...selected.receipt?{salvage:selected.receipt}:{},warnings,generated_at:nowIso()}}export{inspectHistoryTail,salvageHistoryTail};
 //# sourceMappingURL=salvage.js.map
-//# debugId=49af8ec4-dd6b-56ef-8833-9c776fa35c85

package/dist/sdk/history/subject.d.ts

@@ -0,0 +1,19 @@
+import { locateItem } from "../../core/store/item-store.js";
+import type { PmSettings } from "../../types/index.js";
+/** Resolve initialized workspace policy once for single-stream and bulk maintenance. */
+export declare function resolveHistoryWorkspace(pmPath: string | undefined): Promise<{
+    pmRoot: string;
+    settings: PmSettings;
+    typeRegistry: import("../../core/item/type-registry.js").ItemTypeRegistry;
+}>;
+/** Canonical stream address, retaining item location only when the current item exists. */
+export interface HistorySubject {
+    /** Stable identifier used to reference this record across commands and storage. */
+    id: string;
+    /** Filesystem path used for history resolution. */
+    historyPath: string;
+    /** Current item location, or null when only a deleted item's history remains. */
+    located: Awaited<ReturnType<typeof locateItem>>;
+}
+/** Resolve a current item first, then retained streams under normalized and raw legacy IDs. */
+export declare function resolveHistorySubject(pmRoot: string, id: string, settings: PmSettings, typeToFolder: Record<string, string>): Promise<HistorySubject>;