@cmetech/otto 1.1.0 → 1.2.4

package/packages/coworker-utils/src/logger.test.ts

@@ -0,0 +1,50 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createLogger, LogLevel } from './logger.js';
+
+describe('logger', () => {
+  it('createLogger returns an object with debug/info/warn/error', () => {
+    const log = createLogger('test.namespace');
+    assert.equal(typeof log.debug, 'function');
+    assert.equal(typeof log.info, 'function');
+    assert.equal(typeof log.warn, 'function');
+    assert.equal(typeof log.error, 'function');
+  });
+
+  it('logs at or above the configured threshold', () => {
+    const sink: string[] = [];
+    const log = createLogger('test.threshold', {
+      level: 'info' as LogLevel,
+      sink: (line) => sink.push(line),
+    });
+    log.debug('hidden');
+    log.info('visible-info');
+    log.warn('visible-warn');
+    assert.equal(sink.length, 2);
+    assert.match(sink[0], /info.*visible-info/);
+    assert.match(sink[1], /warn.*visible-warn/);
+  });
+
+  it('namespace prefix appears in each line', () => {
+    const sink: string[] = [];
+    const log = createLogger('coworker.memory', { level: 'debug', sink: (l) => sink.push(l) });
+    log.info('hello');
+    assert.match(sink[0], /coworker\.memory/);
+  });
+
+  it('child namespace appends to parent', () => {
+    const sink: string[] = [];
+    const log = createLogger('coworker', { level: 'debug', sink: (l) => sink.push(l) });
+    const child = log.child('memory');
+    child.info('hello');
+    assert.match(sink[0], /coworker\.memory/);
+  });
+
+  it('serializes context object as appended JSON', () => {
+    const sink: string[] = [];
+    const log = createLogger('test.ctx', { level: 'debug', sink: (l) => sink.push(l) });
+    log.info('msg', { user_id: 'u1', count: 3 });
+    assert.match(sink[0], /"user_id":"u1"/);
+    assert.match(sink[0], /"count":3/);
+  });
+});

package/packages/coworker-utils/src/logger.ts

@@ -0,0 +1,45 @@
+// Lightweight logger wrapper. Spec §6.7.
+// Defers to a sink callable so otto-cli can wire it to the existing logger
+// without coworker-utils taking a direct dependency on otto-cli.
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LEVEL_ORDER: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+
+export interface LoggerOptions {
+  level?: LogLevel;
+  sink?: (line: string) => void;
+}
+
+export interface Logger {
+  debug(msg: string, ctx?: Record<string, unknown>): void;
+  info(msg: string, ctx?: Record<string, unknown>): void;
+  warn(msg: string, ctx?: Record<string, unknown>): void;
+  error(msg: string, ctx?: Record<string, unknown>): void;
+  child(suffix: string): Logger;
+}
+
+const DEFAULT_SINK = (line: string): void => {
+  // Phase 0: write to stderr; otto-cli will replace this sink at wire time.
+  process.stderr.write(line + '\n');
+};
+
+export function createLogger(namespace: string, opts: LoggerOptions = {}): Logger {
+  const level = opts.level ?? 'info';
+  const sink = opts.sink ?? DEFAULT_SINK;
+  const threshold = LEVEL_ORDER[level];
+
+  function emit(at: LogLevel, msg: string, ctx?: Record<string, unknown>): void {
+    if (LEVEL_ORDER[at] < threshold) return;
+    const ctxPart = ctx ? ' ' + JSON.stringify(ctx) : '';
+    sink(`${new Date().toISOString()} ${at} ${namespace} ${msg}${ctxPart}`);
+  }
+
+  return {
+    debug: (msg, ctx) => emit('debug', msg, ctx),
+    info:  (msg, ctx) => emit('info', msg, ctx),
+    warn:  (msg, ctx) => emit('warn', msg, ctx),
+    error: (msg, ctx) => emit('error', msg, ctx),
+    child: (suffix) => createLogger(`${namespace}.${suffix}`, { level, sink }),
+  };
+}

