jeo-code 0.1.0

package/src/commands/team.ts

@@ -0,0 +1,337 @@
+import * as fs from "node:fs/promises";
+import { z } from "zod";
+import {
+  readWorkflowState,
+  writeWorkflowState,
+} from "../agent/state";
+import { runAgentLoop } from "../agent/engine";
+import { readGlobalConfig } from "../agent/state";
+import {
+  defaultSubagentRole,
+  resolveSubagentModel,
+  resolveSubagentMaxSteps,
+  subagentSystemPrompt,
+  subagentToolset,
+} from "../agent/subagents";
+import type { Message } from "../agent/loop";
+
+export type RalphStreamKind = "step" | "complete" | "error";
+
+export function formatRalphTodoGuide(tasks: string[], activeIndex = 0, completed: readonly string[] = []): string[] {
+  const done = new Set(completed);
+  const lines = [
+    "[RALPH] Subagent guidance: follow todos in order; stream every step, complete, and error event.",
+  ];
+  tasks.forEach((task, index) => {
+    const mark = done.has(task) ? "x" : index === activeIndex ? ">" : " ";
+    lines.push(`[TODO] ${index + 1}/${tasks.length} [${mark}] ${task}`);
+  });
+  return lines;
+}
+
+export function formatRalphStreamEvent(kind: RalphStreamKind, message: string): string {
+  const label = kind === "complete" ? "complete" : kind === "error" ? "error" : "step";
+  return `  └─ stream:${label} ${message}`;
+}
+
+export interface RalphSubagentPromptContext {
+  task: string;
+  tasks: string[];
+  activeIndex: number;
+  completed?: readonly string[];
+}
+
+export function buildRalphSubagentPrompt(ctx: RalphSubagentPromptContext): string {
+  const guide = formatRalphTodoGuide(ctx.tasks, ctx.activeIndex, ctx.completed ?? []).join("\n");
+  return [
+    "You are an ooo ralph subagent executing one todo from an immutable plan.",
+    "",
+    guide,
+    "",
+    `Current todo: ${ctx.activeIndex + 1}/${ctx.tasks.length} "${ctx.task}"`,
+    "",
+    "Rules:",
+    "- Execute ONLY the current [>] todo; do not skip ahead or rewrite the todo list.",
+    "- Treat completed [x] todos as context only; do not redo them unless required to verify this todo.",
+    "- Use tools in small steps and verify the current todo before calling done.",
+    "- The caller streams your lifecycle as stream:step, stream:complete, and stream:error; keep done.reason concise.",
+  ].join("\n");
+}
+
+
+export async function runTeamCommand(): Promise<void> {
+  const cwd = process.cwd();
+
+  // Read ralplan state
+  const planState = await readWorkflowState("ralplan", cwd);
+  if (!planState || planState.current_phase !== "complete" || !planState.plan_path) {
+    console.log(
+      `[ERROR] No completed plan found. Please run 'joc ralplan' to generate a plan first.`
+    );
+    return;
+  }
+
+  if (!planState.approved) {
+    console.log(
+      `[ERROR] Plan is not approved. Please approve the plan before executing.`
+    );
+    return;
+  }
+
+  const planPath = planState.plan_path;
+  console.log(`\n=== Starting Team Execution Stage ===`);
+  console.log(`Reading plan from: ${planPath}`);
+
+  let planContent = "";
+  try {
+    planContent = await fs.readFile(planPath, "utf-8");
+  } catch (err: any) {
+    console.log(`[ERROR] Failed to read plan file: ${err.message}`);
+    return;
+  }
+
+  let rawPlan: any;
+  try {
+    rawPlan = parseYaml(planContent);
+  } catch (err: any) {
+    console.log(`[ERROR] Failed to parse plan YAML: ${err.message}`);
+    return;
+  }
+
+  const parsed = PlanSchema.safeParse(rawPlan);
+  if (!parsed.success) {
+    console.log(`[ERROR] Plan validation failed: ${parsed.error.message}`);
+    return;
+  }
+
+  const tasks = parsed.data.steps.map(step => step.name);
+
+  console.log(`Loaded ${tasks.length} tasks for execution.`);
+
+
+  // Initialize team state
+  let teamState = await readWorkflowState("team", cwd) || {
+    active: true,
+    current_phase: "executing",
+    skill: "team" as const,
+    slug: planState.slug,
+    plan_path: planPath,
+    completed_tasks: [],
+    pending_tasks: [...tasks],
+  };
+
+  await writeWorkflowState("team", teamState, cwd);
+  for (const line of formatRalphTodoGuide(tasks, Math.max(0, tasks.indexOf(teamState.pending_tasks?.[0] ?? "")), teamState.completed_tasks ?? [])) console.log(line);
+
+  while (teamState.pending_tasks && teamState.pending_tasks.length > 0) {
+    const currentTask = teamState.pending_tasks[0];
+    console.log(`\n[TASK] Current: "${currentTask}"`);
+    const activeIndex = tasks.indexOf(currentTask);
+    for (const line of formatRalphTodoGuide(tasks, activeIndex, teamState.completed_tasks ?? [])) console.log(line);
+
+    // Run the Executor loop
+    const success = await executeTaskWithAgent({
+      task: currentTask,
+      tasks,
+      activeIndex,
+      completed: teamState.completed_tasks ?? [],
+      cwd,
+    });
+    
+    if (success) {
+      teamState.completed_tasks = [...(teamState.completed_tasks ?? []), currentTask];
+      teamState.pending_tasks = teamState.pending_tasks.slice(1);
+      await writeWorkflowState("team", teamState, cwd);
+      console.log(`[TASK SUCCESS] Completed: "${currentTask}"`);
+    } else {
+      console.log(`[TASK FAILED] Failed on task: "${currentTask}". Halting execution.`);
+      break;
+    }
+  }
+
+  if (teamState.pending_tasks && teamState.pending_tasks.length === 0) {
+    teamState.current_phase = "complete";
+    await writeWorkflowState("team", teamState, cwd);
+    console.log("\n[SUCCESS] All tasks in the plan executed successfully!");
+    console.log("Run 'joc ultragoal' to run verify tests and evaluate metrics.");
+  }
+}
+
+async function executeTaskWithAgent(ctx: RalphSubagentPromptContext & { cwd: string }): Promise<boolean> {
+  const config = await readGlobalConfig();
+  const role = defaultSubagentRole();
+  const model = resolveSubagentModel(role.id, config);
+  const maxSteps = resolveSubagentMaxSteps(role.id, config);
+  console.log(`  └─ Subagent: ${role.title} · model ${model} · ≤${maxSteps} steps`);
+
+  const history: Message[] = [
+    { role: "system", content: subagentSystemPrompt(role) },
+    { role: "user", content: buildRalphSubagentPrompt(ctx) },
+  ];
+
+  const result = await runAgentLoop(history, {
+    cwd: ctx.cwd,
+    model,
+    maxSteps,
+    tools: subagentToolset(role),
+    events: {
+      onAssistant: (_raw, invocation) => {
+        if (!invocation) {
+          console.log(formatRalphStreamEvent("error", "invalid tool-call json; retrying"));
+        } else if (invocation.tool !== "done") {
+          console.log(formatRalphStreamEvent("step", `tool ${invocation.tool} requested`));
+        }
+      },
+      onStep: step => console.log(formatRalphStreamEvent("step", `${role.title} thinking ${step}/${maxSteps}`)),
+      onToolResult: (tool, ok) => console.log(formatRalphStreamEvent(ok ? "complete" : "error", `tool ${tool}`)),
+      onError: msg => console.log(formatRalphStreamEvent("error", msg)),
+    },
+  });
+
+  if (result.done) {
+    console.log(formatRalphStreamEvent("complete", `${role.title} finished task`));
+    return true;
+  }
+  console.log(formatRalphStreamEvent("error", `${role.title} did not converge within ${result.steps} steps`));
+  return false;
+}
+export const StepSchema = z.object({
+  name: z.string(),
+}).passthrough();
+
+export const PlanSchema = z.object({
+  name: z.string(),
+  steps: z.array(StepSchema),
+}).passthrough();
+
+function parseValue(v: string): any {
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1);
+  }
+  if (v === "true") return true;
+  if (v === "false") return false;
+  if (v === "null") return null;
+  if (v === "") return "";
+  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v);
+  return v;
+}
+
+export function parseYaml(yamlStr: string): any {
+  const lines = yamlStr.split(/\r?\n/).map(line => {
+    const commentIdx = line.indexOf('#');
+    const cleanLine = commentIdx !== -1 ? line.slice(0, commentIdx) : line;
+    return {
+      raw: cleanLine,
+      trimmed: cleanLine.trim(),
+      indent: cleanLine.length - cleanLine.trimStart().length
+    };
+  }).filter(l => l.trimmed !== '');
+
+  let idx = 0;
+
+  function parseBlock(baseIndent: number): any {
+    let result: any = null;
+    let isArray = false;
+
+    if (idx < lines.length) {
+      if (lines[idx].trimmed.startsWith('-')) {
+        isArray = true;
+        result = [];
+      } else {
+        result = {};
+      }
+    }
+
+    while (idx < lines.length) {
+      const line = lines[idx];
+      if (line.indent < baseIndent) {
+        break;
+      }
+
+      if (isArray) {
+        if (!line.trimmed.startsWith('-')) {
+          if (result.length > 0 && typeof result[result.length - 1] === 'object') {
+            const colonIdx = line.trimmed.indexOf(':');
+            if (colonIdx !== -1) {
+              const k = line.trimmed.slice(0, colonIdx).trim();
+              const rawVal = line.trimmed.slice(colonIdx + 1).trim();
+              if (rawVal === '') {
+                idx++;
+                result[result.length - 1][k] = parseBlock(line.indent + 1);
+                continue;
+              } else {
+                result[result.length - 1][k] = parseValue(rawVal);
+              }
+            } else {
+              throw new Error(`Invalid line inside array block: "${line.trimmed}"`);
+            }
+          } else {
+            throw new Error(`Invalid line in array: "${line.trimmed}"`);
+          }
+          idx++;
+          continue;
+        }
+
+        const rest = line.trimmed.slice(1).trim();
+        if (rest === '') {
+          idx++;
+          const nested = parseBlock(line.indent + 1);
+          result.push(nested);
+        } else if (rest.includes(':')) {
+          const colonIdx = rest.indexOf(':');
+          const k = rest.slice(0, colonIdx).trim();
+          const rawVal = rest.slice(colonIdx + 1).trim();
+          if (rawVal === '') {
+            idx++;
+            const nestedObj = { [k]: parseBlock(line.indent + 2) };
+            result.push(nestedObj);
+          } else {
+            const item: any = { [k]: parseValue(rawVal) };
+            result.push(item);
+            idx++;
+            while (idx < lines.length && !lines[idx].trimmed.startsWith('-') && lines[idx].indent >= line.indent + 2) {
+              const subLine = lines[idx];
+              const subColonIdx = subLine.trimmed.indexOf(':');
+              if (subColonIdx !== -1) {
+                const subK = subLine.trimmed.slice(0, subColonIdx).trim();
+                const rawSubVal = subLine.trimmed.slice(subColonIdx + 1).trim();
+                if (rawSubVal === '') {
+                  idx++;
+                  item[subK] = parseBlock(subLine.indent + 1);
+                } else {
+                  item[subK] = parseValue(rawSubVal);
+                  idx++;
+                }
+              } else {
+                throw new Error(`Invalid sub-line in block mapping: "${subLine.trimmed}"`);
+              }
+            }
+          }
+        } else {
+          result.push(parseValue(rest));
+          idx++;
+        }
+      } else {
+        const colonIdx = line.trimmed.indexOf(':');
+        if (colonIdx === -1) {
+          throw new Error(`Invalid line: "${line.trimmed}"`);
+        }
+
+        const k = line.trimmed.slice(0, colonIdx).trim();
+        const rawVal = line.trimmed.slice(colonIdx + 1).trim();
+
+        if (rawVal === '') {
+          idx++;
+          result[k] = parseBlock(line.indent + 1);
+        } else {
+          result[k] = parseValue(rawVal);
+          idx++;
+        }
+      }
+    }
+
+    return result;
+  }
+
+  return parseBlock(0);
+}

