@higherdev/cli 0.11.0 → 0.11.1

package/README.md

@@ -14,7 +14,8 @@ Create `~/.config/hd/config.json` with an existing workspace API key:
 {
   "url": "https://hdx-higher-ops.vercel.app",
   "api_key": "hdx_...",
-  "current": "workspace"
+  "current": "workspace",
+  "repos": {}
 }
 ```
 
@@ -35,7 +36,7 @@ workspace-map config shapes are migrated automatically when they are read.
 | `hd ticket cancel KEY` | Cancel a ticket |
 | `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 plan [--repo DIR] [--clone-root 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]` | Preflight GitHub, wire the runner, and create a paused workspace |
 | `hd workspace set [options]` | Update settings; max turns uses `--max-turns KIND=N[,KIND=N...]` |
@@ -60,8 +61,12 @@ branch, bootstraps an empty repository unless `--no-bootstrap` is set, and invit
 the repository is missing, approve private creation interactively, use `--create` to force it, or
 `--no-create` to fail. Fully flagged calls remain non-interactive for scripts and Mel.
 
+`hd plan` remembers a matching checkout per workspace. If none exists, it offers to clone into
+`~/HigherDEV/<slug>`; change the parent with `--clone-root DIR`. An explicit `--repo DIR` is saved
+after its Git origin is verified.
+
 Inside the TUI, use `/board`, `/inbox`, `/ticket`, `/queue`, `/cancel`, `/epic new`,
-`/epics`, `/plan`, `/decide`, `/agents add`, `/agents rm`, `/settings`, `/workspace`,
+`/epics`, `/plan [--repo DIR]`, `/decide`, `/agents add`, `/agents rm`, `/settings`, `/workspace`,
 `/workspace new`, `/workspace set`, `/workspace rotate-key`, `/feed`,
 `/orchestrator`, `/refresh`, `/help`, or `/exit`. The display refreshes from
 the HDX API every five seconds.

package/dist/config.js

@@ -16,6 +16,11 @@ function normalizeConnection(value) {
 function missing(path) {
     return new Error(`missing ${path}\nWrite { "url": "https://hdx-higher-ops.vercel.app", "api_key": "hdx_...", "current": "workspace" }`);
 }
+function normalizeRepos(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => Boolean(entry[0]) && typeof entry[1] === "string" && Boolean(entry[1])));
+}
 export function loadStoredConfig(path = configPath()) {
     let raw;
     try {
@@ -27,13 +32,14 @@ export function loadStoredConfig(path = configPath()) {
     const parsed = JSON.parse(raw);
     const connection = normalizeConnection(parsed);
     const current = typeof parsed.current === "string" ? parsed.current : "";
+    const repos = normalizeRepos(parsed.repos);
     if (connection && current)
-        return { ...connection, current };
+        return { ...connection, current, repos };
     // 0.4 stored one workspace at the top level with `slug` rather than
     // `current`. One key can now reach every workspace, so only the selected
     // slug needs to survive.
     if (connection && typeof parsed.slug === "string" && parsed.slug) {
-        const migrated = { ...connection, current: parsed.slug };
+        const migrated = { ...connection, current: parsed.slug, repos };
         writeStoredConfig(migrated, path);
         return migrated;
     }
@@ -46,7 +52,7 @@ export function loadStoredConfig(path = configPath()) {
     const selected = normalizeConnection(source[current]);
     if (!selected)
         throw new Error(`${path} current workspace ${current} is not configured`);
-    const migrated = { ...selected, current };
+    const migrated = { ...selected, current, repos };
     writeStoredConfig(migrated, path);
     return migrated;
 }
@@ -62,10 +68,16 @@ export function writeStoredConfig(config, path = configPath()) {
 }
 /** Store one operator connection and make its selected workspace current. */
 export function writeHdConfig(config, path = configPath()) {
+    let repos = {};
+    try {
+        repos = loadStoredConfig(path).repos;
+    }
+    catch { }
     writeStoredConfig({
         url: config.url.replace(/\/$/, ""),
         api_key: config.api_key,
         current: config.slug,
+        repos,
     }, path);
 }
 export function switchWorkspace(slug, path = configPath()) {
@@ -73,3 +85,7 @@ export function switchWorkspace(slug, path = configPath()) {
     writeStoredConfig({ ...stored, current: slug }, path);
     return { url: stored.url, api_key: stored.api_key, slug };
 }
+export function rememberWorkspaceRepo(slug, directory, path = configPath()) {
+    const stored = loadStoredConfig(path);
+    writeStoredConfig({ ...stored, repos: { ...stored.repos, [slug]: directory } }, path);
+}

package/dist/index.js

@@ -157,11 +157,14 @@ async function cmdEpic(argv) {
 }
 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]");
+    if (rest.length || bools.size || Object.keys(opts).some((key) => !["repo", "clone-root"].includes(key))) {
+        fail("usage: hd plan [--repo DIR] [--clone-root DIR]");
     }
     const { workspace } = await getStatus();
-    await launchArchitect({ workspaceRepo: workspace.repo, repo: opts.repo });
+    const result = await launchArchitect({ workspaceRepo: workspace.repo, workspaceSlug: workspace.slug,
+        repo: opts.repo, cloneRoot: opts["clone-root"] });
+    if (result.cloneCommand)
+        console.log(`Clone it with: ${result.cloneCommand}`);
 }
 async function cmdLogs(argv) {
     const { rest, bools } = flags(argv);

package/dist/out.js

@@ -66,7 +66,7 @@ export function usage() {
         `  ${c.blue("hd status")}                         workspace overview`,
         `  ${c.blue("hd ticket list | show | new | queue | cancel")} 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 plan [--repo DIR] [--clone-root DIR]")} author an epic with Codex`,
         `  ${c.blue("hd workspace ls | new | set | rotate-key")} workspace operations`,
         `  ${c.blue("hd agents [add | rm | set]")}         manage agents`,
         `  ${c.blue("hd caps [set PROVIDER N]")}           provider concurrency`,

