@mikode13/harness 4.0.0 → 5.0.0

package/dist/recovery/domain/recoveryStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoveryStore.js","sourceRoot":"","sources":["../../../src/recovery/domain/recoveryStore.ts"],"names":[],"mappings":"AAwHA,oFAAoF;AACpF,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC;AAsCpC,2FAA2F;AAC3F,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC5C,YAAY,SAA0B;QACrC,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC;QACpF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IAClC,CAAC;CACD;AA4DD,uFAAuF;AACvF,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC7C,uEAAuE;IAC9D,QAAQ,CAAS;IAC1B,wDAAwD;IAC/C,MAAM,CAAS;IAExB,YAAY,QAAgB,EAAE,MAAc;QAC3C,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;QACxF,KAAK,CAAC,iCAAiC,IAAI,CAAC,QAAQ,CAAC,cAAc,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACnC,KAAK,CAAS;IAEvB,YAAY,KAAa;QACxB,KAAK,CAAC,0BAA0B,KAAK,mBAAmB,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;CACD","sourcesContent":["/**\n * What one path held at one moment: nothing, or a regular file with this content and mode.\n * `hash` names the content in the store, so the bytes themselves never travel in a record.\n */\nexport type FileState = { exists: false } | { exists: true; hash: string; mode: number };\n\n/**\n * One change to one file. It is recorded as `prepared` before the file is touched, and only\n * then applied, so a run that stops halfway always leaves a record of what it may have done.\n * `abandoned` means the change was prepared but never happened.\n */\nexport interface JournalEntry {\n\tsequence: number;\n\t/** The file's real path, absolute: a run may write to more than one root of its workspace. */\n\tpath: string;\n\tbefore: FileState;\n\tafter: FileState;\n\t/** Folders the change creates for a new file, outermost first: undo removes them if empty. */\n\tcreatedFolders?: string[];\n\t/**\n\t * The command whose run the change was seen around, for a change no tool of the harness made\n\t * itself. It was found by comparing the file before and after, not journaled before it was made.\n\t */\n\tobservedBy?: string;\n\tstatus: 'prepared' | 'applied' | 'abandoned';\n}\n\n/**\n * What a group of files held right before something outside the journal ran, such as a\n * command: the content of each, by its real path, absolute. It is stored as content, and the\n * journal names its hash before the command starts.\n */\nexport interface Manifest {\n\tfiles: Record<string, FileState>;\n}\n\n/** What one observation cost: before and after together. */\nexport interface ObservationMeasure {\n\t/** Files captured before, and compared after. */\n\tfiles: number;\n\tbytesRead: number;\n\t/** New content stored, which the store did not hold already. */\n\tbytesStored: number;\n\t/** Spent capturing and comparing, not running what was observed. */\n\tdurationMs: number;\n}\n\n/**\n * `interrupted` is a run whose process died while it was writing. The next run to take the\n * workspace settles each change it left `prepared`, from what the file holds now.\n */\nexport type RunStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'interrupted';\n\nexport interface RunRecord {\n\trunId: string;\n\t/** The real path of the workspace root the run wrote to. */\n\troot: string;\n\t/**\n\t * The run the workspace was at when this one started, so runs form a tree: going back to an\n\t * earlier run and writing again starts a new branch. Absent for the first run.\n\t */\n\tparentRunId?: string;\n\t/**\n\t * Runs whose changes retention chained into this one, oldest first. They are no longer in\n\t * the history: this run now goes back to where the oldest of them started.\n\t */\n\tabsorbed?: string[];\n\t/** The journal file that holds the run's changes. Absent while it is the first one written. */\n\tjournal?: string;\n\tstartedAt: string;\n\tfinishedAt?: string;\n\tstatus: RunStatus;\n\t/** The process that ran it, so a run whose process died can be told from a live one. */\n\tpid: number;\n}\n\n/**\n * The recovery record of one run that writes. Every method returns only once what it records\n * is on disk: a change is never made before the record that would undo it exists. Once a step\n * fails to reach the journal, the journal refuses every later step, because a line written\n * after a broken one could not be read back.\n */\nexport interface RunJournal {\n\treadonly runId: string;\n\t/** Stores `content` and returns the hash that names it. Content stored before is reused. */\n\tsaveContent(content: Buffer): Promise<string>;\n\t/** Records a change about to be made, and returns its sequence number. */\n\tprepare(change: Omit<JournalEntry, 'sequence' | 'status'>): Promise<number>;\n\t/** The change was made. */\n\tapplied(sequence: number): Promise<void>;\n\t/** The change was not made, and the file still holds its `before`. */\n\tabandoned(sequence: number): Promise<void>;\n\t/**\n\t * Records that `by`, such as a command, is about to change files the journal cannot see it\n\t * change, and that the stored `manifest` holds what they hold now. Each change it makes is\n\t * then recorded as its own entry, prepared and applied at once, before `observed`. If the run\n\t * stops first, the next run settles it: every file of the manifest that changed since is\n\t * recorded as changed by `by`. A file it created is not in the manifest, and is then missed.\n\t */\n\tobserve(manifest: string, by: string): Promise<number>;\n\t/**\n\t * Every change the observation found is recorded. `measure`, what capturing and comparing the\n\t * files cost, is kept with it.\n\t */\n\tobserved(sequence: number, measure?: ObservationMeasure): Promise<void>;\n\t/** How many bytes of content this run stored that the store did not hold yet. */\n\treadonly storedBytes: number;\n\t/**\n\t * Whether a change it recorded may have reached a file: one prepared and not abandoned. It\n\t * holds whatever happens to the record afterwards.\n\t */\n\treadonly changed: boolean;\n\t/**\n\t * Ends the run and releases the workspace for the next writer. A run that `changed` nothing\n\t * leaves the history, and the workspace is back at the run before it. If removing it fails,\n\t * the store still treats it as gone, and the next run or move finishes removing it.\n\t */\n\tfinish(status: Exclude<RunStatus, 'running' | 'interrupted'>): Promise<void>;\n}\n\n/** The point before any run: going there takes the workspace back to how it was. */\nexport const historyStart = 'start';\n\n/** A file a move left as it was, because it did not hold what the history expected there. */\nexport interface MoveConflict {\n\tpath: string;\n\t/** The run whose change could not be undone or redone. */\n\trunId: string;\n}\n\n/**\n * One move of the workspace through its history, kept so an agent that runs next can tell\n * that its conversation is about a state the workspace has left.\n */\nexport interface Revision {\n\t/** Counts the moves of this workspace, from 1. */\n\trevision: number;\n\t/** The run the workspace was at; absent for the start of the history. */\n\tfrom?: string;\n\t/** The run the workspace is at now; absent for the start of the history. */\n\tto?: string;\n\tat: string;\n\t/** Why the user went there, when the host asked. */\n\treason?: string;\n\t/** Every file reached the state the history expected. Otherwise `conflicts` names those that did not. */\n\tcomplete: boolean;\n\tconflicts: MoveConflict[];\n}\n\nexport interface MoveOptions {\n\t/** Why the user is moving the workspace, recorded with the move. */\n\treason?: string;\n\t/**\n\t * Where the workspace must be for the move to happen: a run, or `historyStart`. Checked under\n\t * the workspace lock, so a move confirmed against one state never runs from another.\n\t */\n\tfrom?: string;\n}\n\n/** There is nothing to undo at the start of the history, or nothing to redo at its tip. */\nexport class NothingToMoveError extends Error {\n\tconstructor(direction: 'undo' | 'redo') {\n\t\tsuper(direction === 'undo' ? 'There is no run to undo' : 'There is no run to redo');\n\t\tthis.name = 'NothingToMoveError';\n\t}\n}\n\n/**\n * Where the runs that write to one workspace keep what is needed to undo them, outside the\n * workspace itself. Only one run writes to a workspace at a time.\n */\nexport interface RecoveryStore {\n\t/**\n\t * Starts recording a run and holds the workspace for it until `finish`. The new run's parent\n\t * is the run the workspace is at, and the workspace is at the new run from then on. Runs a\n\t * dead process left `running` are settled first.\n\t *\n\t * @throws {WorkspaceBusyError} when another live run is writing to the workspace.\n\t */\n\tstartRun(): Promise<RunJournal>;\n\t/**\n\t * Every run, oldest first, and the run the workspace is at (`head`), absent before the first.\n\t * A run still recorded as `running` whose process is gone is listed as `interrupted`.\n\t */\n\tlistRuns(): Promise<{ head?: string; runs: RunRecord[] }>;\n\t/**\n\t * Moves the workspace to the state right after `target`, or to how it was before any run\n\t * with `historyStart`. It undoes runs one by one back to the closest common ancestor, then\n\t * redoes runs one by one forward to `target`. Each file is written only if it holds the\n\t * state the history expects there; one that does not is left as it is and reported, and the\n\t * move is then not `complete`. A move the process did not finish is finished by the next\n\t * move or run.\n\t *\n\t * @throws {WorkspaceBusyError} when a run or another move holds the workspace.\n\t * @throws {WorkspaceMovedError} when `from` was given and the workspace is elsewhere.\n\t * @throws {UnknownRunError} when `target` is not in the history.\n\t * @throws {HistoryExpiredError} when retention chained `target` into a later run.\n\t */\n\tgoTo(target: string, options?: MoveOptions): Promise<Revision>;\n\t/**\n\t * Moves the workspace to the run before the one it is at.\n\t *\n\t * @throws {NothingToMoveError} at the start of the history.\n\t */\n\tundo(options?: MoveOptions): Promise<Revision>;\n\t/**\n\t * Moves the workspace to the next run: towards where it was most recently, or the newest\n\t * branch.\n\t *\n\t * @throws {NothingToMoveError} when no run follows the one it is at.\n\t */\n\tredo(options?: MoveOptions): Promise<Revision>;\n\t/** Every move of the workspace, oldest first. */\n\tlistRevisions(): Promise<Revision[]>;\n\t/**\n\t * A run's record and its changes, in the order they were prepared.\n\t *\n\t * @throws {UnknownRunError} when `runId` was never a run of this workspace.\n\t * @throws {HistoryExpiredError} when retention removed `runId` or chained it into a later run.\n\t */\n\treadRun(runId: string): Promise<{ record: RunRecord; entries: JournalEntry[] }>;\n\t/** The bytes a hash names. */\n\treadContent(hash: string): Promise<Buffer>;\n}\n\n/** A move was asked from one point of the history, and the workspace is at another. */\nexport class WorkspaceMovedError extends Error {\n\t/** Where the move expected the workspace: a run, or `historyStart`. */\n\treadonly expected: string;\n\t/** Where the workspace is: a run, or `historyStart`. */\n\treadonly actual: string;\n\n\tconstructor(expected: string, actual: string) {\n\t\tconst name = (point: string) => (point === historyStart ? 'the start' : `run ${point}`);\n\t\tsuper(`The workspace is no longer at ${name(expected)}: it is at ${name(actual)}`);\n\t\tthis.name = 'WorkspaceMovedError';\n\t\tthis.expected = expected;\n\t\tthis.actual = actual;\n\t}\n}\n\nexport class WorkspaceBusyError extends Error {\n\treadonly runId: string;\n\n\tconstructor(runId: string) {\n\t\tsuper(`The workspace is busy: ${runId} is writing to it`);\n\t\tthis.name = 'WorkspaceBusyError';\n\t\tthis.runId = runId;\n\t}\n}\n"]}