package/src/commands/ultragoal.ts

@@ -0,0 +1,102 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { readWorkflowState, getLocalJocDir } from "../agent/state";
+import { bashTool } from "../agent/tools";
+
+export async function runUltragoalCommand(): Promise<void> {
+  const cwd = process.cwd();
+
+  // Read state to find acceptance criteria
+  const interviewState = await readWorkflowState("deep-interview", cwd);
+  if (!interviewState || !interviewState.seed_path) {
+    console.log(
+      `[ERROR] No crystallized requirements found. Please run 'joc deep-interview' first.`
+    );
+    return;
+  }
+
+  const seedPath = interviewState.seed_path;
+  console.log(`\n=== Starting Ultragoal Verification Stage ===`);
+  console.log(`Reading requirements and acceptance criteria from: ${seedPath}`);
+
+  let seedContent = "";
+  try {
+    seedContent = await fs.readFile(seedPath, "utf-8");
+  } catch (err: any) {
+    console.log(`[ERROR] Failed to read seed file: ${err.message}`);
+    return;
+  }
+
+  // Parse acceptance criteria from seed YAML
+  const criteria: string[] = [];
+  const lines = seedContent.split("\n");
+  let parsingCriteria = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("acceptance_criteria:")) {
+      parsingCriteria = true;
+      continue;
+    }
+    if (parsingCriteria) {
+      if (trimmed.startsWith("-")) {
+        criteria.push(trimmed.replace(/^-\s*/, "").replace(/"/g, "").trim());
+      } else if (trimmed === "" || trimmed.includes(":")) {
+        // End of list or next section
+        parsingCriteria = false;
+      }
+    }
+  }
+
+  if (criteria.length === 0) {
+    criteria.push("Runs successfully in the terminal");
+  }
+
+  console.log(`Loaded ${criteria.length} acceptance criteria for verification.\n`);
+
+  const results: { criterion: string; passed: boolean; output: string }[] = [];
+
+  for (const criterion of criteria) {
+    console.log(`[CHECK] Verifying: "${criterion}"`);
+    
+    // We can execute a automatic verification pass.
+    // E.g., if there are tests, we run bun test. If not, we do a smoke check by running bun src/cli.ts setup or compile.
+    let cmd = "bun test";
+    if (criterion.toLowerCase().includes("run") || criterion.toLowerCase().includes("cli")) {
+      cmd = "bun run src/cli.ts --help";
+    }
+
+    console.log(`  └─ Running validation command: '${cmd}'`);
+    const res = await bashTool(cmd, cwd);
+    
+    results.push({
+      criterion,
+      passed: res.success,
+      output: res.output.slice(0, 300) + (res.output.length > 300 ? "..." : "")
+    });
+
+    console.log(`  └─ Result: ${res.success ? "PASSED" : "FAILED"}`);
+  }
+
+  // Write verification report
+  const reportDir = path.join(getLocalJocDir(cwd), "state");
+  await fs.mkdir(reportDir, { recursive: true });
+  const reportPath = path.join(reportDir, "ultragoal-report.md");
+
+  const passedCount = results.filter(r => r.passed).length;
+  const totalCount = results.length;
+  const status = passedCount === totalCount ? "SUCCESS" : "DEGRADED";
+
+  const reportContent = 
+    `# Ultragoal Verification Report: ${interviewState.slug}\n` +
+    `Date: ${new Date().toISOString()}\n` +
+    `Status: ${status} (${passedCount}/${totalCount} criteria passed)\n\n` +
+    `## Criteria Verification Matrix\n` +
+    `| Criterion | Status | Verification Output |\n` +
+    `|---|---|---|\n` +
+    results.map(r => `| ${r.criterion} | ${r.passed ? "✅ PASSED" : "❌ FAILED"} | \`${r.output.replace(/\n/g, " ")}\` |`).join("\n") +
+    `\n`;
+
+  await fs.writeFile(reportPath, reportContent, "utf-8");
+  console.log(`\n[VERIFICATION COMPLETE] Report saved to: ${reportPath}`);
+  console.log(`Overall status: ${status} (${passedCount}/${totalCount} passed)`);
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export * from "./agent/state";
+export { callLlm } from "./agent/loop";
+export type { ChatOptions } from "./agent/loop";
+export * from "./agent/tools";
+export * from "./auth";
+export * from "./ai";
+export * from "./cli";
+export {
+  runMcpServer,
+  TOOLS,
+  PARSE_ERROR,
+  INVALID_REQUEST,
+  METHOD_NOT_FOUND,
+  INVALID_PARAMS,
+  INTERNAL_ERROR,
+  ok,
+  fail,
+} from "./mcp";
+export type {
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcError,
+  ToolDefinition,
+  ToolResult as McpToolResult,
+} from "./mcp";
+export * from "./commands/setup";
+export * from "./commands/auth";
+export * from "./commands/deep-interview";
+export * from "./commands/ralplan";
+export * from "./commands/team";
+export * from "./commands/ultragoal";

package/src/mcp/index.ts

@@ -0,0 +1,3 @@
+export * from "./protocol";
+export { TOOLS } from "./tools";
+export { runMcpServer } from "./server";

package/src/mcp/protocol.ts

@@ -0,0 +1,45 @@
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id?: number | string | null;
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: number | string | null;
+  result?: unknown;
+  error?: JsonRpcError;
+}
+
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: (args: Record<string, unknown>) => Promise<ToolResult>;
+}
+
+export interface ToolResult {
+  content: { type: "text"; text: string }[];
+  isError?: boolean;
+}
+
+export function ok(id: number | string | null, result: unknown): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, result };
+}
+
+export function fail(id: number | string | null, code: number, message: string, data?: unknown): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, error: { code, message, data } };
+}

