catherd-cli 0.1.0

package/src/tui/backends.ts

@@ -0,0 +1,57 @@
+export interface BackendStatus {
+  backend: "codex" | "opencode";
+  installed: boolean;
+  version: string | null;
+  loggedIn: boolean;
+  fix: string | null;
+}
+
+interface Result {
+  exitCode: number;
+  stdout: string;
+}
+
+const PROBES = {
+  codex: {
+    install: "npm i -g @openai/codex",
+    login: "codex login",
+    status: ["login", "status"],
+    // `codex login status` prints to stderr; its exit code is the answer.
+    loggedIn: (r: Result) => r.exitCode === 0,
+  },
+  opencode: {
+    install: "npm i -g opencode-ai",
+    login: "opencode auth login",
+    status: ["auth", "list"],
+    loggedIn: (r: Result) => r.exitCode === 0 && r.stdout.trim().length > 0,
+  },
+} as const;
+
+async function run(cmd: string, args: string[]): Promise<Result> {
+  // Bun.spawn's own PATH lookup can stay stale across calls when PATH changes mid-process
+  // (as tests do), so the binary is resolved by hand against the current PATH each time.
+  const bin = Bun.which(cmd, { PATH: process.env.PATH ?? "" });
+  if (!bin) return { exitCode: 127, stdout: "" };
+  try {
+    const proc = Bun.spawn([bin, ...args], { stdout: "pipe", stderr: "pipe" });
+    const [stdout] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+    const exitCode = await proc.exited;
+    return { exitCode, stdout };
+  } catch {
+    return { exitCode: 127, stdout: "" };
+  }
+}
+
+async function probe(backend: "codex" | "opencode"): Promise<BackendStatus> {
+  const p = PROBES[backend];
+  const v = await run(backend, ["--version"]);
+  if (v.exitCode !== 0) return { backend, installed: false, version: null, loggedIn: false, fix: p.install };
+  const version = v.stdout.trim().split(/\s+/).at(-1)?.replace(/^v/, "") ?? null;
+  const s = await run(backend, [...p.status]);
+  const loggedIn = p.loggedIn(s);
+  return { backend, installed: true, version, loggedIn, fix: loggedIn ? null : p.login };
+}
+
+export function detectBackends(): Promise<BackendStatus[]> {
+  return Promise.all([probe("codex"), probe("opencode")]);
+}

package/src/tui/commands.ts

@@ -0,0 +1,51 @@
+import { createCliRenderer } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import { defineCommand } from "citty";
+import { createElement, type ReactNode } from "react";
+import { Editor } from "./editor.tsx";
+import { Init } from "./init.tsx";
+import { detectUi } from "./theme.ts";
+import { Watch } from "./watch.tsx";
+
+const uiArgs = {
+  plain: { type: "boolean", description: "ASCII only: a text fallback for every glyph" },
+  "reduced-motion": { type: "boolean", description: "No animation" },
+} as const;
+
+export const isBare = (rawArgs: string[]): boolean => rawArgs.every((a) => a.startsWith("-"));
+
+export async function mount(el: ReactNode, stdin: { isTTY?: boolean } = process.stdin): Promise<number> {
+  if (!stdin.isTTY) {
+    console.error(
+      "catherd: this screen needs an interactive terminal. Scripts can use the MCP tools (status, profile_get).",
+    );
+    return 1;
+  }
+  const renderer = await createCliRenderer({ exitOnCtrlC: true });
+  createRoot(renderer).render(el);
+  await new Promise<void>((resolve) => renderer.once("destroy", () => resolve()));
+  return Number(process.exitCode ?? 0);
+}
+
+/** The main command's run. citty runs it after any subcommand too, hence the isBare check. */
+export async function editorRun({ rawArgs }: { rawArgs: string[] }): Promise<void> {
+  if (!isBare(rawArgs)) return;
+  process.exitCode = await mount(createElement(Editor, { ui: detectUi(rawArgs) }));
+}
+
+export const initCommand = defineCommand({
+  meta: { name: "init", description: "First run: the Jev key, your backends, and a profile" },
+  args: uiArgs,
+  async run({ rawArgs }) {
+    const code = await mount(createElement(Init, { ui: detectUi(rawArgs) }));
+    process.exitCode = process.exitCode || code;
+  },
+});
+
+export const watchCommand = defineCommand({
+  meta: { name: "watch", description: "Live view of running and recent runs" },
+  args: uiArgs,
+  async run({ rawArgs }) {
+    process.exitCode = await mount(createElement(Watch, { ui: detectUi(rawArgs) }));
+  },
+});

