copperhead 0.6.0 → 0.8.0

package/src/util/dock.ts

@@ -0,0 +1,161 @@
+/**
+ * Bottom-of-viewport dock built on DECSTBM scroll regions: content is fenced
+ * into rows [1, H - dockHeight] and the dock is painted with absolute cursor
+ * addressing below the scroll margin, so no amount of content output (or
+ * mouse wheel) can ever move it. Runs inside the alternate screen buffer the
+ * REPL enters at startup. This is the FrankenTUI/ratatui-inline technique;
+ * see also DECSTBM (CSI r).
+ */
+
+import { truncateVisible } from '../agent/box.js';
+
+const HIDE = '\x1b[?25l';
+const SHOW = '\x1b[?25h';
+/** Synchronized-output guards; terminals without support ignore them. */
+const SYNC_ON = '\x1b[?2026h';
+const SYNC_OFF = '\x1b[?2026l';
+/** Reset the scroll region to the full screen. Homes the cursor (hence DECSC/DECRC around it). */
+const REGION_RESET = '\x1b[r';
+const SAVE = '\x1b7';
+const RESTORE = '\x1b8';
+
+export class TerminalDock {
+  /** Rows the dock currently occupies at the bottom of the screen. */
+  private dockH = 0;
+  /**
+   * True while the real cursor is parked at a caret position inside the dock
+   * (the DECSC slot then holds the content-region position to return to).
+   */
+  private parked = false;
+  /** Last set() payload, replayable after an external overdraw (animations). */
+  private last: { lines: string[]; caret?: { row: number; col: number } } | null = null;
+
+  constructor(private readonly out: NodeJS.WriteStream) {}
+
+  cols(): number {
+    return typeof this.out.columns === 'number' && this.out.columns ? this.out.columns : 80;
+  }
+
+  rows(): number {
+    return typeof this.out.rows === 'number' && this.out.rows ? this.out.rows : 24;
+  }
+
+  /**
+   * Replace the docked region. On a height change the content scroll region
+   * is re-fenced; same-height repaints are pure absolute-addressed writes and
+   * can never scroll anything. With `caret` (dock-relative 1-based row and
+   * column) the real terminal cursor is left parked there, Claude Code-style.
+   */
+  set(lines: string[], caret?: { row: number; col: number }): void {
+    if (!lines.length) {
+      this.release();
+      return;
+    }
+    const h = this.rows();
+    const shown = lines.slice(0, Math.max(1, h - 3)).map((l) => truncateVisible(l, this.cols() - 1));
+    const newH = shown.length;
+
+    let seq = SYNC_ON + HIDE;
+    if (this.parked) {
+      // Return to the content position first so the SAVE/RESTORE pairs below
+      // keep preserving it, not the old caret.
+      seq += RESTORE;
+      this.parked = false;
+    }
+    if (this.dockH === 0) {
+      // First activation: free the bottom rows by scrolling exactly as much
+      // as needed (preserves the banner above), then fence content into
+      // [1, h - newH]. DECSTBM homes the cursor; save/restore keeps it.
+      seq += SAVE + REGION_RESET + RESTORE;
+      seq += '\n'.repeat(newH) + `\x1b[${newH}A`;
+      seq += SAVE + `\x1b[1;${h - newH}r` + RESTORE;
+    } else if (newH !== this.dockH) {
+      // Height change while active (menu open/close): overlay mode. Re-fence
+      // and clear any rows freed by a shrink; never scroll content.
+      seq += SAVE + `\x1b[1;${h - newH}r`;
+      for (let r = h - Math.max(this.dockH, newH) + 1; r <= h - newH; r++) {
+        seq += `\x1b[${r};1H\x1b[2K`;
+      }
+      seq += RESTORE;
+    }
+    seq += SAVE;
+    for (let i = 0; i < newH; i++) {
+      seq += `\x1b[${h - newH + 1 + i};1H\x1b[2K${shown[i]!}`;
+    }
+    seq += RESTORE;
+    if (caret) {
+      const row = Math.min(h, h - newH + Math.max(1, caret.row));
+      const col = Math.max(1, Math.min(this.cols(), caret.col));
+      seq += SAVE + `\x1b[${row};${col}H`;
+      this.parked = true;
+    }
+    seq += SHOW + SYNC_OFF;
+    this.out.write(seq);
+    this.dockH = newH;
+    this.last = caret ? { lines, caret } : { lines };
+  }
+
+  /** Replay the last set() (e.g. after an animation overdrew part of the screen). */
+  repaint(): void {
+    if (this.last) this.set(this.last.lines, this.last.caret);
+  }
+
+  /** Rows available to content above the dock. */
+  contentRows(): number {
+    return Math.max(1, this.rows() - this.dockH);
+  }
+
+  /**
+   * Absolute-paint the whole content region (rows 1..contentRows) from the
+   * given lines — used by history scrolling to show any window of the session
+   * log. Does not touch the DECSC slot or the fence; callers repaint() the
+   * dock afterwards to restore the caret.
+   */
+  paintContent(lines: string[]): void {
+    const rowsN = this.contentRows();
+    const shown = lines.slice(-rowsN).map((l) => truncateVisible(l, this.cols() - 1));
+    let seq = SYNC_ON + HIDE;
+    for (let r = 1; r <= rowsN; r++) {
+      seq += `\x1b[${r};1H\x1b[2K${shown[r - 1] ?? ''}`;
+    }
+    seq += SYNC_OFF;
+    this.out.write(seq);
+  }
+
+  /**
+   * Write a scrollback line above the dock. With the fence in place a plain
+   * write cannot touch the dock rows; if the cursor is parked at the caret,
+   * hop back to the content region for the write and re-park after.
+   */
+  log(line: string): void {
+    if (!this.parked) {
+      this.out.write(line + '\n');
+      return;
+    }
+    this.out.write(SYNC_ON + RESTORE + line + '\n' + SAVE + SYNC_OFF);
+    // The slot now holds the advanced content position; the caret will be
+    // re-established by the next set() with a caret argument.
+    this.parked = false;
+  }
+
+  /** Drop the fence, clear the dock rows, and restore the cursor. */
+  release(): void {
+    if (!this.dockH) {
+      this.out.write(SHOW);
+      return;
+    }
+    const h = this.rows();
+    let seq = SYNC_ON;
+    if (this.parked) {
+      seq += RESTORE;
+      this.parked = false;
+    }
+    seq += SAVE + REGION_RESET + RESTORE;
+    seq += SAVE;
+    for (let r = h - this.dockH + 1; r <= h; r++) seq += `\x1b[${r};1H\x1b[2K`;
+    seq += RESTORE + SHOW + SYNC_OFF;
+    this.out.write(seq);
+    this.dockH = 0;
+    this.last = null;
+  }
+}

