argsbarg 3.6.4 → 4.0.1

package/src/config.integration.test.ts

@@ -0,0 +1,100 @@
+/*
+App config bootstrap and MCP config enforcement regressions.
+*/
+
+import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { bootstrapAppConfig } from "./config/bootstrap.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");
+  process.env.FOO = "original";
+  try {
+    const p = testProgram({
+      key: "app",
+      version: "0",
+      description: "",
+      appConfig: {
+        path: configFile,
+        entries: {
+          foo: { description: "x", env: "FOO" },
+          bar: { description: "y", env: "BAR" },
+        },
+      },
+      handler: () => {},
+    });
+    bootstrapAppConfig(p, { validateFile: true });
+    expect(process.env.FOO).toBe("original");
+    expect(process.env.BAR).toBe("bar");
+  } finally {
+    delete process.env.FOO;
+    delete process.env.BAR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("MCP program.appConfig fails when required config missing", async () => {
+  const responses = await mcpRequest(
+    [
+      {
+        jsonrpc: "2.0",
+        id: 13,
+        method: "tools/call",
+        params: { name: "echo_env", arguments: { name: "ARGS_TEST_SECRET" } },
+      },
+    ],
+    { script: "examples/mcp-test.ts", env: { ARGS_TEST_SECRET: "" } },
+  );
+  const res = responses.get(13) as { result: { isError: boolean; content: { text: string }[] } };
+  expect(res.result.isError).toBe(true);
+  expect(res.result.content[0]?.text).toContain("argsTestSecret");
+});
+
+test("MCP program.appConfig succeeds when env present", async () => {
+  const responses = await mcpRequest(
+    [
+      {
+        jsonrpc: "2.0",
+        id: 14,
+        method: "tools/call",
+        params: { name: "echo_env", arguments: { name: "ARGS_TEST_SECRET" } },
+      },
+    ],
+    { script: "examples/mcp-test.ts", env: { ARGS_TEST_SECRET: "sekrit" } },
+  );
+  const res = responses.get(14) as { result: { isError: boolean; content: { text: string }[] } };
+  expect(res.result.isError).toBe(false);
+  expect(res.result.content[0]?.text.trim()).toBe("sekrit");
+});
+
+test("MCP config file loads and exports vars for tool handlers", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "argsbarg-mcp-"));
+  const configFile = join(dir, "config");
+  writeFileSync(
+    configFile,
+    `${JSON.stringify({ argsTestSecret: "file-value" }, null, 2)}\n`,
+    "utf8",
+  );
+  const responses = await mcpRequest(
+    [
+      {
+        jsonrpc: "2.0",
+        id: 15,
+        method: "tools/call",
+        params: { name: "echo_env", arguments: { name: "ARGS_TEST_SECRET" } },
+      },
+    ],
+    {
+      script: "examples/mcp-test.ts",
+      env: { ARGS_TEST_CONFIG_FILE: configFile, 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");
+});

package/src/context.ts

@@ -7,6 +7,8 @@ It keeps handlers small with a typed read API for flags, strings, numbers, and c
 parsed values.
 */
 
+import type { AnyAppConfigSnapshot } from "./config/context.ts";
+import { EmptyAppConfigSnapshot } from "./config/context.ts";
 import { parseCommaList, parseDate, parseDateTime, parseDurationMs } from "./formats.ts";
 import { collectOptionDefs } from "./parse.ts";
 import type { CliInvocation, CliLeaf, CliNode, CliOption, CliProgram } from "./types.ts";
@@ -26,6 +28,7 @@ export class CliContext {
   readonly program: CliProgram;
   readonly opts: Record<string, string>;
   readonly invocation: CliInvocation;
+  readonly appConfig: AnyAppConfigSnapshot;
 
   /** Captures the program root, routed path, positional words, and option map for a leaf handler. */
   constructor(
@@ -35,6 +38,7 @@ export class CliContext {
     opts: Record<string, string>,
     program: CliProgram,
     invocation: CliInvocation = "cli",
+    appConfig: AnyAppConfigSnapshot = new EmptyAppConfigSnapshot(program),
   ) {
     this.appName = appName;
     this.commandPath = commandPath;
@@ -42,6 +46,7 @@ export class CliContext {
     this.opts = opts;
     this.program = program;
     this.invocation = invocation;
+    this.appConfig = appConfig;
   }
 
   /** Returns whether a presence flag was set (including implicit "1" for boolean options). */

package/src/docs/docs.test.ts

@@ -2,9 +2,9 @@ import { afterEach, beforeEach, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { completionBashScript } from "../builtins/index.ts";
 import { cliPresentationRoot } from "../builtins/presentation.ts";
-import { completionBashScript } from "../completion.ts";
-import { cliInvoke } from "../index.ts";
+import { Cli } from "../index.ts";
 import type { CliProgram } from "../types.ts";
 import { cliValidateProgram } from "../validate.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
@@ -80,14 +80,14 @@ test("docsEffectiveDefaultTopic uses first topic key", () => {
   expect(docsEffectiveDefaultTopic(docsFixture().docs!)).toBe("readme");
 });
 
-test("bare docs prints first topic via cliInvoke", async () => {
-  const result = await cliInvoke(docsFixture(), ["docs"]);
+test("bare docs prints first topic via Cli.invoke", async () => {
+  const result = await new Cli(docsFixture()).invoke(["docs"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("Hello README");
 });
 
 test("docs readme prints bundled text", async () => {
-  const result = await cliInvoke(docsFixture(), ["docs", "readme"]);
+  const result = await new Cli(docsFixture()).invoke(["docs", "readme"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("Hello README");
 });
@@ -95,12 +95,12 @@ test("docs readme prints bundled text", async () => {
 test("docs defaultTopic override", async () => {
   const root = docsFixture();
   root.docs!.defaultTopic = "arch";
-  const result = await cliInvoke(root, ["docs"]);
+  const result = await new Cli(root).invoke(["docs"]);
   expect(result.stdout).toContain("Architecture");
 });
 
 test("docs mcp when MCP enabled", async () => {
-  const result = await cliInvoke(docsFixture(true), ["docs", "mcp"]);
+  const result = await new Cli(docsFixture(true)).invoke(["docs", "mcp"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("MCP server (myapp)");
   expect(result.stdout).toContain("myapp mcp");
@@ -109,7 +109,7 @@ test("docs mcp when MCP enabled", async () => {
 });
 
 test("docs rejects unknown subcommand", async () => {
-  const result = await cliInvoke(docsFixture(), ["docs", "all"]);
+  const result = await new Cli(docsFixture()).invoke(["docs", "all"]);
   expect(result.exitCode).not.toBe(0);
 });
 
@@ -121,7 +121,7 @@ test("docs mcp absent from router when MCP disabled", async () => {
   if (docsNode && "commands" in docsNode) {
     expect(docsNode.commands.some((c) => c.key === "mcp")).toBe(false);
   }
-  const result = await cliInvoke(root, ["docs", "mcp"]);
+  const result = await new Cli(root).invoke(["docs", "mcp"]);
   expect(result.exitCode).not.toBe(0);
 });
 
@@ -135,7 +135,7 @@ test("presentation includes docs subtree", () => {
 });
 
 test("docs schema prints JSON", async () => {
-  const result = await cliInvoke(docsFixture(), ["docs", "schema"]);
+  const result = await new Cli(docsFixture()).invoke(["docs", "schema"]);
   expect(result.exitCode).toBe(0);
   const schema = JSON.parse(result.stdout);
   expect(schema.key).toBe("myapp");
@@ -143,7 +143,7 @@ test("docs schema prints JSON", async () => {
 });
 
 test("docs api prints markdown reference", async () => {
-  const result = await cliInvoke(docsFixture(), ["docs", "api"]);
+  const result = await new Cli(docsFixture()).invoke(["docs", "api"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("# myapp — CLI API reference");
   expect(result.stdout).toContain("## `myapp run`");
@@ -152,7 +152,7 @@ test("docs api prints markdown reference", async () => {
 });
 
 test("docs skill prints Cursor SKILL.md", async () => {
-  const result = await cliInvoke(docsFixture(), ["docs", "skill"]);
+  const result = await new Cli(docsFixture()).invoke(["docs", "skill"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("---");
   expect(result.stdout).toContain("name: myapp");
@@ -209,7 +209,7 @@ test("generateMcpGuide includes schema URI and install targets", () => {
 });
 
 test("docs --save writes topic file", async () => {
-  const result = await cliInvoke(docsFixture(), ["docs", "readme", "--save"]);
+  const result = await new Cli(docsFixture()).invoke(["docs", "readme", "--save"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout.trim()).toBe("docs/readme.md");
   const text = readFileSync(join(workDir, "docs/readme.md"), "utf8");
@@ -218,7 +218,7 @@ test("docs --save writes topic file", async () => {
 });
 
 test("docs api --save prepends generated hint", async () => {
-  const result = await cliInvoke(docsFixture(), ["docs", "api", "--save"]);
+  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(
@@ -228,7 +228,7 @@ test("docs api --save prepends generated hint", async () => {
 });
 
 test("docs skill --save keeps frontmatter first", async () => {
-  const result = await cliInvoke(docsFixture(), ["docs", "skill", "--save"]);
+  const result = await new Cli(docsFixture()).invoke(["docs", "skill", "--save"]);
   expect(result.exitCode).toBe(0);
   const text = readFileSync(join(workDir, "docs/skill.md"), "utf8");
   expect(text.startsWith("---\n")).toBe(true);
@@ -238,7 +238,7 @@ test("docs skill --save keeps frontmatter first", async () => {
 });
 
 test("docs schema --save writes JSON file", async () => {
-  const result = await cliInvoke(docsFixture(), ["docs", "schema", "--save"]);
+  const result = await new Cli(docsFixture()).invoke(["docs", "schema", "--save"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout.trim()).toBe("docs/schema.json");
   const text = readFileSync(join(workDir, "docs/schema.json"), "utf8");

package/src/docs/mcp-guide.ts

@@ -1,4 +1,6 @@
 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,
@@ -163,21 +165,43 @@ export function generateMcpGuide(root: CliProgram): string {
     "",
   );
 
-  if (mcp.shellEnv || mcp.envFile) {
+  if (mcp.shellEnv) {
     lines.push("## Environment", "");
-    if (mcp.shellEnv) {
-      lines.push(
-        "- **`shellEnv`** — captures login-shell environment at MCP startup (PATH, toolchain shims, exports).",
-      );
-    }
-    if (mcp.envFile) {
-      lines.push(
-        `- **\`envFile\`** — loads \`${mcp.envFile}\` after shell env (overrides for its keys).`,
-      );
-    }
+    lines.push(
+      "- **`shellEnv`** — captures login-shell environment at MCP startup (PATH, toolchain shims, exports).",
+    );
     lines.push("");
   }
 
+  if (root.appConfig?.entries && Object.keys(root.appConfig.entries).length > 0) {
+    lines.push("## Configuration", "");
+    lines.push(
+      `Configure before first use in Cursor or Claude Desktop (MCP hosts are non-interactive): \`${root.key} install --configure\`.`,
+      "",
+      `Default config file: \`${displayAppConfigPath(root)}\` (flat JSON keys).`,
+      "",
+    );
+    for (const [key, entry] of Object.entries(root.appConfig.entries)) {
+      const label = entry.title ?? defaultConfigEntryTitle(key);
+      const req = entry.required === false ? "optional" : "required";
+      const envNote = entry.env ? ` → env \`${entry.env}\`` : "";
+      lines.push(`- **${label}** (\`${key}\`, ${req}${envNote}) — ${entry.description}`);
+    }
+    lines.push(
+      "",
+      "Example:",
+      "",
+      "```typescript",
+      "config: {",
+      "  schema: {",
+      '    apiToken: { description: "…", env: "API_TOKEN", sensitive: true },',
+      "  },",
+      "},",
+      "```",
+      "",
+    );
+  }
+
   lines.push(
     "## What agents get",
     "",

package/src/hidden-mcpb.test.ts

@@ -1,11 +1,16 @@
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { exportPresentationBuiltins } from "./builtins/export.ts";
 import { cliParseRoot, cliPresentationRoot } from "./builtins/presentation.ts";
 import { cliHelpRender } from "./help.ts";
-import { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
+import {
+  defaultMcpBundlePaths,
+  generateMcpManifest,
+  packMcpBundle,
+  runMcpBundle,
+} from "./mcp/bundle.ts";
 import { collectMcpTools } from "./mcp/tools.ts";
 import { cliSchemaExport } from "./schema.ts";
 import { CliOptionKind, type CliProgram } from "./types.ts";
@@ -149,4 +154,37 @@ describe("mcp bundle", () => {
       rmSync(work, { recursive: true, force: true });
     }
   });
+
+  test("runMcpBundle prints mcpb and plugin paths", () => {
+    const work = mkdtempSync(join(tmpdir(), "mcpb-run-"));
+    const stdout: string[] = [];
+    const orig = process.stdout.write.bind(process.stdout);
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      stdout.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+      return true;
+    }) as typeof process.stdout.write;
+    try {
+      const dist = join(work, "dist");
+      mkdirSync(dist, { recursive: true });
+      writeFileSync(join(dist, "myapp"), "#!/bin/sh\n", { mode: 0o755 });
+      const prevCwd = process.cwd();
+      process.chdir(work);
+      try {
+        runMcpBundle(hiddenFixture);
+      } finally {
+        process.chdir(prevCwd);
+      }
+      const lines = stdout.join("").trim().split("\n");
+      const norm = (p: string) => realpathSync.native(p);
+      expect(lines.map(norm)).toEqual([
+        norm(join(dist, "myapp.mcpb")),
+        norm(join(dist, "claude-plugin", "myapp.zip")),
+      ]);
+      const zip = readFileSync(join(dist, "claude-plugin", "myapp.zip"));
+      expect(zip.indexOf(Buffer.from(".mcp.json"))).toBeGreaterThanOrEqual(0);
+    } finally {
+      process.stdout.write = orig;
+      rmSync(work, { recursive: true, force: true });
+    }
+  });
 });

package/src/index.ts

@@ -7,6 +7,8 @@ It gives consumers one stable import path without forcing them to know the inter
 module layout.
 */
 
+export { Cli, type CliInvokeKind, type CliInvokeResult } from "./cli.ts";
+export { cliErrWithHelp } from "./cli-errors.ts";
 export type { CliLeafInputs } from "./context.ts";
 export { CliContext } from "./context.ts";
 export {
@@ -32,12 +34,11 @@ export {
   isAlreadyCurrent,
   parseReleaseTag,
 } from "./install/gh-release-update.ts";
-export type { CliInvokeKind, CliInvokeResult } from "./invoke.ts";
-export { cliInvoke } from "./invoke.ts";
 export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
-export { cliErrWithHelp, cliRun } from "./runtime";
 export type {
+  CliAppConfig,
+  CliAppConfigEntry,
   CliDocsConfig,
   CliDocsTopic,
   CliHandler,

package/src/install/index.ts

@@ -1,5 +1,6 @@
 import { readSync } from "node:fs";
 import { resolveCapabilities } from "../capabilities.ts";
+import { displayAppConfigPath, runInstallConfigure } from "../config/bootstrap.ts";
 import { cliSkillInstall } from "../skill/install.ts";
 import type { CliProgram } from "../types.ts";
 import { checkCodexMcpConflict } from "./mcp-codex.ts";
@@ -24,6 +25,8 @@ export function parseInstallOpts(raw: Record<string, string>): InstallOpts {
     from: raw.from,
     status: flag("status"),
     uninstall: flag("uninstall"),
+    configure: flag("configure"),
+    config: flag("config"),
     yes: flag("yes"),
     dry: flag("dry"),
     json: flag("json"),
@@ -33,6 +36,23 @@ export function parseInstallOpts(raw: Record<string, string>): InstallOpts {
 }
 
 export function validateInstallOpts(opts: InstallOpts): string | null {
+  if (opts.configure) {
+    if (
+      opts.all ||
+      opts.bin ||
+      opts.completions ||
+      opts.skill ||
+      opts.mcp ||
+      opts.config ||
+      opts.reinstall ||
+      opts.update ||
+      opts.uninstall ||
+      opts.status
+    ) {
+      return "--configure cannot be combined with other install flags.";
+    }
+    return null;
+  }
   if (opts.quiet && opts.dry) {
     return "--quiet cannot be combined with --dry.";
   }
@@ -90,10 +110,18 @@ export function validateInstallOpts(opts: InstallOpts): string | null {
   if (opts.uninstall && (opts.reinstall || opts.update || opts.status)) {
     return "--uninstall cannot be combined with --reinstall, --update, or --status.";
   }
-  if (!opts.status && !opts.reinstall && !opts.update) {
-    const hasTarget = opts.all || opts.bin || opts.completions || opts.skill || opts.mcp;
+  if (opts.uninstall) {
+    const hasUninstallTarget =
+      opts.all || opts.bin || opts.completions || opts.skill || opts.mcp || opts.config;
+    if (!hasUninstallTarget) {
+      return "Specify at least one target: --all, --bin, --completions, --skill, --mcp, or --config.";
+    }
+  }
+  if (!opts.status && !opts.reinstall && !opts.update && !opts.uninstall) {
+    const hasTarget =
+      opts.all || opts.bin || opts.completions || opts.skill || opts.mcp || opts.config;
     if (!hasTarget) {
-      return "Specify at least one target: --all, --bin, --completions, --skill, or --mcp.";
+      return "Specify at least one target: --all, --bin, --completions, --skill, --mcp, or --config.";
     }
   }
   return null;
@@ -242,6 +270,21 @@ export async function cliInstall(
   rawOpts: Record<string, string>,
 ): Promise<never> {
   const opts = parseInstallOpts(rawOpts);
+
+  if (opts.configure) {
+    if (!root.appConfig) {
+      installErr("install --configure requires program.appConfig on the program root.");
+      process.exit(1);
+    }
+    const result = runInstallConfigure(root);
+    if (result.changed) {
+      installOut(`Wrote config: ${displayAppConfigPath(root)}`, opts);
+    } else {
+      installOut(`Config unchanged: ${displayAppConfigPath(root)}`, opts);
+    }
+    process.exit(0);
+  }
+
   const err = validateInstallOpts(opts);
   if (err) {
     installErr(err);

package/src/install/paths.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { mcpServerId, sanitizeToolSegment } from "../mcp/tools.ts";
+import { expandTilde, userHome, xdgConfigHome } from "../paths/host.ts";
 import type { CliProgram } from "../types.ts";
 import { resolveOpenCodeConfigPathForInstall } from "./mcp-opencode.ts";
 
@@ -25,20 +25,7 @@ export interface InstallPaths {
   skillDirName: string;
 }
 
-/** Resolves the user home directory (`$HOME` when set). */
-export function userHome(): string {
-  return process.env.HOME ?? homedir();
-}
-
-function expandTilde(path: string): string {
-  if (path.startsWith("~/")) {
-    return join(userHome(), path.slice(2));
-  }
-  if (path === "~") {
-    return userHome();
-  }
-  return path;
-}
+export { userHome } from "../paths/host.ts";
 
 /** Resolves the binary install directory from CLI flag, env, or config. */
 export function resolveBindir(root: CliProgram, prefix?: string): string {
@@ -58,8 +45,7 @@ export function resolveClaudeDesktopMcpPath(home: string): string {
     const appData = process.env.APPDATA ?? join(home, "AppData", "Roaming");
     return join(appData, "Claude", "claude_desktop_config.json");
   }
-  const xdgConfig = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
-  return join(xdgConfig, "Claude", "claude_desktop_config.json");
+  return join(xdgConfigHome(home), "Claude", "claude_desktop_config.json");
 }
 
 /** True when Claude Desktop app data exists (config file or app support directory). */
@@ -76,8 +62,7 @@ export function resolveChatGptMcpPath(home: string): string {
     const appData = process.env.APPDATA ?? join(home, "AppData", "Roaming");
     return join(appData, "OpenAI", "ChatGPT", "chatgpt_mcp_config.json");
   }
-  const xdgConfig = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
-  return join(xdgConfig, "ChatGPT", "chatgpt_mcp_config.json");
+  return join(xdgConfigHome(home), "ChatGPT", "chatgpt_mcp_config.json");
 }
 
 /** True when ChatGPT desktop app data exists (config file or app support directory). */
@@ -91,7 +76,7 @@ export function resolveInstallPaths(root: CliProgram, opts: { prefix?: string })
   const bindir = resolveBindir(root, opts.prefix);
   const key = root.key;
   const skillDirName = sanitizeToolSegment(root.key);
-  const xdgConfig = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
+  const xdgConfig = xdgConfigHome(home);
   const claudeDesktopMcpPath = resolveClaudeDesktopMcpPath(home);
   const chatGptMcpPath = resolveChatGptMcpPath(home);
 

package/src/install/plan.ts

@@ -31,6 +31,8 @@ export interface InstallOpts {
   from?: string;
   status?: boolean;
   uninstall?: boolean;
+  configure?: boolean;
+  config?: boolean;
   yes?: boolean;
   dry?: boolean;
   json?: boolean;
@@ -73,6 +75,10 @@ export function wantsInstallMcp(opts: InstallOpts, root: CliProgram): boolean {
   return !!(opts.mcp || opts.all) && resolveCapabilities(root).mcp;
 }
 
+export function wantsUninstallConfig(opts: InstallOpts, root: CliProgram): boolean {
+  return !!(opts.config || opts.all) && root.appConfig !== undefined;
+}
+
 /** Builds install actions for normal mode (--all / scoped targets). */
 export function buildInstallPlan(
   root: CliProgram,

package/src/install/status.ts

@@ -1,3 +1,4 @@
+import { appConfigStatus } from "../config/bootstrap.ts";
 import type { CliProgram } from "../types.ts";
 import { buildInstallStatus, detectInstalledArtifacts } from "./detect-installed.ts";
 import { resolveInstallPaths } from "./paths.ts";
@@ -68,4 +69,15 @@ export function printInstallStatus(root: CliProgram, opts: InstallOpts): void {
   if (!any) {
     installOut("  (none detected)", opts);
   }
+
+  const configStatus = appConfigStatus(root);
+  if (configStatus) {
+    installOut(
+      `  app config: ${configStatus.path}${configStatus.exists ? "" : " (missing)"}`,
+      opts,
+    );
+    for (const req of configStatus.required) {
+      installOut(`    ${req.key}: ${req.set ? "set" : "missing"}`, opts);
+    }
+  }
 }

package/src/install/uninstall.ts

@@ -1,4 +1,5 @@
 import { existsSync, rmSync } from "node:fs";
+import { resolveAppConfigPath, uninstallAppConfig } from "../config/file.ts";
 import type { CliProgram } from "../types.ts";
 import { uninstallBinary } from "./binary.ts";
 import { uninstallCompletions } from "./completions.ts";
@@ -13,6 +14,7 @@ import {
   wantsInstallCompletions,
   wantsInstallMcp,
   wantsInstallSkill,
+  wantsUninstallConfig,
 } from "./plan.ts";
 
 export interface UninstallAction {
@@ -147,6 +149,15 @@ export function buildUninstallPlan(
     }
   }
 
+  if (wantsUninstallConfig(opts, root)) {
+    const configPath = resolveAppConfigPath(root);
+    actions.push({
+      summary: `app config: ${configPath}`,
+      message: `Removing app config ${configPath}`,
+      run: () => (uninstallAppConfig(root, dry) ? [configPath] : []),
+    });
+  }
+
   return actions;
 }
 

package/src/install/update.test.ts

@@ -3,7 +3,7 @@ import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { cliPresentationRoot } from "../builtins/presentation.ts";
-import { cliInvoke } from "../index.ts";
+import { Cli } from "../index.ts";
 import type { CliProgram, CliUpdateArtifact } from "../types.ts";
 import { cliValidateProgram } from "../validate.ts";
 import { parseInstallOpts, runInstallMutation } from "./index.ts";
@@ -80,7 +80,7 @@ test("runInstallMutation honors --from for binary copy", async () => {
   expect(readFileSync(dest, "utf8")).toContain("echo hi");
 });
 
-test("cliInvoke install --update uses hook and reinstalls", async () => {
+test("Cli.invoke install --update uses hook and reinstalls", async () => {
   const source = join(home, "new-binary");
   writeFileSync(source, "#!/bin/sh\necho hi\n", "utf8");
   chmodSync(source, 0o755);
@@ -90,19 +90,19 @@ test("cliInvoke install --update uses hook and reinstalls", async () => {
     version: "2.0.0",
   }));
 
-  const result = await cliInvoke(root, ["install", "--update"]);
+  const result = await new Cli(root).invoke(["install", "--update"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("Updated testapp 1.0.0 → 2.0.0");
   expect(existsSync(join(home, ".local", "bin", "testapp"))).toBe(true);
 });
 
-test("cliInvoke install --update reports already current", async () => {
+test("Cli.invoke install --update reports already current", async () => {
   const root = fixtureWithUpdate(async () => ({
     path: process.execPath,
     version: "1.0.0",
   }));
 
-  const result = await cliInvoke(root, ["install", "--update"]);
+  const result = await new Cli(root).invoke(["install", "--update"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("Already at v1.0.0");
 });