@cmetech/otto 1.1.1 → 1.2.5

package/packages/coworker-scratchpad/dist/staleness-banner.d.ts

@@ -0,0 +1,12 @@
+export interface StalenessCheck {
+    scratchpadName: string;
+    sessionId: string;
+    bindings: string[];
+    spawnTime: Date;
+    lookupLastModified: (ref: string) => Promise<string | null>;
+}
+export declare class StalenessBanner {
+    private readonly shown;
+    check(args: StalenessCheck): Promise<string | null>;
+    resetForRespawn(scratchpadName: string): void;
+}

package/packages/coworker-scratchpad/dist/staleness-banner.js

@@ -0,0 +1,27 @@
+export class StalenessBanner {
+    shown = new Map(); // scratchpadName → set of "session|ref"
+    async check(args) {
+        const stale = [];
+        for (const ref of args.bindings) {
+            const lm = await args.lookupLastModified(ref);
+            if (!lm)
+                continue;
+            if (new Date(lm).getTime() <= args.spawnTime.getTime())
+                continue;
+            const key = `${args.sessionId}|${ref}`;
+            const set = this.shown.get(args.scratchpadName) ?? new Set();
+            if (set.has(key))
+                continue;
+            set.add(key);
+            this.shown.set(args.scratchpadName, set);
+            stale.push(ref);
+        }
+        if (stale.length === 0)
+            return null;
+        const list = stale.join(', ');
+        return `${list} was modified after this kernel was spawned; env vars are stale. Run /sp reset to respawn with current values.`;
+    }
+    resetForRespawn(scratchpadName) {
+        this.shown.delete(scratchpadName);
+    }
+}

package/packages/coworker-scratchpad/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@otto/coworker-scratchpad",
+  "version": "0.0.1",
+  "description": "Otto co-worker package: coworker-scratchpad",
+  "type": "module",
+  "otto": {
+    "linkable": true,
+    "scope": "@otto",
+    "name": "coworker-scratchpad"
+  },
+  "dependencies": {
+    "@otto/coworker-artifacts": "*",
+    "@otto/coworker-types": "*",
+    "@otto/coworker-utils": "*",
+    "@otto/coworker-vault": "*",
+    "chokidar": "^5.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:publish": "tsc -p tsconfig.publish.json"
+  },
+  "files": ["dist"]
+}

