kanbo-cli 0.1.0 → 0.1.2

package/README.md

@@ -14,6 +14,7 @@
 - **Status lines and runs.** Every card says what it is doing right now, and every launch of a card is recorded as a run with an attempt number.
 - **Subtasks, comments, pull request links, sprints** and **column entry rules** (`checklist_complete`, `pull_request_linked`, `ci_green`, `approved`).
 - **Storage you choose.** A board file in the project (`.kanbo/board.db`), or an external Postgres database such as Supabase shared by a team, with `kanban_person` / `kanban_agent` roles.
+- **MCP alone is enough to start.** `kanbo mcp` sends the board's basic rules as MCP server instructions when a client connects, so an agent needs no instruction file for the basics.
 - **One-command project setup.** `kanbo init` binds the project, writes an instruction block into `CLAUDE.md` or `AGENTS.md`, and registers the MCP server with Claude Code, Codex or Cursor.
 - **Board over HTTP.** `kanbo serve` answers a JSON API and serves a board page on `http://127.0.0.1:4318`, loopback-only and token-guarded.
 - **Machine-readable capabilities.** `kanbo capabilities --json` describes every tool, command, rule and limit for an orchestrator to read.
@@ -34,8 +35,7 @@ This creates `.kanbo/board.db`, binds the project to it in `.kanbo/binding.json`
 ```bash
 kanbo card create --column to_do --title "Add rate limiting" --description "60 requests per minute per client"
 kanbo ready
-export KANBO_SERVE_TOKEN="$(openssl rand -hex 16)"
-kanbo serve                     # open http://127.0.0.1:4318 and paste the token into the Token field
+kanbo serve                     # opens the board in your browser
 ```
 
 Now start your agent in the project. It reads the instruction block, runs `kanbo prime`, takes a card from `kanbo ready`, and works it. When it runs `kanbo card wait-approval`, you answer with `kanbo approve <card>` or `kanbo return <card> --comment "..."` — or with the buttons on the board page.

package/dist/cli.cjs

