@fixy/core 0.0.0

package/src/__tests__/worktree.test.ts

@@ -0,0 +1,155 @@
+// packages/core/src/__tests__/worktree.test.ts
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, writeFile, access } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { WorktreeManager } from '../worktree.js';
+import type { WorktreeHandle } from '../worktree.js';
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Setup / teardown
+// ---------------------------------------------------------------------------
+
+let tempDir: string;
+let projectRoot: string;
+let manager: WorktreeManager;
+const THREAD_ID = 'test-thread-001';
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'fixy-wt-test-'));
+  process.env['FIXY_HOME'] = join(tempDir, 'fixy-home');
+
+  // Create a real git repo as fixture
+  projectRoot = join(tempDir, 'repo');
+  await execFileAsync('mkdir', ['-p', projectRoot]);
+  await execFileAsync('git', ['init'], { cwd: projectRoot });
+  await execFileAsync('git', ['config', 'user.email', 'test@test.com'], { cwd: projectRoot });
+  await execFileAsync('git', ['config', 'user.name', 'Test'], { cwd: projectRoot });
+  // Need at least one commit for worktrees
+  await writeFile(join(projectRoot, 'README.md'), '# Test\n');
+  await execFileAsync('git', ['add', '.'], { cwd: projectRoot });
+  await execFileAsync('git', ['commit', '-m', 'init'], { cwd: projectRoot });
+
+  manager = new WorktreeManager();
+});
+
+afterEach(async () => {
+  delete process.env['FIXY_HOME'];
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('WorktreeManager', { timeout: 15000 }, () => {
+  it('ensure() creates a worktree with correct handle fields', async () => {
+    const handle: WorktreeHandle = await manager.ensure(projectRoot, THREAD_ID, 'claude');
+
+    // Shape
+    expect(handle.agentId).toBe('claude');
+    expect(handle.threadId).toBe(THREAD_ID);
+    expect(handle.branch).toBe('fixy/test-thread-001-claude');
+    expect(handle.path).toContain('test-thread-001');
+    expect(handle.path).toContain('claude');
+
+    // Directory actually exists on disk
+    await expect(access(handle.path)).resolves.toBeUndefined();
+
+    // git worktree list shows the path
+    const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain'], {
+      cwd: projectRoot,
+    });
+    expect(stdout).toContain(handle.path);
+  });
+
+  it('ensure() is idempotent — second call returns same handle, no error', async () => {
+    const handle1 = await manager.ensure(projectRoot, THREAD_ID, 'claude');
+    const handle2 = await manager.ensure(projectRoot, THREAD_ID, 'claude');
+
+    expect(handle2.path).toBe(handle1.path);
+    expect(handle2.branch).toBe(handle1.branch);
+    expect(handle2.agentId).toBe(handle1.agentId);
+    expect(handle2.threadId).toBe(handle1.threadId);
+  });
+
+  it('collectPatches() returns patches for modified tracked files', async () => {
+    const handle = await manager.ensure(projectRoot, THREAD_ID, 'claude');
+
+    // README.md was tracked from the init commit and is present in the worktree
+    await writeFile(join(handle.path, 'README.md'), '# Test\n\nAdded a line.\n');
+
+    const patches = await manager.collectPatches(handle);
+
+    expect(patches).toHaveLength(1);
+    expect(patches[0].relativePath).toBe('README.md');
+    // One line added
+    expect(patches[0].stats.additions).toBeGreaterThanOrEqual(1);
+    // Original line counted as deletion since it was replaced
+    expect(patches[0].stats.deletions).toBeGreaterThanOrEqual(0);
+    expect(patches[0].diff).toContain('diff --git');
+  });
+
+  it('collectPatches() returns empty array on clean worktree', async () => {
+    const handle = await manager.ensure(projectRoot, THREAD_ID, 'claude');
+
+    const patches = await manager.collectPatches(handle);
+
+    expect(patches).toEqual([]);
+  });
+
+  it('reset() re-provisions a clean worktree', async () => {
+    const handle = await manager.ensure(projectRoot, THREAD_ID, 'claude');
+
+    // Dirty the worktree
+    await writeFile(join(handle.path, 'README.md'), '# Dirty\n');
+
+    await manager.reset(handle, projectRoot);
+
+    // The same path should exist again (re-provisioned)
+    await expect(access(handle.path)).resolves.toBeUndefined();
+
+    // collectPatches on the fresh handle should be empty
+    const freshHandle = await manager.ensure(projectRoot, THREAD_ID, 'claude');
+    const patches = await manager.collectPatches(freshHandle);
+    expect(patches).toEqual([]);
+  });
+
+  it('remove() permanently removes the worktree directory and its branch', async () => {
+    const handle = await manager.ensure(projectRoot, THREAD_ID, 'claude');
+
+    await manager.remove(handle, projectRoot);
+
+    // Directory no longer exists
+    await expect(access(handle.path)).rejects.toThrow();
+
+    // Branch is deleted
+    const { stdout } = await execFileAsync('git', ['branch', '--list', handle.branch], {
+      cwd: projectRoot,
+    });
+    expect(stdout.trim()).toBe('');
+  });
+
+  it('list() returns all worktrees registered for a thread', async () => {
+    await manager.ensure(projectRoot, THREAD_ID, 'claude');
+    await manager.ensure(projectRoot, THREAD_ID, 'codex');
+
+    const handles = await manager.list(THREAD_ID);
+
+    expect(handles).toHaveLength(2);
+    const agentIds = handles.map((h) => h.agentId);
+    expect(agentIds).toContain('claude');
+    expect(agentIds).toContain('codex');
+
+    // All handles should report the correct threadId
+    for (const h of handles) {
+      expect(h.threadId).toBe(THREAD_ID);
+    }
+  });
+});

