argsbarg 4.0.4 → 4.1.0

package/index.d.ts

@@ -22,7 +22,7 @@ declare class AppConfigSnapshot {
 	require(key: string): unknown;
 	set(key: string, value: unknown): void;
 	read(): ResolvedConfig;
-	/** Resolved absolute path to the app JSON config file (honors `program.appConfig.path` or OS default). */
+	/** Resolved absolute path to the app JSON config file (`~/.local/lib/<key>/config.json`). */
 	get path(): string;
 	/** Resolved absolute directory containing the config file. */
 	get dir(): string;
@@ -194,6 +194,10 @@ export interface CliMcpBundleConfig {
 export interface CliMcpServerConfig {
 	/** When `true`, enables the `mcp` built-in and MCP stdio server. */
 	enabled: boolean;
+	/** When `true`, `mcp bundle` writes `dist/<key>.mcpb` for Claude Desktop. Default false. */
+	mcpd?: boolean;
+	/** When `true`, `mcp bundle` also writes `dist/claude-plugin/<name>.zip`. Default false. */
+	claudePlugin?: boolean;
 	/** Resource URI for schema export (default: `<sanitized root key>://schema`). */
 	schemaResourceUri?: string;
 	/**
@@ -281,8 +285,6 @@ export interface CliAppConfigEntry {
  * App configuration block on the program root ({@link CliProgram.appConfig}).
  */
 export interface CliAppConfig {
-	/** Default: `~/.config/<sanitized-key>/config` (or `%APPDATA%/<key>/config` on Windows). */
-	path?: string;
 	/** Built-in `config get` / `config set`. Default: enabled when `appConfig` is set. */
 	commands?: boolean | {
 		enabled?: boolean;
@@ -296,14 +298,67 @@ export interface CliAppConfig {
 export interface CliInstallConfig {
 	/** When `false`, hide/disable `install` (default: enabled). */
 	enabled?: boolean;
-	/** Default bin directory (default: `~/.local/bin`). Overridden by `INSTALL_PREFIX` env and `--prefix`. */
-	prefix?: string;
+	/**
+	 * Default agent integration for full install (`install --all`).
+	 * - `'mcp'` when `mcpServer.enabled` (default): MCP targets in `--all`; paired skills excluded.
+	 * - `'skill'` when MCP is off (default): skill targets in `--all`; paired MCP excluded.
+	 * - `'both'`: install MCP and skill for the same host when both are available.
+	 */
+	agentIntegration?: InstallAgentIntegration;
+	/** Per-artifact gates for full install/uninstall. See {@link resolveEffectiveInstallTargets}. */
+	targets?: CliInstallTargets;
 	/**
 	 * When set, enables `install --update` on the program root.
 	 * Should download or locate the latest release binary and return its path.
 	 */
 	updateGetLatest?: CliUpdateGetLatest;
 }
+/** Agent integration mode for install — MCP vs shell skill per host. */
+export type InstallAgentIntegration = "mcp" | "skill" | "both";
+/** Boolean or structured gate for one install artifact. */
+export type InstallTargetSpec = boolean | {
+	/** When false, artifact is never installed (even with scoped CLI flags). Default true. */
+	enabled?: boolean;
+	/** When true, included in bare `install` / `install --all`. Default varies by key. */
+	includedInAll?: boolean;
+};
+export interface ResolvedInstallTarget {
+	enabled: boolean;
+	includedInAll: boolean;
+}
+/** Per-artifact gates for full install/uninstall. See {@link resolveEffectiveInstallTargets}. */
+export interface CliInstallTargets {
+	/** Copy app to `~/.local/bin/<key>`. Default includedInAll true (opt-out). */
+	app?: InstallTargetSpec;
+	/** ChatGPT desktop MCP. Default false. */
+	chatgptMcp?: InstallTargetSpec;
+	/** Claude Code MCP (`~/.claude.json`). Default false. */
+	claudeCodeMcp?: InstallTargetSpec;
+	/** Claude Desktop MCP. Default false. */
+	claudeDesktopMcp?: InstallTargetSpec;
+	/** Claude Code skill. Default false. */
+	claudeSkill?: InstallTargetSpec;
+	/** Codex MCP (`codex mcp add`). Default false. */
+	codexMcp?: InstallTargetSpec;
+	/** Codex skill. Default false. */
+	codexSkill?: InstallTargetSpec;
+	/** Shell completions for detected shells. Default includedInAll true (opt-out). */
+	completions?: InstallTargetSpec;
+	/** App config: wizard on install, file removal on uninstall. Default includedInAll true. */
+	configure?: InstallTargetSpec;
+	/** Cursor MCP. Default false. */
+	cursorMcp?: InstallTargetSpec;
+	/** Cursor skill. Default false. */
+	cursorSkill?: InstallTargetSpec;
+	/** OpenClaw MCP. Default false. */
+	openclawMcp?: InstallTargetSpec;
+	/** OpenClaw skill. Default false. */
+	openclawSkill?: InstallTargetSpec;
+	/** OpenCode MCP. Default false. */
+	opencodeMcp?: InstallTargetSpec;
+	/** OpenCode skill. Default false. */
+	opencodeSkill?: InstallTargetSpec;
+}
 /**
  * One bundled documentation topic for the `docs` built-in (program root only).
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "4.0.4",
+  "version": "4.1.0",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/builtins/builtins.test.ts

@@ -1,10 +1,11 @@
 import { describe, expect, test } from "bun:test";
+import { ParseKind, parse, postParseValidate } from "../parse.ts";
 import type { CliProgram } from "../types.ts";
 import { exportPresentationBuiltins } from "./export.ts";
 import { completionBashScript, completionFishScript, completionZshScript } from "./index.ts";
 import { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
-import { cliPresentationRoot } from "./presentation.ts";
+import { cliParseRoot, cliPresentationRoot } from "./presentation.ts";
 
 const fixture: CliProgram = {
   key: "myapp",
@@ -23,12 +24,27 @@ const fixture: CliProgram = {
 describe("builtins help copy", () => {
   test("install command includes description and option text", () => {
     const install = cliBuiltinInstallCommand(fixture);
-    expect(install.description).toContain("Install the binary");
+    expect(install.description).toContain("shell completions");
     expect(install.notes).toContain("install --all");
     const names = installBuiltinOptions(fixture).map((o) => o.name);
     expect(names).toContain("all");
     expect(names).toContain("mcp");
-    expect(names).toContain("prefix");
+    expect(names.indexOf("all")).toBeLessThan(names.indexOf("mcp"));
+    expect(names.indexOf("mcp")).toBeLessThan(names.indexOf("status"));
+    expect(names.indexOf("status")).toBeLessThan(names.indexOf("uninstall"));
+    expect(names.indexOf("uninstall")).toBeLessThan(names.indexOf("from"));
+    expect(names.indexOf("from")).toBeLessThan(names.indexOf("yes"));
+    const yesOpt = installBuiltinOptions(fixture).find((o) => o.name === "yes");
+    expect(yesOpt?.shortName).toBe("y");
+  });
+
+  test("install -y parses as --yes", () => {
+    const root = cliParseRoot(fixture);
+    const pr = postParseValidate(root, parse(root, ["install", "-y"]));
+    expect(pr.kind).toBe(ParseKind.Ok);
+    if (pr.kind === ParseKind.Ok) {
+      expect(pr.opts.yes).toBe("1");
+    }
   });
 
   test("install omits --mcp option when mcpServer unset", () => {
@@ -143,6 +159,6 @@ describe("schema export builtins", () => {
   test("exportPresentationBuiltins includes install options", () => {
     const builtins = exportPresentationBuiltins(fixture);
     const install = builtins.find((b) => b.key === "install");
-    expect(install?.options?.find((o) => o.name === "all")?.description).toContain("binary");
+    expect(install?.options?.find((o) => o.name === "all")?.description).toContain("app");
   });
 });

package/src/builtins/config.test.ts

@@ -1,16 +1,16 @@
 import { describe, 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 { resolveAppConfigPath, writeAppConfigFile } from "../config/file.ts";
 import { Cli, type CliProgram } from "../index.ts";
 
-function configFixture(configPath: string): CliProgram {
+function configFixture(): CliProgram {
   return {
     key: "cfg-app",
     version: "1.0.0",
     description: "Config builtin test.",
     appConfig: {
-      path: configPath,
       entries: {
         apiToken: { description: "Token.", env: "API_TOKEN", sensitive: true },
         port: { description: "Port.", required: false },
@@ -23,15 +23,21 @@ function configFixture(configPath: string): CliProgram {
 describe("builtins/config", () => {
   test("config get redacts sensitive values", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
-    const configPath = join(dir, "config");
-    writeFileSync(configPath, `${JSON.stringify({ apiToken: "secret" })}\n`);
+    const prevHome = process.env.HOME;
+    process.env.HOME = dir;
     const prev = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
     try {
-      const result = await new Cli(configFixture(configPath)).invoke(["config", "get", "apiToken"]);
+      const program = configFixture();
+      const configPath = resolveAppConfigPath(program);
+      mkdirSync(dirname(configPath), { recursive: true });
+      writeFileSync(configPath, `${JSON.stringify({ apiToken: "secret" })}\n`);
+      const result = await new Cli(program).invoke(["config", "get", "apiToken"]);
       expect(result.exitCode).toBe(0);
       expect(result.stdout.trim()).toBe("REDACTED");
     } finally {
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
       if (prev !== undefined) process.env.API_TOKEN = prev;
       rmSync(dir, { recursive: true, force: true });
     }
@@ -39,20 +45,21 @@ describe("builtins/config", () => {
 
   test("config get --json redacts sensitive as { set: true }", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
-    const configPath = join(dir, "config");
-    writeFileSync(configPath, `${JSON.stringify({ apiToken: "secret" })}\n`);
+    const prevHome = process.env.HOME;
+    process.env.HOME = dir;
     const prev = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
     try {
-      const result = await new Cli(configFixture(configPath)).invoke([
-        "config",
-        "get",
-        "apiToken",
-        "--json",
-      ]);
+      const program = configFixture();
+      const configPath = resolveAppConfigPath(program);
+      mkdirSync(dirname(configPath), { recursive: true });
+      writeFileSync(configPath, `${JSON.stringify({ apiToken: "secret" })}\n`);
+      const result = await new Cli(program).invoke(["config", "get", "apiToken", "--json"]);
       expect(result.exitCode).toBe(0);
-      expect(JSON.parse(result.stdout.trim())).toEqual({ set: true });
+      expect(JSON.parse(result.stdout)).toEqual({ set: true });
     } finally {
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
       if (prev !== undefined) process.env.API_TOKEN = prev;
       rmSync(dir, { recursive: true, force: true });
     }
@@ -60,21 +67,20 @@ describe("builtins/config", () => {
 
   test("config set writes and resolves without required exit", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
-    const configPath = join(dir, "config");
-    writeFileSync(configPath, `${JSON.stringify({ apiToken: "present" })}\n`);
+    const prevHome = process.env.HOME;
+    process.env.HOME = dir;
     const prev = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
     try {
-      const result = await new Cli(configFixture(configPath)).invoke([
-        "config",
-        "set",
-        "port",
-        "9090",
-      ]);
+      const program = configFixture();
+      writeAppConfigFile(program, { apiToken: "seed" });
+      const result = await new Cli(program).invoke(["config", "set", "port", "9090"]);
       expect(result.exitCode).toBe(0);
-      const get = await new Cli(configFixture(configPath)).invoke(["config", "get", "port"]);
+      const get = await new Cli(program).invoke(["config", "get", "port"]);
       expect(get.stdout.trim()).toBe("9090");
     } finally {
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
       if (prev !== undefined) process.env.API_TOKEN = prev;
       rmSync(dir, { recursive: true, force: true });
     }

package/src/builtins/config.ts

@@ -5,7 +5,7 @@ Built-in `config get` / `config set` commands.
 import { bootstrapAppConfig } from "../config/bootstrap.ts";
 import { configEntrySensitive, defaultConfigEntryTitle } from "../config/entry.ts";
 import { writeAppConfigFile } from "../config/file.ts";
-import { exportConfigToEnv, resolveAppConfig } from "../config/resolve.ts";
+import { captureMappedHostEnv, exportConfigToEnv, resolveAppConfig } from "../config/resolve.ts";
 import { configPropertySchema, effectiveJsonSchema } from "../config/schema.ts";
 import { parseConfigSetValue } from "../config/validate.ts";
 import type { CliLeaf, CliOption, CliProgram, CliRouter } from "../types.ts";
@@ -128,11 +128,12 @@ function configSetRun(program: CliProgram, key: string, rawValue: string, useJso
     process.exit(1);
   }
 
+  const hostEnv = captureMappedHostEnv(program);
   const { fileData } = bootstrapAppConfig(program, { validateFile: true });
   const next = { ...fileData, [key]: parsed };
   writeAppConfigFile(program, next);
-  const resolved = resolveAppConfig(program, next);
-  exportConfigToEnv(program, resolved);
+  const resolved = resolveAppConfig(program, next, hostEnv);
+  exportConfigToEnv(program, resolved, hostEnv);
 }
 
 function configGetLeaf(program: CliProgram): CliLeaf {

package/src/builtins/install.ts

@@ -6,12 +6,13 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
   const opts: CliOption[] = [
     {
       name: "all",
-      description: "Install binary, completions, skills, and MCP config (when enabled).",
+      description:
+        "Install the default set (app, shell completions, and configuration when supported).",
       kind: CliOptionKind.Presence,
     },
     {
-      name: "bin",
-      description: "Copy this binary to your install directory (default ~/.local/bin).",
+      name: "app",
+      description: "Copy this app to your install directory (default ~/.local/bin).",
       kind: CliOptionKind.Presence,
     },
     {
@@ -22,40 +23,68 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
     },
     {
       name: "skill",
-      description: "Install Cursor and Claude Code skills when ~/.cursor or ~/.claude exists.",
+      description:
+        "Install agent skills for Cursor, Claude, and other supported AI tools on this machine.",
       kind: CliOptionKind.Presence,
     },
-    {
-      name: "reinstall",
-      description: "Reinstall artifacts already on disk (always includes the binary).",
+  ];
+
+  if (resolveCapabilities(root).mcp) {
+    opts.push({
+      name: "mcp",
+      description:
+        "Add MCP server configuration for Cursor, Claude Code, and other supported agents.",
       kind: CliOptionKind.Presence,
-    },
-    {
-      name: "from",
-      description: "Binary to copy (default: running executable). Used with --reinstall.",
-      kind: CliOptionKind.String,
-    },
+    });
+  }
+
+  if (root.appConfig) {
+    opts.push({
+      name: "configure",
+      description:
+        "Run the configuration wizard (install), or remove the config file (--uninstall).",
+      kind: CliOptionKind.Presence,
+    });
+  }
+
+  opts.push(
     {
       name: "status",
       description: "Print what is currently installed (read-only).",
       kind: CliOptionKind.Presence,
     },
+    {
+      name: "reinstall",
+      description: "Refresh everything already installed for this app.",
+      kind: CliOptionKind.Presence,
+    },
+  );
+
+  if (resolveCapabilities(root).update) {
+    opts.push({
+      name: "update",
+      description: "Download the latest release and refresh installed files.",
+      kind: CliOptionKind.Presence,
+    });
+  }
+
+  opts.push(
     {
       name: "uninstall",
       description:
-        "Remove installed artifacts (use --all or scoped flags; skips targets not on disk).",
+        "Remove installed files (--all removes everything; use individual flags to remove one category).",
       kind: CliOptionKind.Presence,
     },
     {
-      name: "prefix",
-      description:
-        "Install directory for the binary (default ~/.local/bin; overrides INSTALL_PREFIX).",
+      name: "from",
+      description: "App executable to copy (default: running executable). Used with --reinstall.",
       kind: CliOptionKind.String,
     },
     {
       name: "yes",
       description: "Skip the confirmation prompt.",
       kind: CliOptionKind.Presence,
+      shortName: "y",
     },
     {
       name: "dry",
@@ -67,43 +96,7 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
       description: "Print changed paths (install/update/uninstall) or status JSON on stdout.",
       kind: CliOptionKind.Presence,
     },
-    {
-      name: "quiet",
-      description:
-        "Suppress informational output (requires --yes, --json, --reinstall, or --update).",
-      kind: CliOptionKind.Presence,
-    },
-  ];
-
-  if (resolveCapabilities(root).mcp) {
-    opts.splice(4, 0, {
-      name: "mcp",
-      description: "Add or update MCP server entries in Cursor and Claude config files.",
-      kind: CliOptionKind.Presence,
-    });
-  }
-
-  if (resolveCapabilities(root).update) {
-    const statusIdx = opts.findIndex((o) => o.name === "status");
-    opts.splice(statusIdx, 0, {
-      name: "update",
-      description: "Download the latest release and reinstall installed artifacts.",
-      kind: CliOptionKind.Presence,
-    });
-  }
-
-  if (root.appConfig) {
-    opts.push({
-      name: "configure",
-      description: "Interactively write app config (~/.config/<key>/config).",
-      kind: CliOptionKind.Presence,
-    });
-    opts.push({
-      name: "config",
-      description: "Remove app config file (with --uninstall).",
-      kind: CliOptionKind.Presence,
-    });
-  }
+  );
 
   return opts;
 }
@@ -113,7 +106,7 @@ export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
   const app = root.key;
   const notesLines = [
     "First-time setup:",
-    `  ${app} install --all --yes`,
+    `  ${app} install --yes`,
     "",
     "Refresh after upgrading:",
     `  ${app} install --reinstall`,
@@ -135,9 +128,9 @@ export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
   return {
     key: "install",
     description:
-      "Install the binary, shell completions, agent skills, and MCP config to your user environment.",
-    notes: notesLines.join("\n"),
+      "Install this app, shell completions, agent skills, and MCP config on your machine.",
     options: installBuiltinOptions(root),
+    notes: notesLines.join("\n"),
     handler: () => {},
   };
 }

package/src/builtins/mcp.ts

@@ -28,7 +28,7 @@ export function cliBuiltinMcpCommand(program: CliProgram): CliRouter {
 
   const bundle: CliLeaf = {
     key: "bundle",
-    description: "Pack Claude Desktop `.mcpb` and Claude Code plugin zip from dist/<key>.",
+    description: "Pack dist MCP artifacts (`.mcpb`, Claude Code plugin zip) from dist/<key>.",
     handler: () => {},
   };
 

package/src/capabilities.ts

@@ -65,13 +65,13 @@ export type CapabilityFeature = "mcp" | "install" | "docs" | "config";
 export function capabilityDeniedMessage(feature: CapabilityFeature): string {
   switch (feature) {
     case "mcp":
-      return "MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n";
+      return "MCP is not available for this app.\n";
     case "install":
-      return "install is disabled. Remove install.enabled: false from the program root.\n";
+      return "Install is not available for this app.\n";
     case "docs":
-      return "docs is not enabled. Set docs: { enabled: true } on the program root.\n";
+      return "Documentation commands are not available for this app.\n";
     case "config":
-      return "config commands are disabled. Set program.appConfig or enable config.commands.\n";
+      return "Configuration commands are not available for this app.\n";
   }
 }
 

package/src/cli.ts

@@ -20,6 +20,7 @@ import { type AnyAppConfigSnapshot, createAppConfigSnapshot } from "./config/con
 import { effectiveJsonSchema } from "./config/schema.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
+import { maybeBootstrapInstallArgv } from "./install/bootstrap.ts";
 import { bootstrapMcpEnv } from "./mcp/env.ts";
 import { mcpServeStdioLoop } from "./mcp/server.ts";
 import { ParseKind, type ParseResult, parse, postParseValidate } from "./parse.ts";
@@ -94,6 +95,7 @@ export class Cli {
   }
 
   async run(argv: string[] = process.argv.slice(2)): Promise<never> {
+    argv = maybeBootstrapInstallArgv(argv, this.program);
     assertBuiltinAllowed(argv, this.caps);
 
     const prep = this.prepareDispatch(argv);