@gavana.ai/cli 0.2.0

package/src/commands.mjs

@@ -0,0 +1,259 @@
+// The Gavana CLI command table.
+//
+// One declaration of what commands exist. Before this, the same knowledge lived
+// twice: as nested group/action comparisons inside executeCommand, and again as a
+// hand-maintained usage block inside helpText. The two drifted, and nothing failed
+// when they did — a renamed command kept a stale help line, and a new command
+// shipped undocumented.
+//
+// Help text and shell completions are generated from this array, and runner.mjs
+// asks gavanaCommandIsKnown before dispatching anything. So this is a gate, not a
+// description: a command absent from here is unreachable, whatever the dispatch
+// branches happen to look like. The one exception is a freeformAction group, where
+// the second positional is data and only the group name can be checked.
+//
+// Handler bodies deliberately stay in runner.mjs. They reach into roughly seventy
+// helpers in that file, so moving them here would drag most of the module across a
+// module boundary for no gain. What matters is that the catalog has one home; the
+// drift test in scripts/gavana-cli-command-table.test.mjs holds runner's dispatch
+// to it.
+
+/**
+ * @typedef {object} GavanaCliCommand
+ * @property {string} group Command group, e.g. "canvas".
+ * @property {string} action Sub-command, or "" for a group that takes none.
+ * @property {string[]} usage Usage lines exactly as the root help prints them.
+ * @property {string[]} [notesBefore] Prose printed above this command in root help.
+ * @property {boolean} [hidden] Dispatchable but never advertised anywhere: a
+ *   retired surface or a compatibility alias. Absent from help AND completions.
+ * @property {string} [documentedBy] A real, supported command whose usage line
+ *   lives on another entry (`config get` rides `config list | get | use`). It is
+ *   advertised by completions, it just does not print a second usage line. The
+ *   value names the group whose help block covers it, and a test asserts that
+ *   block really does show the invocation.
+ * @property {boolean} [freeformAction] The second positional is data, not a
+ *   sub-command: `gavana api GET /canvases` passes GET as the HTTP method. Such a
+ *   group accepts any action, so the dispatch guard cannot check it.
+ */
+
+/** @type {GavanaCliCommand[]} */
+export const GAVANA_CLI_COMMANDS = Object.freeze([
+    {
+        group: "auth",
+        action: "login",
+        usage: ["gavana auth login [--profile NAME] [--read-only]", "gavana auth login --base-url URL --token-stdin"],
+        groupUsage: ["gavana auth login [--profile NAME] [--read-only] [--no-browser]", "gavana auth login --token-stdin [--profile NAME]"],
+    },
+    { group: "auth", action: "status", usage: ["gavana auth status"], groupUsage: ["gavana auth status [--profile NAME]"] },
+    { group: "config", action: "list", usage: ["gavana config list | get [PROFILE] | use PROFILE"], groupUsage: ["gavana config list"] },
+    { group: "doctor", action: "", usage: ["gavana doctor [--profile NAME]"] },
+    {
+        group: "api",
+        action: "",
+        usage: ["gavana api GET /canvases --field limit=10"],
+        groupUsage: ["gavana api GET /canvases --field limit=10", `gavana api POST /canvases --json '{"title":"Concepts"}'`],
+        freeformAction: true,
+    },
+    {
+        group: "mcp",
+        action: "install",
+        usage: ["gavana mcp install codex|claude [--read-only]"],
+        groupUsage: ["gavana mcp install codex [--read-only]", "gavana mcp install claude [--read-only]"],
+    },
+    { group: "mcp", action: "config", usage: ["gavana mcp config cursor|chatgpt|local [--read-only]"] },
+    { group: "completion", action: "zsh", usage: ["gavana completion zsh|bash|fish"], groupUsage: ["gavana completion zsh"] },
+    { group: "version", action: "", usage: ["gavana version"] },
+    { group: "capabilities", action: "", usage: ["gavana capabilities"] },
+    {
+        group: "recipe",
+        action: "search",
+        usage: ["gavana recipe search [query] [--limit N] [--cursor CURSOR]"],
+        notesBefore: [
+            "Recipe commands are retained API compatibility while the Recipe UI is unavailable in production.",
+            "They never start image work automatically; recipe_run is the separate explicit paid action.",
+        ],
+    },
+    { group: "recipe", action: "get", usage: ["gavana recipe get recipe:<id> [--version VERSION]"] },
+    { group: "recipe", action: "fork", usage: ["gavana recipe fork recipe:<id> --canvas canvas:<id> --idempotency-key KEY [--x X --y Y]"] },
+    {
+        group: "recipe",
+        action: "run",
+        usage: ["gavana recipe run recipe:<id> --input key=value --destination canvas:<id>", "gavana recipe run recipe:social-creative-angles --input offer-brief=@brief.md --destination agent-canvas"],
+        groupUsage: [
+            "gavana recipe run recipe:<id> --input KEY=VALUE --destination agent-canvas|new-canvas|canvas:<id>",
+            "gavana recipe run recipe:social-creative-angles --input offer-brief=@brief.md --destination agent-canvas",
+        ],
+    },
+    { group: "canvas", action: "list", usage: ["gavana canvas list [--limit N] [--cursor CURSOR]"] },
+    { group: "canvas", action: "agent", usage: ["gavana canvas agent"] },
+    { group: "canvas", action: "create", usage: ["gavana canvas create --title \"New canvas\""] },
+    { group: "canvas", action: "get", usage: ["gavana canvas get canvas:<owner>:<id>"] },
+    { group: "canvas", action: "render", usage: ["gavana canvas render canvas:<id> --file canvas.svg"] },
+    { group: "canvas", action: "apply", usage: ["gavana canvas apply canvas:<id> --file batch.json [--yes]"] },
+    { group: "node", action: "get", usage: ["gavana node get canvas:<id> node:<id>"] },
+    { group: "node", action: "create", usage: ["gavana node create canvas:<id> --type text --title \"Direction\" --prompt \"...\""] },
+    {
+        group: "node",
+        action: "update",
+        usage: ["gavana node update canvas:<id> node:<id> --title \"Approved\""],
+        groupUsage: ["gavana node update canvas:<id> node:<id> [--title VALUE --prompt VALUE]"],
+    },
+    { group: "node", action: "move", usage: ["gavana node move canvas:<id> node:<id> --x 800 --y 120"] },
+    { group: "node", action: "resize", usage: ["gavana node resize canvas:<id> node:<id> --width 420 --height 300"] },
+    { group: "node", action: "delete", usage: ["gavana node delete canvas:<id> node:<id> --yes"] },
+    { group: "connection", action: "list", usage: ["gavana connection list canvas:<id>"] },
+    { group: "connection", action: "create", usage: ["gavana connection create canvas:<id> --from node:<id> --to node:<id>"] },
+    { group: "connection", action: "delete", usage: ["gavana connection delete canvas:<id> connection:<id> --yes"] },
+    { group: "asset", action: "list", usage: ["gavana asset list [--canvas canvas:<id>] [--limit N] [--cursor CURSOR]"] },
+    { group: "asset", action: "get", usage: ["gavana asset get asset:<id>|asset:<ownerUid>:<id>"] },
+    { group: "asset", action: "upload", usage: ["gavana asset upload path/to/image.png"] },
+    { group: "provider", action: "list", usage: ["gavana provider list [--limit N] [--cursor CURSOR]"] },
+    { group: "model", action: "list", usage: ["gavana model list [query] [--provider PROVIDER] [--capability image.generate]"] },
+    { group: "model", action: "get", usage: ["gavana model get model:<id>"] },
+    { group: "action", action: "list", usage: ["gavana action list [query] [--limit N] [--cursor CURSOR]"] },
+    { group: "action", action: "get", usage: ["gavana action get action:<id>"] },
+    {
+        group: "action",
+        action: "run",
+        usage: ["gavana action run action:resize --input node:<id> --destination canvas:<id> --width 1080 --height 1350", "gavana action run action:side-by-side-composite --input node:<id> --input asset:<id> --destination canvas:<id>"],
+        groupUsage: [
+            "gavana action run action:<id> --input VALUE --destination VALUE [--param NAME=VALUE]",
+            "gavana action run action:resize --input node:<id> --destination canvas:<id> --width 1080 --height 1350",
+            "gavana action run action:side-by-side-composite --input node:<id> --input asset:<id> --destination canvas:<id>",
+        ],
+    },
+    { group: "image", action: "generate", usage: ["gavana image generate --destination agent-canvas --prompt \"...\""] },
+    { group: "image", action: "edit", usage: ["gavana image edit --destination canvas:<id> --reference path/to/image.png --prompt \"...\""] },
+    { group: "image", action: "variations", usage: ["gavana image variations --destination new-canvas --canvas-title \"Variations\" --reference path/to/source.png --prompt \"...\""] },
+    { group: "video", action: "generate", usage: ["gavana video generate --model model:<id> --prompt \"...\" --duration 15", "gavana video generate --model model:<id> --prompt \"...\" --first-frame path/to/start.png --no-wait", "gavana video generate --model model:<id> --prompt \"...\" --download output.mp4"] },
+    { group: "video", action: "download", usage: ["gavana video download job:<id> --file output.mp4 [--yes]"] },
+    { group: "job", action: "get", usage: ["gavana job get job:<id>"] },
+    { group: "job", action: "wait", usage: ["gavana job wait job:<id> [--progress] [--output markdown]"] },
+    { group: "job", action: "cancel", usage: ["gavana job cancel job:<id> --yes"] },
+    { group: "run", action: "get", usage: ["gavana run get run:<id>"] },
+    { group: "run", action: "wait", usage: ["gavana run wait run:<id> [--progress] [--output markdown]"] },
+    { group: "run", action: "cancel", usage: ["gavana run cancel run:<id> --yes"] },
+    // Retired campaign surface. Still dispatched so an installed script fails with a
+    // clear message rather than "unknown command", but never advertised.
+    { group: "campaign", action: "plan", usage: [], hidden: true },
+    { group: "campaign", action: "start", usage: [], hidden: true },
+    { group: "campaign", action: "get", usage: [], hidden: true },
+    { group: "campaign", action: "review", usage: [], hidden: true },
+    { group: "campaign", action: "cancel", usage: [], hidden: true },
+    // Accepted as an alias of `provider list` for older scripts.
+    { group: "ai-connection", action: "list", usage: [], hidden: true },
+    // Group-only commands the root help lists without a sub-command.
+    { group: "auth", action: "logout", usage: [], groupUsage: ["gavana auth logout [--profile NAME]"], documentedBy: "auth" },
+    // Bare `gavana config` behaves as `config list` and `gavana completion` as
+    // `completion zsh`. Both work, neither appears in any help text, so they are
+    // hidden rather than claiming a documentation home they do not have.
+    { group: "config", action: "", usage: [], hidden: true },
+    { group: "config", action: "get", usage: [], groupUsage: ["gavana config get [PROFILE]"], documentedBy: "config" },
+    // Undeclared until the command table went in: `config profiles` has always been
+    // an accepted alias of `config list`, and appeared in no help text.
+    { group: "config", action: "profiles", usage: [], hidden: true },
+    { group: "config", action: "use", usage: [], groupUsage: ["gavana config use PROFILE"], documentedBy: "config" },
+    { group: "completion", action: "", usage: [], hidden: true },
+    { group: "completion", action: "bash", usage: [], groupUsage: ["gavana completion bash"], documentedBy: "completion" },
+    { group: "completion", action: "fish", usage: [], groupUsage: ["gavana completion fish"], documentedBy: "completion" },
+]);
+
+/** Every command key, in `group action` form (a group-only command is just the group). */
+export function gavanaCommandKey(command) {
+    return [command.group, command.action].filter(Boolean).join(" ");
+}
+
+/** Lookup by group and action. Undefined means the CLI does not have this command. */
+export function gavanaCommand(group, action = "") {
+    return GAVANA_CLI_COMMANDS.find((command) => command.group === group && command.action === action);
+}
+
+/**
+ * Distinct groups, in the order the root help introduces them.
+ *
+ * A group whose every command is hidden is itself hidden, so the retired campaign
+ * surface and the ai-connection alias fall out of completions without a second
+ * hardcoded list to keep in step with this one.
+ */
+export function gavanaCommandGroups({ includeHidden = false } = {}) {
+    const groups = Array.from(new Set(GAVANA_CLI_COMMANDS.map((command) => command.group)));
+    if (includeHidden) return groups;
+    return groups.filter((group) => GAVANA_CLI_COMMANDS.some((command) => command.group === group && !command.hidden));
+}
+
+/**
+ * Actions under one group. Hidden ones are excluded by default: advertising an
+ * unadvertised alias in a shell completion is the same leak as printing it in help.
+ */
+export function gavanaCommandActions(group, { includeHidden = false } = {}) {
+    return GAVANA_CLI_COMMANDS.filter((command) => command.group === group && command.action && (includeHidden || !command.hidden)).map((command) => command.action);
+}
+
+/**
+ * The usage block of the root help, generated rather than maintained.
+ *
+ * Hidden commands are omitted here and only here: they stay dispatchable, and the
+ * drift test still sees them, but they are not advertised.
+ */
+export function gavanaCommandUsageLines() {
+    return GAVANA_CLI_COMMANDS.filter((command) => !command.hidden).flatMap((command) => [...(command.notesBefore || []), ...command.usage]);
+}
+
+/**
+ * The five groups whose `--help` page has its own title and closing note.
+ *
+ * Every other group gets the generic "Gavana <group> commands" page. These five
+ * carry something a usage line cannot: where the token is stored, that a bare
+ * --profile works everywhere, that remote clients use OAuth, that API paths are
+ * restricted. The usage lines themselves still come from the table.
+ */
+export const GAVANA_CLI_GROUP_HELP = Object.freeze({
+    auth: {
+        title: "Gavana authentication",
+        note: "Browser login is the default. On macOS, the token is stored in Keychain; custom config paths use a mode-0600 file.",
+    },
+    config: { title: "Gavana profiles", note: "Use --profile NAME on any command or set GAVANA_PROFILE." },
+    mcp: { title: "Gavana MCP setup", note: "Remote clients use browser OAuth. The read-only endpoint exposes no mutation or generation tools." },
+    api: { title: "Raw Gavana Canvas API", note: "Paths are restricted to /api/canvas-agent/v1." },
+    completion: { title: "Generate shell completion", note: "" },
+});
+
+/**
+ * The usage lines for one group's help page, optionally narrowed to one action.
+ *
+ * `groupUsage` overrides `usage` where the root help deliberately compresses
+ * several commands onto one line — `gavana config list | get [PROFILE] | use
+ * PROFILE` is right for a root summary and wrong for the config page, which has
+ * room to show each form. Everything else falls back to `usage`, so a command
+ * added to the table appears on its group page without a second edit. That
+ * fallback is the point: group help used to be an independent catalog, and it had
+ * drifted behind the root list.
+ */
+export function gavanaCommandGroupUsageLines(group, action = "") {
+    const entries = GAVANA_CLI_COMMANDS.filter((command) => command.group === group && !command.hidden);
+    // A freeform group takes data in the action slot, so narrowing by it is
+    // meaningless: `gavana api GET /canvases --help` would look up an action named
+    // GET, find none, and answer "Unknown api action: GET" for a command that is
+    // perfectly valid. The whole group's page is the right answer there.
+    const narrow = action && !entries.some((command) => command.freeformAction);
+    const selected = narrow ? entries.filter((command) => command.action === action) : entries;
+    return selected.flatMap((command) => command.groupUsage || command.usage);
+}
+
+/**
+ * Whether the CLI should accept this command at all.
+ *
+ * runner.mjs calls this before dispatching, which is what makes the table the
+ * catalog rather than a description of one. A source scanner could only ever
+ * detect drift after the fact, and only for the code shapes it happened to
+ * recognise; a runtime lookup makes an undeclared command impossible to reach.
+ *
+ * A freeformAction group takes data in the action position, so only its group is
+ * checked.
+ */
+export function gavanaCommandIsKnown(group, action = "") {
+    if (!group) return false;
+    const freeform = GAVANA_CLI_COMMANDS.find((command) => command.group === group && command.freeformAction);
+    if (freeform) return true;
+    return Boolean(gavanaCommand(group, action));
+}

