@higherdev/cli 0.6.0 → 0.8.0

package/README.md

@@ -30,7 +30,11 @@ workspace-map config shapes are migrated automatically when they are read.
 | `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 ticket new --title TITLE [--acceptance TEXT] [options]` | Create a ticket |
+| `hd ticket queue KEY` | Queue a complete ticket now |
+| `hd epic new PATH [--title TITLE]` | Create an epic from a Markdown spec |
+| `hd epic list` | List epics and ticket progress |
+| `hd plan [--repo DIR]` | Hand the terminal to Codex to author an epic spec |
 | `hd workspace ls` | List every workspace available to the configured key |
 | `hd workspace new --name NAME --repo OWNER/NAME [options]` | Create a paused workspace |
 | `hd agents` | List agents |
@@ -44,6 +48,7 @@ workspace-map config shapes are migrated automatically when they are read.
 | `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.
+Inside the TUI, use `/board`, `/inbox`, `/ticket`, `/queue`, `/epic new`,
+`/epics`, `/plan`, `/decide`, `/agents`, `/settings`, `/workspace`, `/feed`,
+`/orchestrator`, `/refresh`, `/help`, or `/exit`. The display refreshes from
+the HDX API every five seconds.

package/dist/api.js

@@ -14,7 +14,7 @@ export function apiErrorMessage(status, parsed, fallback) {
         : trimmed;
     return `hd: ${status} ${body}`;
 }
-async function request(config, method, path, body) {
+async function request(config, method, path, body, verbatimError = false) {
     const response = await fetch(`${config.url}${path}`, {
         method,
         headers: {
@@ -32,6 +32,10 @@ async function request(config, method, path, body) {
         throw new Error(apiErrorMessage(response.status, null, text || response.statusText));
     }
     if (!response.ok) {
+        if (verbatimError && parsed && typeof parsed === "object" && "error" in parsed
+            && typeof parsed.error === "string") {
+            throw new Error(parsed.error);
+        }
         throw new Error(apiErrorMessage(response.status, parsed, text || response.statusText));
     }
     return parsed;
@@ -48,6 +52,9 @@ export async function showTicket(key, config = loadConfig()) {
 export async function createTicket(fields, config = loadConfig()) {
     return request(config, "POST", `/api/w/${config.slug}/tickets`, fields);
 }
+export async function queueTicket(key, config = loadConfig()) {
+    return request(config, "POST", `/api/w/${config.slug}/tickets/${encodeURIComponent(key)}/queue`, undefined, true);
+}
 export async function listTicketEvents(key, afterAt, afterId, config = loadConfig()) {
     const query = new URLSearchParams();
     if (afterAt)
@@ -83,6 +90,9 @@ export async function updateAgent(id, fields, config = loadConfig()) {
 export async function listEpics(config = loadConfig()) {
     return request(config, "GET", `/api/w/${config.slug}/epics`);
 }
+export async function createEpic(fields, config = loadConfig()) {
+    return request(config, "POST", `/api/w/${config.slug}/epics`, fields);
+}
 export async function listMessages(options = {}, config = loadConfig()) {
     const query = new URLSearchParams();
     if (options.ticketId)

package/dist/epics.js

@@ -0,0 +1,25 @@
+import { readFile } from "node:fs/promises";
+export function headingTitle(spec) {
+    const match = spec.match(/^#[ \t]+(.+?)\s*$/m);
+    const title = match?.[1]?.replace(/[ \t]+#+[ \t]*$/, "").trim();
+    return title || null;
+}
+export async function readEpicSpec(path, title) {
+    const spec_md = await readFile(path, "utf8");
+    const resolved = title?.trim() || headingTitle(spec_md);
+    if (!resolved)
+        throw new Error(`No # heading in ${path}. Pass --title TITLE.`);
+    return { title: resolved, spec_md };
+}
+export function epicProgressRows(epics, tickets) {
+    return epics.map((epic) => {
+        const linked = tickets.filter((ticket) => ticket.epic_id === epic.id);
+        return {
+            id: epic.id,
+            title: epic.title,
+            status: epic.status,
+            merged: linked.filter((ticket) => ticket.status === "merged").length,
+            total: linked.length,
+        };
+    });
+}