package/dist/plan.js

@@ -1,8 +1,11 @@
 import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
-import { createInterface } from "node:readline/promises";
+import { loadStoredConfig, rememberWorkspaceRepo } from "./config.js";
+import { promptOnStdin } from "./prompt.js";
+import { defaultGh } from "./workspace-preflight.js";
 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"] });
@@ -21,13 +24,13 @@ export function remoteRepo(remote) {
         return trimmed.includes("/") ? trimmed : null;
     }
 }
-function expanded(path) {
+function expanded(path, home = homedir(), cwd = process.cwd()) {
     const value = path.trim();
     if (value === "~")
-        return homedir();
+        return home;
     if (value.startsWith("~/"))
-        return join(homedir(), value.slice(2));
-    return isAbsolute(value) ? value : resolve(value);
+        return join(home, value.slice(2));
+    return isAbsolute(value) ? value : resolve(cwd, value);
 }
 export function matchingWorkspaceRepo(directory, workspaceRepo) {
     const root = gitOutput(expanded(directory), ["rev-parse", "--show-toplevel"]);
@@ -36,36 +39,6 @@ export function matchingWorkspaceRepo(directory, workspaceRepo) {
     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) {
@@ -84,11 +57,62 @@ function runCodex(cwd, prompt) {
         });
     });
 }
