@anionex/dsh-turn-rewind 0.1.0

package/lib/store.js

@@ -0,0 +1,391 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { link, mkdir, open, readFile, readdir, rmdir, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ChangeLedgerError, errorMessage } from './errors.js';
+import { isNodeError, openExclusive, processExists, readJson, syncDirectory, writeJsonAtomic } from './path-utils.js';
+import { parseManifest, parseOperation, validateBlobHash, validateOperationId, validateRestorePointId } from './validate.js';
+/** Durable content-addressed storage and per-workspace locking. */
+export class LedgerStore {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Create the state root and reconcile crash-interrupted operations. */
+    async initialize() {
+        await mkdir(join(this.config.storageDir, 'workspaces'), { recursive: true, mode: 0o700 });
+        let reconciled = 0;
+        for (const workspaceKey of await safeDirectoryNames(join(this.config.storageDir, 'workspaces'))) {
+            const workspaceDir = join(this.config.storageDir, 'workspaces', workspaceKey);
+            if (await this.workspaceAppearsActive(workspaceDir))
+                continue;
+            const operationDir = join(workspaceDir, 'operations');
+            for (const filename of await safeJsonNames(operationDir)) {
+                const path = join(operationDir, filename);
+                const operation = parseOperation(await readJson(path));
+                if (filename !== `${operation.id}.json`) {
+                    throw new ChangeLedgerError('STATE_CORRUPT', `operation ${filename} does not match its persisted id ${operation.id}`);
+                }
+                if (this.workspaceDir(operation.workspace) !== workspaceDir) {
+                    throw new ChangeLedgerError('STATE_CORRUPT', `operation ${filename} is stored under the wrong workspace key`);
+                }
+                if (operation.state !== 'running' && operation.state !== 'rollback-running')
+                    continue;
+                await this.writeOperation({
+                    ...operation,
+                    state: 'interrupted',
+                    error: operation.error ?? 'DSH stopped before the restore operation reached a terminal state',
+                });
+                reconciled += 1;
+            }
+        }
+        return reconciled;
+    }
+    /** Acquire the exclusive lock for one canonical workspace. */
+    async acquire(workspace) {
+        const lockPath = join(this.workspaceDir(workspace), 'lock.json');
+        await mkdir(this.workspaceDir(workspace), { recursive: true, mode: 0o700 });
+        const nonce = randomUUID();
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            let handle;
+            try {
+                handle = await openExclusive(lockPath);
+            }
+            catch (error) {
+                if (!isNodeError(error, 'EEXIST'))
+                    throw error;
+                const reclaimed = await this.reclaimStaleLock(lockPath);
+                if (reclaimed)
+                    continue;
+                throw new ChangeLedgerError('WORKSPACE_LOCKED', `another change-ledger operation owns ${JSON.stringify(workspace)}`);
+            }
+            const record = { pid: process.pid, createdAt: Date.now(), nonce };
+            try {
+                await handle.writeFile(`${JSON.stringify(record)}\n`, 'utf8');
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await syncDirectory(this.workspaceDir(workspace));
+            let released = false;
+            return async () => {
+                if (released)
+                    return;
+                released = true;
+                try {
+                    const current = parseLock(await readJson(lockPath));
+                    if (current.nonce !== nonce)
+                        return;
+                    await unlink(lockPath);
+                    await syncDirectory(this.workspaceDir(workspace));
+                }
+                catch (error) {
+                    if (!isNodeError(error, 'ENOENT') && !isMissingStateRead(error))
+                        throw error;
+                }
+            };
+        }
+        throw new ChangeLedgerError('WORKSPACE_LOCKED', `could not acquire change-ledger lock for ${JSON.stringify(workspace)}`);
+    }
+    /** Persist a blob if it is not already present, and verify existing content. */
+    async putBlob(workspace, hash, content) {
+        validateBlobHash(hash);
+        const contentHash = createHash('sha256').update(content).digest('hex');
+        if (contentHash !== hash) {
+            throw new ChangeLedgerError('BLOB_HASH_MISMATCH', `refusing to store content whose SHA-256 does not match ${hash}`);
+        }
+        const path = this.blobPath(workspace, hash);
+        const directory = join(this.workspaceDir(workspace), 'blobs', hash.slice(0, 2));
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const temporary = join(directory, `.${randomUUID()}.tmp`);
+        try {
+            const handle = await open(temporary, 'wx', 0o600);
+            try {
+                await handle.writeFile(content);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            try {
+                await link(temporary, path);
+                await syncDirectory(directory);
+                return;
+            }
+            catch (error) {
+                if (!isNodeError(error, 'EEXIST'))
+                    throw error;
+            }
+        }
+        finally {
+            try {
+                await unlink(temporary);
+            }
+            catch (error) {
+                if (!isNodeError(error, 'ENOENT'))
+                    throw error;
+            }
+        }
+        const existing = await readFile(path);
+        const existingHash = createHash('sha256').update(existing).digest('hex');
+        if (existingHash !== hash || !existing.equals(content)) {
+            throw new ChangeLedgerError('BLOB_COLLISION', `stored blob ${hash} does not match its content hash`);
+        }
+    }
+    /** Read and verify one content-addressed blob. */
+    async readBlob(workspace, hash) {
+        validateBlobHash(hash);
+        const content = await readFile(this.blobPath(workspace, hash));
+        const actual = createHash('sha256').update(content).digest('hex');
+        if (actual !== hash)
+            throw new ChangeLedgerError('BLOB_CORRUPT', `blob ${hash} failed SHA-256 verification`);
+        return content;
+    }
+    /** Write one restore-point manifest atomically. */
+    async writeManifest(manifest) {
+        parseManifest(manifest);
+        await writeJsonAtomic(this.manifestPath(manifest.workspace, manifest.id), manifest);
+    }
+    /** Load and validate one restore-point manifest. */
+    async readManifest(workspace, id) {
+        validateRestorePointId(id);
+        let raw;
+        try {
+            raw = await readJson(this.manifestPath(workspace, id));
+        }
+        catch (error) {
+            if (isMissingStateRead(error)) {
+                throw new ChangeLedgerError('RESTORE_POINT_NOT_FOUND', `restore point ${id} does not exist`, { cause: error });
+            }
+            throw error;
+        }
+        const manifest = parseManifest(raw);
+        if (manifest.id !== id) {
+            throw new ChangeLedgerError('STATE_CORRUPT', `restore point file ${id}.json contains id ${manifest.id}`);
+        }
+        if (manifest.workspace !== workspace) {
+            throw new ChangeLedgerError('STATE_CORRUPT', `restore point ${id} belongs to a different workspace`);
+        }
+        return manifest;
+    }
+    /** List all validated restore points for one workspace, newest first. */
+    async listManifests(workspace) {
+        const manifests = [];
+        for (const filename of await safeJsonNames(join(this.workspaceDir(workspace), 'manifests'))) {
+            const manifest = parseManifest(await readJson(join(this.workspaceDir(workspace), 'manifests', filename)));
+            if (filename !== `${manifest.id}.json`) {
+                throw new ChangeLedgerError('STATE_CORRUPT', `manifest ${filename} does not match its persisted id ${manifest.id}`);
+            }
+            if (manifest.workspace !== workspace) {
+                throw new ChangeLedgerError('STATE_CORRUPT', `manifest ${filename} belongs to a different workspace`);
+            }
+            manifests.push(manifest);
+        }
+        return manifests.sort((left, right) => right.createdAt - left.createdAt || right.id.localeCompare(left.id));
+    }
+    /** Delete one restore-point manifest. Blobs remain until garbage collection succeeds. */
+    async deleteManifest(workspace, id) {
+        validateRestorePointId(id);
+        const directory = join(this.workspaceDir(workspace), 'manifests');
+        try {
+            await unlink(this.manifestPath(workspace, id));
+        }
+        catch (error) {
+            if (isNodeError(error, 'ENOENT')) {
+                throw new ChangeLedgerError('RESTORE_POINT_NOT_FOUND', `restore point ${id} does not exist`);
+            }
+            throw error;
+        }
+        await syncDirectory(directory);
+    }
+    /** Persist one restore-operation journal. */
+    async writeOperation(operation) {
+        parseOperation(operation);
+        await writeJsonAtomic(this.operationPath(operation.workspace, operation.id), operation);
+    }
+    /** List validated restore operations for one workspace. */
+    async listOperations(workspace) {
+        const operations = [];
+        for (const filename of await safeJsonNames(join(this.workspaceDir(workspace), 'operations'))) {
+            const operation = parseOperation(await readJson(join(this.workspaceDir(workspace), 'operations', filename)));
+            if (filename !== `${operation.id}.json`) {
+                throw new ChangeLedgerError('STATE_CORRUPT', `operation ${filename} does not match its persisted id ${operation.id}`);
+            }
+            if (operation.workspace !== workspace) {
+                throw new ChangeLedgerError('STATE_CORRUPT', `operation ${filename} belongs to a different workspace`);
+            }
+            operations.push(operation);
+        }
+        return operations.sort((left, right) => right.startedAt - left.startedAt || right.id.localeCompare(left.id));
+    }
+    /** Return whether an incomplete operation still references a restore point. */
+    async isReferencedByRecovery(workspace, restorePointId) {
+        return (await this.listOperations(workspace)).some((operation) => (operation.state === 'interrupted' || operation.state === 'recovery-required')
+            && (operation.restorePointId === restorePointId || operation.rescuePointId === restorePointId));
+    }
+    /** Delete blobs not referenced by any remaining manifest. */
+    async collectGarbage(workspace, additionalReferenced = []) {
+        const referenced = new Set(additionalReferenced);
+        for (const hash of referenced)
+            validateBlobHash(hash);
+        for (const manifest of await this.listManifests(workspace)) {
+            for (const entry of Object.values(manifest.entries)) {
+                if (entry.kind === 'file')
+                    referenced.add(entry.blob);
+            }
+        }
+        let deletedBlobs = 0;
+        let retainedBlobs = 0;
+        const blobsRoot = join(this.workspaceDir(workspace), 'blobs');
+        for (const prefix of await safeDirectoryNames(blobsRoot)) {
+            const prefixPath = join(blobsRoot, prefix);
+            for (const filename of await safeFileNames(prefixPath)) {
+                if (filename.startsWith('.') && filename.endsWith('.tmp')) {
+                    await unlink(join(prefixPath, filename));
+                    deletedBlobs += 1;
+                    continue;
+                }
+                validateBlobHash(filename);
+                if (filename.slice(0, 2) !== prefix) {
+                    throw new ChangeLedgerError('STATE_CORRUPT', `blob ${filename} is stored under the wrong prefix directory ${prefix}`);
+                }
+                if (referenced.has(filename)) {
+                    retainedBlobs += 1;
+                    continue;
+                }
+                await unlink(join(prefixPath, filename));
+                deletedBlobs += 1;
+            }
+            try {
+                await rmdir(prefixPath);
+            }
+            catch (error) {
+                if (!isNodeError(error, 'ENOTEMPTY') && !isNodeError(error, 'EEXIST') && !isNodeError(error, 'ENOENT'))
+                    throw error;
+            }
+        }
+        return { deletedBlobs, retainedBlobs };
+    }
+    workspaceDir(workspace) {
+        const key = createHash('sha256').update(workspace).digest('hex');
+        return join(this.config.storageDir, 'workspaces', key);
+    }
+    manifestPath(workspace, id) {
+        return join(this.workspaceDir(workspace), 'manifests', `${validateRestorePointId(id)}.json`);
+    }
+    operationPath(workspace, id) {
+        return join(this.workspaceDir(workspace), 'operations', `${validateOperationId(id)}.json`);
+    }
+    blobPath(workspace, hash) {
+        validateBlobHash(hash);
+        return join(this.workspaceDir(workspace), 'blobs', hash.slice(0, 2), hash);
+    }
+    async reclaimStaleLock(lockPath) {
+        let lock;
+        try {
+            lock = parseLock(await readJson(lockPath));
+        }
+        catch (error) {
+            let age = 0;
+            try {
+                age = Date.now() - (await stat(lockPath)).mtimeMs;
+            }
+            catch (statError) {
+                if (isNodeError(statError, 'ENOENT'))
+                    return true;
+                throw statError;
+            }
+            if (age < this.config.staleLockMs) {
+                throw new ChangeLedgerError('WORKSPACE_LOCK_CORRUPT', `active lock is unreadable: ${errorMessage(error)}`);
+            }
+            await unlink(lockPath);
+            return true;
+        }
+        if (processExists(lock.pid))
+            return false;
+        if (Date.now() - lock.createdAt < this.config.staleLockMs)
+            return false;
+        try {
+            const current = parseLock(await readJson(lockPath));
+            if (current.nonce !== lock.nonce)
+                return false;
+            await unlink(lockPath);
+            return true;
+        }
+        catch (error) {
+            if (isNodeError(error, 'ENOENT'))
+                return true;
+            throw error;
+        }
+    }
+    async workspaceAppearsActive(workspaceDir) {
+        const lockPath = join(workspaceDir, 'lock.json');
+        try {
+            const lock = parseLock(await readJson(lockPath));
+            if (processExists(lock.pid))
+                return true;
+            return Date.now() - lock.createdAt < this.config.staleLockMs;
+        }
+        catch (error) {
+            if (error instanceof ChangeLedgerError && error.code === 'STATE_READ_FAILED' && isMissingCause(error.cause))
+                return false;
+            if (isNodeError(error, 'ENOENT'))
+                return false;
+            try {
+                return Date.now() - (await stat(lockPath)).mtimeMs < this.config.staleLockMs;
+            }
+            catch (statError) {
+                if (isNodeError(statError, 'ENOENT'))
+                    return false;
+                throw statError;
+            }
+        }
+    }
+}
+function parseLock(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ChangeLedgerError('WORKSPACE_LOCK_CORRUPT', 'workspace lock must be an object');
+    }
+    const record = value;
+    if (!Number.isSafeInteger(record.pid) || record.pid <= 0) {
+        throw new ChangeLedgerError('WORKSPACE_LOCK_CORRUPT', 'workspace lock pid is invalid');
+    }
+    if (!Number.isSafeInteger(record.createdAt) || record.createdAt < 0) {
+        throw new ChangeLedgerError('WORKSPACE_LOCK_CORRUPT', 'workspace lock createdAt is invalid');
+    }
+    if (typeof record.nonce !== 'string' || record.nonce === '') {
+        throw new ChangeLedgerError('WORKSPACE_LOCK_CORRUPT', 'workspace lock nonce is invalid');
+    }
+    return { pid: record.pid, createdAt: record.createdAt, nonce: record.nonce };
+}
+async function safeJsonNames(path) {
+    return (await safeFileNames(path)).filter((name) => name.endsWith('.json')).sort();
+}
+async function safeDirectoryNames(path) {
+    try {
+        const entries = await readdir(path, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    }
+    catch (error) {
+        if (isNodeError(error, 'ENOENT'))
+            return [];
+        throw error;
+    }
+}
+async function safeFileNames(path) {
+    try {
+        const entries = await readdir(path, { withFileTypes: true });
+        return entries.filter((entry) => entry.isFile()).map((entry) => entry.name).sort();
+    }
+    catch (error) {
+        if (isNodeError(error, 'ENOENT'))
+            return [];
+        throw error;
+    }
+}
+function isMissingCause(error) {
+    return error instanceof Error && 'cause' in error && isNodeError(error.cause, 'ENOENT');
+}
+function isMissingStateRead(error) {
+    return error instanceof ChangeLedgerError && error.code === 'STATE_READ_FAILED' && isMissingCause(error);
+}

package/lib/types/client/index.d.ts

@@ -0,0 +1,81 @@
+import { type ReactNode } from 'react';
+interface ConversationNodeLike {
+    readonly kind: string;
+    readonly seq: number;
+    readonly content?: readonly {
+        readonly type: string;
+        readonly text?: string;
+    }[];
+}
+interface ConversationChatNodeLike {
+    readonly key: string;
+    readonly kind: string;
+    readonly data: ConversationNodeLike;
+}
+interface ConversationSnapshotLike {
+    readonly nodes: readonly ConversationNodeLike[];
+    readonly chat?: {
+        readonly nodes: {
+            values(): readonly ConversationChatNodeLike[];
+        };
+    };
+}
+type RewindNodeLike = ConversationNodeLike | ConversationChatNodeLike;
+interface RewindMatch {
+    readonly messageSeq: number;
+    readonly promptText: string;
+}
+interface RewindMessageActionProps {
+    readonly matched: RewindMatch;
+    readonly sessionId: string;
+    readonly openRestoredSession: (sessionId: string, promptText: string) => Promise<void>;
+}
+interface RewindPortalBridgeProps {
+    readonly sessionId: string;
+    readonly openRestoredSession: (sessionId: string, promptText: string) => Promise<void>;
+    readonly useSession: <T>(selector: (snapshot: ConversationSnapshotLike) => T) => T;
+}
+interface SlotsLike {
+    inject(name: string, install: () => unknown): void;
+    register(entry: {
+        readonly name: string;
+        readonly id: string;
+        readonly order: number;
+        readonly inject: () => {
+            readonly openRestoredSession: (sessionId: string, promptText: string) => Promise<void>;
+        };
+    }, component: (props: RewindPortalBridgeProps) => ReactNode): () => void;
+}
+interface ClientContextLike {
+    readonly slots: SlotsLike;
+    readonly sessions: {
+        open(sessionId: string): void;
+        scope(sessionId: string): unknown | undefined;
+    };
+    readonly conversation: {
+        readonly input: {
+            for(scope: unknown): {
+                setDraft(text: string): void;
+            };
+        };
+    };
+    effect(setup: () => (() => void), label?: string): unknown;
+}
+type ChangeKind = 'added' | 'deleted' | 'modified' | 'mode-changed' | 'type-changed';
+/** Return the rewind anchor and editable text owned by one direct user message. */
+export declare function selectRewindMessage(node: ConversationNodeLike): RewindMatch | null;
+/** Browser plugin entry: bridge every direct user-message action row to the rewind UI. */
+export declare const inject: string[];
+export declare function apply(ctx: ClientContextLike): void;
+/** Session-scoped bridge that portals rewind controls into direct user-message action rows. */
+export declare function RewindMessagePortals({ sessionId, openRestoredSession, useSession }: RewindPortalBridgeProps): ReactNode;
+/** User-message action and its review-first file/conversation restore dialog. */
+export declare function RewindMessageAction({ matched, sessionId, openRestoredSession }: RewindMessageActionProps): ReactNode;
+/** Resolve one conversation node to its DOM row key and rewind match. */
+export declare function selectRewindMessageTarget(value: RewindNodeLike): {
+    readonly matched: RewindMatch;
+    readonly rowKey: string;
+} | null;
+/** Describe the user-visible result of restoring one changed file. */
+export declare function fileRecoveryLabel(kind: ChangeKind): string;
+export {};

package/lib/types/engine.d.ts

@@ -0,0 +1,90 @@
+import { LedgerStore } from './store.js';
+import { type ChangeLedgerConfig, type RecoverySummary, type ResolvedChangeLedgerConfig, type RestorePlan, type RestorePointInspection, type RestorePointManifest, type RestorePointSummary, type RestoreResult } from './types.js';
+/** Persistent workspace change-set engine, independent of the DSH tool adapter. */
+export declare class ChangeLedgerEngine {
+    readonly config: ResolvedChangeLedgerConfig;
+    readonly store: LedgerStore;
+    private readonly plans;
+    private readonly activePlans;
+    private readonly ready;
+    /** Build an engine and start crash-journal reconciliation. */
+    constructor(config?: ChangeLedgerConfig);
+    /** Wait for startup reconciliation and return the number of interrupted journals found. */
+    initialize(): Promise<number>;
+    /** Create a durable restore point for the current Git worktree. */
+    create(options: {
+        readonly cwd: string;
+        readonly sessionId?: string;
+        readonly label?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<RestorePointSummary>;
+    /** Capture project files before one DSH turn begins its first step. */
+    createTurnCheckpoint(options: {
+        readonly cwd: string;
+        readonly sessionId: string;
+        readonly turn: number;
+        readonly turnStartSeq: number;
+        readonly signal?: AbortSignal;
+    }): Promise<RestorePointSummary>;
+    /** Find the prompt-anchored checkpoint captured before one session turn. */
+    findTurnCheckpoint(options: {
+        readonly cwd: string;
+        readonly sessionId: string;
+        readonly turn: number;
+        readonly signal?: AbortSignal;
+    }): Promise<RestorePointSummary | undefined>;
+    /** List restore points for the current worktree. */
+    list(options: {
+        readonly cwd: string;
+        readonly includeRescue?: boolean;
+        readonly includeTurnCheckpoints?: boolean;
+        readonly signal?: AbortSignal;
+    }): Promise<RestorePointSummary[]>;
+    /** Compare one restore point with the current worktree. */
+    inspect(options: {
+        readonly cwd: string;
+        readonly restorePointId: string;
+        readonly signal?: AbortSignal;
+    }): Promise<RestorePointInspection>;
+    /** Produce an expiring, exact confirmation plan for a restore. */
+    planRestore(options: {
+        readonly cwd: string;
+        readonly restorePointId: string;
+        readonly sessionId?: string;
+        readonly paths?: readonly string[];
+        readonly allowHeadChange?: boolean;
+        readonly expectedCurrentTreeHash?: string;
+        readonly expectedRepository?: RestorePointManifest['repository'];
+        readonly signal?: AbortSignal;
+    }): Promise<RestorePlan>;
+    /** Apply one approved restore plan, creating a durable rescue point first. */
+    applyRestore(options: {
+        readonly planId: string;
+        readonly confirmation: string;
+        readonly sessionId?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<RestoreResult>;
+    /** Delete one restore point and collect unreferenced blobs. */
+    delete(options: {
+        readonly cwd: string;
+        readonly restorePointId: string;
+        readonly confirmation: string;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly restorePointId: string;
+        readonly deletedBlobs: number;
+        readonly retainedBlobs: number;
+    }>;
+    /** List restore operations that were interrupted or require manual recovery. */
+    listRecovery(options: {
+        readonly cwd: string;
+        readonly signal?: AbortSignal;
+    }): Promise<RecoverySummary[]>;
+    private createLocked;
+    private restorePaths;
+    private verifyPaths;
+    private assertStorageSeparated;
+    private expirePlans;
+}
+/** Resolve and validate every deployment-varying configuration value. */
+export declare function resolveConfig(config: ChangeLedgerConfig): ResolvedChangeLedgerConfig;

package/lib/types/errors.d.ts

@@ -0,0 +1,15 @@
+/** Stable error carrying a machine-readable change-ledger code. */
+export declare class ChangeLedgerError extends Error {
+    readonly code: string;
+    readonly name = "ChangeLedgerError";
+    /**
+     * @param code - Stable error category.
+     * @param message - Human-readable diagnostic.
+     * @param cause - Optional lower-level failure.
+     */
+    constructor(code: string, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+/** Convert an unknown thrown value into one bounded diagnostic line. */
+export declare function errorMessage(error: unknown): string;

package/lib/types/git.d.ts

@@ -0,0 +1,14 @@
+import type { RepositoryState } from './types.js';
+/** Repository discovery result plus the eligible path inventory. */
+export interface RepositorySnapshotSource {
+    readonly state: RepositoryState;
+    readonly paths: readonly string[];
+}
+/** Discover the Git worktree owning `cwd` and enumerate tracked/non-ignored paths. */
+export declare function discoverRepository(cwd: string, signal?: AbortSignal): Promise<RepositorySnapshotSource>;
+/** Resolve the canonical Git worktree root owning `cwd` without inventorying its files. */
+export declare function discoverRepositoryRoot(cwd: string, signal?: AbortSignal): Promise<string>;
+/** Return true when two repository fences refer to the same checkout state. */
+export declare function sameRepositoryFence(left: RepositoryState, right: RepositoryState): boolean;
+/** Return the Git metadata directory for diagnostics. */
+export declare function gitMetadataParent(state: RepositoryState): string;

package/lib/types/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * DSH Turn Rewind, powered by persistent, inspectable, approval-gated Change Ledger restore points.
+ * @module @anionex/dsh-turn-rewind
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { ChangeLedgerEngine } from './engine.js';
+import type { ChangeLedgerConfig } from './types.js';
+export * from './engine.js';
+export * from './errors.js';
+export * from './rewind-host.js';
+export * from './types.js';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        changeLedger: ChangeLedgerService;
+    }
+}
+/** Cordis service exposed as `ctx.changeLedger` for other DSH plugins. */
+export declare class ChangeLedgerService {
+    readonly engine: ChangeLedgerEngine;
+    /** Register the service and startup reconciliation. */
+    constructor(ctx: Context, config?: ChangeLedgerConfig);
+    /** Wait for startup reconciliation. */
+    initialize(): ReturnType<ChangeLedgerEngine['initialize']>;
+    /** Create a user restore point. */
+    create(options: Parameters<ChangeLedgerEngine['create']>[0]): ReturnType<ChangeLedgerEngine['create']>;
+    /** Capture project files before one turn enters its first Agent step. */
+    createTurnCheckpoint(options: Parameters<ChangeLedgerEngine['createTurnCheckpoint']>[0]): ReturnType<ChangeLedgerEngine['createTurnCheckpoint']>;
+    /** Find the prompt-anchored checkpoint for one session turn. */
+    findTurnCheckpoint(options: Parameters<ChangeLedgerEngine['findTurnCheckpoint']>[0]): ReturnType<ChangeLedgerEngine['findTurnCheckpoint']>;
+    /** List restore points. */
+    list(options: Parameters<ChangeLedgerEngine['list']>[0]): ReturnType<ChangeLedgerEngine['list']>;
+    /** Compare a restore point with the current worktree. */
+    inspect(options: Parameters<ChangeLedgerEngine['inspect']>[0]): ReturnType<ChangeLedgerEngine['inspect']>;
+    /** Create an expiring restore plan. */
+    planRestore(options: Parameters<ChangeLedgerEngine['planRestore']>[0]): ReturnType<ChangeLedgerEngine['planRestore']>;
+    /** Apply an exact restore plan after approval. */
+    applyRestore(options: Parameters<ChangeLedgerEngine['applyRestore']>[0]): ReturnType<ChangeLedgerEngine['applyRestore']>;
+    /** Delete one restore point and collect unused blobs. */
+    delete(options: Parameters<ChangeLedgerEngine['delete']>[0]): ReturnType<ChangeLedgerEngine['delete']>;
+    /** List interrupted restore operations and their rescue points. */
+    listRecovery(options: Parameters<ChangeLedgerEngine['listRecovery']>[0]): ReturnType<ChangeLedgerEngine['listRecovery']>;
+}
+export default ChangeLedgerService;

package/lib/types/path-utils.d.ts

@@ -0,0 +1,34 @@
+/** Return whether `candidate` is equal to or below `root`. */
+export declare function isWithin(root: string, candidate: string): boolean;
+/** Validate and normalize one repository-relative path without filesystem access. */
+export declare function validateRelativePath(path: string): string;
+/** Resolve a validated relative path below `root`. */
+export declare function resolveWorkspacePath(root: string, path: string): string;
+/** Expand a leading `~/` against the provided home directory. */
+export declare function expandHome(path: string, home: string): string;
+/** Canonicalize an existing directory and reject non-directories. */
+export declare function canonicalDirectory(path: string): Promise<string>;
+/** Atomically replace one JSON file with owner-only permissions. */
+export declare function writeJsonAtomic(path: string, value: unknown): Promise<void>;
+/** Read and parse one JSON file. */
+export declare function readJson(path: string): Promise<unknown>;
+/** Return whether a filesystem path exists without following its final symlink. */
+export declare function pathExists(path: string): Promise<boolean>;
+/** Ensure every existing parent below `root` is a real directory, never a symlink. */
+export declare function ensureSafeParents(root: string, target: string): Promise<void>;
+/** Replace a path with a regular file using a sibling temporary file. */
+export declare function replaceRegularFile(path: string, content: Buffer, mode: number): Promise<void>;
+/** Replace a path with a symbolic link using a sibling temporary name. */
+export declare function replaceSymbolicLink(path: string, target: string): Promise<void>;
+/** Remove one file/symlink or one empty directory, never a non-empty tree. */
+export declare function removeRestoreTarget(path: string): Promise<void>;
+/** Best-effort removal of empty parent directories up to but excluding `root`. */
+export declare function pruneEmptyParents(root: string, start: string): Promise<void>;
+/** Test whether a process id currently exists. */
+export declare function processExists(pid: number): boolean;
+/** Type guard for Node.js errors with a selected `code`. */
+export declare function isNodeError(error: unknown, code: string): error is NodeJS.ErrnoException;
+/** Create one owner-only file exclusively and return its handle. */
+export declare function openExclusive(path: string): Promise<import("fs/promises").FileHandle>;
+/** Flush directory-entry changes where the platform supports directory fsync. */
+export declare function syncDirectory(path: string): Promise<void>;