package/packages/coworker-utils/src/migration-runner.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { MigrationRunner } from './migration-runner.js';
+
+describe('MigrationRunner', () => {
+  let runner: MigrationRunner;
+
+  beforeEach(() => {
+    runner = new MigrationRunner();
+  });
+
+  it('no migrations registered → identity', async () => {
+    const out = await runner.migrate('cells.jsonl', 1, { rows: [] });
+    assert.deepEqual(out, { rows: [] });
+  });
+
+  it('runs a single registered migration v1 → v2', async () => {
+    runner.register('cells.jsonl', 1, 2, async (data: any) => ({ ...data, kind: 'session' }));
+    const out: any = await runner.migrate('cells.jsonl', 1, { foo: 'bar' });
+    assert.equal(out.kind, 'session');
+    assert.equal(out.foo, 'bar');
+  });
+
+  it('runs a chain of migrations in version order', async () => {
+    runner.register('cells.jsonl', 1, 2, async (d: any) => ({ ...d, v2: true }));
+    runner.register('cells.jsonl', 2, 3, async (d: any) => ({ ...d, v3: true }));
+    const out: any = await runner.migrate('cells.jsonl', 1, {});
+    assert.equal(out.v2, true);
+    assert.equal(out.v3, true);
+  });
+
+  it('throws on missing migration in the chain', async () => {
+    runner.register('cells.jsonl', 1, 2, async (d) => d);
+    runner.register('cells.jsonl', 3, 4, async (d) => d);
+    await assert.rejects(
+      () => runner.migrate('cells.jsonl', 1, {}),
+      /no migration from version 2 to 3/i,
+    );
+  });
+
+  it('idempotent at current version', async () => {
+    runner.register('cells.jsonl', 1, 2, async (d: any) => ({ ...d, ran: true }));
+    const out: any = await runner.migrate('cells.jsonl', 2, { ran: false });
+    assert.equal(out.ran, false, 'should not run migrations when already at latest');
+  });
+
+  it('different kinds have independent migration chains', async () => {
+    runner.register('cells.jsonl', 1, 2, async (d: any) => ({ ...d, kind: 'cells' }));
+    runner.register('layer-b.db', 1, 2, async (d: any) => ({ ...d, kind: 'layer-b' }));
+    const cells: any = await runner.migrate('cells.jsonl', 1, {});
+    const layerB: any = await runner.migrate('layer-b.db', 1, {});
+    assert.equal(cells.kind, 'cells');
+    assert.equal(layerB.kind, 'layer-b');
+  });
+
+  it('latestVersion returns highest registered target version', () => {
+    runner.register('cells.jsonl', 1, 2, async (d) => d);
+    runner.register('cells.jsonl', 2, 3, async (d) => d);
+    assert.equal(runner.latestVersion('cells.jsonl'), 3);
+  });
+
+  it('latestVersion returns null for unknown kind', () => {
+    assert.equal(runner.latestVersion('unknown'), null);
+  });
+});

package/packages/coworker-utils/src/migration-runner.ts

