@akanjs/devkit 3.0.0-beta.16 → 3.0.0-beta.18

package/codeAgent/tools/askToolPack.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, test } from "bun:test";
+import { type CodeAgentProfile, type CodeAgentQuestion, codeAgentPresets } from "akanjs/common";
+import { AskToolPack } from "./AskToolPack";
+
+interface RegisteredTool {
+  name: string;
+  description: string;
+  execute: (
+    id: string,
+    params: { questions?: unknown[] },
+  ) => Promise<{ content: { text?: string }[]; isError?: boolean }>;
+}
+
+/** Runs the pack's extension and hands back the one tool it registered, plus the questions it went on to ask. */
+const mount = (
+  profile: CodeAgentProfile,
+  answer: (question: Omit<CodeAgentQuestion, "questionId">) => string | undefined,
+) => {
+  const asked: Omit<CodeAgentQuestion, "questionId">[] = [];
+  const pack = new AskToolPack({
+    profile,
+    ask: async (question) => {
+      asked.push(question);
+      return answer(question);
+    },
+  });
+  const tools: RegisteredTool[] = [];
+  const extension = pack.extension();
+  if (extension && "factory" in extension)
+    extension.factory({ registerTool: (spec: RegisteredTool) => tools.push(spec) } as never);
+  return { pack, tool: tools[0], asked };
+};
+
+const local = codeAgentPresets.local("/repo");
+const pod = codeAgentPresets.pod("/repo");
+
+const one = (patch: Record<string, unknown> = {}) => ({
+  question: "Which database?",
+  options: [{ label: "Postgres" }, { label: "SQLite", recommended: true }],
+  ...patch,
+});
+
+describe("ask_user", () => {
+  test("it is published only where somebody can answer", () => {
+    expect(mount(local, () => "x").pack.names()).toEqual(["ask_user"]);
+    // A pod and a sub-agent both set `canPrompt` false; the tool is never constructed there.
+    expect(mount(pod, () => "x").pack.names()).toEqual([]);
+    expect(mount(pod, () => "x").tool).toBeUndefined();
+  });
+
+  test("a question reaches the wire with its options, and the answer comes back as the label", async () => {
+    const { tool, asked } = mount(local, () => "SQLite");
+    const result = await tool?.execute("t", { questions: [one()] });
+    expect(asked[0]).toMatchObject({
+      prompt: "Which database?",
+      kind: "select",
+      options: [
+        { key: "0", label: "Postgres" },
+        { key: "1", label: "SQLite", recommended: true },
+      ],
+    });
+    expect(result?.content[0]?.text).toContain("→ SQLite");
+  });
+
+  test("a header is folded into the prompt, because the wire carries one line", async () => {
+    const { tool, asked } = mount(local, () => "a");
+    await tool?.execute("t", { questions: [one({ header: "Storage" })] });
+    expect(asked[0]?.prompt).toBe("Storage — Which database?");
+  });
+
+  test("several questions are asked in order, one at a time", async () => {
+    const { tool, asked } = mount(local, (question) => (question.prompt.includes("database") ? "SQLite" : "Yes"));
+    const result = await tool?.execute("t", {
+      questions: [one(), { question: "Run migrations now?", options: [{ label: "Yes" }, { label: "No" }] }],
+    });
+    expect(asked.map((entry) => entry.prompt)).toEqual(["Which database?", "Run migrations now?"]);
+    expect(result?.content[0]?.text).toContain("Which database?\n→ SQLite");
+    expect(result?.content[0]?.text).toContain("Run migrations now?\n→ Yes");
+  });
+
+  test("more questions than fit on a screen are cut rather than drawn over the transcript", async () => {
+    const { tool, asked } = mount(local, () => "a");
+    await tool?.execute("t", { questions: Array.from({ length: 7 }, (_, at) => one({ question: `Q${at}?` })) });
+    expect(asked).toHaveLength(AskToolPack.maxQuestions);
+  });
+
+  /** A blank answer reads to a model as "the user wanted nothing", which is the one thing a skip never means. */
+  test("a skipped question says so, and says what to do about it", async () => {
+    const { tool } = mount(local, () => undefined);
+    const result = await tool?.execute("t", { questions: [one()] });
+    expect(result?.content[0]?.text).toContain("skipped");
+    expect(result?.content[0]?.text).toContain("decide this yourself");
+  });
+
+  test("free text is offered unless the model turns it off", async () => {
+    const { tool, asked } = mount(local, () => "a");
+    await tool?.execute("t", { questions: [one(), one({ freeText: false })] });
+    expect(asked[0]?.freeText).toBe(true);
+    expect(asked[1]?.freeText).toBe(false);
+  });
+
+  test("a question with no options asks for prose", async () => {
+    const { tool, asked } = mount(local, () => "because of the index");
+    await tool?.execute("t", { questions: [{ question: "Why is it slow?" }] });
+    expect(asked[0]?.kind).toBe("text");
+    expect(asked[0]?.options).toBeUndefined();
+  });
+
+  test("multi-select travels as itself", async () => {
+    const { tool, asked } = mount(local, () => "a, b");
+    await tool?.execute("t", { questions: [one({ multiSelect: true })] });
+    expect(asked[0]?.multiSelect).toBe(true);
+  });
+
+  test("asking nothing is a mistake, not an empty answer", async () => {
+    const { tool } = mount(local, () => "a");
+    expect((await tool?.execute("t", { questions: [] }))?.isError).toBe(true);
+  });
+});