package/dist/recovery/domain/retention.d.ts

@@ -0,0 +1,33 @@
+import type { JournalEntry, Revision, RunRecord } from './recoveryStore.ts';
+/** One step towards keeping at most a given number of runs. */
+export type PruneStep = 
+/** An abandoned run nothing depends on: it goes whole. */
+{
+    kind: 'remove';
+    runId: string;
+}
+/** A run on the current line: its changes are chained into `into`, its child on that line. */
+ | {
+    kind: 'chain';
+    runId: string;
+    into: string;
+};
+/**
+ * The line the user works along: from the first run after the start to the run the workspace is
+ * at, then on through the runs `redo` would take, so what can be redone is kept too.
+ */
+export declare function currentLine(runs: RunRecord[], revisions: Revision[], head: string | undefined): string[];
+/**
+ * The next step that brings the history down to `keep` runs, or `undefined` once it is there or
+ * nothing more can go. Abandoned branches go first, a leaf at a time, oldest first. Then the
+ * oldest run on the current line other than the one the workspace is at is chained into the
+ * next one, so the start of the history, before any run, always stays reachable.
+ */
+export declare function nextPruneStep(runs: RunRecord[], revisions: Revision[], head: string | undefined, keep: number): PruneStep | undefined;
+/**
+ * The changes of `older` followed by those of `newer`, as one run's: each file's chain reduced to
+ * its net, from before its first change to after its last, so the contents in between are no
+ * longer referenced. A break in a chain, where someone wrote to the file between two changes,
+ * is kept as a second change, so undoing still leaves that work alone.
+ */
+export declare function chainEntries(older: JournalEntry[], newer: JournalEntry[]): JournalEntry[];

