@anionex/dsh-turn-rewind 0.1.1 → 0.2.0

package/lib/git.js

@@ -1,26 +1,27 @@
-import { execFile } from 'node:child_process';
-import { lstat, realpath } from 'node:fs/promises';
-import { dirname, isAbsolute, resolve } from 'node:path';
+import { execFile, spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { link, lstat, mkdir, open, readFile, realpath, unlink } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { ChangeLedgerError, errorMessage } from './errors.js';
-import { canonicalDirectory, isNodeError, validateRelativePath } from './path-utils.js';
+import { canonicalDirectory, isNodeError, syncDirectory, validateRelativePath } from './path-utils.js';
 const GIT_MAX_BUFFER = 32 * 1024 * 1024;
 /** Discover the Git worktree owning `cwd` and enumerate tracked/non-ignored paths. */
 export async function discoverRepository(cwd, signal) {
     const root = await discoverRepositoryRoot(cwd, signal);
-    const sparse = (await gitOptional(root, ['config', '--bool', '--get', 'core.sparseCheckout'], signal))?.trim() === 'true';
+    const sparse = (await runGitOptional(root, ['config', '--bool', '--get', 'core.sparseCheckout'], signal))?.trim() === 'true';
     if (sparse) {
         throw new ChangeLedgerError('SPARSE_CHECKOUT_UNSUPPORTED', 'sparse-checkout worktrees are not supported because absent paths are ambiguous');
     }
-    const gitDirRaw = stripLineEnding(await git(root, ['rev-parse', '--git-dir'], signal));
+    const gitDirRaw = stripLineEnding(await runGit(root, ['rev-parse', '--git-dir'], signal));
     const gitDir = await realpath(resolve(root, gitDirRaw));
-    const commonDirRaw = stripLineEnding(await git(root, ['rev-parse', '--git-common-dir'], signal));
+    const commonDirRaw = stripLineEnding(await runGit(root, ['rev-parse', '--git-common-dir'], signal));
     const commonDir = await realpath(resolve(root, commonDirRaw));
-    const stageOutput = await git(root, ['ls-files', '--stage', '-z'], signal);
+    const stageOutput = await runGit(root, ['ls-files', '--stage', '-z'], signal);
     const submodules = parseSubmodules(stageOutput);
     if (submodules.length > 0) {
         throw new ChangeLedgerError('SUBMODULE_UNSUPPORTED', `submodules require independent restore points; unsupported gitlinks: ${submodules.slice(0, 10).join(', ')}`);
     }
-    const pathOutput = await git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], signal);
+    const pathOutput = await runGit(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], signal);
     // `ls-files --others` refuses to descend into embedded repositories, such as a
     // linked worktree nested inside this checkout; it reports the directory itself
     // with a trailing slash (for example `nested/`). Those directories are separate
