neuvikon 0.2.17 → 0.2.19

package/README.md

@@ -55,14 +55,22 @@ pbpaste | npx neuvikon start
 npx neuvikon start --tickets EWWQ-1,EWWQ-2,EWWQ-3 --spawn
 ```
 
-Opens one terminal per ticket (a tmux window if you're already in tmux, an
-iTerm2 or Terminal.app tab on macOS, a Windows Terminal tab on Windows), each
-`cd`'d into this directory with the ticket ref printed and waiting — nothing
-is tracked automatically. That's deliberate: a session only scopes safely
-once an agent is actually running in that terminal, so paste the ticket into
-your agent (or run `npx neuvikon start --ticket EWWQ-1`) once it's up, same
-as any other ticket. On a platform or terminal this can't drive, it just
-prints the same command for you to paste by hand.
+If [Herdr](https://herdr.dev) is installed, every ticket in the batch lands as
+its own tab in one Herdr workspace instead of separate OS windows — Herdr's
+own UI then shows each agent's live working/blocked/done state. Otherwise it
+opens one terminal per ticket the usual way (a tmux window if you're already
+in tmux, an iTerm2 or Terminal.app tab on macOS, a Windows Terminal tab on
+Windows), each `cd`'d into this directory. Either way, if a coding agent CLI
+is installed (Claude Code, Cursor, Codex) it's launched with that ticket's
+full text as its first prompt — same substance a manual paste would give it.
+With more than one installed, you're asked once which to use and that choice
+is remembered (`--agent <name>` overrides it any time). Nothing is tracked
+automatically, even then: a session only scopes safely once an agent is
+actually running, so the launched agent runs `npx neuvikon start --ticket
+EWWQ-1` itself once it's up, via its rules file, same as a manual paste
+always has. Without a detected agent, or on a platform/terminal this can't
+drive, it just prints the ticket ref and that command for you to paste by
+hand.
 
 ## Project pages
 

package/dist/index.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { spawn } from "node:child_process";
+import { delimiter, dirname, join } from "node:path";
+import { execFileSync, spawn } from "node:child_process";
+import { createInterface } from "node:readline/promises";
 //#region src/api.ts
 var ApiError = class extends Error {
 	status;
@@ -79,6 +80,23 @@ function resolveDeployment(flags) {
 const DEFAULT_SITE_URL = process.env.NEUVIKON_URL ?? DEPLOYMENTS.production.api;
 const CONFIG_DIR = join(homedir(), ".neuvikon");
 const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+function readConfigFile() {
+	try {
+		const parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+		return typeof parsed === "object" && parsed !== null ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+function writeConfigFile(config) {
+	mkdirSync(CONFIG_DIR, {
+		recursive: true,
+		mode: 448
+	});
+	chmodSync(CONFIG_DIR, 448);
+	writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, { mode: 384 });
+	chmodSync(CONFIG_PATH, 384);
+}
 /**
 * Somewhere a browser cannot open — CI, a container, a remote box — there is no
 * way to complete a device login, so a token handed in through the environment
@@ -116,16 +134,15 @@ function readCredentials() {
 /**
 * A token on disk is only as safe as its permissions, so directory and file are
 * locked to the owner on every write, not just on first create — an earlier
-* version may have left them readable.
+* version may have left them readable. Merges over the existing file rather
+* than replacing it outright, so a re-login doesn't silently drop unrelated
+* settings this file has grown since (e.g. `preferredAgent`).
 */
 function writeCredentials(credentials) {
-	mkdirSync(CONFIG_DIR, {
-		recursive: true,
-		mode: 448
+	writeConfigFile({
+		...readConfigFile(),
+		...credentials
 	});
-	chmodSync(CONFIG_DIR, 448);
-	writeFileSync(CONFIG_PATH, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 384 });
-	chmodSync(CONFIG_PATH, 384);
 }
 function clearCredentials() {
 	try {
@@ -135,6 +152,22 @@ function clearCredentials() {
 		return false;
 	}
 }
+/**
+* Which agent CLI `start --spawn` should launch without asking, remembered
+* across invocations once the user has answered the question once. Kept in
+* the same config file as credentials rather than a separate one — it's the
+* same "settings for this machine" concern.
+*/
+function readPreferredAgent() {
+	const value = readConfigFile().preferredAgent;
+	return typeof value === "string" && value ? value : null;
+}
+function writePreferredAgent(id) {
+	writeConfigFile({
+		...readConfigFile(),
+		preferredAgent: id
+	});
+}
 //#endregion
 //#region src/session.ts
 /**
@@ -1134,20 +1167,234 @@ async function pages(flags, positional) {
 	}
 }
 //#endregion
+//#region src/agentCli.ts
+const KNOWN_AGENT_CLIS = [
+	{
+		id: "claude-code",
+		label: "Claude Code",
+		binary: "claude",
+		buildArgs: (prompt) => [prompt]
+	},
+	{
+		id: "cursor",
+		label: "Cursor",
+		binary: "cursor-agent",
+		buildArgs: (prompt) => [prompt]
+	},
+	{
+		id: "codex",
+		label: "Codex",
+		binary: "codex",
+		buildArgs: (prompt) => [prompt]
+	}
+];
+/**
+* Manual PATH scan instead of shelling out to `which`/`where`: keeps this
+* dependency-free and synchronous, and doesn't assume either helper exists
+* (minimal containers, and Windows has neither `which` nor always `where`
+* usable from a spawned child the same way).
+*/
+function isOnPath(binary) {
+	const pathEnv = process.env.PATH ?? "";
+	const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+	for (const dir of pathEnv.split(delimiter)) {
+		if (!dir) continue;
+		for (const ext of exts) if (existsSync(join(dir, binary + ext))) return true;
+	}
+	return false;
+}
+function detectAgentClis() {
+	return KNOWN_AGENT_CLIS.filter((agent) => isOnPath(agent.binary));
+}
+function findById(id) {
+	return KNOWN_AGENT_CLIS.find((agent) => agent.id === id);
+}
+/**
+* Only prompts when stdin is a real terminal: `--tickets`/`--spawn` never
+* reads stdin for the ticket itself (unlike plain `start`), so it's free for
+* this, but a non-interactive invocation (CI, a script) must never block on
+* input that will never arrive.
+*/
+async function promptForAgent(candidates) {
+	if (!process.stdin.isTTY) return candidates[0] ?? null;
+	info("Multiple coding agents found on this machine:");
+	candidates.forEach((agent, index) => info(`  ${index + 1}. ${agent.label}`));
+	info(dim("This choice is remembered — override any time with --agent <name>."));
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	try {
+		for (;;) {
+			const answer = (await rl.question(`Which one should Neuvikon launch? [1-${candidates.length}]: `)).trim();
+			const picked = candidates[Number(answer) - 1];
+			if (picked) return picked;
+			info(dim(`Enter a number from 1 to ${candidates.length}.`));
+		}
+	} finally {
+		rl.close();
+	}
+}
+/**
+* Resolves which agent CLI (if any) `--spawn` should launch. `--agent` is a
+* one-off override and is never persisted, same as `--tool` never rewrites
+* anything. Otherwise: a stored preference wins as long as it's still on
+* this machine's PATH (an uninstalled tool shouldn't stay sticky forever);
+* failing that, one candidate is used silently, and more than one is asked
+* about exactly once and then remembered.
+*/
+async function resolveAgentCli(flags) {
+	const explicit = flags.get("agent");
+	if (explicit) {
+		const agent = findById(explicit);
+		if (!agent) fail(`Unknown agent "${explicit}".`, `Expected one of: ${KNOWN_AGENT_CLIS.map((a) => a.id).join(", ")}.`);
+		return agent;
+	}
+	const candidates = detectAgentClis();
+	if (candidates.length === 0) return null;
+	const preferredId = readPreferredAgent();
+	if (preferredId) {
+		const preferred = candidates.find((agent) => agent.id === preferredId);
+		if (preferred) return preferred;
+	}
+	const picked = candidates.length === 1 ? candidates[0] : await promptForAgent(candidates);
+	if (picked) writePreferredAgent(picked.id);
+	return picked;
+}
+//#endregion
+//#region src/herdr.ts
+/** Herdr's `--kind` values for the agents we already know how to pick between. */
+const HERDR_KIND = {
+	"claude-code": "claude",
+	codex: "codex",
+	cursor: "cursor"
+};
+function herdrAvailable() {
+	return isOnPath("herdr");
+}
+/** Every mutating Herdr socket-API command prints one JSON object; a failure prints to stderr instead. */
+function runHerdr(args) {
+	try {
+		const output = execFileSync("herdr", args, {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+		return JSON.parse(output);
+	} catch {
+		return null;
+	}
+}
+/**
+* Herdr's `agent start` requires a name matching `[a-z][a-z0-9_-]{0,31}`,
+* unique among live agents. A ticket ref (`NS-60`) lowercases straight into
+* that shape, and reusing the ref as the name is what makes `herdr agent
+* get NS-60`-style lookups obvious later.
+*/
+function agentName(ref) {
+	return ref.toLowerCase();
+}
+/**
+* One Herdr workspace per `--spawn` call, one tab per ticket, so a whole
+* batch shows up together in Herdr's own UI — with its live
+* working/blocked/done state per agent — instead of scattered across OS
+* windows. The first successful ref seeds the workspace; every later ref in
+* the same batch adds a tab to it.
+*/
+var HerdrBatch = class {
+	workspaceId = null;
+	openPane(ref, cwd) {
+		if (!this.workspaceId) {
+			const created = runHerdr([
+				"workspace",
+				"create",
+				"--cwd",
+				cwd,
+				"--label",
+				ref,
+				"--focus"
+			]);
+			if (!created) return null;
+			this.workspaceId = created.result.workspace.workspace_id;
+			return created.result.root_pane.pane_id;
+		}
+		return runHerdr([
+			"tab",
+			"create",
+			"--workspace",
+			this.workspaceId,
+			"--cwd",
+			cwd,
+			"--label",
+			ref,
+			"--focus"
+		])?.result.root_pane.pane_id ?? null;
+	}
+	/**
+	* True once this ref has a live Herdr pane — even if starting an agent in
+	* it failed, in which case the pane still exists with the same
+	* print-and-wait fallback a plain spawned terminal gets. False only means
+	* Herdr itself couldn't be reached, and the caller should fall back to
+	* opening a native OS terminal for this ref instead.
+	*/
+	spawn(ref, cwd, agent, ticketText) {
+		const paneId = this.openPane(ref, cwd);
+		if (!paneId) return false;
+		if (agent && ticketText) {
+			if (runHerdr([
+				"agent",
+				"start",
+				agentName(ref),
+				"--kind",
+				HERDR_KIND[agent.id],
+				"--pane",
+				paneId
+			])) {
+				runHerdr([
+					"agent",
+					"prompt",
+					agentName(ref),
+					ticketText
+				]);
+				return true;
+			}
+		}
+		runHerdr([
+			"pane",
+			"run",
+			paneId,
+			`echo 'Ticket: ${ref}' && echo 'Paste it into your agent, or run: npx neuvikon start --ticket ${ref}'`
+		]);
+		return true;
+	}
+};
+//#endregion
 //#region src/terminal.ts
 function shQuote(value) {
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 /**
-* Deliberately does not run `neuvikon start` itself: that only scopes safely
-* once an agent is attached (see session.ts's instanceKey), and nothing is
-* attached yet in a terminal that just opened. Printing the ticket and
-* dropping to a shell lets the user launch their agent first, same as typing
-* the ticket by hand always has.
+* Never `exec`s the agent in place: if it's the wrong binary, isn't actually
+* installed, or the user just exits it, the terminal must not go on to close
+* or hang — it drops to the same interactive shell either way, ticket ref
+* already printed above.
+*
+* Still deliberately does not run `neuvikon start` itself: that only scopes
+* safely once an agent is attached (see session.ts's instanceKey), and
+* nothing is attached yet in a terminal that just opened. Launching the
+* agent (rather than `start`) is safe precisely because the agent is the one
+* that calls `start`, once it's actually running, via the rules file — same
+* as if the ticket had been pasted in by hand.
 */
-function buildInnerCommand({ ref, cwd }) {
-	const echoes = [`Ticket: ${ref}`, `Paste it into your agent, or run: npx neuvikon start --ticket ${ref}`].map((line) => `echo ${shQuote(line)}`).join(" && ");
-	return `cd ${shQuote(cwd)} && ${echoes} && exec $SHELL -l`;
+function buildInnerCommand({ ref, cwd, launch }) {
+	const lines = [`Ticket: ${ref}`];
+	if (!launch) lines.push(`Paste it into your agent, or run: npx neuvikon start --ticket ${ref}`);
+	const echoes = lines.map((line) => `echo ${shQuote(line)}`).join(" && ");
+	const launchCmd = launch ? `${launch.binary} ${launch.args.map(shQuote).join(" ")}; ` : "";
+	return `cd ${shQuote(cwd)} && ${echoes} && ${launchCmd}exec $SHELL -l`;
 }
 function escapeAppleScript(value) {
 	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
@@ -1264,22 +1511,60 @@ async function resolveRefs(flags, positional) {
 	return [await resolveRef(flags, positional)];
 }
 /**
+* Best effort, same shape as `spawnTerminal` itself: a ticket that can't be
+* fetched (offline, a typo'd ref, a revoked token) degrades that one terminal
+* back to the plain print-and-shell fallback rather than failing the whole
+* batch, or worse, launching an agent with nothing to work from.
+*/
+async function fetchTicketText(credentials, ref) {
+	try {
+		return (await post(credentials.url, "/api/agent/ticket", {
+			token: credentials.token,
+			ticketRef: ref
+		})).text;
+	} catch {
+		return null;
+	}
+}
+/**
 * Opens one terminal per ref and stops there — it deliberately never calls
 * `start` itself. A session file written outside of a running agent has no
 * CLAUDE_CODE_SESSION_ID to scope it, so two of these firing in the same
 * directory before either agent launches would each read the other's
-* not-yet-attached session as "existing" and stop it out from under it.
-* Letting the user (or their agent) run `start` once it's actually running
-* is what keeps concurrent tracking safe.
+* not-yet-attached session as "existing" and stop it out from under it. That
+* still holds here: a detected agent CLI is launched with the ticket's text
+* as its first prompt, but this never calls `start` itself — the agent does,
+* once it's actually running, via the rules file, exactly as if the ticket
+* had been pasted in by hand.
+*
+* Herdr, when installed, wins over a native OS terminal: it's a multiplexer
+* built for exactly this (multiple coding agents, one UI, live
+* working/blocked/done state), so a whole `--tickets` batch lands as one
+* Herdr workspace with one tab per ticket instead of scattered app windows.
 */
-async function spawnMode(refs) {
+async function spawnMode(flags, credentials, refs) {
 	const cwd = process.cwd();
-	info(`Opening ${refs.length} terminal${refs.length === 1 ? "" : "s"} in ${cwd}...`);
-	for (const ref of refs) if (spawnTerminal({
-		ref,
-		cwd
-	})) success(`${bold(ref)} — new terminal opened`);
-	else info(`${bold(ref)} — couldn't open a terminal here, paste manually: ${dim(`npx neuvikon start --ticket ${ref}`)}`);
+	const agent = await resolveAgentCli(flags);
+	const herdr = herdrAvailable() ? new HerdrBatch() : null;
+	info(`Opening ${refs.length} terminal${refs.length === 1 ? "" : "s"}${herdr ? " in Herdr" : ` in ${cwd}`}...`);
+	for (const ref of refs) {
+		const ticketText = agent ? await fetchTicketText(credentials, ref) : null;
+		if (herdr?.spawn(ref, cwd, agent, ticketText)) {
+			success(`${bold(ref)} — ${agent && ticketText ? `${agent.label} starting in Herdr` : "opened in Herdr"}`);
+			continue;
+		}
+		const launch = agent && ticketText ? {
+			binary: agent.binary,
+			args: agent.buildArgs(ticketText)
+		} : null;
+		const startingLabel = launch && agent ? agent.label : null;
+		if (spawnTerminal({
+			ref,
+			cwd,
+			launch
+		})) success(startingLabel ? `${bold(ref)} — ${startingLabel} starting` : `${bold(ref)} — new terminal opened`);
+		else info(`${bold(ref)} — couldn't open a terminal here, paste manually: ${dim(`npx neuvikon start --ticket ${ref}`)}`);
+	}
 }
 async function resolveRef(flags, positional) {
 	const explicit = flags.get("ticket") ?? positional[0];
@@ -1303,7 +1588,7 @@ async function start(flags, positional) {
 	const credentials = readCredentials();
 	if (!credentials) fail("Not logged in.", "Run `npx neuvikon login` first.");
 	if (flags.has("tickets") && !flags.has("spawn")) fail("--tickets needs --spawn.", "Opening more than one terminal is the only thing --tickets does.");
-	if (flags.has("spawn")) return spawnMode(await resolveRefs(flags, positional));
+	if (flags.has("spawn")) return spawnMode(flags, credentials, await resolveRefs(flags, positional));
 	const ref = await resolveRef(flags, positional);
 	const tool = flags.get("tool") ?? detectTool();
 	if (!TOOLS.has(tool)) fail(`Unknown tool "${tool}".`, `Expected one of: ${[...TOOLS].join(", ")}.`);
@@ -1400,6 +1685,7 @@ ${bold("Project pages")}
 
 ${bold("Options")}
   --tool <name>                   claude-code | codex | cursor | other
+  --agent <name>                  claude-code | codex | cursor — which agent CLI --spawn launches
   --transcript <path>             Read token usage from an agent transcript
   --tokens-in <n> --tokens-out <n>
   --dev                           Use the development deployment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neuvikon",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "Tell Neuvikon which ticket your coding agent is working on.",
   "keywords": [
     "neuvikon",