package/src/tui/editor.tsx

@@ -0,0 +1,221 @@
+import { TextAttributes } from "@opentui/core";
+import { useKeyboard, useRenderer } from "@opentui/react";
+import { useEffect, useState } from "react";
+import { type HarnessCost, harnessCosts } from "../core/harness.ts";
+import { listRuns } from "../core/runstore.ts";
+import {
+  activeProfileName,
+  defaultProfile,
+  listProfiles,
+  loadProfile,
+  validateProfile,
+} from "../profile/profile.ts";
+import { loadCatalog } from "../routing/catalog.ts";
+import type { Catalog, Profile } from "../types.ts";
+import { type BackendStatus, detectBackends } from "./backends.ts";
+import { Matrix } from "./matrix.tsx";
+import { deleteProfile, nameError, saveAndActivate } from "./profiles.ts";
+import { face, glyph, type Mood, tint, type Ui } from "./theme.ts";
+import { CatSpinner, Header, Screen } from "./ui.tsx";
+
+export interface EditorDeps {
+  loadCatalog: () => Catalog;
+  detectBackends: () => Promise<BackendStatus[]>;
+  harnessCosts: () => HarnessCost[];
+  save: (p: Profile, c: Catalog) => void;
+}
+
+const editorDeps: EditorDeps = {
+  loadCatalog,
+  detectBackends,
+  harnessCosts: () => harnessCosts(listRuns().map((r) => r.dir)),
+  save: saveAndActivate,
+};
+
+type Ask = "new" | "copy" | "delete" | "quit" | null;
+
+function openBook(): { profiles: Profile[]; idx: number } {
+  const names = listProfiles();
+  const profiles = names.length > 0 ? names.map((n) => loadProfile(n)) : [defaultProfile()];
+  const active = activeProfileName();
+  return {
+    profiles,
+    idx: Math.max(
+      0,
+      profiles.findIndex((p) => p.name === active),
+    ),
+  };
+}
+
+export function Editor({ ui, deps = {} }: { ui: Ui; deps?: Partial<EditorDeps> }) {
+  const d = { ...editorDeps, ...deps };
+  const renderer = useRenderer();
+  const exit = () => renderer.destroy();
+  const [catalog, setCatalog] = useState(d.loadCatalog);
+  const [costs] = useState(d.harnessCosts);
+  const [backends, setBackends] = useState<BackendStatus[] | null>(null);
+  const [book, setBook] = useState(openBook);
+  const [active, setActive] = useState(activeProfileName);
+  const [dirty, setDirty] = useState<ReadonlySet<string>>(new Set());
+  const [errors, setErrors] = useState<string[]>([]);
+  const [note, setNote] = useState("");
+  const [ask, setAsk] = useState<Ask>(null);
+  const profile = book.profiles[book.idx] as Profile;
+  const pink = tint("pink", ui.depth);
+  const dot = ` ${glyph("dot", ui.plain)} `;
+
+  useEffect(() => {
+    d.detectBackends().then(setBackends, () => setBackends([]));
+  }, []);
+
+  const mark = (name: string, on: boolean) => {
+    const next = new Set(dirty);
+    if (on) next.add(name);
+    else next.delete(name);
+    setDirty(next);
+  };
+
+  const put = (p: Profile) => {
+    setBook({ profiles: book.profiles.map((x, i) => (i === book.idx ? p : x)), idx: book.idx });
+    mark(p.name, true);
+    setErrors([]);
+    setNote("");
+  };
+
+  const save = () => {
+    const errs = validateProfile(profile, catalog);
+    setErrors(errs);
+    if (errs.length > 0) return;
+    d.save(profile, catalog);
+    mark(profile.name, false);
+    setActive(profile.name);
+    setNote(`Saved ${profile.name}; it is active now. New Claude Code sessions get its agents.`);
+  };
+
+  const add = (name: string) => {
+    const err = nameError(
+      name,
+      book.profiles.map((p) => p.name),
+    );
+    setAsk(null);
+    if (err) {
+      setNote(err);
+      return;
+    }
+    const base = ask === "new" ? defaultProfile() : structuredClone(profile);
+    setBook({ profiles: [...book.profiles, { ...base, name }], idx: book.profiles.length });
+    mark(name, true);
+    setNote("");
+  };
+
+  const remove = () => {
+    if (book.profiles.length === 1) {
+      setNote("Keep at least one profile.");
+      return;
+    }
+    try {
+      if (listProfiles().includes(profile.name)) deleteProfile(profile.name);
+    } catch (e) {
+      setNote((e as Error).message);
+      return;
+    }
+    mark(profile.name, false);
+    setBook({ profiles: book.profiles.filter((_, i) => i !== book.idx), idx: 0 });
+    setNote(`Deleted ${profile.name}.`);
+  };
+
+  const onKey = (input: string) => {
+    setNote("");
+    if (input === "p") {
+      setBook({ ...book, idx: (book.idx + 1) % book.profiles.length });
+      setErrors([]);
+    } else if (input === "n") setAsk("new");
+    else if (input === "c") setAsk("copy");
+    else if (input === "x") setAsk("delete");
+  };
+
+  useKeyboard((key) => {
+    if (ask === "new" || ask === "copy") {
+      if (key.name === "escape") setAsk(null);
+      return;
+    }
+    if (ask === "quit") {
+      if (key.sequence === "q") exit();
+      setAsk(null);
+      return;
+    }
+    if (ask === "delete") {
+      if (key.sequence === "y") remove();
+      setAsk(null);
+    }
+  });
+
+  const mood: Mood =
+    backends === null
+      ? "working"
+      : errors.length > 0
+        ? "failed"
+        : dirty.has(profile.name)
+          ? "waiting"
+          : "good";
+
+  return (
+    <Screen>
+      <Header ui={ui} mood={mood} title={`profiles${dot}${profile.name}`} />
+      <text wrapMode="none" truncate>
+        {`profile ${profile.name} ${book.idx + 1}/${book.profiles.length}${
+          profile.name === active ? " (active)" : ""
+        }${dirty.has(profile.name) ? " (unsaved)" : ""}`}
+        <span attributes={TextAttributes.DIM}>{`${dot}p next${dot}n new${dot}c copy${dot}x delete`}</span>
+      </text>
+      {backends === null ? (
+        <CatSpinner ui={ui} label="sniffing out codex and opencode" />
+      ) : (
+        <Matrix
+          key={profile.name}
+          ui={ui}
+          profile={profile}
+          catalog={catalog}
+          backends={backends}
+          costs={costs}
+          reloadCatalog={d.loadCatalog}
+          onChange={put}
+          onCatalog={setCatalog}
+          onSubmit={save}
+          onQuit={() => (dirty.size > 0 ? setAsk("quit") : exit())}
+          onKey={onKey}
+          active={ask === null}
+        />
+      )}
+      {ask === "new" || ask === "copy" ? (
+        <box style={{ flexDirection: "row" }}>
+          <text>
+            {ask === "new" ? "Name for the new profile: " : `Name for the copy of ${profile.name}: `}
+          </text>
+          {/* React 19's DOMAttributes adds a DOM `onSubmit(event: SubmitEvent)` overload to every
+              intrinsic element, including OpenTUI's non-DOM <input>; `as any` sidesteps that
+              phantom overload rather than fighting it with a full-signature cast. */}
+          <input focused onSubmit={add as any} />
+        </box>
+      ) : null}
+      {ask === "delete" ? (
+        <text fg={pink}>{`Delete profile ${profile.name}? y deletes it, any other key keeps it.`}</text>
+      ) : null}
+      {ask === "quit" ? (
+        <text fg={pink} wrapMode="none" truncate>
+          {`Unsaved changes in ${[...dirty].join(", ")}. q quits without saving, any other key stays.`}
+        </text>
+      ) : null}
+      {errors.map((e) => (
+        <text key={e} fg={pink} wrapMode="none" truncate>
+          {`${face("failed", ui.plain)} ${e}`}
+        </text>
+      ))}
+      {note ? (
+        <text wrapMode="none" truncate>
+          {note}
+        </text>
+      ) : null}
+    </Screen>
+  );
+}