package/src/adapter.ts

@@ -0,0 +1,84 @@
+// packages/core/src/adapter.ts
+
+import type { FixyMessage, FixyPatch } from './thread.js';
+
+export interface FixyAgent {
+  /** Stable handle without '@', e.g. "claude", "codex". */
+  id: string;
+  /** Display name shown in the terminal. */
+  name: string;
+}
+
+export interface FixyThreadContext {
+  threadId: string;
+  projectRoot: string; // absolute path to the git repo the thread lives in
+  worktreePath: string; // absolute path to the (thread, agent) worktree
+  repoRef: string | null; // branch or commit the worktree was created from
+}
+
+export interface FixyExecutionContext {
+  runId: string; // unique per adapter invocation
+  agent: FixyAgent; // which adapter is being invoked
+  threadContext: FixyThreadContext;
+  /** Full normalized message history Fixy decided to send this turn. */
+  messages: FixyMessage[];
+  /** Fresh user input for this turn, already stripped of the @mention prefix. */
+  prompt: string;
+  /** Opaque adapter-owned state from the previous turn in this thread. */
+  session: FixySession | null;
+  /** Streamed stdout/stderr chunks. Adapters MUST call this. */
+  onLog: (stream: 'stdout' | 'stderr', chunk: string) => void;
+  /** Called once with the resolved command + args + env for transcript/logging. */
+  onMeta: (meta: FixyInvocationMeta) => void;
+  /** Called with the child pid the moment the process spawns. */
+  onSpawn: (pid: number) => void;
+  /** Abort signal propagated from `/reset` and Ctrl-C. */
+  signal: AbortSignal;
+}
+
+export interface FixyExecutionResult {
+  exitCode: number | null;
+  signal: string | null;
+  timedOut: boolean;
+  /** Human-readable summary the router appends to the thread. */
+  summary: string;
+  /** Opaque per-adapter state to persist for the next turn (e.g. Claude session id). */
+  session: FixySession | null;
+  /** Any patches/diffs the adapter produced, keyed by file path. */
+  patches: FixyPatch[];
+  /** Non-fatal warnings shown to the user after the turn completes. */
+  warnings: string[];
+  errorMessage: string | null;
+}
+
+export interface FixySession {
+  /** Adapter-native session id, e.g. Claude `--resume` id or Codex thread id. */
+  sessionId: string;
+  /** Any adapter-specific params needed to resume. Must be JSON-serializable. */
+  params: Record<string, unknown>;
+}
+
+export interface FixyInvocationMeta {
+  resolvedCommand: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string>; // already redacted of secrets by the adapter
+}
+
+export interface FixyAdapter {
+  /** Stable id, matches the mention handle without '@'. */
+  readonly id: string;
+  /** Human-readable name for `/status`. */
+  readonly name: string;
+  /** Verify the CLI is installed and the user's auth is valid. */
+  probe(): Promise<FixyProbeResult>;
+  /** Run one turn. Must honor `ctx.signal`. */
+  execute(ctx: FixyExecutionContext): Promise<FixyExecutionResult>;
+}
+
+export interface FixyProbeResult {
+  available: boolean;
+  version: string | null;
+  authStatus: 'ok' | 'needs_login' | 'unknown';
+  detail: string | null;
+}

