neuvikon 0.2.16 → 0.2.18

package/README.md

@@ -36,6 +36,7 @@ as being worked on, by whom, with which tool.
 | `neuvikon login` | Sign in through the browser and set up the current project |
 | `neuvikon init` | Set up another project (credentials are per-machine, rules are per-project) |
 | `neuvikon start --ticket EWWQ-1` | Begin tracking. `--tool claude-code\|codex\|cursor\|other` |
+| `neuvikon start --tickets EWWQ-1,EWWQ-2 --spawn` | Open one terminal per ticket instead of tracking one here |
 | `neuvikon stop` | Stop tracking |
 | `neuvikon status` | Login, project setup, current ticket |
 | `neuvikon logout` | Revoke this machine's token and forget it |
@@ -48,6 +49,26 @@ as being worked on, by whom, with which tool.
 pbpaste | npx neuvikon start
 ```
 
+## Kicking off several tickets at once
+
+```sh
+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. 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
 
 An agent's most useful output often isn't the ticket, it's what it learned

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,6 +1167,210 @@ 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, `'\\''`)}'`;
+}
+/**
+* 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, 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, "\\\"");
+}
+/**
+* Same shape as openBrowser: fire-and-forget, never throws. A `false` return
+* means the spawn call itself failed synchronously (e.g. the binary isn't on
+* PATH) — the async case (binary exists but the app itself errors) is
+* swallowed by the "error" listener, same tradeoff openBrowser already makes.
+*/
+function fireAndForget(command, args) {
+	try {
+		const child = spawn(command, args, {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
+function spawnViaTmux(target) {
+	return fireAndForget("tmux", [
+		"new-window",
+		"-n",
+		target.ref,
+		"-c",
+		target.cwd,
+		buildInnerCommand(target)
+	]);
+}
+/**
+* iTerm2 needs its own dialect (Terminal.app's `do script` isn't understood
+* by it) — detected through TERM_PROGRAM rather than "is it running", because
+* a user who has iTerm2 installed but is currently in Terminal.app wants a
+* Terminal.app tab, not a background iTerm2 window they won't notice.
+*/
+function spawnOnDarwin(target) {
+	const inner = escapeAppleScript(buildInnerCommand(target));
+	return fireAndForget("osascript", ["-e", process.env.TERM_PROGRAM === "iTerm.app" ? `tell application "iTerm2"
+  activate
+  try
+    tell current window to create tab with default profile
+  on error
+    create window with default profile
+  end try
+  tell current window to tell current tab to tell current session to write text "${inner}"
+end tell` : `tell application "Terminal" to do script "${inner}"`]);
+}
+function spawnOnWindows(target) {
+	const inner = buildInnerCommand(target).replace(/"/g, "\\\"");
+	return fireAndForget("wt", [
+		"-w",
+		"0",
+		"nt",
+		"-d",
+		target.cwd,
+		"powershell",
+		"-NoExit",
+		"-Command",
+		inner
+	]);
+}
+/**
+* `x-terminal-emulator` is the Debian/Ubuntu alternatives symlink to
+* whichever terminal the user has set as default — the closest thing Linux
+* has to a single common denominator. Anything else degrades to the plain
+* command list the caller already prints.
+*/
+function spawnOnLinux(target) {
+	return fireAndForget("x-terminal-emulator", [
+		"-e",
+		"bash",
+		"-c",
+		`${buildInnerCommand(target)}; exec bash`
+	]);
+}
+function spawnTerminal(target) {
+	if (process.env.TMUX) return spawnViaTmux(target);
+	if (process.platform === "darwin") return spawnOnDarwin(target);
+	if (process.platform === "win32") return spawnOnWindows(target);
+	return spawnOnLinux(target);
+}
+//#endregion
 //#region src/commands/start.ts
 const TOOLS = /* @__PURE__ */ new Set([
 	"claude-code",
@@ -1141,6 +1378,78 @@ const TOOLS = /* @__PURE__ */ new Set([
 	"cursor",
 	"other"
 ]);
+/**
+* Explicit and comma-separated, not scraped from stdin like a single ref
+* would be: a ticket's own description can easily mention other refs
+* ("see NS-12"), and those must never trigger opening terminals for them.
+*/
+function parseTicketsFlag(raw) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const token of raw.split(",")) {
+		const trimmed = token.trim();
+		if (!trimmed) continue;
+		const [ref] = extractTicketRefs(trimmed);
+		if (!ref || ref !== trimmed.toUpperCase()) fail(`"${trimmed}" is not a ticket reference.`, "Expected something like EWWQ-1.");
+		seen.add(ref);
+	}
+	if (seen.size === 0) fail("No ticket references found in --tickets.", "Expected something like NS-1,NS-2.");
+	return [...seen];
+}
+async function resolveRefs(flags, positional) {
+	const raw = flags.get("tickets");
+	if (raw) return parseTicketsFlag(raw);
+	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. 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(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) {
+		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];
 	if (explicit) {
@@ -1162,6 +1471,8 @@ function detectTool() {
 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(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(", ")}.`);
@@ -1235,6 +1546,8 @@ ${bold("Usage")}
   npx neuvikon login              Sign in through the browser
   npx neuvikon init               Teach this project's coding agents to report work
   npx neuvikon start --ticket EWWQ-1
+  npx neuvikon start --tickets EWWQ-1,EWWQ-2 --spawn
+                                   Open one terminal per ticket instead of tracking one here
   npx neuvikon stop
   npx neuvikon status             Show login, project setup and current ticket
   npx neuvikon logout
@@ -1256,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.16",
+  "version": "0.2.18",
   "description": "Tell Neuvikon which ticket your coding agent is working on.",
   "keywords": [
     "neuvikon",