@splinterzzz/ouro 0.1.0

package/src/lib/store.js

@@ -0,0 +1,188 @@
+import fs from "node:fs";
+import { EventEmitter } from "node:events";
+import { nanoid } from "nanoid";
+import { ticketsPath, ensureOuroDir } from "./paths.js";
+
+// Lightweight file-backed store. A hackathon-scale ticket board doesn't need
+// sqlite/postgres — a JSON file + an in-memory EventEmitter for the WS layer
+// is plenty, and it means `ouro init` produces zero external dependencies.
+
+export const STATUSES = ["inbox", "triaged", "in_progress", "review", "done", "cancelled"];
+
+// A streaming agent emits events far faster than a board needs to persist.
+// Writes are coalesced onto a trailing timer so a chatty run costs one write
+// per tick instead of one per line; every mutation still broadcasts instantly
+// over WS, so the UI is live regardless of when the file lands.
+const PERSIST_DEBOUNCE_MS = 250;
+
+// Per-ticket log ceiling. The terminal dock only ever renders a tail, and an
+// unbounded array would grow tickets.json without limit across a long run.
+const MAX_LOG_ENTRIES = 400;
+
+class TicketStore extends EventEmitter {
+  constructor() {
+    super();
+    this.tickets = [];
+    this._persistTimer = null;
+    this._load();
+  }
+
+  _load() {
+    ensureOuroDir();
+    if (fs.existsSync(ticketsPath())) {
+      try {
+        this.tickets = JSON.parse(fs.readFileSync(ticketsPath(), "utf-8"));
+      } catch {
+        this.tickets = [];
+      }
+    }
+
+    // A ticket left mid-run by a killed dashboard process has no live child
+    // to reattach to, so it would otherwise sit spinning forever. Reconcile
+    // it to a terminal state at startup instead.
+    let reconciled = 0;
+    for (const ticket of this.tickets) {
+      if (ticket.status === "in_progress") {
+        ticket.status = "cancelled";
+        ticket.cancelReason = "Dashboard stopped while this run was in flight.";
+        reconciled++;
+      }
+    }
+    // Write it back immediately. Reconciling only in memory leaves the file
+    // claiming in_progress until some unrelated edit happens to flush it —
+    // so anything reading tickets.json directly (or a crash before the next
+    // write) would still see a run that hasn't existed since the last boot.
+    if (reconciled > 0) this.flush();
+  }
+
+  _persist() {
+    if (this._persistTimer) return;
+    this._persistTimer = setTimeout(() => {
+      this._persistTimer = null;
+      this.flush();
+    }, PERSIST_DEBOUNCE_MS);
+  }
+
+  /** Write immediately. Called on shutdown so a pending tick isn't lost. */
+  flush() {
+    if (this._persistTimer) {
+      clearTimeout(this._persistTimer);
+      this._persistTimer = null;
+    }
+    try {
+      fs.writeFileSync(ticketsPath(), JSON.stringify(this.tickets, null, 2));
+    } catch {
+      // A failed write shouldn't take the dashboard down — the in-memory
+      // state is still authoritative for this process.
+    }
+  }
+
+  list() {
+    return this.tickets;
+  }
+
+  get(id) {
+    return this.tickets.find((t) => t.id === id);
+  }
+
+  create({ title, body, source = "manual", agentId = null, mode = null, priority = null, summary = null }) {
+    const ticket = {
+      id: nanoid(8),
+      title,
+      body,
+      source,
+      status: "inbox", // inbox -> triaged -> in_progress -> review -> done | cancelled
+      mode, // "agent" | "human" — null inherits the board's default
+      agentId, // which .ouro/agents/<id>.md runs this ticket
+      priority,
+      summary,
+      sessionId: null,
+      log: [],
+      worktree: null,
+      branch: null, // ouro/<id>, created with the worktree
+      baseBranch: null, // what HEAD was when the worktree was cut — the PR's target
+      diff: null,
+      plan: null,
+      prUrl: null, // set once the ticket ships
+      shipNote: null, // why it didn't ship, when it didn't
+      awaitingApproval: false,
+      cancelReason: null,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    this.tickets.unshift(ticket);
+    this._persist();
+    this.emit("change", { type: "created", ticket });
+    return ticket;
+  }
+
+  update(id, patch) {
+    const ticket = this.get(id);
+    if (!ticket) return null;
+    Object.assign(ticket, patch, { updatedAt: new Date().toISOString() });
+    this._persist();
+    this.emit("change", { type: "updated", ticket });
+    return ticket;
+  }
+
+  appendLog(id, entry) {
+    const ticket = this.get(id);
+    if (!ticket) return null;
+
+    const record = { ts: new Date().toISOString(), ...entry };
+    ticket.log.push(record);
+    if (ticket.log.length > MAX_LOG_ENTRIES) {
+      ticket.log.splice(0, ticket.log.length - MAX_LOG_ENTRIES);
+    }
+    ticket.updatedAt = record.ts;
+    this._persist();
+
+    // Log traffic is the terminal dock's firehose. It ships the single new
+    // entry rather than the whole ticket, so a long run doesn't re-send its
+    // entire history down the socket on every line.
+    this.emit("change", { type: "log", ticketId: id, entry: record });
+    return ticket;
+  }
+
+  /**
+   * Terminal transition for a run that was killed. Distinct from `update`
+   * only in that it clears the mid-run fields a cancelled ticket shouldn't
+   * keep showing (pending approval, half-written plan).
+   */
+  cancel(id, reason) {
+    const ticket = this.get(id);
+    if (!ticket) return null;
+    return this.update(id, {
+      status: "cancelled",
+      awaitingApproval: false,
+      cancelReason: reason ?? "Cancelled from the dashboard.",
+    });
+  }
+
+  /** Back to the board as a fresh triaged ticket, keeping title/body/agent. */
+  reopen(id) {
+    const ticket = this.get(id);
+    if (!ticket) return null;
+    return this.update(id, {
+      status: ticket.summary ? "triaged" : "inbox",
+      awaitingApproval: false,
+      cancelReason: null,
+      diff: null,
+      plan: null,
+      sessionId: null,
+      log: [],
+    });
+  }
+
+  remove(id) {
+    const index = this.tickets.findIndex((t) => t.id === id);
+    if (index === -1) return false;
+    this.tickets.splice(index, 1);
+    this._persist();
+    this.emit("change", { type: "deleted", ticketId: id });
+    return true;
+  }
+}
+
+// Singleton — one store per running `ouro dashboard` process.
+export const store = new TicketStore();

package/src/lib/telegram.js

@@ -0,0 +1,60 @@
+// Telegram's Bot API, only as far as ouro needs it to answer one question:
+// "is this token real?"
+//
+// Plain fetch rather than node-telegram-bot-api: the dashboard process has no
+// business holding a polling client (that's what `ouro listen` is), and one
+// getMe call doesn't justify instantiating a bot that would start a connection
+// pool and a retry loop the moment it's constructed.
+
+// @BotFather issues `<bot id>:<35-char secret>`. Checking the shape before a
+// network call turns the usual paste mistakes — the bot's @name, a half-copied
+// token, the whole BotFather message — into a specific error, rather than a
+// round trip that comes back as an unexplained "Unauthorized".
+const SHAPE = /^\d{5,}:[A-Za-z0-9_-]{30,}$/;
+
+export function looksLikeToken(token) {
+  return SHAPE.test(String(token ?? "").trim());
+}
+
+/**
+ * `123456789:…QsT4` — enough to recognise which token is set, useless to
+ * anyone who reads it. The bot id half is public (it's in the token's own
+ * structure and every getMe response); only the secret half is masked.
+ */
+export function maskToken(token) {
+  const value = String(token ?? "").trim();
+  if (!value) return null;
+  const [id] = value.split(":");
+  return value.includes(":") ? `${id}:…${value.slice(-4)}` : `…${value.slice(-4)}`;
+}
+
+/**
+ * Asks Telegram who this token belongs to. Returns `{ ok: true, bot }` or
+ * `{ ok: false, error }` — never throws, and never echoes the token back in an
+ * error string, since these land in an HTTP response and a browser console.
+ */
+export async function verifyBotToken(token) {
+  let res;
+  try {
+    res = await fetch(`https://api.telegram.org/bot${token}/getMe`, {
+      signal: AbortSignal.timeout(8000),
+    });
+  } catch (err) {
+    // Offline, DNS, proxy, or Telegram blocked by the network — decidedly not
+    // "your token is wrong", and saying so would send someone to @BotFather
+    // for a token that was fine all along.
+    return { ok: false, error: `Couldn't reach Telegram (${err.name === "TimeoutError" ? "timed out" : err.message}).` };
+  }
+
+  const body = await res.json().catch(() => ({}));
+
+  if (!res.ok || !body.ok) {
+    const why = body.description ?? `Telegram responded ${res.status}`;
+    return { ok: false, error: res.status === 401 ? "Telegram rejected this token — get a fresh one from @BotFather." : why };
+  }
+
+  return {
+    ok: true,
+    bot: { id: body.result.id, username: body.result.username, name: body.result.first_name },
+  };
+}

package/src/lib/worktree.js

@@ -0,0 +1,93 @@
+import path from "node:path";
+import fs from "node:fs";
+import simpleGit from "simple-git";
+import { repoRoot, worktreesDir } from "./paths.js";
+
+/**
+ * Every ticket that goes into agent mode gets its own git worktree on a
+ * throwaway branch. This means a live demo can show a real diff being
+ * generated without any risk to the actual working tree mid-presentation,
+ * and "Apply" is just a merge instead of hoping the agent didn't wander.
+ */
+
+export function branchFor(ticketId) {
+  return `ouro/${ticketId}`;
+}
+
+export function worktreePath(ticketId) {
+  return path.join(worktreesDir(), ticketId);
+}
+
+/** The branch the repo is on right now — the base a ticket branches from. */
+export async function currentBranch() {
+  try {
+    return (await simpleGit(repoRoot()).revparse(["--abbrev-ref", "HEAD"])).trim();
+  } catch {
+    return null;
+  }
+}
+
+export async function createTicketWorktree(ticketId) {
+  const git = simpleGit(repoRoot());
+  const branch = branchFor(ticketId);
+  const dir = worktreePath(ticketId);
+
+  // Captured before the worktree exists: this is what the PR should target,
+  // and by ship time HEAD may have moved on.
+  const base = await currentBranch();
+
+  if (fs.existsSync(dir)) return { dir, branch, base };
+
+  await git.raw(["worktree", "add", dir, "-b", branch]);
+  return { dir, branch, base };
+}
+
+export async function diffWorktree(ticketId) {
+  const git = simpleGit(worktreePath(ticketId));
+  // Include staged changes: an agent that ran `git add` would otherwise show
+  // an empty diff and look like it did nothing.
+  const [unstaged, staged] = await Promise.all([git.diff(), git.diff(["--cached"])]);
+  return [staged, unstaged].filter(Boolean).join("\n") || null;
+}
+
+/** Files the agent touched, staged or not. Empty means it changed nothing. */
+export async function worktreeChanges(ticketId) {
+  const status = await simpleGit(worktreePath(ticketId)).status();
+  return [...new Set([...status.files.map((f) => f.path), ...status.not_added])];
+}
+
+/**
+ * Commits everything the agent produced. Agents aren't asked to commit — their
+ * prompt is about the work, not the plumbing — so ouro does it, which also
+ * keeps the commit message consistent regardless of which agent ran.
+ */
+export async function commitWorktree(ticketId, message) {
+  const git = simpleGit(worktreePath(ticketId));
+  const changed = await worktreeChanges(ticketId);
+  if (changed.length === 0) return { committed: false, files: [] };
+
+  await git.add(["-A"]);
+  await git.commit(message);
+  return { committed: true, files: changed };
+}
+
+export async function hasRemote() {
+  try {
+    return (await simpleGit(repoRoot()).getRemotes(false)).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Pushes the ticket branch and sets upstream. Throws with git's own message. */
+export async function pushTicketBranch(ticketId) {
+  const git = simpleGit(worktreePath(ticketId));
+  const branch = branchFor(ticketId);
+  await git.push(["-u", "origin", branch]);
+  return branch;
+}
+
+export async function removeTicketWorktree(ticketId) {
+  const git = simpleGit(repoRoot());
+  await git.raw(["worktree", "remove", worktreePath(ticketId), "--force"]).catch(() => {});
+}