package/src/diff-parser.ts

@@ -0,0 +1,46 @@
+// packages/core/src/diff-parser.ts
+import { join } from 'node:path';
+import type { FixyPatch } from './thread.js';
+
+export function parseUnifiedDiff(diffOutput: string, worktreePath: string): FixyPatch[] {
+  if (!diffOutput || !diffOutput.trim()) {
+    return [];
+  }
+
+  // Split on diff --git boundaries using lookahead to keep the delimiter with each segment
+  const segments = diffOutput.split(/(?=^diff --git )/m).filter((segment) => segment.trim());
+
+  const patches: FixyPatch[] = [];
+
+  for (const segment of segments) {
+    // Extract file path from the diff --git header line (b/ side)
+    const headerMatch = /^diff --git a\/.+ b\/(.+)$/m.exec(segment);
+    if (!headerMatch) {
+      continue;
+    }
+
+    const relativePath = headerMatch[1].trim();
+    const filePath = join(worktreePath, relativePath);
+
+    let additions = 0;
+    let deletions = 0;
+
+    const lines = segment.split('\n');
+    for (const line of lines) {
+      if (line.startsWith('+') && !line.startsWith('+++')) {
+        additions++;
+      } else if (line.startsWith('-') && !line.startsWith('---')) {
+        deletions++;
+      }
+    }
+
+    patches.push({
+      filePath,
+      relativePath,
+      diff: segment,
+      stats: { additions, deletions },
+    });
+  }
+
+  return patches;
+}

package/src/fixy-commands.ts

