@splinterzzz/ouro 0.1.0

package/src/commands/stop.js

@@ -0,0 +1,39 @@
+import chalk from "chalk";
+import { SERVICES, stopService } from "../lib/daemon.js";
+
+// Stops the listener first, then the dashboard: the bot posts tickets to the
+// dashboard's API, so killing the dashboard first would leave the bot briefly
+// answering people with "couldn't reach the ouro dashboard".
+const ORDER = ["listen", "dashboard"];
+
+export async function stopCommand() {
+  const results = [];
+  for (const name of ORDER) {
+    results.push(await stopService(name));
+  }
+
+  for (const r of results) {
+    if (r.stopped) {
+      console.log(chalk.green("✔ stopped ") + chalk.gray(`${r.name} (pid ${r.pid})${r.forced ? " — forced" : ""}`));
+    } else if (r.reason === "not running") {
+      console.log(chalk.gray(`• ${r.name} wasn't running`));
+    } else {
+      console.log(chalk.yellow(`! ${r.name}: ${r.reason}`));
+    }
+  }
+
+  const stuck = results.filter((r) => !r.stopped && r.reason === "refused to die");
+  if (stuck.length) {
+    console.log("");
+    console.log(chalk.red("Some processes wouldn't stop. Kill them by pid manually:"));
+    for (const r of stuck) console.log(chalk.gray(`  ${r.name}: pid ${r.pid}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (results.every((r) => r.reason === "not running")) return;
+  console.log("");
+  console.log(chalk.gray("ouro is stopped. Any in-flight agent runs were killed with it."));
+}
+
+export { SERVICES };

package/src/index.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import { loadEnvFile } from "./lib/env.js";
+import { initCommand } from "./commands/init.js";
+import { dashboardCommand } from "./commands/dashboard.js";
+import { listenCommand } from "./commands/listen.js";
+import { startCommand } from "./commands/start.js";
+import { stopCommand } from "./commands/stop.js";
+import { statusCommand } from "./commands/status.js";
+import { logsCommand } from "./commands/logs.js";
+
+// Before any command reads a token: the detached daemon has no shell to
+// inherit exports from, so `.ouro/.env` is what survives a closed terminal or
+// a reboot. A real export still wins over the file. See lib/env.js.
+loadEnvFile();
+
+const program = new Command();
+
+program
+  .name("ouro")
+  .description(
+    "Loop engineering CLI — roots into your repo, gives you a kanban board\n" +
+      "and agents that run on your existing Claude Code / Codex subscription.\n" +
+      "No API key required."
+  )
+  .version("0.1.0");
+
+program
+  .command("init")
+  .description("Configure the current repo for ouro (creates .ouro/ config + ticket store)")
+  .option("--backend <backend>", "claude-code | codex", "claude-code")
+  .action(initCommand);
+
+program
+  .command("start")
+  .description("Start the dashboard + Telegram intake agent in the background (survives closing the terminal)")
+  .option("-p, --port <port>", "port to run the dashboard server on", "4747")
+  .option("--no-listen", "start only the dashboard, without the Telegram intake agent")
+  .action(startCommand);
+
+program.command("stop").description("Stop the background services and any agent runs they own").action(stopCommand);
+
+program
+  .command("restart")
+  .description("Stop, then start, the background services")
+  .option("-p, --port <port>", "port to run the dashboard server on", "4747")
+  .option("--no-listen", "start only the dashboard, without the Telegram intake agent")
+  .action(async (opts) => {
+    await stopCommand();
+    console.log("");
+    await startCommand(opts);
+  });
+
+program.command("status").description("Show what's running in the background").action(statusCommand);
+
+program
+  .command("logs [service]")
+  .description("Show background service logs (dashboard | listen)")
+  .option("-f, --follow", "keep printing new output as it arrives")
+  .option("-n, --lines <n>", "how many lines of history to show", "40")
+  .action(logsCommand);
+
+// The two foreground commands `start` supervises. Run them directly to watch a
+// service in this terminal — useful when debugging one that won't stay up.
+program
+  .command("dashboard")
+  .description("Run the dashboard in the foreground (see also: ouro start)")
+  .option("-p, --port <port>", "port to run the dashboard server on", "4747")
+  .option("--no-open", "don't auto-open the browser")
+  .action(dashboardCommand);
+
+program
+  .command("listen")
+  .description("Run the Telegram intake agent in the foreground (see also: ouro start)")
+  .action(listenCommand);
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(chalk.red("ouro: fatal error"), err);
+  process.exit(1);
+});

package/src/lib/agentBackend.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import { configPath } from "./paths.js";
+import * as codex from "./codexExec.js";
+import * as claudeCode from "./claudeCodeExec.js";
+
+const BACKENDS = {
+  codex,
+  "claude-code": claudeCode,
+};
+
+export function getBackendName() {
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath(), "utf-8"));
+    return BACKENDS[config.backend] ? config.backend : "claude-code";
+  } catch {
+    return "claude-code";
+  }
+}
+
+export function setBackendName(name) {
+  if (!BACKENDS[name]) throw new Error(`Unknown backend: ${name}`);
+  const config = JSON.parse(fs.readFileSync(configPath(), "utf-8"));
+  config.backend = name;
+  fs.writeFileSync(configPath(), JSON.stringify(config, null, 2));
+  return name;
+}
+
+function backend() {
+  return BACKENDS[getBackendName()];
+}
+
+// Unified interface — every route calls through here instead of importing
+// codexExec/claudeCodeExec directly, so switching backends is a one-line
+// config change picked up on the next call.
+export const triage = (args) => backend().triage(args);
+export const runAgent = (args) => backend().runAgent(args);
+export const planTicket = (args) => backend().planTicket(args);
+export const executeTicket = (args) => backend().executeTicket(args);
+// Read-only, JSON-in/JSON-out. Backs the Telegram intake interview, which
+// needs a cheap per-turn decision rather than a full agent run.
+export const askJson = (args) => backend().askJson(args);

package/src/lib/agents.js

@@ -0,0 +1,251 @@
+import fs from "node:fs";
+import path from "node:path";
+import { EventEmitter } from "node:events";
+import { agentsDir, ensureOuroDir } from "./paths.js";
+import { parseFrontmatter, stringifyFrontmatter } from "./frontmatter.js";
+
+// Agents are plain markdown on disk — `.ouro/agents/<id>.md` — so they're
+// diffable, reviewable in a PR, and editable in your editor without ouro
+// running. The dashboard is just one writer among several; every read goes
+// back to the filesystem rather than an in-memory cache, so a file edited
+// behind ouro's back shows up on the next request instead of being clobbered.
+
+export const TOOL_UNIVERSE = ["Read", "Grep", "Glob", "Edit", "Write", "Bash", "WebFetch", "WebSearch"];
+
+// Tools that can mutate the worktree or reach the network. Surfaced with a
+// warning affordance in the UI so granting them is a deliberate act.
+export const DANGER_TOOLS = new Set(["Edit", "Write", "Bash", "WebFetch", "WebSearch"]);
+
+const DEFAULT_MODEL = "sonnet";
+const DEFAULT_GLYPH = "◆";
+const DEFAULT_TOOLS = ["Read", "Grep", "Glob", "Edit", "Write", "Bash"];
+
+export const agentEvents = new EventEmitter();
+
+/** `Senior Engineer` -> `senior-engineer`. Also the filename stem. */
+export function slugify(name) {
+  const slug = String(name ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return slug || "agent";
+}
+
+function agentPath(id) {
+  return path.join(agentsDir(), `${id}.md`);
+}
+
+/** Guards against `id` escaping .ouro/agents via `../` or an absolute path. */
+function assertSafeId(id) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(String(id ?? ""))) {
+    throw new Error(`Invalid agent id: ${id}`);
+  }
+}
+
+function toAgent(id, text) {
+  const { data, body } = parseFrontmatter(text);
+  const tools = Array.isArray(data.tools)
+    ? data.tools
+    : typeof data.tools === "string" && data.tools.trim()
+      ? data.tools.split(/[,\s]+/).filter(Boolean)
+      : DEFAULT_TOOLS;
+
+  return {
+    id,
+    name: data.name || id,
+    glyph: data.glyph || DEFAULT_GLYPH,
+    description: data.description || "",
+    model: data.model || DEFAULT_MODEL,
+    tools,
+    systemPrompt: body,
+  };
+}
+
+export function listAgents() {
+  ensureOuroDir();
+  let files = [];
+  try {
+    files = fs.readdirSync(agentsDir()).filter((f) => f.endsWith(".md"));
+  } catch {
+    return [];
+  }
+
+  return files
+    .map((file) => {
+      const id = file.replace(/\.md$/, "");
+      try {
+        return toAgent(id, fs.readFileSync(path.join(agentsDir(), file), "utf-8"));
+      } catch {
+        return null; // an unreadable file shouldn't blank the whole list
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function getAgent(id) {
+  assertSafeId(id);
+  try {
+    return toAgent(id, fs.readFileSync(agentPath(id), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Raw file text — backs the dashboard's "edit as .md" mode. */
+export function getAgentRaw(id) {
+  assertSafeId(id);
+  try {
+    return fs.readFileSync(agentPath(id), "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function write(id, text) {
+  ensureOuroDir();
+  fs.writeFileSync(agentPath(id), text);
+  const agent = getAgent(id);
+  agentEvents.emit("change", { type: "agent", agent, id });
+  return agent;
+}
+
+/** Writes hand-authored markdown through verbatim, after a parse sanity check. */
+export function saveAgentRaw(id, text) {
+  assertSafeId(id);
+  parseFrontmatter(text); // throws only on truly broken input; keeps bad files out
+  return write(id, text);
+}
+
+export function saveAgent(id, patch) {
+  assertSafeId(id);
+  const current = getAgent(id);
+  if (!current) return null;
+
+  const next = { ...current, ...patch };
+  return write(
+    id,
+    stringifyFrontmatter(
+      {
+        name: next.name,
+        glyph: next.glyph,
+        description: next.description,
+        model: next.model,
+        tools: next.tools,
+      },
+      next.systemPrompt
+    )
+  );
+}
+
+export function createAgent({ name }) {
+  ensureOuroDir();
+  const base = slugify(name);
+
+  // Never overwrite an existing agent — suffix until the name is free.
+  let id = base;
+  for (let i = 2; fs.existsSync(agentPath(id)); i++) id = `${base}-${i}`;
+
+  return write(
+    id,
+    stringifyFrontmatter(
+      {
+        name: name || id,
+        glyph: DEFAULT_GLYPH,
+        description: "",
+        model: DEFAULT_MODEL,
+        tools: DEFAULT_TOOLS,
+      },
+      `You are ${name || id}. Describe how this agent should work here — this body is sent to the model as its system prompt.`
+    )
+  );
+}
+
+export function deleteAgent(id) {
+  assertSafeId(id);
+  try {
+    fs.unlinkSync(agentPath(id));
+    agentEvents.emit("change", { type: "agent-deleted", id });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Shipped defaults. Written only when `.ouro/agents/` has no files at all, so
+// `ouro init` in an existing repo never resurrects an agent you deleted.
+const SEEDS = [
+  {
+    id: "senior-engineer",
+    data: {
+      name: "Senior Engineer",
+      glyph: "◆",
+      description: "Ships production changes with minimal, well-tested diffs.",
+      model: DEFAULT_MODEL,
+      tools: ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
+    },
+    body: `You are a senior engineer working in an isolated git worktree.
+
+Work to these standards:
+- Read the surrounding code before you edit it. Match its idiom, naming, and comment density.
+- Prefer the smallest diff that fully solves the ticket. No drive-by refactors.
+- Never delete or weaken a test to make something pass.
+- Run the relevant tests before you call the work done, and report what you ran.
+- If the ticket is ambiguous, state the assumption you made in your final message rather than guessing silently.`,
+  },
+  {
+    id: "bug-fixer",
+    data: {
+      name: "Bug Fixer",
+      glyph: "▲",
+      description: "Reproduces first, then fixes the root cause — not the symptom.",
+      model: DEFAULT_MODEL,
+      tools: ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
+    },
+    body: `You are a debugging specialist working in an isolated git worktree.
+
+Method, in order:
+1. Reproduce the bug and state the exact failing behaviour you observed.
+2. Find the root cause. Trace it — do not pattern-match a plausible-looking fix.
+3. Fix the cause, not the symptom. If the real fix is out of scope, say so explicitly.
+4. Add or extend a test that fails before your change and passes after it.
+5. Report the reproduction, the cause, and the fix separately in your final message.`,
+  },
+  {
+    id: "reviewer",
+    data: {
+      name: "Reviewer",
+      glyph: "○",
+      description: "Read-only. Audits a diff for correctness and risk.",
+      model: DEFAULT_MODEL,
+      tools: ["Read", "Grep", "Glob"],
+    },
+    body: `You are a code reviewer. You have read-only tools — you cannot edit, and should not try.
+
+Review for, in priority order:
+1. Correctness bugs that would fail at runtime.
+2. Missing or weakened test coverage.
+3. Unnecessary complexity that a simpler construct would cover.
+
+For each finding give: the file and line, what breaks, and the concrete input or state that triggers it. Skip anything you cannot substantiate — a speculative finding is worse than no finding.`,
+  },
+];
+
+export function seedDefaultAgents() {
+  ensureOuroDir();
+  const existing = fs.existsSync(agentsDir()) ? fs.readdirSync(agentsDir()).filter((f) => f.endsWith(".md")) : [];
+  if (existing.length > 0) return 0;
+
+  for (const seed of SEEDS) {
+    fs.writeFileSync(agentPath(seed.id), stringifyFrontmatter(seed.data, seed.body));
+  }
+  return SEEDS.length;
+}
+
+/** The agent a ticket runs as when it has no explicit assignment. */
+export function defaultAgentId() {
+  const all = listAgents();
+  if (all.length === 0) return null;
+  return (all.find((a) => a.id === "senior-engineer") ?? all[0]).id;
+}

package/src/lib/claudeCodeExec.js

@@ -0,0 +1,213 @@
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+
+/**
+ * NOTE, same caveat as codexExec.js: field names in Claude Code's
+ * stream-json events (`type`, `subtype`, `session_id`, `result`) are based
+ * on public docs, not verified against a live run in this environment.
+ * Run `claude -p "say hello" --output-format stream-json --verbose` once and
+ * diff against `parseLine()`/the close handler below before relying on this.
+ */
+
+const CLAUDE_BIN = process.env.OURO_CLAUDE_BIN || "claude";
+
+const READ_ONLY_TOOLS = ["Read", "Grep", "Glob"];
+const DEFAULT_WRITE_TOOLS = ["Read", "Edit", "Write", "Bash", "Grep", "Glob"];
+
+function parseLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return { type: "raw", text: line };
+  }
+}
+
+/**
+ * Turns an agent (from `.ouro/agents/*.md`) into CLI flags. `restrictTo`
+ * intersects the agent's granted tools with what the phase permits, so a
+ * plan phase stays read-only even if the agent is granted Write — the agent
+ * file widens what's possible, never what a read-only phase allows.
+ */
+function agentFlags(agent, restrictTo) {
+  if (!agent) {
+    return restrictTo ? ["--allowedTools", restrictTo.join(",")] : [];
+  }
+
+  const granted = agent.tools?.length ? agent.tools : DEFAULT_WRITE_TOOLS;
+  const allowed = restrictTo ? granted.filter((t) => restrictTo.includes(t)) : granted;
+
+  const flags = [];
+  if (allowed.length) flags.push("--allowedTools", allowed.join(","));
+  if (agent.model) flags.push("--model", agent.model);
+  // Append rather than replace: Claude Code's own system prompt carries the
+  // tool contract, so blowing it away with --system-prompt breaks tool use.
+  if (agent.systemPrompt?.trim()) flags.push("--append-system-prompt", agent.systemPrompt.trim());
+  return flags;
+}
+
+function runClaude(args, { cwd, onEvent, signal } = {}) {
+  return new Promise((resolve, reject) => {
+    // `signal` wires cancellation straight to the child: aborting SIGTERMs the
+    // CLI rather than leaving it running detached. See lib/runs.js.
+    const proc = spawn(CLAUDE_BIN, args, { cwd, env: process.env, signal });
+
+    const rl = readline.createInterface({ input: proc.stdout });
+    let sessionId = null;
+    let lastMessage = null;
+
+    rl.on("line", (line) => {
+      if (!line.trim()) return;
+      const event = parseLine(line);
+      if (event.session_id) sessionId = event.session_id;
+      if (event.type === "result") {
+        lastMessage = event.result ?? lastMessage;
+      }
+      onEvent?.(event);
+    });
+
+    let stderrBuf = "";
+    proc.stderr.on("data", (chunk) => {
+      stderrBuf += chunk.toString();
+      onEvent?.({ type: "stderr", text: chunk.toString() });
+    });
+
+    proc.on("error", (err) => {
+      // An abort surfaces here as ABORT_ERR — that's an expected cancel, not a
+      // crash, so it resolves rather than rejecting into the route's catch.
+      if (err.name === "AbortError" || signal?.aborted) {
+        resolve({ code: null, sessionId, lastMessage, stderr: stderrBuf, aborted: true });
+        return;
+      }
+      reject(err);
+    });
+
+    proc.on("close", (code) => {
+      resolve({ code, sessionId, lastMessage, stderr: stderrBuf, aborted: Boolean(signal?.aborted) });
+    });
+  });
+}
+
+/** Strips ``` fences a model sometimes wraps JSON in, then parses. */
+function parseJsonish(text) {
+  const cleaned = String(text ?? "").replace(/```json|```/g, "").trim();
+  try {
+    return JSON.parse(cleaned);
+  } catch {
+    // Fall back to the outermost {...} in case prose leaked in around it.
+    const start = cleaned.indexOf("{");
+    const end = cleaned.lastIndexOf("}");
+    if (start !== -1 && end > start) {
+      try {
+        return JSON.parse(cleaned.slice(start, end + 1));
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+}
+
+/**
+ * One-shot, read-only, JSON-in/JSON-out call. Backs the Telegram intake
+ * interview (lib/intake.js), which needs a cheap turn-by-turn decision and no
+ * repo writes. Returns null when the model didn't produce parseable JSON, so
+ * callers decide the fallback rather than getting a half-object.
+ */
+export async function askJson({ prompt, cwd, signal }) {
+  const { lastMessage } = await runClaude(
+    ["-p", prompt, "--output-format", "stream-json", "--verbose", "--allowedTools", READ_ONLY_TOOLS.join(",")],
+    { cwd, signal }
+  );
+  return parseJsonish(lastMessage);
+}
+
+/**
+ * Triage: read-only tools only, no file writes. Claude Code doesn't have a
+ * sandbox flag like Codex — read-only-ness comes from restricting
+ * --allowedTools instead.
+ */
+export async function triage({ prompt, cwd, signal }) {
+  const { lastMessage } = await runClaude(
+    [
+      "-p",
+      `${prompt}\n\nRespond with ONLY a JSON object: {"summary": string, "priority": "low"|"medium"|"high", "files_likely_affected": string[]}. No prose, no markdown fences.`,
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      "--allowedTools",
+      READ_ONLY_TOOLS.join(","),
+    ],
+    { cwd, signal }
+  );
+
+  return (
+    parseJsonish(lastMessage) ?? {
+      summary: lastMessage ?? "(no summary returned)",
+      priority: "medium",
+      files_likely_affected: [],
+    }
+  );
+}
+
+/**
+ * Agent mode: full autonomy, write tools allowed, no interactive approval.
+ * Tools/model/system prompt come from the ticket's assigned agent .md.
+ */
+export function runAgent({ prompt, cwd, onEvent, signal, agent }) {
+  return runClaude(
+    [
+      "-p",
+      prompt,
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      ...agentFlags(agent, null),
+      ...(agent ? [] : ["--allowedTools", DEFAULT_WRITE_TOOLS.join(",")]),
+      "--permission-mode",
+      "bypassPermissions",
+    ],
+    { cwd, onEvent, signal }
+  );
+}
+
+/**
+ * Human-in-the-loop, phase 1: plan only, read-only tools, no edits. Returns
+ * the session_id so the UI can resume it once the person approves.
+ */
+export function planTicket({ prompt, cwd, onEvent, signal, agent }) {
+  return runClaude(
+    [
+      "-p",
+      `${prompt}\n\nDo NOT edit any files yet. First produce a short numbered plan of what you'd change and why.`,
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      ...agentFlags(agent, READ_ONLY_TOOLS),
+      ...(agent ? [] : ["--allowedTools", READ_ONLY_TOOLS.join(",")]),
+    ],
+    { cwd, onEvent, signal }
+  );
+}
+
+/**
+ * Human-in-the-loop, phase 2: resume the planning session with write tools
+ * enabled, after the person clicks Approve.
+ */
+export function executeTicket({ cwd, sessionId, onEvent, signal, agent }) {
+  return runClaude(
+    [
+      "--resume",
+      sessionId,
+      "-p",
+      "Approved. Implement the plan now and run relevant tests.",
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      ...agentFlags(agent, null),
+      ...(agent ? [] : ["--allowedTools", DEFAULT_WRITE_TOOLS.join(",")]),
+      "--permission-mode",
+      "acceptEdits",
+    ],
+    { cwd, onEvent, signal }
+  );
+}