@anionex/dsh-turn-rewind 0.1.0

package/lib/git.js

@@ -0,0 +1,155 @@
+import { execFile } from 'node:child_process';
+import { lstat, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { ChangeLedgerError, errorMessage } from './errors.js';
+import { canonicalDirectory, isNodeError, 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';
+    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 gitDir = await realpath(resolve(root, gitDirRaw));
+    const commonDirRaw = stripLineEnding(await git(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 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 paths = [...new Set(splitNul(pathOutput).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 stagedPaths = splitNul(stagedOutput).map(validateRelativePath).sort(comparePaths);
+    const operation = await gitOperation(gitDir);
+    return {
+        state: {
+            root,
+            commonDir,
+            ...(head === undefined ? {} : { head }),
+            ...(branch === undefined ? {} : { branch }),
+            ...(operation === undefined ? {} : { operation }),
+            stagedPaths,
+        },
+        paths,
+    };
+}
+/** 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 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;
+}
+/** Return true when two repository fences refer to the same checkout state. */
+export function sameRepositoryFence(left, right) {
+    return left.root === right.root
+        && left.commonDir === right.commonDir
+        && left.head === right.head
+        && left.branch === right.branch
+        && left.operation === right.operation;
+}
+async function git(cwd, args, signal) {
+    return new Promise((resolvePromise, reject) => {
+        execFile('git', ['-c', 'core.quotepath=false', '-C', cwd, ...args], {
+            encoding: 'utf8',
+            maxBuffer: GIT_MAX_BUFFER,
+            windowsHide: true,
+            signal,
+            env: {
+                ...process.env,
+                GIT_OPTIONAL_LOCKS: '0',
+                GIT_TERMINAL_PROMPT: '0',
+            },
+        }, (error, stdout, stderr) => {
+            if (error !== null) {
+                reject(new ChangeLedgerError('GIT_COMMAND_FAILED', `git ${args.join(' ')} failed in ${JSON.stringify(cwd)}: ${stderr.trim() || errorMessage(error)}`, { cause: error }));
+                return;
+            }
+            resolvePromise(stdout);
+        });
+    });
+}
+async function gitOptional(cwd, args, signal) {
+    try {
+        return await git(cwd, args, signal);
+    }
+    catch (error) {
+        if (error instanceof ChangeLedgerError && error.code === 'GIT_COMMAND_FAILED' && gitExitCode(error.cause) === 1)
+            return undefined;
+        throw error;
+    }
+}
+function gitExitCode(error) {
+    if (error === null || typeof error !== 'object' || !('code' in error))
+        return undefined;
+    const code = error.code;
+    return typeof code === 'string' || typeof code === 'number' ? code : undefined;
+}
+function splitNul(value) {
+    if (value === '')
+        return [];
+    const parts = value.split('\0');
+    if (parts.at(-1) === '')
+        parts.pop();
+    return parts;
+}
+function parseSubmodules(value) {
+    const paths = [];
+    for (const record of splitNul(value)) {
+        const match = /^(\d{6}) [0-9a-f]+ \d+\t([\s\S]+)$/.exec(record);
+        if (match === null) {
+            throw new ChangeLedgerError('GIT_INDEX_PARSE_FAILED', `cannot parse git index record: ${JSON.stringify(record.slice(0, 200))}`);
+        }
+        if (match[1] === '160000')
+            paths.push(validateRelativePath(match[2] ?? ''));
+    }
+    return paths.sort(comparePaths);
+}
+async function gitOperation(gitDir) {
+    const markers = [
+        ['rebase-merge', 'rebase'],
+        ['rebase-apply', 'rebase'],
+        ['MERGE_HEAD', 'merge'],
+        ['CHERRY_PICK_HEAD', 'cherry-pick'],
+        ['REVERT_HEAD', 'revert'],
+        ['BISECT_LOG', 'bisect'],
+    ];
+    for (const [marker, operation] of markers) {
+        try {
+            await lstat(resolve(gitDir, marker));
+            return operation;
+        }
+        catch (error) {
+            if (!isNodeError(error, 'ENOENT'))
+                throw error;
+        }
+    }
+    return undefined;
+}
+function trimOptional(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === '' ? undefined : trimmed;
+}
+function stripLineEnding(value) {
+    if (value.endsWith('\r\n'))
+        return value.slice(0, -2);
+    if (value.endsWith('\n'))
+        return value.slice(0, -1);
+    return value;
+}
+function comparePaths(left, right) {
+    return Buffer.from(left).compare(Buffer.from(right));
+}
+/** Return the Git metadata directory for diagnostics. */
+export function gitMetadataParent(state) {
+    return dirname(state.commonDir);
+}

package/lib/index.js

@@ -0,0 +1,71 @@
+import { ChangeLedgerEngine } from './engine.js';
+import { installRewindHttp, TurnCheckpointCoordinator } from './rewind-host.js';
+export * from './engine.js';
+export * from './errors.js';
+export * from './rewind-host.js';
+export * from './types.js';
+/** Cordis service exposed as `ctx.changeLedger` for other DSH plugins. */
+export class ChangeLedgerService {
+    engine;
+    /** Register the service and startup reconciliation. */
+    constructor(ctx, config = {}) {
+        ctx.provide('changeLedger', this);
+        this.engine = new ChangeLedgerEngine(config);
+        const checkpoints = new TurnCheckpointCoordinator(this.engine);
+        ctx.inject(['agents'], (scope) => { checkpoints.install(scope); });
+        ctx.inject(['webServer', 'sessions', 'sessionQuery', 'apiProxy', 'agents'], (scope) => {
+            installRewindHttp(scope, this.engine, checkpoints);
+        });
+        void this.engine.initialize().then((reconciled) => {
+            if (reconciled > 0) {
+                ctx.logger.warn(`[change-ledger] marked ${reconciled} interrupted restore operation(s) for manual recovery`);
+            }
+            else {
+                ctx.logger.info(`[change-ledger] ready; state=${this.engine.config.storageDir}`);
+            }
+        }).catch((error) => {
+            ctx.logger.error(`[change-ledger] startup failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    /** Wait for startup reconciliation. */
+    initialize() {
+        return this.engine.initialize();
+    }
+    /** Create a user restore point. */
+    create(options) {
+        return this.engine.create(options);
+    }
+    /** Capture project files before one turn enters its first Agent step. */
+    createTurnCheckpoint(options) {
+        return this.engine.createTurnCheckpoint(options);
+    }
+    /** Find the prompt-anchored checkpoint for one session turn. */
+    findTurnCheckpoint(options) {
+        return this.engine.findTurnCheckpoint(options);
+    }
+    /** List restore points. */
+    list(options) {
+        return this.engine.list(options);
+    }
+    /** Compare a restore point with the current worktree. */
+    inspect(options) {
+        return this.engine.inspect(options);
+    }
+    /** Create an expiring restore plan. */
+    planRestore(options) {
+        return this.engine.planRestore(options);
+    }
+    /** Apply an exact restore plan after approval. */
+    applyRestore(options) {
+        return this.engine.applyRestore(options);
+    }
+    /** Delete one restore point and collect unused blobs. */
+    delete(options) {
+        return this.engine.delete(options);
+    }
+    /** List interrupted restore operations and their rescue points. */
+    listRecovery(options) {
+        return this.engine.listRecovery(options);
+    }
+}
+export default ChangeLedgerService;

package/lib/path-utils.js

@@ -0,0 +1,262 @@
+import { chmod, lstat, mkdir, open, readFile, realpath, rename, rm, rmdir, stat, symlink, unlink } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ChangeLedgerError } from './errors.js';
+/** Return whether `candidate` is equal to or below `root`. */
+export function isWithin(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+/** Validate and normalize one repository-relative path without filesystem access. */
+export function validateRelativePath(path) {
+    if (path === '' || path.includes('\0')) {
+        throw new ChangeLedgerError('INVALID_PATH', 'snapshot paths must be non-empty and contain no NUL bytes');
+    }
+    if (path.startsWith('/') || /^[A-Za-z]:[\\/]/.test(path)) {
+        throw new ChangeLedgerError('INVALID_PATH', `path escapes the workspace: ${JSON.stringify(path)}`);
+    }
+    if (sep === '\\' && path.includes('\\')) {
+        throw new ChangeLedgerError('INVALID_PATH', `Git paths must use forward slashes: ${JSON.stringify(path)}`);
+    }
+    const segments = path.split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw new ChangeLedgerError('INVALID_PATH', `path is not canonical: ${JSON.stringify(path)}`);
+    }
+    return path;
+}
+/** Resolve a validated relative path below `root`. */
+export function resolveWorkspacePath(root, path) {
+    const normalized = validateRelativePath(path);
+    const target = resolve(root, ...normalized.split('/'));
+    if (!isWithin(root, target)) {
+        throw new ChangeLedgerError('INVALID_PATH', `path escapes the workspace: ${JSON.stringify(path)}`);
+    }
+    return target;
+}
+/** Expand a leading `~/` against the provided home directory. */
+export function expandHome(path, home) {
+    if (path === '~')
+        return home;
+    if (path.startsWith(`~${sep}`) || path.startsWith('~/'))
+        return join(home, path.slice(2));
+    return path;
+}
+/** Canonicalize an existing directory and reject non-directories. */
+export async function canonicalDirectory(path) {
+    let canonical;
+    try {
+        canonical = await realpath(path);
+    }
+    catch (error) {
+        throw new ChangeLedgerError('WORKSPACE_NOT_FOUND', `cannot resolve directory ${JSON.stringify(path)}`, { cause: error });
+    }
+    const info = await stat(canonical);
+    if (!info.isDirectory()) {
+        throw new ChangeLedgerError('WORKSPACE_NOT_DIRECTORY', `${JSON.stringify(path)} is not a directory`);
+    }
+    return canonical;
+}
+/** Atomically replace one JSON file with owner-only permissions. */
+export async function writeJsonAtomic(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = join(dirname(path), `.${randomUUID()}.tmp`);
+    const body = `${JSON.stringify(value, null, 2)}\n`;
+    try {
+        const handle = await open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(body, 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await renameReplacing(temporary, path);
+        await syncDirectory(dirname(path));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Read and parse one JSON file. */
+export async function readJson(path) {
+    let body;
+    try {
+        body = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        throw new ChangeLedgerError('STATE_READ_FAILED', `cannot read ${JSON.stringify(path)}`, { cause: error });
+    }
+    try {
+        return JSON.parse(body);
+    }
+    catch (error) {
+        throw new ChangeLedgerError('STATE_CORRUPT', `invalid JSON in ${JSON.stringify(path)}`, { cause: error });
+    }
+}
+/** Return whether a filesystem path exists without following its final symlink. */
+export async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error, 'ENOENT'))
+            return false;
+        throw error;
+    }
+}
+/** Ensure every existing parent below `root` is a real directory, never a symlink. */
+export async function ensureSafeParents(root, target) {
+    if (!isWithin(root, target) || target === root) {
+        throw new ChangeLedgerError('UNSAFE_TARGET', `restore target is outside the workspace: ${JSON.stringify(target)}`);
+    }
+    const rel = relative(root, dirname(target));
+    let current = root;
+    if (rel === '')
+        return;
+    for (const segment of rel.split(sep)) {
+        current = join(current, segment);
+        try {
+            const info = await lstat(current);
+            if (info.isSymbolicLink()) {
+                throw new ChangeLedgerError('SYMLINK_PARENT', `restore path traverses symlink parent ${JSON.stringify(current)}`);
+            }
+            if (!info.isDirectory()) {
+                throw new ChangeLedgerError('PARENT_NOT_DIRECTORY', `restore parent is not a directory: ${JSON.stringify(current)}`);
+            }
+        }
+        catch (error) {
+            if (!isNodeError(error, 'ENOENT'))
+                throw error;
+            await mkdir(current, { mode: 0o755 });
+        }
+    }
+}
+/** Replace a path with a regular file using a sibling temporary file. */
+export async function replaceRegularFile(path, content, mode) {
+    const temporary = join(dirname(path), `.${randomUUID()}.change-ledger.tmp`);
+    try {
+        const handle = await open(temporary, 'wx', mode & 0o777);
+        try {
+            await handle.writeFile(content);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await chmod(temporary, mode & 0o777);
+        await renameReplacing(temporary, path);
+        await syncDirectory(dirname(path));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Replace a path with a symbolic link using a sibling temporary name. */
+export async function replaceSymbolicLink(path, target) {
+    const temporary = join(dirname(path), `.${randomUUID()}.change-ledger.tmp`);
+    try {
+        await symlink(target, temporary);
+        await renameReplacing(temporary, path);
+        await syncDirectory(dirname(path));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Remove one file/symlink or one empty directory, never a non-empty tree. */
+export async function removeRestoreTarget(path) {
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        if (isNodeError(error, 'ENOENT'))
+            return;
+        throw error;
+    }
+    if (info.isDirectory() && !info.isSymbolicLink()) {
+        try {
+            await rmdir(path);
+        }
+        catch (error) {
+            if (isNodeError(error, 'ENOTEMPTY') || isNodeError(error, 'EEXIST')) {
+                throw new ChangeLedgerError('DIRECTORY_NOT_EMPTY', `refusing to remove non-empty directory ${JSON.stringify(path)}`);
+            }
+            throw error;
+        }
+        return;
+    }
+    await unlink(path);
+}
+/** Best-effort removal of empty parent directories up to but excluding `root`. */
+export async function pruneEmptyParents(root, start) {
+    let current = dirname(start);
+    while (current !== root && isWithin(root, current)) {
+        try {
+            await rmdir(current);
+        }
+        catch (error) {
+            if (isNodeError(error, 'ENOENT')) {
+                current = dirname(current);
+                continue;
+            }
+            if (isNodeError(error, 'ENOTEMPTY') || isNodeError(error, 'EEXIST'))
+                return;
+            throw error;
+        }
+        current = dirname(current);
+    }
+}
+/** Test whether a process id currently exists. */
+export function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return isNodeError(error, 'EPERM');
+    }
+}
+/** Type guard for Node.js errors with a selected `code`. */
+export function isNodeError(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+async function renameReplacing(source, destination) {
+    try {
+        await rename(source, destination);
+        return;
+    }
+    catch (error) {
+        if (!isNodeError(error, 'EEXIST') && !isNodeError(error, 'EPERM') && !isNodeError(error, 'ENOTEMPTY')) {
+            throw error;
+        }
+    }
+    await removeRestoreTarget(destination);
+    await rename(source, destination);
+}
+/** Create one owner-only file exclusively and return its handle. */
+export async function openExclusive(path) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    return open(path, 'wx', 0o600);
+}
+/** Flush directory-entry changes where the platform supports directory fsync. */
+export async function syncDirectory(path) {
+    let handle;
+    try {
+        handle = await open(path, 'r');
+        await handle.sync();
+    }
+    catch (error) {
+        if (isNodeError(error, 'EINVAL')
+            || isNodeError(error, 'ENOTSUP')
+            || isNodeError(error, 'EISDIR')
+            || isNodeError(error, 'EPERM')
+            || isNodeError(error, 'EACCES'))
+            return;
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}