package/codeAgent/tools/mcpOAuth.test.ts

@@ -0,0 +1,320 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import type { CodeAgentMcpServerRef } from "akanjs/common";
+import { McpOAuth } from "./McpOAuth";
+import { McpSignIn } from "./McpSignIn";
+import { McpTokenStore } from "./McpTokenStore";
+import { McpToolPack } from "./McpToolPack";
+
+/**
+ * One process playing the whole other side: an MCP resource server, its RFC 9728 metadata, the authorization
+ * server named by it, dynamic client registration, and the token endpoint.
+ *
+ * Built as a real server rather than as stubbed fetches because what is being tested is a wire contract — the
+ * challenge header, the well-known paths, the PKCE round trip — and a stub can only ever assert the shape this
+ * code already believes in.
+ */
+class FakeProvider {
+  readonly server: ReturnType<typeof Bun.serve>;
+  readonly issued: string[] = [];
+  readonly registrations: { redirect_uris?: string[] }[] = [];
+  /** code -> the challenge it was issued against, which the token endpoint checks the verifier against. */
+  readonly #codes = new Map<string, { challenge: string; resource: string | null }>();
+  #next = 0;
+  /** Set to refuse S256, which a client must treat as "do not send a code" rather than downgrade. */
+  methods: string[] = ["S256"];
+  registerable = true;
+  refreshable = true;
+
+  constructor() {
+    this.server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: (request) => this.#route(request) });
+  }
+
+  get origin() {
+    return `http://127.0.0.1:${this.server.port}`;
+  }
+
+  get mcpUrl() {
+    return `${this.origin}/mcp`;
+  }
+
+  close() {
+    this.server.stop(true);
+  }
+
+  async #route(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname === "/mcp") return await this.#mcp(request);
+    if (url.pathname === "/.well-known/oauth-protected-resource/mcp")
+      return Response.json({ resource: this.mcpUrl, authorization_servers: [this.origin], scopes_supported: ["read"] });
+    if (url.pathname === "/.well-known/oauth-authorization-server")
+      return Response.json({
+        issuer: this.origin,
+        authorization_endpoint: `${this.origin}/authorize`,
+        token_endpoint: `${this.origin}/token`,
+        ...(this.registerable ? { registration_endpoint: `${this.origin}/register` } : {}),
+        code_challenge_methods_supported: this.methods,
+      });
+    if (url.pathname === "/register") return await this.#register(request);
+    if (url.pathname === "/authorize") return this.#authorize(url);
+    if (url.pathname === "/token") return await this.#token(request);
+    return new Response("not found", { status: 404 });
+  }
+
+  async #mcp(request: Request) {
+    const token = request.headers.get("authorization")?.replace(/^Bearer /, "");
+    if (!token || !this.issued.includes(token))
+      return Response.json(
+        { error_description: "Authentication is required to use this MCP server." },
+        {
+          status: 401,
+          headers: {
+            "WWW-Authenticate": `Bearer resource_metadata="${this.origin}/.well-known/oauth-protected-resource/mcp"`,
+          },
+        },
+      );
+    const body = (await request.json()) as { id?: number; method?: string };
+    if (body.method === "initialize")
+      return Response.json({ jsonrpc: "2.0", id: body.id, result: { protocolVersion: "2025-06-18" } });
+    if (body.method === "tools/list")
+      return Response.json({
+        jsonrpc: "2.0",
+        id: body.id,
+        result: {
+          tools: [{ name: "search", description: "search it", inputSchema: { type: "object", properties: {} } }],
+        },
+      });
+    return Response.json({ jsonrpc: "2.0", id: body.id, result: {} });
+  }
+
+  async #register(request: Request) {
+    const body = (await request.json()) as { redirect_uris?: string[] };
+    this.registrations.push(body);
+    this.#next += 1;
+    return Response.json({ client_id: `client-${this.#next}`, redirect_uris: body.redirect_uris });
+  }
+
+  /** Stands in for the consent screen: it redirects straight back, which is what a browser would end up doing. */
+  #authorize(url: URL) {
+    const redirect = url.searchParams.get("redirect_uri") ?? "";
+    const challenge = url.searchParams.get("code_challenge") ?? "";
+    const code = `code-${this.#codes.size + 1}`;
+    this.#codes.set(code, { challenge, resource: url.searchParams.get("resource") });
+    const back = new URL(redirect);
+    back.searchParams.set("code", code);
+    back.searchParams.set("state", url.searchParams.get("state") ?? "");
+    back.searchParams.set("iss", this.origin);
+    return Response.redirect(back.href, 302);
+  }
+
+  async #token(request: Request) {
+    const form = new URLSearchParams(await request.text());
+    if (form.get("grant_type") === "refresh_token") {
+      if (!this.refreshable) return Response.json({ error: "invalid_grant" }, { status: 400 });
+      const access = `access-refreshed-${this.issued.length + 1}`;
+      this.issued.push(access);
+      return Response.json({ access_token: access, refresh_token: "refresh-2", expires_in: 3600 });
+    }
+    const issued = this.#codes.get(form.get("code") ?? "");
+    if (!issued) return Response.json({ error: "invalid_grant" }, { status: 400 });
+    const verifier = form.get("code_verifier") ?? "";
+    if (createHash("sha256").update(verifier).digest("base64url") !== issued.challenge)
+      return Response.json({ error: "invalid_grant" }, { status: 400 });
+    const access = `access-${this.issued.length + 1}`;
+    this.issued.push(access);
+    return Response.json({ access_token: access, refresh_token: "refresh-1", expires_in: 3600, scope: "read" });
+  }
+}
+
+let provider: FakeProvider;
+let home: string;
+let realHome: string | undefined;
+
+const refOf = (patch: Partial<CodeAgentMcpServerRef> = {}): CodeAgentMcpServerRef => ({
+  name: "fake",
+  transport: "http",
+  url: provider.mcpUrl,
+  ...patch,
+});
+
+/** A browser, reduced to what the flow needs of one: visit the url and follow where it points. */
+const browser = (url: string) => void fetch(url).catch(() => undefined);
+
+/**
+ * The credential directory is moved off the real home for the whole file.
+ *
+ * Through `AKAN_CODE_HOME` rather than `HOME`: Bun resolves `os.homedir()` once and caches it, so `HOME`
+ * written after anything in the import graph has read it changes nothing — and a test that quietly fell back
+ * would write its tokens into the developer's own `~/.akan/code`.
+ */
+beforeAll(() => {
+  realHome = process.env.AKAN_CODE_HOME;
+  home = mkdtempSync(path.join(tmpdir(), "akan-mcpauth-"));
+  process.env.AKAN_CODE_HOME = home;
+  expect(McpTokenStore.file().startsWith(home)).toBe(true);
+});
+
+afterAll(() => {
+  if (realHome === undefined) delete process.env.AKAN_CODE_HOME;
+  else process.env.AKAN_CODE_HOME = realHome;
+  rmSync(home, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  provider = new FakeProvider();
+  rmSync(McpTokenStore.file(), { force: true });
+});
+
+afterEach(() => {
+  provider.close();
+});
+
+describe("MCP OAuth discovery", () => {
+  test("the challenge names the metadata, and it is preferred over any url we could derive", () => {
+    expect(
+      McpOAuth.resourceMetadataUrls("https://x.dev/mcp", 'Bearer resource_metadata="https://x.dev/custom"'),
+    ).toEqual(["https://x.dev/custom"]);
+  });
+
+  test("with no challenge, both spellings of the well-known url are tried", () => {
+    expect(McpOAuth.resourceMetadataUrls("https://x.dev/mcp")).toEqual([
+      "https://x.dev/.well-known/oauth-protected-resource/mcp",
+      "https://x.dev/.well-known/oauth-protected-resource",
+    ]);
+  });
+
+  test("the issuer's path is inserted after the suffix, as RFC 8414 requires", () => {
+    expect(McpOAuth.serverMetadataUrls("https://x.dev/tenant/a")).toEqual([
+      "https://x.dev/.well-known/oauth-authorization-server/tenant/a",
+      "https://x.dev/tenant/a/.well-known/openid-configuration",
+      "https://x.dev/.well-known/oauth-authorization-server",
+    ]);
+  });
+
+  test("everything the flow needs is found from the server url alone", async () => {
+    const server = await McpOAuth.discover(provider.mcpUrl, await McpSignIn.challenge(refOf()));
+    expect(server).toMatchObject({
+      issuer: provider.origin,
+      authorizationEndpoint: `${provider.origin}/authorize`,
+      tokenEndpoint: `${provider.origin}/token`,
+      registrationEndpoint: `${provider.origin}/register`,
+      resource: provider.mcpUrl,
+      resourceScopes: ["read"],
+    });
+  });
+
+  /** OAuth 2.1 drops `plain`; a downgrade here is one a network attacker would pick on the client's behalf. */
+  test("a server that will not do S256 is refused rather than downgraded", async () => {
+    provider.methods = ["plain"];
+    await expect(McpOAuth.discover(provider.mcpUrl)).rejects.toThrow(/S256/);
+  });
+
+  test("a server that wants no credential answers no challenge", async () => {
+    const open = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: () => Response.json({ jsonrpc: "2.0", id: 0 }) });
+    try {
+      expect(await McpSignIn.challenge(refOf({ url: `http://127.0.0.1:${open.port}/mcp` }))).toBeNull();
+    } finally {
+      open.stop(true);
+    }
+  });
+});
+
+describe("MCP sign-in", () => {
+  test("a browser round trip ends with a token this session can connect with", async () => {
+    const auth = await McpSignIn.run(refOf(), { open: browser });
+    expect(auth.accessToken).toBe("access-1");
+    expect(auth.issuer).toBe(provider.origin);
+    expect(auth.resource).toBe(provider.mcpUrl);
+    // The client was registered on demand, against the loopback the flow actually bound.
+    expect(provider.registrations).toHaveLength(1);
+    expect(provider.registrations[0]?.redirect_uris?.[0]).toBe(auth.redirectUri);
+    expect(McpTokenStore.read("fake")?.accessToken).toBe("access-1");
+  });
+
+  test("the token is what makes the server publish its tools", async () => {
+    const before = await McpToolPack.connect({
+      workspaceRoot: home,
+      profile: { name: "t", tools: { mcp: [refOf()] } } as never,
+    });
+    expect(before?.status[0]).toMatchObject({ auth: "required", tools: [] });
+    await McpSignIn.run(refOf(), { open: browser });
+    const after = await McpToolPack.connect({
+      workspaceRoot: home,
+      profile: { name: "t", tools: { mcp: [refOf()] } } as never,
+    });
+    try {
+      expect(after?.status[0]).toMatchObject({ auth: "authorized" });
+      expect(after?.toolNames).toEqual(["mcp__fake__search"]);
+    } finally {
+      after?.close();
+      before?.close();
+    }
+  });
+
+  test("a second sign-in reuses the client it already registered", async () => {
+    await McpSignIn.run(refOf(), { open: browser });
+    await McpSignIn.run(refOf(), { open: browser });
+    expect(provider.registrations).toHaveLength(1);
+  });
+
+  test("an expired token is refreshed without anybody being asked", async () => {
+    const auth = await McpSignIn.run(refOf(), { open: browser });
+    McpTokenStore.write("fake", { ...auth, expiresAt: Date.now() - 1 });
+    expect(await McpSignIn.token(refOf())).toBe("access-refreshed-2");
+    // The rotated refresh token replaced the spent one, or the next refresh would be refused.
+    expect(McpTokenStore.read("fake")?.refreshToken).toBe("refresh-2");
+  });
+
+  test("a refresh the server refuses reports no token rather than throwing", async () => {
+    const auth = await McpSignIn.run(refOf(), { open: browser });
+    McpTokenStore.write("fake", { ...auth, expiresAt: Date.now() - 1 });
+    provider.refreshable = false;
+    const notices: string[] = [];
+    expect(await McpSignIn.token(refOf(), (message) => notices.push(message))).toBeUndefined();
+    expect(notices.join(" ")).toContain("fake");
+  });
+
+  test("a provider that registers no clients says what to declare instead", async () => {
+    provider.registerable = false;
+    await expect(McpSignIn.run(refOf(), { open: browser })).rejects.toThrow(/clientId/);
+  });
+
+  test("a declared client id is used instead of registering one", async () => {
+    const auth = await McpSignIn.run(refOf({ oauth: { clientId: "mine" } }), { open: browser });
+    expect(auth.clientId).toBe("mine");
+    expect(provider.registrations).toHaveLength(0);
+  });
+
+  test("a stdio server is told its credential goes in env", async () => {
+    await expect(McpSignIn.run({ name: "s", transport: "stdio", command: "x" }, { open: browser })).rejects.toThrow(
+      /env/,
+    );
+  });
+
+  test("signing out forgets the token and leaves nothing behind", async () => {
+    await McpSignIn.run(refOf(), { open: browser });
+    expect(McpTokenStore.clear("fake")).toBe(true);
+    expect(McpTokenStore.read("fake")).toBeUndefined();
+    expect(McpTokenStore.clear("fake")).toBe(false);
+  });
+});
+
+describe("the token file", () => {
+  test("it is readable only by its owner, and lives outside the workspace", async () => {
+    await McpSignIn.run(refOf(), { open: browser });
+    const file = McpTokenStore.file();
+    expect(file.startsWith(home)).toBe(true);
+    expect(await Bun.file(file).exists()).toBe(true);
+    expect(statSync(file).mode & 0o777).toBe(0o600);
+  });
+
+  test("a corrupt file costs the sign-ins and not the session", async () => {
+    await McpSignIn.run(refOf(), { open: browser });
+    await Bun.write(McpTokenStore.file(), "{ not json");
+    expect(McpTokenStore.read("fake")).toBeUndefined();
+    expect(McpTokenStore.names()).toEqual([]);
+  });
+});

