@higherdev/cli 0.3.0 → 0.5.0

package/README.md

@@ -1,176 +1,51 @@
-# hd
+# HigherDEV CLI
 
-HigherDEV in your terminal. Full control of the board, and live views of agents,
-tickets, runs, and spend without a browser.
+Operator controls for HDX workspaces, tickets, agents, and runner hosts.
 
 ## Install
 
-```bash
-npm i -g @higherdev/cli
-hd login       # six-digit code, emailed, then HigherDEV opens
-```
-
-`hd` on its own opens it too. Inside, everything is a slash command:
-
-```
-/architect        talk to your own model, which can do anything here
-/orchestrator     talk to the agent that finishes work in flight
-/browse           stop talking, look around
-/workspace [slug] switch workspace, or list the ones you can reach
-/board /agents /feed /inbox /ticket HD-12
-/help /exit
-```
-
-Anything not starting with `/` goes to whoever you are talking to. The header
-always shows the workspace you are on, what is running, and which model is
-answering. `hd login --no-launch` signs in without opening it.
-
-Or from the registry: `npm i -g @higherdev/cli`, then the same commands.
-`hd upgrade` updates it, `hd upgrade --check` only reports.
-
-## Which HigherDEV
-
-`hd` is not tied to one deployment. On first sign-in it fetches the Supabase
-settings from the app's `/api/config` and caches them in
-`~/.config/higherdev/config.json`.
-
-```bash
-hd login --app-url https://dev.yourcompany.com
-```
-
-Switching deployments clears the previous one's session, cached settings, and
-selected workspace, so two never mix. `HIGHERDEV_APP_URL` overrides per command,
-and `HIGHERDEV_SUPABASE_URL` plus `HIGHERDEV_PUBLISHABLE_KEY` skip the fetch
-entirely. `HIGHERDEV_CONFIG_DIR` keeps a second deployment in its own directory
-if you work across two.
-
-Who may sign in is the deployment's decision, not the CLI's: `hd` asks the
-server's own `is_allowlisted()`, the same function RLS enforces with, so a
-published binary carries no list of names.
-
-## How it talks to the platform
-
-It signs in as you, with the same emailed six-digit code the web app uses, and
-talks to Supabase directly under RLS. No service key lives on your laptop, and
-every write records an audit event naming you, so a CLI change reads the same as
-a click. Live views are Realtime subscriptions, not polling.
-
-## Two ways to talk to it
-
-`hd ask` reaches the **orchestrator**, which runs on the box and is in charge of
-getting work in flight to finish. Ask it why something is stuck or tell it to
-reshuffle a workstream. It cannot change agent settings, and that is enforced by
-its action schema rather than by its prompt.
-
-```bash
-hd ask "why is HD-12 stuck?"
-hd msg HD-12 --to builder "also rename the old column" --interrupt
-```
-
-`hd plan` talks to **your own model**, here on your machine, on your ChatGPT
-subscription. It is not a worker in a workspace and not a row in the agent
-registry: nothing on the runner dispatches to it, and it reaches the whole
-platform. `hd brain` shows which model it is and connects the subscription the
-first time. It reads the repo, decides what should be built, files an epic,
-and can tune the platform itself: models, effort, routing notes, prompt addenda,
-conventions, budgets. Creating an epic fires `epic.created`, which the
-orchestrator already triggers on, so the handoff needs no glue.
-
-```bash
-hd brain       # which model, and connect it the first time
-hd plan        # a conversation: type, it answers, keep going
-```
-
-Bare `hd plan` on a terminal is a back-and-forth. Every turn after the first
-continues the same Codex session, so it remembers what you already said. A blank
-line or `/exit` leaves, and `hd plan --resume "..."` picks the thread back up
-later.
-
-Give it a request on the command line instead and it runs one turn and exits,
-which is what a script wants:
-
-```bash
-hd plan "assess the call-intel code and plan what is missing"
-hd plan --read-only "what would you change about the agent lineup?"
-hd plan --once "file the epic we discussed"
-```
-
-### How it reaches the model
-
-`hd` calls the ChatGPT backend directly with your subscription credentials and
-runs its own agent loop over its own tools, in process. It does not spawn
-`codex exec`. That matters: a subprocess made Codex's coding agent the brain, so
-it owned the system prompt, it had a shell, and a greeting took twenty seconds.
-Direct, a turn answers in about two, `hd` owns the prompt, there is no shell in
-the path, and text streams as it is written.
-
-The credential comes from `~/.codex/auth.json`, because the Codex CLI is what
-performs the browser login. Nothing else about Codex is involved. `hd connect`
-runs that login for you; `hd` never sees or stores the token, and renews the
-session automatically rather than asking you to sign in again.
-
-`hd plan` **refuses to start** unless that session is a real ChatGPT one, since
-the platform runs on subscriptions and never per-token APIs. It distinguishes
-connected, signed in with an API key (which bills per token), signed out, and
-not installed. `--allow-api-billing` overrides the refusal when you mean it.
-
-The architect reads code through `list_files`, `read_file`, and `search_code`,
-scoped to the workspace checkout. Read only, no shell, no path escape.
-
-`hd mcp` is the same platform as MCP tools on stdio. `hd plan` attaches it to
-Codex for the invocation, with no global config edit. Attach it to Claude Code or
-give Mel the read-only half:
-
-```bash
-hd mcp --list                 # the 24 tools, with what each does
-hd mcp --read-only            # safe to hand to anything
-```
-
-The architect does not go through MCP: its tools are the same functions, called
-in process. `hd mcp` exists so anything else can reach them.
-
-## Everything else
-
-```
-hd                    live dashboard          hd new "title" --area web/auth
-hd status             one-screen summary      hd set HD-12 --agent Codex
-hd board              kanban by status        hd block HD-12 HD-9
-hd ls --stuck         why nothing is moving   hd take HD-12 / hd handback HD-12
-hd show HD-12         one ticket in full      hd cancel HD-12 / hd kill HD-12
-hd watch HD-12        live run transcript     hd epic new "title" spec.md
-hd logs <run> -f      one run, following      hd epic replan <id>
-hd agents             live agent state        hd orchestrate
-hd feed               live activity           hd decide <id> "answer"
-hd inbox              decisions and messages  hd pause / hd resume [--all|-p claude]
-hd cost               spend, by day and more  hd agent set Codex --model gpt-5.6-sol
-hd hosts              runner health           hd conventions --edit
-hd connect --check    Codex connection        hd upgrade [--check]
-hd epic show <id>     dependency waves        hd attach HD-12 shot.png
-```
-
-Every read takes `--json` and every write is non-interactive when given flags, so
-Claude Code and Mel can drive the board over SSH. Colour follows `NO_COLOR` and
-turns itself off when stdout is not a terminal.
-
-## Onboarding a new host
-
-`hd init` still does host onboarding: it writes the runner env file, registers
-the host, installs the launchd plist, and checks each provider CLI is authed. It
-delegates to the runner package, so the box's systemd service never pulls in the
-CLI's UI dependencies.
-
-```bash
-hd init --host seb-mac --owner-email sebastian@higherops.io --install-launchd
-hd login
-```
-
-## Development
-
-```bash
-pnpm --filter @higherdev/cli dev -- status   # run from source
-pnpm --filter @higherdev/cli test
-pnpm --filter @higherdev/cli typecheck
-```
-
-`HIGHERDEV_CONFIG_DIR` points the config and session somewhere else, which is
-how to keep a scratch login separate from your real one.
+```sh
+npm install --global @higherdev/cli
+```
+
+Create `~/.config/hd/config.json` with an existing workspace API key:
+
+```json
+{
+  "current": "workspace",
+  "workspaces": {
+    "workspace": {
+      "url": "https://hdx-higher-ops.vercel.app",
+      "api_key": "hdx_..."
+    }
+  }
+}
+```
+
+The previous single-workspace config shape is migrated automatically when it is read.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `hd` | Open the live TUI when attached to a terminal |
+| `hd --help` | Show the HigherDEV banner and usage |
+| `hd status` | Show workspace, ticket, run, and decision status |
+| `hd ticket list` | List tickets |
+| `hd ticket show KEY` | Show one ticket |
+| `hd ticket new --title TITLE [options]` | Create a ticket |
+| `hd workspace new --name NAME --repo OWNER/NAME [options]` | Create a paused workspace |
+| `hd agents` | List agents |
+| `hd agents set ROLE --provider P --model M [--effort E]` | Update an agent |
+| `hd logs KEY [-f]` | Show or follow run events |
+| `hd msg KEY "message" [--interrupt]` | Message a builder |
+| `hd decide` | List open decisions |
+| `hd decide ID --answer TEXT` | Answer a decision |
+| `hd on` / `hd off` | Turn the workspace on or off |
+| `hd pause` / `hd resume` | Pause or resume the workspace |
+| `hd init [options]` | Configure this host and runner service |
+| `hd upgrade [options]` | Refresh this host configuration |
+
+Inside the TUI, use `/board`, `/inbox`, `/ticket`, `/decide`, `/agents`,
+`/settings`, `/workspace`, `/feed`, `/orchestrator`, `/refresh`, `/help`, or
+`/exit`. The display refreshes from the HDX API every five seconds.

