argsbarg 5.1.8 → 5.1.10

package/src/config/file.test.ts

@@ -7,13 +7,17 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import type { CliProgram } from "../types.ts";
+import { CONFIG_BINDINGS_KEY } from "./bindings.ts";
 import { bootstrapAppConfig } from "./bootstrap.ts";
 import {
+  appConfigFileExists,
+  ensureAppConfigFile,
   readAppConfigFile,
   resolveAppConfigDir,
   resolveAppConfigPath,
   uninstallAppConfig,
   writeAppConfigFile,
+  writeAppConfigFileRaw,
 } from "./file.ts";
 import { buildProgramUserConfig } from "./manifest.ts";
 import { formatMissingConfigMessage, missingRequiredConfig, resolveAppConfig } from "./resolve.ts";
@@ -58,9 +62,7 @@ describe("config/file", () => {
 
   test("resolveAppConfigPath uses config.json", () => {
     withHome((home) => {
-      expect(resolveAppConfigPath(program)).toBe(
-        join(home, ".local", "lib", "myapp", "config.json"),
-      );
+      expect(resolveAppConfigPath(program)).toBe(join(home, ".local", "lib", "myapp", "config.json"));
     });
   });
 
@@ -126,4 +128,45 @@ describe("config/file", () => {
       expect(existsSync(configDir)).toBe(false);
     });
   });
+
+  test("ensureAppConfigFile creates empty config", () => {
+    withHome(() => {
+      const created = ensureAppConfigFile(program);
+      expect(created).toBe(resolveAppConfigPath(program));
+      expect(appConfigFileExists(program)).toBe(true);
+      expect(readAppConfigFile(program)).toEqual({});
+    });
+  });
+
+  test("ensureAppConfigFile no-op when file exists", () => {
+    withHome(() => {
+      writeAppConfigFileRaw(program, { apiToken: "x" });
+      expect(ensureAppConfigFile(program)).toBeNull();
+    });
+  });
+
+  test("read allows _bindings framework key", () => {
+    withHome(() => {
+      writeAppConfigFileRaw(program, {
+        [CONFIG_BINDINGS_KEY]: { apiToken: "env" },
+      });
+      expect(readAppConfigFile(program)).toEqual({
+        [CONFIG_BINDINGS_KEY]: { apiToken: "env" },
+      });
+    });
+  });
+
+  test("partial write allows bindings without required keys", () => {
+    withHome(() => {
+      writeAppConfigFile(program, { [CONFIG_BINDINGS_KEY]: { apiToken: "env" } }, { partial: true });
+      expect(readAppConfigFile(program)[CONFIG_BINDINGS_KEY]).toEqual({ apiToken: "env" });
+    });
+  });
+
+  test("appConfigFileExists false when only directory exists", () => {
+    withHome(() => {
+      mkdirSync(resolveAppConfigDir(program), { recursive: true });
+      expect(appConfigFileExists(program)).toBe(false);
+    });
+  });
 });

package/src/config/file.ts

@@ -7,8 +7,9 @@ import { dirname, join } from "node:path";
 import { sanitizeToolSegment } from "../mcp/tools.ts";
 import { appConfigLibHome, displayHomePath } from "../paths/host.ts";
 import type { CliProgram } from "../types.ts";
+import { isFrameworkConfigKey, validateBindingsShape } from "./bindings.ts";
 import { effectiveJsonSchema } from "./schema.ts";
-import { validateConfigDocument } from "./validate.ts";
+import { validateConfigDocument, validateConfigDocumentPartial } from "./validate.ts";
 
 export type AppConfigFileData = Record<string, unknown>;
 
@@ -56,15 +57,13 @@ export function readAppConfigFileRaw(path: string): AppConfigFileData {
   return parseConfigJson(text, path);
 }
 