package/src/config.mjs

@@ -0,0 +1,197 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCallback);
+const KEYCHAIN_SERVICE = "ai.gavana.cli";
+
+export async function readAgentConfig(env = process.env) {
+    const store = await readAgentConfigStore(env);
+    const profile = selectedProfileName(store, env);
+    const selected = store.profiles?.[profile] || {};
+    let token = selected.token || "";
+    if (!token && selected.credentialStore === "macos-keychain") token = await readMacKeychainCredential(profile);
+    return { ...store, ...selected, ...(token ? { token } : {}), profile };
+}
+
+export async function readAgentConfigMetadata(env = process.env) {
+    const store = await readAgentConfigStore(env);
+    const profile = selectedProfileName(store, env);
+    const selected = store.profiles?.[profile] || {};
+    return {
+        version: 1,
+        activeProfile: store.activeProfile,
+        profile,
+        baseUrl: selected.baseUrl || "",
+        credentialStore: selected.credentialStore || "",
+        authMode: selected.authMode || "",
+    };
+}
+
+export async function readAgentConfigStore(env = process.env) {
+    for (const filePath of agentConfigFileCandidates(env)) {
+        try {
+            const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+            return normalizeConfigStore(parsed);
+        } catch {
+            // New Gavana config wins. Fall back to the legacy Craftboard path
+            // only when no explicit config file was requested.
+        }
+    }
+    return normalizeConfigStore({});
+}
+
+export async function writeAgentConfig(config, env = process.env) {
+    const current = await readAgentConfigStore(env);
+    const profile = cleanProfileName(config.profile || selectedProfileName(current, env));
+    let token = config.token || "";
+    let credentialStore = config.credentialStore || "";
+    if (token && shouldUseMacKeychain(env)) {
+        await writeMacKeychainCredential(profile, token);
+        token = "";
+        credentialStore = "macos-keychain";
+    }
+    const profileConfig = {
+        ...(current.profiles?.[profile] || {}),
+        ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
+        ...(token ? { token } : {}),
+        ...(credentialStore ? { credentialStore } : {}),
+        ...(config.authMode ? { authMode: config.authMode } : {}),
+    };
+    if (credentialStore === "macos-keychain") delete profileConfig.token;
+    const next = {
+        version: 1,
+        activeProfile: profile,
+        profiles: { ...(current.profiles || {}), [profile]: profileConfig },
+    };
+    return writeAgentConfigStore(next, env);
+}
+
+export async function writeAgentConfigStore(config, env = process.env) {
+    const filePath = agentConfigFilePath(env);
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    const active = config.profiles?.[config.activeProfile] || {};
+    const compatible = {
+        ...config,
+        ...(active.baseUrl ? { baseUrl: active.baseUrl } : {}),
+        ...(active.token ? { token: active.token } : {}),
+    };
+    await fs.writeFile(temporary, `${JSON.stringify(compatible, null, 2)}\n`, { mode: 0o600 });
+    await fs.rename(temporary, filePath);
+    await fs.chmod(filePath, 0o600);
+    return filePath;
+}
+
+export async function removeAgentConfig(env = process.env) {
+    const filePaths = agentConfigFileCandidates(env);
+    await Promise.all(filePaths.map((filePath) => fs.rm(filePath, { force: true })));
+    return filePaths[0];
+}
+
+export async function removeAgentProfile(profile, env = process.env) {
+    const store = await readAgentConfigStore(env);
+    const name = cleanProfileName(profile || selectedProfileName(store, env));
+    if (!store.profiles?.[name]) return { configPath: agentConfigFilePath(env), profile: name, removed: false };
+    const profiles = { ...store.profiles };
+    if (profiles[name]?.credentialStore === "macos-keychain") await removeMacKeychainCredential(name);
+    delete profiles[name];
+    if (!Object.keys(profiles).length) {
+        await removeAgentConfig(env);
+        return { configPath: agentConfigFilePath(env), profile: name, removed: true };
+    }
+    const activeProfile = store.activeProfile === name ? Object.keys(profiles).sort()[0] : store.activeProfile;
+    await writeAgentConfigStore({ version: 1, activeProfile, profiles }, env);
+    return { configPath: agentConfigFilePath(env), profile: name, removed: true, activeProfile };
+}
+
+export async function setActiveAgentProfile(profile, env = process.env) {
+    const store = await readAgentConfigStore(env);
+    const name = cleanProfileName(profile);
+    if (!store.profiles?.[name]) throw configUsageError(`Unknown Gavana profile: ${name}`);
+    await writeAgentConfigStore({ ...store, version: 1, activeProfile: name }, env);
+    return { profile: name, configPath: agentConfigFilePath(env) };
+}
+
+export async function listAgentProfiles(env = process.env) {
+    const store = await readAgentConfigStore(env);
+    return {
+        activeProfile: selectedProfileName(store, env),
+        profiles: Object.entries(store.profiles || {})
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([name, value]) => ({
+                name,
+                baseUrl: value?.baseUrl || "",
+                active: name === selectedProfileName(store, env),
+                configured: Boolean(value?.baseUrl && (value?.token || value?.credentialStore === "macos-keychain")),
+            })),
+        configPath: agentConfigFilePath(env),
+    };
+}
+
+export function agentConfigFilePath(env = process.env) {
+    if (env.GAVANA_AGENT_CONFIG_FILE) return path.resolve(env.GAVANA_AGENT_CONFIG_FILE);
+    if (env.CRAFTBOARD_AGENT_CONFIG_FILE) return path.resolve(env.CRAFTBOARD_AGENT_CONFIG_FILE);
+    const configHome = env.XDG_CONFIG_HOME || path.join(env.HOME || os.homedir(), ".config");
+    return path.join(configHome, "gavana", "agent.json");
+}
+
+function agentConfigFileCandidates(env) {
+    const preferred = agentConfigFilePath(env);
+    if (env.GAVANA_AGENT_CONFIG_FILE || env.CRAFTBOARD_AGENT_CONFIG_FILE) return [preferred];
+    const configHome = env.XDG_CONFIG_HOME || path.join(env.HOME || os.homedir(), ".config");
+    return [preferred, path.join(configHome, "craftboard", "agent.json")];
+}
+
+function normalizeConfigStore(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return { version: 1, activeProfile: "default", profiles: {} };
+    if (value.profiles && typeof value.profiles === "object" && !Array.isArray(value.profiles)) {
+        return { version: 1, activeProfile: cleanProfileName(value.activeProfile || "default"), profiles: value.profiles };
+    }
+    const legacy = {
+        ...(typeof value.baseUrl === "string" && value.baseUrl ? { baseUrl: value.baseUrl } : {}),
+        ...(typeof value.token === "string" && value.token ? { token: value.token } : {}),
+    };
+    return { version: 1, activeProfile: "default", profiles: Object.keys(legacy).length ? { default: legacy } : {} };
+}
+
+function selectedProfileName(store, env) {
+    return cleanProfileName(env.GAVANA_PROFILE || env.CRAFTBOARD_PROFILE || store.activeProfile || "default");
+}
+
+function cleanProfileName(value) {
+    const name = String(value || "default").trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(name)) throw configUsageError("Profile names must use 1-64 letters, numbers, dots, underscores, or dashes.");
+    return name;
+}
+
+function configUsageError(message) {
+    return Object.assign(new Error(message), { code: "usage" });
+}
+
+function shouldUseMacKeychain(env) {
+    return process.platform === "darwin" && env.GAVANA_CLI_KEYCHAIN !== "false" && !env.GAVANA_AGENT_CONFIG_FILE && !env.CRAFTBOARD_AGENT_CONFIG_FILE && !env.XDG_CONFIG_HOME;
+}
+
+async function writeMacKeychainCredential(profile, token) {
+    await execFile("security", ["add-generic-password", "-a", profile, "-s", KEYCHAIN_SERVICE, "-w", token, "-U"]);
+}
+
+async function readMacKeychainCredential(profile) {
+    try {
+        const { stdout } = await execFile("security", ["find-generic-password", "-a", profile, "-s", KEYCHAIN_SERVICE, "-w"]);
+        return stdout.trim();
+    } catch {
+        return "";
+    }
+}
+
+async function removeMacKeychainCredential(profile) {
+    try {
+        await execFile("security", ["delete-generic-password", "-a", profile, "-s", KEYCHAIN_SERVICE]);
+    } catch {
+        // Missing keychain items are already logged out.
+    }
+}