package/packages/coworker-scratchpad/src/cell-archive.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CellArchive, CELLS_SCHEMA_VERSION } from './cell-archive.js';
+
+let dir: string;
+const lines = (p: string): string[] => readFileSync(p, 'utf8').split('\n').filter((l) => l.trim());
+const cellsPath = (): string => join(dir, 'cells.jsonl');
+
+describe('CellArchive', () => {
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'cells-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('writes a schema header once, then a first entry with id 1 / parentId null', () => {
+    const a = new CellArchive(dir, () => 1000);
+    const e = a.append({ code: 'return 1;', ok: true, value: 1, stdout: '' });
+    assert.equal(e.id, 1);
+    assert.equal(e.parentId, null);
+    const ls = lines(cellsPath());
+    assert.deepEqual(JSON.parse(ls[0]), { type: 'header', version: CELLS_SCHEMA_VERSION });
+    const rec = JSON.parse(ls[1]);
+    assert.equal(rec.id, 1);
+    assert.equal(rec.ok, true);
+    assert.equal(rec.value, 1);
+    assert.equal(rec.ts, new Date(1000).toISOString());
+  });
+
+  it('chains parentId to the previous entry', () => {
+    const a = new CellArchive(dir, () => 0);
+    a.append({ code: 'a', ok: true, value: null, stdout: '' });
+    const second = a.append({ code: 'b', ok: true, value: null, stdout: '' });
+    assert.equal(second.id, 2);
+    assert.equal(second.parentId, 1);
+  });
+
+  it('records a failed cell with ok:false and an error (no value)', () => {
+    const a = new CellArchive(dir, () => 0);
+    const e = a.append({ code: 'throw 1', ok: false, error: { name: 'Error', message: 'boom' }, stdout: '' });
+    assert.equal(e.ok, false);
+    assert.equal(e.error!.message, 'boom');
+    assert.equal('value' in e, false);
+  });
+
+  it('continues ids across a fresh archive over the same file (re-attach durability)', () => {
+    const a1 = new CellArchive(dir, () => 0);
+    a1.append({ code: 'a', ok: true, value: null, stdout: '' }); // id 1
+    a1.append({ code: 'b', ok: true, value: null, stdout: '' }); // id 2
+    const a2 = new CellArchive(dir, () => 0); // re-attach: scans existing file
+    const next = a2.append({ code: 'c', ok: true, value: null, stdout: '' });
+    assert.equal(next.id, 3);
+    assert.equal(next.parentId, 2);
+    assert.equal(lines(cellsPath()).filter((l) => l.includes('"id"')).length, 3);
+  });
+
+  it('exposes lastId — null before any append, the most recent id after', () => {
+    const a = new CellArchive(dir, () => 0);
+    assert.equal(a.lastId, null);
+    a.append({ code: 'a', ok: true, value: null, stdout: '' });
+    assert.equal(a.lastId, 1);
+    a.append({ code: 'b', ok: true, value: null, stdout: '' });
+    assert.equal(a.lastId, 2);
+    // re-attach preserves it
+    const a2 = new CellArchive(dir, () => 0);
+    assert.equal(a2.lastId, 2);
+  });
+
+  it('leafId equals lastId after construct on a linear chain (backward-compat)', () => {
+    const a = new CellArchive(dir, () => 0);
+    a.append({ code: 'a', ok: true, value: null, stdout: '' });
+    a.append({ code: 'b', ok: true, value: null, stdout: '' });
+    assert.equal(a.lastId, 2);
+    assert.equal(a.leafId, 2);
+    // Re-construct over the same file: both seed to file-max.
+    const a2 = new CellArchive(dir, () => 0);
+    assert.equal(a2.lastId, 2);
+    assert.equal(a2.leafId, 2);
+  });
+
+  it('setLeaf moves leafId without affecting lastId', () => {
+    const a = new CellArchive(dir, () => 0);
+    a.append({ code: 'a', ok: true, value: null, stdout: '' }); // id 1
+    a.append({ code: 'b', ok: true, value: null, stdout: '' }); // id 2
+    a.append({ code: 'c', ok: true, value: null, stdout: '' }); // id 3
+    a.setLeaf(1);
+    assert.equal(a.lastId, 3);
+    assert.equal(a.leafId, 1);
+  });
+
+  it('append after setLeaf chains parentId from leaf, not from lastId', () => {
+    const a = new CellArchive(dir, () => 0);
+    a.append({ code: 'a', ok: true, value: null, stdout: '' }); // id 1, parent null
+    a.append({ code: 'b', ok: true, value: null, stdout: '' }); // id 2, parent 1
+    a.append({ code: 'c', ok: true, value: null, stdout: '' }); // id 3, parent 2
+    a.setLeaf(1);
+    const branched = a.append({ code: 'd', ok: true, value: null, stdout: '' }); // id 4, parent 1
+    assert.equal(branched.id, 4);
+    assert.equal(branched.parentId, 1);
+  });
+
+  it('append after setLeaf updates BOTH lastId and leafId to the new id', () => {
+    const a = new CellArchive(dir, () => 0);
+    a.append({ code: 'a', ok: true, value: null, stdout: '' }); // id 1
+    a.append({ code: 'b', ok: true, value: null, stdout: '' }); // id 2
+    a.setLeaf(1);
+    a.append({ code: 'c', ok: true, value: null, stdout: '' }); // id 3, parent 1
+    assert.equal(a.lastId, 3);
+    assert.equal(a.leafId, 3);
+  });
+
+  it('setLeaf(null) makes the next append a root cell (parentId null)', () => {
+    const a = new CellArchive(dir, () => 0);
+    a.append({ code: 'a', ok: true, value: null, stdout: '' });
+    a.setLeaf(null);
+    const next = a.append({ code: 'b', ok: true, value: null, stdout: '' });
+    assert.equal(next.parentId, null);
+  });
+
+  it('reset truncates the file back to the schema header and clears lastId + leafId', () => {
+    const a = new CellArchive(dir, () => 1000);
+    a.append({ code: 'a', ok: true, value: 1, stdout: '' });
+    a.append({ code: 'b', ok: true, value: 2, stdout: '' });
+    assert.equal(a.lastId, 2);
+    assert.equal(a.leafId, 2);
+    a.reset();
+    assert.equal(a.lastId, null);
+    assert.equal(a.leafId, null);
+    const ls = lines(cellsPath());
+    assert.equal(ls.length, 1);
+    assert.deepEqual(JSON.parse(ls[0]), { type: 'header', version: CELLS_SCHEMA_VERSION });
+  });
+
+  it('append after reset starts a fresh chain at id 1, parentId null', () => {
+    const a = new CellArchive(dir, () => 1000);
+    a.append({ code: 'a', ok: true, value: 1, stdout: '' });
+    a.append({ code: 'b', ok: true, value: 2, stdout: '' });
+    a.reset();
+    const next = a.append({ code: 'c', ok: true, value: 3, stdout: '' });
+    assert.equal(next.id, 1);
+    assert.equal(next.parentId, null);
+    assert.equal(a.lastId, 1);
+    assert.equal(a.leafId, 1);
+  });
+});

package/packages/coworker-scratchpad/src/cell-archive.ts

@@ -0,0 +1,97 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const CELLS_SCHEMA_VERSION = 1;
+
+export interface CellEntry {
+  id: number;
+  parentId: number | null;
+  code: string;
+  ok: boolean;
+  value?: unknown;
+  error?: { name: string; message: string };
+  stdout: string;
+  ts: string;
+}
+
+export interface AppendInput {
+  code: string;
+  ok: boolean;
+  value?: unknown;
+  error?: { name: string; message: string };
+  stdout: string;
+}
+
+export class CellArchive {
+  private readonly path: string;
+  private nextId: number;
+  #lastId: number | null;
+  #leafId: number | null;
+
+  constructor(private readonly dir: string, private readonly now: () => number = Date.now) {
+    this.path = join(dir, 'cells.jsonl');
+    const { nextId, lastId } = this.scan();
+    this.nextId = nextId;
+    this.#lastId = lastId;
+    this.#leafId = lastId;
+  }
+
+  private scan(): { nextId: number; lastId: number | null } {
+    if (!existsSync(this.path)) return { nextId: 1, lastId: null };
+    let lastId: number | null = null;
+    for (const line of readFileSync(this.path, 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const obj = JSON.parse(line) as { id?: unknown };
+        if (typeof obj.id === 'number') lastId = obj.id;
+      } catch {
+        // header or corrupt line -> ignore
+      }
+    }
+    return { nextId: (lastId ?? 0) + 1, lastId };
+  }
+
+  private ensureHeader(): void {
+    if (existsSync(this.path)) return;
+    mkdirSync(this.dir, { recursive: true });
+    appendFileSync(this.path, JSON.stringify({ type: 'header', version: CELLS_SCHEMA_VERSION }) + '\n');
+  }
+
+  append(input: AppendInput): CellEntry {
+    this.ensureHeader();
+    const id = this.nextId++;
+    const entry: CellEntry = {
+      id,
+      parentId: this.#leafId,
+      code: input.code,
+      ok: input.ok,
+      ...(input.ok ? { value: input.value } : { error: input.error }),
+      stdout: input.stdout,
+      ts: new Date(this.now()).toISOString(),
+    };
+    appendFileSync(this.path, JSON.stringify(entry) + '\n');
+    this.#lastId = id;
+    this.#leafId = id;
+    return entry;
+  }
+
+  get lastId(): number | null {
+    return this.#lastId;
+  }
+
+  get leafId(): number | null {
+    return this.#leafId;
+  }
+
+  setLeaf(id: number | null): void {
+    this.#leafId = id;
+  }
+
+  reset(): void {
+    mkdirSync(this.dir, { recursive: true });
+    writeFileSync(this.path, JSON.stringify({ type: 'header', version: CELLS_SCHEMA_VERSION }) + '\n');
+    this.nextId = 1;
+    this.#lastId = null;
+    this.#leafId = null;
+  }
+}

package/packages/coworker-scratchpad/src/cell-tree.test.ts

@@ -0,0 +1,105 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import type { CellEntry } from './cell-archive.js';
+import { projectTree, findLeaves, validateLeafId, formatTreeText } from './cell-tree.js';
+
+function mkCell(id: number, parentId: number | null, ok = true, value: unknown = id, code = `return ${id};`): CellEntry {
+  return ok
+    ? { id, parentId, code, ok: true, value, stdout: '', ts: `t${id}` }
+    : { id, parentId, code, ok: false, error: { name: 'Error', message: String(value) }, stdout: '', ts: `t${id}` };
+}
+
+describe('projectTree', () => {
+  it('returns null root and empty maps for an empty cell list', () => {
+    const t = projectTree([]);
+    assert.equal(t.root, null);
+    assert.equal(t.byId.size, 0);
+    assert.deepEqual(t.orphans, []);
+  });
+
+  it('builds a linear chain into a single-spine tree', () => {
+    const cells = [mkCell(1, null), mkCell(2, 1), mkCell(3, 2)];
+    const t = projectTree(cells);
+    assert.equal(t.root?.cell.id, 1);
+    assert.equal(t.root?.children.length, 1);
+    assert.equal(t.root?.children[0].cell.id, 2);
+    assert.equal(t.root?.children[0].children[0].cell.id, 3);
+    assert.equal(t.byId.size, 3);
+    assert.deepEqual(t.orphans, []);
+  });
+
+  it('builds a branching tree when a parent has two children', () => {
+    // 1 → 2 → 3
+    //     └→ 4
+    const cells = [mkCell(1, null), mkCell(2, 1), mkCell(3, 2), mkCell(4, 2)];
+    const t = projectTree(cells);
+    assert.equal(t.byId.get(2)!.children.length, 2);
+    const ids = t.byId.get(2)!.children.map((c) => c.cell.id).sort();
+    assert.deepEqual(ids, [3, 4]);
+  });
+
+  it('collects orphans when parentId points to a missing id', () => {
+    const cells = [mkCell(1, null), mkCell(5, 99)]; // 99 doesn't exist
+    const t = projectTree(cells);
+    assert.equal(t.root?.cell.id, 1);
+    assert.equal(t.orphans.length, 1);
+    assert.equal(t.orphans[0].cell.id, 5);
+  });
+});
+
+describe('findLeaves', () => {
+  it('returns all childless nodes', () => {
+    // 1 → 2 → 3
+    //     └→ 4
+    const cells = [mkCell(1, null), mkCell(2, 1), mkCell(3, 2), mkCell(4, 2)];
+    const leaves = findLeaves(projectTree(cells));
+    const ids = leaves.map((n) => n.cell.id).sort();
+    assert.deepEqual(ids, [3, 4]);
+  });
+});
+
+describe('validateLeafId', () => {
+  it('returns without throwing when id is present', () => {
+    const t = projectTree([mkCell(1, null), mkCell(2, 1)]);
+    assert.doesNotThrow(() => validateLeafId(t, 2));
+  });
+
+  it('throws when id is missing', () => {
+    const t = projectTree([mkCell(1, null)]);
+    assert.throws(() => validateLeafId(t, 99), /cell id 99 not found/);
+  });
+});
+
+describe('formatTreeText', () => {
+  it('renders ok cells with #id, ok flag, value, and code preview', () => {
+    const text = formatTreeText(projectTree([mkCell(1, null, true, 42, 'return 42;')]));
+    assert.match(text, /#1/);
+    assert.match(text, /\bok\b/);
+    assert.match(text, /value=42/);
+    assert.match(text, /return 42;/);
+  });
+
+  it('renders err cells with error message instead of value', () => {
+    const text = formatTreeText(projectTree([mkCell(1, null, false, 'boom', 'throw 1;')]));
+    assert.match(text, /\berr\b/);
+    assert.match(text, /error=boom/);
+    assert.doesNotMatch(text, /value=/);
+  });
+
+  it('marks the current leaf with a trailing *', () => {
+    const cells = [mkCell(1, null), mkCell(2, 1)];
+    const text = formatTreeText(projectTree(cells), 2);
+    const lineWith2 = text.split('\n').find((l) => l.includes('#2'))!;
+    assert.match(lineWith2, /\*\s*$/);
+    const lineWith1 = text.split('\n').find((l) => l.includes('#1'))!;
+    assert.doesNotMatch(lineWith1, /\*\s*$/);
+  });
+
+  it('truncates code preview to 60 chars', () => {
+    const longCode = 'const x = '.padEnd(200, 'A');
+    const text = formatTreeText(projectTree([mkCell(1, null, true, null, longCode)]));
+    const line = text.split('\n').find((l) => l.includes('#1'))!;
+    // The 60-char preview plus ellipsis OR cut at 60; either way the full 200-char source must not appear.
+    assert.doesNotMatch(line, /A{100}/);
+  });
+});

package/packages/coworker-scratchpad/src/cell-tree.ts

@@ -0,0 +1,90 @@
+import type { CellEntry } from './cell-archive.js';
+
+export interface TreeNode {
+  cell: CellEntry;
+  children: TreeNode[];
+}
+
+export interface CellTree {
+  root: TreeNode | null;
+  byId: Map<number, TreeNode>;
+  orphans: TreeNode[];
+}
+
+export function projectTree(cells: CellEntry[]): CellTree {
+  const byId = new Map<number, TreeNode>();
+  for (const cell of cells) byId.set(cell.id, { cell, children: [] });
+  const orphans: TreeNode[] = [];
+  const rootCandidates: TreeNode[] = [];
+  for (const cell of cells) {
+    const node = byId.get(cell.id)!;
+    if (cell.parentId === null) {
+      rootCandidates.push(node);
+      continue;
+    }
+    const parent = byId.get(cell.parentId);
+    if (parent) parent.children.push(node);
+    else orphans.push(node);
+  }
+  let root: TreeNode | null = null;
+  if (rootCandidates.length >= 1) {
+    root = rootCandidates[0];
+    // 1d/1d2 invariant: exactly one root. Defensive: extra roots become orphans.
+    for (let i = 1; i < rootCandidates.length; i++) orphans.push(rootCandidates[i]);
+  }
+  return { root, byId, orphans };
+}
+
+export function findLeaves(tree: CellTree): TreeNode[] {
+  const out: TreeNode[] = [];
+  for (const node of tree.byId.values()) {
+    if (node.children.length === 0) out.push(node);
+  }
+  return out;
+}
+
+export function validateLeafId(tree: CellTree, id: number): void {
+  if (!tree.byId.has(id)) {
+    throw new Error(`cell id ${id} not found`);
+  }
+}
+
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1) + '…';
+}
+
+function summarizeCell(cell: CellEntry): string {
+  const okFlag = cell.ok ? 'ok ' : 'err';
+  const detail = cell.ok
+    ? `value=${truncate(JSON.stringify(cell.value ?? null), 40)}`
+    : `error=${truncate(cell.error?.message ?? '', 40)}`;
+  const codePreview = truncate(cell.code.split('\n')[0], 60);
+  return `#${cell.id} ${okFlag} ${detail.padEnd(45)} ${codePreview}`;
+}
+
+function renderNode(
+  node: TreeNode,
+  depth: number,
+  lastSibling: boolean,
+  currentLeaf: number | null | undefined,
+  out: string[],
+): void {
+  const indent = '  '.repeat(depth);
+  const connector = lastSibling ? '└─' : '├─';
+  const marker = currentLeaf === node.cell.id ? ' *' : '';
+  out.push(`${indent}${connector} ${summarizeCell(node.cell)}${marker}`);
+  const last = node.children.length - 1;
+  node.children.forEach((child, i) => renderNode(child, depth + 1, i === last, currentLeaf, out));
+}
+
+export function formatTreeText(tree: CellTree, currentLeaf?: number | null): string {
+  const lines: string[] = [];
+  if (tree.root) renderNode(tree.root, 0, true, currentLeaf ?? null, lines);
+  if (tree.orphans.length > 0) {
+    lines.push('# orphans:');
+    const last = tree.orphans.length - 1;
+    tree.orphans.forEach((o, i) => renderNode(o, 0, i === last, currentLeaf ?? null, lines));
+  }
+  return lines.join('\n');
+}