@splinterzzz/ouro 0.1.0

package/src/lib/codexExec.js

@@ -0,0 +1,204 @@
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * NOTE on the JSONL event shape: `codex exec --json` emits one JSON object
+ * per line to stdout. Field names below (`type`, `item.text`, `msg`, etc.)
+ * are based on public docs/community usage as of build time, not a locked
+ * spec — Codex's event schema has moved before. First thing to do when you
+ * sit down: run `codex exec --json "say hello"` once and diff the real
+ * output against the parsing in `parseLine()` below, then adjust. Don't
+ * build the rest of the pipeline on top of an unverified assumption here.
+ */
+
+const CODEX_BIN = process.env.OURO_CODEX_BIN || "codex";
+
+const TRIAGE_SCHEMA = {
+  type: "object",
+  properties: {
+    summary: { type: "string" },
+    priority: { type: "string", enum: ["low", "medium", "high"] },
+    files_likely_affected: { type: "array", items: { type: "string" } },
+  },
+  required: ["summary", "priority", "files_likely_affected"],
+  additionalProperties: false,
+};
+
+function parseLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    // Non-JSON stderr-ish noise sometimes rides along on stdout depending on
+    // version; surface it as a raw event instead of crashing the parser.
+    return { type: "raw", text: line };
+  }
+}
+
+/**
+ * Codex takes the agent's system prompt as a config override rather than a
+ * flag, and has no per-tool grant model — the sandbox mode governs writes.
+ * So an agent's tool list is advisory on this backend; it's the Claude Code
+ * path (--allowedTools) where it's enforced.
+ */
+function agentFlags(agent) {
+  if (!agent) return [];
+  const flags = [];
+  if (agent.model) flags.push("--model", agent.model);
+  if (agent.systemPrompt?.trim()) {
+    flags.push("-c", `experimental_instructions=${JSON.stringify(agent.systemPrompt.trim())}`);
+  }
+  return flags;
+}
+
+/**
+ * Runs `codex exec` and streams parsed JSONL events to `onEvent`.
+ * Resolves with { code, sessionId, lastMessage } when the process exits.
+ */
+function runCodexExec(args, { cwd, onEvent, signal } = {}) {
+  return new Promise((resolve, reject) => {
+    // `signal` makes cancellation kill the child process. See lib/runs.js.
+    const proc = spawn(CODEX_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" || event.subtype === "success") {
+        lastMessage = event.result ?? event.text ?? lastMessage;
+      }
+      onEvent?.(event);
+    });
+
+    let stderrBuf = "";
+    proc.stderr.on("data", (chunk) => {
+      stderrBuf += chunk.toString();
+      onEvent?.({ type: "stderr", text: chunk.toString() });
+    });
+
+    proc.on("error", (err) => {
+      // Abort is an expected cancel, not a crash — resolve so the route can
+      // mark the ticket cancelled instead of erroring.
+      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) });
+    });
+  });
+}
+
+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;
+  }
+}
+
+/** Read-only JSON-in/JSON-out call — backs the Telegram intake interview. */
+export async function askJson({ prompt, cwd, signal }) {
+  const { lastMessage } = await runCodexExec(["exec", prompt, "--json", "--sandbox", "read-only"], { cwd, signal });
+  return parseJsonish(lastMessage);
+}
+
+/**
+ * Triage: read-only, schema-constrained call. Cheap, safe, no repo writes.
+ */
+export async function triage({ prompt, cwd, signal }) {
+  // os.tmpdir(), not a hardcoded /tmp — this has to work on Windows too. The
+  // pid suffix keeps concurrent triages off one another's schema file.
+  const schemaPath = path.join(os.tmpdir(), `ouro-triage-schema-${process.pid}.json`);
+  fs.writeFileSync(schemaPath, JSON.stringify(TRIAGE_SCHEMA));
+
+  try {
+    const { lastMessage } = await runCodexExec(
+      ["exec", prompt, "--json", "--sandbox", "read-only", "--output-schema", schemaPath],
+      { cwd, signal }
+    );
+
+    return (
+      parseJsonish(lastMessage) ?? {
+        summary: lastMessage ?? "(no summary returned)",
+        priority: "medium",
+        files_likely_affected: [],
+      }
+    );
+  } finally {
+    fs.rmSync(schemaPath, { force: true });
+  }
+}
+
+/**
+ * Agent mode: full autonomy within the worktree, workspace-write sandbox,
+ * auto-approved. `onEvent` should be wired to the ticket's log + WS broadcast.
+ */
+export function runAgent({ prompt, cwd, onEvent, signal, agent }) {
+  return runCodexExec(
+    ["exec", prompt, "--json", "--sandbox", "workspace-write", "--full-auto", ...agentFlags(agent)],
+    { cwd, onEvent, signal }
+  );
+}
+
+/**
+ * Human-in-the-loop, phase 1: plan only, read-only sandbox, no writes.
+ * Non-interactive headless mode can't reliably pause mid-run for approval
+ * (an unapproved action just fails the run rather than blocking on it), so
+ * instead we do two full calls: plan (read-only) -> show on card -> approve
+ * -> execute (write-enabled, resumed from the same session).
+ */
+export function planTicket({ prompt, cwd, onEvent, signal, agent }) {
+  return runCodexExec(
+    [
+      "exec",
+      `${prompt}\n\nDo not edit any files yet. First produce a short numbered plan of what you'd change and why.`,
+      "--json",
+      "--sandbox",
+      "read-only",
+      ...agentFlags(agent),
+    ],
+    { cwd, onEvent, signal }
+  );
+}
+
+/**
+ * Human-in-the-loop, phase 2: resume the planning session with a
+ * write-enabled sandbox, after the person clicks Approve.
+ */
+export function executeTicket({ cwd, sessionId, onEvent, signal, agent }) {
+  return runCodexExec(
+    [
+      "exec",
+      "resume",
+      sessionId ?? "--last",
+      "Approved. Implement the plan now and run relevant tests.",
+      "--json",
+      "--sandbox",
+      "workspace-write",
+      "--full-auto",
+      ...agentFlags(agent),
+    ],
+    { cwd, onEvent, signal }
+  );
+}