-/** Read and validate config file against program schema. */
-export function readAppConfigFile(program: CliProgram): AppConfigFileData {
-  const path = resolveAppConfigPath(program);
-  const data = readAppConfigFileRaw(path);
-  if (Object.keys(data).length === 0) {
-    return data;
-  }
-  validateAppConfigData(program, data, path);
-  return data;
+function isEmptyConfigDocument(data: AppConfigFileData): boolean {
+  return Object.keys(data).every((k) => isFrameworkConfigKey(k));
+}
+
+/** True when `config.json` exists on disk. */
+export function appConfigFileExists(program: CliProgram): boolean {
+  return existsSync(resolveAppConfigPath(program));
 }
 
 /** Validate in-memory config data; throws on failure. */
@@ -72,15 +71,21 @@ export function validateAppConfigData(
   program: CliProgram,
   data: AppConfigFileData,
   pathLabel?: string,
+  opts: { partial?: boolean } = {},
 ): void {
   const appConfig = program.appConfig;
   if (!appConfig) {
     throw new Error("program.appConfig is not set");
   }
+  const where = pathLabel ? displayHomePath(pathLabel) : "config";
+  const bindingErrors = validateBindingsShape(data);
+  if (bindingErrors.length > 0) {
+    throw new Error(`Invalid config in ${where}: ${bindingErrors.join("; ")}`);
+  }
   const allowed = new Set(Object.keys(appConfig.entries));
   for (const key of Object.keys(data)) {
+    if (isFrameworkConfigKey(key)) continue;
     if (!allowed.has(key)) {
-      const where = pathLabel ? displayHomePath(pathLabel) : "config";
       throw new Error(`Unknown config key '${key}' in ${where}`);
     }
   }
@@ -88,26 +93,61 @@ export function validateAppConfigData(
   if (!jsonSchema) {
     return;
   }
+  if (opts.partial || isEmptyConfigDocument(data)) {
+    const result = validateConfigDocumentPartial(data, jsonSchema);
+    if (!result.valid) {
+      throw new Error(`Invalid config in ${where}: ${result.errors.join("; ")}`);
+    }
+    return;
+  }
   const result = validateConfigDocument(data, jsonSchema);
   if (!result.valid) {
-    const where = pathLabel ? displayHomePath(pathLabel) : "config";
     throw new Error(`Invalid config in ${where}: ${result.errors.join("; ")}`);
   }
 }
 
-/** Merge-write schema keys to the config file (`0o600`). */
-export function writeAppConfigFile(program: CliProgram, data: AppConfigFileData): void {
-  validateAppConfigData(program, data, displayAppConfigPath(program));
+/** Write JSON to the config path without schema validation (`0o600`). */
+export function writeAppConfigFileRaw(program: CliProgram, data: AppConfigFileData, dry = false): void {
   const path = resolveAppConfigPath(program);
+  if (dry) return;
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
 }
 
-/** True when the app config file or config directory is present. */
-export function appConfigInstalled(program: CliProgram): boolean {
+/** Create `config.json` as `{}` when missing; returns absolute path if created. */
+export function ensureAppConfigFile(program: CliProgram, dry = false): string | null {
+  const path = resolveAppConfigPath(program);
+  if (existsSync(path)) {
+    return null;
+  }
+  writeAppConfigFileRaw(program, {}, dry);
+  return path;
+}
+
+/** Read and validate config file against program schema. */
+export function readAppConfigFile(program: CliProgram): AppConfigFileData {
   const path = resolveAppConfigPath(program);
-  if (existsSync(path)) return true;
-  return existsSync(resolveAppConfigDir(program));
+  const data = readAppConfigFileRaw(path);
+  if (isEmptyConfigDocument(data)) {
+    return data;
+  }
+  validateAppConfigData(program, data, path);
+  return data;
+}
+
+/** Merge-write schema keys to the config file (`0o600`). */
+export function writeAppConfigFile(
+  program: CliProgram,
+  data: AppConfigFileData,
+  opts: { partial?: boolean } = {},
+): void {
+  validateAppConfigData(program, data, displayAppConfigPath(program), opts);
+  writeAppConfigFileRaw(program, data);
+}
+
+/** True when the app config file is present. */
+export function appConfigInstalled(program: CliProgram): boolean {
+  return appConfigFileExists(program);
 }
 
 /** Removes the app config file and config directory when present. */

package/src/config/resolve.ts

@@ -35,10 +35,7 @@ export function captureMappedHostEnv(program: CliProgram): Record<string, string
   return out;
 }
 
-function envOverrideValue(
-  envName: string,
-  hostEnv?: Record<string, string | undefined>,
-): string | undefined {
+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;

package/src/config/schema.ts

@@ -6,9 +6,7 @@ import type { CliAppConfigEntry, CliProgram } from "../types.ts";
 import { configEntryRequired, jsonSchemaRequiredKeys } from "./entry.ts";
 
 /** Synthesize a draft-07 object schema with string properties from metadata entries. */
-export function synthesizeAllStringSchema(
-  schema: Record<string, CliAppConfigEntry>,
-): Record<string, unknown> {
+export function synthesizeAllStringSchema(schema: Record<string, CliAppConfigEntry>): Record<string, unknown> {
   const properties: Record<string, unknown> = {};
   const required: string[] = [];
   for (const [key, entry] of Object.entries(schema)) {

package/src/config/validate.test.ts

@@ -24,10 +24,7 @@ const rootSchema = {
 /** Tests for config/validate. */
 describe("config/validate", () => {
   test("accepts valid document", () => {
-    const result = validateConfigDocument(
-      { apiToken: "x", maxRetries: 3, prefs: { ttl: 3600 } },
-      rootSchema,
-    );
+    const result = validateConfigDocument({ apiToken: "x", maxRetries: 3, prefs: { ttl: 3600 } }, rootSchema);
     expect(result.valid).toBe(true);
     expect(result.errors).toEqual([]);
   });
@@ -39,10 +36,7 @@ describe("config/validate", () => {
   });
 
   test("rejects unknown property when additionalProperties is false", () => {
-    const result = validateConfigDocument(
-      { apiToken: "x", maxRetries: 1, extra: true },
-      rootSchema,
-    );
+    const result = validateConfigDocument({ apiToken: "x", maxRetries: 1, extra: true }, rootSchema);
     expect(result.valid).toBe(false);
     expect(result.errors.some((e) => e.includes("extra"))).toBe(true);
   });
@@ -58,9 +52,7 @@ describe("config/validate", () => {
   });
 
   test("parseConfigSetValue requires --json for objects", () => {
-    expect(() => parseConfigSetValue("ttl:1", { type: "object" }, rootSchema, false)).toThrow(
-      /--json/,
-    );
+    expect(() => parseConfigSetValue("ttl:1", { type: "object" }, rootSchema, false)).toThrow(/--json/);
     expect(parseConfigSetValue('{"ttl":1}', { type: "object" }, rootSchema, true)).toEqual({
       ttl: 1,
     });

package/src/config/validate.ts

@@ -4,6 +4,7 @@ Aligned with common ts-json-schema-generator output (local $ref, objects, scalar
 */
 
 import { parseCommaList, parseDate, parseDateTime } from "../formats.ts";
+import { isFrameworkConfigKey } from "./bindings.ts";
 
 type JsonSchema = Record<string, unknown>;
 
@@ -21,7 +22,14 @@ export interface ValidateResult {
 /** Validate `data` against a JSON Schema root. Returns human-readable error messages. */
 export function validateConfigDocument(data: unknown, rootSchema: JsonSchema): ValidateResult {
   const errors: string[] = [];
-  validateValue(data, rootSchema, rootSchema, "$", errors);
+  validateValue(data, rootSchema, rootSchema, "$", errors, false);
+  return { valid: errors.length === 0, errors };
+}
+
+/** Validate present keys only — skips root `required` checks (partial writes / bootstrap). */
+export function validateConfigDocumentPartial(data: unknown, rootSchema: JsonSchema): ValidateResult {
+  const errors: string[] = [];
+  validateValue(data, rootSchema, rootSchema, "$", errors, true);
   return { valid: errors.length === 0, errors };
 }
 
@@ -31,6 +39,7 @@ function validateValue(
   root: JsonSchema,
   path: string,
   errors: string[],
+  partial: boolean,
 ): void {
   const resolved = resolveSchema(schema, root);
   if (!resolved) {
@@ -59,7 +68,7 @@ function validateValue(
         continue;
       }
       const branchErrs: string[] = [];
-      validateValue(value, branch as JsonSchema, root, path, branchErrs);
+      validateValue(value, branch as JsonSchema, root, path, branchErrs, partial);
       if (branchErrs.length === 0) {
         return;
       }
@@ -93,10 +102,10 @@ function validateValue(
     errors.push(`${path}: must be null`);
   }
   if (types.includes("object") || (types.length === 0 && isPlainObject(value))) {
-    validateObject(value, resolved, root, path, errors);
+    validateObject(value, resolved, root, path, errors, partial);
   }
   if (types.includes("array") || (types.length === 0 && Array.isArray(value))) {
-    validateArray(value, resolved, root, path, errors);
+    validateArray(value, resolved, root, path, errors, partial);
   }
 }
 
@@ -165,13 +174,7 @@ function validateString(value: unknown, schema: JsonSchema, path: string, errors
   }
 }
 
-function validateNumber(
-  value: unknown,
-  schema: JsonSchema,
-  path: string,
-  errors: string[],
-  integer: boolean,
-): void {
+function validateNumber(value: unknown, schema: JsonSchema, path: string, errors: string[], integer: boolean): void {
   if (typeof value !== "number" || Number.isNaN(value)) {
     errors.push(`${path}: must be number`);
     return;
@@ -193,6 +196,7 @@ function validateObject(
   root: JsonSchema,
   path: string,
   errors: string[],
+  partial: boolean,
 ): void {
   if (!isPlainObject(value)) {
     errors.push(`${path}: must be object`);
@@ -207,22 +211,25 @@ function validateObject(
   if (propMap) {
     for (const [key, propSchema] of Object.entries(propMap)) {
       if (key in value) {
-        validateValue(value[key], propSchema, root, `${path}.${key}`, errors);
+        validateValue(value[key], propSchema, root, `${path}.${key}`, errors, partial);
       }
     }
   }
 
-  const required = schema.required;
-  if (Array.isArray(required)) {
-    for (const key of required) {
-      if (typeof key === "string" && !(key in value)) {
-        errors.push(`${path}: missing required property '${key}'`);
+  if (!partial) {
+    const required = schema.required;
+    if (Array.isArray(required)) {
+      for (const key of required) {
+        if (typeof key === "string" && !(key in value)) {
+          errors.push(`${path}: missing required property '${key}'`);
+        }
       }
     }
   }
 
   if (schema.additionalProperties === false && propMap) {
     for (const key of Object.keys(value)) {
+      if (isFrameworkConfigKey(key)) continue;
       if (!(key in propMap)) {
         errors.push(`${path}: unknown property '${key}'`);
       }
@@ -236,6 +243,7 @@ function validateArray(
   root: JsonSchema,
   path: string,
   errors: string[],
+  partial: boolean,
 ): void {
   if (!Array.isArray(value)) {
     errors.push(`${path}: must be array`);
@@ -250,12 +258,12 @@ function validateArray(
   const items = schema.items;
   if (typeof items === "object" && items !== null && !Array.isArray(items)) {
     for (let i = 0; i < value.length; i++) {
-      validateValue(value[i], items as JsonSchema, root, `${path}[${i}]`, errors);
+      validateValue(value[i], items as JsonSchema, root, `${path}[${i}]`, errors, partial);
     }
   }
 }
 
-function validateParsedConfigValue(
+export function validateParsedConfigValue(
   parsed: unknown,
   propertySchema: JsonSchema | undefined,
   rootSchema: JsonSchema,
@@ -264,18 +272,14 @@ function validateParsedConfigValue(
     return parsed;
   }
   const errors: string[] = [];
-  validateValue(parsed, propertySchema, rootSchema, "$", errors);
+  validateValue(parsed, propertySchema, rootSchema, "$", errors, false);
   if (errors.length > 0) {
     throw new Error(errors[0] ?? "Invalid config value");
   }
   return parsed;
 }
 
-function parseJsonLiteral(
-  raw: string,
-  propertySchema: JsonSchema | undefined,
-  rootSchema: JsonSchema,
-): unknown {
+function parseJsonLiteral(raw: string, propertySchema: JsonSchema | undefined, rootSchema: JsonSchema): unknown {
   let parsed: unknown;
   try {
     parsed = JSON.parse(raw) as unknown;
@@ -346,11 +350,7 @@ function parsePrimitiveArraySegment(segment: string, items: PrimitiveArrayItems)
   }
 }
 
-function parseHomogeneousPrimitiveArray(
-  raw: string,
-  arraySchema: JsonSchema,
-  rootSchema: JsonSchema,
-): unknown[] {
+function parseHomogeneousPrimitiveArray(raw: string, arraySchema: JsonSchema, rootSchema: JsonSchema): unknown[] {
   const items = homogeneousPrimitiveArrayItems(arraySchema, rootSchema);
   if (!items) {
     throw new Error("Use --json for object or array config values");

package/src/config.integration.test.ts

@@ -85,11 +85,7 @@ test("MCP config file loads and exports vars for tool handlers", async () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-mcp-"));
   const configFile = join(dir, ".local", "lib", "mcp_test", "config");
   mkdirSync(dirname(configFile), { recursive: true });
-  writeFileSync(
-    configFile,
-    `${JSON.stringify({ argsTestSecret: "file-value" }, null, 2)}\n`,
-    "utf8",
-  );
+  writeFileSync(configFile, `${JSON.stringify({ argsTestSecret: "file-value" }, null, 2)}\n`, "utf8");
   const responses = await mcpRequest(
     [
       {

package/src/configure/configure.test.ts

@@ -6,11 +6,9 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import {
-  appConfigHasEntries,
-  parseConfigureOpts,
-  validateConfigureOpts,
-} from "../configure/index.ts";
+import { appConfigFileExists } from "../config/file.ts";
+import { appConfigHasEntries, parseConfigureOpts, validateConfigureOpts } from "../configure/index.ts";
+import { Cli } from "../index.ts";
 import { detectInstalledArtifacts } from "../install/detect-installed.ts";
 import { parseInstallOpts } from "../install/opts.ts";
 import { resolveClaudeDesktopMcpPath, resolveInstallPaths } from "../install/paths.ts";
@@ -157,3 +155,19 @@ describe("app config wizard", () => {
     expect(appConfigHasEntries(fixture)).toBe(false);
   });
 });
+
+describe("configure --sync bootstrap", () => {
+  test("creates config.json for apps without appConfig", async () => {
+    const program: CliProgram = {
+      key: "syncboot",
+      version: "0.0.0",
+      description: "Sync bootstrap test.",
+      handler: () => {},
+      configure: { enabled: true },
+    };
+    expect(appConfigFileExists(program)).toBe(false);
+    const result = await new Cli(program).invoke(["configure", "--sync", "--yes"]);
+    expect(result.exitCode).toBe(0);
+    expect(appConfigFileExists(program)).toBe(true);
+  });
+});

package/src/configure/index.ts

@@ -4,6 +4,7 @@ Interactive and automated `configure` command orchestration (agent artifacts and
 
 import { resolveCapabilities } from "../capabilities.ts";
 import { displayAppConfigPath, runConfigure } from "../config/bootstrap.ts";
+import { ensureAppConfigFile } from "../config/file.ts";
 import { resolveInstallPaths } from "../install/paths.ts";
 import { buildInstallPlan, buildUpdatePlan } from "../install/plan.ts";
 import {
@@ -25,11 +26,7 @@ import type {
   TargetPlanContext,
   UninstallAction,
 } from "../install/target-types.ts";
-import {
-  buildUninstallPlan,
-  skillDirFromUninstallSummary,
-  uninstallSkillDir,
-} from "../install/uninstall.ts";
+import { buildUninstallPlan, skillDirFromUninstallSummary, uninstallSkillDir } from "../install/uninstall.ts";
 import { cliSkillInstall, skillTargetFromActionKind } from "../skill/install.ts";
 import type { CliProgram } from "../types.ts";
 import { artifactPromptLabel, promptTargetAction } from "./prompt.ts";
@@ -218,8 +215,7 @@ async function runInteractiveConfigure(root: CliProgram, opts: ConfigureOpts): P
     if (actions.length === 0) continue;
 
     const installActions = actions.filter(
-      (a): a is InstallAction =>
-        "kind" in a && typeof a.kind === "string" && a.kind.includes("-mcp"),
+      (a): a is InstallAction => "kind" in a && typeof a.kind === "string" && a.kind.includes("-mcp"),
     );
     if (choice === "install" && resolveCapabilities(root).mcp && installActions.length > 0) {
       runTargetPreflight(root, paths, mutationOpts, installActions);
@@ -241,6 +237,17 @@ async function runAutomatedConfigure(root: CliProgram, opts: ConfigureOpts): Pro
     return [];
   }
 
+  const changed: string[] = [];
+
+  if (installOpts.reinstall && !installOpts.uninstall) {
+    const bootstrapped = ensureAppConfigFile(root, !!installOpts.dry);
+    if (bootstrapped) {
+      const display = displayAppConfigPath(root);
+      changed.push(display);
+      installOut(`Initialized config: ${display}`, installOpts);
+    }
+  }
+
   let actions: Array<InstallAction | UninstallAction>;
   if (installOpts.uninstall) {
     actions = buildUninstallPlan(root, paths, installOpts);
@@ -257,14 +264,11 @@ async function runAutomatedConfigure(root: CliProgram, opts: ConfigureOpts): Pro
     runTargetPreflight(root, paths, installOpts, installActions);
   }
 
-  return executePlan(root, actions, installOpts, true);
+  return [...changed, ...executePlan(root, actions, installOpts, true)];
 }
 
 /** Main configure command orchestrator. */
-export async function cliConfigure(
-  root: CliProgram,
-  rawOpts: Record<string, string>,
-): Promise<never> {
+export async function cliConfigure(root: CliProgram, rawOpts: Record<string, string>): Promise<never> {
   const opts = parseConfigureOpts(rawOpts);
   const err = validateConfigureOpts(opts);
   if (err) {
@@ -276,9 +280,7 @@ export async function cliConfigure(
 
   let changed: string[] = [];
   try {
-    changed = isInteractive
-      ? await runInteractiveConfigure(root, opts)
-      : await runAutomatedConfigure(root, opts);
+    changed = isInteractive ? await runInteractiveConfigure(root, opts) : await runAutomatedConfigure(root, opts);
   } catch (mutationErr) {
     installErr(mutationErr instanceof Error ? mutationErr.message : String(mutationErr));
     process.exit(1);

package/src/docs/api-guide.ts

@@ -90,12 +90,7 @@ function fallbackLine(node: CliSchemaExport): string | null {
 }
 
 /** Renders one command node and recurses into subcommands. */
-function renderCommandNode(
-  rootKey: string,
-  path: string[],
-  node: CliSchemaExport,
-  lines: string[],
-): void {
+function renderCommandNode(rootKey: string, path: string[], node: CliSchemaExport, lines: string[]): void {
   const level = Math.min(path.length + 2, 6);
   const heading = "#".repeat(level);
   const cmd = commandPath(rootKey, path);

package/src/docs/builtin.ts

@@ -25,11 +25,7 @@ const DOCS_SAVE_OPTION: CliOption = {
   kind: CliOptionKind.Presence,
 };
 
-function runDocsTopic(
-  program: CliProgram,
-  topic: string,
-  ctx: { hasFlag(name: string): boolean },
-): void {
+function runDocsTopic(program: CliProgram, topic: string, ctx: { hasFlag(name: string): boolean }): void {
   if (ctx.hasFlag("save")) {
     process.stdout.write(`${saveDocsTopic(program, topic)}\n`);
     return;

package/src/docs/docs.test.ts

@@ -136,9 +136,7 @@ test("presentation includes docs subtree", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
   expect(docsNode).toBeDefined();
-  expect(
-    docsNode && "commands" in docsNode && docsNode.commands.some((c) => c.key === "readme"),
-  ).toBe(true);
+  expect(docsNode && "commands" in docsNode && docsNode.commands.some((c) => c.key === "readme")).toBe(true);
 });
 
 test("docs schema prints JSON", async () => {
@@ -243,9 +241,7 @@ test("docs api --save prepends generated hint", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "api", "--save"]);
   expect(result.exitCode).toBe(0);
   const text = readFileSync(join(workDir, "docs/api.md"), "utf8");
-  expect(text.startsWith("<!-- Generated by myapp docs api --save; do not edit. -->\n\n")).toBe(
-    true,
-  );
+  expect(text.startsWith("<!-- Generated by myapp docs api --save; do not edit. -->\n\n")).toBe(true);
   expect(text).toContain("CLI API reference");
 });
 

package/src/docs/mcp-guide.ts

@@ -2,12 +2,7 @@ import { resolveCapabilities } from "../capabilities.ts";
 import { defaultConfigEntryTitle } from "../config/entry.ts";
 import { displayAppConfigPath } from "../config/file.ts";
 import { expectedOpenCodeMcpEntry, OPENCODE_CONFIG_SCHEMA } from "../install/mcp-opencode.ts";
-import {
-  collectMcpTools,
-  type McpToolDef,
-  mcpServerId,
-  resolveMcpSchemaUri,
-} from "../mcp/tools.ts";
+import { collectMcpTools, type McpToolDef, mcpServerId, resolveMcpSchemaUri } from "../mcp/tools.ts";
 import { collectOptionDefs } from "../parse.ts";
 import { CliOptionKind, type CliProgram } from "../types.ts";
 import { resolveDocsTopicResourceUri } from "./mcp-resources.ts";
@@ -115,10 +110,7 @@ export function generateMcpGuide(root: CliProgram): string {
       "",
     );
   } else {
-    lines.push(
-      `The CLI binary \`${root.key}\` must already be on your PATH. Host configs reference it by name.`,
-      "",
-    );
+    lines.push(`The CLI binary \`${root.key}\` must already be on your PATH. Host configs reference it by name.`, "");
   }
 
   lines.push(
@@ -217,9 +209,7 @@ export function generateMcpGuide(root: CliProgram): string {
     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(`| Docs topic \`${key}\` | \`${uri}\` — same markdown as \`${root.key} docs ${key}\` |`);
       }
     }
   }

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

@@ -61,7 +61,5 @@ test("docsMcpResources empty when MCP disabled", () => {
 
 test("reservedDocsTopicResourceUris matches docsMcpResources URIs", () => {
   const program = fixture();
-  expect(reservedDocsTopicResourceUris(program)).toEqual(
-    docsMcpResources(program).map((r) => r.uri),
-  );
+  expect(reservedDocsTopicResourceUris(program)).toEqual(docsMcpResources(program).map((r) => r.uri));
 });

package/src/docs/mcp-resources.ts

@@ -3,12 +3,7 @@ Auto MCP resources for user docs.topics when docs and MCP are both enabled.
 */
 
 import type { CliProgram } from "../types.ts";
-import {
-  docsEnabled,
-  docsTopicContent,
-  docsTopicDescription,
-  docsUserTopicKeys,
-} from "./resolve.ts";
+import { docsEnabled, docsTopicContent, docsTopicDescription, docsUserTopicKeys } from "./resolve.ts";
 
 /** Default URI pattern for a docs topic MCP resource (`<mcpId>://docs/<topicKey>`). */
 export function defaultDocsTopicResourceUri(mcpId: string, topicKey: string): string {