package/dist/api.js

@@ -0,0 +1,85 @@
+import { loadConfig } from "./config.js";
+async function request(config, method, path, body) {
+    const response = await fetch(`${config.url}${path}`, {
+        method,
+        headers: {
+            authorization: `Bearer ${config.api_key}`,
+            ...(body ? { "content-type": "application/json" } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await response.text();
+    let parsed = null;
+    try {
+        parsed = text ? JSON.parse(text) : null;
+    }
+    catch {
+        throw new Error(`hd: ${response.status} ${text || response.statusText}`);
+    }
+    if (!response.ok) {
+        const err = parsed;
+        throw new Error(`hd: ${response.status} ${err.error ?? text}`);
+    }
+    return parsed;
+}
+export async function getStatus(config = loadConfig()) {
+    return request(config, "GET", `/api/w/${config.slug}/status`);
+}
+export async function listTickets(config = loadConfig()) {
+    return request(config, "GET", `/api/w/${config.slug}/tickets`);
+}
+export async function showTicket(key, config = loadConfig()) {
+    return request(config, "GET", `/api/w/${config.slug}/tickets/${encodeURIComponent(key)}`);
+}
+export async function createTicket(fields, config = loadConfig()) {
+    return request(config, "POST", `/api/w/${config.slug}/tickets`, fields);
+}
+export async function listTicketEvents(key, afterAt, afterId, config = loadConfig()) {
+    const query = new URLSearchParams();
+    if (afterAt)
+        query.set("after_at", afterAt);
+    if (afterId)
+        query.set("after_id", afterId);
+    const suffix = query.size ? `?${query.toString()}` : "";
+    return request(config, "GET", `/api/w/${config.slug}/tickets/${encodeURIComponent(key)}/events${suffix}`);
+}
+export async function postMessage(fields, config = loadConfig()) {
+    return request(config, "POST", `/api/w/${config.slug}/messages`, fields);
+}
+export async function answerDecision(id, answer_md, config = loadConfig()) {
+    return request(config, "POST", `/api/w/${config.slug}/decisions/${encodeURIComponent(id)}/answer`, { answer_md });
+}
+export async function setPaused(paused, config = loadConfig()) {
+    const path = paused ? `/api/w/${config.slug}/pause` : `/api/w/${config.slug}/resume`;
+    return request(config, "POST", path);
+}
+export async function createWorkspace(fields, config = loadConfig()) {
+    const result = await request(config, "POST", "/api/workspaces", fields);
+    return { ...result, url: config.url };
+}
+export async function listAgents(config = loadConfig()) {
+    return request(config, "GET", `/api/w/${config.slug}/agents`);
+}
+export async function updateAgent(id, fields, config = loadConfig()) {
+    return request(config, "PATCH", `/api/w/${config.slug}/agents`, { id, ...fields });
+}
+export async function listEpics(config = loadConfig()) {
+    return request(config, "GET", `/api/w/${config.slug}/epics`);
+}
+export async function listMessages(options = {}, config = loadConfig()) {
+    const query = new URLSearchParams();
+    if (options.ticketId)
+        query.set("ticket_id", options.ticketId);
+    if (options.since)
+        query.set("since", options.since);
+    if (options.limit)
+        query.set("limit", String(options.limit));
+    const suffix = query.size ? `?${query.toString()}` : "";
+    return request(config, "GET", `/api/w/${config.slug}/messages${suffix}`);
+}
+export async function updateCaps(provider_caps, config = loadConfig()) {
+    return request(config, "PATCH", `/api/w/${config.slug}/caps`, { provider_caps });
+}
+export async function listFeed(config = loadConfig()) {
+    return request(config, "GET", `/api/w/${config.slug}/feed`);
+}

package/dist/config.js

@@ -0,0 +1,80 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+export function configPath() {
+    return process.env.HD_CONFIG ?? join(homedir(), ".config/hd/config.json");
+}
+function normalizeWorkspace(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const row = value;
+    if (typeof row.url !== "string" || typeof row.api_key !== "string" || !row.url || !row.api_key) {
+        return null;
+    }
+    return { url: row.url.replace(/\/$/, ""), api_key: row.api_key };
+}
+function missing(path) {
+    return new Error(`missing ${path}\nWrite { "current": "workspace", "workspaces": { "workspace": { "url": "https://hdx-higher-ops.vercel.app", "api_key": "hdx_..." } } }`);
+}
+export function loadStoredConfig(path = configPath()) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        throw missing(path);
+    }
+    const parsed = JSON.parse(raw);
+    // 0.4 and earlier stored one workspace at the top level. Rewrite it once so
+    // every later read sees the multi-workspace format.
+    const legacy = normalizeWorkspace(parsed);
+    if (legacy && typeof parsed.slug === "string" && parsed.slug) {
+        const migrated = { current: parsed.slug, workspaces: { [parsed.slug]: legacy } };
+        writeStoredConfig(migrated, path);
+        return migrated;
+    }
+    const current = typeof parsed.current === "string" ? parsed.current : "";
+    const source = parsed.workspaces;
+    if (!current || !source || typeof source !== "object" || Array.isArray(source)) {
+        throw new Error(`${path} needs current and workspaces`);
+    }
+    const workspaces = {};
+    for (const [slug, value] of Object.entries(source)) {
+        const workspace = normalizeWorkspace(value);
+        if (workspace)
+            workspaces[slug] = workspace;
+    }
+    if (!workspaces[current])
+        throw new Error(`${path} current workspace ${current} is not configured`);
+    return { current, workspaces };
+}
+export function loadConfig(slug) {
+    const stored = loadStoredConfig();
+    const selected = slug ?? stored.current;
+    const workspace = stored.workspaces[selected];
+    if (!workspace)
+        throw new Error(`No configured workspace ${selected}.`);
+    return { ...workspace, slug: selected };
+}
+export function writeStoredConfig(config, path = configPath()) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+/** Store credentials for a workspace and make it current. */
+export function writeHdConfig(config, path = configPath()) {
+    const stored = existsSync(path)
+        ? loadStoredConfig(path)
+        : { current: config.slug, workspaces: {} };
+    stored.workspaces[config.slug] = { url: config.url.replace(/\/$/, ""), api_key: config.api_key };
+    stored.current = config.slug;
+    writeStoredConfig(stored, path);
+}
+export function switchWorkspace(slug, path = configPath()) {
+    const stored = loadStoredConfig(path);
+    const workspace = stored.workspaces[slug];
+    if (!workspace)
+        throw new Error(`No configured workspace ${slug}.`);
+    writeStoredConfig({ ...stored, current: slug }, path);
+    return { ...workspace, slug };
+}

package/dist/host.js

@@ -0,0 +1,179 @@
+import { execFile } from "node:child_process";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir, hostname } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { writeHdConfig } from "./config.js";
+const execFileAsync = promisify(execFile);
+export const LAUNCHD_LABEL = "io.higherops.hdx-runner";
+export const SYSTEMD_UNIT = "hdx-runner.service";
+export function repoRootFrom(fileUrl = import.meta.url) {
+    return path.resolve(path.dirname(fileURLToPath(fileUrl)), "../../..");
+}
+export function parseEnvFile(text) {
+    const out = {};
+    for (const line of text.split(/\r?\n/)) {
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        out[line.slice(0, eq)] = line.slice(eq + 1);
+    }
+    return out;
+}
+export function formatEnvFile(values) {
+    return `${Object.entries(values)
+        .map(([key, value]) => `${key}=${value}`)
+        .join("\n")}\n`;
+}
+function xmlEscape(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export function launchdPlist(opts) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>-lc</string>
+    <string>set -a; source "${xmlEscape(opts.envFile)}"; set +a; exec "${xmlEscape(opts.nodePath)}" --experimental-strip-types "${xmlEscape(opts.runnerPath)}"</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(opts.workDir)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(opts.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(opts.logPath)}</string>
+</dict>
+</plist>
+`;
+}
+export function systemdUnit(opts) {
+    return `[Unit]
+Description=HDX runner
+After=network-online.target
+
+[Service]
+Type=simple
+EnvironmentFile=${opts.envFile}
+WorkingDirectory=${opts.workDir}
+ExecStart=${opts.nodePath} --experimental-strip-types ${opts.runnerPath}
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function parseHostFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const next = () => {
+            const value = argv[i + 1];
+            if (!value || value.startsWith("--"))
+                throw new Error(`Missing value for ${arg}`);
+            i += 1;
+            return value;
+        };
+        if (arg === "--host")
+            flags.host = next();
+        else if (arg === "--env-out")
+            flags.envFile = next();
+        else if (arg === "--worktree-root")
+            flags.worktreeRoot = next();
+        else if (arg === "--install-launchd")
+            flags.installLaunchd = true;
+        else if (arg === "--install-systemd")
+            flags.installSystemd = true;
+        else if (arg === "--url")
+            flags.url = next();
+        else if (arg === "--api-key")
+            flags.apiKey = next();
+        else if (arg === "--slug")
+            flags.slug = next();
+        else if (arg === "--plist-out")
+            flags.plistOut = next();
+        else if (arg === "--unit-out")
+            flags.unitOut = next();
+        else
+            throw new Error(`Unknown option: ${arg}`);
+    }
+    return flags;
+}
+export async function initHost(flags, env = process.env) {
+    const home = homedir();
+    const host = flags.host || env.RUNNER_HOST || hostname().replace(/\..*$/, "").toLowerCase();
+    const envFile = flags.envFile || path.join(home, ".config/hdx/runner.env");
+    const worktreeRoot = flags.worktreeRoot || env.WORKTREE_ROOT || path.join(home, "hdx-worktrees");
+    const repo = repoRootFrom();
+    const runnerPath = path.join(repo, "apps/runner/src/index.ts");
+    const nodePath = process.execPath;
+    let existing = {};
+    try {
+        existing = parseEnvFile(await readFile(envFile, "utf8"));
+    }
+    catch {
+        existing = {};
+    }
+    const merged = {
+        ...existing,
+        SUPABASE_URL: env.SUPABASE_URL || existing.SUPABASE_URL || "https://skssvedzleumwhofkqxv.supabase.co",
+        SUPABASE_SECRET_KEY: env.SUPABASE_SECRET_KEY || existing.SUPABASE_SECRET_KEY || "",
+        RUNNER_HOST: host,
+        WORKTREE_ROOT: worktreeRoot,
+        GH_TOKEN: env.GH_TOKEN || existing.GH_TOKEN || "",
+    };
+    await mkdir(path.dirname(envFile), { recursive: true });
+    await writeFile(envFile, formatEnvFile(merged), { encoding: "utf8", mode: 0o600 });
+    await chmod(envFile, 0o600);
+    if (flags.url && flags.apiKey && flags.slug) {
+        writeHdConfig({ url: flags.url.replace(/\/$/, ""), api_key: flags.apiKey, slug: flags.slug });
+    }
+    const lines = [`hd init host=${host}`, `env: ${envFile}`];
+    const workDir = repo;
+    if (process.platform === "darwin" || flags.plistOut || flags.installLaunchd) {
+        const plistPath = flags.plistOut || path.join(home, "Library/LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+        const logPath = path.join(home, "Library/Logs/hdx-runner.log");
+        await mkdir(path.dirname(plistPath), { recursive: true });
+        await writeFile(plistPath, launchdPlist({ nodePath, runnerPath, envFile, logPath, workDir }), "utf8");
+        let loaded = false;
+        if (flags.installLaunchd && process.platform === "darwin") {
+            const uid = process.getuid?.() ?? 501;
+            const domain = `gui/${uid}`;
+            try {
+                await execFileAsync("launchctl", ["bootout", `${domain}/${LAUNCHD_LABEL}`]);
+            }
+            catch {
+                // First install has nothing to boot out.
+            }
+            await execFileAsync("launchctl", ["bootstrap", domain, plistPath]);
+            loaded = true;
+        }
+        lines.push(`launchd plist: ${plistPath}${loaded ? " (loaded)" : ""}`);
+    }
+    if (process.platform === "linux" || flags.unitOut || flags.installSystemd) {
+        const unitPath = flags.unitOut || path.join(home, ".config/systemd/user", SYSTEMD_UNIT);
+        await mkdir(path.dirname(unitPath), { recursive: true });
+        await writeFile(unitPath, systemdUnit({ nodePath, runnerPath, envFile, workDir }), "utf8");
+        let loaded = false;
+        if (flags.installSystemd && process.platform === "linux") {
+            await execFileAsync("systemctl", ["--user", "daemon-reload"]);
+            await execFileAsync("systemctl", ["--user", "enable", "--now", SYSTEMD_UNIT]);
+            loaded = true;
+        }
+        lines.push(`systemd unit: ${unitPath}${loaded ? " (enabled)" : ""}`);
+    }
+    lines.push("Start the runner service to register this host.");
+    return lines.join("\n");
+}