@opsee/cli 0.11.9

package/src/init/mcp-config.ts

@@ -0,0 +1,77 @@
+/** Registers the Opsee MCP server in the two per-repo config files coding agents read, touching
+ * only the `opsee` entry so other servers listed there survive untouched. */
+import type { WritePlan } from "./managed.js";
+import { appendBlock, detectJsonIndent, parseJsonObject } from "./text.js";
+
+export const MCP_SERVER_KEY = "opsee";
+
+/** Claude Code: `.mcp.json` at the repo root, `{ "mcpServers": { name: {...} } }`. */
+export function mergeClaudeMcpJson(existing: string | null, url: string): WritePlan {
+  const entry = { type: "http", url };
+  let root: Record<string, unknown> = {};
+  if (existing !== null && existing.trim() !== "") {
+    const parsed = parseJsonObject(existing);
+    if ("reason" in parsed) return { action: "kept-invalid", reason: parsed.reason };
+    root = parsed.root;
+  }
+  const serversRaw = root.mcpServers;
+  if (serversRaw !== undefined && (!serversRaw || typeof serversRaw !== "object" || Array.isArray(serversRaw))) {
+    return { action: "kept-invalid", reason: "mcpServers is not an object" };
+  }
+  const servers = { ...((serversRaw as Record<string, unknown> | undefined) ?? {}) };
+  if (JSON.stringify(servers[MCP_SERVER_KEY]) === JSON.stringify(entry)) return { action: "unchanged" };
+  servers[MCP_SERVER_KEY] = entry;
+  const content = JSON.stringify({ ...root, mcpServers: servers }, null, existing === null ? "  " : detectJsonIndent(existing)) + "\n";
+  return { action: existing === null ? "create" : "update", content };
+}
+
+/** A TOML table header alone on its line: `[a.b]`, `[ a."b" ]`, `[[arr]]`, with an optional
+ * comment. A line that merely starts with `[`, such as a nested array `["a", "b"],`, is not one. */
+const HEADER_RE = /^\s*\[\[?\s*([^\]]*?)\s*\]\]?\s*(?:#.*)?$/;
+
+/** Normalises a header's dotted key so `mcp_servers."opsee"` and `mcp_servers . opsee` match. */
+function headerKey(line: string): string | null {
+  const match = HEADER_RE.exec(line);
+  if (!match) return null;
+  return match[1]
+    .split(".")
+    .map((part) => part.trim().replace(/^["']|["']$/g, ""))
+    .join(".");
+}
+
+const OPSEE_TABLE = `mcp_servers.${MCP_SERVER_KEY}`;
+
+function codexBlock(url: string): string {
+  return `[${OPSEE_TABLE}]\nurl = ${JSON.stringify(url)}\n`;
+}
+
+/** Codex: `.codex/config.toml`, one `[mcp_servers.<name>]` table per server. Handled textually
+ * rather than through a TOML round-trip so every other byte of the user's file is preserved: the
+ * table is the span from its header to the next header or end of file. An `opsee = { ... }`
+ * inline table under `[mcp_servers]` is the same server in a shape this merge does not rewrite,
+ * so it is reported and left alone. */
+export function mergeCodexConfigToml(existing: string | null, url: string): WritePlan {
+  const block = codexBlock(url);
+  if (existing === null) return { action: "create", content: block };
+  const lines = existing.split("\n");
+  let table: string | null = null;
+  for (const line of lines) {
+    const key = headerKey(line);
+    if (key !== null) table = key;
+    else if (table === "mcp_servers" && new RegExp(`^\\s*"?${MCP_SERVER_KEY}"?\\s*=`).test(line)) {
+      return { action: "kept-invalid", reason: `${MCP_SERVER_KEY} is an inline table under [mcp_servers]; move it to a [${OPSEE_TABLE}] table or delete it` };
+    }
+  }
+  const start = lines.findIndex((l) => headerKey(l) === OPSEE_TABLE);
+  if (start === -1) return { action: "update", content: appendBlock(existing, block) };
+  let end = start + 1;
+  while (end < lines.length && headerKey(lines[end]) === null) end++;
+  // Trailing blank lines belong to the separator, not the table.
+  while (end > start + 1 && lines[end - 1].trim() === "") end--;
+  const current = lines.slice(start, end).join("\n") + "\n";
+  if (current === block) return { action: "unchanged" };
+  const before = lines.slice(0, start).join("\n");
+  const after = lines.slice(end).join("\n");
+  const content = `${before}${before ? "\n" : ""}${block}${after ? `${after.startsWith("\n") ? "" : "\n"}${after}` : ""}`;
+  return { action: "update", content };
+}

package/src/init/paths.ts

@@ -0,0 +1,16 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The cli package root: the skills and the tracker-doc template ship inside it, next to src/. */
+export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+export const SKILLS_DIR = join(PACKAGE_ROOT, "skills");
+export const TRACKER_TEMPLATE_PATH = join(PACKAGE_ROOT, "templates", "issue-tracker.md");
+
+/** Where `opsee init` writes, relative to the repo root. */
+export const TRACKER_DOC_PATH = "docs/agents/issue-tracker.md";
+export const SKILL_TARGETS = [".claude/skills", ".agents/skills"] as const;
+export const CLAUDE_MCP_PATH = ".mcp.json";
+export const CODEX_CONFIG_PATH = ".codex/config.toml";
+
+/** The remote Opsee MCP server every agent config points at (OAuth on first use). */
+export const DEFAULT_MCP_URL = "https://mcp.api.opsee.ai/mcp";

package/src/init/pointer-block.ts

@@ -0,0 +1,45 @@
+/** The block `opsee init` adds to the repo's agent instructions so a session that reads
+ * AGENTS.md or CLAUDE.md knows the planning skills and the tracker doc exist. Bounded by begin
+ * and end markers so a re-run replaces it in place and never appends a second copy. */
+import type { WritePlan } from "./managed.js";
+import { appendBlock } from "./text.js";
+
+export const POINTER_BEGIN = "<!-- opsee:skills:begin -->";
+export const POINTER_END = "<!-- opsee:skills:end -->";
+
+export const INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"] as const;
+
+export function pointerBlock(trackerDocPath: string): string {
+  return [
+    POINTER_BEGIN,
+    "## Agent skills",
+    "",
+    "`opsee init` installs Opsee's planning skills (`/wayfinder`, `/to-spec`, `/to-issues`) into",
+    "`.claude/skills/` and `.agents/skills/`, and writes the tracker doc they read to",
+    `\`${trackerDocPath}\`. Opsee owns those files; edit them upstream and re-run \`opsee init\`,`,
+    "which updates what it wrote and leaves any file you changed alone.",
+    POINTER_END,
+    "",
+  ].join("\n");
+}
+
+/** Inserts or replaces the block in `existing` (null when the file does not exist yet). A begin
+ * marker with no end marker means someone cut the block in half; appending another would grow
+ * the file on every run, so the file is kept and the reason reported. */
+export function upsertPointerBlock(existing: string | null, block: string): WritePlan {
+  if (existing === null) return { action: "create", content: block };
+  const begin = existing.indexOf(POINTER_BEGIN);
+  const end = begin === -1 ? -1 : existing.indexOf(POINTER_END, begin);
+  if (begin === -1) return { action: "update", content: appendBlock(existing, block) };
+  if (end === -1) return { action: "kept-invalid", reason: `has ${POINTER_BEGIN} without ${POINTER_END}; restore the end marker or remove the block` };
+  const tail = existing.slice(end + POINTER_END.length).replace(/^\n/, "");
+  const content = `${existing.slice(0, begin)}${block}${tail}`;
+  return content === existing ? { action: "unchanged" } : { action: "update", content };
+}
+
+/** Which instruction file gets the block: an existing AGENTS.md wins over an existing CLAUDE.md;
+ * with neither, AGENTS.md is created (Codex and Cursor read it; Claude Code reads CLAUDE.md, which
+ * may @-include it). */
+export function pickInstructionFile(exists: (name: string) => boolean): string {
+  return INSTRUCTION_FILES.find(exists) ?? INSTRUCTION_FILES[0];
+}

package/src/init/project.ts

@@ -0,0 +1,22 @@
+export interface ProjectChoice {
+  id: number;
+  key: string;
+  name: string;
+}
+
+/** Which project the repo is set up for: `--project <key>` when given, the only one when there
+ * is one, else whatever `choose` answers (null when it had no terminal to ask on). The string
+ * result is the message to show when nothing was picked. */
+export async function pickProject(
+  projects: ProjectChoice[],
+  key: string | undefined,
+  choose: (projects: ProjectChoice[]) => Promise<string | null>,
+): Promise<ProjectChoice | string> {
+  if (projects.length === 0) return "Your Opsee account has no active project. Create one in the Opsee app first.";
+  const list = projects.map((p) => `${p.key} (${p.name})`).join(", ");
+  const byKey = (wanted: string) => projects.find((p) => p.key.toLowerCase() === wanted.toLowerCase());
+  if (key !== undefined) return byKey(key) ?? `No project with key ${key}. Projects: ${list}`;
+  if (projects.length === 1) return projects[0];
+  const chosen = await choose(projects);
+  return (chosen === null ? undefined : byKey(chosen)) ?? `Several projects; pass --project <key>. Projects: ${list}`;
+}

package/src/init/prompt.ts

@@ -0,0 +1,45 @@
+import { createInterface } from "node:readline/promises";
+import type { ProjectChoice } from "./project.js";
+import type { RunRecipe } from "../foreman/run-recipe.js";
+import type { RecipeDefaults } from "./run-recipe-config.js";
+
+/** Asks for the Run Recipe with the inferred values as defaults (Enter keeps them). Without a
+ * terminal the defaults stand as they are, and null comes back when no start command could be
+ * inferred, since a recipe without one cannot start anything. */
+export async function askRecipe(defaults: RecipeDefaults): Promise<RunRecipe | null> {
+  if (!process.stdin.isTTY) {
+    return defaults.start ? { ...defaults, start: defaults.start } : null;
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = async (label: string, fallback: string | undefined): Promise<string> => {
+    const answer = (await rl.question(`${label}${fallback ? ` [${fallback}]` : ""}: `)).trim();
+    return answer || fallback || "";
+  };
+  try {
+    rl.write("Run Recipe (how the Foreman starts the app for verification; {port} is the Worker's port):\n");
+    const start = await ask("Start command", defaults.start);
+    if (!start) return null;
+    const readinessUrl = await ask("Readiness URL", defaults.readinessUrl);
+    const portEnv = await ask("Port variable", defaults.portEnv);
+    const typecheck = await ask("Typecheck command (blank for none)", defaults.gates.typecheck);
+    return { start, readinessUrl, portEnv, gates: { ...defaults.gates, typecheck: typecheck || undefined } };
+  } finally {
+    rl.close();
+  }
+}
+
+/** Asks which project to set the repo up for; null when stdin is not a terminal, in which case
+ * the caller has to be told to pass `--project`. */
+export async function chooseProject(projects: ProjectChoice[]): Promise<string | null> {
+  if (!process.stdin.isTTY) return null;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    projects.forEach((p, i) => rl.write(`  ${i + 1}. ${p.key}  ${p.name}\n`));
+    const answer = (await rl.question(`Project [1-${projects.length}]: `)).trim();
+    const index = Number(answer);
+    if (Number.isInteger(index) && index >= 1 && index <= projects.length) return projects[index - 1].key;
+    return answer || null;
+  } finally {
+    rl.close();
+  }
+}

package/src/init/run-recipe-config.ts

@@ -0,0 +1,133 @@
+/** The Run Recipe step of `opsee init`: writes the `foreman` block into the analyzer's
+ * `.opsee/config` (yaml and its json copy) when absent and leaves an existing one exactly as it is,
+ * so a re-run never clobbers values the user or the analyzer wrote (spec story 5). */
+import { DEFAULT_PORT_ENV, DEFAULT_READINESS_URL, RECIPE_KEY, recipeFromConfig, type RunRecipe, type RunRecipeGates } from "../foreman/run-recipe.js";
+import { detectYamlIndent, parseOpseeJson, readYamlBlock, yamlScalar, type OpseeConfigFiles } from "../opsee-config.js";
+import type { WritePlan } from "./managed.js";
+import { detectJsonIndent, parseJsonObject } from "./text.js";
+
+/** A recipe with `start` still possibly unknown: what inference produces and the prompt offers
+ * as defaults. The prompt or the flags turn it into a RunRecipe. */
+export type RecipeDefaults = Omit<RunRecipe, "start"> & { start?: string };
+
+/** `--start`, `--readiness-url`, `--port-env`, `--typecheck` on `opsee init`: the recipe values
+ * for a non-interactive run; anything absent is inferred from `.opsee/config` or asked for. */
+export interface RecipeFlags {
+  start?: string;
+  readinessUrl?: string;
+  portEnv?: string;
+  typecheck?: string;
+}
+
+/** The analyzer's `commands` block (`dev`, `start`, `test`, `lint`, `install`...), string values
+ * only, from whichever of the two config files exists; the Foreman's install step reads it too. */
+export function commandsOf(files: OpseeConfigFiles): Record<string, string> {
+  const json = files.json === null ? null : parseOpseeJson(files.json);
+  const block = json ? json.commands : files.yaml === null ? undefined : readYamlBlock(files.yaml, "commands");
+  if (!block || typeof block !== "object") return {};
+  return Object.fromEntries(Object.entries(block as Record<string, unknown>).filter(([, v]) => typeof v === "string")) as Record<string, string>;
+}
+
+/** Defaults for the recipe: flags first, then the analyzer's `commands` (`dev`, or `start` when
+ * there is no dev server, for the start command; `test` and `lint` for the Gates). The typecheck
+ * Gate has no analyzer equivalent and is only ever a flag or a prompt answer. */
+export function inferRecipe(files: OpseeConfigFiles, flags: RecipeFlags): RecipeDefaults {
+  const commands = commandsOf(files);
+  return {
+    start: flags.start ?? commands.dev ?? commands.start,
+    readinessUrl: flags.readinessUrl ?? DEFAULT_READINESS_URL,
+    portEnv: flags.portEnv ?? DEFAULT_PORT_ENV,
+    gates: { test: commands.test, lint: commands.lint, typecheck: flags.typecheck },
+  };
+}
+
+/** Why `init` skipped the recipe when nothing said how to start the app. */
+export const NO_START_COMMAND =
+  "no start command: pass --start <cmd>, answer the prompt on a terminal, or set commands.dev in .opsee/config";
+
+/** The recipe a config file already carries, so a block present in one of the two files is copied
+ * into the other rather than asked for again; null when neither has a block that can serve as a
+ * recipe. The YAML is the analyzer's primary file and wins when both have one. */
+export function existingRecipe(files: OpseeConfigFiles): RunRecipe | null {
+  const candidates: unknown[] = [];
+  if (files.yaml !== null) candidates.push(readYamlBlock(files.yaml, RECIPE_KEY));
+  if (files.json !== null) candidates.push(parseOpseeJson(files.json)?.[RECIPE_KEY]);
+  for (const block of candidates) {
+    if (block === null || block === undefined) continue;
+    try {
+      return recipeFromConfig(block, RECIPE_KEY);
+    } catch {
+      // An incomplete block: mergeRecipe* reports it for its own file.
+    }
+  }
+  return null;
+}
+
+function gateEntries(gates: RunRecipeGates): Array<[string, string]> {
+  return (["test", "lint", "typecheck"] as const).flatMap((name) => (gates[name] ? [[name, gates[name]!] as [string, string]] : []));
+}
+
+function yamlRecipeBlock(recipe: RunRecipe, indent: string): string {
+  const lines = [
+    `${RECIPE_KEY}:`,
+    `${indent}start: ${yamlScalar(recipe.start)}`,
+    `${indent}readiness_url: ${yamlScalar(recipe.readinessUrl)}`,
+    `${indent}port_env: ${yamlScalar(recipe.portEnv)}`,
+  ];
+  const gates = gateEntries(recipe.gates);
+  if (gates.length > 0) {
+    lines.push(`${indent}gates:`);
+    for (const [name, command] of gates) lines.push(`${indent}${indent}${name}: ${yamlScalar(command)}`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+const YAML_HEADER = "# Opsee Project Configuration\n# Run Recipe written by opsee init; the Opsee analyzer fills in the rest.\n\n";
+
+/** Textual splice, like the Codex TOML merge: the analyzer's header comments and key order have
+ * no representation in a parsed document, so the block is appended rather than the file
+ * re-serialised. An existing `foreman` block is the user's or the analyzer's and is not rewritten;
+ * one that cannot serve as a recipe is reported instead. */
+export function mergeRecipeYaml(existing: string | null, recipe: RunRecipe): WritePlan {
+  const current = existing === null ? null : readYamlBlock(existing, RECIPE_KEY);
+  if (current !== null) return existingBlockPlan(current);
+  if (existing === null) {
+    return { action: "create", content: `${YAML_HEADER}version: "1.0"\n${yamlRecipeBlock(recipe, "    ")}` };
+  }
+  // No blank line before the block: yaml.v3, which wrote the rest of the file, puts none between
+  // top-level keys either.
+  const sep = existing === "" || existing.endsWith("\n") ? "" : "\n";
+  return { action: "update", content: `${existing}${sep}${yamlRecipeBlock(recipe, detectYamlIndent(existing))}` };
+}
+
+function existingBlockPlan(block: unknown): WritePlan {
+  try {
+    recipeFromConfig(block, RECIPE_KEY);
+    return { action: "unchanged" };
+  } catch (error) {
+    return { action: "kept-invalid", reason: `${error instanceof Error ? error.message : String(error)} Fix or delete the foreman block to let opsee init write its own.` };
+  }
+}
+
+function jsonRecipe(recipe: RunRecipe): Record<string, unknown> {
+  const gates = Object.fromEntries(gateEntries(recipe.gates));
+  return {
+    start: recipe.start,
+    readiness_url: recipe.readinessUrl,
+    port_env: recipe.portEnv,
+    ...(Object.keys(gates).length > 0 ? { gates } : {}),
+  };
+}
+
+/** The JSON copy of the same document: re-serialised in its own indentation with `foreman` added
+ * after the analyzer's members. */
+export function mergeRecipeJson(existing: string | null, recipe: RunRecipe): WritePlan {
+  if (existing === null) {
+    return { action: "create", content: JSON.stringify({ version: "1.0", [RECIPE_KEY]: jsonRecipe(recipe) }, null, "  ") + "\n" };
+  }
+  const parsed = parseJsonObject(existing);
+  if ("reason" in parsed) return { action: "kept-invalid", reason: parsed.reason };
+  if (RECIPE_KEY in parsed.root) return existingBlockPlan(parsed.root[RECIPE_KEY]);
+  const content = JSON.stringify({ ...parsed.root, [RECIPE_KEY]: jsonRecipe(recipe) }, null, detectJsonIndent(existing));
+  return { action: "update", content: existing.endsWith("\n") ? content + "\n" : content };
+}

package/src/init/skills.ts

@@ -0,0 +1,38 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import type { MarkerStyle } from "./managed.js";
+
+export interface SkillFile {
+  /** Path relative to the skills dir, e.g. `to-issues/SKILL.md`. */
+  rel: string;
+  content: string;
+  style: MarkerStyle;
+}
+
+/** Every file of every skill folder under `dir`, file-for-file; `opsee init` copies exactly this
+ * set into each target. Files at the top level (the folder's own README) are not skills. A file
+ * whose type has no comment syntax we stamp is refused rather than copied unmarked, because an
+ * unmarked copy could never be told from a user's file on re-run. */
+export function listSkillFiles(dir: string): SkillFile[] {
+  const out: SkillFile[] = [];
+  const walk = (path: string, depth: number) => {
+    const entries = readdirSync(path, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const full = join(path, entry.name);
+      if (entry.isDirectory()) walk(full, depth + 1);
+      else if (depth > 0) out.push({ rel: relative(dir, full), content: readFileSync(full, "utf8"), style: styleFor(entry.name) });
+    }
+  };
+  walk(dir, 0);
+  return out;
+}
+
+function styleFor(name: string): MarkerStyle {
+  if (/\.md$/i.test(name)) return "markdown";
+  if (/\.ya?ml$/i.test(name)) return "yaml";
+  throw new Error(`Skill file ${name} has a type opsee init cannot mark as managed`);
+}
+
+export function skillNames(files: SkillFile[]): string[] {
+  return [...new Set(files.map((f) => f.rel.split("/")[0]))];
+}

package/src/init/text.ts

@@ -0,0 +1,22 @@
+/** The indentation a JSON file already uses, so a merge does not reformat it. */
+export function detectJsonIndent(json: string): string {
+  const match = /^([ \t]+)"/m.exec(json);
+  return match ? match[1] : "  ";
+}
+
+/** Parses a JSON document that must be an object; `reason` says why it is not one. */
+export function parseJsonObject(text: string): { root: Record<string, unknown> } | { reason: string } {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { reason: "top level is not an object" };
+    return { root: parsed as Record<string, unknown> };
+  } catch (error) {
+    return { reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** Appends `block` to `existing` with exactly one blank line between them. */
+export function appendBlock(existing: string, block: string): string {
+  const sep = existing === "" || existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  return `${existing}${sep}${block}`;
+}

package/src/init/tracker-doc.ts

@@ -0,0 +1,106 @@
+/** Renders the per-repo tracker doc from the template shipped in this package, filling in what
+ * differs per Opsee project: its key and id, the label ids, the board and its columns, the task
+ * types and priorities. The doc's structure (its section names) is fixed by the template; the
+ * planning skills' structural test asserts it. */
+
+export interface Named {
+  id: number;
+  name: string;
+}
+
+export interface TrackerDocData {
+  project: { id: number; name: string; key: string };
+  labels: Named[];
+  board: Named;
+  /** In board order. */
+  columns: Named[];
+  types: Named[];
+  priorities: Named[];
+}
+
+export const READY_LABEL = "ready-for-agent";
+
+/** What the doc says where the ready label's id should go when the project has none; the id is
+ * filled in by the next `opsee init` once the label exists. Rendering never creates it: setting
+ * up a repo must not write to the tracker. */
+export const READY_LABEL_MISSING = `<no ${READY_LABEL} label yet: create it in Opsee, then re-run opsee init>`;
+
+const norm = (name: string) => name.trim().toLowerCase().replace(/[\s_-]+/g, " ");
+
+/** Pipes would start a new markdown table cell; names come from the user's project. */
+const cell = (text: string) => text.replace(/\|/g, "\\|");
+
+const LABEL_MEANINGS: Array<[RegExp, string]> = [
+  [/^ready for agent$/, "Triage: spec is complete, ready for an unattended Worker"],
+  [/^from pr$/, "Task created from a merge request"],
+  [/^wayfinder:/, "Wayfinder ticket type (see Wayfinding operations)"],
+];
+
+type Role = "todo" | "inProgress" | "done";
+
+/** The one place a column name is interpreted: what the skills call it, whether it counts as
+ * closed, and which role (if any) it fills in the doc's tool calls. */
+const COLUMN_KINDS: Array<{ re: RegExp; meaning: string; role?: Role; closed?: boolean }> = [
+  { re: /^backlog$/, meaning: "open, not yet scheduled" },
+  { re: /^to ?do$/, meaning: "open; where new Tasks land", role: "todo" },
+  { re: /^(in progress|doing)$/, meaning: "open, claimed and being worked", role: "inProgress" },
+  { re: /^in review$/, meaning: "open, Hand-off (draft MR) exists" },
+  { re: /^(done|closed|completed?)$/, meaning: "**closed**", role: "done", closed: true },
+  { re: /^archived?$/, meaning: "closed, hidden", closed: true },
+];
+
+const kindOf = (column: Named) => COLUMN_KINDS.find((k) => k.re.test(norm(column.name)));
+
+/** The columns the skills address by role, resolved by name with a positional fallback so a
+ * board with unusual names still yields a doc whose ids point somewhere sensible. */
+export function columnRoles(columns: Named[]): Record<Role, Named> {
+  if (columns.length === 0) throw new Error("The board has no columns");
+  const byRole = (role: Role) => columns.find((c) => kindOf(c)?.role === role);
+  const open = columns.filter((c) => !kindOf(c)?.closed);
+  const todo = byRole("todo") ?? open[0] ?? columns[0];
+  const inProgress = byRole("inProgress") ?? todo;
+  const done = byRole("done") ?? open[open.length - 1] ?? columns[columns.length - 1];
+  return { todo, inProgress, done };
+}
+
+export function findReadyLabel(labels: Named[]): Named | undefined {
+  return labels.find((l) => norm(l.name) === norm(READY_LABEL));
+}
+
+const idList = (items: Named[]) => items.map((i) => `${i.name} \`${i.id}\``).join(", ");
+
+export function renderTrackerDoc(template: string, data: TrackerDocData): string {
+  const ready = findReadyLabel(data.labels);
+  const bug = data.types.find((t) => /bug/.test(norm(t.name))) ?? data.types[0];
+  if (!bug) throw new Error("The project has no task types");
+  const roles = columnRoles(data.columns);
+  const labelsOrdered = ready ? [ready, ...data.labels.filter((l) => l !== ready)] : data.labels;
+  const labelRows = labelsOrdered
+    .map((l) => `  | \`${cell(l.name)}\` | ${l.id} | ${LABEL_MEANINGS.find(([re]) => re.test(norm(l.name)))?.[1] ?? "Project label, optional"} |`)
+    .join("\n");
+  const columnRows = data.columns.map((c) => `  | ${cell(c.name)} | ${c.id} | ${kindOf(c)?.meaning ?? "open"} |`).join("\n");
+  const values: Record<string, string> = {
+    PROJECT_NAME: data.project.name,
+    PROJECT_KEY: data.project.key,
+    PROJECT_ID: String(data.project.id),
+    LABELS_ROWS: labelRows,
+    READY_LABEL_ID: ready ? String(ready.id) : READY_LABEL_MISSING,
+    BOARD_NAME: data.board.name,
+    BOARD_ID: String(data.board.id),
+    COLUMNS_ROWS: columnRows,
+    TODO_COLUMN_ID: String(roles.todo.id),
+    IN_PROGRESS_COLUMN_ID: String(roles.inProgress.id),
+    DONE_COLUMN_ID: String(roles.done.id),
+    BUG_TYPE_ID: String(bug.id),
+    TYPES_LINE: idList(data.types),
+    PRIORITIES_LINE: idList(data.priorities),
+  };
+  const rendered = template.replace(/\{\{([A-Z_]+)\}\}/g, (whole, key: string) => {
+    const value = values[key];
+    if (value === undefined) throw new Error(`Template placeholder ${whole} has no value`);
+    return value;
+  });
+  const left = /\{\{[A-Z_]+\}\}/.exec(rendered);
+  if (left) throw new Error(`Unfilled placeholder ${left[0]}`);
+  return rendered;
+}

package/src/opsee-config.ts

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseJsonObject } from "./init/text.js";
+
+/** The analyzer writes `.opsee/config.yaml` and a JSON copy of the same document
+ * (orchestrator/internal/analysis/analyzer.go); anything that edits one must keep the other in step. */
+export const OPSEE_CONFIG_YAML = ".opsee/config.yaml";
+export const OPSEE_CONFIG_JSON = ".opsee/config.json";
+
+export interface OpseeConfigFiles {
+  yaml: string | null;
+  json: string | null;
+}
+
+export function readOpseeConfigFiles(root: string): OpseeConfigFiles {
+  const read = (rel: string) => (existsSync(join(root, rel)) ? readFileSync(join(root, rel), "utf8") : null);
+  return { yaml: read(OPSEE_CONFIG_YAML), json: read(OPSEE_CONFIG_JSON) };
+}
+
+/** The JSON copy as an object, or null when it is not one; callers that must report why parse it
+ * through `parseJsonObject` instead. */
+export function parseOpseeJson(json: string): Record<string, unknown> | null {
+  const parsed = parseJsonObject(json);
+  return "root" in parsed ? parsed.root : null;
+}
+
+/** A mapping of scalars, one level of nesting deep: the shape of the config blocks the CLI reads
+ * (`commands`, `foreman`). Anything else in the block is skipped, not an error. */
+export type ScalarBlock = Record<string, string | Record<string, string>>;
+
+/** Strips a trailing `# comment` from a scalar and unquotes a single- or double-quoted one. Quoted
+ * strings honour the escapes that appear in generated configs (`\"`, `\\`, `''`); YAML's wider
+ * escape set is out of scope for a reader that only ever sees commands and URLs. */
+export function parseScalar(raw: string): string {
+  const text = raw.trim();
+  const quote = text[0];
+  if (quote !== '"' && quote !== "'") return text.replace(/\s+#.*$/, "").trim();
+  // Walk to the closing quote so a comment after it (`'x' # don't`) is not mistaken for content.
+  let out = "";
+  for (let i = 1; i < text.length; i++) {
+    const c = text[i];
+    if (quote === '"' && c === "\\" && i + 1 < text.length) {
+      out += text[++i];
+    } else if (quote === "'" && c === "'" && text[i + 1] === "'") {
+      out += "'";
+      i++;
+    } else if (c === quote) {
+      return out;
+    } else {
+      out += c;
+    }
+  }
+  return text;
+}
+
+function indentOf(line: string): number {
+  return line.length - line.trimStart().length;
+}
+
+const KEY_LINE = /^([A-Za-z_][\w-]*):(?:\s+(.*))?$/;
+
+/** Reads the top-level `key:` block of a YAML document as scalars plus one nested mapping level.
+ * Returns null when the document has no such key; an empty object when it is present but empty. */
+export function readYamlBlock(yaml: string, key: string): ScalarBlock | null {
+  const lines = yaml.split("\n");
+  const start = lines.findIndex((line) => new RegExp(`^${key}:\\s*(#.*)?$`).test(line));
+  if (start === -1) return null;
+  const block: ScalarBlock = {};
+  let child: { name: string; indent: number; map: Record<string, string> } | null = null;
+  let blockIndent = -1;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+    const indent = indentOf(line);
+    if (indent === 0) break;
+    const match = KEY_LINE.exec(line.trim());
+    if (!match) continue;
+    const [, name, value] = match;
+    if (blockIndent === -1) blockIndent = indent;
+    if (indent === blockIndent) {
+      if (value === undefined || value.trim() === "" || value.trim().startsWith("#")) {
+        child = { name, indent: -1, map: {} };
+        block[name] = child.map;
+      } else {
+        child = null;
+        block[name] = parseScalar(value);
+      }
+    } else if (child && indent > blockIndent && (child.indent === -1 || indent === child.indent) && value !== undefined) {
+      child.indent = indent;
+      child.map[name] = parseScalar(value);
+    }
+  }
+  return block;
+}
+
+/** The indentation step the document already uses (the analyzer's yaml.v3 output uses four
+ * spaces), so an appended block does not look foreign. */
+export function detectYamlIndent(yaml: string): string {
+  const match = /^( +)\S/m.exec(yaml);
+  return match ? match[1] : "    ";
+}
+
+/** Quotes a scalar the way the analyzer's output does: bare when plain, double-quoted when YAML
+ * would otherwise misread it (a leading `$` or `- `, a `{`, a `: `, a `#`, or surrounding
+ * whitespace). */
+export function yamlScalar(value: string): string {
+  if (value === "") return '""';
+  if (
+    /^[A-Za-z0-9_./-][^#:{}[\],&*?!|>'"%@`]*$/.test(value) &&
+    !/^-(\s|$)|:\s|\s#|\s$/.test(value) &&
+    !/^(true|false|null|yes|no|~)$/i.test(value)
+  ) {
+    return value;
+  }
+  return JSON.stringify(value);
+}