@@ -0,0 +1,50 @@
+// Migration framework — forward-only schema migrations per file kind.
+// Spec §6.2, §3.4c.
+
+export type MigrationFn<TIn = unknown, TOut = unknown> = (data: TIn) => Promise<TOut>;
+
+interface MigrationRecord {
+  from: number;
+  to: number;
+  fn: MigrationFn;
+}
+
+export class MigrationRunner {
+  #byKind = new Map<string, MigrationRecord[]>();
+
+  register<TIn = unknown, TOut = unknown>(
+    kind: string,
+    from: number,
+    to: number,
+    fn: MigrationFn<TIn, TOut>,
+  ): void {
+    if (to <= from) {
+      throw new Error(`migration target version (${to}) must be greater than source (${from})`);
+    }
+    const list = this.#byKind.get(kind) ?? [];
+    list.push({ from, to, fn: fn as MigrationFn });
+    list.sort((a, b) => a.from - b.from);
+    this.#byKind.set(kind, list);
+  }
+
+  latestVersion(kind: string): number | null {
+    const list = this.#byKind.get(kind);
+    if (!list || list.length === 0) return null;
+    return Math.max(...list.map(m => m.to));
+  }
+
+  async migrate(kind: string, fromVersion: number, data: unknown): Promise<unknown> {
+    const target = this.latestVersion(kind);
+    if (target == null || fromVersion >= target) return data;
+    const list = this.#byKind.get(kind)!;
+    let current = fromVersion;
+    let value = data;
+    while (current < target) {
+      const next = list.find(m => m.from === current);
+      if (!next) throw new Error(`no migration from version ${current} to ${current + 1} for kind ${kind}`);
+      value = await next.fn(value);
+      current = next.to;
+    }
+    return value;
+  }
+}

package/packages/coworker-utils/src/ndjson-channel.test.ts

@@ -0,0 +1,76 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { Readable, Writable } from 'node:stream';
+import { writeNdjson, readNdjson } from './ndjson-channel.js';
+
+function makeReader(chunks: string[]): Readable {
+  let i = 0;
+  return new Readable({
+    read() {
+      if (i >= chunks.length) { this.push(null); return; }
+      this.push(chunks[i++], 'utf8');
+    },
+  });
+}
+
+function makeWriter(): { stream: Writable; written: () => string } {
+  const buf: string[] = [];
+  const stream = new Writable({
+    write(chunk, _enc, cb) { buf.push(chunk.toString('utf8')); cb(); },
+  });
+  return { stream, written: () => buf.join('') };
+}
+
+describe('ndjson channel', () => {
+  it('writes one object per line with \\n terminator', async () => {
+    const { stream, written } = makeWriter();
+    await writeNdjson(stream, { type: 'ready' });
+    await writeNdjson(stream, { type: 'exec', cell_id: 'c1' });
+    assert.equal(written(), '{"type":"ready"}\n{"type":"exec","cell_id":"c1"}\n');
+  });
+
+  it('reads one object per yielded value', async () => {
+    const reader = makeReader([
+      '{"type":"ready"}\n{"type":"result","cell_id":"c1"}\n',
+    ]);
+    const got: Array<Record<string, unknown>> = [];
+    for await (const msg of readNdjson(reader)) {
+      got.push(msg as Record<string, unknown>);
+    }
+    assert.equal(got.length, 2);
+    assert.equal(got[0].type, 'ready');
+    assert.equal(got[1].type, 'result');
+  });
+
+  it('handles JSON object split across read chunks', async () => {
+    const reader = makeReader([
+      '{"type":"re',
+      'ady","extra":"long string"}\n',
+    ]);
+    const got: Array<Record<string, unknown>> = [];
+    for await (const msg of readNdjson(reader)) {
+      got.push(msg as Record<string, unknown>);
+    }
+    assert.equal(got.length, 1);
+    assert.equal(got[0].type, 'ready');
+    assert.equal(got[0].extra, 'long string');
+  });
+
+  it('skips empty lines silently', async () => {
+    const reader = makeReader(['\n\n{"a":1}\n\n{"b":2}\n']);
+    const got: Array<Record<string, unknown>> = [];
+    for await (const msg of readNdjson(reader)) {
+      got.push(msg as Record<string, unknown>);
+    }
+    assert.equal(got.length, 2);
+    assert.equal(got[0].a, 1);
+    assert.equal(got[1].b, 2);
+  });
+
+  it('throws on malformed JSON with line number', async () => {
+    const reader = makeReader(['{"ok":1}\n{not json\n']);
+    await assert.rejects(async () => {
+      for await (const _ of readNdjson(reader)) { /* drain */ }
+    }, /line 2/);
+  });
+});

package/packages/coworker-utils/src/ndjson-channel.ts

