omni-pi 0.1.0

package/src/work.ts

@@ -0,0 +1,345 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  gatherTaskContext,
+  renderContextBlocks,
+  renderContextSummary,
+} from "./context.js";
+import type {
+  EscalationBrief,
+  TaskAttemptResult,
+  TaskBrief,
+} from "./contracts.js";
+import {
+  findNextExecutableTask,
+  readTasks,
+  updateTaskStatus,
+  writeTasks,
+} from "./tasks.js";
+
+export interface WorkEngine {
+  runWorkerTask: (
+    task: TaskBrief,
+    attempt: number,
+  ) => Promise<TaskAttemptResult>;
+  runExpertTask: (
+    task: TaskBrief,
+    escalation: EscalationBrief,
+  ) => Promise<TaskAttemptResult>;
+}
+
+export interface WorkResult {
+  kind: "completed" | "expert_completed" | "blocked" | "idle";
+  taskId: string | null;
+  message: string;
+  recoveryOptions?: string[];
+}
+
+export interface WorkDispatchResult {
+  kind: "ready" | "idle";
+  taskId: string | null;
+  prompt: string;
+  briefPath?: string;
+  message: string;
+}
+
+const DEFAULT_RETRY_LIMIT = 2;
+
+async function readRetryLimit(testsPath: string): Promise<number> {
+  try {
+    const content = await readFile(testsPath, "utf8");
+    const match = content.match(
+      /Worker retries before expert takeover:\s*(\d+)/u,
+    );
+    return match ? Number.parseInt(match[1], 10) : DEFAULT_RETRY_LIMIT;
+  } catch {
+    return DEFAULT_RETRY_LIMIT;
+  }
+}
+
+async function ensureTaskDir(rootDir: string): Promise<string> {
+  const taskDir = path.join(rootDir, ".omni", "tasks");
+  await mkdir(taskDir, { recursive: true });
+  return taskDir;
+}
+
+function historyPath(taskDir: string, taskId: string): string {
+  return path.join(taskDir, `${taskId}.history.json`);
+}
+
+async function readTaskHistory(
+  taskDir: string,
+  taskId: string,
+): Promise<TaskAttemptResult[]> {
+  try {
+    return JSON.parse(
+      await readFile(historyPath(taskDir, taskId), "utf8"),
+    ) as TaskAttemptResult[];
+  } catch {
+    return [];
+  }
+}
+
+async function writeTaskHistory(
+  taskDir: string,
+  taskId: string,
+  history: TaskAttemptResult[],
+): Promise<void> {
+  await writeFile(
+    historyPath(taskDir, taskId),
+    JSON.stringify(history, null, 2),
+    "utf8",
+  );
+}
+
+async function writeTaskBrief(taskDir: string, task: TaskBrief): Promise<void> {
+  const content = `# ${task.id}: ${task.title}
+
+## Objective
+
+${task.objective}
+
+## Done Criteria
+
+${task.doneCriteria.map((item) => `- ${item}`).join("\n") || "- None yet"}
+
+## Skills
+
+${task.skills.map((item) => `- ${item}`).join("\n") || "- None"}
+
+## Context Files
+
+${task.contextFiles.map((item) => `- ${item}`).join("\n") || "- None"}
+`;
+  await writeFile(path.join(taskDir, `${task.id}-BRIEF.md`), content, "utf8");
+}
+
+export async function prepareNextTaskDispatch(
+  rootDir: string,
+): Promise<WorkDispatchResult> {
+  const tasksPath = path.join(rootDir, ".omni", "TASKS.md");
+  const tasks = await readTasks(tasksPath);
+  const nextTask = findNextExecutableTask(tasks);
+
+  if (!nextTask) {
+    return {
+      kind: "idle",
+      taskId: null,
+      prompt: "",
+      message:
+        "No executable tasks are available. Refresh the plan or complete dependencies first.",
+    };
+  }
+
+  const taskDir = await ensureTaskDir(rootDir);
+  await writeTaskBrief(taskDir, nextTask);
+  await writeTasks(
+    tasksPath,
+    updateTaskStatus(tasks, nextTask.id, "in_progress"),
+  );
+
+  const briefPath = path.join(taskDir, `${nextTask.id}-BRIEF.md`);
+  const preReadContext = await gatherTaskContext(rootDir, nextTask, 4000);
+  const prompt = [
+    "You are working inside an Omni-Pi guided task session.",
+    "",
+    `Task: ${nextTask.id} - ${nextTask.title}`,
+    `Objective: ${nextTask.objective}`,
+    "",
+    "Read these files first:",
+    "- .omni/PROJECT.md",
+    "- .omni/SPEC.md",
+    "- .omni/TESTS.md",
+    `- ${path.relative(rootDir, briefPath)}`,
+    ...nextTask.contextFiles.map((file) => `- ${file}`),
+    "",
+    "Then implement the task, explain the change briefly, and run the planned verification steps before finishing.",
+    nextTask.skills.length > 0
+      ? `Relevant skills: ${nextTask.skills.join(", ")}`
+      : "Relevant skills: none explicitly listed",
+    ...(preReadContext.length > 0
+      ? [
+          "",
+          renderContextSummary(preReadContext),
+          "",
+          "Pre-loaded context (already read for you):",
+          renderContextBlocks(preReadContext),
+        ]
+      : []),
+  ].join("\n");
+
+  return {
+    kind: "ready",
+    taskId: nextTask.id,
+    prompt,
+    briefPath,
+    message: `Prepared ${nextTask.id} for a focused worker session.`,
+  };
+}
+
+async function writeEscalationBrief(
+  taskDir: string,
+  escalation: EscalationBrief,
+): Promise<void> {
+  const verificationResultsSection = escalation.verificationResults
+    ? escalation.verificationResults
+        .map((r) => `- ${r.command}: ${r.passed ? "passed" : "failed"}`)
+        .join("\n")
+    : "- None recorded";
+  const modifiedFilesSection =
+    escalation.modifiedFiles?.map((f) => `- ${f}`).join("\n") ||
+    "- None recorded";
+
+  const content = `# Escalation for ${escalation.taskId}
+
+## Prior Attempts
+
+${escalation.priorAttempts}
+
+## Failure Logs
+
+${escalation.failureLogs.map((item) => `- ${item}`).join("\n") || "- None"}
+
+## Verification Results
+
+${verificationResultsSection}
+
+## Modified Files
+
+${modifiedFilesSection}
+
+## Expert Objective
+
+${escalation.expertObjective}
+`;
+  await writeFile(
+    path.join(taskDir, `${escalation.taskId}-ESCALATION.md`),
+    content,
+    "utf8",
+  );
+}
+
+function createEscalationBrief(
+  task: TaskBrief,
+  history: TaskAttemptResult[],
+): EscalationBrief {
+  const failureLogs = history
+    .filter((attempt) => !attempt.verification.passed)
+    .map((attempt) => attempt.verification.failureSummary.join("; "))
+    .filter((log) => log.length > 0);
+
+  const verificationResults = history.flatMap((attempt) =>
+    attempt.verification.checksRun.map((command) => ({
+      command,
+      passed: attempt.verification.passed,
+      stdout: "",
+      stderr: attempt.verification.failureSummary.join("\n"),
+    })),
+  );
+
+  const modifiedFiles = [
+    ...new Set(history.flatMap((attempt) => attempt.modifiedFiles ?? [])),
+  ];
+
+  return {
+    taskId: task.id,
+    priorAttempts: history.length,
+    failureLogs,
+    expertObjective: `Resolve the root cause preventing ${task.id} from passing verification and complete the task.`,
+    verificationResults,
+    modifiedFiles,
+  };
+}
+
+function formatVerificationSummary(result: TaskAttemptResult): string {
+  const checks =
+    result.verification.checksRun.length > 0
+      ? result.verification.checksRun.join(", ")
+      : "no recorded checks";
+  if (result.verification.passed) {
+    return `Verification passed: ${checks}.`;
+  }
+  const failures =
+    result.verification.failureSummary.length > 0
+      ? result.verification.failureSummary.join("; ")
+      : "unknown verification failure";
+  return `Verification failed: ${checks}. Reason: ${failures}.`;
+}
+
+export async function executeNextTask(
+  rootDir: string,
+  engine: WorkEngine,
+): Promise<WorkResult> {
+  const tasksPath = path.join(rootDir, ".omni", "TASKS.md");
+  const testsPath = path.join(rootDir, ".omni", "TESTS.md");
+  const tasks = await readTasks(tasksPath);
+  const nextTask = findNextExecutableTask(tasks);
+
+  if (!nextTask) {
+    return {
+      kind: "idle",
+      taskId: null,
+      message:
+        "No executable tasks are available. Complete dependencies or refresh the plan first.",
+    };
+  }
+
+  const taskDir = await ensureTaskDir(rootDir);
+  await writeTaskBrief(taskDir, nextTask);
+
+  const history = await readTaskHistory(taskDir, nextTask.id);
+  const retryLimit = await readRetryLimit(testsPath);
+  const attempt = history.length + 1;
+  const workerResult = await engine.runWorkerTask(nextTask, attempt);
+  const workerHistory = [...history, workerResult];
+  await writeTaskHistory(taskDir, nextTask.id, workerHistory);
+
+  if (workerResult.verification.passed) {
+    await writeTasks(tasksPath, updateTaskStatus(tasks, nextTask.id, "done"));
+    return {
+      kind: "completed",
+      taskId: nextTask.id,
+      message: `Completed ${nextTask.id} with the worker path. ${formatVerificationSummary(workerResult)}`,
+    };
+  }
+
+  if (attempt < retryLimit) {
+    await writeTasks(tasksPath, updateTaskStatus(tasks, nextTask.id, "todo"));
+    return {
+      kind: "blocked",
+      taskId: nextTask.id,
+      message: `Worker attempt ${attempt} for ${nextTask.id} failed verification and is queued for retry. ${formatVerificationSummary(workerResult)}`,
+    };
+  }
+
+  const escalation = createEscalationBrief(nextTask, workerHistory);
+  await writeEscalationBrief(taskDir, escalation);
+  const expertResult = await engine.runExpertTask(nextTask, escalation);
+  await writeTaskHistory(taskDir, nextTask.id, [
+    ...workerHistory,
+    expertResult,
+  ]);
+
+  if (expertResult.verification.passed) {
+    await writeTasks(tasksPath, updateTaskStatus(tasks, nextTask.id, "done"));
+    return {
+      kind: "expert_completed",
+      taskId: nextTask.id,
+      message: `Completed ${nextTask.id} after expert escalation. ${formatVerificationSummary(expertResult)}`,
+    };
+  }
+
+  await writeTasks(tasksPath, updateTaskStatus(tasks, nextTask.id, "blocked"));
+  return {
+    kind: "blocked",
+    taskId: nextTask.id,
+    message: `Task ${nextTask.id} remains blocked after worker retries and expert escalation. ${formatVerificationSummary(expertResult)}`,
+    recoveryOptions: [
+      "Review the escalation notes in `.omni/tasks/` and refine the task inputs.",
+      "Run /omni-plan to restructure the task into smaller slices.",
+      "Run /omni-sync to capture learnings before attempting a different approach.",
+      "Manually inspect and fix the failing checks listed in `.omni/TESTS.md`.",
+    ],
+  };
+}

