@anionex/dsh-turn-rewind 0.1.0

package/src/errors.ts

@@ -0,0 +1,23 @@
+/** Stable error carrying a machine-readable change-ledger code. */
+export class ChangeLedgerError extends Error {
+  override readonly name = 'ChangeLedgerError'
+
+  /**
+   * @param code - Stable error category.
+   * @param message - Human-readable diagnostic.
+   * @param cause - Optional lower-level failure.
+   */
+  constructor(
+    readonly code: string,
+    message: string,
+    options?: { readonly cause?: unknown },
+  ) {
+    super(`[${code}] ${message}`, options)
+  }
+}
+
+/** Convert an unknown thrown value into one bounded diagnostic line. */
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message.slice(0, 2_000)
+  return String(error).slice(0, 2_000)
+}

package/src/git.ts

@@ -0,0 +1,178 @@
+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'
+import type { RepositoryState } from './types.js'
+
+const GIT_MAX_BUFFER = 32 * 1024 * 1024
+
+/** 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 async function discoverRepository(cwd: string, signal?: AbortSignal): Promise<RepositorySnapshotSource> {
+  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: string, signal?: AbortSignal): Promise<string> {
+  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: RepositoryState, right: RepositoryState): boolean {
+  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: string, args: readonly string[], signal?: AbortSignal): Promise<string> {
+  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: string, args: readonly string[], signal?: AbortSignal): Promise<string | undefined> {
+  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: unknown): string | number | undefined {
+  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: string): string[] {
+  if (value === '') return []
+  const parts = value.split('\0')
+  if (parts.at(-1) === '') parts.pop()
+  return parts
+}
+
+function parseSubmodules(value: string): string[] {
+  const paths: string[] = []
+  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: string): Promise<string | undefined> {
+  const markers: readonly [string, string][] = [
+    ['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: string | undefined): string | undefined {
+  const trimmed = value?.trim()
+  return trimmed === undefined || trimmed === '' ? undefined : trimmed
+}
+
+function stripLineEnding(value: string): string {
+  if (value.endsWith('\r\n')) return value.slice(0, -2)
+  if (value.endsWith('\n')) return value.slice(0, -1)
+  return value
+}
+
+function comparePaths(left: string, right: string): number {
+  return Buffer.from(left).compare(Buffer.from(right))
+}
+
+/** Return the Git metadata directory for diagnostics. */
+export function gitMetadataParent(state: RepositoryState): string {
+  return dirname(state.commonDir)
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 { installRewindHttp, TurnCheckpointCoordinator } from './rewind-host.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 class ChangeLedgerService {
+  readonly engine: ChangeLedgerEngine
+
+  /** Register the service and startup reconciliation. */
+  constructor(ctx: Context, config: ChangeLedgerConfig = {}) {
+    ctx.provide('changeLedger', this)
+    this.engine = new ChangeLedgerEngine(config)
+    const checkpoints = new TurnCheckpointCoordinator(this.engine)
+    ctx.inject(['agents'], (scope: Context) => { checkpoints.install(scope) })
+    ctx.inject(['webServer', 'sessions', 'sessionQuery', 'apiProxy', 'agents'], (scope: Context) => {
+      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: unknown) => {
+      ctx.logger.error(`[change-ledger] startup failed: ${error instanceof Error ? error.message : String(error)}`)
+    })
+  }
+
+  /** Wait for startup reconciliation. */
+  initialize(): ReturnType<ChangeLedgerEngine['initialize']> {
+    return this.engine.initialize()
+  }
+
+  /** Create a user restore point. */
+  create(options: Parameters<ChangeLedgerEngine['create']>[0]): ReturnType<ChangeLedgerEngine['create']> {
+    return this.engine.create(options)
+  }
+
+  /** Capture project files before one turn enters its first Agent step. */
+  createTurnCheckpoint(
+    options: Parameters<ChangeLedgerEngine['createTurnCheckpoint']>[0],
+  ): ReturnType<ChangeLedgerEngine['createTurnCheckpoint']> {
+    return this.engine.createTurnCheckpoint(options)
+  }
+
+  /** Find the prompt-anchored checkpoint for one session turn. */
+  findTurnCheckpoint(
+    options: Parameters<ChangeLedgerEngine['findTurnCheckpoint']>[0],
+  ): ReturnType<ChangeLedgerEngine['findTurnCheckpoint']> {
+    return this.engine.findTurnCheckpoint(options)
+  }
+
+  /** List restore points. */
+  list(options: Parameters<ChangeLedgerEngine['list']>[0]): ReturnType<ChangeLedgerEngine['list']> {
+    return this.engine.list(options)
+  }
+
+  /** Compare a restore point with the current worktree. */
+  inspect(options: Parameters<ChangeLedgerEngine['inspect']>[0]): ReturnType<ChangeLedgerEngine['inspect']> {
+    return this.engine.inspect(options)
+  }
+
+  /** Create an expiring restore plan. */
+  planRestore(options: Parameters<ChangeLedgerEngine['planRestore']>[0]): ReturnType<ChangeLedgerEngine['planRestore']> {
+    return this.engine.planRestore(options)
+  }
+
+  /** Apply an exact restore plan after approval. */
+  applyRestore(options: Parameters<ChangeLedgerEngine['applyRestore']>[0]): ReturnType<ChangeLedgerEngine['applyRestore']> {
+    return this.engine.applyRestore(options)
+  }
+
+  /** Delete one restore point and collect unused blobs. */
+  delete(options: Parameters<ChangeLedgerEngine['delete']>[0]): ReturnType<ChangeLedgerEngine['delete']> {
+    return this.engine.delete(options)
+  }
+
+  /** List interrupted restore operations and their rescue points. */
+  listRecovery(options: Parameters<ChangeLedgerEngine['listRecovery']>[0]): ReturnType<ChangeLedgerEngine['listRecovery']> {
+    return this.engine.listRecovery(options)
+  }
+}
+
+export default ChangeLedgerService

package/src/path-utils.ts

@@ -0,0 +1,255 @@
+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: string, candidate: string): boolean {
+  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: string): string {
+  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: string, path: string): string {
+  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: string, home: string): string {
+  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: string): Promise<string> {
+  let canonical: string
+  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: string, value: unknown): Promise<void> {
+  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: string): Promise<unknown> {
+  let body: string
+  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) as unknown
+  } 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: string): Promise<boolean> {
+  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: string, target: string): Promise<void> {
+  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: string, content: Buffer, mode: number): Promise<void> {
+  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: string, target: string): Promise<void> {
+  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: string): Promise<void> {
+  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: string, start: string): Promise<void> {
+  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: number): boolean {
+  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: unknown, code: string): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error && error.code === code
+}
+
+async function renameReplacing(source: string, destination: string): Promise<void> {
+  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: string) {
+  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: string): Promise<void> {
+  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()
+  }
+}