package/src/guide-sources.mjs

@@ -0,0 +1,86 @@
+// Generated by scripts/generate-canvas-guides.mjs from packages/cli/guides/*.md.
+// Do not edit. Edit the markdown and run: node scripts/generate-canvas-guides.mjs
+
+/** Guide prose, ordered by frontmatter `order`. Order drives the guide index and search listings. */
+export const GAVANA_CANVAS_GUIDE_SOURCES = Object.freeze([
+    Object.freeze({
+        id: "getting-started",
+        title: "Canvas Agent Workflow",
+        description: "The required inspect, guide, validate, edit, and review sequence for every canvas task.",
+        keywords: Object.freeze(["start","workflow","inspect","read","validate","edit","review","revision","idempotency"]),
+        order: 1,
+        markdown: "\n## Required sequence\n\n1. Identify one exact canvas handle. Never guess between candidates.\n2. Call `canvas_get` before reasoning about or changing an existing canvas.\n3. Read the guide topics relevant to the requested operation.\n4. Plan the smallest graph change that satisfies the request. Preserve unrelated nodes, connections, positions, metadata, and the user's current structure.\n5. Call `canvas_validate` with the proposed operations before a large, spatial, or destructive batch.\n6. Apply related changes atomically with `canvas_apply_batch`, the current `baseRevision`, and one caller-stable idempotency key.\n7. If a write returns revision conflict `409`, read the canvas again, preserve the newer user change, and retry the same intent. Reuse the same idempotency key only for the same payload.\n8. Call `canvas_validate` after editing. Report exact changed handles and unresolved warnings.\n\n## Non-negotiable safety\n\n- Building or preparing a workflow does not mean running it.\n- Never start image, video, Action, or Recipe generation unless the user explicitly requested that paid action in the current conversation.\n- Never automatically retry a failed paid action.\n- Never delete, disconnect, overwrite, or reorganize existing work unless the user explicitly requested that scope.\n- Generated media content is server-owned. Use generation or import tools; do not place bytes or arbitrary media URLs into node metadata.\n",
+    }),
+    Object.freeze({
+        id: "notes-text-sections",
+        title: "Notes, Text, and Sections",
+        description: "Choose the correct native canvas object for observations, durable copy, headings, and spatial groups.",
+        keywords: Object.freeze(["note","notes","sticky","text","heading","header","section","frame","content","annotation"]),
+        order: 2,
+        markdown: "\n## Object grammar\n\n- Sticky note: one short observation, idea, decision, question, or human annotation. Create a `sticky` node and put the readable value in `metadata.content`.\n- Text: a paragraph, prompt, brief, instruction, caption, or durable written output. Create a `text` node and put the body in `metadata.content`.\n- Section: a labeled spatial container and navigation landmark. Create a `text` node with `metadata.isSection: true`. Put the section title in `title`; keep `metadata.content` empty unless the user asked for a section description.\n- Heading: use the title of a real Section. Do not stretch an ordinary Text or Sticky node across the canvas to imitate a section header.\n\n## Section example\n\n```json\n{\n  \"type\": \"node.create\",\n  \"clientId\": \"research-section\",\n  \"node\": {\n    \"type\": \"text\",\n    \"title\": \"Customer objections\",\n    \"position\": { \"x\": 1200, \"y\": 200 },\n    \"width\": 1040,\n    \"height\": 720,\n    \"metadata\": { \"isSection\": true }\n  }\n}\n```\n\nPlace each child's complete frame inside the Section bounds; a centered but\noverflowing frame is not contained. A Section may overlap its children by\ndesign; ordinary nodes should not overlap one another. A child whose frame\ncrosses its Section boundary receives a `section_content_overflow` finding.\n\n## Stored membership\n\nMembership is stored: the server keeps `metadata.sectionId` on every node\nwhose complete frame fits inside a Section, recomputing it after each batch on\ncreate, move, resize, and delete. When Sections nest or overlap, the smallest\ncontaining Section wins. Do not set `sectionId` yourself — geometry is the\nsource of truth and caller-supplied values are corrected.\n",
+    }),
+    Object.freeze({
+        id: "sections-layout",
+        title: "Sections and Layout",
+        description: "Place native objects in readable groups without hiding or rearranging existing work.",
+        keywords: Object.freeze(["section","layout","position","overlap","spacing","grid","right","below","contain","navigation"]),
+        order: 3,
+        markdown: "\n## Layout rules\n\n- Treat the current canvas as user-owned. Preserve existing coordinates unless reorganization was explicitly requested.\n- For additions to an existing canvas, compute its visible bounding box and place the new Section to the right with at least 160 canvas units of outer spacing. If right-side placement would make the canvas excessively wide, place it below with the same spacing.\n- Use 48 units of inner Section padding, 32 units between sibling nodes, and at least 80 units between major stages.\n- Keep workflow direction consistent, normally left to right. Keep inputs before transformations and outputs after them.\n- Use compact rows or columns. Avoid extremely long, thin canvases that become unreadable at Fit Canvas.\n- For 2-8 generated image outputs, reserve each requested final aspect frame before work begins and pack the complete result cluster as a grid. The usual four-image photoshoot is a 2x2 grid; do not stack it as a tall output column that can overlap when images finalize.\n- Size Sections after their contents. Do not use Section overlap as a substitute for node placement.\n- Run `canvas_validate` before and after a multi-node layout change.\n\n## One task = one Section\n\nGroup each task's output in a titled Section sized to its contents plus 48\nunits of padding. Workflow creation and multi-output image generation wrap\ntheir clusters in a Section automatically (multi-output wrapping applies to\nautomatic placement; passing explicit target coordinates opts out and leaves\nplacement fully caller-controlled); do the same for hand-built\nclusters. Agent-created nodes left outside every Section raise an info-level\n`unsectioned_node` finding. Membership is stored server-side as\n`metadata.sectionId`, recomputed from complete-frame geometry after every\nbatch. Agent-created Sections receive an owned auto-fit contract; after a\ngenerated child changes size, Gavana refits only that still-owned Section to\nthe full child bounds plus 48 units. Do not use this as permission to move or\nresize a user-controlled Section.\n\nFor a newly proposed agent cluster, ordinary-node overlap and full-frame\nSection overflow are write-blocking errors. On an existing Canvas, historical\nuser-created overlap or overflow remains advisory so an unrelated scoped edit\ncan still proceed. Agent-owned task findings still block completion review\nuntil they are corrected.\n\n## Existing canvas rule\n\nWhen the user says \"add\", do not interpret it as \"reorganize\". New work should be distinguishable, spatially contained, and reversible without moving unrelated content.\n",
+    }),
+    Object.freeze({
+        id: "connections",
+        title: "Connections",
+        description: "Create directed, persistent relationships with valid endpoint semantics.",
+        keywords: Object.freeze(["connection","connect","edge","direction","input","output","reference","list","first-frame","last-frame","prompt"]),
+        order: 4,
+        markdown: "\n## Direction\n\nA connection goes from source to target. Use source input or instruction -> transformation or generator -> output. Never connect a node to itself, and never connect a Section as if it were a workflow step.\n\n## Modes\n\n- Omit `mode` for a normal dependency or transformation flow.\n- `prompt`: a text or sticky note whose content is the generation prompt for the target image node. One prompt connection per target; image generation reads the prompt from this node when the request omits a prompt.\n- `reference`: an image reference that guides another node.\n- `list`: a Prompt List or Image List flow.\n- `first-frame`: an image used as the first frame of a video node.\n- `last-frame`: an image used as the last frame of a video node.\n\nUse exact `node:` handles or batch-local `client:` references. Connections remain attached when nodes move. Avoid duplicate edges with the same source, target, and mode.\n\n## Batch-local example\n\n```json\n{\n  \"type\": \"connection.create\",\n  \"clientId\": \"brief-to-generator\",\n  \"from\": \"client:brief\",\n  \"to\": \"client:generator\"\n}\n```\n\nDo not rely on spatial proximity to imply a relationship. If a relationship matters to execution or later understanding, connect it.\n",
+    }),
+    Object.freeze({
+        id: "prompt-lists",
+        title: "Prompt Lists and Repeated Directions",
+        description: "Represent several editable creative directions as one native Prompt List with shared and row-specific references.",
+        keywords: Object.freeze(["prompt","list","directions","rows","referenceBindings","product","style","batch","generator"]),
+        order: 5,
+        markdown: "\n## Prompt List shape\n\nUse one `text` node with:\n\n- `metadata.isList: true`\n- `metadata.listType: \"prompt\"`\n- `metadata.listExecutionMode: \"batch\"` for separate outputs\n- one checked `metadata.listItems` entry per direction\n\nConnect a shared product image to the List once. Connect the List to one empty image generator. For a row-specific style, store the exact style image in that row's `referenceBindings` as `{ \"nodeId\": \"node:<id>\", \"role\": \"style\" }`. Do not copy a filename into prompt prose as a substitute for a binding.\n\nEvery product-variant row should explicitly say to preserve the exact connected product and not substitute it. Building the List and generator prepares the workflow only; it must not start generation.\n",
+    }),
+    Object.freeze({
+        id: "generated-assets",
+        title: "Generated Images, Videos, and Durable Outputs",
+        description: "Prepare media nodes, start only explicit generation, and preserve output lineage.",
+        keywords: Object.freeze(["generated","generation","image","video","output","asset","durable","lineage","placeholder","job"]),
+        order: 6,
+        markdown: "\n## Before generation\n\n- Read the destination canvas and relevant source nodes.\n- Use exact source `node:` or `asset:` handles.\n- For a standalone image request, pass every visual source in `references`.\n  Use `{ \"handle\": \"node:...\", \"role\": \"identity\" }` when its\n  responsibility is known; valid roles are `identity`, `construction`,\n  `texture`, `fit`, and `style`. Do not flatten multi-reference work\n  into prompt prose or omit a source during fallback.\n- Create an empty image or video target only through supported operations. Do not write media bytes, storage keys, or arbitrary output URLs into metadata.\n- Connect prompts, products, references, Lists, and frame inputs to their target with the correct direction and mode.\n\n## Paid execution\n\nGeneration is allowed only after explicit current-turn user intent. Start one run with one caller-stable idempotency key. Poll the returned Run or Job; do not start another run while waiting. A terminal failure must be reported without automatic retry.\n\n## Completion\n\nDo not claim a generated image is durable until the result returns a target `node:`, durable `asset:`, and the final canvas read shows server-owned media fields. A video Job may return a protected download without materializing a native video node; report exactly what the server returned and do not invent durability.\n\nKeep generated output spatially near its input stage and connected to its source, prompt, List, or workflow. After finalization, run `canvas_validate` and read `completionReview`: it reports overlap, full-frame Section containment, reference lineage, durable output count, and product-fidelity review state. Do not claim Done while it says `doneClaimAllowed: false`. Product-fidelity uncertainty requires human review; never create another paid provider call automatically.\n",
+    }),
+    Object.freeze({
+        id: "existing-canvases",
+        title: "Editing Existing Canvases Safely",
+        description: "Preserve user structure, concurrent edits, and unrelated content while making scoped changes.",
+        keywords: Object.freeze(["existing","preserve","concurrent","revision","conflict","409","idempotency","unrelated","delete","scope"]),
+        order: 7,
+        markdown: "\n## Preservation contract\n\n- Call `canvas_get` and retain the exact revision before planning a write.\n- Make the smallest requested delta. Do not move, resize, retitle, reconnect, delete, or rewrite an existing node outside the requested scope.\n- Prefer one atomic batch for related nodes and connections so a malformed operation leaves no partial graph.\n- Pass the read revision as `baseRevision`.\n- On `409`, read again and rebase the intended additions around the newer graph. Preserve the concurrent user change.\n- Reuse an idempotency key only for an identical intended payload. If the intended payload changes, use a new key.\n- Pass proposed delete operations to `canvas_validate` and report their node and connection impact before applying them.\n\nAn agent-authored addition should be removable without damaging surrounding user work. Exact returned handles are the audit trail.\n",
+    }),
+    Object.freeze({
+        id: "paid-action-safety",
+        title: "Paid Action Safety",
+        description: "Separate preparation from execution and prevent accidental or repeated provider charges.",
+        keywords: Object.freeze(["paid","credits","cost","generate","run","retry","failure","prepare","setup","explicit"]),
+        order: 8,
+        markdown: "\n## Intent boundary\n\n\"Build\", \"prepare\", \"set up\", \"connect\", \"draft\", and \"make ready\" authorize graph edits only. They do not authorize Recipe, image, video, or Action execution.\n\nStart paid work only when the current user message explicitly asks to run or generate it. Do not infer authorization from an older message, a node label, an unfinished placeholder, or nearby content.\n\n## Retry boundary\n\n- Use one stable idempotency key for one intended paid operation.\n- Poll the returned handle with status tools.\n- Never automatically retry a terminal failure, timeout, disconnect, or ambiguous provider response with a new key.\n- Ask for new user intent before any new paid attempt.\n\nDeterministic Actions may be described as credit-free only when `action_get` confirms that contract. Inspect an Action before running it.\n",
+    }),
+    Object.freeze({
+        id: "validation-recovery",
+        title: "Validation and Recovery",
+        description: "Interpret structural findings, correct invalid batches, and finish with an evidence-based review.",
+        keywords: Object.freeze(["validate","lint","overlap","orphan","header","connection","destructive","recovery","error","atomic","blocked","force"]),
+        order: 9,
+        markdown: "\n## Use `canvas_validate`\n\nCall it with only `canvasId` to audit the current graph. Pass the proposed `operations` to inspect the planned post-batch graph and destructive impact before writing.\n\nWarning- and info-level findings are advisory. Error-severity findings caused by the proposed agent write have teeth: `canvas_apply_batch` rejects that batch and writes nothing. Historical findings remain visible for review but do not turn an unrelated scoped write into a forced cleanup. Validation never mutates the canvas or consumes an idempotency key.\n\n`summary.passed` means there is no structural error. `summary.reviewRequired` is true when errors, warnings, or truncated findings still require agent or human review. `completionReview` is the finalization-ready structured view: it names overlap, containment, reference lineage, output count, and product-fidelity state. Never claim Done unless `completionReview.doneClaimAllowed` is true.\n\n## Blocked writes\n\nWhen a batch is rejected with error-severity findings:\n\n- Nothing was written and the idempotency key was not consumed — the same key retries the corrected batch of the same intent.\n- The rejection lists the blocking findings. Fix the listed operations, then confirm with `canvas_validate` using the same `operations` before applying again.\n- `force: true` applies the batch despite error findings. Use it only after validating, and only when the user explicitly accepts the listed findings — never as a routine retry shortcut.\n\n## Recovery\n\n- If an operation is rejected, the atomic batch makes no partial change.\n- Read the finding's exact handles and linked guide topic.\n- Correct unsupported object types, metadata, endpoint modes, positions, or references instead of guessing repeatedly.\n- Use a new idempotency key if the corrected payload represents a changed intent.\n- Read and validate again after a successful write.\n\nCommon findings include ordinary-node overlap, Section content overflow, generated output without an incoming relationship, text imitating a Section header, broken lineage handles, unclear media connections, and proposed deletions. Product-fidelity uncertainty is a review state, not authorization to regenerate.\n",
+    }),
+    Object.freeze({
+        id: "examples-common-mistakes",
+        title: "Examples and Common Mistakes",
+        description: "Compact patterns to copy and anti-patterns agents must avoid.",
+        keywords: Object.freeze(["example","examples","mistake","mistakes","anti-pattern","section","note","text","generated","connection"]),
+        order: 10,
+        markdown: "\n## Good patterns\n\n- Research cluster: one Section, several Sticky observations, one Text synthesis, and directed observation -> synthesis connections.\n- Creative workflow: source image -> Prompt List -> empty generator -> generated outputs.\n- Video workflow: first image -[first-frame]-> video target and optional last image -[last-frame]-> video target.\n- Existing-canvas addition: new contained Section outside the current bounds, with no existing-node mutations.\n\n## Common mistakes\n\n- Using long Text or Sticky nodes as fake headers instead of Sections.\n- Creating every node at `{ \"x\": 0, \"y\": 0 }` or stacking nodes on top of one another.\n- Leaving generated outputs disconnected from their prompt, List, source, or stage.\n- Connecting a Section to workflow nodes.\n- Treating nearby objects as implicit inputs without explicit handles or connections.\n- Copying a style image name into prompt text instead of using a row-level reference binding.\n- Writing generated media content directly into node metadata.\n- Reorganizing or deleting existing work when the user asked only to add something.\n- Starting generation when the user asked only to prepare a workflow.\n- Retrying a failed paid operation automatically.\n- Reporting a temporary Job or Run handle as a durable Canvas output.\n- Passing `force: true` to push a batch past error-severity findings instead of fixing the operations. Force is for explicit, user-approved exceptions only.\n",
+    }),
+]);