neuvikon 0.2.13 → 0.2.15

package/README.md

@@ -39,6 +39,8 @@ as being worked on, by whom, with which tool.
 | `neuvikon stop` | Stop tracking |
 | `neuvikon status` | Login, project setup, current ticket |
 | `neuvikon logout` | Revoke this machine's token and forget it |
+| `neuvikon pages [--ticket EWWQ-1]` | List the ticket's project pages, flattened to plain text |
+| `neuvikon pages update "Title" [--ticket EWWQ-1]` | Create or update a page by title, body on stdin (or `--text`) |
 
 `start` also accepts the ticket on stdin, and pulls the reference out of it:
 
@@ -46,6 +48,32 @@ as being worked on, by whom, with which tool.
 pbpaste | npx neuvikon start
 ```
 
+## Project pages
+
+An agent's most useful output often isn't the ticket, it's what it learned
+doing it. `pages` reads and writes the same project pages a person sees in the
+app — the running knowledge base for that project, not a per-ticket scratchpad:
+
+```sh
+npx neuvikon pages --ticket EWWQ-1
+```
+
+```sh
+npx neuvikon pages update "Auth flow" --ticket EWWQ-1 <<'EOF'
+Sessions are issued by convex/auth.ts and expire after 30 days.
+See [[Session storage]] for where they're persisted.
+EOF
+```
+
+An update matches an existing page by title (case-insensitive) and overwrites
+it, so writing to the same title again refines that page instead of piling up
+duplicates. `[[Another Title]]` inside the text becomes a real link to that
+page if a page with that title already exists in the project, same as typing
+it in the editor.
+
+Both commands fall back to whichever ticket `npx neuvikon start` is already
+tracking in this directory when `--ticket` is omitted.
+
 ## Token usage
 
 `start`/`stop` are all an agent can report about itself — no agent knows its own
@@ -97,4 +125,3 @@ pnpm typecheck
 ```
 
 No runtime dependencies, so `npx neuvikon` stays a fast cold start.
-# neuvikon-cli

package/dist/index.mjs

