@bugabinga/pi-ext-llmiterate 0.1.0

package/index.ts

@@ -0,0 +1,434 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  buildAgentPrompt,
+  compilePathFilter,
+  emptyState,
+  loadConfig,
+  loadState,
+  parseMarkerPrompts,
+  previewText,
+  projectStoreDir,
+  saveState,
+  shouldIncludeCompiledPath,
+  toSlash,
+  type CompiledPathFilter,
+  type LlmiterateConfig,
+  type LlmiterateState,
+  type MarkerPrompt,
+} from "./core";
+import { acquireLock, findProjectRoot, realPath, releaseLock, type LockHandle } from "./lock";
+import { PiRpcWorker } from "./rpc";
+import { renderLlmiterateUi } from "./ui";
+import { ProjectWatcher } from "./watcher";
+import type { LlmiterateRun, RpcEvent, RpcMessage, RpcTextPart, RpcToolResult } from "./types";
+
+interface WatchRuntime {
+  root: string;
+  cwd: string;
+  config: LlmiterateConfig;
+  pathFilter: CompiledPathFilter;
+  storeDir: string;
+  state: LlmiterateState;
+  watcher?: ProjectWatcher;
+  lock?: LockHandle;
+  lockError?: string;
+}
+
+interface ScannedFile {
+  runtime: WatchRuntime;
+  projectRel: string;
+  agentRel: string;
+  text: string;
+}
+
+const MAX_RUNS = 20;
+const STATE_PROMPT_PREVIEW_CHARS = 120;
+
+export default function (pi: ExtensionAPI) {
+  let runtime: WatchRuntime | undefined;
+  let sessionCtx: ExtensionContext | undefined;
+  let panelVisible = false;
+  let nextRunId = 1;
+  let activeRunId: number | undefined;
+  let activeJob = false;
+  let rpcWorker: PiRpcWorker | undefined;
+  const runs: LlmiterateRun[] = [];
+
+  pi.on("session_start", async (_event, ctx) => {
+    sessionCtx = ctx;
+    start(ctx.cwd);
+    updateUi(ctx);
+  });
+
+  pi.on("session_shutdown", async () => {
+    stop();
+    sessionCtx = undefined;
+    activeRunId = undefined;
+  });
+
+  pi.registerCommand("llmiterate", {
+    description: "Toggle/show llmiterate watcher UI. Args: show | hide | status | scan | reset | reload",
+    handler: async (args, ctx) => {
+      runCommand(args.trim().toLowerCase(), ctx);
+      updateUi(ctx);
+    },
+  });
+
+  function runCommand(command: string, ctx: ExtensionCommandContext): void {
+    switch (command) {
+      case "": panelVisible = !panelVisible; return;
+      case "show":
+      case "status": panelVisible = true; return;
+      case "hide": panelVisible = false; return;
+      case "scan": scanCommand(ctx); return;
+      case "reset": resetCommand(ctx); return;
+      case "reload":
+        start(ctx.cwd);
+        ctx.ui.notify("llmiterate config/watcher reloaded", "info");
+        return;
+      default:
+        ctx.ui.notify("Usage: /llmiterate [show|hide|status|scan|reset|reload]", "warning");
+    }
+  }
+
+  function scanCommand(ctx: ExtensionCommandContext): void {
+    if (notifyIfStandby(ctx)) {
+      panelVisible = true;
+      return;
+    }
+
+    const count = scanAll();
+    panelVisible = true;
+    ctx.ui.notify(`llmiterate scan queued ${count} new prompt(s)`, "info");
+  }
+
+  function resetCommand(ctx: ExtensionCommandContext): void {
+    if (notifyIfStandby(ctx)) return;
+
+    if (runtime) {
+      runtime.state = emptyState();
+      persistState(runtime);
+    }
+    stopWorker();
+    runs.length = 0;
+    activeRunId = undefined;
+    ctx.ui.notify("llmiterate state reset", "info");
+  }
+
+  function notifyIfStandby(ctx: ExtensionCommandContext): boolean {
+    if (!runtime?.lockError) return false;
+    ctx.ui.notify(`llmiterate inactive: ${runtime.lockError}`, "warning");
+    return true;
+  }
+
+  function start(cwd: string): void {
+    stop();
+    const root = findProjectRoot(cwd);
+    const config = loadConfig(root);
+    const storeDir = projectStoreDir(root);
+    const state = loadState(storeDir);
+    runtime = {
+      root,
+      cwd: realPath(cwd),
+      config,
+      pathFilter: compilePathFilter(config),
+      storeDir,
+      state,
+    };
+    if (!config.enabled) return;
+
+    const lock = acquireLock(storeDir);
+    if (typeof lock === "string") {
+      runtime.lockError = lock;
+      return;
+    }
+    runtime.lock = lock;
+    runtime.watcher = new ProjectWatcher(root, config, runtime.pathFilter, scanFile, () => updateUi(sessionCtx));
+    runtime.watcher.start();
+  }
+
+  function stop(): void {
+    if (!runtime) return;
+    runtime.watcher?.stop();
+    stopWorker();
+    if (runtime.lock) releaseLock(runtime.lock);
+    runtime = undefined;
+  }
+
+  function scanFile(absPath: string): number {
+    const file = readScannedFile(absPath);
+    if (!file) return 0;
+
+    let queued = 0;
+    const blocks = parseMarkerPrompts(file.projectRel, file.text, file.runtime.config.markers);
+    for (const block of blocks) {
+      if (file.runtime.state.processed[block.key]) continue;
+      recordProcessedPrompt(file.runtime, block);
+      enqueueRun({ ...block, file: file.agentRel }, file.projectRel, absPath);
+      queued++;
+    }
+
+    if (queued > 0) persistState(file.runtime);
+    return queued;
+  }
+
+  function readScannedFile(absPath: string): ScannedFile | undefined {
+    const current = runtime;
+    if (!current) return undefined;
+
+    const projectRel = toSlash(path.relative(current.root, absPath));
+    if (!shouldIncludeCompiledPath(projectRel, current.pathFilter)) return undefined;
+
+    const stat = statFile(absPath);
+    if (!stat?.isFile() || stat.size > current.config.maxFileBytes) return undefined;
+
+    const text = readUtf8(absPath);
+    if (text === undefined) return undefined;
+
+    return {
+      runtime: current,
+      projectRel,
+      agentRel: toSlash(path.relative(current.cwd, absPath)),
+      text,
+    };
+  }
+
+  function recordProcessedPrompt(current: WatchRuntime, block: MarkerPrompt): void {
+    current.state.processed[block.key] = {
+      file: block.file,
+      startLine: block.startLine,
+      endLine: block.endLine,
+      promptHash: block.promptHash,
+      promptPreview: previewText(block.prompt, STATE_PROMPT_PREVIEW_CHARS),
+      queuedAt: Date.now(),
+    };
+  }
+
+  function statFile(absPath: string): fs.Stats | undefined {
+    try { return fs.statSync(absPath); } catch { return undefined; }
+  }
+
+  function readUtf8(absPath: string): string | undefined {
+    try { return fs.readFileSync(absPath, "utf-8"); } catch { return undefined; }
+  }
+
+  function persistState(current: WatchRuntime): void {
+    saveState(current.storeDir, current.state);
+  }
+
+  function scanAll(): number {
+    return runtime?.watcher?.scanAll(scanFile) ?? 0;
+  }
+
+  function enqueueRun(block: MarkerPrompt, projectFile: string, absoluteFile: string): void {
+    runs.unshift(createRun(block, projectFile, absoluteFile));
+    trimRuns();
+    startNextRun();
+    updateUi(sessionCtx);
+  }
+
+  function createRun(block: MarkerPrompt, projectFile: string, absoluteFile: string): LlmiterateRun {
+    const now = Date.now();
+    return {
+      id: nextRunId++,
+      block,
+      projectFile,
+      absoluteFile,
+      fullPrompt: buildAgentPrompt(block),
+      status: "queued",
+      queuedAt: now,
+      updatedAt: now,
+      assistantText: "",
+      toolText: "",
+    };
+  }
+
+  function trimRuns(): void {
+    while (runs.length > MAX_RUNS) runs.pop();
+  }
+
+  function startNextRun(): void {
+    if (activeJob || !runtime) return;
+
+    while (runtime) {
+      const run = nextQueuedRun();
+      if (!run) return;
+      if (isRunStillValid(run)) {
+        void runInRpcWorker(run);
+        return;
+      }
+      failRun(run, "marker span changed before background agent start; skipped stale request");
+      updateUi(sessionCtx);
+    }
+  }
+
+  function nextQueuedRun(): LlmiterateRun | undefined {
+    for (let i = runs.length - 1; i >= 0; i--) {
+      if (runs[i]?.status === "queued") return runs[i];
+    }
+    return undefined;
+  }
+
+  async function runInRpcWorker(run: LlmiterateRun): Promise<void> {
+    if (!runtime) return;
+
+    if (!isRunStillValid(run)) {
+      failRun(run, "marker span changed before background agent start; skipped stale request");
+      updateUi(sessionCtx);
+      queueMicrotask(startNextRun);
+      return;
+    }
+
+    markRunRunning(run);
+    updateUi(sessionCtx);
+
+    try {
+      await worker().runPrompt(run.fullPrompt, sessionName(run));
+      markRunDone(run);
+    } catch (error) {
+      failRun(run, errorMessage(error));
+    } finally {
+      activeJob = false;
+      activeRunId = undefined;
+      touchRun(run);
+      updateUi(sessionCtx);
+      startNextRun();
+    }
+  }
+
+  function worker(): PiRpcWorker {
+    if (!runtime) throw new Error("llmiterate runtime is not started");
+    rpcWorker ??= new PiRpcWorker({
+      cwd: runtime.root,
+      sessionDir: path.join(runtime.storeDir, "sessions"),
+      onEvent: handleRpcEvent,
+    });
+    return rpcWorker;
+  }
+
+  function stopWorker(): void {
+    rpcWorker?.dispose();
+    rpcWorker = undefined;
+    activeJob = false;
+    activeRunId = undefined;
+  }
+
+  function handleRpcEvent(event: RpcEvent): void {
+    const run = activeRun();
+    if (!run) return;
+
+    switch (event.type) {
+      case "message_update":
+      case "message_end":
+        if (event.message?.role === "assistant") updateAssistantText(run, event.message);
+        break;
+      case "tool_execution_start":
+        updateToolText(run, `running ${toolName(event.toolName)}`);
+        break;
+      case "tool_execution_end": {
+        const failed = event.isError === true;
+        updateToolText(run, `${failed ? "error" : "done"} ${toolName(event.toolName)}`);
+        if (failed) failRun(run, extractToolResultText(event.result));
+        break;
+      }
+      case "agent_end":
+        markRunDone(run);
+        break;
+    }
+
+    updateUi(sessionCtx);
+  }
+
+  function markRunRunning(run: LlmiterateRun): void {
+    activeJob = true;
+    activeRunId = run.id;
+    run.status = "running";
+    run.toolText = "starting isolated RPC session";
+    run.assistantText = "";
+    touchRun(run);
+  }
+
+  function markRunDone(run: LlmiterateRun): void {
+    if (run.status === "error") return;
+    run.status = "done";
+    touchRun(run);
+  }
+
+  function failRun(run: LlmiterateRun, error: string): void {
+    run.status = "error";
+    run.error = error || "background pi failed";
+    touchRun(run);
+  }
+
+  function updateAssistantText(run: LlmiterateRun, message: RpcMessage): void {
+    run.assistantText = extractMessageText(message);
+    touchRun(run);
+  }
+
+  function updateToolText(run: LlmiterateRun, text: string): void {
+    run.toolText = text;
+    touchRun(run);
+  }
+
+  function touchRun(run: LlmiterateRun): void {
+    run.updatedAt = Date.now();
+  }
+
+  function isRunStillValid(run: LlmiterateRun): boolean {
+    if (!runtime) return false;
+    const text = readUtf8(run.absoluteFile);
+    if (text === undefined) return false;
+    return parseMarkerPrompts(run.projectFile, text, runtime.config.markers).some((block) =>
+      block.startLine === run.block.startLine && block.promptHash === run.block.promptHash
+    );
+  }
+
+  function activeRun(): LlmiterateRun | undefined {
+    return runs.find((run) => run.id === activeRunId);
+  }
+
+  function updateUi(ctx: ExtensionContext | undefined): void {
+    renderLlmiterateUi(ctx, panelVisible, runs, {
+      config: runtime?.config,
+      lockError: runtime?.lockError,
+      watchErrors: runtime?.watcher?.errorCount ?? 0,
+      activeRun: activeRun(),
+      queuedRuns: queuedRunCount(),
+    });
+  }
+
+  function queuedRunCount(): number {
+    return runs.filter((run) => run.status === "queued").length;
+  }
+}
+
+function sessionName(run: LlmiterateRun): string {
+  return `llmiterate ${run.projectFile}:${run.block.startLine}`;
+}
+
+function extractMessageText(message: RpcMessage): string {
+  if (typeof message.content === "string") return message.content.trim();
+  return textParts(message.content).join("\n").trim();
+}
+
+function extractToolResultText(result: RpcToolResult | undefined): string {
+  return textParts(result?.content).join("\n").trim();
+}
+
+function textParts(parts: RpcMessage["content"]): string[] {
+  return Array.isArray(parts) ? parts.filter(isTextPart).map((part) => part.text) : [];
+}
+
+function isTextPart(part: RpcTextPart): part is RpcTextPart & { text: string } {
+  return part.type === "text" && typeof part.text === "string";
+}
+
+function toolName(value: unknown): string {
+  return typeof value === "string" && value.trim() ? value : "tool";
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/lock.ts

@@ -0,0 +1,139 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+
+const LOCK_DIR = "lock";
+const OWNER_FILE = "owner.json";
+
+export interface LockHandle {
+  dir: string;
+  token: string;
+}
+
+interface LockOwner {
+  pid: number;
+  hostname: string;
+  token: string;
+}
+
+export function findProjectRoot(cwd: string): string {
+  const start = realPath(cwd);
+
+  for (let dir: string | undefined = start; dir; dir = parentDir(dir)) {
+    if (isProjectBoundary(dir)) return realPath(dir);
+  }
+
+  return start;
+}
+
+export function realPath(file: string): string {
+  try { return fs.realpathSync(file); } catch { return path.resolve(file); }
+}
+
+export function acquireLock(storeDir: string): LockHandle | string {
+  const lockDir = path.join(storeDir, LOCK_DIR);
+  fs.mkdirSync(storeDir, { recursive: true });
+
+  const token = randomUUID();
+  const owner = createOwner(token);
+  const created = tryCreateLock(lockDir, owner);
+  if (created) return created;
+
+  const existing = readLockOwner(lockDir);
+  if (existing && isStaleOwner(existing)) {
+    const recovered = reclaimStaleLock(lockDir, existing, owner);
+    if (recovered) return recovered;
+  }
+
+  const by = existing ? `pid ${existing.pid} on ${existing.hostname}` : "another pi";
+  return `singleton lock held by ${by}`;
+}
+
+export function releaseLock(lock: LockHandle): void {
+  const owner = readLockOwner(lock.dir);
+  if (!owner || owner.token !== lock.token) return;
+  fs.rmSync(lock.dir, { recursive: true, force: true });
+}
+
+function createOwner(token: string): LockOwner {
+  return { pid: process.pid, hostname: os.hostname(), token };
+}
+
+function tryCreateLock(lockDir: string, owner: LockOwner): LockHandle | undefined {
+  try {
+    fs.mkdirSync(lockDir);
+    fs.writeFileSync(path.join(lockDir, OWNER_FILE), JSON.stringify(owner, null, 2) + "\n", "utf-8");
+    return { dir: lockDir, token: owner.token };
+  } catch (error) {
+    if (nodeErrorCode(error) !== "EEXIST") throw error;
+    return undefined;
+  }
+}
+
+function readLockOwner(lockDir: string): LockOwner | undefined {
+  try {
+    return parseLockOwner(JSON.parse(fs.readFileSync(path.join(lockDir, OWNER_FILE), "utf-8")));
+  } catch {
+    return undefined;
+  }
+}
+
+function parseLockOwner(value: unknown): LockOwner | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const keys = Object.keys(value).sort();
+  if (keys.join("\0") !== "hostname\0pid\0token") return undefined;
+
+  const owner = value as Partial<LockOwner>;
+  if (typeof owner.pid !== "number") return undefined;
+  if (typeof owner.hostname !== "string") return undefined;
+  if (typeof owner.token !== "string") return undefined;
+  return { pid: owner.pid, hostname: owner.hostname, token: owner.token };
+}
+
+function reclaimStaleLock(lockDir: string, staleOwner: LockOwner, newOwner: LockOwner): LockHandle | undefined {
+  const reclaimedDir = `${lockDir}.stale.${newOwner.token}`;
+  try {
+    fs.renameSync(lockDir, reclaimedDir);
+  } catch {
+    return undefined;
+  }
+
+  const movedOwner = readLockOwner(reclaimedDir);
+  if (movedOwner?.token !== staleOwner.token) {
+    try { fs.renameSync(reclaimedDir, lockDir); } catch {}
+    return undefined;
+  }
+
+  fs.rmSync(reclaimedDir, { recursive: true, force: true });
+  return tryCreateLock(lockDir, newOwner);
+}
+
+function isStaleOwner(owner: LockOwner): boolean {
+  if (owner.hostname !== os.hostname()) return false;
+  try {
+    process.kill(owner.pid, 0);
+    return false;
+  } catch (error) {
+    return nodeErrorCode(error) === "ESRCH";
+  }
+}
+
+function isProjectBoundary(dir: string): boolean {
+  return isDirectory(path.join(dir, ".pi"))
+    || fs.existsSync(path.join(dir, "AGENTS.md"))
+    || fs.existsSync(path.join(dir, ".git"));
+}
+
+function parentDir(dir: string): string | undefined {
+  const parent = path.dirname(dir);
+  return parent === dir ? undefined : parent;
+}
+
+function isDirectory(file: string): boolean {
+  try { return fs.statSync(file).isDirectory(); } catch { return false; }
+}
+
+function nodeErrorCode(error: unknown): string | undefined {
+  return error instanceof Error && "code" in error ? String((error as NodeJS.ErrnoException).code) : undefined;
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@bugabinga/pi-ext-llmiterate",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "test": "bun test ./__tests__/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "license": "MIT",
+  "description": "LLM iteration watcher for Pi.",
+  "keywords": [
+    "pi",
+    "pi-extension"
+  ]
+}