package/dist/recovery/domain/retention.js

@@ -0,0 +1,90 @@
+import { sameState } from "./fileChanges.js";
+import { redoTarget } from "./runTree.js";
+/**
+ * The line the user works along: from the first run after the start to the run the workspace is
+ * at, then on through the runs `redo` would take, so what can be redone is kept too.
+ */
+export function currentLine(runs, revisions, head) {
+    const byId = new Map(runs.map(run => [run.runId, run]));
+    const line = [];
+    for (let runId = head; runId !== undefined; runId = byId.get(runId)?.parentRunId) {
+        line.unshift(runId);
+    }
+    for (let next = redoTarget(runs, revisions, head); next !== undefined;) {
+        line.push(next);
+        next = redoTarget(runs, revisions, next);
+    }
+    return line;
+}
+/**
+ * The next step that brings the history down to `keep` runs, or `undefined` once it is there or
+ * nothing more can go. Abandoned branches go first, a leaf at a time, oldest first. Then the
+ * oldest run on the current line other than the one the workspace is at is chained into the
+ * next one, so the start of the history, before any run, always stays reachable.
+ */
+export function nextPruneStep(runs, revisions, head, keep) {
+    if (runs.length <= keep)
+        return undefined;
+    const line = currentLine(runs, revisions, head);
+    const parents = new Set(runs.map(run => run.parentRunId));
+    const leaf = runs
+        .map(run => run.runId)
+        .filter(runId => !line.includes(runId) && !parents.has(runId))
+        .sort()[0];
+    if (leaf)
+        return { kind: 'remove', runId: leaf };
+    for (let index = 0; index + 1 < line.length; index++) {
+        const runId = line[index];
+        const into = line[index + 1];
+        if (runId !== undefined && into !== undefined && runId !== head) {
+            return { kind: 'chain', runId, into };
+        }
+    }
+    return undefined;
+}
+/**
+ * The changes of `older` followed by those of `newer`, as one run's: each file's chain reduced to
+ * its net, from before its first change to after its last, so the contents in between are no
+ * longer referenced. A break in a chain, where someone wrote to the file between two changes,
+ * is kept as a second change, so undoing still leaves that work alone.
+ */
+export function chainEntries(older, newer) {
+    const byPath = new Map();
+    for (const entry of [...older, ...newer]) {
+        if (entry.status === 'abandoned')
+            continue;
+        const segments = byPath.get(entry.path) ?? [];
+        const last = segments.at(-1);
+        const previous = last?.at(-1);
+        if (last && previous && sameState(previous.after, entry.before))
+            last.push(entry);
+        else
+            segments.push([entry]);
+        byPath.set(entry.path, segments);
+    }
+    const chained = [];
+    for (const [path, segments] of byPath) {
+        for (const segment of segments) {
+            const first = segment[0];
+            const last = segment.at(-1);
+            if (!first || !last)
+                continue;
+            const createdFolders = [...new Set(segment.flatMap(entry => entry.createdFolders ?? []))];
+            // Seen around commands only when no tool of the harness made any part of it.
+            const observers = new Set(segment.map(entry => entry.observedBy));
+            const observedBy = observers.has(undefined) ? undefined : [...observers].join(', ');
+            chained.push({
+                sequence: chained.length + 1,
+                path,
+                before: first.before,
+                after: last.after,
+                ...(createdFolders.length > 0 ? { createdFolders } : {}),
+                ...(observedBy === undefined ? {} : { observedBy }),
+                // One change nobody could settle leaves the whole chain unsettled.
+                status: segment.some(entry => entry.status === 'prepared') ? 'prepared' : 'applied',
+            });
+        }
+    }
+    return chained;
+}
+//# sourceMappingURL=retention.js.map

package/dist/recovery/domain/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../../src/recovery/domain/retention.ts"],"names":[],"mappings":"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","sourcesContent":["import { sameState } from './fileChanges.ts';\nimport type { JournalEntry, Revision, RunRecord } from './recoveryStore.ts';\nimport { redoTarget } from './runTree.ts';\n\n/** One step towards keeping at most a given number of runs. */\nexport type PruneStep =\n\t/** An abandoned run nothing depends on: it goes whole. */\n\t| { kind: 'remove'; runId: string }\n\t/** A run on the current line: its changes are chained into `into`, its child on that line. */\n\t| { kind: 'chain'; runId: string; into: string };\n\n/**\n * The line the user works along: from the first run after the start to the run the workspace is\n * at, then on through the runs `redo` would take, so what can be redone is kept too.\n */\nexport function currentLine(\n\truns: RunRecord[],\n\trevisions: Revision[],\n\thead: string | undefined,\n): string[] {\n\tconst byId = new Map(runs.map(run => [run.runId, run]));\n\tconst line: string[] = [];\n\tfor (let runId = head; runId !== undefined; runId = byId.get(runId)?.parentRunId) {\n\t\tline.unshift(runId);\n\t}\n\tfor (let next = redoTarget(runs, revisions, head); next !== undefined;) {\n\t\tline.push(next);\n\t\tnext = redoTarget(runs, revisions, next);\n\t}\n\treturn line;\n}\n\n/**\n * The next step that brings the history down to `keep` runs, or `undefined` once it is there or\n * nothing more can go. Abandoned branches go first, a leaf at a time, oldest first. Then the\n * oldest run on the current line other than the one the workspace is at is chained into the\n * next one, so the start of the history, before any run, always stays reachable.\n */\nexport function nextPruneStep(\n\truns: RunRecord[],\n\trevisions: Revision[],\n\thead: string | undefined,\n\tkeep: number,\n): PruneStep | undefined {\n\tif (runs.length <= keep) return undefined;\n\tconst line = currentLine(runs, revisions, head);\n\n\tconst parents = new Set(runs.map(run => run.parentRunId));\n\tconst leaf = runs\n\t\t.map(run => run.runId)\n\t\t.filter(runId => !line.includes(runId) && !parents.has(runId))\n\t\t.sort()[0];\n\tif (leaf) return { kind: 'remove', runId: leaf };\n\n\tfor (let index = 0; index + 1 < line.length; index++) {\n\t\tconst runId = line[index];\n\t\tconst into = line[index + 1];\n\t\tif (runId !== undefined && into !== undefined && runId !== head) {\n\t\t\treturn { kind: 'chain', runId, into };\n\t\t}\n\t}\n\treturn undefined;\n}\n\n/**\n * The changes of `older` followed by those of `newer`, as one run's: each file's chain reduced to\n * its net, from before its first change to after its last, so the contents in between are no\n * longer referenced. A break in a chain, where someone wrote to the file between two changes,\n * is kept as a second change, so undoing still leaves that work alone.\n */\nexport function chainEntries(older: JournalEntry[], newer: JournalEntry[]): JournalEntry[] {\n\tconst byPath = new Map<string, JournalEntry[][]>();\n\tfor (const entry of [...older, ...newer]) {\n\t\tif (entry.status === 'abandoned') continue;\n\t\tconst segments = byPath.get(entry.path) ?? [];\n\t\tconst last = segments.at(-1);\n\t\tconst previous = last?.at(-1);\n\t\tif (last && previous && sameState(previous.after, entry.before)) last.push(entry);\n\t\telse segments.push([entry]);\n\t\tbyPath.set(entry.path, segments);\n\t}\n\n\tconst chained: JournalEntry[] = [];\n\tfor (const [path, segments] of byPath) {\n\t\tfor (const segment of segments) {\n\t\t\tconst first = segment[0];\n\t\t\tconst last = segment.at(-1);\n\t\t\tif (!first || !last) continue;\n\t\t\tconst createdFolders = [...new Set(segment.flatMap(entry => entry.createdFolders ?? []))];\n\t\t\t// Seen around commands only when no tool of the harness made any part of it.\n\t\t\tconst observers = new Set(segment.map(entry => entry.observedBy));\n\t\t\tconst observedBy = observers.has(undefined) ? undefined : [...observers].join(', ');\n\t\t\tchained.push({\n\t\t\t\tsequence: chained.length + 1,\n\t\t\t\tpath,\n\t\t\t\tbefore: first.before,\n\t\t\t\tafter: last.after,\n\t\t\t\t...(createdFolders.length > 0 ? { createdFolders } : {}),\n\t\t\t\t...(observedBy === undefined ? {} : { observedBy }),\n\t\t\t\t// One change nobody could settle leaves the whole chain unsettled.\n\t\t\t\tstatus: segment.some(entry => entry.status === 'prepared') ? 'prepared' : 'applied',\n\t\t\t});\n\t\t}\n\t}\n\treturn chained;\n}\n"]}

package/dist/recovery/domain/runChanges.d.ts

@@ -0,0 +1,37 @@
+import { type FileChange } from './fileChanges.ts';
+import type { JournalEntry, RecoveryStore, RunRecord } from './recoveryStore.ts';
+export interface ShowChangesOptions {
+    /**
+     * The most lines of diff shown. What does not fit is named instead, in at most two more lines.
+     */
+    maxLines?: number;
+    /**
+     * Whether a file, by its real path, may be shown. A file it may not show is neither shown nor
+     * named: only how many there were is said. Defaults to every file.
+     */
+    visible?: (path: string) => Promise<boolean>;
+}
+/**
+ * What a run changed, as a git-style diff per file, in the order the run first touched each one.
+ * It shows each file from before the run's first change to after its last, so a file the run
+ * created and then deleted does not appear. A change a live run has prepared but not made yet
+ * is named, not shown. It reports the run's recorded effects, not a comparison of the whole
+ * repository.
+ */
+export declare function showChanges(store: RecoveryStore, runId: string, { maxLines, visible }?: ShowChangesOptions): Promise<string>;
+/**
+ * The files a run changed, in the order it first touched each one. A file left as it was, such
+ * as one the run created and then deleted, is not a change; one it may or may not have changed,
+ * or is changing now, is.
+ */
+export declare function changedFiles(record: RunRecord, entries: JournalEntry[]): FileChange[];
+/**
+ * Git's test, a NUL byte near the start, plus content that is not valid UTF-8: decoding would
+ * replace its bytes, and two different files could then show no difference.
+ */
+export declare function isText(content: Buffer): boolean;
+/**
+ * Relative to the run's root when inside it; a file in another root keeps its real path. Both
+ * are real absolute paths, with `/` as the separator on every supported platform.
+ */
+export declare function displayPath(root: string, path: string): string;

package/dist/recovery/domain/runChanges.js

@@ -0,0 +1,109 @@
+import { unifiedDiff } from '#src/diff/domain/unifiedDiff';
+import { fileChanges, sameState } from "./fileChanges.js";
+const binaryProbeBytes = 8000;
+/**
+ * What a run changed, as a git-style diff per file, in the order the run first touched each one.
+ * It shows each file from before the run's first change to after its last, so a file the run
+ * created and then deleted does not appear. A change a live run has prepared but not made yet
+ * is named, not shown. It reports the run's recorded effects, not a comparison of the whole
+ * repository.
+ */
+export async function showChanges(store, runId, { maxLines = 1000, visible } = {}) {
+    const { record, entries } = await store.readRun(runId);
+    const all = changedFiles(record, entries);
+    const changes = [];
+    for (const change of all)
+        if (!visible || (await visible(change.path)))
+            changes.push(change);
+    const output = [];
+    const hidden = all.length - changes.length;
+    if (hidden > 0) {
+        output.push(`# ${String(hidden)} changed ${hidden === 1 ? 'file is' : 'files are'} not shown: you may not read ${hidden === 1 ? 'it' : 'them'}`);
+    }
+    for (const [index, change] of changes.entries()) {
+        const name = displayPath(record.root, change.path);
+        const lines = await renderFile(store, name, change);
+        const room = maxLines - output.length;
+        if (lines.length <= room) {
+            output.push(...lines);
+            continue;
+        }
+        const rest = changes.slice(index + 1).map(next => displayPath(record.root, next.path));
+        const shown = Math.max(0, room);
+        output.push(...lines.slice(0, shown));
+        output.push(`... ${String(lines.length - shown)} more lines of the diff of ${name} not shown`);
+        if (rest.length > 0) {
+            output.push(`... ${String(rest.length)} more changed files not shown: ${rest.join(', ')}`);
+        }
+        break;
+    }
+    return output.join('\n');
+}
+/**
+ * The files a run changed, in the order it first touched each one. A file left as it was, such
+ * as one the run created and then deleted, is not a change; one it may or may not have changed,
+ * or is changing now, is.
+ */
+export function changedFiles(record, entries) {
+    return fileChanges(entries, record.status !== 'running').filter(change => change.uncertain || change.pending || !sameState(change.before, change.after));
+}
+async function renderFile(store, name, change) {
+    const { before, after } = change;
+    const lines = [];
+    if (change.uncertain) {
+        lines.push(`# ${name}: the run stopped while changing this file; it may not hold this change`);
+    }
+    if (change.observedBy.length > 0) {
+        const commands = change.observedBy.map(command => `"${command}"`).join(', ');
+        lines.push(`# ${name}: changed while the command ${commands} ran, seen by comparing before and after`);
+    }
+    if (change.pending) {
+        lines.push(`# ${name}: the run is changing this file now; that change is not shown`);
+        if (sameState(before, after))
+            return lines;
+    }
+    lines.push(`diff --git a/${name} b/${name}`);
+    if (!before.exists && after.exists)
+        lines.push(`new file mode ${gitMode(after.mode)}`);
+    if (before.exists && !after.exists)
+        lines.push(`deleted file mode ${gitMode(before.mode)}`);
+    if (before.exists && after.exists && before.mode !== after.mode) {
+        lines.push(`old mode ${gitMode(before.mode)}`, `new mode ${gitMode(after.mode)}`);
+    }
+    if (before.exists && after.exists && before.hash === after.hash)
+        return lines;
+    const oldContent = before.exists ? await store.readContent(before.hash) : Buffer.alloc(0);
+    const newContent = after.exists ? await store.readContent(after.hash) : Buffer.alloc(0);
+    const oldName = before.exists ? `a/${name}` : '/dev/null';
+    const newName = after.exists ? `b/${name}` : '/dev/null';
+    if (!isText(oldContent) || !isText(newContent)) {
+        lines.push(`Binary files ${oldName} and ${newName} differ`);
+        return lines;
+    }
+    const hunks = unifiedDiff(oldContent.toString('utf8'), newContent.toString('utf8'));
+    // An empty file created or deleted has no hunks, as in git.
+    if (hunks !== '')
+        lines.push(`--- ${oldName}`, `+++ ${newName}`, ...hunks.split('\n'));
+    return lines;
+}
+/**
+ * Git's test, a NUL byte near the start, plus content that is not valid UTF-8: decoding would
+ * replace its bytes, and two different files could then show no difference.
+ */
+export function isText(content) {
+    if (content.subarray(0, binaryProbeBytes).includes(0))
+        return false;
+    return Buffer.from(content.toString('utf8'), 'utf8').equals(content);
+}
+/** A regular file's mode as git writes it, such as `100644`. */
+function gitMode(mode) {
+    return (0o100000 | mode).toString(8);
+}
+/**
+ * Relative to the run's root when inside it; a file in another root keeps its real path. Both
+ * are real absolute paths, with `/` as the separator on every supported platform.
+ */
+export function displayPath(root, path) {
+    return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+}
+//# sourceMappingURL=runChanges.js.map

package/dist/recovery/domain/runChanges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runChanges.js","sourceRoot":"","sources":["../../../src/recovery/domain/runChanges.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAmB,WAAW,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG3E,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAc9B;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,KAAoB,EACpB,KAAa,EACb,EAAE,QAAQ,GAAG,IAAI,EAAE,OAAO,KAAyB,EAAE;IAErD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACvD,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,MAAM,IAAI,GAAG;QAAE,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7F,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC3C,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAChB,MAAM,CAAC,IAAI,CACV,KAAK,MAAM,CAAC,MAAM,CAAC,YAAY,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,gCAAgC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CACnI,CAAC;IACH,CAAC;IAED,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QACjD,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACnD,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACpD,MAAM,IAAI,GAAG,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;QACtC,IAAI,KAAK,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;YACtB,SAAS;QACV,CAAC;QAED,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACvF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAChC,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,8BAA8B,IAAI,YAAY,CAAC,CAAC;QAC/F,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,kCAAkC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD,MAAM;IACP,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB,EAAE,OAAuB;IACtE,OAAO,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,MAAM,CAC9D,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CACvF,CAAC;AACH,CAAC;AAED,KAAK,UAAU,UAAU,CACxB,KAAoB,EACpB,IAAY,EACZ,MAAkB;IAElB,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,yEAAyE,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7E,KAAK,CAAC,IAAI,CACT,KAAK,IAAI,+BAA+B,QAAQ,0CAA0C,CAC1F,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,+DAA+D,CAAC,CAAC;QACrF,IAAI,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;IAC5C,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,gBAAgB,IAAI,MAAM,IAAI,EAAE,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,iBAAiB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvF,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,qBAAqB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5F,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;QACjE,KAAK,CAAC,IAAI,CAAC,YAAY,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,YAAY,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IAE9E,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1F,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACxF,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC;IAC1D,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC;IAEzD,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,gBAAgB,OAAO,QAAQ,OAAO,SAAS,CAAC,CAAC;QAC5D,OAAO,KAAK,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACpF,4DAA4D;IAC5D,IAAI,KAAK,KAAK,EAAE;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,EAAE,EAAE,OAAO,OAAO,EAAE,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACvF,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,OAAe;IACrC,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACpE,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACtE,CAAC;AAED,gEAAgE;AAChE,SAAS,OAAO,CAAC,IAAY;IAC5B,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,IAAY;IACrD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACzE,CAAC","sourcesContent":["import { unifiedDiff } from '#src/diff/domain/unifiedDiff';\nimport { type FileChange, fileChanges, sameState } from './fileChanges.ts';\nimport type { JournalEntry, RecoveryStore, RunRecord } from './recoveryStore.ts';\n\nconst binaryProbeBytes = 8000;\n\nexport interface ShowChangesOptions {\n\t/**\n\t * The most lines of diff shown. What does not fit is named instead, in at most two more lines.\n\t */\n\tmaxLines?: number;\n\t/**\n\t * Whether a file, by its real path, may be shown. A file it may not show is neither shown nor\n\t * named: only how many there were is said. Defaults to every file.\n\t */\n\tvisible?: (path: string) => Promise<boolean>;\n}\n\n/**\n * What a run changed, as a git-style diff per file, in the order the run first touched each one.\n * It shows each file from before the run's first change to after its last, so a file the run\n * created and then deleted does not appear. A change a live run has prepared but not made yet\n * is named, not shown. It reports the run's recorded effects, not a comparison of the whole\n * repository.\n */\nexport async function showChanges(\n\tstore: RecoveryStore,\n\trunId: string,\n\t{ maxLines = 1000, visible }: ShowChangesOptions = {},\n): Promise<string> {\n\tconst { record, entries } = await store.readRun(runId);\n\tconst all = changedFiles(record, entries);\n\tconst changes: FileChange[] = [];\n\tfor (const change of all) if (!visible || (await visible(change.path))) changes.push(change);\n\tconst output: string[] = [];\n\tconst hidden = all.length - changes.length;\n\tif (hidden > 0) {\n\t\toutput.push(\n\t\t\t`# ${String(hidden)} changed ${hidden === 1 ? 'file is' : 'files are'} not shown: you may not read ${hidden === 1 ? 'it' : 'them'}`,\n\t\t);\n\t}\n\n\tfor (const [index, change] of changes.entries()) {\n\t\tconst name = displayPath(record.root, change.path);\n\t\tconst lines = await renderFile(store, name, change);\n\t\tconst room = maxLines - output.length;\n\t\tif (lines.length <= room) {\n\t\t\toutput.push(...lines);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst rest = changes.slice(index + 1).map(next => displayPath(record.root, next.path));\n\t\tconst shown = Math.max(0, room);\n\t\toutput.push(...lines.slice(0, shown));\n\t\toutput.push(`... ${String(lines.length - shown)} more lines of the diff of ${name} not shown`);\n\t\tif (rest.length > 0) {\n\t\t\toutput.push(`... ${String(rest.length)} more changed files not shown: ${rest.join(', ')}`);\n\t\t}\n\t\tbreak;\n\t}\n\n\treturn output.join('\\n');\n}\n\n/**\n * The files a run changed, in the order it first touched each one. A file left as it was, such\n * as one the run created and then deleted, is not a change; one it may or may not have changed,\n * or is changing now, is.\n */\nexport function changedFiles(record: RunRecord, entries: JournalEntry[]): FileChange[] {\n\treturn fileChanges(entries, record.status !== 'running').filter(\n\t\tchange => change.uncertain || change.pending || !sameState(change.before, change.after),\n\t);\n}\n\nasync function renderFile(\n\tstore: RecoveryStore,\n\tname: string,\n\tchange: FileChange,\n): Promise<string[]> {\n\tconst { before, after } = change;\n\tconst lines: string[] = [];\n\tif (change.uncertain) {\n\t\tlines.push(`# ${name}: the run stopped while changing this file; it may not hold this change`);\n\t}\n\tif (change.observedBy.length > 0) {\n\t\tconst commands = change.observedBy.map(command => `\"${command}\"`).join(', ');\n\t\tlines.push(\n\t\t\t`# ${name}: changed while the command ${commands} ran, seen by comparing before and after`,\n\t\t);\n\t}\n\tif (change.pending) {\n\t\tlines.push(`# ${name}: the run is changing this file now; that change is not shown`);\n\t\tif (sameState(before, after)) return lines;\n\t}\n\tlines.push(`diff --git a/${name} b/${name}`);\n\tif (!before.exists && after.exists) lines.push(`new file mode ${gitMode(after.mode)}`);\n\tif (before.exists && !after.exists) lines.push(`deleted file mode ${gitMode(before.mode)}`);\n\tif (before.exists && after.exists && before.mode !== after.mode) {\n\t\tlines.push(`old mode ${gitMode(before.mode)}`, `new mode ${gitMode(after.mode)}`);\n\t}\n\tif (before.exists && after.exists && before.hash === after.hash) return lines;\n\n\tconst oldContent = before.exists ? await store.readContent(before.hash) : Buffer.alloc(0);\n\tconst newContent = after.exists ? await store.readContent(after.hash) : Buffer.alloc(0);\n\tconst oldName = before.exists ? `a/${name}` : '/dev/null';\n\tconst newName = after.exists ? `b/${name}` : '/dev/null';\n\n\tif (!isText(oldContent) || !isText(newContent)) {\n\t\tlines.push(`Binary files ${oldName} and ${newName} differ`);\n\t\treturn lines;\n\t}\n\tconst hunks = unifiedDiff(oldContent.toString('utf8'), newContent.toString('utf8'));\n\t// An empty file created or deleted has no hunks, as in git.\n\tif (hunks !== '') lines.push(`--- ${oldName}`, `+++ ${newName}`, ...hunks.split('\\n'));\n\treturn lines;\n}\n\n/**\n * Git's test, a NUL byte near the start, plus content that is not valid UTF-8: decoding would\n * replace its bytes, and two different files could then show no difference.\n */\nexport function isText(content: Buffer): boolean {\n\tif (content.subarray(0, binaryProbeBytes).includes(0)) return false;\n\treturn Buffer.from(content.toString('utf8'), 'utf8').equals(content);\n}\n\n/** A regular file's mode as git writes it, such as `100644`. */\nfunction gitMode(mode: number): string {\n\treturn (0o100000 | mode).toString(8);\n}\n\n/**\n * Relative to the run's root when inside it; a file in another root keeps its real path. Both\n * are real absolute paths, with `/` as the separator on every supported platform.\n */\nexport function displayPath(root: string, path: string): string {\n\treturn path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;\n}\n"]}

package/dist/recovery/domain/runTree.d.ts

@@ -0,0 +1,32 @@
+import type { Revision, RunRecord } from './recoveryStore.ts';
+/** The runs to undo, newest first, then the runs to redo, oldest first. */
+export interface Route {
+    undo: string[];
+    redo: string[];
+}
+/** A run named in the history is not kept any more, or never existed. */
+export declare class UnknownRunError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/**
+ * Retention removed a run: an abandoned one whole, or one on the current line by chaining its
+ * changes into the next run. Either way the state right after it is gone.
+ */
+export declare class HistoryExpiredError extends Error {
+    readonly runId: string;
+    /** The run that now holds its changes, when it was chained rather than removed. */
+    readonly keptIn: string | undefined;
+    constructor(runId: string, keptIn?: string);
+}
+/**
+ * The runs from `from` to `to` through their closest common ancestor. `undefined` is the start
+ * of the history, before any run.
+ */
+export declare function route(runs: RunRecord[], from: string | undefined, to: string | undefined): Route;
+/**
+ * The run `redo` goes to from `head`: the child of `head` towards the run the workspace was at
+ * most recently, so going back and forward again returns where it was. Without one, the newest
+ * child. `undefined` when `head` has no children.
+ */
+export declare function redoTarget(runs: RunRecord[], revisions: Revision[], head: string | undefined): string | undefined;

package/dist/recovery/domain/runTree.js

@@ -0,0 +1,90 @@
+/** A run named in the history is not kept any more, or never existed. */
+export class UnknownRunError extends Error {
+    runId;
+    constructor(runId) {
+        super(`Run ${runId} is not in the history of this workspace`);
+        this.name = 'UnknownRunError';
+        this.runId = runId;
+    }
+}
+/**
+ * Retention removed a run: an abandoned one whole, or one on the current line by chaining its
+ * changes into the next run. Either way the state right after it is gone.
+ */
+export class HistoryExpiredError extends Error {
+    runId;
+    /** The run that now holds its changes, when it was chained rather than removed. */
+    keptIn;
+    constructor(runId, keptIn) {
+        super(keptIn
+            ? `Run ${runId} is no longer kept: its changes are now part of run ${keptIn}`
+            : `Run ${runId} is no longer kept`);
+        this.name = 'HistoryExpiredError';
+        this.runId = runId;
+        this.keptIn = keptIn;
+    }
+}
+/**
+ * The runs from `from` to `to` through their closest common ancestor. `undefined` is the start
+ * of the history, before any run.
+ */
+export function route(runs, from, to) {
+    const byId = new Map(runs.map(run => [run.runId, run]));
+    const back = ancestry(byId, from);
+    const forward = ancestry(byId, to);
+    // Both lines end at the start, so they share at least that much.
+    const shared = forward.filter(runId => back.includes(runId));
+    const meeting = shared[0];
+    return {
+        undo: until(back, meeting),
+        redo: until(forward, meeting).reverse(),
+    };
+}
+/**
+ * The run `redo` goes to from `head`: the child of `head` towards the run the workspace was at
+ * most recently, so going back and forward again returns where it was. Without one, the newest
+ * child. `undefined` when `head` has no children.
+ */
+export function redoTarget(runs, revisions, head) {
+    const byId = new Map(runs.map(run => [run.runId, run]));
+    const children = runs.filter(run => run.parentRunId === head).map(run => run.runId);
+    if (children.length === 0)
+        return undefined;
+    for (const revision of [...revisions].reverse()) {
+        for (const visited of [revision.from, revision.to]) {
+            // Up from where the workspace was, until one of the children, if it is below `head`.
+            for (let current = visited; current !== undefined; current = byId.get(current)?.parentRunId) {
+                if (children.includes(current))
+                    return current;
+            }
+        }
+    }
+    return children.sort().at(-1);
+}
+/**
+ * `runId` and its ancestors, newest first. A parent that is not kept any more makes the line
+ * unknown, because the workspace could not be moved across it.
+ */
+function ancestry(byId, runId) {
+    const line = [];
+    for (let current = runId; current !== undefined;) {
+        const run = byId.get(current);
+        if (!run)
+            throw new UnknownRunError(current);
+        line.push(current);
+        current = run.parentRunId;
+    }
+    line.push(undefined);
+    return line;
+}
+/** The runs of `line` before `meeting`. */
+function until(line, meeting) {
+    const result = [];
+    for (const runId of line) {
+        if (runId === meeting || runId === undefined)
+            break;
+        result.push(runId);
+    }
+    return result;
+}
+//# sourceMappingURL=runTree.js.map

package/dist/recovery/domain/runTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runTree.js","sourceRoot":"","sources":["../../../src/recovery/domain/runTree.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Revision, RunRecord } from './recoveryStore.ts';\n\n/** The runs to undo, newest first, then the runs to redo, oldest first. */\nexport interface Route {\n\tundo: string[];\n\tredo: string[];\n}\n\n/** A run named in the history is not kept any more, or never existed. */\nexport class UnknownRunError extends Error {\n\treadonly runId: string;\n\n\tconstructor(runId: string) {\n\t\tsuper(`Run ${runId} is not in the history of this workspace`);\n\t\tthis.name = 'UnknownRunError';\n\t\tthis.runId = runId;\n\t}\n}\n\n/**\n * Retention removed a run: an abandoned one whole, or one on the current line by chaining its\n * changes into the next run. Either way the state right after it is gone.\n */\nexport class HistoryExpiredError extends Error {\n\treadonly runId: string;\n\t/** The run that now holds its changes, when it was chained rather than removed. */\n\treadonly keptIn: string | undefined;\n\n\tconstructor(runId: string, keptIn?: string) {\n\t\tsuper(\n\t\t\tkeptIn\n\t\t\t\t? `Run ${runId} is no longer kept: its changes are now part of run ${keptIn}`\n\t\t\t\t: `Run ${runId} is no longer kept`,\n\t\t);\n\t\tthis.name = 'HistoryExpiredError';\n\t\tthis.runId = runId;\n\t\tthis.keptIn = keptIn;\n\t}\n}\n\n/**\n * The runs from `from` to `to` through their closest common ancestor. `undefined` is the start\n * of the history, before any run.\n */\nexport function route(runs: RunRecord[], from: string | undefined, to: string | undefined): Route {\n\tconst byId = new Map(runs.map(run => [run.runId, run]));\n\tconst back = ancestry(byId, from);\n\tconst forward = ancestry(byId, to);\n\t// Both lines end at the start, so they share at least that much.\n\tconst shared = forward.filter(runId => back.includes(runId));\n\tconst meeting = shared[0];\n\n\treturn {\n\t\tundo: until(back, meeting),\n\t\tredo: until(forward, meeting).reverse(),\n\t};\n}\n\n/**\n * The run `redo` goes to from `head`: the child of `head` towards the run the workspace was at\n * most recently, so going back and forward again returns where it was. Without one, the newest\n * child. `undefined` when `head` has no children.\n */\nexport function redoTarget(\n\truns: RunRecord[],\n\trevisions: Revision[],\n\thead: string | undefined,\n): string | undefined {\n\tconst byId = new Map(runs.map(run => [run.runId, run]));\n\tconst children = runs.filter(run => run.parentRunId === head).map(run => run.runId);\n\tif (children.length === 0) return undefined;\n\n\tfor (const revision of [...revisions].reverse()) {\n\t\tfor (const visited of [revision.from, revision.to]) {\n\t\t\t// Up from where the workspace was, until one of the children, if it is below `head`.\n\t\t\tfor (let current = visited; current !== undefined; current = byId.get(current)?.parentRunId) {\n\t\t\t\tif (children.includes(current)) return current;\n\t\t\t}\n\t\t}\n\t}\n\treturn children.sort().at(-1);\n}\n\n/**\n * `runId` and its ancestors, newest first. A parent that is not kept any more makes the line\n * unknown, because the workspace could not be moved across it.\n */\nfunction ancestry(byId: Map<string, RunRecord>, runId: string | undefined): (string | undefined)[] {\n\tconst line: (string | undefined)[] = [];\n\tfor (let current = runId; current !== undefined;) {\n\t\tconst run = byId.get(current);\n\t\tif (!run) throw new UnknownRunError(current);\n\t\tline.push(current);\n\t\tcurrent = run.parentRunId;\n\t}\n\tline.push(undefined);\n\treturn line;\n}\n\n/** The runs of `line` before `meeting`. */\nfunction until(line: (string | undefined)[], meeting: string | undefined): string[] {\n\tconst result: string[] = [];\n\tfor (const runId of line) {\n\t\tif (runId === meeting || runId === undefined) break;\n\t\tresult.push(runId);\n\t}\n\treturn result;\n}\n"]}

package/dist/recovery/infrastructure/createHistory.d.ts

@@ -0,0 +1,11 @@
+import { type History } from '../domain/history.ts';
+/**
+ * The history of the runs that wrote to `root`, kept outside it under the platform's state
+ * directory. Only runs of a model-backed agent with write tools are recorded: the Agent SDK
+ * engines change files through their own tools, and their changes are not in it.
+ */
+export declare function createHistory({ root, stateDirectory, }: {
+    root: string;
+    /** Where the history is kept. Defaults to the platform's state directory. */
+    stateDirectory?: string;
+}): Promise<History>;

package/dist/recovery/infrastructure/createHistory.js

@@ -0,0 +1,17 @@
+import { realpath } from 'node:fs/promises';
+import { StoreHistory } from "../domain/history.js";
+import { FileRecoveryStore } from "./fileRecoveryStore.js";
+/**
+ * The history of the runs that wrote to `root`, kept outside it under the platform's state
+ * directory. Only runs of a model-backed agent with write tools are recorded: the Agent SDK
+ * engines change files through their own tools, and their changes are not in it.
+ */
+export async function createHistory({ root, stateDirectory, }) {
+    const store = await FileRecoveryStore.open({
+        root,
+        ...(stateDirectory === undefined ? {} : { directory: stateDirectory }),
+    });
+    // The store keys the workspace by its real path, and records real paths.
+    return new StoreHistory({ store, root: await realpath(root) });
+}
+//# sourceMappingURL=createHistory.js.map

package/dist/recovery/infrastructure/createHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createHistory.js","sourceRoot":"","sources":["../../../src/recovery/infrastructure/createHistory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAgB,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EACnC,IAAI,EACJ,cAAc,GAKd;IACA,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC;QAC1C,IAAI;QACJ,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC;KACtE,CAAC,CAAC;IACH,yEAAyE;IACzE,OAAO,IAAI,YAAY,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAChE,CAAC","sourcesContent":["import { realpath } from 'node:fs/promises';\nimport { type History, StoreHistory } from '../domain/history.ts';\nimport { FileRecoveryStore } from './fileRecoveryStore.ts';\n\n/**\n * The history of the runs that wrote to `root`, kept outside it under the platform's state\n * directory. Only runs of a model-backed agent with write tools are recorded: the Agent SDK\n * engines change files through their own tools, and their changes are not in it.\n */\nexport async function createHistory({\n\troot,\n\tstateDirectory,\n}: {\n\troot: string;\n\t/** Where the history is kept. Defaults to the platform's state directory. */\n\tstateDirectory?: string;\n}): Promise<History> {\n\tconst store = await FileRecoveryStore.open({\n\t\troot,\n\t\t...(stateDirectory === undefined ? {} : { directory: stateDirectory }),\n\t});\n\t// The store keys the workspace by its real path, and records real paths.\n\treturn new StoreHistory({ store, root: await realpath(root) });\n}\n"]}