@@ -3,6 +3,49 @@ import { chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readF
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { spawn } from "node:child_process";
+//#region src/api.ts
+var ApiError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.status = status;
+		this.name = "ApiError";
+	}
+};
+/** A request that never reached the server: offline, DNS, TLS, timeout. */
+var NetworkError = class extends Error {
+	constructor(cause) {
+		super("Could not reach Neuvikon", { cause });
+		this.name = "NetworkError";
+	}
+};
+const TIMEOUT_MS = 15e3;
+/**
+* The one place an HTTP failure becomes a typed error. Callers decide what a
+* failure means — a hook wrapping the agent's turn wants to swallow it, `login`
+* wants to shout about it.
+*/
+async function post(url, path, body) {
+	let response;
+	try {
+		response = await fetch(`${url}${path}`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new NetworkError(error);
+	}
+	const payload = await response.json().catch(() => ({}));
+	const error = typeof payload === "object" && payload !== null ? payload.error : void 0;
+	if (!response.ok) throw new ApiError(typeof error === "string" ? error : `Request failed with status ${response.status}`, response.status);
+	return payload;
+}
+function normalizeUrl(url) {
+	return url.trim().replace(/\/+$/, "");
+}
+//#endregion
 //#region src/config.ts
 /**
 * The two deployments this CLI knows about. The browser origin is kept here
@@ -93,49 +136,6 @@ function clearCredentials() {
 	}
 }
 //#endregion
-//#region src/api.ts
-var ApiError = class extends Error {
-	status;
-	constructor(message, status) {
-		super(message);
-		this.status = status;
-		this.name = "ApiError";
-	}
-};
-/** A request that never reached the server: offline, DNS, TLS, timeout. */
-var NetworkError = class extends Error {
-	constructor(cause) {
-		super("Could not reach Neuvikon", { cause });
-		this.name = "NetworkError";
-	}
-};
-const TIMEOUT_MS = 15e3;
-/**
-* The one place an HTTP failure becomes a typed error. Callers decide what a
-* failure means — a hook wrapping the agent's turn wants to swallow it, `login`
-* wants to shout about it.
-*/
-async function post(url, path, body) {
-	let response;
-	try {
-		response = await fetch(`${url}${path}`, {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify(body),
-			signal: AbortSignal.timeout(TIMEOUT_MS)
-		});
-	} catch (error) {
-		throw new NetworkError(error);
-	}
-	const payload = await response.json().catch(() => ({}));
-	const error = typeof payload === "object" && payload !== null ? payload.error : void 0;
-	if (!response.ok) throw new ApiError(typeof error === "string" ? error : `Request failed with status ${response.status}`, response.status);
-	return payload;
-}
-function normalizeUrl(url) {
-	return url.trim().replace(/\/+$/, "");
-}
-//#endregion
 //#region src/session.ts
 /**
 * Distinguishes concurrent agents working in the *same* checkout — two Claude
@@ -184,6 +184,74 @@ function clearSession() {
 	} catch {}
 }
 //#endregion
+//#region src/ui.ts
+/**
+* Output helpers. Everything the agent shouldn't parse goes to stderr, so a
+* command's stdout stays a clean, pipeable value.
+*/
+const useColor = process.env.NO_COLOR === void 0 && process.stderr.isTTY === true;
+function paint(code, text) {
+	return useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+const dim = (text) => paint("2", text);
+const bold = (text) => paint("1", text);
+const green = (text) => paint("32", text);
+const red = (text) => paint("31", text);
+const cyan = (text) => paint("36", text);
+function info(message) {
+	process.stderr.write(`${message}\n`);
+}
+function success(message) {
+	process.stderr.write(`${green("✓")} ${message}\n`);
+}
+function warn(message) {
+	process.stderr.write(`${red("!")} ${message}\n`);
+}
+/** Ends the process. Every user-facing failure funnels through here. */
+function fail(message, hint) {
+	process.stderr.write(`${red("✗")} ${message}\n`);
+	if (hint) process.stderr.write(`  ${dim(hint)}\n`);
+	process.exit(1);
+}
+//#endregion
+//#region src/commands/board.ts
+function requireCredentials$3() {
+	const credentials = readCredentials();
+	if (!credentials) fail("Not logged in.", "Run `npx neuvikon login` first.");
+	return credentials;
+}
+function resolveTicketRef$3(flags) {
+	const ref = flags.get("ticket") ?? readSession()?.ticket;
+	if (!ref) fail("No ticket to look up a board for.", "Pass --ticket EWWQ-1, or run this where `npx neuvikon start` is already tracking one.");
+	return ref;
+}
+/**
+* Shows an agent the real shape of this project's board before it guesses at
+* a column name — boards vary per project, and some have no "done" at all.
+*/
+async function board(flags) {
+	const credentials = requireCredentials$3();
+	const ticketRef = resolveTicketRef$3(flags);
+	let result;
+	try {
+		result = await post(credentials.url, "/api/agent/board", {
+			token: credentials.token,
+			ticketRef
+		});
+	} catch (error) {
+		if (error instanceof NetworkError) fail("Could not reach Neuvikon.");
+		if (error instanceof ApiError) {
+			if (error.status === 401) fail(error.message, "Run `npx neuvikon login` again.");
+			fail(error.message);
+		}
+		throw error;
+	}
+	info(`${ticketRef} is on ${bold(result.currentColumn || "(no column)")}`);
+	info(dim("Columns, in board order:"));
+	for (const column of result.columns) info(`  - ${column.name}${column.isDone ? dim(" (terminal)") : ""}`);
+	if (!result.columns.some((column) => column.isDone)) info(dim("No column is marked terminal on this board — use your judgment on what counts as done."));
+}
+//#endregion
 //#region src/ticket.ts
 /**
 * Ticket refs look like `AWKN-14`. This pattern is deliberately looser than the
@@ -209,6 +277,40 @@ async function readStdin() {
 	return Buffer.concat(chunks).toString("utf8");
 }
 //#endregion
+//#region src/commands/comment.ts
+function requireCredentials$2() {
+	const credentials = readCredentials();
+	if (!credentials) fail("Not logged in.", "Run `npx neuvikon login` first.");
+	return credentials;
+}
+function resolveTicketRef$2(flags) {
+	const ref = flags.get("ticket") ?? readSession()?.ticket;
+	if (!ref) fail("No ticket to comment on.", "Pass --ticket EWWQ-1, or run this where `npx neuvikon start` is already tracking one.");
+	return ref;
+}
+/** A note on a ticket that doesn't move it — e.g. explaining a handoff mid-ticket. */
+async function comment(flags) {
+	const credentials = requireCredentials$2();
+	const ticketRef = resolveTicketRef$2(flags);
+	const text = (flags.get("text") || await readStdin()).trim();
+	if (!text) fail("No comment text given.", "Pipe the comment in on stdin, or pass --text.");
+	try {
+		await post(credentials.url, "/api/agent/comment", {
+			token: credentials.token,
+			ticketRef,
+			comment: text
+		});
+	} catch (error) {
+		if (error instanceof NetworkError) fail("Could not reach Neuvikon.");
+		if (error instanceof ApiError) {
+			if (error.status === 401) fail(error.message, "Run `npx neuvikon login` again.");
+			fail(error.message);
+		}
+		throw error;
+	}
+	success(`Commented on ${ticketRef}`);
+}
+//#endregion
 //#region src/usage.ts
 /**
 * Sums token usage out of a JSONL agent transcript, starting from `offset`.
@@ -336,36 +438,6 @@ function claudeTranscriptPath() {
 	}
 }
 //#endregion
-//#region src/ui.ts
-/**
-* Output helpers. Everything the agent shouldn't parse goes to stderr, so a
-* command's stdout stays a clean, pipeable value.
-*/
-const useColor = process.env.NO_COLOR === void 0 && process.stderr.isTTY === true;
-function paint(code, text) {
-	return useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
-}
-const dim = (text) => paint("2", text);
-const bold = (text) => paint("1", text);
-const green = (text) => paint("32", text);
-const red = (text) => paint("31", text);
-const cyan = (text) => paint("36", text);
-function info(message) {
-	process.stderr.write(`${message}\n`);
-}
-function success(message) {
-	process.stderr.write(`${green("✓")} ${message}\n`);
-}
-function warn(message) {
-	process.stderr.write(`${red("!")} ${message}\n`);
-}
-/** Ends the process. Every user-facing failure funnels through here. */
-function fail(message, hint) {
-	process.stderr.write(`${red("✗")} ${message}\n`);
-	if (hint) process.stderr.write(`  ${dim(hint)}\n`);
-	process.exit(1);
-}
-//#endregion
 //#region src/commands/report.ts
 /**
 * Agent hooks hand their context to the command on stdin as JSON. Reading the
@@ -640,12 +712,61 @@ When the user hands you a Neuvikon ticket — text beginning with a reference li
 
     npx neuvikon start --ticket EWWQ-1
 
-When you finish that ticket, or the user moves you to a different one, run:
+Before you start, and any time you need more context, read the ticket's
+project pages — this is the project's accumulated knowledge, not just this
+ticket's:
+
+    npx neuvikon pages --ticket EWWQ-1
+
+When you learn something worth keeping — how a system works, a decision and
+why, anything future work on this project would benefit from — write it back
+so the next agent or teammate has it:
+
+    npx neuvikon pages update "Some Title" --ticket EWWQ-1 <<'EOF'
+    What you learned.
+    EOF
+
+An update with a title that already exists overwrites that page instead of
+creating a duplicate, so reuse a title for anything you're extending.
+Reference another page by writing its title in double brackets, e.g.
+\`[[Auth Flow]]\` — it becomes a real link if that page already exists.
+
+Before you change the ticket's status, look at what columns this project's
+board actually has — they vary per project, and there may be no column
+literally called "Done":
+
+    npx neuvikon board --ticket EWWQ-1
+
+Then decide, based on what's actually true, not on finishing your turn:
+
+- The work is really done — merged to main, deployed, whatever "done" means
+  for this project — move it to that board's terminal column (the one
+  \`board\` marks as terminal), and say why:
+
+      npx neuvikon move --ticket EWWQ-1 --column "Done" --comment "Merged to main in #142"
+
+- The work needs a step before done — a PR is open, it's waiting on review,
+  it's blocked — move it to whichever real column matches that, with the
+  same reasoning:
+
+      npx neuvikon move --ticket EWWQ-1 --column "Code Review" --comment "PR up, waiting on review"
+
+- If the board has no column that fits, or you're just leaving a note without
+  changing where the ticket sits (e.g. handing off mid-ticket), comment
+  instead of moving:
+
+      npx neuvikon comment --ticket EWWQ-1 --text "Handing off — blocked on design"
+
+A ticket that isn't actually finished should never land on a terminal column
+just because you're done for now. When you finish that ticket, or the user
+moves you to a different one, also run:
 
     npx neuvikon stop
 
-This is bookkeeping that tells the user's team which ticket you are on. You do
-not need to narrate these commands, and if one fails, carry on with the actual
+\`stop\` only tells the team you're no longer working on it — it does not move
+the ticket, since stopping and finishing are not the same thing. This is
+bookkeeping that tells the user's team which ticket you are on. You do not
+need to narrate these commands, and if one fails, carry on with the actual
 work — never let it block you.`;
 function instructionBlock() {
 	return `${START_MARKER}\n${INSTRUCTION_BODY}\n${END_MARKER}`;
@@ -907,6 +1028,112 @@ async function logout() {
 	info(dim("  Could not reach Neuvikon to revoke the token — revoke it in settings if it leaked."));
 }
 //#endregion
+//#region src/commands/move.ts
+function requireCredentials$1() {
+	const credentials = readCredentials();
+	if (!credentials) fail("Not logged in.", "Run `npx neuvikon login` first.");
+	return credentials;
+}
+function resolveTicketRef$1(flags) {
+	const ref = flags.get("ticket") ?? readSession()?.ticket;
+	if (!ref) fail("No ticket to move.", "Pass --ticket EWWQ-1, or run this where `npx neuvikon start` is already tracking one.");
+	return ref;
+}
+/**
+* Explicit column change, e.g. `npx neuvikon move --column "Code Review" \
+* --comment "PR up, waiting on review"`. A comment is mandatory: this is the
+* command that lands a ticket on a done-like column, and it should never do
+* that silently.
+*/
+async function move(flags) {
+	const credentials = requireCredentials$1();
+	const ticketRef = resolveTicketRef$1(flags);
+	const column = flags.get("column");
+	if (!column) fail("A target column is required.", `Pass --column "Code Review" — run \`npx neuvikon board\` first if you're not sure what this project calls it.`);
+	const comment = (flags.get("comment") || await readStdin()).trim();
+	if (!comment) fail("A comment is required.", "Pass --comment \"why this ticket is moving\", e.g. \"Merged to main.\"");
+	let result;
+	try {
+		result = await post(credentials.url, "/api/agent/move", {
+			token: credentials.token,
+			ticketRef,
+			column,
+			comment
+		});
+	} catch (error) {
+		if (error instanceof NetworkError) fail("Could not reach Neuvikon.");
+		if (error instanceof ApiError) {
+			if (error.status === 401) fail(error.message, "Run `npx neuvikon login` again.");
+			fail(error.message);
+		}
+		throw error;
+	}
+	success(`Moved ${ticketRef} to ${bold(result.column)}`);
+}
+//#endregion
+//#region src/commands/pages.ts
+function requireCredentials() {
+	const credentials = readCredentials();
+	if (!credentials) fail("Not logged in.", "Run `npx neuvikon login` first.");
+	return credentials;
+}
+/** `--ticket` wins; otherwise fall back to whatever this directory is already tracking. */
+function resolveTicketRef(flags) {
+	const ref = flags.get("ticket") ?? readSession()?.ticket;
+	if (!ref) fail("No ticket to look up pages for.", "Pass --ticket EWWQ-1, or run this where `npx neuvikon start` is already tracking one.");
+	return ref;
+}
+/** Both pages subcommands fail the same two ways `start` does; shared so they say so identically. */
+async function request(credentials, path, body) {
+	try {
+		return await post(credentials.url, path, body);
+	} catch (error) {
+		if (error instanceof NetworkError) fail("Could not reach Neuvikon.");
+		if (error instanceof ApiError) {
+			if (error.status === 401) fail(error.message, "Run `npx neuvikon login` again.");
+			fail(error.message);
+		}
+		throw error;
+	}
+}
+async function list(flags) {
+	const credentials = requireCredentials();
+	const ticketRef = resolveTicketRef(flags);
+	const { pages } = await request(credentials, "/api/agent/pages", {
+		token: credentials.token,
+		ticketRef
+	});
+	if (pages.length === 0) {
+		info(dim(`No pages in ${ticketRef}'s project yet.`));
+		return;
+	}
+	const body = pages.map((page) => `# ${page.title}\n\n${page.text}`).join("\n\n---\n\n");
+	process.stdout.write(`${body}\n`);
+}
+async function update(flags, positional) {
+	const credentials = requireCredentials();
+	const ticketRef = resolveTicketRef(flags);
+	const title = flags.get("title") ?? positional[0];
+	if (!title) fail("A page title is required.", `Pass --title "Auth flow notes", or give it as the first argument.`);
+	const text = (flags.get("text") || await readStdin()).trim();
+	if (!text) fail("No page text given.", "Pipe the page's body in on stdin, or pass --text.");
+	success(`${(await request(credentials, "/api/agent/pages/upsert", {
+		token: credentials.token,
+		ticketRef,
+		title,
+		text
+	})).created ? "Created" : "Updated"} page ${bold(title)} in ${ticketRef}'s project`);
+}
+async function pages(flags, positional) {
+	const [subcommand, ...rest] = positional;
+	switch (subcommand) {
+		case void 0:
+		case "list": return list(flags);
+		case "update": return update(flags, rest);
+		default: fail(`Unknown "pages ${subcommand}".`, "Try `pages` or `pages update`.");
+	}
+}
+//#endregion
 //#region src/commands/start.ts
 const TOOLS = /* @__PURE__ */ new Set([
 	"claude-code",
@@ -1012,6 +1239,21 @@ ${bold("Usage")}
   npx neuvikon status             Show login, project setup and current ticket
   npx neuvikon logout
 
+${bold("Board")}
+  npx neuvikon board                        Show this project's columns and where the ticket sits
+  npx neuvikon move --column "Code Review" --comment "PR up, waiting on review"
+                                   Move the ticket to a specific column, with why
+  npx neuvikon comment --text "Handing off, blocked on design"
+                                   Leave a note without changing the column
+  All three accept --ticket EWWQ-1 instead of relying on a tracked session.
+
+${bold("Project pages")}
+  npx neuvikon pages                        List the current ticket's project pages
+  npx neuvikon pages update "Title" < notes.txt
+                                   Create or update a page by title
+  Reference another page with [[Its Title]], same as in the editor.
+  Both accept --ticket EWWQ-1 instead of relying on a tracked session.
+
 ${bold("Options")}
   --tool <name>                   claude-code | codex | cursor | other
   --transcript <path>             Read token usage from an agent transcript
@@ -1059,6 +1301,10 @@ async function main() {
 		case "report": return report(flags);
 		case "stop": return stop(flags);
 		case "status": return status();
+		case "pages": return pages(flags, positional);
+		case "board": return board(flags);
+		case "move": return move(flags);
+		case "comment": return comment(flags);
 		case void 0:
 		case "help":
 		case "--help":

package/package.json

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