package/codeAgent/tools/mcpServerConfig.test.ts

@@ -0,0 +1,205 @@
+import { afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { akanCodePaths } from "../agent/akanCodePaths";
+import { McpServerConfig, type McpServerScope } from "./McpServerConfig";
+
+const roots: string[] = [];
+
+/**
+ * The home half of the config, moved somewhere disposable.
+ *
+ * Without it every `add` in this file writes into whoever runs it — `~/.akan/code/mcp.json` is now a real
+ * default, and a test that declares `github` would declare it for their every session.
+ */
+beforeAll(() => {
+  const home = mkdtempSync(path.join(tmpdir(), "akan-home-"));
+  roots.push(home);
+  process.env.AKAN_CODE_HOME = home;
+  expect(akanCodePaths.globalMcpFile().startsWith(home)).toBe(true);
+});
+
+const globalFile = (file: string) => {
+  const target = akanCodePaths.globalMcpFile();
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, file);
+};
+
+const workspace = (file?: string) => {
+  const root = mkdtempSync(path.join(tmpdir(), "akan-mcp-"));
+  roots.push(root);
+  if (file === undefined) return root;
+  const target = McpServerConfig.file(root);
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, file);
+  return root;
+};
+
+const written = (root: string) =>
+  JSON.parse(readFileSync(McpServerConfig.file(root), "utf8")) as Record<string, object>;
+
+afterEach(() => {
+  rmSync(akanCodePaths.globalMcpFile(), { force: true });
+  for (const root of roots.slice(1)) rmSync(root, { recursive: true, force: true });
+  roots.splice(1);
+});
+
+describe("MCP server config", () => {
+  test("an editor's own block is read as it is written", () => {
+    const root = workspace(
+      JSON.stringify({
+        mcpServers: {
+          github: { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
+          linear: { url: "https://mcp.linear.app/sse" },
+        },
+      }),
+    );
+    expect(McpServerConfig.read(root)).toEqual([
+      { name: "github", transport: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
+      { name: "linear", transport: "http", url: "https://mcp.linear.app/sse" },
+    ]);
+  });
+
+  /** Both are what a server that discovery cannot finish for is reached with, so the file has to carry them. */
+  test("a static token and a hand-issued oauth client travel from the file", () => {
+    const root = workspace(
+      JSON.stringify({
+        mcpServers: {
+          sentry: {
+            url: "https://mcp.sentry.dev/mcp",
+            headers: { "x-api-key": "from-the-file" },
+            oauth: { clientId: "abc", scope: "project:read" },
+          },
+        },
+      }),
+    );
+    expect(McpServerConfig.read(root)[0]).toMatchObject({
+      headers: { "x-api-key": "from-the-file" },
+      oauth: { clientId: "abc", scope: "project:read" },
+    });
+  });
+
+  test("a disabled server is declared but never connected", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { off: { command: "x", disabled: true } } }));
+    expect(McpServerConfig.read(root)).toEqual([]);
+    expect(McpServerConfig.declared(root)).toEqual([
+      { ref: { name: "off", transport: "stdio", command: "x" }, disabled: true, scope: "workspace" },
+    ]);
+  });
+
+  test("a url is an http server and anything else is a command with its argv", () => {
+    const root = workspace();
+    expect(McpServerConfig.add(root, "linear", ["https://mcp.linear.app/sse"], "workspace")).toEqual({
+      name: "linear",
+      transport: "http",
+      url: "https://mcp.linear.app/sse",
+    });
+    expect(McpServerConfig.add(root, "github", ["npx", "-y", "server-github"], "workspace")).toEqual({
+      name: "github",
+      transport: "stdio",
+      command: "npx",
+      args: ["-y", "server-github"],
+    });
+    expect(Object.keys(written(root).mcpServers ?? {})).toEqual(["linear", "github"]);
+  });
+
+  /** The file is shared with whatever editor wrote it, so the key it already uses is the key a write goes into. */
+  test("a VS Code file keeps its own spelling through a write", () => {
+    const root = workspace(JSON.stringify({ servers: { a: { command: "a" } } }));
+    McpServerConfig.add(root, "b", ["b"], "workspace");
+    const file = written(root);
+    expect(Object.keys(file)).toEqual(["servers"]);
+    expect(Object.keys(file.servers ?? {})).toEqual(["a", "b"]);
+  });
+
+  test("adding the same name twice replaces the entry rather than doubling it", () => {
+    const root = workspace();
+    McpServerConfig.add(root, "a", ["old"], "workspace");
+    McpServerConfig.add(root, "a", ["new", "--flag"], "workspace");
+    expect(McpServerConfig.read(root)).toEqual([{ name: "a", transport: "stdio", command: "new", args: ["--flag"] }]);
+  });
+
+  test("removing says whether it removed anything", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { a: { command: "a" } } }));
+    expect(McpServerConfig.remove(root, "nope")).toBe(false);
+    expect(McpServerConfig.remove(root, "a")).toBe("workspace");
+    expect(McpServerConfig.read(root)).toEqual([]);
+  });
+
+  test("a server with nothing to reach it by is refused", () => {
+    expect(() => McpServerConfig.add(workspace(), "a", [], "workspace")).toThrow();
+  });
+
+  test("a malformed file costs its servers and is named rather than thrown", () => {
+    const root = workspace("{ not json");
+    expect(McpServerConfig.read(root)).toEqual([]);
+    expect(McpServerConfig.problem(root)).toContain("not valid JSON");
+  });
+
+  test("no file at all is not a problem", () => {
+    const root = workspace();
+    expect(McpServerConfig.read(root)).toEqual([]);
+    expect(McpServerConfig.problem(root)).toBeUndefined();
+  });
+
+  /**
+   * The whole point of the home file: one declaration, every checkout.
+   *
+   * A server is an integration with an account and its token already lives in the home directory, so making
+   * the declaration per repo means declaring and signing in again in each one.
+   */
+  test("a server declared in the home file is read from a workspace that declares nothing", () => {
+    globalFile(JSON.stringify({ mcpServers: { office: { url: "https://office.example/mcp" } } }));
+    const root = workspace();
+    expect(McpServerConfig.read(root)).toEqual([
+      { name: "office", transport: "http", url: "https://office.example/mcp" },
+    ]);
+    expect(McpServerConfig.declared(root)[0]?.scope).toBe("global");
+  });
+
+  test("both files are merged, and the workspace wins the name they share", () => {
+    globalFile(JSON.stringify({ mcpServers: { office: { url: "https://home/mcp" }, shared: { command: "home" } } }));
+    const root = workspace(JSON.stringify({ mcpServers: { shared: { command: "repo" } } }));
+    expect(McpServerConfig.declared(root).map((entry) => [entry.ref.name, entry.scope])).toEqual([
+      ["office", "global"],
+      ["shared", "workspace"],
+    ]);
+    expect(McpServerConfig.read(root).find((ref) => ref.name === "shared")?.command).toBe("repo");
+  });
+
+  test("a write goes to the scope it was asked for, and leaves the other file alone", () => {
+    const root = workspace();
+    McpServerConfig.add(root, "office", ["https://office.example/mcp"]);
+    expect(McpServerConfig.declared(root)).toEqual([
+      {
+        ref: { name: "office", transport: "http", url: "https://office.example/mcp" },
+        disabled: false,
+        scope: "global",
+      },
+    ]);
+    expect(existsSync(McpServerConfig.file(root, "workspace"))).toBe(false);
+  });
+
+  test("removing finds the file the server is actually in", () => {
+    globalFile(JSON.stringify({ mcpServers: { office: { command: "x" } } }));
+    const root = workspace(JSON.stringify({ mcpServers: { repobot: { command: "y" } } }));
+    expect(McpServerConfig.remove(root, "office")).toBe("global");
+    expect(McpServerConfig.remove(root, "repobot")).toBe("workspace");
+    expect(McpServerConfig.read(root)).toEqual([]);
+  });
+
+  test("a scope is what a caller names, never guessed from the shape", () => {
+    const root = workspace();
+    const scopes: McpServerScope[] = ["global", "workspace"];
+    for (const scope of scopes) McpServerConfig.add(root, `in-${scope}`, ["x"], scope);
+    expect(McpServerConfig.declared(root).map((entry) => entry.scope)).toEqual(["global", "workspace"]);
+  });
+
+  test("a server reads back as the one line it is reached at", () => {
+    expect(McpServerConfig.targetOf({ name: "a", transport: "stdio", command: "npx", args: ["-y", "x"] })).toBe(
+      "npx -y x",
+    );
+    expect(McpServerConfig.targetOf({ name: "a", transport: "http", url: "https://x" })).toBe("https://x");
+  });
+});