package/dist/index.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { answerDecision, createTicket, createWorkspace, getStatus, listAgents, listTicketEvents, listTickets, listWorkspaces, postMessage, setPaused, showTicket, updateAgent, } from "./api.js";
+import { answerDecision, createEpic, createTicket, createWorkspace, getStatus, listAgents, listEpics, listTicketEvents, listTickets, listWorkspaces, postMessage, queueTicket, setPaused, showTicket, updateAgent, } from "./api.js";
 import { initHost, parseHostFlags } from "./host.js";
 import { loadConfig, writeHdConfig } from "./config.js";
+import { epicProgressRows, readEpicSpec } from "./epics.js";
 import { banner, c, statusChip, table, truncate, usage } from "./out.js";
+import { launchArchitect } from "./plan.js";
 function fail(message) {
     console.error(message);
     process.exit(1);
@@ -96,7 +98,7 @@ async function cmdTicket(argv) {
     if (action === "new") {
         const { opts } = flags(rest);
         if (!opts.title)
-            fail("usage: hd ticket new --title TITLE [--body TEXT] [--area TAG] [--provider NAME] [--epic ID]");
+            fail("usage: hd ticket new --title TITLE [--body TEXT] [--acceptance TEXT] [--area TAG] [--provider NAME] [--epic ID]");
         const { ticket } = await createTicket({
             title: opts.title,
             body_md: opts.body,
@@ -108,7 +110,49 @@ async function cmdTicket(argv) {
         console.log(`${c.bold(ticket.key)}  ${statusChip(ticket.status)}  ${ticket.title}`);
         return;
     }
-    fail("usage: hd ticket list | show KEY | new --title TITLE");
+    if (action === "queue") {
+        const key = rest[0];
+        if (!key)
+            fail("usage: hd ticket queue KEY");
+        const { ticket } = await queueTicket(key.toUpperCase());
+        console.log(`${c.bold(ticket.key)}  ${statusChip(ticket.status)}`);
+        return;
+    }
+    fail("usage: hd ticket list | show KEY | new --title TITLE | queue KEY");
+}
+async function cmdEpic(argv) {
+    const [action, ...rest] = argv;
+    if (action === "list") {
+        const [{ epics }, { tickets }] = await Promise.all([listEpics(), listTickets()]);
+        const rows = epicProgressRows(epics, tickets);
+        if (!rows.length) {
+            console.log(c.dim("No epics."));
+            return;
+        }
+        console.log(table(["KEY", "STATUS", "PROGRESS", "TITLE"], rows.map((epic) => [
+            epic.id, statusChip(epic.status), `${epic.merged}/${epic.total}`, epic.title,
+        ])));
+        return;
+    }
+    if (action === "new") {
+        const { rest: paths, opts } = flags(rest);
+        const path = paths.join(" ");
+        if (!path)
+            fail("usage: hd epic new PATH [--title TITLE]");
+        const input = await readEpicSpec(path, opts.title);
+        const { epic } = await createEpic(input);
+        console.log(`${c.bold(epic.id)}  ${statusChip(epic.status)}  ${epic.title}`);
+        return;
+    }
+    fail("usage: hd epic new PATH [--title TITLE] | list");
+}
+async function cmdPlan(argv) {
+    const { rest, opts, bools } = flags(argv);
+    if (rest.length || bools.size || Object.keys(opts).some((key) => key !== "repo")) {
+        fail("usage: hd plan [--repo DIR]");
+    }
+    const { workspace } = await getStatus();
+    await launchArchitect({ workspaceRepo: workspace.repo, repo: opts.repo });
 }
 async function cmdLogs(argv) {
     const { rest, bools } = flags(argv);
@@ -264,6 +308,14 @@ export async function main(argv = process.argv.slice(2)) {
             await cmdTicket(rest);
             return;
         }
+        if (cmd === "epic") {
+            await cmdEpic(rest);
+            return;
+        }
+        if (cmd === "plan") {
+            await cmdPlan(rest);
+            return;
+        }
         if (cmd === "logs") {
             await cmdLogs(rest);
             return;

package/dist/out.js

@@ -64,7 +64,9 @@ export function usage() {
     return [
         c.bold("Usage"),
         `  ${c.blue("hd status")}                         workspace overview`,
-        `  ${c.blue("hd ticket list | show | new")}       ticket operations`,
+        `  ${c.blue("hd ticket list | show | new | queue")} ticket operations`,
+        `  ${c.blue("hd epic new PATH | list")}            epic operations`,
+        `  ${c.blue("hd plan [--repo DIR]")}               author an epic with Codex`,
         `  ${c.blue("hd workspace ls | new")}             list or create workspaces`,
         `  ${c.blue("hd agents [set]")}                   inspect or update agents`,
         `  ${c.blue("hd logs KEY [-f]")}                  run events`,

package/dist/plan.js

@@ -0,0 +1,94 @@
+import { spawn, spawnSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+const ARCHITECT_PROMPT = new URL("../prompts/architect.md", import.meta.url);
+function gitOutput(cwd, args) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return result.status === 0 ? result.stdout.trim() : null;
+}
+export function remoteRepo(remote) {
+    const trimmed = remote.trim().replace(/\/$/, "").replace(/\.git$/, "");
+    const scp = trimmed.match(/^[^@]+@[^:]+:(.+)$/);
+    if (scp)
+        return scp[1] ?? null;
+    try {
+        const url = new URL(trimmed);
+        return url.pathname.replace(/^\//, "") || null;
+    }
+    catch {
+        return trimmed.includes("/") ? trimmed : null;
+    }
+}
+function expanded(path) {
+    const value = path.trim();
+    if (value === "~")
+        return homedir();
+    if (value.startsWith("~/"))
+        return join(homedir(), value.slice(2));
+    return isAbsolute(value) ? value : resolve(value);
+}
+export function matchingWorkspaceRepo(directory, workspaceRepo) {
+    const root = gitOutput(expanded(directory), ["rev-parse", "--show-toplevel"]);
+    if (!root)
+        return null;
+    const origin = gitOutput(root, ["remote", "get-url", "origin"]);
+    return origin && remoteRepo(origin)?.toLowerCase() === workspaceRepo.toLowerCase() ? root : null;
+}
+async function askForRepo(workspaceRepo) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error(`Current directory is not ${workspaceRepo}. Pass --repo DIR.`);
+    }
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await prompt.question(`Repository directory for ${workspaceRepo}: `)).trim();
+    }
+    finally {
+        prompt.close();
+    }
+}
+export async function resolveWorkspaceRepo(workspaceRepo, requested) {
+    if (requested) {
+        const match = matchingWorkspaceRepo(requested, workspaceRepo);
+        if (!match)
+            throw new Error(`${requested} is not a checkout of ${workspaceRepo}.`);
+        return match;
+    }
+    const current = matchingWorkspaceRepo(process.cwd(), workspaceRepo);
+    if (current)
+        return current;
+    const answer = await askForRepo(workspaceRepo);
+    if (!answer)
+        throw new Error("A repository directory is required.");
+    const match = matchingWorkspaceRepo(answer, workspaceRepo);
+    if (!match)
+        throw new Error(`${answer} is not a checkout of ${workspaceRepo}.`);
+    return match;
+}
+export function verifyCodex(checkVersion = () => spawnSync("codex", ["--version"], { stdio: "ignore" })) {
+    const check = checkVersion();
+    if (check.error || check.status !== 0) {
+        throw new Error("Codex CLI is unavailable. Install it if needed, then run `codex login`.");
+    }
+}
+function runCodex(cwd, prompt) {
+    return new Promise((resolveRun, rejectRun) => {
+        const child = spawn("codex", [prompt], { cwd, stdio: "inherit" });
+        child.once("error", rejectRun);
+        child.once("exit", (code, signal) => {
+            if (code === 0)
+                resolveRun();
+            else
+                rejectRun(new Error(`codex exited ${signal ? `with signal ${signal}` : `with status ${code ?? "unknown"}`}.`));
+        });
+    });
+}
+export async function launchArchitect(options, runtime = {}) {
+    (runtime.verifyCodex ?? verifyCodex)();
+    const [cwd, prompt] = await Promise.all([
+        resolveWorkspaceRepo(options.workspaceRepo, options.repo),
+        readFile(ARCHITECT_PROMPT, "utf8"),
+    ]);
+    await (runtime.invokeCodex ?? runCodex)(cwd, prompt);
+}

package/dist/tui/App.js

@@ -1,6 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Box, Static, Text, useApp, useInput, useStdout } from "ink";
+import { epicProgressRows } from "../epics.js";
+import { launchArchitect } from "../plan.js";
 import { Banner } from "./Banner.js";
 import { Bubble } from "./Bubble.js";
 import { Cockpit, StreamPanel, boardTicketIds, nextCursor } from "./Dashboard.js";
@@ -14,7 +16,7 @@ import { alertOnce } from "./alert.js";
 import { bubbleRows } from "./height.js";
 import { planLayout, splitPanels } from "./layout.js";
 import { parseLine } from "./parse.js";
-import { configuredSlugs, decisionOptions, loadLiveEvents, loadTicketDetail, pollSnapshot, postOrchestrator, resolveDecision, switchWorkspace, updateAgent, updateProviderCap, } from "./data.js";
+import { configuredSlugs, createEpicFromFile, decisionOptions, loadLiveEvents, loadTicketDetail, pollSnapshot, postOrchestrator, queueTicket, resolveDecision, switchWorkspace, updateAgent, updateProviderCap, } from "./data.js";
 import { editFor, editableKeys, nextValue, seedFor, settingsRows } from "./settings-model.js";
 import { appendLines, runLabels, toStreamLines } from "./stream.js";
 import { UI } from "./theme.js";
@@ -22,7 +24,7 @@ import { WorkspaceLoads } from "./workspace-load.js";
 let messageSeq = 0;
 const nextId = () => `m${messageSeq++}`;
 export function App({ initial }) {
-    const { exit } = useApp();
+    const { exit, suspendTerminal } = useApp();
     const { stdout } = useStdout();
     const columns = stdout?.columns && stdout.columns > 0 ? stdout.columns : 80;
     const rows = stdout?.rows && stdout.rows > 0 ? stdout.rows : 24;
@@ -311,6 +313,55 @@ export function App({ initial }) {
                     setBusy(false);
                 }
                 return;
+            case "epic-new":
+                setBusy(true);
+                try {
+                    const { epic } = await createEpicFromFile(config, action.path);
+                    say("system", `Created epic ${epic.id}: ${epic.title}`);
+                    await refresh();
+                }
+                catch (error) {
+                    setNotice(error instanceof Error ? error.message : String(error));
+                }
+                finally {
+                    setBusy(false);
+                }
+                return;
+            case "epics": {
+                const rows = epicProgressRows(board.epics, board.tickets);
+                say("system", rows.length
+                    ? rows.map((epic) => `${epic.id}  ${epic.status}  ${epic.merged}/${epic.total}  ${epic.title}`).join("\n")
+                    : "No epics.");
+                return;
+            }
+            case "queue":
+                setBusy(true);
+                try {
+                    const { ticket: queued } = await queueTicket(config, action.key);
+                    say("system", `${queued.key} queued.`);
+                    await refresh();
+                }
+                catch (error) {
+                    setNotice(error instanceof Error ? error.message : String(error));
+                }
+                finally {
+                    setBusy(false);
+                }
+                return;
+            case "plan":
+                setBusy(true);
+                try {
+                    await suspendTerminal(() => launchArchitect({ workspaceRepo: workspace.repo }));
+                    say("system", "Architect session ended. Review the spec, then run /epic new PATH.");
+                    await refresh();
+                }
+                catch (error) {
+                    setNotice(error instanceof Error ? error.message : String(error));
+                }
+                finally {
+                    setBusy(false);
+                }
+                return;
             case "decide": {
                 const decision = board.decisions[0];
                 if (!decision) {
@@ -357,7 +408,8 @@ export function App({ initial }) {
             default:
                 return;
         }
-    }, [view, settings, applyEdit, board, browsing, mode, say, askOrchestrator, order, settingsOrder, changeWorkspace, config, refresh, exit]);
+    }, [view, settings, applyEdit, board, browsing, mode, say, askOrchestrator, order, settingsOrder, changeWorkspace,
+        config, workspace.repo, refresh, suspendTerminal, exit]);
     useInput((input, key) => {
         if (key.ctrl && input === "c")
             exit();

package/dist/tui/Help.js

@@ -8,6 +8,10 @@ export const COMMANDS = [
     { name: "/board", help: "the kanban board" },
     { name: "/inbox", help: "decisions and messages waiting on you" },
     { name: "/ticket", args: "HD-12", help: "open one ticket" },
+    { name: "/queue", args: "HD-12", help: "queue a complete ticket now" },
+    { name: "/epic", args: "new PATH", help: "create an epic from a Markdown spec" },
+    { name: "/epics", help: "list epics and ticket progress" },
+    { name: "/plan", help: "author an epic with your Codex CLI" },
     { name: "/decide", args: "2 | text", help: "answer the decision on screen" },
     { name: "/agents", help: "every agent in full, and the live run stream" },
     { name: "/settings", help: "change provider caps and agent settings" },

package/dist/tui/data.js

@@ -1,5 +1,6 @@
-import { answerDecision, getStatus, listAgents, listEpics, listFeed, listMessages, listTicketEvents, listTickets, listWorkspaces, postMessage as sendMessage, showTicket, updateAgent as patchAgent, updateCaps, } from "../api.js";
+import { answerDecision, createEpic as postEpic, getStatus, listAgents, listEpics, listFeed, listMessages, listTicketEvents, listTickets, listWorkspaces, postMessage as sendMessage, queueTicket as queueTicketNow, showTicket, updateAgent as patchAgent, updateCaps, } from "../api.js";
 import { loadConfig, switchWorkspace as selectWorkspace, } from "../config.js";
+import { readEpicSpec } from "../epics.js";
 export const POLL_MS = 5_000;
 export const providers = ["claude", "codex", "gemini", "grok"];
 export const efforts = ["low", "medium", "high"];
@@ -98,6 +99,12 @@ export async function postOrchestrator(body, config) {
 export async function loadTicketDetail(config, key) {
     return showTicket(key, config);
 }
+export async function createEpicFromFile(config, path) {
+    return postEpic(await readEpicSpec(path), config);
+}
+export async function queueTicket(config, key) {
+    return queueTicketNow(key, config);
+}
 export async function waitForReply(config, since, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() <= deadline) {

package/dist/tui/parse.js

@@ -29,6 +29,18 @@ export function parseLine(raw) {
             return argument
                 ? { kind: "ticket", key: argument.toUpperCase() }
                 : { kind: "unknown", command: "ticket needs a key" };
+        case "epic":
+            return rest[0]?.toLowerCase() === "new" && rest.length > 1
+                ? { kind: "epic-new", path: rest.slice(1).join(" ") }
+                : { kind: "unknown", command: "epic needs new PATH" };
+        case "epics":
+            return { kind: "epics" };
+        case "queue":
+            return argument
+                ? { kind: "queue", key: argument.toUpperCase() }
+                : { kind: "unknown", command: "queue needs a key" };
+        case "plan":
+            return argument ? { kind: "unknown", command: "plan takes no arguments" } : { kind: "plan" };
         case "decide": {
             const dismiss = /(^|\s)--(skip|dismiss)(\s|$)/.test(argument);
             return {

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@higherdev/cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "bin": {
     "hd": "dist/index.js"
   },
   "main": "dist/index.js",
   "files": [
-    "dist"
+    "dist",
+    "prompts"
   ],
   "scripts": {
     "build": "tsc",

package/prompts/architect.md

@@ -0,0 +1,23 @@
+You are helping the operator author an HDX epic for this repository.
+
+Start by interviewing the operator about the goal. Ask focused questions until the intended outcome, boundaries, and important tradeoffs are clear. Read the repository as needed so the plan reflects the code that actually exists.
+
+Draft the epic in this exact structure:
+
+# <title>
+
+## Goal
+
+## Scope
+
+## Out of scope
+
+## Acceptance
+
+## Constraints
+
+The operator is the author. Let them review and revise the draft before saving it. Do not submit the epic to HDX yourself.
+
+Once the operator accepts the spec, write it to `docs/epics/<slug>.md`, where `<slug>` is a concise kebab-case name for the epic. End by printing the exact next command, with the real path substituted:
+
+`hd epic new docs/epics/<slug>.md`