package/src/tui/init.tsx

@@ -0,0 +1,221 @@
+import { TextAttributes } from "@opentui/core";
+import { useKeyboard, useRenderer } from "@opentui/react";
+import { useRef, useState } from "react";
+import { type HarnessCost, harnessCosts } from "../core/harness.ts";
+import { listRuns } from "../core/runstore.ts";
+import { defaultProfile, validateProfile } from "../profile/profile.ts";
+import { loadCatalog } from "../routing/catalog.ts";
+import { jevKey, saveJevKey, testJevKey } from "../routing/jev.ts";
+import type { Catalog, Profile } from "../types.ts";
+import { type BackendStatus, detectBackends } from "./backends.ts";
+import { Matrix } from "./matrix.tsx";
+import { saveAndActivate } from "./profiles.ts";
+import { face, glyph, type Mood, tint, type Ui } from "./theme.ts";
+import { CatSpinner, Header, Intro, Screen } from "./ui.tsx";
+
+export interface InitDeps {
+  jevKey: () => string | null;
+  testJevKey: (key: string) => Promise<boolean>;
+  saveJevKey: (key: string) => void;
+  detectBackends: () => Promise<BackendStatus[]>;
+  loadCatalog: () => Catalog;
+  harnessCosts: () => HarnessCost[];
+  save: (p: Profile, c: Catalog) => void;
+}
+
+const initDeps: InitDeps = {
+  jevKey,
+  testJevKey,
+  saveJevKey,
+  detectBackends,
+  loadCatalog,
+  harnessCosts: () => harnessCosts(listRuns().map((r) => r.dir)),
+  save: saveAndActivate,
+};
+
+export const PLUGIN_STEPS = ["/plugin marketplace add 47vigen/catherd", "/plugin install catherd@catherd"];
+
+type Phase = "intro" | "key" | "testing" | "backends" | "matrix" | "done";
+
+const TITLES: Record<Phase, string> = {
+  intro: "",
+  key: "init 1/3: the Jev key",
+  testing: "init 1/3: the Jev key",
+  backends: "init 2/3: your backends",
+  matrix: "init 3/3: your profile",
+  done: "ready",
+};
+
+function BackendLine({ ui, b }: { ui: Ui; b: BackendStatus }) {
+  const ok = b.installed && b.loggedIn;
+  const state = !b.installed ? "not installed" : b.loggedIn ? "logged in" : "not logged in";
+  const fix = b.fix ? ` ${glyph("dot", ui.plain)} fix: ${b.fix}` : "";
+  return (
+    <text wrapMode="none" truncate attributes={ok ? TextAttributes.NONE : TextAttributes.DIM}>
+      {`${glyph(ok ? "on" : "off", ui.plain)} ${b.backend.padEnd(9)}${(b.version ?? "").padEnd(9)}${state}${fix}`}
+    </text>
+  );
+}
+
+/** No masked input ships with OpenTUI, so the key is kept in state and shown as asterisks. */
+function MaskedKeyInput({ onSubmit }: { onSubmit: (key: string) => void }) {
+  const [value, setValue] = useState("");
+  useKeyboard((key) => {
+    if (key.name === "return") {
+      onSubmit(value);
+      return;
+    }
+    if (key.name === "backspace") {
+      setValue((v) => v.slice(0, -1));
+      return;
+    }
+    if (!key.ctrl && !key.meta) {
+      const ch = key.name === "space" ? " " : key.sequence;
+      if (ch && ch.length === 1) setValue((v) => v + ch);
+    }
+  });
+  return <text>{"*".repeat(value.length)}</text>;
+}
+
+export function Init({ ui, deps = {} }: { ui: Ui; deps?: Partial<InitDeps> }) {
+  const d = { ...initDeps, ...deps };
+  const renderer = useRenderer();
+  const started = useRef(false);
+  const [phase, setPhase] = useState<Phase>("intro");
+  const [note, setNote] = useState("");
+  const [catalog, setCatalog] = useState(d.loadCatalog);
+  const [costs] = useState(d.harnessCosts);
+  const [profile, setProfile] = useState<Profile>(defaultProfile);
+  const [backends, setBackends] = useState<BackendStatus[]>([]);
+  const [errors, setErrors] = useState<string[]>([]);
+  const pink = tint("pink", ui.depth);
+
+  // Any key finishes, once the "done" message has actually had a chance to sit on screen:
+  // destroying the renderer immediately tears down the render tree, so a frame captured
+  // right after would show nothing, and a real terminal would lose the message the same way.
+  useKeyboard(() => {
+    if (phase === "done") renderer.destroy();
+  });
+
+  const check = async (key: string, typed: boolean) => {
+    setPhase("testing");
+    const ok = await d.testJevKey(key).catch(() => false);
+    if (!ok) {
+      setNote(
+        typed
+          ? "Jev did not accept that key. Check it at typesafe.ai and paste it again."
+          : "The saved Jev key did not answer. Paste a new one.",
+      );
+      setPhase("key");
+      return;
+    }
+    if (typed) d.saveJevKey(key);
+    setNote("");
+    setPhase("backends");
+    setBackends(await d.detectBackends());
+    setPhase("matrix");
+  };
+
+  const afterIntro = () => {
+    if (started.current) return;
+    started.current = true;
+    const saved = d.jevKey();
+    if (saved) void check(saved, false);
+    else setPhase("key");
+  };
+
+  const accept = () => {
+    const errs = validateProfile(profile, catalog);
+    setErrors(errs);
+    if (errs.length > 0) return;
+    d.save(profile, catalog);
+    setPhase("done");
+  };
+
+  if (phase === "intro") {
+    return (
+      <Screen>
+        <Intro ui={ui} onDone={afterIntro} />
+      </Screen>
+    );
+  }
+
+  const mood: Mood =
+    phase === "done"
+      ? "landed"
+      : errors.length > 0 || note
+        ? "failed"
+        : phase === "key"
+          ? "waiting"
+          : phase === "matrix"
+            ? "good"
+            : "working";
+
+  return (
+    <Screen>
+      <Header ui={ui} mood={mood} title={TITLES[phase]} />
+      {phase === "key" ? (
+        <box style={{ flexDirection: "column" }}>
+          <text>Paste your TypeSafe API key. Jev uses it to pick each lane's model and effort.</text>
+          <box style={{ flexDirection: "row" }}>
+            <text>key: </text>
+            <MaskedKeyInput
+              onSubmit={(k) => {
+                if (k.trim()) void check(k.trim(), true);
+              }}
+            />
+          </box>
+        </box>
+      ) : null}
+      {phase === "testing" ? <CatSpinner ui={ui} label="asking Jev a test question" /> : null}
+      {phase === "backends" ? <CatSpinner ui={ui} label="sniffing out codex and opencode" /> : null}
+      {phase === "matrix" ? (
+        <box style={{ flexDirection: "column" }}>
+          {backends.map((b) => (
+            <BackendLine key={b.backend} ui={ui} b={b} />
+          ))}
+          <Matrix
+            ui={ui}
+            profile={profile}
+            catalog={catalog}
+            backends={backends}
+            costs={costs}
+            reloadCatalog={d.loadCatalog}
+            onChange={(p) => {
+              setProfile(p);
+              setErrors([]);
+            }}
+            onCatalog={setCatalog}
+            onSubmit={accept}
+            onQuit={() => {
+              process.exitCode = 1;
+              renderer.destroy();
+            }}
+            submitLabel="accept"
+          />
+          {errors.map((e) => (
+            <text key={e} fg={pink} wrapMode="none" truncate>
+              {`${face("failed", ui.plain)} ${e}`}
+            </text>
+          ))}
+        </box>
+      ) : null}
+      {phase === "done" ? (
+        <box style={{ flexDirection: "column" }}>
+          <text>{`Saved profile ${profile.name} and its Claude agents.`}</text>
+          <text>Now add the plugin in Claude Code:</text>
+          {PLUGIN_STEPS.map((s) => (
+            <text key={s} fg={tint("ginger", ui.depth)}>{`  ${s}`}</text>
+          ))}
+          <text>Then start a new Claude Code session: it picks up the agents.</text>
+          <text attributes={TextAttributes.DIM}>Press any key to finish.</text>
+        </box>
+      ) : null}
+      {note ? (
+        <text fg={pink} wrapMode="none" truncate>
+          {note}
+        </text>
+      ) : null}
+    </Screen>
+  );
+}