+function shellPath(path) {
+    return /^[A-Za-z0-9_./~-]+$/.test(path) ? path : `'${path.replaceAll("'", "'\\''")}'`;
+}
+export async function resolveWorkspaceRepo(options, runtime = {}) {
+    const matchRepo = runtime.matchRepo ?? matchingWorkspaceRepo;
+    const cwd = runtime.cwd?.() ?? process.cwd();
+    const home = runtime.home?.() ?? homedir();
+    const saveRepo = runtime.saveRepo ?? rememberWorkspaceRepo;
+    const accept = (directory) => {
+        saveRepo(options.workspaceSlug, directory);
+        return { directory };
+    };
+    if (options.repo) {
+        const match = matchRepo(options.repo, options.workspaceRepo);
+        if (!match)
+            throw new Error(`${options.repo} is not a checkout of ${options.workspaceRepo}.`);
+        return accept(match);
+    }
+    const saved = (runtime.savedRepo ?? ((slug) => loadStoredConfig().repos[slug]))(options.workspaceSlug);
+    if (saved) {
+        const match = matchRepo(saved, options.workspaceRepo);
+        if (match)
+            return { directory: match };
+    }
+    const current = matchRepo(cwd, options.workspaceRepo);
+    if (current)
+        return accept(current);
+    const defaultRoot = "~/HigherDEV";
+    const rootInput = options.cloneRoot ?? defaultRoot;
+    const root = expanded(rootInput, home, cwd);
+    const destination = join(root, options.workspaceSlug);
+    const shownDestination = join(rootInput, options.workspaceSlug);
+    const cloneCommand = `gh repo clone ${options.workspaceRepo} ${shellPath(shownDestination)}`;
+    const interactive = runtime.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (!interactive || ["n", "no"].includes((await (runtime.prompt ?? promptOnStdin)(`Clone ${options.workspaceRepo} to ${shownDestination}? [Y/n] `)).trim().toLowerCase()))
+        return { cloneCommand };
+    const gh = runtime.gh ?? defaultGh;
+    try {
+        await gh(["--version"]);
+    }
+    catch {
+        throw new Error("GitHub CLI is unavailable. Install it if needed, then run `gh auth login`.");
+    }
+    (runtime.mkdir ?? ((path) => mkdirSync(path, { recursive: true })))(root);
+    await gh(["repo", "clone", options.workspaceRepo, destination]);
+    const cloned = matchRepo(destination, options.workspaceRepo);
+    if (!cloned)
+        throw new Error(`Clone completed but ${destination} is not a checkout of ${options.workspaceRepo}.`);
+    return accept(cloned);
+}
 export async function launchArchitect(options, runtime = {}) {
+    const resolved = await resolveWorkspaceRepo(options, runtime);
+    if ("cloneCommand" in resolved)
+        return { launched: false, cloneCommand: resolved.cloneCommand };
     (runtime.verifyCodex ?? verifyCodex)();
-    const [cwd, prompt] = await Promise.all([
-        resolveWorkspaceRepo(options.workspaceRepo, options.repo),
-        readFile(ARCHITECT_PROMPT, "utf8"),
-    ]);
-    await (runtime.invokeCodex ?? runCodex)(cwd, prompt);
+    const prompt = await readFile(ARCHITECT_PROMPT, "utf8");
+    await (runtime.invokeCodex ?? runCodex)(resolved.directory, prompt);
+    return { launched: true };
 }

package/dist/prompt.js

@@ -0,0 +1,13 @@
+import { createInterface } from "node:readline/promises";
+export async function promptOnStdin(question, resumeStdin = false) {
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await prompt.question(question);
+    }
+    finally {
+        prompt.close();
+        // Ink restores raw mode and listeners, but it cannot read a paused stream.
+        if (resumeStdin)
+            process.stdin.resume();
+    }
+}

package/dist/tui/App.js

@@ -4,6 +4,7 @@ import { Box, Static, Text, useApp, useInput, useStdout } from "ink";
 import { loadConfig } from "../config.js";
 import { epicProgressRows } from "../epics.js";
 import { launchArchitect } from "../plan.js";
+import { promptOnStdin } from "../prompt.js";
 import { workspaceNew, workspaceRotateKey, workspaceSet } from "../workspace-commands.js";
 import { Banner } from "./Banner.js";
 import { Bubble } from "./Bubble.js";
