neuvikon 0.2.17 → 0.2.18

package/README.md

@@ -57,12 +57,17 @@ 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.
+`cd`'d into this directory. If a coding agent CLI is installed (Claude Code,
+Cursor, Codex) it's launched in each terminal 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 { delimiter, dirname, join } from "node:path";
 import { 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,124 @@ 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/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 +1401,54 @@ 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;
+	}
+}
+async function buildLaunch(agent, credentials, ref) {
+	const text = await fetchTicketText(credentials, ref);
+	if (!text) return null;
+	return {
+		binary: agent.binary,
+		args: agent.buildArgs(text)
+	};
+}
+/**
 * 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.
 */
-async function spawnMode(refs) {
+async function spawnMode(flags, credentials, refs) {
 	const cwd = process.cwd();
+	const agent = await resolveAgentCli(flags);
 	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}`)}`);
+	for (const ref of refs) {
+		const launch = agent ? await buildLaunch(agent, credentials, ref) : 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 +1472,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 +1569,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.18",
   "description": "Tell Neuvikon which ticket your coding agent is working on.",
   "keywords": [
     "neuvikon",