@@ -29,9 +30,9 @@ export async function discoverRepository(cwd, signal) {
     const paths = [...new Set(splitNul(pathOutput)
             .filter((path) => !path.endsWith('/'))
             .map(validateRelativePath))].sort(comparePaths);
-    const head = trimOptional(await gitOptional(root, ['rev-parse', '--verify', '--quiet', 'HEAD'], signal));
-    const branch = trimOptional(await gitOptional(root, ['symbolic-ref', '--quiet', '--short', 'HEAD'], signal));
-    const stagedOutput = await git(root, ['diff', '--cached', '--name-only', '-z'], signal);
+    const head = trimOptional(await runGitOptional(root, ['rev-parse', '--verify', '--quiet', 'HEAD'], signal));
+    const branch = trimOptional(await runGitOptional(root, ['symbolic-ref', '--quiet', '--short', 'HEAD'], signal));
+    const stagedOutput = await runGit(root, ['diff', '--cached', '--name-only', '-z'], signal);
     const stagedPaths = splitNul(stagedOutput).map(validateRelativePath).sort(comparePaths);
     const operation = await gitOperation(gitDir);
     return {
@@ -49,13 +50,55 @@ export async function discoverRepository(cwd, signal) {
 /** Resolve the canonical Git worktree root owning `cwd` without inventorying its files. */
 export async function discoverRepositoryRoot(cwd, signal) {
     const canonicalCwd = await canonicalDirectory(cwd);
-    const rootRaw = await git(canonicalCwd, ['rev-parse', '--show-toplevel'], signal);
+    const rootRaw = await runGit(canonicalCwd, ['rev-parse', '--show-toplevel'], signal);
     const root = await realpath(stripLineEnding(rootRaw));
     if (!isAbsolute(root)) {
         throw new ChangeLedgerError('GIT_ROOT_INVALID', `git returned a non-absolute worktree root: ${JSON.stringify(root)}`);
     }
     return root;
 }
+/** Create or read the per-worktree identity used by refs and cross-store locking. */
+export async function ensureGitWorktreeIdentity(cwd, signal) {
+    const root = await discoverRepositoryRoot(cwd, signal);
+    const gitDir = await realpath(resolve(root, stripLineEnding(await runGit(root, ['rev-parse', '--git-dir'], signal))));
+    const commonDir = await realpath(resolve(root, stripLineEnding(await runGit(root, ['rev-parse', '--git-common-dir'], signal))));
+    const identityDir = join(gitDir, 'dsh-turn-rewind');
+    await mkdir(identityDir, { recursive: true, mode: 0o700 });
+    const worktreeId = await ensureWorktreeId(identityDir, commonDir, gitDir);
+    return {
+        root,
+        gitDir,
+        commonDir,
+        worktreeId,
+        lockPath: join(commonDir, 'dsh-turn-rewind', 'locks', `${worktreeId}.json`),
+    };
+}
+/** Resolve a moved linked worktree from its common directory and durable identity. */
+export async function resolveGitWorktreeRoot(commonDir, worktreeId, fallback, signal) {
+    const candidates = [fallback];
+    try {
+        const output = await runGit(commonDir, [`--git-dir=${commonDir}`, 'worktree', 'list', '--porcelain', '-z'], signal);
+        for (const record of output.split('\0\0')) {
+            const first = record.split('\0', 1)[0];
+            if (first?.startsWith('worktree '))
+                candidates.push(first.slice('worktree '.length));
+        }
+    }
+    catch {
+        // The fallback below still gives deterministic failure details if the common directory is gone.
+    }
+    for (const candidate of [...new Set(candidates)]) {
+        try {
+            const identity = await readGitWorktreeIdentity(candidate, signal);
+            if (identity.worktreeId === worktreeId && identity.commonDir === commonDir)
+                return identity.root;
+        }
+        catch {
+            // Missing/pruned/unrelated worktrees are not candidates for this durable identity.
+        }
+    }
+    throw new ChangeLedgerError('GIT_WORKTREE_MISSING', `cannot locate Git worktree ${worktreeId} under ${JSON.stringify(commonDir)}`);
+}
 /** Return true when two repository fences refer to the same checkout state. */
 export function sameRepositoryFence(left, right) {
     return left.root === right.root
@@ -64,20 +107,21 @@ export function sameRepositoryFence(left, right) {
         && left.branch === right.branch
         && left.operation === right.operation;
 }
-async function git(cwd, args, signal) {
+/** Run Git with stable non-interactive defaults and return UTF-8 output. */
+export async function runGit(cwd, args, signal, options = {}) {
     return new Promise((resolvePromise, reject) => {
         execFile('git', ['-c', 'core.quotepath=false', '-C', cwd, ...args], {
             encoding: 'utf8',
-            maxBuffer: GIT_MAX_BUFFER,
+            maxBuffer: options.maxBuffer ?? GIT_MAX_BUFFER,
             windowsHide: true,
             signal,
-            env: {
-                ...process.env,
-                GIT_OPTIONAL_LOCKS: '0',
-                GIT_TERMINAL_PROMPT: '0',
-            },
+            env: gitEnvironment(options.env),
         }, (error, stdout, stderr) => {
             if (error !== null) {
+                if (signal?.aborted === true) {
+                    reject(signal.reason ?? error);
+                    return;
+                }
                 reject(new ChangeLedgerError('GIT_COMMAND_FAILED', `git ${args.join(' ')} failed in ${JSON.stringify(cwd)}: ${stderr.trim() || errorMessage(error)}`, { cause: error }));
                 return;
             }
@@ -85,9 +129,10 @@ async function git(cwd, args, signal) {
         });
     });
 }
-async function gitOptional(cwd, args, signal) {
+/** Run Git and return undefined for its ordinary "not found" exit status. */
+export async function runGitOptional(cwd, args, signal, options = {}) {
     try {
-        return await git(cwd, args, signal);
+        return await runGit(cwd, args, signal, options);
     }
     catch (error) {
         if (error instanceof ChangeLedgerError && error.code === 'GIT_COMMAND_FAILED' && gitExitCode(error.cause) === 1)
@@ -95,6 +140,105 @@ async function gitOptional(cwd, args, signal) {
         throw error;
     }
 }
+/** Run Git with binary stdin and return UTF-8 stdout. */
+export async function runGitInput(cwd, args, input, signal, options = {}) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn('git', ['-c', 'core.quotepath=false', '-C', cwd, ...args], {
+            windowsHide: true,
+            signal,
+            env: gitEnvironment(options.env),
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const stdout = [];
+        const stderr = [];
+        let stdoutBytes = 0;
+        child.stdout.on('data', (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes <= GIT_MAX_BUFFER)
+                stdout.push(chunk);
+        });
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        let settled = false;
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (signal?.aborted === true) {
+                reject(signal.reason ?? error);
+                return;
+            }
+            reject(new ChangeLedgerError('GIT_COMMAND_FAILED', `git ${args.join(' ')} failed in ${JSON.stringify(cwd)}: ${errorMessage(error)}`, { cause: error }));
+        };
+        child.on('error', fail);
+        child.stdin.on('error', fail);
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            if (code !== 0) {
+                settled = true;
+                const message = Buffer.concat(stderr).toString('utf8').trim();
+                reject(new ChangeLedgerError('GIT_COMMAND_FAILED', `git ${args.join(' ')} failed in ${JSON.stringify(cwd)}: ${message || `exit ${String(code)}`}`));
+                return;
+            }
+            if (stdoutBytes > GIT_MAX_BUFFER) {
+                settled = true;
+                reject(new ChangeLedgerError('GIT_COMMAND_FAILED', `git ${args.join(' ')} output exceeded ${GIT_MAX_BUFFER} bytes`));
+                return;
+            }
+            settled = true;
+            resolvePromise(Buffer.concat(stdout).toString('utf8'));
+        });
+        child.stdin.end(input);
+    });
+}
+/** Run Git and return raw stdout bytes. */
+export async function runGitBuffer(cwd, args, signal, options = {}) {
+    return new Promise((resolvePromise, reject) => {
+        execFile('git', ['-c', 'core.quotepath=false', '-C', cwd, ...args], {
+            encoding: 'buffer',
+            maxBuffer: options.maxBuffer ?? GIT_MAX_BUFFER,
+            windowsHide: true,
+            signal,
+            env: gitEnvironment(options.env),
+        }, (error, stdout, stderr) => {
+            if (error !== null) {
+                if (signal?.aborted === true) {
+                    reject(signal.reason ?? error);
+                    return;
+                }
+                reject(new ChangeLedgerError('GIT_COMMAND_FAILED', `git ${args.join(' ')} failed in ${JSON.stringify(cwd)}: ${stderr.toString('utf8').trim() || errorMessage(error)}`, { cause: error }));
+                return;
+            }
+            resolvePromise(stdout);
+        });
+    });
+}
+function gitEnvironment(extra) {
+    const env = { ...process.env };
+    for (const key of [
+        'GIT_DIR',
+        'GIT_COMMON_DIR',
+        'GIT_WORK_TREE',
+        'GIT_INDEX_FILE',
+        'GIT_OBJECT_DIRECTORY',
+        'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+        'GIT_QUARANTINE_PATH',
+        'GIT_REPLACE_REF_BASE',
+        'GIT_CONFIG_PARAMETERS',
+        'GIT_CONFIG_COUNT',
+    ])
+        delete env[key];
+    for (const key of Object.keys(env)) {
+        if (/^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(key))
+            delete env[key];
+    }
+    return {
+        ...env,
+        ...extra,
+        GIT_OPTIONAL_LOCKS: '0',
+        GIT_TERMINAL_PROMPT: '0',
+    };
+}
 function gitExitCode(error) {
     if (error === null || typeof error !== 'object' || !('code' in error))
         return undefined;
@@ -156,6 +300,135 @@ function stripLineEnding(value) {
 function comparePaths(left, right) {
     return Buffer.from(left).compare(Buffer.from(right));
 }
+function parseWorktreeId(value) {
+    const worktreeId = value.trim();
+    if (!/^[0-9a-f]{32}$/.test(worktreeId)) {
+        throw new ChangeLedgerError('STATE_CORRUPT', 'Git worktree identity is malformed');
+    }
+    return worktreeId;
+}
+async function readGitWorktreeIdentity(cwd, signal) {
+    const root = await discoverRepositoryRoot(cwd, signal);
+    const gitDir = await realpath(resolve(root, stripLineEnding(await runGit(root, ['rev-parse', '--git-dir'], signal))));
+    const commonDir = await realpath(resolve(root, stripLineEnding(await runGit(root, ['rev-parse', '--git-common-dir'], signal))));
+    const worktreeId = await ensureWorktreeId(join(gitDir, 'dsh-turn-rewind'), commonDir, gitDir);
+    return {
+        root,
+        gitDir,
+        commonDir,
+        worktreeId,
+        lockPath: join(commonDir, 'dsh-turn-rewind', 'locks', `${worktreeId}.json`),
+    };
+}
+async function ensureWorktreeId(identityDir, commonDir, gitDir) {
+    const identityPath = join(identityDir, 'worktree-id');
+    const backupPath = join(identityDir, 'worktree-id.backup');
+    const initializedPath = join(identityDir, 'worktree-id.initialized');
+    const localPaths = [identityPath, backupPath, initializedPath];
+    const centralDir = join(commonDir, 'dsh-turn-rewind-worktree-identities');
+    const centralPath = join(centralDir, `${createHash('sha256').update(gitDir).digest('hex')}.id`);
+    await mkdir(identityDir, { recursive: true, mode: 0o700 });
+    await mkdir(centralDir, { recursive: true, mode: 0o700 });
+    const localCopies = await Promise.all(localPaths.map(readIdentityCopy));
+    const centralCopy = await readIdentityCopy(centralPath);
+    const valid = [...localCopies, centralCopy].flatMap(copy => copy.value === undefined ? [] : [copy.value]);
+    if (new Set(valid).size > 1) {
+        throw new ChangeLedgerError('STATE_CORRUPT', 'Git worktree identity copies disagree');
+    }
+    const localValid = localCopies.flatMap(copy => copy.value === undefined ? [] : [copy.value]);
+    const localDurable = localValid[0];
+    const durable = localDurable ?? (gitDir === commonDir ? centralCopy.value : undefined);
+    if (durable !== undefined) {
+        for (const path of [...localPaths, centralPath]) {
+            if (await publishIdentityFile(path, durable, true) !== durable) {
+                throw new ChangeLedgerError('STATE_CORRUPT', `Git worktree identity copy disagrees at ${JSON.stringify(path)}`);
+            }
+        }
+        await syncDirectory(identityDir);
+        await syncDirectory(centralDir);
+        return durable;
+    }
+    if (localCopies.some(copy => copy.malformed) || centralCopy.malformed) {
+        throw new ChangeLedgerError('STATE_CORRUPT', 'Git worktree identity is malformed and no valid durable copy remains');
+    }
+    if (gitDir !== commonDir && centralCopy.value !== undefined) {
+        throw new ChangeLedgerError('STATE_CORRUPT', 'linked Git worktree identity is ambiguous because only a detached central copy remains');
+    }
+    const candidate = randomBytes(16).toString('hex');
+    const chosen = await publishIdentityFile(identityPath, candidate, false);
+    for (const path of [backupPath, initializedPath, centralPath]) {
+        if (await publishIdentityFile(path, chosen, true) !== chosen) {
+            throw new ChangeLedgerError('STATE_CORRUPT', `Git worktree identity copy disagrees at ${JSON.stringify(path)}`);
+        }
+    }
+    await syncDirectory(identityDir);
+    await syncDirectory(centralDir);
+    return chosen;
+}
+async function readIdentityCopy(path) {
+    try {
+        return { value: parseWorktreeId(await readFile(path, 'utf8')), malformed: false };
+    }
+    catch (error) {
+        if (isNodeError(error, 'ENOENT'))
+            return { malformed: false };
+        if (error instanceof ChangeLedgerError && error.code === 'STATE_CORRUPT')
+            return { malformed: true };
+        throw error;
+    }
+}
+async function publishIdentityFile(path, value, repairMalformed) {
+    const directory = dirname(path);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = join(directory, `.${randomBytes(16).toString('hex')}.tmp`);
+    try {
+        const handle = await open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(`${value}\n`);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        for (let attempt = 0; attempt < 8; attempt += 1) {
+            try {
+                await link(temporary, path);
+                await syncDirectory(directory);
+                return value;
+            }
+            catch (error) {
+                if (!isNodeError(error, 'EEXIST'))
+                    throw error;
+            }
+            const existing = await readIdentityCopy(path);
+            if (existing.value !== undefined)
+                return existing.value;
+            if (!existing.malformed)
+                continue;
+            if (!repairMalformed) {
+                throw new ChangeLedgerError('STATE_CORRUPT', `Git worktree identity copy is malformed at ${JSON.stringify(path)}`);
+            }
+            try {
+                await unlink(path);
+                await syncDirectory(directory);
+            }
+            catch (error) {
+                if (!isNodeError(error, 'ENOENT'))
+                    throw error;
+            }
+        }
+        throw new ChangeLedgerError('STATE_CORRUPT', `could not repair Git worktree identity copy at ${JSON.stringify(path)}`);
+    }
+    finally {
+        try {
+            await unlink(temporary);
+        }
+        catch (error) {
+            if (!isNodeError(error, 'ENOENT'))
+                throw error;
+        }
+    }
+}
 /** Return the Git metadata directory for diagnostics. */
 export function gitMetadataParent(state) {
     return dirname(state.commonDir);

package/lib/index.js

@@ -1,8 +1,10 @@
 import { ChangeLedgerEngine } from './engine.js';
-import { installRewindHttp, TurnCheckpointCoordinator } from './rewind-host.js';
+import { installManageHttp, installRewindHttp, TurnCheckpointCoordinator } from './rewind-host.js';
+import { installTurnRewindSettings } from './settings.js';
 export * from './engine.js';
 export * from './errors.js';
 export * from './rewind-host.js';
+export * from './settings.js';
 export * from './types.js';
 /** Cordis service exposed as `ctx.changeLedger` for other DSH plugins. */
 export class ChangeLedgerService {
@@ -15,10 +17,12 @@ export class ChangeLedgerService {
         ctx.inject(['agents'], (scope) => { checkpoints.install(scope); });
         ctx.inject(['webServer', 'sessions', 'sessionQuery', 'apiProxy', 'agents'], (scope) => {
             installRewindHttp(scope, this.engine, checkpoints);
+            installManageHttp(scope, this.engine);
         });
+        installTurnRewindSettings(ctx, config, this.engine);
         void this.engine.initialize().then((reconciled) => {
             if (reconciled > 0) {
-                ctx.logger.warn(`[change-ledger] marked ${reconciled} interrupted restore operation(s) for manual recovery`);
+                ctx.logger.warn(`[change-ledger] reconciled ${reconciled} interrupted durable operation(s)`);
             }
             else {
                 ctx.logger.info(`[change-ledger] ready; state=${this.engine.config.storageDir}`);
@@ -67,5 +71,17 @@ export class ChangeLedgerService {
     listRecovery(options) {
         return this.engine.listRecovery(options);
     }
+    /** Inventory every workspace this storage root has persisted state for. */
+    listWorkspaces(options) {
+        return this.engine.listWorkspaces(options);
+    }
+    /** Delete unprotected restore points recorded for one workspace. */
+    purgeWorkspace(options) {
+        return this.engine.purgeWorkspace(options);
+    }
+    /** Swap runtime-tunable configuration; the storage root must stay fixed. */
+    updateConfig(config) {
+        this.engine.updateConfig(config);
+    }
 }
 export default ChangeLedgerService;

package/lib/path-utils.js

@@ -107,6 +107,13 @@ export async function pathExists(path) {
 }
 /** Ensure every existing parent below `root` is a real directory, never a symlink. */
 export async function ensureSafeParents(root, target) {
+    await walkSafeParents(root, target, true);
+}
+/** Validate existing parents without creating missing directories. */
+export async function assertSafeParents(root, target) {
+    await walkSafeParents(root, target, false);
+}
+async function walkSafeParents(root, target, createMissing) {
     if (!isWithin(root, target) || target === root) {
         throw new ChangeLedgerError('UNSAFE_TARGET', `restore target is outside the workspace: ${JSON.stringify(target)}`);
     }
@@ -128,6 +135,8 @@ export async function ensureSafeParents(root, target) {
         catch (error) {
             if (!isNodeError(error, 'ENOENT'))
                 throw error;
+            if (!createMissing)
+                return;
             await mkdir(current, { mode: 0o755 });
         }
     }