package/src/mcp/server.ts

@@ -0,0 +1,97 @@
+import {
+  fail,
+  INTERNAL_ERROR,
+  INVALID_PARAMS,
+  INVALID_REQUEST,
+  METHOD_NOT_FOUND,
+  ok,
+  PARSE_ERROR,
+  type JsonRpcRequest,
+  type JsonRpcResponse,
+  type ToolDefinition,
+} from "./protocol";
+import { TOOLS } from "./tools";
+
+const SERVER_INFO = { name: "joc-mcp", version: "0.1.0" };
+const PROTOCOL_VERSION = "2024-11-05";
+
+interface ServerOptions {
+  tools?: ToolDefinition[];
+  log?: (line: string) => void;
+}
+
+export async function runMcpServer(options: ServerOptions = {}): Promise<void> {
+  const tools = options.tools ?? TOOLS;
+  const log = options.log ?? (line => process.stderr.write(`${line}\n`));
+  log(`joc-mcp v${SERVER_INFO.version} listening on stdio (${tools.length} tools)`);
+
+  let buffer = "";
+  const decoder = new TextDecoder();
+
+  for await (const chunk of (process.stdin as unknown as AsyncIterable<Uint8Array>)) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let newlineIndex: number;
+    while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, newlineIndex).trim();
+      buffer = buffer.slice(newlineIndex + 1);
+      if (!line) continue;
+      const response = await handleLine(line, tools);
+      if (response) writeResponse(response);
+    }
+  }
+}
+
+async function handleLine(line: string, tools: ToolDefinition[]): Promise<JsonRpcResponse | null> {
+  let req: JsonRpcRequest;
+  try {
+    req = JSON.parse(line) as JsonRpcRequest;
+  } catch {
+    return fail(null, PARSE_ERROR, "invalid JSON");
+  }
+  if (req.jsonrpc !== "2.0" || typeof req.method !== "string") {
+    return fail(req.id ?? null, INVALID_REQUEST, "malformed JSON-RPC request");
+  }
+
+  try {
+    switch (req.method) {
+      case "initialize":
+        return ok(req.id ?? null, {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: SERVER_INFO,
+        });
+      case "initialized":
+      case "notifications/initialized":
+        return null;
+      case "ping":
+        return ok(req.id ?? null, {});
+      case "tools/list":
+        return ok(req.id ?? null, {
+          tools: tools.map(t => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+          })),
+        });
+      case "tools/call":
+        return await handleToolCall(req, tools);
+      default:
+        return fail(req.id ?? null, METHOD_NOT_FOUND, `unknown method: ${req.method}`);
+    }
+  } catch (err) {
+    return fail(req.id ?? null, INTERNAL_ERROR, (err as Error).message);
+  }
+}
+
+async function handleToolCall(req: JsonRpcRequest, tools: ToolDefinition[]): Promise<JsonRpcResponse> {
+  const params = (req.params ?? {}) as { name?: string; arguments?: Record<string, unknown> };
+  if (!params.name) return fail(req.id ?? null, INVALID_PARAMS, "'name' is required");
+  const tool = tools.find(t => t.name === params.name);
+  if (!tool) return fail(req.id ?? null, METHOD_NOT_FOUND, `unknown tool: ${params.name}`);
+  const result = await tool.handler(params.arguments ?? {});
+  return ok(req.id ?? null, result);
+}
+
+function writeResponse(response: JsonRpcResponse): void {
+  process.stdout.write(`${JSON.stringify(response)}\n`);
+}