@@ -0,0 +1,41 @@
+// NDJSON channel — one JSON object per line over Node streams.
+// Used by scratchpad <-> kernel subprocess and other inter-process channels.
+// Spec §6.3.
+import type { Readable, Writable } from 'node:stream';
+
+export async function writeNdjson(stream: Writable, message: unknown): Promise<void> {
+  const line = JSON.stringify(message) + '\n';
+  await new Promise<void>((resolve, reject) => {
+    stream.write(line, 'utf8', (err) => (err ? reject(err) : resolve()));
+  });
+}
+
+export async function* readNdjson(stream: Readable): AsyncGenerator<unknown> {
+  stream.setEncoding('utf8');
+  let buffer = '';
+  let lineNumber = 0;
+  for await (const chunk of stream) {
+    buffer += chunk;
+    let idx: number;
+    while ((idx = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 1);
+      lineNumber++;
+      if (line.length === 0) continue;
+      try {
+        yield JSON.parse(line);
+      } catch (err) {
+        throw new Error(`NDJSON parse error at line ${lineNumber}: ${(err as Error).message}`);
+      }
+    }
+  }
+  // Tail (no trailing newline)
+  if (buffer.length > 0) {
+    lineNumber++;
+    try {
+      yield JSON.parse(buffer);
+    } catch (err) {
+      throw new Error(`NDJSON parse error at line ${lineNumber}: ${(err as Error).message}`);
+    }
+  }
+}

package/packages/coworker-utils/src/secret-scanner.test.ts

@@ -0,0 +1,61 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { SecretScanner } from './secret-scanner.js';
+
+describe('SecretScanner', () => {
+  const scanner = new SecretScanner();
+
+  it('detects an Anthropic key pattern', () => {
+    const text = 'My key is sk-ant-api03-aaaabbbbccccddddeeeeffffgggghhhh111122223333AAA-BBBBCCCC';
+    const hits = scanner.scan(text);
+    assert.equal(hits.length, 1);
+    assert.equal(hits[0].kind, 'anthropic_api_key');
+  });
+
+  it('detects an OpenAI sk- key', () => {
+    const text = 'openai key: sk-proj-AAAAaaaaBBBBccccDDDDeeeeFFFFggggHHHHiiiiJJJJkkkkLLLL';
+    const hits = scanner.scan(text);
+    assert.equal(hits.length, 1);
+    assert.equal(hits[0].kind, 'openai_api_key');
+  });
+
+  it('detects an AWS access key id', () => {
+    const text = 'AKIAIOSFODNN7EXAMPLE was leaked';
+    const hits = scanner.scan(text);
+    assert.equal(hits.length, 1);
+    assert.equal(hits[0].kind, 'aws_access_key_id');
+  });
+
+  it('detects a GitHub PAT', () => {
+    const text = 'token: ghp_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ';
+    const hits = scanner.scan(text);
+    assert.equal(hits.length, 1);
+    assert.equal(hits[0].kind, 'github_pat');
+  });
+
+  it('does not flag generic English text', () => {
+    const text = 'The server had multiple alerts and we restarted it twice.';
+    const hits = scanner.scan(text);
+    assert.equal(hits.length, 0);
+  });
+
+  it('redact replaces detected secrets with [REDACTED:<kind>]', () => {
+    const text = 'My key is sk-ant-api03-aaaabbbbccccddddeeeeffffgggghhhh111122223333AAA-BBBBCCCC and a note.';
+    const redacted = scanner.redact(text);
+    assert.match(redacted, /\[REDACTED:anthropic_api_key\]/);
+    assert.match(redacted, /and a note\.$/);
+  });
+
+  it('returns multiple hits when multiple secrets present', () => {
+    const text = 'sk-ant-api03-aaaabbbbccccddddeeeeffffgggghhhh111122223333AAA-BBBBCCCC AKIAIOSFODNN7EXAMPLE';
+    const hits = scanner.scan(text);
+    assert.equal(hits.length, 2);
+  });
+
+  it('records hit positions (start, end) in the original text', () => {
+    const text = '----AKIAIOSFODNN7EXAMPLE----';
+    const hits = scanner.scan(text);
+    assert.equal(hits[0].start, 4);
+    assert.equal(hits[0].end, 24);
+  });
+});

