@fixy/core 0.0.0

package/src/store.ts

@@ -0,0 +1,164 @@
+// packages/core/src/store.ts
+
+import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+
+import type { FixyMessage, FixyThread } from './thread.js';
+import {
+  computeProjectId,
+  getFixyHome,
+  getProjectFile,
+  getThreadFile,
+  getThreadsDir,
+} from './paths.js';
+
+export class LocalThreadStore {
+  /**
+   * Ensures the top-level `projects/` and `worktrees/` directories exist
+   * under the Fixy home directory.
+   */
+  async init(): Promise<void> {
+    const home = getFixyHome();
+    await Promise.all([
+      mkdir(join(home, 'projects'), { recursive: true }),
+      mkdir(join(home, 'worktrees'), { recursive: true }),
+    ]);
+  }
+
+  /**
+   * Creates a new thread for the given project root, persisting it to disk.
+   * Writes project.json if it does not already exist.
+   */
+  async createThread(projectRoot: string): Promise<FixyThread> {
+    const id = randomUUID();
+    const projectId = computeProjectId(projectRoot);
+    const now = new Date().toISOString();
+
+    // Ensure project and threads directories exist.
+    await mkdir(getThreadsDir(projectRoot), { recursive: true });
+
+    // Write project.json only if it doesn't already exist (flag 'wx').
+    const projectFile = getProjectFile(projectRoot);
+    try {
+      await writeFile(
+        projectFile,
+        JSON.stringify({ projectId, projectRoot, createdAt: now }, null, 2),
+        { flag: 'wx' },
+      );
+    } catch (err) {
+      // EEXIST means the file already exists — that's fine.
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') {
+        throw err;
+      }
+    }
+
+    const thread: FixyThread = {
+      id,
+      projectId,
+      projectRoot,
+      createdAt: now,
+      updatedAt: now,
+      title: null,
+      status: 'active',
+      workerModel: 'claude',
+      agentSessions: {},
+      worktrees: {},
+      messages: [],
+    };
+
+    await this._writeAtomic(getThreadFile(projectRoot, id), thread);
+
+    return thread;
+  }
+
+  /**
+   * Appends a message to an existing thread and persists the update.
+   * Throws if the thread does not exist.
+   */
+  async appendMessage(
+    threadId: string,
+    projectRoot: string,
+    message: FixyMessage,
+  ): Promise<FixyThread> {
+    const thread = await this.getThread(threadId, projectRoot);
+
+    thread.messages.push(message);
+    thread.updatedAt = new Date().toISOString();
+
+    await this._writeAtomic(getThreadFile(projectRoot, threadId), thread);
+
+    return thread;
+  }
+
+  /**
+   * Reads and returns a single thread by id.
+   * Throws if the thread file does not exist.
+   */
+  async getThread(threadId: string, projectRoot: string): Promise<FixyThread> {
+    const threadPath = getThreadFile(projectRoot, threadId);
+    try {
+      const raw = await readFile(threadPath, 'utf8');
+      return JSON.parse(raw) as FixyThread;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        throw new Error(`Thread not found: ${threadId}`, { cause: err });
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Returns all threads for the given project root.
+   * Returns an empty array if the threads directory does not exist yet.
+   */
+  async listThreads(projectRoot: string): Promise<FixyThread[]> {
+    const threadsDir = getThreadsDir(projectRoot);
+    let entries: string[];
+    try {
+      entries = await readdir(threadsDir);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        return [];
+      }
+      throw err;
+    }
+
+    const jsonFiles = entries.filter((f) => f.endsWith('.json') && !f.endsWith('.tmp'));
+
+    const threads = await Promise.all(
+      jsonFiles.map(async (file) => {
+        const raw = await readFile(join(threadsDir, file), 'utf8');
+        return JSON.parse(raw) as FixyThread;
+      }),
+    );
+
+    return threads;
+  }
+
+  /**
+   * Sets the thread status to "archived" and persists the change.
+   * Throws if the thread does not exist.
+   */
+  async archiveThread(threadId: string, projectRoot: string): Promise<FixyThread> {
+    const thread = await this.getThread(threadId, projectRoot);
+
+    thread.status = 'archived';
+    thread.updatedAt = new Date().toISOString();
+
+    await this._writeAtomic(getThreadFile(projectRoot, threadId), thread);
+
+    return thread;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /** Atomically writes an object as formatted JSON: write to *.tmp, then rename. */
+  private async _writeAtomic(destPath: string, data: unknown): Promise<void> {
+    const tmpPath = `${destPath}.tmp`;
+    await writeFile(tmpPath, JSON.stringify(data, null, 2), 'utf8');
+    await rename(tmpPath, destPath);
+  }
+}

package/src/thread.ts

@@ -0,0 +1,50 @@
+// packages/core/src/thread.ts
+
+import type { FixySession } from './adapter.js';
+
+export type FixyRole = 'user' | 'agent' | 'system';
+
+export interface FixyThread {
+  id: string; // uuid v7
+  projectId: string; // sha1 of projectRoot
+  projectRoot: string; // absolute path
+  createdAt: string; // ISO 8601
+  updatedAt: string; // ISO 8601
+  title: string | null; // user-editable, null until first message
+  status: 'active' | 'archived';
+  workerModel: string; // current @fixy worker adapter id, e.g. "claude"
+  agentSessions: Record<string, FixySession | null>; // per-adapter resume state
+  worktrees: Record<string, string>; // agentId → absolute worktree path
+  messages: FixyMessage[];
+}
+
+export interface FixyMessage {
+  id: string; // uuid v7, monotonic by createdAt
+  createdAt: string; // ISO 8601
+  role: FixyRole;
+  /** For role=agent, the adapter id that produced this message. */
+  agentId: string | null;
+  /** The raw user input or agent summary. Streamed chunks are concatenated here once settled. */
+  content: string;
+  /** For role=agent, the runId of the FixyAdapter.execute() call. */
+  runId: string | null;
+  /** For role=user, the list of adapter ids the router dispatched this message to. */
+  dispatchedTo: string[];
+  /** Patches captured from the agent's worktree after the turn, if any. */
+  patches: FixyPatch[];
+  /** Non-fatal warnings surfaced to the user. */
+  warnings: string[];
+}
+
+export interface FixyPatch {
+  /** Absolute path of the file inside the adapter's worktree. */
+  filePath: string;
+  /** Path relative to the thread's project root. */
+  relativePath: string;
+  /** Unified diff produced by `git diff --no-color` inside the worktree. */
+  diff: string;
+  /** Bytes added / removed, populated by the worktree manager. */
+  stats: { additions: number; deletions: number };
+}
+
+export type { FixySession } from './adapter.js';

package/src/turn.ts

@@ -0,0 +1,165 @@
+// packages/core/src/turn.ts
+
+import { randomUUID } from 'node:crypto';
+
+import type { FixyExecutionContext } from './adapter.js';
+import type { FixyMessage, FixyThread } from './thread.js';
+import type { AdapterRegistry } from './registry.js';
+import { Router } from './router.js';
+import type { LocalThreadStore } from './store.js';
+import { FixyCommandRunner } from './fixy-commands.js';
+import { WorktreeManager } from './worktree.js';
+
+export interface TurnParams {
+  thread: FixyThread;
+  input: string;
+  registry: AdapterRegistry;
+  store: LocalThreadStore;
+  onLog: (stream: 'stdout' | 'stderr', chunk: string) => void;
+  signal: AbortSignal;
+  worktreeManager?: WorktreeManager;
+}
+
+export class TurnController {
+  async runTurn(params: TurnParams): Promise<void> {
+    const { thread, input, store } = params;
+
+    const router = new Router(params.registry);
+    const parsed = router.parse(input);
+
+    let dispatchedTo: string[];
+    if (parsed.kind === 'mention') {
+      dispatchedTo = parsed.agentIds;
+    } else if (parsed.kind === 'bare') {
+      const lastAgent = this._findLastAgentId(thread);
+      dispatchedTo = [lastAgent ?? thread.workerModel];
+    } else {
+      dispatchedTo = [];
+    }
+
+    const userMsg: FixyMessage = {
+      id: randomUUID(),
+      createdAt: new Date().toISOString(),
+      role: 'user',
+      agentId: null,
+      content: input,
+      runId: null,
+      dispatchedTo,
+      patches: [],
+      warnings: [],
+    };
+
+    await store.appendMessage(thread.id, thread.projectRoot, userMsg);
+
+    switch (parsed.kind) {
+      case 'mention': {
+        if (parsed.agentIds.length > 3) {
+          await this._appendSystemMessage('maximum 3 adapters per turn', params);
+          return;
+        }
+        for (const agentId of parsed.agentIds) {
+          await this._dispatchToAdapter(agentId, parsed.body, params);
+        }
+        break;
+      }
+
+      case 'fixy': {
+        const runner = new FixyCommandRunner();
+        await runner.run({
+          thread: params.thread,
+          rest: parsed.rest,
+          store: params.store,
+          registry: params.registry,
+          worktreeManager: params.worktreeManager ?? new WorktreeManager(),
+          onLog: params.onLog,
+          signal: params.signal,
+        });
+        break;
+      }
+
+      case 'bare': {
+        const lastAgent = this._findLastAgentId(thread);
+        const resolvedAgentId = lastAgent ?? thread.workerModel;
+        await this._dispatchToAdapter(resolvedAgentId, parsed.body, params);
+        break;
+      }
+
+      case 'error': {
+        await this._appendSystemMessage(parsed.reason, params);
+        break;
+      }
+    }
+  }
+
+  private _findLastAgentId(thread: FixyThread): string | null {
+    for (let i = thread.messages.length - 1; i >= 0; i--) {
+      const msg = thread.messages[i];
+      if (msg.role === 'agent' && msg.agentId !== null) {
+        return msg.agentId;
+      }
+    }
+    return null;
+  }
+
+  private async _dispatchToAdapter(
+    agentId: string,
+    body: string,
+    params: TurnParams,
+  ): Promise<void> {
+    const freshThread = await params.store.getThread(params.thread.id, params.thread.projectRoot);
+
+    const adapter = params.registry.require(agentId);
+    const runId = randomUUID();
+
+    const ctx: FixyExecutionContext = {
+      runId,
+      agent: { id: adapter.id, name: adapter.name },
+      threadContext: {
+        threadId: freshThread.id,
+        projectRoot: freshThread.projectRoot,
+        worktreePath: freshThread.projectRoot,
+        repoRef: null,
+      },
+      messages: freshThread.messages,
+      prompt: body,
+      session: freshThread.agentSessions[agentId] ?? null,
+      onLog: params.onLog,
+      onMeta: () => {},
+      onSpawn: () => {},
+      signal: params.signal,
+    };
+
+    const result = await adapter.execute(ctx);
+
+    const agentMsg: FixyMessage = {
+      id: randomUUID(),
+      createdAt: new Date().toISOString(),
+      role: 'agent',
+      agentId: adapter.id,
+      content: result.summary,
+      runId,
+      dispatchedTo: [],
+      patches: result.patches,
+      warnings: result.warnings,
+    };
+
+    await params.store.appendMessage(params.thread.id, params.thread.projectRoot, agentMsg);
+
+    params.thread.agentSessions[agentId] = result.session;
+  }
+
+  private async _appendSystemMessage(content: string, params: TurnParams): Promise<void> {
+    const msg: FixyMessage = {
+      id: randomUUID(),
+      createdAt: new Date().toISOString(),
+      role: 'system',
+      agentId: null,
+      content,
+      runId: null,
+      dispatchedTo: [],
+      patches: [],
+      warnings: [],
+    };
+    await params.store.appendMessage(params.thread.id, params.thread.projectRoot, msg);
+  }
+}

package/src/worktree.ts

@@ -0,0 +1,119 @@
+// packages/core/src/worktree.ts
+
+import { execFile } from 'node:child_process';
+import { access, mkdir, readdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { parseUnifiedDiff } from './diff-parser.js';
+import { getWorktreesDir } from './paths.js';
+import type { FixyPatch } from './thread.js';
+
+const execFileAsync = promisify(execFile);
+
+export interface WorktreeHandle {
+  /** Absolute path to the worktree directory. */
+  path: string;
+  /** Branch name, e.g. "fixy/<threadId>-<agentId>" */
+  branch: string;
+  agentId: string;
+  threadId: string;
+}
+
+export class WorktreeManager {
+  /**
+   * Idempotent — returns an existing worktree handle or creates a new one.
+   */
+  async ensure(projectRoot: string, threadId: string, agentId: string): Promise<WorktreeHandle> {
+    const worktreePath = join(getWorktreesDir(threadId), agentId);
+    const branch = `fixy/${threadId}-${agentId}`;
+
+    const exists = await this.#pathExists(worktreePath);
+
+    if (!exists) {
+      // Ensure parent directories exist before running git worktree add.
+      // git worktree add creates the leaf directory itself — only create the parent.
+      await mkdir(dirname(worktreePath), { recursive: true });
+
+      await execFileAsync('git', ['worktree', 'add', worktreePath, '-b', branch], {
+        cwd: projectRoot,
+      });
+    }
+
+    return { path: worktreePath, branch, agentId, threadId };
+  }
+
+  /**
+   * Runs `git diff --no-color` in the worktree and parses the output into
+   * FixyPatch objects.  Returns an empty array when there are no changes.
+   */
+  async collectPatches(handle: WorktreeHandle): Promise<FixyPatch[]> {
+    const { stdout } = await execFileAsync('git', ['diff', '--no-color'], { cwd: handle.path });
+
+    if (!stdout || stdout.trim().length === 0) {
+      return [];
+    }
+
+    return parseUnifiedDiff(stdout, handle.path);
+  }
+
+  /**
+   * Removes the worktree and its branch, then re-provisions a fresh one.
+   */
+  async reset(handle: WorktreeHandle, projectRoot: string): Promise<void> {
+    await this.#removeWorktree(handle, projectRoot);
+    await this.ensure(projectRoot, handle.threadId, handle.agentId);
+  }
+
+  /**
+   * Permanently removes the worktree and its tracking branch.
+   * Does NOT re-provision.
+   */
+  async remove(handle: WorktreeHandle, projectRoot: string): Promise<void> {
+    await this.#removeWorktree(handle, projectRoot);
+  }
+
+  /**
+   * Lists all WorktreeHandles for the given threadId by reading the worktrees
+   * directory on disk.  Returns an empty array when no worktrees exist yet.
+   */
+  async list(threadId: string): Promise<WorktreeHandle[]> {
+    const dir = getWorktreesDir(threadId);
+
+    const dirExists = await this.#pathExists(dir);
+    if (!dirExists) {
+      return [];
+    }
+
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isDirectory())
+      .map((e) => ({
+        path: join(dir, e.name),
+        branch: `fixy/${threadId}-${e.name}`,
+        agentId: e.name,
+        threadId,
+      }));
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  async #removeWorktree(handle: WorktreeHandle, projectRoot: string): Promise<void> {
+    await execFileAsync('git', ['worktree', 'remove', '--force', handle.path], {
+      cwd: projectRoot,
+    });
+
+    await execFileAsync('git', ['branch', '-D', handle.branch], { cwd: projectRoot });
+  }
+
+  async #pathExists(p: string): Promise<boolean> {
+    try {
+      await access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}