package/src/workflow.ts

@@ -0,0 +1,375 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { readConfig } from "./config.js";
+import type {
+  ConversationBrief,
+  OmniState,
+  SkillCandidate,
+} from "./contracts.js";
+import { type DoctorReport, runDoctor } from "./doctor.js";
+import { buildStarterFileMap, listStarterFiles } from "./memory.js";
+import {
+  createInitialSpec,
+  gatherPlanningContext,
+  renderSpecMarkdown,
+  renderTasksMarkdown,
+  renderTestsMarkdown,
+} from "./planning.js";
+import { appendProgress, cleanupCompletedPlans, createPlan } from "./plans.js";
+import { detectRepoSignals } from "./repo.js";
+import {
+  appendSkillUsageNote,
+  buildSkillInstallPlan,
+  defaultSkillSignals,
+  renderSkillDecision,
+  toSkillCandidate,
+} from "./skills.js";
+import { type SyncRequest, syncOmniMemory } from "./sync.js";
+import { executeNextTask, type WorkEngine, type WorkResult } from "./work.js";
+
+export interface InitResult {
+  created: string[];
+  reused: string[];
+  repoSignals: Awaited<ReturnType<typeof detectRepoSignals>>;
+  skillCandidates: SkillCandidate[];
+  installedSkills: SkillCandidate[];
+  installCommands: string[];
+  installSteps: Array<{
+    command: string;
+    args: string[];
+    summary: string;
+  }>;
+  diagnostics: DoctorReport;
+}
+
+export interface PlanResult {
+  specPath: string;
+  tasksPath: string;
+  testsPath: string;
+}
+
+export interface WorkExecutionResult extends WorkResult {
+  state: OmniState;
+}
+
+export interface SyncResult {
+  state: OmniState;
+}
+
+const starterFileMap = buildStarterFileMap();
+
+async function writeIfMissing(
+  filePath: string,
+  content: string,
+): Promise<boolean> {
+  try {
+    await readFile(filePath, "utf8");
+    return false;
+  } catch {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, content, "utf8");
+    return true;
+  }
+}
+
+async function replaceSection(
+  filePath: string,
+  heading: string,
+  lines: string[],
+): Promise<void> {
+  const current = await readFile(filePath, "utf8");
+  const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  const sectionRegex = new RegExp(
+    `(${escapedHeading}\\n\\n)([\\s\\S]*?)(?=\\n## |$)`,
+    "u",
+  );
+  const replacement = `$1${lines.join("\n")}\n`;
+  const next = current.match(sectionRegex)
+    ? current.replace(sectionRegex, replacement)
+    : `${current.trimEnd()}\n\n${heading}\n\n${lines.join("\n")}\n`;
+  await writeFile(filePath, next, "utf8");
+}
+
+async function writeState(rootDir: string, state: OmniState): Promise<void> {
+  const statePath = path.join(rootDir, ".omni", "STATE.md");
+  const recoverySection =
+    state.recoveryOptions && state.recoveryOptions.length > 0
+      ? `\nRecovery Options:\n${state.recoveryOptions.map((option) => `- ${option}`).join("\n")}\n`
+      : "";
+  const content = `# State
+
+Current Phase: ${state.currentPhase[0].toUpperCase()}${state.currentPhase.slice(1)}
+Active Task: ${state.activeTask}
+Status Summary: ${state.statusSummary}
+Blockers: ${state.blockers.length > 0 ? state.blockers.join("; ") : "None"}
+Next Step: ${state.nextStep}
+${recoverySection}`;
+  await writeFile(statePath, content, "utf8");
+}
+
+function buildSkillCandidates(
+  repoSignals: Awaited<ReturnType<typeof detectRepoSignals>>,
+): SkillCandidate[] {
+  const candidates = defaultSkillSignals.map(toSkillCandidate);
+
+  if (
+    repoSignals.tools.includes("playwright") ||
+    repoSignals.tools.includes("cypress")
+  ) {
+    candidates.push({
+      name: "browser-test-helpers",
+      reason:
+        "The repository already has browser testing signals, so browser-oriented workflow helpers are useful.",
+      confidence: "medium",
+      policy: "recommend-only",
+    });
+  }
+
+  return candidates;
+}
+
+export async function initializeOmniProject(
+  rootDir: string,
+): Promise<InitResult> {
+  const created: string[] = [];
+  const reused: string[] = [];
+
+  for (const file of listStarterFiles()) {
+    const absolutePath = path.join(rootDir, file.path);
+    if (await writeIfMissing(absolutePath, file.content)) {
+      created.push(file.path);
+    } else {
+      reused.push(file.path);
+    }
+  }
+
+  const repoSignals = await detectRepoSignals(rootDir);
+  const skillCandidates = buildSkillCandidates(repoSignals);
+  const {
+    installed: installedSkills,
+    commands: installCommands,
+    steps: installSteps,
+  } = buildSkillInstallPlan(skillCandidates);
+
+  const skillsPath = path.join(rootDir, ".omni", "SKILLS.md");
+  await replaceSection(
+    skillsPath,
+    "## Installed",
+    installedSkills.length > 0
+      ? installedSkills.map(renderSkillDecision)
+      : ["- None yet"],
+  );
+  await replaceSection(
+    skillsPath,
+    "## Recommended",
+    skillCandidates
+      .filter((candidate) => candidate.policy !== "auto-install")
+      .map(renderSkillDecision)
+      .concat(
+        skillCandidates.every(
+          (candidate) => candidate.policy === "auto-install",
+        )
+          ? ["- None yet"]
+          : [],
+      ),
+  );
+
+  const projectPath = path.join(rootDir, ".omni", "PROJECT.md");
+  const project = await readFile(projectPath, "utf8");
+  const signalSummary = [
+    `- Detected languages: ${repoSignals.languages.join(", ") || "unknown"}`,
+    `- Detected frameworks: ${repoSignals.frameworks.join(", ") || "unknown"}`,
+    `- Detected tools: ${repoSignals.tools.join(", ") || "unknown"}`,
+  ].join("\n");
+  if (!project.includes("## Repo Signals")) {
+    await writeFile(
+      projectPath,
+      `${project.trimEnd()}\n\n## Repo Signals\n\n${signalSummary}\n`,
+      "utf8",
+    );
+  }
+
+  if (installCommands.length > 0) {
+    await appendSkillUsageNote(
+      rootDir,
+      `Planned install commands: ${installCommands.join(" ; ")}`,
+    );
+  }
+
+  const diagnostics = await runDoctor(rootDir);
+
+  await writeState(rootDir, {
+    currentPhase: "understand",
+    activeTask: "Initialize Omni-Pi",
+    statusSummary:
+      "Omni-Pi has created its project memory files and scanned the repository for useful signals.",
+    blockers: [],
+    nextStep:
+      diagnostics.overall === "red"
+        ? "Run /omni-doctor to review issues before proceeding."
+        : "Run /omni-plan to turn the current project context into a spec and first task slices.",
+  });
+
+  return {
+    created,
+    reused,
+    repoSignals,
+    skillCandidates,
+    installedSkills,
+    installCommands,
+    installSteps,
+    diagnostics,
+  };
+}
+
+export async function planOmniProject(
+  rootDir: string,
+  brief: ConversationBrief,
+): Promise<PlanResult> {
+  const specPath = path.join(rootDir, ".omni", "SPEC.md");
+  const tasksPath = path.join(rootDir, ".omni", "TASKS.md");
+  const testsPath = path.join(rootDir, ".omni", "TESTS.md");
+
+  for (const required of [specPath, tasksPath, testsPath]) {
+    const relative = path.relative(rootDir, required);
+    if (!starterFileMap[relative]) {
+      continue;
+    }
+    await writeIfMissing(required, starterFileMap[relative]);
+  }
+
+  const repoSignals = await detectRepoSignals(rootDir);
+  const planningCtx = await gatherPlanningContext(rootDir);
+  const spec = createInitialSpec(brief, repoSignals, planningCtx);
+  await writeFile(specPath, renderSpecMarkdown(spec), "utf8");
+  await writeFile(tasksPath, renderTasksMarkdown(spec.taskSlices), "utf8");
+  await writeFile(testsPath, renderTestsMarkdown(repoSignals), "utf8");
+
+  const planEntry = await createPlan(
+    rootDir,
+    spec.title,
+    brief.summary,
+    spec.taskSlices.map((t) => `${t.id}: ${t.title}`),
+  );
+  await appendProgress(rootDir, `Created plan ${planEntry.id}: ${spec.title}`);
+
+  await writeState(rootDir, {
+    currentPhase: "plan",
+    activeTask: "Prepare the first implementation slice",
+    statusSummary:
+      "Omni-Pi refreshed the spec, task slices, and verification plan.",
+    blockers: [],
+    nextStep:
+      "Review the proposed tasks, then run /omni-work when you are ready to execute the next slice.",
+  });
+
+  return { specPath, tasksPath, testsPath };
+}
+
+export async function readOmniStatus(rootDir: string): Promise<OmniState> {
+  const statePath = path.join(rootDir, ".omni", "STATE.md");
+  const content = await readFile(statePath, "utf8");
+
+  const matchValue = (label: string): string => {
+    const regex = new RegExp(`^${label}:\\s*(.*)$`, "mu");
+    return content.match(regex)?.[1]?.trim() ?? "";
+  };
+
+  const blockersValue = matchValue("Blockers");
+  const recoveryMatch = content.match(/Recovery Options:\n((?:- .*\n?)*)/u);
+  const recoveryOptions = recoveryMatch
+    ? recoveryMatch[1]
+        .split("\n")
+        .map((line) => line.replace(/^- /u, "").trim())
+        .filter(Boolean)
+    : undefined;
+  return {
+    currentPhase: matchValue(
+      "Current Phase",
+    ).toLowerCase() as OmniState["currentPhase"],
+    activeTask: matchValue("Active Task"),
+    statusSummary: matchValue("Status Summary"),
+    blockers:
+      blockersValue && blockersValue !== "None"
+        ? blockersValue.split(/;\s*/u)
+        : [],
+    nextStep: matchValue("Next Step"),
+    recoveryOptions,
+  };
+}
+
+export async function workOnOmniProject(
+  rootDir: string,
+  engine: WorkEngine,
+): Promise<WorkExecutionResult> {
+  const result = await executeNextTask(rootDir, engine);
+
+  let state: OmniState;
+  if (result.kind === "completed" || result.kind === "expert_completed") {
+    state = {
+      currentPhase: result.kind === "expert_completed" ? "escalate" : "build",
+      activeTask: result.taskId ?? "None",
+      statusSummary: result.message,
+      blockers: [],
+      nextStep:
+        "Run /omni-status to review progress or /omni-work to continue with the next task.",
+    };
+  } else if (result.kind === "blocked") {
+    state = {
+      currentPhase: result.message.includes("expert escalation")
+        ? "escalate"
+        : "check",
+      activeTask: result.taskId ?? "None",
+      statusSummary: result.message,
+      blockers: result.taskId
+        ? [`Verification failures on ${result.taskId}`]
+        : ["A task is blocked."],
+      nextStep: result.message.includes("queued for retry")
+        ? "Run /omni-work again to retry the task or inspect `.omni/tasks/` for the failure history."
+        : "Review the escalation notes in `.omni/tasks/` and refine the plan or task inputs.",
+      recoveryOptions: result.recoveryOptions,
+    };
+  } else {
+    state = {
+      currentPhase: "plan",
+      activeTask: "None",
+      statusSummary: result.message,
+      blockers: [],
+      nextStep:
+        "Run /omni-plan to refresh the task list if more work is needed.",
+    };
+  }
+
+  await writeState(rootDir, state);
+  if (result.kind === "completed" || result.kind === "expert_completed") {
+    await appendProgress(
+      rootDir,
+      `Completed ${result.taskId ?? "task"}: ${result.message}`,
+    );
+  }
+  return { ...result, state };
+}
+
+export async function syncOmniProject(
+  rootDir: string,
+  request: SyncRequest,
+): Promise<SyncResult> {
+  await syncOmniMemory(rootDir, request);
+  await appendProgress(rootDir, request.summary);
+
+  const config = await readConfig(rootDir);
+  if (config.cleanupCompletedPlans) {
+    await cleanupCompletedPlans(rootDir);
+  }
+
+  const state: OmniState = {
+    currentPhase: "understand",
+    activeTask: "Sync project memory",
+    statusSummary: "Omni-Pi synced recent progress into durable memory files.",
+    blockers: [],
+    nextStep:
+      "Run /omni-status to inspect the latest state or /omni-plan to refine the next slice.",
+  };
+  await writeState(rootDir, state);
+  return { state };
+}