package/packages/coworker-utils/src/secret-scanner.ts

@@ -0,0 +1,56 @@
+// SecretScanner — stub gate before any disk write to memory layers A/B.
+// Spec §6.5.
+
+export interface SecretHit {
+  kind: string;
+  start: number;
+  end: number;
+  preview: string;        // first 8 chars + "..." — for audit logs (never the full secret)
+}
+
+interface Pattern {
+  kind: string;
+  regex: RegExp;
+}
+
+// Patterns are intentionally conservative — false negatives are OK in v1; false positives in
+// memory are a real cost (user lessons get over-redacted). Tighten or extend as Phase 3 reveals
+// real-world content.
+const PATTERNS: Pattern[] = [
+  { kind: 'anthropic_api_key', regex: /sk-ant-api03-[A-Za-z0-9_-]{40,}/g },
+  { kind: 'openai_api_key',    regex: /sk-(?:proj-)?[A-Za-z0-9]{40,}/g },
+  { kind: 'aws_access_key_id', regex: /AKIA[0-9A-Z]{16}/g },
+  { kind: 'github_pat',        regex: /gh[pous]_[A-Za-z0-9]{36,}/g },
+];
+
+export class SecretScanner {
+  scan(text: string): SecretHit[] {
+    const hits: SecretHit[] = [];
+    for (const { kind, regex } of PATTERNS) {
+      regex.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = regex.exec(text)) != null) {
+        hits.push({
+          kind,
+          start: m.index,
+          end: m.index + m[0].length,
+          preview: m[0].slice(0, 8) + '...',
+        });
+      }
+    }
+    return hits.sort((a, b) => a.start - b.start);
+  }
+
+  redact(text: string): string {
+    const hits = this.scan(text);
+    if (hits.length === 0) return text;
+    let out = '';
+    let cursor = 0;
+    for (const h of hits) {
+      out += text.slice(cursor, h.start) + `[REDACTED:${h.kind}]`;
+      cursor = h.end;
+    }
+    out += text.slice(cursor);
+    return out;
+  }
+}

package/packages/coworker-utils/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}

package/packages/coworker-utils/tsconfig.publish.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "incremental": false }
+}

package/packages/coworker-vault/dist/data-vault.d.ts

@@ -0,0 +1,41 @@
+import { AuditLog } from '@otto/coworker-utils';
+import type { EntryRef, VaultEntry, VaultScope } from './types.js';
+export interface LocalDataVaultOptions {
+    globalDir: string;
+    workspaceDir?: string;
+    audit: AuditLog;
+    now?: () => string;
+}
+export interface ListedEntry {
+    engine: string;
+    name: string;
+    scope: VaultScope;
+    fields_set: string[];
+    last_modified_at: string;
+}
+export declare class LocalDataVault {
+    private readonly globalRoot;
+    private readonly workspaceRoot?;
+    private readonly audit;
+    private readonly now;
+    constructor(opts: LocalDataVaultOptions);
+    static parseRef(input: string): EntryRef;
+    static formatRef(ref: EntryRef): string;
+    private globalVaultDir;
+    private workspaceVaultDir;
+    private fileNameFor;
+    private resolveScope;
+    private writeScope;
+    set(ref: EntryRef, fields: Record<string, string>, opts?: {
+        forceWorkspace?: boolean;
+    }): Promise<void>;
+    get(ref: EntryRef): Promise<VaultEntry>;
+    remove(ref: EntryRef): Promise<void>;
+    lookupLastModified(refStr: string): Promise<string | null>;
+    private sidecarPathFor;
+    private readSidecar;
+    private writeSidecar;
+    list(): Promise<ListedEntry[]>;
+    private readEntry;
+    private sweepOrphans;
+}