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

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

@@ -1,11 +1,31 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+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 { McpServerConfig } from "./McpServerConfig";
+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);
@@ -20,7 +40,9 @@ const written = (root: string) =>
   JSON.parse(readFileSync(McpServerConfig.file(root), "utf8")) as Record<string, object>;
 
 afterEach(() => {
-  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+  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", () => {
@@ -39,22 +61,41 @@ describe("MCP server config", () => {
     ]);
   });
 
+  /** 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 },
+      { 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"])).toEqual({
+    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"])).toEqual({
+    expect(McpServerConfig.add(root, "github", ["npx", "-y", "server-github"], "workspace")).toEqual({
       name: "github",
       transport: "stdio",
       command: "npx",
@@ -66,7 +107,7 @@ describe("MCP server config", () => {
   /** 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"]);
+    McpServerConfig.add(root, "b", ["b"], "workspace");
     const file = written(root);
     expect(Object.keys(file)).toEqual(["servers"]);
     expect(Object.keys(file.servers ?? {})).toEqual(["a", "b"]);
@@ -74,20 +115,20 @@ describe("MCP server config", () => {
 
   test("adding the same name twice replaces the entry rather than doubling it", () => {
     const root = workspace();
-    McpServerConfig.add(root, "a", ["old"]);
-    McpServerConfig.add(root, "a", ["new", "--flag"]);
+    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(true);
+    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", [])).toThrow();
+    expect(() => McpServerConfig.add(workspace(), "a", [], "workspace")).toThrow();
   });
 
   test("a malformed file costs its servers and is named rather than thrown", () => {
@@ -102,6 +143,59 @@ describe("MCP server config", () => {
     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",

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

package/executors.test.ts

@@ -727,7 +727,7 @@ describe("Workspace and app executor environment contracts", () => {
     });
   });
 
-  test("accepts metadata route exports during page key discovery", async () => {
+  test("accepts head route exports during page key discovery", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
     process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
@@ -737,24 +737,19 @@ describe("Workspace and app executor environment contracts", () => {
     await writeFile(path.join(root, "apps/demo/akan.config.ts"), "export default {};\n");
     await writeFile(
       path.join(root, "apps/demo/page/_layout.tsx"),
-      [
-        "export const head = null;",
-        "export const metadata = { title: 'Root' };",
-        "export default function Layout({ children }) { return children; }",
-        "",
-      ].join("\n"),
+      ["export const head = null;", "export default function Layout({ children }) { return children; }", ""].join("\n"),
     );
     await writeFile(
       path.join(root, "apps/demo/page/docs/_layout.tsx"),
       [
-        "export async function generateMetadata() { return { title: 'Docs' }; }",
+        "export async function generateHead() { return null; }",
         "export default function Layout({ children }) { return children; }",
         "",
       ].join("\n"),
     );
     await writeFile(
       path.join(root, "apps/demo/page/docs/intro.tsx"),
-      ["export const metadata = { title: 'Intro' };", "export default function Page() { return null; }", ""].join("\n"),
+      ["export const head = null;", "export default function Page() { return null; }", ""].join("\n"),
     );
 
     const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
@@ -767,7 +762,7 @@ describe("Workspace and app executor environment contracts", () => {
     ]);
   });
 
-  test("rejects conflicting metadata route exports during page key discovery", async () => {
+  test("rejects a metadata route export during page key discovery", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
     process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
@@ -776,47 +771,16 @@ describe("Workspace and app executor environment contracts", () => {
     await mkdir(path.join(root, "apps/demo/page"), { recursive: true });
     await writeFile(path.join(root, "apps/demo/akan.config.ts"), "export default {};\n");
     await writeFile(
-      path.join(root, "apps/demo/page/conflict.tsx"),
-      [
-        "export const metadata = { title: 'Conflict' };",
-        "export function generateMetadata() { return { title: 'Conflict' }; }",
-        "export default function Page() { return null; }",
-        "",
-      ].join("\n"),
+      path.join(root, "apps/demo/page/legacy.tsx"),
+      ["export const metadata = { title: 'Legacy' };", "export default function Page() { return null; }", ""].join(
+        "\n",
+      ),
     );
 
     const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
     const app = AppExecutor.from(workspace, "demo");
 
-    await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(
-      "metadata and generateMetadata cannot both be exported",
-    );
-  });
-
-  test("rejects mixed head and metadata route export channels during page key discovery", async () => {
-    const root = await makeTempRoot();
-    process.env.AKAN_PUBLIC_REPO_NAME = "repo";
-    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
-    process.env.AKAN_PUBLIC_ENV = "local";
-    await writeJson(path.join(root, "package.json"), rootPackageJson());
-    await mkdir(path.join(root, "apps/demo/page"), { recursive: true });
-    await writeFile(path.join(root, "apps/demo/akan.config.ts"), "export default {};\n");
-    await writeFile(
-      path.join(root, "apps/demo/page/mixed.tsx"),
-      [
-        "export const head = null;",
-        "export const metadata = { title: 'Mixed' };",
-        "export default function Page() { return null; }",
-        "",
-      ].join("\n"),
-    );
-
-    const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
-    const app = AppExecutor.from(workspace, "demo");
-
-    await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(
-      "head/generateHead and metadata/generateMetadata cannot both be exported",
-    );
+    await expect(app.getPageKeys({ refresh: true })).rejects.toThrow('unsupported export "metadata"');
   });
 
   test("assigns start command ports from sorted app order", async () => {

package/index.ts

@@ -32,7 +32,6 @@ export type * from "./fileSys";
 export type * from "./frontendBuild";
 export type * from "./getDirname";
 export type * from "./getRelatedCnsts";
-export type * from "./guideline";
 export type * from "./incrementalBuilder";
 export type * from "./mobile";
 export type * from "./packageExportsMap";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-beta.17",
+  "version": "3.0.0-beta.18",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -48,7 +48,7 @@
     "@inquirer/prompts": "^8.4.3",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-beta.17",
+    "akanjs": "3.0.0-beta.18",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",