@higherdev/cli 0.7.0 → 0.8.0

package/README.md

@@ -34,6 +34,7 @@ workspace-map config shapes are migrated automatically when they are read.
 | `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 |
@@ -48,6 +49,6 @@ workspace-map config shapes are migrated automatically when they are read.
 | `hd upgrade [options]` | Refresh this host configuration |
 
 Inside the TUI, use `/board`, `/inbox`, `/ticket`, `/queue`, `/epic new`,
-`/epics`, `/decide`, `/agents`, `/settings`, `/workspace`, `/feed`,
+`/epics`, `/plan`, `/decide`, `/agents`, `/settings`, `/workspace`, `/feed`,
 `/orchestrator`, `/refresh`, `/help`, or `/exit`. The display refreshes from
 the HDX API every five seconds.

package/dist/index.js

@@ -6,6 +6,7 @@ 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);
@@ -145,6 +146,14 @@ async function cmdEpic(argv) {
     }
     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);
     const key = rest[0];
@@ -303,6 +312,10 @@ export async function main(argv = process.argv.slice(2)) {
             await cmdEpic(rest);
             return;
         }
+        if (cmd === "plan") {
+            await cmdPlan(rest);
+            return;
+        }
         if (cmd === "logs") {
             await cmdLogs(rest);
             return;

package/dist/out.js

@@ -66,6 +66,7 @@ export function usage() {
         `  ${c.blue("hd status")}                         workspace overview`,
         `  ${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

@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 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";
@@ -23,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;
@@ -347,6 +348,20 @@ export function App({ initial }) {
                     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) {
@@ -393,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

@@ -11,6 +11,7 @@ export const COMMANDS = [
     { 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/parse.js

@@ -39,6 +39,8 @@ export function parseLine(raw) {
             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.7.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`