@@ -0,0 +1,201 @@
+import { randomUUID } from 'node:crypto';
+import { rename, writeFile } from 'node:fs/promises';
+
+import type { FixyExecutionContext } from './adapter.js';
+import type { AdapterRegistry } from './registry.js';
+import type { LocalThreadStore } from './store.js';
+import type { FixyMessage, FixyThread } from './thread.js';
+import type { WorktreeManager } from './worktree.js';
+import { getThreadFile } from './paths.js';
+
+export interface FixyCommandContext {
+  thread: FixyThread;
+  rest: string;
+  store: LocalThreadStore;
+  registry: AdapterRegistry;
+  worktreeManager: WorktreeManager;
+  onLog: (stream: 'stdout' | 'stderr', chunk: string) => void;
+  signal: AbortSignal;
+}
+
+export class FixyCommandRunner {
+  async run(ctx: FixyCommandContext): Promise<void> {
+    const { rest } = ctx;
+
+    if (!rest.startsWith('/')) {
+      await this._handleBare(rest, ctx);
+      return;
+    }
+
+    const spaceIdx = rest.indexOf(' ');
+    const command = spaceIdx === -1 ? rest : rest.slice(0, spaceIdx);
+    const args = spaceIdx === -1 ? '' : rest.slice(spaceIdx + 1).trim();
+
+    switch (command) {
+      case '/worker':
+        await this._handleWorker(args, ctx);
+        break;
+      case '/all':
+        await this._handleAll(ctx);
+        break;
+      case '/settings':
+        await this._handleSettings(ctx);
+        break;
+      case '/reset':
+        await this._handleReset(ctx);
+        break;
+      case '/status':
+        await this._handleStatus(ctx);
+        break;
+      default:
+        await this._appendSystemMessage(`unknown command: ${command}`, ctx);
+    }
+  }
+
+  private async _handleWorker(adapterId: string, ctx: FixyCommandContext): Promise<void> {
+    ctx.registry.require(adapterId);
+
+    const fresh = await ctx.store.getThread(ctx.thread.id, ctx.thread.projectRoot);
+    fresh.workerModel = adapterId;
+    fresh.updatedAt = new Date().toISOString();
+
+    const sysMsg: FixyMessage = {
+      id: randomUUID(),
+      createdAt: new Date().toISOString(),
+      role: 'system',
+      agentId: null,
+      content: `worker set to ${adapterId}`,
+      runId: null,
+      dispatchedTo: [],
+      patches: [],
+      warnings: [],
+    };
+    fresh.messages.push(sysMsg);
+
+    await this._persistThread(fresh);
+    ctx.thread.workerModel = adapterId;
+  }
+
+  private async _handleAll(ctx: FixyCommandContext): Promise<void> {
+    await this._appendSystemMessage(
+      'collaboration engine not yet implemented — arriving in Step 12',
+      ctx,
+    );
+  }
+
+  private async _handleSettings(ctx: FixyCommandContext): Promise<void> {
+    await this._appendSystemMessage('settings command not yet implemented', ctx);
+  }
+
+  private async _handleReset(ctx: FixyCommandContext): Promise<void> {
+    ctx.thread.agentSessions = {};
+
+    for (const [agentId, worktreePath] of Object.entries(ctx.thread.worktrees)) {
+      const handle = {
+        path: worktreePath,
+        branch: `fixy/${ctx.thread.id}-${agentId}`,
+        agentId,
+        threadId: ctx.thread.id,
+      };
+      await ctx.worktreeManager.reset(handle, ctx.thread.projectRoot);
+    }
+
+    const fresh = await ctx.store.getThread(ctx.thread.id, ctx.thread.projectRoot);
+    fresh.agentSessions = {};
+    fresh.updatedAt = new Date().toISOString();
+    await this._persistThread(fresh);
+
+    await this._appendSystemMessage(
+      'thread reset — all agent sessions cleared, worktrees re-provisioned',
+      ctx,
+    );
+  }
+
+  private async _handleStatus(ctx: FixyCommandContext): Promise<void> {
+    const adapters = ctx.registry.list();
+    const lines: string[] = [`worker: ${ctx.thread.workerModel}`, ''];
+
+    for (const adapter of adapters) {
+      const probe = await adapter.probe();
+      const session = ctx.thread.agentSessions[adapter.id];
+      const sessionId = session ? session.sessionId : 'none';
+
+      lines.push(`adapter: ${adapter.id}`);
+      lines.push(`  name: ${adapter.name}`);
+      lines.push(`  available: ${probe.available ? 'yes' : 'no'}`);
+      lines.push(`  version: ${probe.version ?? 'unknown'}`);
+      lines.push(`  auth: ${probe.authStatus}`);
+      lines.push(`  session: ${sessionId}`);
+      if (probe.detail) {
+        lines.push(`  detail: ${probe.detail}`);
+      }
+      lines.push('');
+    }
+
+    await this._appendSystemMessage(lines.join('\n').trimEnd(), ctx);
+  }
+
+  private async _handleBare(prompt: string, ctx: FixyCommandContext): Promise<void> {
+    const { thread } = ctx;
+    const adapter = ctx.registry.require(thread.workerModel);
+    const runId = randomUUID();
+
+    const execCtx: FixyExecutionContext = {
+      runId,
+      agent: { id: adapter.id, name: adapter.name },
+      threadContext: {
+        threadId: thread.id,
+        projectRoot: thread.projectRoot,
+        worktreePath: thread.projectRoot,
+        repoRef: null,
+      },
+      messages: thread.messages,
+      prompt,
+      session: thread.agentSessions[thread.workerModel] ?? null,
+      onLog: ctx.onLog,
+      onMeta: () => {},
+      onSpawn: () => {},
+      signal: ctx.signal,
+    };
+
+    const result = await adapter.execute(execCtx);
+
+    thread.agentSessions[thread.workerModel] = result.session;
+
+    const agentMsg: FixyMessage = {
+      id: randomUUID(),
+      createdAt: new Date().toISOString(),
+      role: 'agent',
+      agentId: 'fixy',
+      content: result.summary,
+      runId,
+      dispatchedTo: [],
+      patches: result.patches,
+      warnings: result.warnings,
+    };
+
+    await ctx.store.appendMessage(thread.id, thread.projectRoot, agentMsg);
+  }
+
+  private async _persistThread(thread: FixyThread): Promise<void> {
+    const filePath = getThreadFile(thread.projectRoot, thread.id);
+    const tmpPath = `${filePath}.tmp`;
+    await writeFile(tmpPath, JSON.stringify(thread, null, 2), 'utf8');
+    await rename(tmpPath, filePath);
+  }
+
+  private async _appendSystemMessage(content: string, ctx: FixyCommandContext): Promise<void> {
+    const msg: FixyMessage = {
+      id: randomUUID(),
+      createdAt: new Date().toISOString(),
+      role: 'system',
+      agentId: null,
+      content,
+      runId: null,
+      dispatchedTo: [],
+      patches: [],
+      warnings: [],
+    };
+    await ctx.store.appendMessage(ctx.thread.id, ctx.thread.projectRoot, msg);
+  }
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+export type { FixyRole, FixyThread, FixyMessage, FixyPatch } from './thread.js';
+
+export type {
+  FixyAgent,
+  FixyThreadContext,
+  FixyExecutionContext,
+  FixyExecutionResult,
+  FixySession,
+  FixyInvocationMeta,
+  FixyAdapter,
+  FixyProbeResult,
+} from './adapter.js';
+
+export {
+  getFixyHome,
+  getConfigPath,
+  computeProjectId,
+  getProjectDir,
+  getProjectFile,
+  getThreadsDir,
+  getThreadFile,
+  getWorktreesDir,
+} from './paths.js';
+
+export { LocalThreadStore } from './store.js';
+
+export { AdapterRegistry } from './registry.js';
+
+export { Router } from './router.js';
+export type { ParsedInput } from './router.js';
+
+export { TurnController } from './turn.js';
+export type { TurnParams } from './turn.js';
+
+export { WorktreeManager } from './worktree.js';
+export type { WorktreeHandle } from './worktree.js';
+export { parseUnifiedDiff } from './diff-parser.js';
+
+export { FixyCommandRunner } from './fixy-commands.js';
+export type { FixyCommandContext } from './fixy-commands.js';

package/src/paths.ts

@@ -0,0 +1,43 @@
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Returns the Fixy home directory. Respects FIXY_HOME env var for testing. */
+export function getFixyHome(): string {
+  return process.env['FIXY_HOME'] ?? join(homedir(), '.fixy');
+}
+
+/** Returns the path to the global config file. */
+export function getConfigPath(): string {
+  return join(getFixyHome(), 'config.json');
+}
+
+/** Computes the project id (sha1 hex digest of the absolute projectRoot). */
+export function computeProjectId(projectRoot: string): string {
+  return createHash('sha1').update(projectRoot).digest('hex');
+}
+
+/** Returns the project directory for a given projectRoot. */
+export function getProjectDir(projectRoot: string): string {
+  return join(getFixyHome(), 'projects', computeProjectId(projectRoot));
+}
+
+/** Returns the project.json path for a given projectRoot. */
+export function getProjectFile(projectRoot: string): string {
+  return join(getProjectDir(projectRoot), 'project.json');
+}
+
+/** Returns the threads directory for a given projectRoot. */
+export function getThreadsDir(projectRoot: string): string {
+  return join(getProjectDir(projectRoot), 'threads');
+}
+
+/** Returns the full path to a thread JSON file. */
+export function getThreadFile(projectRoot: string, threadId: string): string {
+  return join(getThreadsDir(projectRoot), `${threadId}.json`);
+}
+
+/** Returns the worktrees directory for a given threadId. */
+export function getWorktreesDir(threadId: string): string {
+  return join(getFixyHome(), 'worktrees', threadId);
+}

package/src/registry.ts

@@ -0,0 +1,40 @@
+import type { FixyAdapter } from './adapter.js';
+
+export class AdapterRegistry {
+  private readonly adapters = new Map<string, FixyAdapter>();
+
+  register(adapter: FixyAdapter): void {
+    if (this.adapters.has(adapter.id)) {
+      throw new Error(`Adapter already registered: ${adapter.id}`);
+    }
+    this.adapters.set(adapter.id, adapter);
+  }
+
+  unregister(id: string): void {
+    this.adapters.delete(id);
+  }
+
+  require(id: string): FixyAdapter {
+    const adapter = this.adapters.get(id);
+    if (adapter === undefined) {
+      throw new Error(`Unknown adapter: ${id}`);
+    }
+    return adapter;
+  }
+
+  get(id: string): FixyAdapter | undefined {
+    return this.adapters.get(id);
+  }
+
+  list(): FixyAdapter[] {
+    return Array.from(this.adapters.values());
+  }
+
+  has(id: string): boolean {
+    return this.adapters.has(id);
+  }
+
+  clear(): void {
+    this.adapters.clear();
+  }
+}

package/src/router.ts

@@ -0,0 +1,49 @@
+// packages/core/src/router.ts
+
+import type { AdapterRegistry } from './registry.js';
+
+export type ParsedInput =
+  | { kind: 'mention'; agentIds: string[]; body: string }
+  | { kind: 'fixy'; rest: string }
+  | { kind: 'bare'; body: string }
+  | { kind: 'error'; reason: string };
+
+const MENTION_RE = /^@(\w+)/;
+
+export class Router {
+  constructor(private readonly registry: AdapterRegistry) {}
+
+  parse(input: string): ParsedInput {
+    if (!input.startsWith('@')) {
+      return { kind: 'bare', body: input };
+    }
+
+    const tokens: string[] = [];
+    let remaining = input;
+
+    while (remaining.startsWith('@')) {
+      const match = MENTION_RE.exec(remaining);
+      if (!match) break;
+
+      // @fixy as first token: everything after it is the rest
+      if (tokens.length === 0 && match[1] === 'fixy') {
+        return { kind: 'fixy', rest: remaining.slice(match[0].length).trimStart() };
+      }
+
+      tokens.push(match[1]);
+      remaining = remaining.slice(match[0].length).trimStart();
+    }
+
+    if (tokens.length === 0) {
+      return { kind: 'bare', body: input };
+    }
+
+    for (const token of tokens) {
+      if (!this.registry.has(token)) {
+        return { kind: 'error', reason: `unknown agent: @${token}` };
+      }
+    }
+
+    return { kind: 'mention', agentIds: tokens, body: remaining };
+  }
+}