package/src/util/git.ts

@@ -1,13 +1,53 @@
 import { execa } from 'execa';
-import { cp, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { access, constants, cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { PreflightError } from './preflight.js';
 
+/**
+ * Paths copperhead must keep out of `git add -A`. KiCad ≥9 writes a
+ * git-backed local-history directory (`.history/`, complete with its own nested
+ * `.git`) into the project the first time kicad-cli touches it. Left untracked,
+ * that nested repo has an unborn HEAD, so a plain `git add -A` in the parent
+ * aborts with `error: '.history/' does not have a commit checked out` (exit
+ * 128) — which fails the commit at the end of every KiCad-touching stage
+ * (schematic, layout, outputs). Ignoring it is both correct (local history is
+ * never a project artifact) and the fix for that abort. Kept as a list so other
+ * KiCad transients can join it if they surface.
+ */
+const GIT_ADD_EXCLUDES = ['.history/'];
+
+/**
+ * Ensure the repo's root .gitignore lists each entry, appending only the
+ * missing ones. Idempotent and best-effort: a failure here must never block a
+ * commit, so it swallows its own errors. Run before any `git add -A` so a
+ * git-backed KiCad `.history/` (or similar nested repo) is skipped instead of
+ * aborting the add.
+ */
+export async function ensureIgnored(repo: string, entries: string[]): Promise<void> {
+  try {
+    const p = path.join(repo, '.gitignore');
+    const text = existsSync(p) ? await readFile(p, 'utf8') : '';
+    const present = new Set(text.split('\n').map((l) => l.trim()));
+    const missing = entries.filter((e) => !present.has(e));
+    if (!missing.length) return;
+    const prefix = text.length && !text.endsWith('\n') ? '\n' : '';
+    await writeFile(p, text + prefix + missing.join('\n') + '\n', 'utf8');
+  } catch {
+    // best-effort: .gitignore maintenance must never be the thing that fails a run
+  }
+}
+
 export interface GitSnapshot {
   head: string;
   stash: string | null;
+  /**
+   * Tree object holding the untracked-but-not-ignored files that `git stash
+   * create` cannot capture. Without it a rollback's `git clean -fd` deletes
+   * them for good; see snapshotUntracked().
+   */
+  untracked: string | null;
 }
 
 async function git(repo: string, args: string[]): Promise<string> {
@@ -15,6 +55,121 @@ async function git(repo: string, args: string[]): Promise<string> {
   return stdout.trim();
 }
 
+/** Same as git(), with a scratch index so the repo's real index is untouched. */
+async function gitWithIndex(repo: string, indexFile: string, args: string[]): Promise<string> {
+  const { stdout } = await execa('git', args, {
+    cwd: repo,
+    env: { GIT_INDEX_FILE: indexFile },
+  });
+  return stdout.trim();
+}
+
+/** Monotonic suffix so two scratch indexes in one process never collide. */
+let scratchIndexSeq = 0;
+
+/**
+ * Path for a throwaway index, inside the repo's own git dir rather than
+ * TMPDIR: git guarantees that directory exists and is writable, so a hostile
+ * or missing temp dir cannot make a snapshot fail and block a run from
+ * starting. Absolute, because git resolves GIT_INDEX_FILE against cwd.
+ */
+async function scratchIndexPath(repo: string): Promise<string> {
+  const gitDir = await git(repo, ['rev-parse', '--absolute-git-dir']);
+  return path.join(gitDir, `copperhead-index-${process.pid}-${scratchIndexSeq++}`);
+}
+
+/**
+ * Write the untracked-but-not-ignored files to a tree object and return its
+ * sha, or null when there are none.
+ *
+ * `git stash create` only ever captures tracked changes, so on its own it
+ * leaves every new file a run (or the user) has not added yet outside the
+ * snapshot — and restore()'s `git clean -fd` then deletes exactly those. The
+ * two sets line up: `--exclude-standard` skips ignored paths and plain
+ * `clean -fd` (no -x) leaves them alone, so what is captured here is precisely
+ * what the rollback would otherwise destroy.
+ *
+ * Built through a scratch GIT_INDEX_FILE rather than `git add -A`, because
+ * this runs at the *start* of a run: staging the user's files would outlive a
+ * successful run and silently rewrite their staged/unstaged split.
+ */
+async function snapshotUntracked(repo: string): Promise<string | null> {
+  const listed = await git(repo, ['ls-files', '--others', '--exclude-standard', '-z']);
+  const paths = listed.split('\0').filter(Boolean);
+  if (!paths.length) return null;
+  const usable = await readableOnly(repo, paths);
+  if (!usable.length) return null;
+  const indexFile = await scratchIndexPath(repo);
+  try {
+    await execa('git', ['update-index', '-z', '--add', '--stdin'], {
+      cwd: repo,
+      env: { GIT_INDEX_FILE: indexFile },
+      input: usable.join('\0') + '\0',
+    });
+    return (await gitWithIndex(repo, indexFile, ['write-tree'])) || null;
+  } catch (err) {
+    // A path that passed the readability check above and still failed here
+    // lost the race (permissions or existence changed in between). Same
+    // refusal, since the same file would be destroyed by the rollback.
+    throw unsnapshottable(String((err as Error).message).split('\n')[0] ?? 'unknown path');
+  } finally {
+    await rm(indexFile, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Drop untracked paths that no longer exist, and refuse on any that exist but
+ * cannot be read.
+ *
+ * `git update-index` aborts the whole batch with exit 128 on the first path it
+ * cannot open, and this runs before the first turn, so one stray root-owned or
+ * mode-000 file would otherwise refuse every `--allow-dirty` run with a bare
+ * `fatal: Unable to process path …`. A vanished path is dropped rather than
+ * refused: a file that no longer exists cannot be lost. One that exists but is
+ * unreadable is refused deliberately rather than skipped, because `restore()`'s
+ * `git clean -fd` deletes it either way, and skipping would quietly reinstate
+ * exactly the data loss the untracked snapshot exists to prevent.
+ */
+async function readableOnly(repo: string, paths: string[]): Promise<string[]> {
+  const usable: string[] = [];
+  for (const p of paths) {
+    try {
+      await access(path.join(repo, p), constants.R_OK);
+      usable.push(p);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') continue;
+      throw unsnapshottable(p);
+    }
+  }
+  return usable;
+}
+
+function unsnapshottable(what: string): PreflightError {
+  return new PreflightError(
+    `cannot read untracked file: ${what}`,
+    'a run started with --allow-dirty promises your uncommitted work survives a failed run, but a file copperhead cannot read cannot be snapshotted, and the rollback would delete it with nothing to restore it from',
+    [
+      `make it readable: chmod +r "${what}"`,
+      'or delete it, or add it to .gitignore so the rollback leaves it alone',
+      'or commit your work and rerun without --allow-dirty',
+    ],
+  );
+}
+
+/**
+ * Re-materialize the untracked files captured by snapshotUntracked(). Runs
+ * after `stash apply` so tracked restores win any path collision.
+ */
+async function restoreUntracked(repo: string, tree: string): Promise<void> {
+  const indexFile = await scratchIndexPath(repo);
+  try {
+    await gitWithIndex(repo, indexFile, ['read-tree', tree]);
+    await gitWithIndex(repo, indexFile, ['checkout-index', '-a', '-f']);
+  } finally {
+    await rm(indexFile, { force: true }).catch(() => {});
+  }
+}
+
 export async function isGitRepo(repo: string): Promise<boolean> {
   try {
     await git(repo, ['rev-parse', '--git-dir']);
@@ -74,16 +229,19 @@ export async function gitPreflight(repo: string, opts: { allowDirty?: boolean }
 
 /**
  * Snapshot the working tree before a run. On a clean tree HEAD is enough;
- * with --allow-dirty we keep a `git stash create` object so uncommitted work
- * survives a rollback (SPEC §7).
+ * with --allow-dirty we keep a `git stash create` object for tracked changes
+ * plus a tree of the untracked files it cannot see, so uncommitted work
+ * survives a rollback intact (SPEC §7).
  */
 export async function snapshot(repo: string): Promise<GitSnapshot> {
   const head = await git(repo, ['rev-parse', 'HEAD']);
   let stash: string | null = null;
+  let untracked: string | null = null;
   if (await isDirty(repo)) {
     stash = (await git(repo, ['stash', 'create'])) || null;
+    untracked = await snapshotUntracked(repo);
   }
-  return { head, stash };
+  return { head, stash, untracked };
 }
 
 /**
@@ -114,6 +272,18 @@ export async function restore(repo: string, snap: GitSnapshot): Promise<void> {
       if (snap.stash) {
         await git(repo, ['stash', 'apply', snap.stash]);
       }
+      // The clean above deleted every untracked file; put back the ones that
+      // were there before the run. Never fatal: a rollback that restored the
+      // tracked state is still better than one that threw halfway.
+      if (snap.untracked) {
+        try {
+          await restoreUntracked(repo, snap.untracked);
+        } catch (err) {
+          console.warn(
+            `warning: could not restore untracked files after rollback: ${(err as Error).message}`,
+          );
+        }
+      }
     } finally {
       if (backup && existsSync(backup)) {
         try {
@@ -147,6 +317,7 @@ export async function restore(repo: string, snap: GitSnapshot): Promise<void> {
 export async function preserveFailedRun(repo: string, runId: string): Promise<string | null> {
   try {
     if (!(await isDirty(repo))) return null;
+    await ensureIgnored(repo, GIT_ADD_EXCLUDES);
     // Never leave the audit trail staged: a staged-but-not-in-HEAD path is
     // deleted by restore()'s `reset --hard`, which silently defeats its
     // `clean -e .copperhead/runs` protection (that flag only spares untracked
@@ -181,6 +352,7 @@ export async function uncommittedCount(repo: string): Promise<number> {
 }
 
 export async function commitAll(repo: string, message: string): Promise<string> {
+  await ensureIgnored(repo, GIT_ADD_EXCLUDES);
   await git(repo, ['add', '-A']);
   await git(repo, ['commit', '-m', message]);
   return git(repo, ['rev-parse', 'HEAD']);