@@ -25,6 +26,7 @@ import { UI } from "./theme.js";
 import { WorkspaceLoads } from "./workspace-load.js";
 let messageSeq = 0;
 const nextId = () => `m${messageSeq++}`;
+const tuiPrompt = (question) => promptOnStdin(question, true);
 export function App({ initial }) {
     const { exit, suspendTerminal } = useApp();
     const { stdout } = useStdout();
@@ -305,7 +307,7 @@ export function App({ initial }) {
                 try {
                     if (action.command === "new") {
                         let created;
-                        await suspendTerminal(async () => { created = await workspaceNew(action.args); });
+                        await suspendTerminal(async () => { created = await workspaceNew(action.args, { prompt: tuiPrompt }); });
                         if (!created)
                             throw new Error("Workspace wizard did not finish.");
                         await changeWorkspace(created.slug, loadConfig());
@@ -434,9 +436,21 @@ export function App({ initial }) {
             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();
+                    let result;
+                    await suspendTerminal(async () => {
+                        result = await launchArchitect({
+                            workspaceRepo: workspace.repo, workspaceSlug: workspace.slug,
+                            repo: action.repo, cloneRoot: action.cloneRoot,
+                        }, { prompt: tuiPrompt });
+                    });
+                    if (!result)
+                        throw new Error("Architect did not finish.");
+                    if (result.cloneCommand)
+                        say("system", `Clone it with: ${result.cloneCommand}`);
+                    else {
+                        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));

package/dist/tui/Help.js

@@ -12,7 +12,7 @@ export const COMMANDS = [
     { name: "/cancel", args: "HD-12", help: "cancel a ticket" },
     { 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: "/plan", args: "[--repo DIR]", help: "author an epic with your Codex CLI" },
     { name: "/decide", args: "2 | text", help: "answer the decision on screen" },
     { name: "/agents", args: "[add ... | rm ROLE|ID]", help: "view or manage agents" },
     { name: "/settings", help: "change provider caps and agent settings" },

package/dist/tui/parse.js

@@ -60,8 +60,20 @@ export function parseLine(raw) {
         case "cancel":
             return argument ? { kind: "cancel", key: argument.toUpperCase() }
                 : { kind: "unknown", command: "cancel needs a key" };
-        case "plan":
-            return argument ? { kind: "unknown", command: "plan takes no arguments" } : { kind: "plan" };
+        case "plan": {
+            const opts = {};
+            for (let i = 0; i < rest.length; i += 2) {
+                if (!rest[i]?.startsWith("--") || !rest[i + 1]) {
+                    return { kind: "unknown", command: "plan accepts --repo DIR and --clone-root DIR" };
+                }
+                opts[rest[i].slice(2)] = rest[i + 1];
+            }
+            if (Object.keys(opts).some((key) => !["repo", "clone-root"].includes(key))) {
+                return { kind: "unknown", command: "plan accepts --repo DIR and --clone-root DIR" };
+            }
+            return { kind: "plan", ...(opts.repo ? { repo: opts.repo } : {}),
+                ...(opts["clone-root"] ? { cloneRoot: opts["clone-root"] } : {}) };
+        }
         case "decide": {
             const dismiss = /(^|\s)--(skip|dismiss)(\s|$)/.test(argument);
             return {

package/dist/workspace-commands.js

@@ -1,6 +1,6 @@
-import { createInterface } from "node:readline/promises";
 import { createWorkspace, rotateWorkspaceApiKey, updateWorkspace } from "./api.js";
 import { loadConfig, writeHdConfig } from "./config.js";
+import { promptOnStdin } from "./prompt.js";
 import { defaultGh, HDX_RUNNER_GH_USER, preflightWorkspace } from "./workspace-preflight.js";
 export const WORKSPACE_USAGE = "usage: hd workspace ls | new --name NAME --repo OWNER/NAME [--create|--no-create] [flags] | set [flags] | rotate-key";
 function flags(argv) {
@@ -44,12 +44,7 @@ async function repoState(repo, gh) {
     }
 }
 function lazyPrompt(deps) {
-    let readline;
-    const ask = deps.prompt ?? (async (question) => {
-        readline ??= createInterface({ input: process.stdin, output: process.stdout });
-        return readline.question(question);
-    });
-    return { ask, close: () => readline?.close() };
+    return deps.prompt ?? promptOnStdin;
 }
 async function askDefault(ask, label, fallback = "") {
     const answer = (await ask(`${label}${fallback ? ` [${fallback}]` : ""}: `)).trim();
@@ -65,7 +60,7 @@ export async function workspaceNew(argv, deps = {}) {
         throw new Error(WORKSPACE_USAGE);
     const gh = deps.gh ?? defaultGh;
     const prompt = lazyPrompt(deps);
-    try {
+    {
         let name = opts.name ?? "";
         let repo = opts.repo ?? "";
         let branch = opts.branch;
@@ -79,7 +74,7 @@ export async function workspaceNew(argv, deps = {}) {
             }
         }
         if (guided) {
-            name = await askDefault(prompt.ask, "Name", name);
+            name = await askDefault(prompt, "Name", name);
             if (!name)
                 throw new Error("Name is required.");
             let defaultRepo = repo;
@@ -87,7 +82,7 @@ export async function workspaceNew(argv, deps = {}) {
                 const owner = (await gh(["api", "user", "--jq", ".login"])).trim();
                 defaultRepo = `${owner}/${workspaceSlug(name)}`;
             }
-            repo = await askDefault(prompt.ask, "Repo", defaultRepo);
+            repo = await askDefault(prompt, "Repo", defaultRepo);
             if (!repo)
                 throw new Error("Repo is required.");
         }
@@ -97,17 +92,17 @@ export async function workspaceNew(argv, deps = {}) {
         if (state && !state.found) {
             if (bools.has("no-create"))
                 throw new Error(`GitHub repository ${repo} does not exist and --no-create was set.`);
-            const create = bools.has("create") || (interactive && yes(await prompt.ask(`Create ${repo} as a private GitHub repo? [Y/n] `)));
+            const create = bools.has("create") || (interactive && yes(await prompt(`Create ${repo} as a private GitHub repo? [Y/n] `)));
             if (!create)
                 throw new Error(`GitHub repository ${repo} was not created.`);
             await gh(["repo", "create", repo, "--private"]);
             state = { found: true, branch: "main" };
         }
         if (guided) {
-            branch = await askDefault(prompt.ask, "Branch", branch ?? state?.branch ?? "main");
-            host = await askDefault(prompt.ask, "Host", host);
+            branch = await askDefault(prompt, "Branch", branch ?? state?.branch ?? "main");
+            host = await askDefault(prompt, "Host", host);
             const summary = `${name} | ${repo} | ${branch} | host ${host}`;
-            if (!yes(await prompt.ask(`Create ${summary}. Proceed? [Y/n] `)))
+            if (!yes(await prompt(`Create ${summary}. Proceed? [Y/n] `)))
                 throw new Error("Workspace creation cancelled.");
         }
         const preflight = await (deps.preflightWorkspace ?? preflightWorkspace)({
@@ -122,9 +117,6 @@ export async function workspaceNew(argv, deps = {}) {
             runnerUser: opts["runner-user"] ?? HDX_RUNNER_GH_USER,
             initCommand: `hd init --url ${result.url} --api-key ${result.api_key} --slug ${result.workspace.slug}` };
     }
-    finally {
-        prompt.close();
-    }
 }
 export async function workspaceSet(argv) {
     const { opts, bools, rest } = flags(argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@higherdev/cli",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "type": "module",
   "bin": {
     "hd": "dist/index.js"
@@ -13,6 +13,7 @@
   "scripts": {
     "build": "tsc",
     "test": "pnpm build && node --experimental-strip-types --test test/*.test.ts",
+    "test:pty": "pnpm build && expect test/tui-prompt.expect",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {