@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/workspace-transaction-gc.js

@@ -1,150 +1,2 @@
-/**
- * @module sdk/workspace-transaction-gc
- *
- * Age-based garbage collector for the durable SDK workspace-transaction
- * journals written by `commitWorkspaceTransaction` under
- * `transactions/sdk/<transactionId>.json`. Only terminal journals (status
- * `committed` or `compensated`) older than the configured retention are
- * pruned; in-flight journals (`applying`/`compensating`) are crash-recovery
- * state and are always retained, as are journals whose status or timestamp
- * cannot be read (safety-first, mirroring the checkpoint and stale-lock
- * sweeps). Transaction steps are contract-idempotent, so pruning a terminal
- * receipt only costs the ability to short-circuit an identical replay — it
- * never breaks correctness.
- */
-
-!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]="7df80849-51e1-5efa-b40a-b44088f941a9")}catch(e){}}();
-import { isFileMissingError } from "../core/fs/fs-utils.js";
-import fs from "node:fs/promises";
-import path from "node:path";
-const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
-const TERMINAL_JOURNAL_STATUSES = new Set(["committed", "compensated"]);
-function readJournalStatusAndTimestamp(raw) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return { status: null, updatedAt: null };
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return { status: null, updatedAt: null };
-    }
-    const record = parsed;
-    return {
-        status: typeof record.status === "string" ? record.status : null,
-        updatedAt: typeof record.updatedAt === "string" ? record.updatedAt : null,
-    };
-}
-function classifyWorkspaceTransactionJournal(file, status, updatedAt, nowMs, retentionMs) {
-    const updatedAtMs = updatedAt === null ? Number.NaN : Date.parse(updatedAt);
-    if (status === null || !Number.isFinite(updatedAtMs)) {
-        return {
-            entry: {
-                file,
-                status,
-                age_seconds: null,
-                stale: false,
-                reason: "unparseable",
-            },
-            remove: false,
-        };
-    }
-    const ageMs = nowMs - updatedAtMs;
-    if (!TERMINAL_JOURNAL_STATUSES.has(status)) {
-        return {
-            entry: {
-                file,
-                status,
-                age_seconds: Math.floor(ageMs / 1000),
-                stale: false,
-                reason: "active",
-            },
-            remove: false,
-        };
-    }
-    // A non-finite retentionMs makes this comparison false, disabling pruning
-    // rather than risking deletion under bad input.
-    if (!(ageMs > retentionMs)) {
-        return {
-            entry: {
-                file,
-                status,
-                age_seconds: Math.floor(ageMs / 1000),
-                stale: false,
-                reason: "fresh",
-            },
-            remove: false,
-        };
-    }
-    return {
-        entry: {
-            file,
-            status,
-            age_seconds: Math.floor(ageMs / 1000),
-            stale: true,
-        },
-        remove: true,
-    };
-}
-async function processWorkspaceTransactionJournal(absolutePath, relativePath, fileName, options) {
-    const warnings = options.hooks?.onRead
-        ? await options.hooks.onRead(absolutePath)
-        : [];
-    const journal = readJournalStatusAndTimestamp(await fs.readFile(absolutePath, "utf8"));
-    const decision = classifyWorkspaceTransactionJournal(relativePath, journal.status, journal.updatedAt, options.nowMs, options.retentionMs);
-    if (decision.entry.reason === "unparseable") {
-        warnings.push(`transaction_journal_unparseable:${fileName}`);
-    }
-    if (decision.remove && !options.dryRun) {
-        await fs.rm(absolutePath, { force: true });
-        if (options.hooks?.onWrite) {
-            warnings.push(...(await options.hooks.onWrite(absolutePath)));
-        }
-    }
-    return { decision, warnings };
-}
-/** Sweep `transactions/sdk/` and prune terminal workspace-transaction journals older than the retention window. One decision row is reported per journal so `pm gc` output stays auditable. */
-export async function runWorkspaceTransactionGc(pmRoot, options) {
-    const { dryRun, hooks } = options;
-    const nowMs = options.now ?? Date.now();
-    const retentionMs = Math.max(0, options.retentionDays) * MILLISECONDS_PER_DAY;
-    const journalsDir = path.join(pmRoot, "transactions", "sdk");
-    const result = {
-        scanned: 0,
-        removed: [],
-        retained: [],
-        warnings: [],
-        entries: [],
-    };
-    let files;
-    try {
-        files = (await fs.readdir(journalsDir))
-            .filter((file) => file.endsWith(".json"))
-            .sort((left, right) => left.localeCompare(right));
-    }
-    catch (error) {
-        if (isFileMissingError(error)) {
-            return result;
-        }
-        throw error;
-    }
-    for (const file of files) {
-        const absPath = path.join(journalsDir, file);
-        const relPath = `transactions/sdk/${file}`;
-        const fileResult = await processWorkspaceTransactionJournal(absPath, relPath, file, { dryRun, hooks, nowMs, retentionMs });
-        result.warnings.push(...fileResult.warnings);
-        result.scanned += 1;
-        const { decision } = fileResult;
-        if (!decision.remove) {
-            result.retained.push(relPath);
-            result.entries.push(decision.entry);
-            continue;
-        }
-        result.removed.push(relPath);
-        result.entries.push(decision.entry);
-    }
-    return result;
-}
+!(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]="9189cea6-950f-5594-9321-b7590171297c")}catch(e2){}})();import{isFileMissingError}from"../core/fs/fs-utils.js";import fs from"node:fs/promises";import path from"node:path";const MILLISECONDS_PER_DAY=24*60*60*1e3;const TERMINAL_JOURNAL_STATUSES=new Set(["committed","compensated"]);function readJournalStatusAndTimestamp(raw){let parsed;try{parsed=JSON.parse(raw)}catch{return{status:null,updatedAt:null}}if(typeof parsed!=="object"||parsed===null||Array.isArray(parsed)){return{status:null,updatedAt:null}}const record=parsed;return{status:typeof record.status==="string"?record.status:null,updatedAt:typeof record.updatedAt==="string"?record.updatedAt:null}}function classifyWorkspaceTransactionJournal(file,status,updatedAt,nowMs,retentionMs){const updatedAtMs=updatedAt===null?Number.NaN:Date.parse(updatedAt);if(status===null||!Number.isFinite(updatedAtMs)){return{entry:{file,status,age_seconds:null,stale:false,reason:"unparseable"},remove:false}}const ageMs=nowMs-updatedAtMs;if(!TERMINAL_JOURNAL_STATUSES.has(status)){return{entry:{file,status,age_seconds:Math.floor(ageMs/1e3),stale:false,reason:"active"},remove:false}}if(!(ageMs>retentionMs)){return{entry:{file,status,age_seconds:Math.floor(ageMs/1e3),stale:false,reason:"fresh"},remove:false}}return{entry:{file,status,age_seconds:Math.floor(ageMs/1e3),stale:true},remove:true}}async function processWorkspaceTransactionJournal(absolutePath,relativePath,fileName,options){const warnings=options.hooks?.onRead?await options.hooks.onRead(absolutePath):[];const journal=readJournalStatusAndTimestamp(await fs.readFile(absolutePath,"utf8"));const decision=classifyWorkspaceTransactionJournal(relativePath,journal.status,journal.updatedAt,options.nowMs,options.retentionMs);if(decision.entry.reason==="unparseable"){warnings.push(`transaction_journal_unparseable:${fileName}`)}if(decision.remove&&!options.dryRun){await fs.rm(absolutePath,{force:true});if(options.hooks?.onWrite){warnings.push(...await options.hooks.onWrite(absolutePath))}}return{decision,warnings}}async function runWorkspaceTransactionGc(pmRoot,options){const{dryRun,hooks}=options;const nowMs=options.now??Date.now();const retentionMs=Math.max(0,options.retentionDays)*MILLISECONDS_PER_DAY;const journalsDir=path.join(pmRoot,"transactions","sdk");const result={scanned:0,removed:[],retained:[],warnings:[],entries:[]};let files;try{files=(await fs.readdir(journalsDir)).filter(file=>file.endsWith(".json")).sort((left,right)=>left.localeCompare(right))}catch(error){if(isFileMissingError(error)){return result}throw error}for(const file of files){const absPath=path.join(journalsDir,file);const relPath=`transactions/sdk/${file}`;const fileResult=await processWorkspaceTransactionJournal(absPath,relPath,file,{dryRun,hooks,nowMs,retentionMs});result.warnings.push(...fileResult.warnings);result.scanned+=1;const{decision}=fileResult;if(!decision.remove){result.retained.push(relPath);result.entries.push(decision.entry);continue}result.removed.push(relPath);result.entries.push(decision.entry)}return result}export{runWorkspaceTransactionGc};
 //# sourceMappingURL=workspace-transaction-gc.js.map
-//# debugId=7df80849-51e1-5efa-b40a-b44088f941a9

package/dist/sdk/workspace-transaction.js

@@ -1,364 +1,3 @@
-/**
- * @module sdk/workspace-transaction
- *
- * Coordinates crash-recoverable, compensating transactions across public SDK
- * mutation primitives without rewriting immutable item or relationship history.
- */
-
-!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]="6ed4a26f-2ae2-556a-87db-56844108757f")}catch(e){}}();
-import { mkdir, readFile } from "node:fs/promises";
-import path from "node:path";
-import { acquireLock } from "../core/lock/lock.js";
-import { isFileMissingError, writeFileAtomic } from "../core/fs/fs-utils.js";
-import { nowIso } from "../core/shared/time.js";
-/**
- * Deliberate process-boundary interruption used by deterministic crash tests.
- * Throwing this from `onTransition` leaves the journal resumable and skips the
- * normal in-process compensation path.
- */
-export class WorkspaceTransactionInterruptedError extends Error {
-    /** Create one explicit crash-boundary interruption. */
-    constructor(message = "Workspace transaction interrupted") {
-        super(message);
-        this.name = "WorkspaceTransactionInterruptedError";
-    }
-}
-const WORKSPACE_TRANSACTION_LOCK_ID = "sdk-workspace-transaction";
-const TRANSACTION_ID_PATTERN = /^[a-zA-Z0-9._-]+$/;
-const DEFAULT_LOCK_TTL_SECONDS = 30;
-const DEFAULT_LOCK_WAIT_MS = 3_000;
-function requiredIdentifier(value, label) {
-    if (typeof value !== "string")
-        throw new TypeError(`${label} must be a string`);
-    const normalized = value.trim();
-    if (!normalized || !TRANSACTION_ID_PATTERN.test(normalized))
-        throw new TypeError(`${label} must match [a-zA-Z0-9._-]+`);
-    return normalized;
-}
-function requiredText(value, label) {
-    if (typeof value !== "string")
-        throw new TypeError(`${label} must be a string`);
-    const normalized = value.trim();
-    if (!normalized)
-        throw new TypeError(`${label} must be non-empty`);
-    return normalized;
-}
-function positiveInteger(value, fallback, label) {
-    const resolved = value ?? fallback;
-    if (!Number.isInteger(resolved) || resolved <= 0)
-        throw new TypeError(`${label} must be a positive integer`);
-    return resolved;
-}
-function journalPath(pmRoot, transactionId) {
-    return path.join(pmRoot, "transactions", "sdk", `${transactionId}.json`);
-}
-async function writeJournal(pmRoot, journal) {
-    journal.updatedAt = nowIso();
-    const target = journalPath(pmRoot, journal.transactionId);
-    await mkdir(path.dirname(target), { recursive: true });
-    await writeFileAtomic(target, `${JSON.stringify(journal, null, 2)}\n`);
-}
-function hasValidJournalMetadata(journal) {
-    return (Number.isInteger(journal.attempt) &&
-        typeof journal.author === "string" &&
-        typeof journal.createdAt === "string" &&
-        typeof journal.updatedAt === "string");
-}
-function createResultMap(source) {
-    return Object.assign(Object.create(null), source);
-}
-function cloneJournalValue(value, label) {
-    try {
-        const serialized = JSON.stringify(value, (_key, nestedValue) => {
-            if (typeof nestedValue === "number" && !Number.isFinite(nestedValue))
-                throw new TypeError(`${label} contains a non-finite number`);
-            if (nestedValue === undefined ||
-                typeof nestedValue === "function" ||
-                typeof nestedValue === "symbol")
-                throw new TypeError(`${label} contains a non-JSON value`);
-            return nestedValue;
-        });
-        return JSON.parse(serialized);
-    }
-    catch (error) {
-        throw new TypeError(`${label} must be JSON serializable`, { cause: error });
-    }
-}
-function cloneOptionalJournalValue(value, label) {
-    return value === undefined ? undefined : cloneJournalValue(value, label);
-}
-function setJournalEntry(target, stepId, value, label) {
-    const cloned = cloneOptionalJournalValue(value, label);
-    if (cloned === undefined)
-        delete target[stepId];
-    else
-        target[stepId] = cloned;
-}
-function isJournalMap(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function hasUniqueKnownStepIds(value, stepIds) {
-    return (Array.isArray(value) &&
-        new Set(value).size === value.length &&
-        value.every((stepId) => typeof stepId === "string" && stepIds.includes(stepId)));
-}
-function hasValidJournalLifecycle(journal, stepIds) {
-    if (!hasUniqueKnownStepIds(journal.startedStepIds, stepIds) ||
-        !hasUniqueKnownStepIds(journal.completedStepIds, stepIds) ||
-        !isJournalMap(journal.results) ||
-        !isJournalMap(journal.compensationData))
-        return false;
-    const startedStepIds = journal.startedStepIds;
-    const started = new Set(startedStepIds);
-    const completedStepIds = journal.completedStepIds;
-    const completed = new Set(completedStepIds);
-    if (Object.keys(journal.compensationData).some((stepId) => !started.has(stepId)) ||
-        Object.keys(journal.results).some((stepId) => !completed.has(stepId)))
-        return false;
-    if (journal.status === "committed")
-        return stepIds.every((stepId) => completed.has(stepId));
-    return (journal.status !== "compensated" ||
-        (completed.size === 0 && started.size === 0));
-}
-function parseJournal(raw, transactionId, stepIds) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new TypeError(`Workspace transaction ${transactionId} journal is invalid JSON`);
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-        throw new TypeError(`Workspace transaction ${transactionId} journal is invalid`);
-    const journal = parsed;
-    const identityMatches = journal.schemaVersion === 1 && journal.transactionId === transactionId;
-    const stepsMatch = Array.isArray(journal.stepIds) &&
-        journal.stepIds.length === stepIds.length &&
-        journal.stepIds.every((stepId, index) => stepId === stepIds[index]);
-    const lifecycleMatches = hasValidJournalLifecycle(journal, stepIds);
-    const metadataMatches = hasValidJournalMetadata(journal);
-    const statusMatches = [
-        "applying",
-        "compensating",
-        "compensated",
-        "committed",
-    ].includes(String(journal.status));
-    if (!identityMatches ||
-        !stepsMatch ||
-        !lifecycleMatches ||
-        !metadataMatches ||
-        !statusMatches)
-        throw new TypeError(`Workspace transaction ${transactionId} journal does not match the supplied plan`);
-    return {
-        ...journal,
-        results: createResultMap(journal.results),
-        compensationData: createResultMap(journal.compensationData),
-    };
-}
-async function prepareJournalForApply(options, transactionId, author, stepIds, existing) {
-    let journal = existing;
-    const recovered = journal !== undefined;
-    if (journal?.status === "compensating")
-        await compensateAppliedSteps(options, journal);
-    if (journal === undefined || journal.status === "compensated") {
-        const timestamp = nowIso();
-        journal = {
-            schemaVersion: 1,
-            transactionId,
-            author,
-            status: "applying",
-            attempt: (journal?.attempt ?? 0) + 1,
-            createdAt: journal?.createdAt ?? timestamp,
-            updatedAt: timestamp,
-            stepIds,
-            startedStepIds: [],
-            completedStepIds: [],
-            results: createResultMap(),
-            compensationData: createResultMap(),
-        };
-        await writeJournal(options.pmRoot, journal);
-        await emitTransition(options, journal, "prepared");
-    }
-    return { journal, recovered };
-}
-async function applyPreparedTransaction(options, journal, recovered) {
-    try {
-        await discoverAppliedSteps(journal, options.steps);
-        await writeJournal(options.pmRoot, journal);
-        const completed = new Set(journal.completedStepIds);
-        const started = new Set(journal.startedStepIds);
-        for (const step of options.steps) {
-            if (completed.has(step.id))
-                continue;
-            const inspection = await step.inspect();
-            let result = cloneOptionalJournalValue(inspection.result, `Step ${step.id} result`);
-            if (inspection.state !== "applied") {
-                const compensationData = await step.prepareCompensation?.();
-                setJournalEntry(journal.compensationData, step.id, compensationData, `Step ${step.id} compensation data`);
-                started.add(step.id);
-                journal.startedStepIds = options.steps
-                    .map((candidate) => candidate.id)
-                    .filter((stepId) => started.has(stepId));
-                await writeJournal(options.pmRoot, journal);
-                const appliedResult = await step.apply();
-                result = cloneOptionalJournalValue(appliedResult, `Step ${step.id} result`);
-            }
-            await emitTransition(options, journal, "step_applied", step.id);
-            completed.add(step.id);
-            journal.completedStepIds = options.steps
-                .map((candidate) => candidate.id)
-                .filter((stepId) => completed.has(stepId));
-            setJournalEntry(journal.results, step.id, result, `Step ${step.id} result`);
-            await writeJournal(options.pmRoot, journal);
-            await emitTransition(options, journal, "step_recorded", step.id);
-        }
-        await emitTransition(options, journal, "committing");
-        journal.status = "committed";
-        await writeJournal(options.pmRoot, journal);
-        await emitTransition(options, journal, "committed");
-        return {
-            transactionId: journal.transactionId,
-            status: "committed",
-            recovered,
-            results: createResultMap(journal.results),
-        };
-    }
-    catch (error) {
-        if (error instanceof WorkspaceTransactionInterruptedError ||
-            journal.status === "committed")
-            throw error;
-        try {
-            await compensateAppliedSteps(options, journal);
-        }
-        catch (compensationError) {
-            throw new AggregateError([error, compensationError], `Workspace transaction failed and compensation failed: ${String(compensationError)}`, { cause: compensationError });
-        }
-        throw error;
-    }
-}
-async function loadJournal(pmRoot, transactionId, stepIds) {
-    try {
-        return parseJournal(await readFile(journalPath(pmRoot, transactionId), "utf8"), transactionId, stepIds);
-    }
-    catch (error) {
-        if (error !== null &&
-            typeof error === "object" &&
-            "code" in error &&
-            isFileMissingError(error))
-            return undefined;
-        throw error;
-    }
-}
-async function emitTransition(options, journal, transition, stepId) {
-    await options.onTransition?.({
-        transactionId: journal.transactionId,
-        attempt: journal.attempt,
-        transition,
-        ...(stepId === undefined ? {} : { stepId }),
-    });
-}
-async function discoverAppliedSteps(journal, steps) {
-    const completed = new Set();
-    const results = createResultMap();
-    for (const step of steps) {
-        const inspection = await step.inspect();
-        if (inspection.state === "applied") {
-            completed.add(step.id);
-            setJournalEntry(results, step.id, inspection.result, `Step ${step.id} result`);
-        }
-    }
-    journal.results = results;
-    journal.completedStepIds = steps
-        .map((step) => step.id)
-        .filter((stepId) => completed.has(stepId));
-}
-async function compensateAppliedSteps(options, journal) {
-    journal.status = "compensating";
-    await writeJournal(options.pmRoot, journal);
-    await emitTransition(options, journal, "compensating");
-    const completed = new Set(journal.completedStepIds);
-    const started = new Set(journal.startedStepIds);
-    for (const step of [...options.steps].reverse()) {
-        if (!started.has(step.id) && !completed.has(step.id))
-            continue;
-        let shouldCompensate;
-        try {
-            shouldCompensate =
-                started.has(step.id) && (await step.inspect()).state === "applied";
-        }
-        catch {
-            shouldCompensate = started.has(step.id);
-        }
-        if (shouldCompensate) {
-            await emitTransition(options, journal, "step_compensating", step.id);
-            await step.compensate(journal.compensationData[step.id]);
-        }
-        completed.delete(step.id);
-        started.delete(step.id);
-        journal.completedStepIds = options.steps
-            .map((candidate) => candidate.id)
-            .filter((stepId) => completed.has(stepId));
-        journal.startedStepIds = options.steps
-            .map((candidate) => candidate.id)
-            .filter((stepId) => started.has(stepId));
-        delete journal.results[step.id];
-        delete journal.compensationData[step.id];
-        await writeJournal(options.pmRoot, journal);
-        await emitTransition(options, journal, "step_compensated", step.id);
-    }
-    journal.status = "compensated";
-    await writeJournal(options.pmRoot, journal);
-    await emitTransition(options, journal, "compensated");
-}
-/**
- * Commit an ordered set of idempotent SDK mutations under one workspace writer
- * lock. The durable journal resumes interrupted forward work, while ordinary
- * failures append reverse-order compensations. This provides atomic logical
- * replay without deleting or rewriting immutable domain histories.
- */
-export async function commitWorkspaceTransaction(options) {
-    const pmRoot = requiredText(options.pmRoot, "Transaction pmRoot");
-    const transactionId = requiredIdentifier(options.transactionId, "Transaction id");
-    const author = requiredText(options.author, "Transaction author");
-    const lockTtlSeconds = positiveInteger(options.lockTtlSeconds, DEFAULT_LOCK_TTL_SECONDS, "Transaction lock TTL");
-    const lockWaitMs = positiveInteger(options.lockWaitMs, DEFAULT_LOCK_WAIT_MS, "Transaction lock wait");
-    const steps = [...options.steps];
-    if (steps.length === 0)
-        throw new TypeError("Workspace transaction requires at least one step");
-    const stepIds = steps.map((step) => {
-        const stepId = requiredIdentifier(step.id, "Transaction step id");
-        if (stepId !== step.id)
-            throw new TypeError("Transaction step id must not contain surrounding whitespace");
-        return stepId;
-    });
-    if (new Set(stepIds).size !== stepIds.length)
-        throw new TypeError("Workspace transaction step ids must be unique");
-    const stableOptions = {
-        ...options,
-        pmRoot,
-        transactionId,
-        author,
-        steps,
-        lockTtlSeconds,
-        lockWaitMs,
-    };
-    const release = await acquireLock(pmRoot, WORKSPACE_TRANSACTION_LOCK_ID, lockTtlSeconds, author, false, false, lockWaitMs);
-    try {
-        const existing = await loadJournal(pmRoot, transactionId, stepIds);
-        const recovered = existing !== undefined;
-        if (existing?.status === "committed")
-            return {
-                transactionId,
-                status: "committed",
-                recovered: true,
-                results: createResultMap(existing.results),
-            };
-        const prepared = await prepareJournalForApply(stableOptions, transactionId, author, stepIds, existing);
-        return await applyPreparedTransaction(stableOptions, prepared.journal, recovered || prepared.recovered);
-    }
-    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]="4d7f490a-03a3-512c-ba3c-b19fcc9a1270")}catch(e2){}})();import{mkdir,readFile}from"node:fs/promises";import path from"node:path";import{acquireLock}from"../core/lock/lock.js";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{nowIso}from"../core/shared/time.js";class WorkspaceTransactionInterruptedError extends Error{constructor(message="Workspace transaction interrupted"){super(message);this.name="WorkspaceTransactionInterruptedError"}}const WORKSPACE_TRANSACTION_LOCK_ID="sdk-workspace-transaction";const TRANSACTION_ID_PATTERN=/^[a-zA-Z0-9._-]+$/;const DEFAULT_LOCK_TTL_SECONDS=30;const DEFAULT_LOCK_WAIT_MS=3e3;function requiredIdentifier(value,label){if(typeof value!=="string")throw new TypeError(`${label} must be a string`);const normalized=value.trim();if(!normalized||!TRANSACTION_ID_PATTERN.test(normalized))throw new TypeError(`${label} must match [a-zA-Z0-9._-]+`);return normalized}function requiredText(value,label){if(typeof value!=="string")throw new TypeError(`${label} must be a string`);const normalized=value.trim();if(!normalized)throw new TypeError(`${label} must be non-empty`);return normalized}function positiveInteger(value,fallback,label){const resolved=value??fallback;if(!Number.isInteger(resolved)||resolved<=0)throw new TypeError(`${label} must be a positive integer`);return resolved}function journalPath(pmRoot,transactionId){return path.join(pmRoot,"transactions","sdk",`${transactionId}.json`)}async function writeJournal(pmRoot,journal){journal.updatedAt=nowIso();const target=journalPath(pmRoot,journal.transactionId);await mkdir(path.dirname(target),{recursive:true});await writeFileAtomic(target,`${JSON.stringify(journal,null,2)}
+`)}function hasValidJournalMetadata(journal){return Number.isInteger(journal.attempt)&&typeof journal.author==="string"&&typeof journal.createdAt==="string"&&typeof journal.updatedAt==="string"}function createResultMap(source){return Object.assign(Object.create(null),source)}function cloneJournalValue(value,label){try{const serialized=JSON.stringify(value,(_key,nestedValue)=>{if(typeof nestedValue==="number"&&!Number.isFinite(nestedValue))throw new TypeError(`${label} contains a non-finite number`);if(nestedValue===void 0||typeof nestedValue==="function"||typeof nestedValue==="symbol")throw new TypeError(`${label} contains a non-JSON value`);return nestedValue});return JSON.parse(serialized)}catch(error){throw new TypeError(`${label} must be JSON serializable`,{cause:error})}}function cloneOptionalJournalValue(value,label){return value===void 0?void 0:cloneJournalValue(value,label)}function setJournalEntry(target,stepId,value,label){const cloned=cloneOptionalJournalValue(value,label);if(cloned===void 0)delete target[stepId];else target[stepId]=cloned}function isJournalMap(value){return value!==null&&typeof value==="object"&&!Array.isArray(value)}function hasUniqueKnownStepIds(value,stepIds){return Array.isArray(value)&&new Set(value).size===value.length&&value.every(stepId=>typeof stepId==="string"&&stepIds.includes(stepId))}function hasValidJournalLifecycle(journal,stepIds){if(!hasUniqueKnownStepIds(journal.startedStepIds,stepIds)||!hasUniqueKnownStepIds(journal.completedStepIds,stepIds)||!isJournalMap(journal.results)||!isJournalMap(journal.compensationData))return false;const startedStepIds=journal.startedStepIds;const started=new Set(startedStepIds);const completedStepIds=journal.completedStepIds;const completed=new Set(completedStepIds);if(Object.keys(journal.compensationData).some(stepId=>!started.has(stepId))||Object.keys(journal.results).some(stepId=>!completed.has(stepId)))return false;if(journal.status==="committed")return stepIds.every(stepId=>completed.has(stepId));return journal.status!=="compensated"||completed.size===0&&started.size===0}function parseJournal(raw,transactionId,stepIds){let parsed;try{parsed=JSON.parse(raw)}catch{throw new TypeError(`Workspace transaction ${transactionId} journal is invalid JSON`)}if(!parsed||typeof parsed!=="object"||Array.isArray(parsed))throw new TypeError(`Workspace transaction ${transactionId} journal is invalid`);const journal=parsed;const identityMatches=journal.schemaVersion===1&&journal.transactionId===transactionId;const stepsMatch=Array.isArray(journal.stepIds)&&journal.stepIds.length===stepIds.length&&journal.stepIds.every((stepId,index)=>stepId===stepIds[index]);const lifecycleMatches=hasValidJournalLifecycle(journal,stepIds);const metadataMatches=hasValidJournalMetadata(journal);const statusMatches=["applying","compensating","compensated","committed"].includes(String(journal.status));if(!identityMatches||!stepsMatch||!lifecycleMatches||!metadataMatches||!statusMatches)throw new TypeError(`Workspace transaction ${transactionId} journal does not match the supplied plan`);return{...journal,results:createResultMap(journal.results),compensationData:createResultMap(journal.compensationData)}}async function prepareJournalForApply(options,transactionId,author,stepIds,existing){let journal=existing;const recovered=journal!==void 0;if(journal?.status==="compensating")await compensateAppliedSteps(options,journal);if(journal===void 0||journal.status==="compensated"){const timestamp=nowIso();journal={schemaVersion:1,transactionId,author,status:"applying",attempt:(journal?.attempt??0)+1,createdAt:journal?.createdAt??timestamp,updatedAt:timestamp,stepIds,startedStepIds:[],completedStepIds:[],results:createResultMap(),compensationData:createResultMap()};await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"prepared")}return{journal,recovered}}async function applyPreparedTransaction(options,journal,recovered){try{await discoverAppliedSteps(journal,options.steps);await writeJournal(options.pmRoot,journal);const completed=new Set(journal.completedStepIds);const started=new Set(journal.startedStepIds);for(const step of options.steps){if(completed.has(step.id))continue;const inspection=await step.inspect();let result=cloneOptionalJournalValue(inspection.result,`Step ${step.id} result`);if(inspection.state!=="applied"){const compensationData=await step.prepareCompensation?.();setJournalEntry(journal.compensationData,step.id,compensationData,`Step ${step.id} compensation data`);started.add(step.id);journal.startedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>started.has(stepId));await writeJournal(options.pmRoot,journal);const appliedResult=await step.apply();result=cloneOptionalJournalValue(appliedResult,`Step ${step.id} result`)}await emitTransition(options,journal,"step_applied",step.id);completed.add(step.id);journal.completedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>completed.has(stepId));setJournalEntry(journal.results,step.id,result,`Step ${step.id} result`);await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"step_recorded",step.id)}await emitTransition(options,journal,"committing");journal.status="committed";await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"committed");return{transactionId:journal.transactionId,status:"committed",recovered,results:createResultMap(journal.results)}}catch(error){if(error instanceof WorkspaceTransactionInterruptedError||journal.status==="committed")throw error;try{await compensateAppliedSteps(options,journal)}catch(compensationError){throw new AggregateError([error,compensationError],`Workspace transaction failed and compensation failed: ${String(compensationError)}`,{cause:compensationError})}throw error}}async function loadJournal(pmRoot,transactionId,stepIds){try{return parseJournal(await readFile(journalPath(pmRoot,transactionId),"utf8"),transactionId,stepIds)}catch(error){if(error!==null&&typeof error==="object"&&"code"in error&&isFileMissingError(error))return void 0;throw error}}async function emitTransition(options,journal,transition,stepId){await options.onTransition?.({transactionId:journal.transactionId,attempt:journal.attempt,transition,...stepId===void 0?{}:{stepId}})}async function discoverAppliedSteps(journal,steps){const completed=new Set;const results=createResultMap();for(const step of steps){const inspection=await step.inspect();if(inspection.state==="applied"){completed.add(step.id);setJournalEntry(results,step.id,inspection.result,`Step ${step.id} result`)}}journal.results=results;journal.completedStepIds=steps.map(step=>step.id).filter(stepId=>completed.has(stepId))}async function compensateAppliedSteps(options,journal){journal.status="compensating";await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"compensating");const completed=new Set(journal.completedStepIds);const started=new Set(journal.startedStepIds);for(const step of[...options.steps].reverse()){if(!started.has(step.id)&&!completed.has(step.id))continue;let shouldCompensate;try{shouldCompensate=started.has(step.id)&&(await step.inspect()).state==="applied"}catch{shouldCompensate=started.has(step.id)}if(shouldCompensate){await emitTransition(options,journal,"step_compensating",step.id);await step.compensate(journal.compensationData[step.id])}completed.delete(step.id);started.delete(step.id);journal.completedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>completed.has(stepId));journal.startedStepIds=options.steps.map(candidate=>candidate.id).filter(stepId=>started.has(stepId));delete journal.results[step.id];delete journal.compensationData[step.id];await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"step_compensated",step.id)}journal.status="compensated";await writeJournal(options.pmRoot,journal);await emitTransition(options,journal,"compensated")}async function commitWorkspaceTransaction(options){const pmRoot=requiredText(options.pmRoot,"Transaction pmRoot");const transactionId=requiredIdentifier(options.transactionId,"Transaction id");const author=requiredText(options.author,"Transaction author");const lockTtlSeconds=positiveInteger(options.lockTtlSeconds,DEFAULT_LOCK_TTL_SECONDS,"Transaction lock TTL");const lockWaitMs=positiveInteger(options.lockWaitMs,DEFAULT_LOCK_WAIT_MS,"Transaction lock wait");const steps=[...options.steps];if(steps.length===0)throw new TypeError("Workspace transaction requires at least one step");const stepIds=steps.map(step=>{const stepId=requiredIdentifier(step.id,"Transaction step id");if(stepId!==step.id)throw new TypeError("Transaction step id must not contain surrounding whitespace");return stepId});if(new Set(stepIds).size!==stepIds.length)throw new TypeError("Workspace transaction step ids must be unique");const stableOptions={...options,pmRoot,transactionId,author,steps,lockTtlSeconds,lockWaitMs};const release=await acquireLock(pmRoot,WORKSPACE_TRANSACTION_LOCK_ID,lockTtlSeconds,author,false,false,lockWaitMs);try{const existing=await loadJournal(pmRoot,transactionId,stepIds);const recovered=existing!==void 0;if(existing?.status==="committed")return{transactionId,status:"committed",recovered:true,results:createResultMap(existing.results)};const prepared=await prepareJournalForApply(stableOptions,transactionId,author,stepIds,existing);return await applyPreparedTransaction(stableOptions,prepared.journal,recovered||prepared.recovered)}finally{await release()}}export{WorkspaceTransactionInterruptedError,commitWorkspaceTransaction};
 //# sourceMappingURL=workspace-transaction.js.map
-//# debugId=6ed4a26f-2ae2-556a-87db-56844108757f