@@ -3083,7 +3083,7 @@ var import_picocolors = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin((
 * `package.version`. A build carries it as a literal; running from source
 * (tests, `tsx`) reads the package's own `package.json` instead.
 */
-const KANBO_PACKAGE_VERSION = "0.1.0";
+const KANBO_PACKAGE_VERSION = "0.1.2";
 /**
 * Every exit code this tool promises, and what it means — the capabilities
 * manifest's `exitCodes` reads this rather than naming the codes again. `0` and
@@ -11178,32 +11178,61 @@ async function migrateCards(store, input) {
 	};
 }
 //#endregion
-//#region src/ops/prime.ts
+//#region src/ops/agent-rules.ts
 /**
-* The rules of this board, as an agent needs to hear them.
+* The sentences that tell an agent how to work this board, written once.
+*
+* Four surfaces say them: the text `kanbo prime` returns (`BOARD_RULES`), the
+* block `kanbo init` writes into a project's `CLAUDE.md` / `AGENTS.md`, the
+* `instructions` the `kanbo mcp` server sends when a client connects, and the
+* `kanbo_card_create` tool's description. Each surface adds its own way of
+* doing the thing — a command, a tool name — but the rule itself is read from
+* here, so the four cannot come to say different things.
+*
+* No sentence names a tool or a command: the same text reaches an agent holding
+* MCP tools, one with a command line, and one talking to a server over HTTP.
+*/
+const MOVE_CARD_RULE = "You move the card between columns yourself, at the moment its real state changes. The board never moves a card for you.";
+const STATUS_LINE_RULE = "Write a status line at every step, including before and after anything long-running. One sentence, present tense, about what is happening right now.";
+const WAIT_FOR_PERSON_RULE = "When you need a person, mark the card as waiting for approval and end your turn. You will be told when the answer comes.";
+const PERSON_ONLY_RULE = "Only a person approves a card, and only a person takes one out of waiting. Never do either yourself.";
+const EXECUTION_MODE_RULE = "Each card says where it runs: `worktree` means a separate copy of the project, `main` means the project folder itself. Work in the mode the card names.";
+/** When to split a card at all — said on its own where the surface names the parent its own way. */
+const SUBTASK_WHEN_SENTENCE = "Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go.";
+/** How to split one, with the way this surface names the parent card. */
+function subtaskSplitSentence(parentReference) {
+	return `When you do split a card, make the parts subtasks of it (${parentReference}), not separate top-level cards.`;
+}
+const SUBTASK_RULE = `${SUBTASK_WHEN_SENTENCE} ${subtaskSplitSentence("the parent card's id")}`;
+const PULL_REQUEST_RULE = "Opened a pull request? Link it to the card. Its state and CI checks then reach the card as comments on their own — nothing else tells the board a pull request exists.";
+const OWN_SESSION_RULE = "Started the work yourself, not launched by an app that tracks the run for you? Say so when you start the run — `claude:<session id>` from Claude Code, `codex:<session id>` from Codex (the session id Codex prints) — so your own log of it can be found later.";
+/** Said by the `kanbo init` block and the MCP instructions, which name the comment command or tool beside it. */
+const COMMENT_RULE = "Findings, results, decisions and questions go on the card as comments.";
+/**
+* The rules of this board, as `kanbo prime` says them under its column list.
 *
 * They are about the board and nothing else. The board does not hand out a role, a
 * method or a pipeline — that belongs to the instructions the person wrote for
 * their own agent — so the list stops at what the board itself guarantees and
-* expects. No tool is named either: the same text reaches an agent holding MCP
-* tools, one with a command line, and one talking to a server over HTTP, and each
-* of them already knows what it is holding.
+* expects.
 *
-* Exported because it is also the source `buildCapabilitiesManifest` reads its
-* `rules` from — one list, read by the prompt an agent sees and by the manifest
-* an orchestrator reads about the board.
+* Also the source `buildCapabilitiesManifest` reads its `rules` from — one list,
+* read by the prompt an agent sees and by the manifest an orchestrator reads
+* about the board.
 */
 const BOARD_RULES = [
-	"You move the card between columns yourself, at the moment its real state changes. The board never moves a card for you.",
-	"Write a status line at every step, including before and after anything long-running. One sentence, present tense, about what is happening right now.",
-	"When you need a person, mark the card as waiting for approval and end your turn. You will be told when the answer comes.",
-	"Only a person approves a card, and only a person takes one out of waiting. Never do either yourself.",
-	"Each card says where it runs: `worktree` means a separate copy of the project, `main` means the project folder itself. Work in the mode the card names.",
-	"Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go. When you do split a card, make the parts subtasks of it (the parent card's id), not separate top-level cards.",
-	"Opened a pull request? Link it to the card. Its state and CI checks then reach the card as comments on their own — nothing else tells the board a pull request exists.",
-	"Started the work yourself, not launched by an app that tracks the run for you? Say so when you start the run — `claude:<session id>` from Claude Code, `codex:<session id>` from Codex (the session id Codex prints) — so your own log of it can be found later.",
+	MOVE_CARD_RULE,
+	STATUS_LINE_RULE,
+	WAIT_FOR_PERSON_RULE,
+	PERSON_ONLY_RULE,
+	EXECUTION_MODE_RULE,
+	SUBTASK_RULE,
+	PULL_REQUEST_RULE,
+	OWN_SESSION_RULE,
 	"Read the column descriptions above before moving a card, and do all of this through the board tools or commands you have — a statement in your reply changes nothing."
 ];
+//#endregion
+//#region src/ops/prime.ts
 /**
 * What the board tells an agent about itself: the columns it has, what each one
 * means, and how a card is expected to travel across them.
@@ -22777,6 +22806,33 @@ function readCardNumber(session, reference) {
 	return reference.slice(0, separator).toUpperCase() === prefix ? Number(digits) : null;
 }
 //#endregion
+//#region src/domain/card-display-title.ts
+/**
+* What a card is called wherever a person or an agent reads it by name.
+*
+* A card written as a description alone is titled with its own key (every
+* writer does that). Named by its key, such a card says nothing — so its name
+* is the first line of its description instead. A browser bundle that does not
+* load this package keeps the same rule on its own, tested with the same
+* examples.
+*/
+/** How long a description line may run before it is cut with an ellipsis. */
+const DESCRIPTION_LINE_LIMIT = 120;
+function cardDisplayTitle(card) {
+	if (card.title !== card.id) return card.title;
+	return descriptionFirstLine(card.description) ?? card.title;
+}
+function descriptionFirstLine(description) {
+	for (const rawLine of (description ?? "").split("\n")) {
+		const line = stripMarkdown(rawLine);
+		if (line) return line.length > DESCRIPTION_LINE_LIMIT ? `${line.slice(0, 119).trimEnd()}…` : line;
+	}
+	return null;
+}
+function stripMarkdown(line) {
+	return line.replace(/^\s*(?:>\s*)+/, "").replace(/^\s*#{1,6}\s+/, "").replace(/^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ x]\]\s+)?/i, "").replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<[^>]+>/g, "").replace(/[*_~`]/g, "").replace(/\s+/g, " ").trim();
+}
+//#endregion
 //#region src/cli/view.ts
 /** Every field `kanbo card list|get --json` may ask for, in listing order. */
 const CARD_VIEW_FIELDS = [
@@ -22893,16 +22949,16 @@ function projectRun(run) {
 		launchedByKind: run.launchedByKind
 	};
 }
-/** One card per line: the key, the column it is in, and what it is called. */
+/** One card per line: the key, the column it is in, and what it is called (`cardDisplayTitle`). */
 function describeCards(cards) {
 	if (cards.length === 0) return "No cards";
 	const keyWidth = Math.max(...cards.map((card) => card.id.length));
 	const columnWidth = Math.max(...cards.map((card) => (card.column ?? "—").length));
-	return cards.map((card) => `${card.id.padEnd(keyWidth)}  ${(card.column ?? "—").padEnd(columnWidth)}  ${card.title}`).join("\n");
+	return cards.map((card) => `${card.id.padEnd(keyWidth)}  ${(card.column ?? "—").padEnd(columnWidth)}  ${cardDisplayTitle(card)}`).join("\n");
 }
 /** The whole card, for a person who asked about exactly one. */
 function describeCard(card) {
-	const lines = [`${card.id}  ${card.column ?? "—"}  ${card.executionMode}`, card.title];
+	const lines = [`${card.id}  ${card.column ?? "—"}  ${card.executionMode}`, cardDisplayTitle(card)];
 	if (card.description) lines.push("", card.description);
 	const facts = [
 		card.statusLine ? `status line: ${card.statusLine}` : null,
@@ -23090,7 +23146,7 @@ const SUBTASK_SENTENCE = "To create a subtask (sub-card) under another card, pas
 const cardCreateTool = defineKanboTool({
 	name: "kanbo_card_create",
 	title: "Create a card",
-	description: `Put a new card on this board. ${SUBTASK_SENTENCE} Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go. When you do split a card, make the parts subtasks of it (pass \`parent\`), not separate top-level cards.`,
+	description: `Put a new card on this board. ${SUBTASK_SENTENCE} ${SUBTASK_WHEN_SENTENCE} ${subtaskSplitSentence("pass `parent`")}`,
 	inputSchema: {
 		title: string().optional().describe("What the card is called. Leave it out and the card is titled with its own key; the description then says what the task is."),
 		description: string().optional().describe("What the card is about, spelled out for whoever picks it up."),
@@ -24154,7 +24210,8 @@ const CODEX_TABLE_PATTERN = new RegExp(String.raw`^\s*\[\s*mcp_servers\s*\.\s*(?
 *
 * It says what to run and when, and nothing about how to do the work: the
 * method is the person's own instructions to their agent, and the board only
-* insists on the part that keeps the card honest.
+* insists on the part that keeps the card honest. The rules are the sentences
+* `ops/agent-rules.ts` holds for every surface, with the command beside each.
 */
 const INSTRUCTION_BLOCK = [
 	INSTRUCTION_START,
@@ -24163,12 +24220,13 @@ const INSTRUCTION_BLOCK = [
 	"Work on this project is tracked on a kanbo board. Before starting a task run `kanbo prime` — it prints the board's columns and what each one means.",
 	"",
 	"- Take a card from `kanbo ready`.",
-	"- Move the card yourself (`kanbo card move <id> <column>`) — a card in the wrong column is a lie.",
-	"- Write a status line at every step (`kanbo card status-line <id> --text \"...\"`).",
-	"- Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go. When you do split a card, make the parts subtasks of it (the parent card's id), not separate top-level cards. (`kanbo card create --description \"...\" --parent <id>`).",
-	"- Findings, decisions and questions go on the card (`kanbo card comment <id> --content \"...\"`).",
-	"- When you need a person, run `kanbo card wait-approval <id>` and end your turn. Never approve your own work, and never take a card out of a column where it is waiting for a person.",
-	"- Started the work yourself, not launched by an app that tracks the run? Pass your own session to `kanbo run start --session` — `claude:<session id>` from Claude Code, `codex:<session id>` from Codex (the session id Codex prints).",
+	`- ${MOVE_CARD_RULE} (\`kanbo card move <id> <column>\`)`,
+	`- ${STATUS_LINE_RULE} (\`kanbo card status-line <id> --text "..."\`)`,
+	`- ${SUBTASK_RULE} (\`kanbo card create --description "..." --parent <id>\`)`,
+	`- ${COMMENT_RULE} (\`kanbo card comment <id> --content "..."\`)`,
+	`- ${WAIT_FOR_PERSON_RULE} (\`kanbo card wait-approval <id>\`)`,
+	`- ${PERSON_ONLY_RULE}`,
+	`- ${OWN_SESSION_RULE} (\`kanbo run start <id> --agent <name> --session <ref>\`)`,
 	"- Run `kanbo capabilities` for the full list of tools, commands and rules.",
 	INSTRUCTION_END
 ].join("\n");
@@ -40692,6 +40750,36 @@ function registerKanboCapabilitiesResources(server) {
 	}] }));
 }
 //#endregion
+//#region src/mcp/instructions.ts
+/** A tool name as the instructions print it — typed, so a renamed tool fails the build here. */
+function tool(name) {
+	return `\`${name}\``;
+}
+/**
+* What `kanbo mcp` tells a client when it connects — the `instructions` of the
+* MCP initialize result, which a client hands its model before any tool is
+* called. An agent with nothing but this server connected learns from it how
+* to work the board, with no instruction file in the project.
+*
+* Static on purpose: it is sent before any board is resolved, so it says
+* nothing about columns — `kanbo_prime` returns those. The rules are the
+* sentences `ops/agent-rules.ts` holds for every surface, with the tool beside
+* each; the full manifest stays a resource.
+*/
+const KANBO_MCP_INSTRUCTIONS = [
+	"kanbo is a kanban board shared by people and agents; these tools read and change its cards.",
+	"",
+	`- At the start of a session call ${tool("kanbo_prime")} — it returns this board's columns and what each one means.`,
+	`- Take work from ${tool("kanbo_ready")}.`,
+	`- ${MOVE_CARD_RULE} (${tool("kanbo_card_move")})`,
+	`- ${STATUS_LINE_RULE} (${tool("kanbo_status_line")})`,
+	`- ${COMMENT_RULE} (${tool("kanbo_card_comment")})`,
+	`- ${SUBTASK_RULE} (${tool("kanbo_card_create")} with \`parent\`)`,
+	`- ${WAIT_FOR_PERSON_RULE} (${tool("kanbo_wait_approval")})`,
+	`- ${PERSON_ONLY_RULE}`,
+	`- Every tool, rule and canonical string: the resource \`${KANBO_CAPABILITIES_MARKDOWN_RESOURCE_URI}\`.`
+].join("\n");
+//#endregion
 //#region src/mcp/server.ts
 /** The name a client sees this server under. */
 const KANBO_MCP_SERVER_NAME = "kanbo";
@@ -40718,12 +40806,15 @@ function registerKanboTools(server, transport, options) {
 * function: it documents its capabilities its own way, and adding a second
 * `kanbo://` resource namespace to an inventory that is not only the board's
 * is a decision for that server to make, not this one.
+*
+* For the same reason it alone sends `KANBO_MCP_INSTRUCTIONS` in the initialize
+* result: the instructions of a server that is only the board.
 */
 function createKanboMcpServer(transport, options) {
 	const server = new McpServer({
 		name: KANBO_MCP_SERVER_NAME,
 		version: KANBO_MCP_SERVER_VERSION
-	});
+	}, { instructions: KANBO_MCP_INSTRUCTIONS });
 	registerKanboTools(server, transport, options);
 	registerKanboCapabilitiesResources(server);
 	return server;
@@ -42512,12 +42603,11 @@ async function startKanboServer(options) {
 }
 /**
 * Who may act for a person on this server, said once when it starts: only a
-* request presenting the token does, and a server with no token, or started
-* from an agent's shell, has nobody who may.
+* request presenting the token does, and a server started from an agent's
+* shell has nobody who may.
 */
-function describePersonRights(actors, token) {
+function describePersonRights(actors) {
 	if (!actors.person) return "no request acts for a person (started from an agent's shell)";
-	if (!token) return "no request acts for a person (no token; set KANBO_SERVE_TOKEN to allow it)";
 	return `a request with the token acts for ${actors.person.id}`;
 }
 function stripBrackets(host) {
@@ -42699,12 +42789,58 @@ function sendJson(response, status, value) {
 	response.end(body);
 }
 //#endregion
+//#region src/serve/access.ts
+/** The token given, or one made up for a loopback server; refused off loopback without one. */
+function resolveServeAccess(host, givenToken) {
+	assertServeBinding(host, givenToken);
+	if (givenToken) return {
+		token: givenToken,
+		generated: false
+	};
+	return {
+		token: (0, node_crypto.randomBytes)(24).toString("base64url"),
+		generated: true
+	};
+}
+/**
+* Hand the person the board page: a link printed once, and opened in the
+* browser unless they said not to. A generated token rides in the link's
+* fragment; one they gave is theirs already and is left out.
+*/
+function presentServePage(presentation, output) {
+	const { url, access, open } = presentation;
+	if (presentation.agentShell || !presentation.terminal) {
+		if (access.generated) output.print("kanbo serve: a token was generated for this run and is not shown here; set KANBO_SERVE_TOKEN to choose your own");
+		return;
+	}
+	const link = access.generated ? `${url}/#token=${access.token}` : `${url}/`;
+	output.print(`kanbo serve: board page ${link}`);
+	if (open) output.openInBrowser(link);
+}
+/** Open a link in the default browser, without waiting for it and without failing when there is none. */
+function openInBrowser(url) {
+	const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", [
+		"/c",
+		"start",
+		"\"\"",
+		url
+	]] : ["xdg-open", [url]];
+	try {
+		const child = (0, node_child_process.spawn)(command, args, {
+			detached: true,
+			stdio: "ignore",
+			windowsVerbatimArguments: process.platform === "win32"
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+//#endregion
 //#region src/cli/commands/serve.ts
 function registerServeCommand(program) {
-	program.command("serve").description("serve this board over HTTP, with a board page for the browser").option("--port <port>", "port to listen on", String(DEFAULT_SERVE_PORT)).option("--host <host>", "address to bind; anything but loopback needs a token", DEFAULT_SERVE_HOST).option("--db <path>", "board database file to open").option("--database-url <url>", "external Postgres board to serve instead of a board file").option("--workspace <nameOrId>", "workspace the server is about").option("--token <token>", "bearer token every request must carry (or set KANBO_SERVE_TOKEN)").option("--cors-origin <origin>", "let a browser call from this exact origin; repeat for more", collect, []).action(async (options) => {
+	program.command("serve").description("serve this board over HTTP, with a board page for the browser").option("--port <port>", "port to listen on", String(DEFAULT_SERVE_PORT)).option("--host <host>", "address to bind; anything but loopback needs a token", DEFAULT_SERVE_HOST).option("--db <path>", "board database file to open").option("--database-url <url>", "external Postgres board to serve instead of a board file").option("--workspace <nameOrId>", "workspace the server is about").option("--token <token>", "bearer token every request must carry (or set KANBO_SERVE_TOKEN); made up for the run on loopback when absent").option("--cors-origin <origin>", "let a browser call from this exact origin; repeat for more", collect, []).option("--no-open", "print the board page link without opening it in the browser").action(async (options) => {
 		const port = parsePort(options.port);
-		const token = options.token?.trim() || process.env.KANBO_SERVE_TOKEN?.trim() || null;
-		assertServeBinding(options.host, token);
+		const access = resolveServeAccess(options.host, options.token?.trim() || process.env.KANBO_SERVE_TOKEN?.trim() || null);
 		const session = await openBoardSession({
 			db: options.db,
 			databaseUrl: options.databaseUrl,
@@ -42722,15 +42858,25 @@ function registerServeCommand(program) {
 				actors,
 				host: options.host,
 				port,
-				token,
+				token: access.token,
 				corsOrigins: options.corsOrigin
 			});
 		} catch (error) {
 			await session.close();
 			throw error;
 		}
-		console.error(`kanbo serve: ${server.url} — workspace ${session.workspace.id}${token ? ", bearer token required" : ""}`);
-		console.error(`kanbo serve: ${describePersonRights(actors, token)}`);
+		console.error(`kanbo serve: ${server.url} — workspace ${session.workspace.id}, bearer token required${access.generated ? " (generated for this run)" : ""}`);
+		console.error(`kanbo serve: ${describePersonRights(actors)}`);
+		presentServePage({
+			url: server.url,
+			access,
+			agentShell,
+			terminal: process.stdout.isTTY === true,
+			open: options.open
+		}, {
+			print: (line) => console.log(line),
+			openInBrowser
+		});
 		let stopping = false;
 		const stop = async () => {
 			if (stopping) return;