@higherdev/cli 0.7.0 → 0.9.0

package/README.md

@@ -34,8 +34,9 @@ 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 workspace new --name NAME --repo OWNER/NAME [options]` | Preflight GitHub, wire the runner, and 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 |
@@ -47,7 +48,11 @@ 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 |
 
+`hd workspace new` uses the operator's authenticated `gh`, defaults to the repository's real default
+branch, bootstraps an empty repository unless `--no-bootstrap` is set, and invites `mel-ilotus` unless
+`--runner-user USER` overrides it.
+
 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,8 @@ 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";
+import { HDX_RUNNER_GH_USER, preflightWorkspace } from "./workspace-preflight.js";
 function fail(message) {
     console.error(message);
     process.exit(1);
@@ -145,6 +147,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];
@@ -209,7 +219,7 @@ async function cmdDecide(argv) {
     await answerDecision(id, opts.answer);
     console.log("answered");
 }
-async function cmdWorkspace(argv) {
+async function cmdWorkspace(argv, deps = {}) {
     const [action, ...rest] = argv;
     if (action === "ls") {
         const current = loadConfig().slug;
@@ -223,14 +233,20 @@ async function cmdWorkspace(argv) {
         ])));
         return;
     }
+    const workspaceUsage = "usage: hd workspace ls | new --name NAME --repo OWNER/NAME [--slug S] [--branch B] [--host box] [--runner-user USER] [--no-bootstrap]";
     if (action !== "new")
-        fail("usage: hd workspace ls | new --name NAME --repo OWNER/NAME [--slug S] [--branch main] [--host box]");
-    const { opts } = flags(rest);
+        fail(workspaceUsage);
+    const { opts, bools } = flags(rest);
     if (!opts.name || !opts.repo) {
-        fail("usage: hd workspace new --name NAME --repo OWNER/NAME [--slug S] [--branch main] [--host box]");
+        fail(workspaceUsage);
     }
+    const preflight = await (deps.preflightWorkspace ?? preflightWorkspace)({ name: opts.name, repo: opts.repo,
+        branch: opts.branch, noBootstrap: bools.has("no-bootstrap"),
+        runnerUser: opts["runner-user"] ?? HDX_RUNNER_GH_USER });
+    if (preflight.invitationPending)
+        console.log(`invitation pending for ${opts["runner-user"] ?? HDX_RUNNER_GH_USER}`);
     const result = await createWorkspace({ name: opts.name, repo: opts.repo, slug: opts.slug,
-        default_branch: opts.branch ?? "main", default_host: opts.host ?? "box" });
+        default_branch: preflight.branch, default_host: opts.host ?? "box" });
     console.log(`workspace: ${result.workspace.slug}`);
     writeHdConfig({ url: result.url, api_key: result.api_key, slug: result.workspace.slug });
     console.log("saved and switched; configure another machine with:");
@@ -270,7 +286,7 @@ async function cmdAgents(argv) {
     });
     console.log(`${agent.role}  ${agent.provider}  ${agent.model}  ${agent.effort}`);
 }
-export async function main(argv = process.argv.slice(2)) {
+export async function main(argv = process.argv.slice(2), deps = {}) {
     const [cmd, ...rest] = argv;
     try {
         if (!cmd) {
@@ -303,6 +319,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;
@@ -316,7 +336,7 @@ export async function main(argv = process.argv.slice(2)) {
             return;
         }
         if (cmd === "workspace") {
-            await cmdWorkspace(rest);
+            await cmdWorkspace(rest, deps);
             return;
         }
         if (cmd === "agents") {

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/dist/workspace-preflight.js

@@ -0,0 +1,77 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+export const HDX_RUNNER_GH_USER = "mel-ilotus";
+export function preflightDecision(input) {
+    if (!input.found)
+        return { ok: false, error: "Repository was not found or is inaccessible." };
+    if (input.viewerPermission.toUpperCase() !== "ADMIN") {
+        return { ok: false, error: `Repository admin permission is required; viewer has ${input.viewerPermission || "none"}.` };
+    }
+    if (input.empty && input.noBootstrap) {
+        return { ok: false, error: "Repository is empty and --no-bootstrap was set." };
+    }
+    return { ok: true, bootstrap: input.empty };
+}
+function errorMessage(error) {
+    if (!error || typeof error !== "object")
+        return String(error);
+    const value = error;
+    return value.stderr?.trim() || value.message || String(error);
+}
+async function defaultGh(args) {
+    try {
+        return (await exec("gh", args, { encoding: "utf8", maxBuffer: 1024 * 1024 })).stdout;
+    }
+    catch (error) {
+        throw new Error(errorMessage(error));
+    }
+}
+async function repoView(repo, gh) {
+    return JSON.parse(await gh(["repo", "view", repo, "--json", "defaultBranchRef,isEmpty,viewerPermission"]));
+}
+function canPush(permission) {
+    return ["admin", "maintain", "write", "push"].includes(permission.toLowerCase());
+}
+export async function preflightWorkspace(input, gh = defaultGh) {
+    try {
+        await gh(["--version"]);
+    }
+    catch {
+        throw new Error("GitHub CLI is unavailable. Install it if needed, then run `gh auth login`.");
+    }
+    let view;
+    try {
+        view = await repoView(input.repo, gh);
+    }
+    catch (error) {
+        throw new Error(`GitHub repository ${input.repo} was not found or is inaccessible: ${errorMessage(error)}`);
+    }
+    const decision = preflightDecision({ found: true, empty: view.isEmpty,
+        viewerPermission: view.viewerPermission, noBootstrap: input.noBootstrap });
+    if (!decision.ok)
+        throw new Error(decision.error);
+    if (decision.bootstrap) {
+        await gh(["api", "-X", "PUT", `repos/${input.repo}/contents/README.md`,
+            "-f", "message=Initial commit", "-f", `content=${Buffer.from(`# ${input.name}`).toString("base64")}`]);
+        view = await repoView(input.repo, gh);
+    }
+    const branch = input.branch || view.defaultBranchRef?.name;
+    if (!branch)
+        throw new Error(`GitHub repository ${input.repo} has no default branch.`);
+    const runnerUser = input.runnerUser || HDX_RUNNER_GH_USER;
+    let permission = "none";
+    try {
+        const result = JSON.parse(await gh(["api", `repos/${input.repo}/collaborators/${runnerUser}/permission`]));
+        permission = result.permission ?? "none";
+    }
+    catch (error) {
+        if (!/404|not found/i.test(errorMessage(error)))
+            throw error;
+    }
+    const invitationPending = !canPush(permission);
+    if (invitationPending) {
+        await gh(["api", "-X", "PUT", `repos/${input.repo}/collaborators/${runnerUser}`, "-f", "permission=push"]);
+    }
+    return { branch, invitationPending };
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@higherdev/cli",
-  "version": "0.7.0",
+  "version": "0.9.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`