package/src/lib/config.js

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import { configPath } from "./paths.js";
+import { maskToken } from "./telegram.js";
+
+// `.ouro/config.json` is the one piece of state a human is expected to hand-edit,
+// so reads are always fresh from disk and writes merge rather than replace —
+// an unknown key someone added by hand survives a dashboard toggle.
+
+const DEFAULTS = {
+  version: 1,
+  backend: "claude-code",
+  defaultMode: "human", // safe default: plan first, write only after approval
+  // Commit + push + open a PR automatically once a run finishes with changes.
+  // On by default so a run ends somewhere a human can review it, rather than
+  // as an unpushed branch in a local worktree. Set false to require the
+  // explicit "Create PR" button instead — pushing is outward-facing, so this
+  // is deliberately a knob and not a hardcode.
+  autoShip: true,
+  telegram: {
+    botTokenEnvVar: "OURO_TELEGRAM_BOT_TOKEN",
+    chatIdEnvVar: "OURO_TELEGRAM_CHAT_ID",
+  },
+};
+
+export function readConfig() {
+  try {
+    return { ...DEFAULTS, ...JSON.parse(fs.readFileSync(configPath(), "utf-8")) };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+export function writeConfig(patch) {
+  const next = { ...readConfig(), ...patch };
+  fs.writeFileSync(configPath(), JSON.stringify(next, null, 2));
+  return next;
+}
+
+export const DEFAULT_TELEGRAM_TOKEN_VAR = "OURO_TELEGRAM_BOT_TOKEN";
+
+const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * The *name* of the env var holding the bot token — never the token itself.
+ *
+ * Returns `{ name, error? }`. The error case is a real one people hit: the key
+ * reads like somewhere to put a token, so a token goes in it, and every caller
+ * then looks up process.env["8123:AA…"], finds undefined, and reports
+ * "8123:AA… is not set" — which blames the token for the config's mistake.
+ * Worse, config.json is committed on purpose (that's the point of
+ * agents-as-files), so a token parked here is a token headed for git history.
+ */
+export function telegramTokenVar() {
+  const value = readConfig().telegram?.botTokenEnvVar;
+  if (!value) return { name: DEFAULT_TELEGRAM_TOKEN_VAR };
+  if (ENV_VAR_NAME.test(value)) return { name: value };
+
+  // Newlines rather than one long string: this is printed to a terminal by two
+  // commands and rendered in the dashboard, and none of them own a wrapper.
+  return {
+    name: DEFAULT_TELEGRAM_TOKEN_VAR,
+    error: [
+      `.ouro/config.json has telegram.botTokenEnvVar set to "${maskToken(value)}".`,
+      `That field takes the NAME of the env var holding your token — "${DEFAULT_TELEGRAM_TOKEN_VAR}" — not the token itself.`,
+      `config.json is committed on purpose, so treat that token as exposed: revoke it via @BotFather, set the field back`,
+      `to "${DEFAULT_TELEGRAM_TOKEN_VAR}", and put the new token in .ouro/.env (gitignored) or the dashboard's Settings screen.`,
+    ].join("\n"),
+  };
+}
+
+export const MODES = ["human", "agent"];
+
+export function getDefaultMode() {
+  const mode = readConfig().defaultMode;
+  return MODES.includes(mode) ? mode : "human";
+}
+
+export function setDefaultMode(mode) {
+  if (!MODES.includes(mode)) throw new Error(`Unknown mode: ${mode}`);
+  writeConfig({ defaultMode: mode });
+  return mode;
+}
+
+export function getAutoShip() {
+  return readConfig().autoShip !== false;
+}
+
+export function setAutoShip(on) {
+  writeConfig({ autoShip: Boolean(on) });
+  return Boolean(on);
+}

package/src/lib/daemon.js

@@ -0,0 +1,235 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { runDir, logsDir, repoRoot, ensureOuroDir } from "./paths.js";
+
+// Background process supervision for `ouro start` / `ouro stop`.
+//
+// Deliberately not pm2/forever/systemd: ouro is a single-operator tool that
+// roots into one repo, and a pid file plus a detached spawn is the whole job.
+// Adding a process manager would mean a global daemon with its own state,
+// which is exactly the thing ouro avoids everywhere else.
+//
+// The two services:
+//   dashboard — Express + WS, holds ticket state, spawns agent CLIs
+//   listen    — Telegram intake agent, talks to the dashboard over HTTP
+// They're separate processes so restarting the bot can't drop board state,
+// which is the same split the foreground commands already had.
+
+export const SERVICES = ["dashboard", "listen"];
+
+const CLI_ENTRY = fileURLToPath(new URL("../index.js", import.meta.url));
+
+// A 24/7 process writes logs forever. Rotate one generation at start; two
+// files bounded at 5MB is plenty to debug "why did the bot stop overnight",
+// and beats either unbounded growth or a logrotate dependency.
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
+
+function pidFile(name) {
+  return path.join(runDir(), `${name}.json`);
+}
+
+export function logFile(name) {
+  return path.join(logsDir(), `${name}.log`);
+}
+
+export function readRecord(name) {
+  try {
+    return JSON.parse(fs.readFileSync(pidFile(name), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeRecord(name, record) {
+  ensureOuroDir();
+  fs.writeFileSync(pidFile(name), JSON.stringify(record, null, 2));
+}
+
+export function clearRecord(name) {
+  fs.rmSync(pidFile(name), { force: true });
+}
+
+/** Merges fields into an existing record — e.g. the port, once it's confirmed. */
+export function updateRecord(name, patch) {
+  const current = readRecord(name);
+  if (!current) return null;
+  const next = { ...current, ...patch };
+  writeRecord(name, next);
+  return next;
+}
+
+/** Signal 0 probes for existence without delivering anything. */
+export function isAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means it exists but is owned by someone else — still alive.
+    return err.code === "EPERM";
+  }
+}
+
+/**
+ * A pid file whose process is gone is stale — from a reboot, or a crash. Clean
+ * it up on read so `status` and `start` never trust a recycled pid.
+ */
+export function serviceStatus(name) {
+  const record = readRecord(name);
+  if (!record) return { name, running: false };
+
+  if (!isAlive(record.pid)) {
+    clearRecord(name);
+    return { name, running: false, stale: true };
+  }
+  return { name, running: true, ...record };
+}
+
+export function statusAll() {
+  return SERVICES.map(serviceStatus);
+}
+
+function rotate(file) {
+  try {
+    if (fs.statSync(file).size > MAX_LOG_BYTES) fs.renameSync(file, `${file}.1`);
+  } catch {
+    // No log yet, or a Windows lock — not worth failing a start over.
+  }
+}
+
+/**
+ * Spawns a service detached from this terminal.
+ *
+ * `detached: true` puts the child in its own process group (POSIX) / process
+ * tree root (Windows), which is what lets it outlive the shell — and what
+ * lets stopService kill its agent grandchildren later. stdout/stderr go to a
+ * file rather than a pipe, because a pipe with no reader fills its buffer and
+ * wedges the child once the parent exits.
+ */
+export function startService(name, args = []) {
+  ensureOuroDir();
+  const file = logFile(name);
+  rotate(file);
+
+  // Where this run's output starts. Logs are append-only across restarts, so
+  // without this a failed start would tail yesterday's errors and send you
+  // debugging a problem you already fixed.
+  const logOffset = fs.existsSync(file) ? fs.statSync(file).size : 0;
+
+  const fd = fs.openSync(file, "a");
+  try {
+    const child = spawn(process.execPath, [CLI_ENTRY, name, ...args], {
+      cwd: repoRoot(),
+      detached: true,
+      windowsHide: true, // no flashing console window on Windows
+      stdio: ["ignore", fd, fd],
+      env: process.env,
+    });
+    child.unref(); // don't hold this CLI's event loop open
+
+    const record = { pid: child.pid, startedAt: new Date().toISOString(), args, logOffset };
+    writeRecord(name, record);
+    return record;
+  } finally {
+    fs.closeSync(fd); // the child holds its own dup of the fd
+  }
+}
+
+function killTree(pid) {
+  if (process.platform === "win32") {
+    // /T kills the whole tree. Without it, a running `claude` child is
+    // orphaned and keeps burning subscription tokens with nothing watching it.
+    spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore" });
+    return;
+  }
+  // Negative pid targets the process group — same reasoning as /T above.
+  try {
+    process.kill(-pid, "SIGTERM");
+  } catch {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      // already gone
+    }
+  }
+}
+
+function forceKillTree(pid) {
+  if (process.platform === "win32") return; // taskkill /F was already forceful
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // already gone
+    }
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Stops a service and its children. Returns what actually happened so the
+ * command can report honestly rather than always printing "stopped".
+ */
+export async function stopService(name, { timeoutMs = 5000 } = {}) {
+  const record = readRecord(name);
+  if (!record) return { name, stopped: false, reason: "not running" };
+
+  if (!isAlive(record.pid)) {
+    clearRecord(name);
+    return { name, stopped: false, reason: "stale pid file (process already gone)" };
+  }
+
+  killTree(record.pid);
+
+  // Give it a moment to go down cleanly; the dashboard flushes its store and
+  // cancels in-flight runs on SIGTERM (POSIX). Windows has no real signals, so
+  // taskkill /F is immediate — the store's debounced write and the
+  // in_progress→cancelled reconciliation on next boot cover that gap.
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isAlive(record.pid)) {
+      clearRecord(name);
+      return { name, stopped: true, pid: record.pid };
+    }
+    await sleep(100);
+  }
+
+  forceKillTree(record.pid);
+  await sleep(200);
+
+  const gone = !isAlive(record.pid);
+  if (gone) clearRecord(name);
+  return { name, stopped: gone, pid: record.pid, forced: true, ...(gone ? {} : { reason: "refused to die" }) };
+}
+
+/**
+ * Last N lines of a service log. `fromOffset` limits it to output written
+ * after a given byte position — pass a start record's `logOffset` to show only
+ * the run that just failed, rather than the whole file's history.
+ */
+export function tailLog(name, lines = 20, fromOffset = 0) {
+  try {
+    let text = fs.readFileSync(logFile(name), "utf-8");
+    if (fromOffset > 0) text = Buffer.from(text, "utf-8").subarray(fromOffset).toString("utf-8");
+    return text.split(/\r?\n/).filter(Boolean).slice(-lines);
+  } catch {
+    return [];
+  }
+}
+
+export function uptime(startedAt) {
+  const ms = Date.now() - new Date(startedAt).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return "?";
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  return `${Math.floor(h / 24)}d ${h % 24}h`;
+}

package/src/lib/env.js

@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import { envPath, ensureOuroDir } from "./paths.js";
+
+// `.ouro/.env` — secrets for the background services.
+//
+// `ouro start` detaches the daemon from the shell that launched it, so the
+// daemon can't inherit a token you only exported in that shell: close the
+// terminal, or reboot, and `ouro listen` comes back up with no token and dies.
+// A file the daemon reads at startup is what makes 24/7 actually 24/7.
+//
+// Gitignored by `ouro init` (see .ouro/.gitignore) — it holds a bot token.
+
+// Group 1 is the `export ` prefix, kept so a rewrite can put it back — this is
+// somebody's hand-written file, not a generated one.
+const LINE = /^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/;
+
+function unquote(value) {
+  const v = value.trim();
+  if (v.length >= 2 && ((v[0] === '"' && v.at(-1) === '"') || (v[0] === "'" && v.at(-1) === "'"))) {
+    return v.slice(1, -1);
+  }
+  // An unquoted trailing `# comment` isn't part of the value.
+  return v.split(" #")[0].trim();
+}
+
+export function parseEnv(text) {
+  const out = {};
+  for (const line of String(text ?? "").split(/\r?\n/)) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const match = line.match(LINE);
+    if (match) out[match[2]] = unquote(match[3]);
+  }
+  return out;
+}
+
+/**
+ * Loads `.ouro/.env` into process.env. A real shell export always wins — if
+ * you deliberately set a token for one invocation, a stale file shouldn't
+ * silently override it.
+ */
+export function loadEnvFile() {
+  let text;
+  try {
+    text = fs.readFileSync(envPath(), "utf-8");
+  } catch {
+    return {}; // no file is the normal case, not an error
+  }
+
+  const vars = parseEnv(text);
+  for (const [key, value] of Object.entries(vars)) {
+    if (process.env[key] === undefined) process.env[key] = value;
+  }
+  return vars;
+}
+
+export function hasEnvFile() {
+  return fs.existsSync(envPath());
+}
+
+/** What's actually in the file, without touching process.env. */
+export function readEnvVars() {
+  try {
+    return parseEnv(fs.readFileSync(envPath(), "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+const HEADER = [
+  "# ouro secrets — read by the background services at startup.",
+  "# Gitignored (.ouro/.gitignore). Written by the dashboard's Settings screen,",
+  "# and safe to hand-edit: comments and unknown keys survive a save.",
+  "",
+];
+
+// Bare words don't need quoting; anything with whitespace, a `#`, or a quote
+// would come back wrong through unquote(), so it goes through JSON.
+function serialize(value) {
+  const v = String(value);
+  return /^[A-Za-z0-9_\-.:/@+=]*$/.test(v) ? v : JSON.stringify(v);
+}
+
+/**
+ * Merges vars into `.ouro/.env`. A `null` value deletes the key.
+ *
+ * Rewrites lines in place rather than regenerating the file, because this file
+ * has two authors: the dashboard and a human with an editor. Comments, order,
+ * `export ` prefixes and keys ouro knows nothing about all outlive a save.
+ */
+export function writeEnvVars(patch) {
+  ensureOuroDir();
+
+  let existing = null;
+  try {
+    existing = fs.readFileSync(envPath(), "utf-8");
+  } catch {
+    // No file yet — the header is what tells whoever opens it later what it is.
+  }
+
+  const pending = new Map(Object.entries(patch));
+  const next = [];
+
+  for (const line of existing === null ? HEADER : existing.split(/\r?\n/)) {
+    const match = line.trim().startsWith("#") ? null : line.match(LINE);
+    const key = match?.[2];
+    if (!key || !pending.has(key)) {
+      next.push(line);
+      continue;
+    }
+    const value = pending.get(key);
+    pending.delete(key);
+    if (value !== null) next.push(`${match[1]}${key}=${serialize(value)}`);
+  }
+
+  for (const [key, value] of pending) {
+    if (value !== null) next.push(`${key}=${serialize(value)}`);
+  }
+
+  while (next.length && !next.at(-1).trim()) next.pop(); // no growing tail of blanks
+
+  // 0600 applies on create only, which is the case that matters: a token
+  // shouldn't land world-readable in the first place.
+  fs.writeFileSync(envPath(), next.join("\n") + "\n", { mode: 0o600 });
+
+  // The file and this process's env have to move together: everything here
+  // reads tokens from process.env, and a service spawned after this call
+  // inherits it (see lib/daemon.js). Unlike loadEnvFile, an explicit save wins
+  // over a shell export — you just told us what the token is.
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) delete process.env[key];
+    else process.env[key] = String(value);
+  }
+
+  return readEnvVars();
+}