argsbarg 4.0.3 → 4.1.0

package/src/config/file.test.ts

@@ -1,10 +1,16 @@
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type { CliProgram } from "../types.ts";
 import { bootstrapAppConfig } from "./bootstrap.ts";
-import { readAppConfigFile, resolveAppConfigPath, writeAppConfigFile } from "./file.ts";
+import {
+  readAppConfigFile,
+  resolveAppConfigDir,
+  resolveAppConfigPath,
+  uninstallAppConfig,
+  writeAppConfigFile,
+} from "./file.ts";
 import { buildProgramUserConfig } from "./manifest.ts";
 import { formatMissingConfigMessage, missingRequiredConfig, resolveAppConfig } from "./resolve.ts";
 
@@ -13,7 +19,6 @@ const program: CliProgram = {
   version: "1.0.0",
   description: "Demo.",
   appConfig: {
-    path: "~/.config/myapp-test/config",
     entries: {
       apiToken: { description: "Token.", env: "API_TOKEN" },
       port: { description: "HTTP listen port (default 8080).", required: false },
@@ -22,6 +27,19 @@ const program: CliProgram = {
   handler: () => {},
 };
 
+function withHome<T>(fn: (home: string) => T): T {
+  const home = mkdtempSync(join(tmpdir(), "cfg-test-"));
+  const prevHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    return fn(home);
+  } finally {
+    if (prevHome === undefined) delete process.env.HOME;
+    else process.env.HOME = prevHome;
+    rmSync(home, { recursive: true, force: true });
+  }
+}
+
 describe("config/file", () => {
   test("buildProgramUserConfig from program.appConfig env entries", () => {
     const cfg = buildProgramUserConfig(program);
@@ -33,31 +51,29 @@ describe("config/file", () => {
     expect(cfg?.port).toBeUndefined();
   });
 
+  test("resolveAppConfigPath uses config.json", () => {
+    withHome((home) => {
+      expect(resolveAppConfigPath(program)).toBe(
+        join(home, ".local", "lib", "myapp", "config.json"),
+      );
+    });
+  });
+
   test("resolveAppConfig prefers host env over file", () => {
-    const dir = mkdtempSync(join(tmpdir(), "cfg-test-"));
-    const prevHome = process.env.HOME;
-    process.env.HOME = dir;
-    const prevToken = process.env.API_TOKEN;
-    process.env.API_TOKEN = "from-host";
-    try {
-      const p: CliProgram = {
-        ...program,
-        appConfig: {
-          ...program.appConfig!,
-          path: join(dir, ".config", "myapp-test", "config"),
-        },
-      };
-      mkdirSync(join(dir, ".config", "myapp-test"), { recursive: true });
-      writeFileSync(resolveAppConfigPath(p), `${JSON.stringify({ apiToken: "from-file" })}\n`);
-      const resolved = resolveAppConfig(p, { apiToken: "from-file" });
-      expect(resolved.apiToken).toBe("from-host");
-    } finally {
-      if (prevHome === undefined) delete process.env.HOME;
-      else process.env.HOME = prevHome;
-      if (prevToken === undefined) delete process.env.API_TOKEN;
-      else process.env.API_TOKEN = prevToken;
-      rmSync(dir, { recursive: true, force: true });
-    }
+    withHome((_home) => {
+      const prevToken = process.env.API_TOKEN;
+      process.env.API_TOKEN = "from-host";
+      try {
+        const configPath = resolveAppConfigPath(program);
+        mkdirSync(dirname(configPath), { recursive: true });
+        writeFileSync(configPath, `${JSON.stringify({ apiToken: "from-file" })}\n`);
+        const resolved = resolveAppConfig(program, { apiToken: "from-file" });
+        expect(resolved.apiToken).toBe("from-host");
+      } finally {
+        if (prevToken === undefined) delete process.env.API_TOKEN;
+        else process.env.API_TOKEN = prevToken;
+      }
+    });
   });
 
   test("missingRequiredConfig and formatMissingConfigMessage", () => {
@@ -76,37 +92,31 @@ describe("config/file", () => {
   });
 
   test("rejects unknown keys on read", () => {
-    const dir = mkdtempSync(join(tmpdir(), "cfg-test-"));
-    try {
-      const p: CliProgram = {
-        ...program,
-        appConfig: {
-          ...program.appConfig!,
-          path: join(dir, "config"),
-        },
-      };
-      writeFileSync(join(dir, "config"), `${JSON.stringify({ extra: true })}\n`);
-      expect(() => readAppConfigFile(p)).toThrow(/Unknown config key/);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
+    withHome(() => {
+      const configPath = resolveAppConfigPath(program);
+      mkdirSync(dirname(configPath), { recursive: true });
+      writeFileSync(configPath, `${JSON.stringify({ extra: true })}\n`);
+      expect(() => readAppConfigFile(program)).toThrow(/Unknown config key/);
+    });
   });
 
   test("writeAppConfigFile round-trip", () => {
-    const dir = mkdtempSync(join(tmpdir(), "cfg-test-"));
-    try {
-      const p: CliProgram = {
-        ...program,
-        appConfig: {
-          ...program.appConfig!,
-          path: join(dir, "config"),
-        },
-      };
-      writeAppConfigFile(p, { apiToken: "saved" });
-      const { resolved } = bootstrapAppConfig(p, { validateFile: true });
+    withHome(() => {
+      writeAppConfigFile(program, { apiToken: "saved" });
+      const { resolved } = bootstrapAppConfig(program, { validateFile: true });
       expect(resolved.apiToken).toBe("saved");
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
+    });
+  });
+
+  test("uninstallAppConfig removes config directory recursively", () => {
+    withHome(() => {
+      writeAppConfigFile(program, { apiToken: "saved" });
+      const configPath = resolveAppConfigPath(program);
+      const configDir = resolveAppConfigDir(program);
+      writeFileSync(join(configDir, "extra.txt"), "leftover", "utf8");
+      expect(uninstallAppConfig(program, false)).toEqual([configPath, `${configDir}/`]);
+      expect(existsSync(configPath)).toBe(false);
+      expect(existsSync(configDir)).toBe(false);
+    });
   });
 });

package/src/config/file.ts

@@ -2,24 +2,20 @@
 JSON app config file path helpers and strict read/write.
 */
 
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { sanitizeToolSegment } from "../mcp/tools.ts";
-import { appConfigHome, expandTilde } from "../paths/host.ts";
+import { appConfigLibHome, displayHomePath } from "../paths/host.ts";
 import type { CliProgram } from "../types.ts";
 import { effectiveJsonSchema } from "./schema.ts";
 import { validateConfigDocument } from "./validate.ts";
 
 export type AppConfigFileData = Record<string, unknown>;
 
-/** Resolved absolute path to the app JSON config file. */
+/** Resolved absolute path to the app JSON config file (`~/.local/lib/<key>/config.json`). */
 export function resolveAppConfigPath(program: CliProgram): string {
-  const custom = program.appConfig?.path;
-  if (custom) {
-    return expandTilde(custom);
-  }
   const dirName = sanitizeToolSegment(program.key);
-  return join(appConfigHome(), dirName, "config");
+  return join(appConfigLibHome(), dirName, "config.json");
 }
 
 /** Resolved absolute directory containing the app JSON config file. */
@@ -27,14 +23,9 @@ export function resolveAppConfigDir(program: CliProgram): string {
   return dirname(resolveAppConfigPath(program));
 }
 
-/** Human-readable config path for error messages (`~` when under home). */
+/** Human-readable config path for error messages (`~/…` when under home). */
 export function displayAppConfigPath(program: CliProgram): string {
-  const resolved = resolveAppConfigPath(program);
-  const home = process.env.HOME ?? "";
-  if (home.length > 0 && resolved.startsWith(home)) {
-    return `~${resolved.slice(home.length)}`;
-  }
-  return resolved;
+  return displayHomePath(resolveAppConfigPath(program));
 }
 
 function parseConfigJson(text: string, path: string): AppConfigFileData {
@@ -46,7 +37,7 @@ function parseConfigJson(text: string, path: string): AppConfigFileData {
     return parsed as AppConfigFileData;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`Invalid JSON in config file ${path}: ${msg}`);
+    throw new Error(`Invalid JSON in config file ${displayHomePath(path)}: ${msg}`);
   }
 }
 
@@ -60,7 +51,7 @@ export function readAppConfigFileRaw(path: string): AppConfigFileData {
     text = readFileSync(path, "utf8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`Could not read config file ${path}: ${msg}`);
+    throw new Error(`Could not read config file ${displayHomePath(path)}: ${msg}`);
   }
   return parseConfigJson(text, path);
 }
@@ -89,7 +80,7 @@ export function validateAppConfigData(
   const allowed = new Set(Object.keys(appConfig.entries));
   for (const key of Object.keys(data)) {
     if (!allowed.has(key)) {
-      const where = pathLabel ?? "config";
+      const where = pathLabel ? displayHomePath(pathLabel) : "config";
       throw new Error(`Unknown config key '${key}' in ${where}`);
     }
   }
@@ -99,7 +90,7 @@ export function validateAppConfigData(
   }
   const result = validateConfigDocument(data, jsonSchema);
   if (!result.valid) {
-    const where = pathLabel ?? "config";
+    const where = pathLabel ? displayHomePath(pathLabel) : "config";
     throw new Error(`Invalid config in ${where}: ${result.errors.join("; ")}`);
   }
 }
@@ -112,14 +103,31 @@ export function writeAppConfigFile(program: CliProgram, data: AppConfigFileData)
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
 }
 
-/** Removes the app config file when present. Returns true if removed. */
-export function uninstallAppConfig(program: CliProgram, dry: boolean): boolean {
+/** True when the app config file or config directory is present. */
+export function appConfigInstalled(program: CliProgram): boolean {
   const path = resolveAppConfigPath(program);
-  if (!existsSync(path)) {
-    return false;
+  if (existsSync(path)) return true;
+  return existsSync(resolveAppConfigDir(program));
+}
+
+/** Removes the app config file and config directory when present. */
+export function uninstallAppConfig(program: CliProgram, dry: boolean): string[] {
+  const path = resolveAppConfigPath(program);
+  const dir = resolveAppConfigDir(program);
+  const hasFile = existsSync(path);
+  const hasDir = existsSync(dir);
+
+  if (!hasFile && !hasDir) {
+    return [];
   }
+
+  const changed: string[] = [];
+  if (hasFile) changed.push(path);
+  if (hasDir) changed.push(`${dir}/`);
+
   if (!dry) {
-    unlinkSync(path);
+    if (hasFile) unlinkSync(path);
+    if (hasDir) rmSync(dir, { recursive: true, force: true });
   }
-  return true;
+  return changed;
 }

package/src/config/resolve.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import type { CliProgram } from "../types.ts";
-import { resolveAppConfig } from "./resolve.ts";
+import { captureMappedHostEnv, exportConfigToEnv, resolveAppConfig } from "./resolve.ts";
 
 const program: CliProgram = {
   key: "app",
@@ -85,4 +85,28 @@ describe("config/resolve", () => {
     const resolved = resolveAppConfig(stringProgram, {});
     expect(resolved.greeting).toBe("world");
   });
+
+  test("prefers captured host env over file when process.env was exported from file", () => {
+    const hostEnv = { API_TOKEN: "from-host" };
+    process.env.API_TOKEN = "from-file-export";
+    try {
+      const resolved = resolveAppConfig(program, { apiToken: "from-file" }, hostEnv);
+      expect(resolved.apiToken).toBe("from-host");
+    } finally {
+      delete process.env.API_TOKEN;
+    }
+  });
+
+  test("exportConfigToEnv does not overwrite host env", () => {
+    const prev = process.env.API_TOKEN;
+    process.env.API_TOKEN = "from-host";
+    const hostEnv = captureMappedHostEnv(program);
+    try {
+      exportConfigToEnv(program, { apiToken: "from-file" }, hostEnv);
+      expect(process.env.API_TOKEN).toBe("from-host");
+    } finally {
+      if (prev === undefined) delete process.env.API_TOKEN;
+      else process.env.API_TOKEN = prev;
+    }
+  });
 });

package/src/config/resolve.ts

@@ -20,8 +20,26 @@ function isPresent(value: unknown): boolean {
   return true;
 }
 
-function envOverrideValue(envName: string): string | undefined {
-  const val = process.env[envName];
+/** Snapshot mapped host env at bootstrap entry (before file exports mutate process.env). */
+export function captureMappedHostEnv(program: CliProgram): Record<string, string | undefined> {
+  const out: Record<string, string | undefined> = {};
+  const entries = program.appConfig?.entries;
+  if (!entries) {
+    return out;
+  }
+  for (const entry of Object.values(entries)) {
+    if (entry.env) {
+      out[entry.env] = process.env[entry.env];
+    }
+  }
+  return out;
+}
+
+function envOverrideValue(
+  envName: string,
+  hostEnv?: Record<string, string | undefined>,
+): string | undefined {
+  const val = hostEnv && envName in hostEnv ? hostEnv[envName] : process.env[envName];
   if (val === undefined || val.length === 0) {
     return undefined;
   }
@@ -55,15 +73,19 @@ function coerceEnvValue(program: CliProgram, key: string, raw: string): unknown
   return raw;
 }
 
-/** Resolve all schema keys from file data and process.env. */
-export function resolveAppConfig(program: CliProgram, fileData: AppConfigFileData): ResolvedConfig {
+/** Resolve all schema keys from file data and mapped host env (env wins over file). */
+export function resolveAppConfig(
+  program: CliProgram,
+  fileData: AppConfigFileData,
+  hostEnv?: Record<string, string | undefined>,
+): ResolvedConfig {
   const appConfig = program.appConfig;
   if (!appConfig) {
     return {};
   }
   const out: ResolvedConfig = {};
   for (const [key, entry] of Object.entries(appConfig.entries)) {
-    const value = resolveConfigKey(program, key, entry, fileData);
+    const value = resolveConfigKey(program, key, entry, fileData, hostEnv);
     if (value !== undefined) {
       out[key] = value;
     }
@@ -76,9 +98,10 @@ function resolveConfigKey(
   key: string,
   entry: CliAppConfigEntry,
   fileData: AppConfigFileData,
+  hostEnv?: Record<string, string | undefined>,
 ): unknown {
   if (entry.env) {
-    const fromEnv = envOverrideValue(entry.env);
+    const fromEnv = envOverrideValue(entry.env, hostEnv);
     if (fromEnv !== undefined) {
       return coerceEnvValue(program, key, fromEnv);
     }
@@ -93,8 +116,12 @@ function resolveConfigKey(
   return undefined;
 }
 
-/** Write mapped config values to process.env for subprocess inheritance. */
-export function exportConfigToEnv(program: CliProgram, resolved: ResolvedConfig): void {
+/** Write mapped config values to process.env for subprocess inheritance (never overwrites host env). */
+export function exportConfigToEnv(
+  program: CliProgram,
+  resolved: ResolvedConfig,
+  hostEnv?: Record<string, string | undefined>,
+): void {
   const appConfig = program.appConfig;
   if (!appConfig) {
     return;
@@ -103,6 +130,14 @@ export function exportConfigToEnv(program: CliProgram, resolved: ResolvedConfig)
     if (!entry.env) {
       continue;
     }
+    const captured = hostEnv?.[entry.env];
+    if (captured !== undefined && captured.length > 0) {
+      continue;
+    }
+    const existing = process.env[entry.env];
+    if (existing !== undefined && existing.length > 0) {
+      continue;
+    }
     const value = resolved[key];
     if (!isPresent(value)) {
       continue;

package/src/config.integration.test.ts

@@ -3,16 +3,17 @@ App config bootstrap and MCP config enforcement regressions.
 */
 
 import { expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { bootstrapAppConfig } from "./config/bootstrap.ts";
+import { resolveAppConfigPath } from "./config/file.ts";
 import { mcpRequest, testProgram } from "./test-fixtures.ts";
 
 test("bootstrapAppConfig prefers host env over config file", () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-env-"));
-  const configFile = join(dir, "config");
-  writeFileSync(configFile, `${JSON.stringify({ foo: "fromfile", bar: "bar" })}\n`, "utf8");
+  const prevHome = process.env.HOME;
+  process.env.HOME = dir;
   process.env.FOO = "original";
   try {
     const p = testProgram({
@@ -20,7 +21,6 @@ test("bootstrapAppConfig prefers host env over config file", () => {
       version: "0",
       description: "",
       appConfig: {
-        path: configFile,
         entries: {
           foo: { description: "x", env: "FOO" },
           bar: { description: "y", env: "BAR" },
@@ -28,10 +28,15 @@ test("bootstrapAppConfig prefers host env over config file", () => {
       },
       handler: () => {},
     });
+    const configFile = resolveAppConfigPath(p);
+    mkdirSync(dirname(configFile), { recursive: true });
+    writeFileSync(configFile, `${JSON.stringify({ foo: "fromfile", bar: "bar" })}\n`, "utf8");
     bootstrapAppConfig(p, { validateFile: true });
     expect(process.env.FOO).toBe("original");
     expect(process.env.BAR).toBe("bar");
   } finally {
+    if (prevHome === undefined) delete process.env.HOME;
+    else process.env.HOME = prevHome;
     delete process.env.FOO;
     delete process.env.BAR;
     rmSync(dir, { recursive: true, force: true });
@@ -74,7 +79,8 @@ test("MCP program.appConfig succeeds when env present", async () => {
 
 test("MCP config file loads and exports vars for tool handlers", async () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-mcp-"));
-  const configFile = join(dir, "config");
+  const configFile = join(dir, ".local", "lib", "mcp_test", "config");
+  mkdirSync(dirname(configFile), { recursive: true });
   writeFileSync(
     configFile,
     `${JSON.stringify({ argsTestSecret: "file-value" }, null, 2)}\n`,
@@ -91,17 +97,19 @@ test("MCP config file loads and exports vars for tool handlers", async () => {
     ],
     {
       script: "examples/mcp-test.ts",
-      env: { ARGS_TEST_CONFIG_FILE: configFile, ARGS_TEST_SECRET: "present" },
+      env: { HOME: dir, ARGS_TEST_SECRET: "present" },
     },
   );
   const res = responses.get(15) as { result: { isError: boolean; content: { text: string }[] } };
   expect(res.result.isError).toBe(false);
   expect(res.result.content[0]?.text.trim()).toBe("present");
+  rmSync(dir, { recursive: true, force: true });
 });
 
 test("Cli.run docs api skips required appConfig exit", async () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-docs-skip-"));
-  const configFile = join(dir, "config");
+  const configFile = join(dir, ".local", "lib", "docs_skip_test", "config");
+  mkdirSync(dirname(configFile), { recursive: true });
   writeFileSync(configFile, "{}\n");
   const entry = join(import.meta.dir, "index.ts");
   const mainPath = join(dir, "run-docs.ts");
@@ -114,7 +122,6 @@ const program = {
   description: "test",
   docs: { enabled: true, topics: { readme: { text: "# readme\\n" } } },
   appConfig: {
-    path: ${JSON.stringify(configFile)},
     entries: { token: { description: "Token.", env: "DOCS_SKIP_RUN_TOKEN" } },
   },
   handler: () => {},
@@ -122,7 +129,7 @@ const program = {
 await new Cli(program).run(process.argv.slice(2));
 `,
   );
-  const env = { ...process.env };
+  const env = { ...process.env, HOME: dir } as Record<string, string | undefined>;
   delete env.DOCS_SKIP_RUN_TOKEN;
   try {
     const proc = Bun.spawn(["bun", "run", mainPath, "docs", "api"], {

package/src/docs/api-guide.test.ts

@@ -71,7 +71,7 @@ test("generateApiGuide resolves program key in install notes", () => {
   };
   const md = generateApiGuide(fixture);
   expect(md).not.toContain("{argsbarg:program}");
-  expect(md).toContain("myapp install --all --yes");
+  expect(md).toContain("myapp install --yes");
   expect(md).not.toContain("Upgrade to latest release");
 });
 

package/src/docs/docs.test.ts

@@ -217,7 +217,7 @@ test("generateMcpGuide includes schema URI and install targets", () => {
   expect(guide).toContain("claude_desktop_config.json");
   expect(guide).toContain("## Installation");
   expect(guide).toContain("## Running directly");
-  expect(guide).toContain("install --bin");
+  expect(guide).toContain("install --app");
   expect(guide).toContain("OpenAI Codex");
   expect(guide).toContain("ChatGPT");
 });

package/src/docs/mcp-guide.ts

@@ -10,6 +10,8 @@ import {
 } from "../mcp/tools.ts";
 import { collectOptionDefs } from "../parse.ts";
 import { CliOptionKind, type CliProgram } from "../types.ts";
+import { resolveDocsTopicResourceUri } from "./mcp-resources.ts";
+import { docsEnabled, docsUserTopicKeys } from "./resolve.ts";
 
 /** Extra host notes for generated `docs mcp` (manual fallbacks and ChatGPT Connectors). */
 function appendManualHostSetup(lines: string[], root: CliProgram, serverId: string): void {
@@ -109,7 +111,7 @@ export function generateMcpGuide(root: CliProgram): string {
 
   if (caps.install) {
     lines.push(
-      `Install the CLI first so \`${root.key}\` is on your PATH (e.g. \`${root.key} install --bin --yes\` or \`install --all --yes\`). Host configs reference the binary by name.`,
+      `Install the CLI first so \`${root.key}\` is on your PATH (e.g. \`${root.key} install --app --yes\` or \`install --all --yes\`). Host configs reference the app by name.`,
       "",
     );
   } else {
@@ -210,10 +212,19 @@ export function generateMcpGuide(root: CliProgram): string {
     "| `tools/list` | Callable tools for exposed leaf commands |",
     "| `tools/call` | Runs handlers headlessly; JSON stdout becomes `structuredContent` when valid |",
     `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} docs schema\` |`,
-    "",
-    "## Exposed tools",
-    "",
   );
+  if (docsEnabled(root)) {
+    const docs = root.docs;
+    if (docs) {
+      for (const key of docsUserTopicKeys(docs)) {
+        const uri = resolveDocsTopicResourceUri(root, key);
+        lines.push(
+          `| Docs topic \`${key}\` | \`${uri}\` — same markdown as \`${root.key} docs ${key}\` |`,
+        );
+      }
+    }
+  }
+  lines.push("", "## Exposed tools", "");
 
   if (tools.length === 0) {
     lines.push("(No MCP tools exposed.)", "");

package/src/docs/mcp-resources.test.ts

@@ -0,0 +1,63 @@
+import { expect, test } from "bun:test";
+import type { CliProgram } from "../types.ts";
+import {
+  defaultDocsTopicResourceUri,
+  docsMcpResources,
+  reservedDocsTopicResourceUris,
+  resolveDocsTopicResourceUri,
+} from "./mcp-resources.ts";
+
+function fixture(opts?: { docs?: boolean; mcp?: boolean }): CliProgram {
+  const docs = opts?.docs !== false;
+  const mcp = opts?.mcp !== false;
+  return {
+    key: "my-app",
+    version: "1.0.0",
+    description: "Test.",
+    ...(docs
+      ? {
+          docs: {
+            enabled: true,
+            topics: {
+              readme: { text: "# Readme\n", description: "User guide." },
+              arch: { text: "# Arch\n" },
+            },
+          },
+        }
+      : {}),
+    ...(mcp ? { mcpServer: { enabled: true } } : {}),
+    handler: () => {},
+  };
+}
+
+test("defaultDocsTopicResourceUri", () => {
+  expect(defaultDocsTopicResourceUri("my_app", "readme")).toBe("my_app://docs/readme");
+});
+
+test("resolveDocsTopicResourceUri sanitizes program key", () => {
+  expect(resolveDocsTopicResourceUri(fixture(), "readme")).toBe("my_app://docs/readme");
+});
+
+test("docsMcpResources when docs and MCP enabled", () => {
+  const resources = docsMcpResources(fixture());
+  expect(resources.map((r) => r.uri)).toEqual(["my_app://docs/readme", "my_app://docs/arch"]);
+  expect(resources[0]?.name).toBe("readme");
+  expect(resources[0]?.mimeType).toBe("text/markdown");
+  expect(resources[0]?.description).toBe("User guide.");
+  expect(resources[0]?.load()).toBe("# Readme\n");
+});
+
+test("docsMcpResources empty when docs disabled", () => {
+  expect(docsMcpResources(fixture({ docs: false }))).toEqual([]);
+});
+
+test("docsMcpResources empty when MCP disabled", () => {
+  expect(docsMcpResources(fixture({ mcp: false }))).toEqual([]);
+});
+
+test("reservedDocsTopicResourceUris matches docsMcpResources URIs", () => {
+  const program = fixture();
+  expect(reservedDocsTopicResourceUris(program)).toEqual(
+    docsMcpResources(program).map((r) => r.uri),
+  );
+});