package/commandDecorators/command.ts

@@ -71,6 +71,8 @@ const handleOption = (programCommand: Command, argMeta: ArgMeta) => {
     `-${flag}, --${kebabName}${type === "boolean" ? " [boolean]" : ` <${kebabName}>`}`,
     `${desc}${ask ? ` (${ask})` : ""}${example ? ` (example: ${example})` : ""}${choices ? ` (choices: ${choices.map((choice) => choice.name).join(", ")})` : ""}`,
   );
+  if (type === "boolean" && argMeta.argsOption.default === true)
+    programCommand.option(`--no-${kebabName}`, `turn off --${kebabName}`);
   return programCommand;
 };
 const handleArgument = (programCommand: Command, argMeta: ArgMeta) => {

package/commandDecorators/commandDecorators.test.ts

@@ -125,7 +125,7 @@ describe("command helper metadata", () => {
 
     const commandHelp = stripAnsi(formatCommandHelp(HelpCommand, "buildApp"));
     expect(commandHelp).toContain("akan build-app [app]");
-    expect(commandHelp).toContain("--write");
+    expect(commandHelp).toContain("--write, --no-write");
     expect(commandHelp).toContain("[default: true]");
     expect(commandHelp).toContain("Fast, Full");
   });

package/commandDecorators/helpFormatter.ts

@@ -217,7 +217,8 @@ export const formatCommandHelp = (command: CommandCls, key: string) => {
       const opt = arg.argsOption;
       const flag = opt.flag ? `-${opt.flag}, ` : "";
       const kebabName = camelToKebabCase(arg.name);
-      const optName = `${flag}--${kebabName}`;
+      const negation = opt.type === "boolean" && opt.default === true ? `, --no-${kebabName}` : "";
+      const optName = `${flag}--${kebabName}${negation}`;
       const optDesc = opt.desc ?? "";
       const defaultVal = opt.default !== undefined ? chalk.gray(` [default: ${String(opt.default)}]`) : "";
       const choices = opt.enum