argsbarg 3.6.4 → 4.0.0

package/src/builtins/config.ts

@@ -0,0 +1,220 @@
+/*
+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 { configPropertySchema, effectiveJsonSchema } from "../config/schema.ts";
+import { parseConfigSetValue } from "../config/validate.ts";
+import type { CliLeaf, CliOption, CliProgram, CliRouter } from "../types.ts";
+import { CliOptionKind } from "../types.ts";
+
+const JSON_OPTION: CliOption = {
+  name: "json",
+  description: "Emit JSON (compact).",
+  kind: CliOptionKind.Presence,
+};
+
+const PRETTY_OPTION: CliOption = {
+  name: "pretty",
+  description: "Pretty-print JSON (requires --json).",
+  kind: CliOptionKind.Presence,
+};
+
+function configGetOutput(
+  program: CliProgram,
+  key: string | undefined,
+  json: boolean,
+  pretty: boolean,
+): void {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return;
+  }
+  const { resolved } = bootstrapAppConfig(program, { validateFile: true });
+  const entries = appConfig.entries;
+
+  if (key !== undefined) {
+    if (!(key in entries)) {
+      process.stderr.write(`Unknown configuration key: ${key}\n`);
+      process.exit(1);
+    }
+    const entry = entries[key];
+    if (!entry) {
+      process.exit(1);
+    }
+    const value = resolved[key];
+    if (json) {
+      const out =
+        configEntrySensitive(key, entry) && value !== undefined && String(value).length > 0
+          ? { set: true }
+          : (value ?? null);
+      const space = pretty ? 2 : undefined;
+      process.stdout.write(`${JSON.stringify(out, null, space)}\n`);
+      return;
+    }
+    if (configEntrySensitive(key, entry)) {
+      const set = value !== undefined && value !== null && String(value).length > 0;
+      process.stdout.write(set ? "REDACTED\n" : "(not set)\n");
+      return;
+    }
+    if (value === undefined) {
+      process.stdout.write("(not set)\n");
+      return;
+    }
+    if (typeof value === "object") {
+      process.stdout.write(`${JSON.stringify(value)}\n`);
+      return;
+    }
+    process.stdout.write(`${String(value)}\n`);
+    return;
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [k, entry] of Object.entries(entries)) {
+    const value = resolved[k];
+    if (configEntrySensitive(k, entry)) {
+      out[k] =
+        value !== undefined && value !== null && String(value).length > 0
+          ? json
+            ? { set: true }
+            : "REDACTED"
+          : json
+            ? null
+            : "(not set)";
+    } else {
+      out[k] = value ?? (json ? null : "(not set)");
+    }
+  }
+
+  if (json) {
+    const space = pretty ? 2 : undefined;
+    process.stdout.write(`${JSON.stringify(out, null, space)}\n`);
+    return;
+  }
+
+  for (const [k, v] of Object.entries(out)) {
+    const title = entries[k]?.title ?? defaultConfigEntryTitle(k);
+    process.stdout.write(`${title}: ${String(v)}\n`);
+  }
+}
+
+function configSetRun(program: CliProgram, key: string, rawValue: string, useJson: boolean): void {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return;
+  }
+  const entries = appConfig.entries;
+  if (!(key in entries)) {
+    process.stderr.write(`Unknown configuration key: ${key}\n`);
+    process.exit(1);
+  }
+
+  const jsonSchema = effectiveJsonSchema(program);
+  if (!jsonSchema) {
+    process.stderr.write("Internal error: missing effective jsonSchema.\n");
+    process.exit(1);
+  }
+
+  const propSchema = configPropertySchema(jsonSchema, key);
+  let parsed: unknown;
+  try {
+    parsed = parseConfigSetValue(rawValue, propSchema, jsonSchema, useJson);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${msg}\n`);
+    process.exit(1);
+  }
+
+  const { fileData } = bootstrapAppConfig(program, { validateFile: true });
+  const next = { ...fileData, [key]: parsed };
+  writeAppConfigFile(program, next);
+  const resolved = resolveAppConfig(program, next);
+  exportConfigToEnv(program, resolved);
+}
+
+function configGetLeaf(program: CliProgram): CliLeaf {
+  return {
+    key: "get",
+    description: "Print resolved configuration value(s).",
+    options: [JSON_OPTION, PRETTY_OPTION],
+    positionals: [
+      {
+        name: "key",
+        description: "Schema key to read (omit for all keys).",
+        kind: CliOptionKind.String,
+        argMin: 0,
+        argMax: 1,
+      },
+    ],
+    handler: (ctx) => {
+      const key = ctx.args[0];
+      configGetOutput(program, key, ctx.hasFlag("json"), ctx.hasFlag("pretty"));
+    },
+  };
+}
+
+function configSetLeaf(program: CliProgram, mcpSetEnabled: boolean): CliLeaf {
+  return {
+    key: "set",
+    description: "Write one configuration key to the config file.",
+    options: [JSON_OPTION],
+    mcpTool: mcpSetEnabled ? undefined : { enabled: false },
+    positionals: [
+      {
+        name: "key",
+        description: "Schema key to write.",
+        kind: CliOptionKind.String,
+        argMin: 1,
+        argMax: 1,
+      },
+      {
+        name: "value",
+        description: "Value to store (use --json for objects/arrays).",
+        kind: CliOptionKind.String,
+        argMin: 0,
+        argMax: 1,
+      },
+    ],
+    handler: (ctx) => {
+      const key = ctx.args[0];
+      if (!key) {
+        process.stderr.write("config set requires a key.\n");
+        process.exit(1);
+      }
+      const raw = ctx.args[1];
+      if (raw === undefined || raw.length === 0) {
+        if (!ctx.hasFlag("json")) {
+          process.stderr.write("config set requires a value (or --json).\n");
+          process.exit(1);
+        }
+        process.stderr.write("config set requires a value.\n");
+        process.exit(1);
+      }
+      configSetRun(program, key, raw, ctx.hasFlag("json"));
+    },
+  };
+}
+
+import { configCommandsEnabled, configMcpSetEnabled } from "../config/entry.ts";
+
+/** Built-in `config` router when program.appConfig is set. */
+export function cliBuiltinConfigGroup(program: CliProgram): CliRouter {
+  if (!program.appConfig) {
+    throw new Error("config not enabled");
+  }
+  return {
+    key: "config",
+    description: "Read or write app configuration.",
+    commands: [configGetLeaf(program), configSetLeaf(program, configMcpSetEnabled(program))],
+  };
+}
+
+export function cliBuiltinConfigGroupIfEnabled(program: CliProgram): CliRouter | undefined {
+  if (!configCommandsEnabled(program)) {
+    return undefined;
+  }
+  return cliBuiltinConfigGroup(program);
+}

package/src/builtins/dispatch.ts

@@ -1,8 +1,8 @@
-import { resolveCapabilities } from "../capabilities.ts";
+import { capabilityDeniedMessage, resolveCapabilities } from "../capabilities.ts";
+import { Cli } from "../cli.ts";
 import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 import { cliInstall } from "../install/index.ts";
 import { runMcpBundle } from "../mcp/bundle.ts";
-import { cliMcpServeStdio } from "../mcp.ts";
 import type { ParseResult } from "../parse.ts";
 import { ParseKind } from "../parse.ts";
 import type { CliNode, CliProgram, CliRouter } from "../types.ts";
@@ -11,6 +11,7 @@ import { completionBashScript } from "./completion-bash.ts";
 import { completionFishScript } from "./completion-fish.ts";
 import { cliBuiltinCompletionGroup as completionGroup } from "./completion-group.ts";
 import { completionZshScript } from "./completion-zsh.ts";
+import { cliBuiltinConfigGroupIfEnabled } from "./config.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliPresentationRoot } from "./presentation.ts";
@@ -70,14 +71,12 @@ export async function dispatchBuiltin(
 
   if (pr.path[0] === "mcp") {
     if (!caps.mcp) {
-      process.stderr.write(
-        "MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n",
-      );
+      process.stderr.write(capabilityDeniedMessage("mcp"));
       process.exit(1);
     }
     const sub = pr.path[1];
     if (pr.path.length === 1 || sub === "serve") {
-      await cliMcpServeStdio(program);
+      await new Cli(program).serveMcp();
       process.exit(0);
     }
     if (pr.path.length === 2 && sub === "bundle") {
@@ -95,9 +94,7 @@ export async function dispatchBuiltin(
 
   if (pr.path[0] === "install") {
     if (!caps.install) {
-      process.stderr.write(
-        "install is disabled. Remove install.enabled: false from the program root.\n",
-      );
+      process.stderr.write(capabilityDeniedMessage("install"));
       process.exit(1);
     }
     if (pr.path.length !== 1) {
@@ -176,5 +173,17 @@ export function builtinInterceptRoot(
     };
   }
 
+  const configGroup = cliBuiltinConfigGroupIfEnabled(program);
+  if (first === "config" && configGroup) {
+    return {
+      parseRoot: {
+        key: program.key,
+        description: program.description,
+        commands: [configGroup],
+      },
+      isLeafCompletionIntercept: false,
+    };
+  }
+
   return { parseRoot: program, isLeafCompletionIntercept: false };
 }

package/src/builtins/export.ts

@@ -1,19 +1,15 @@
-import { type CliCapabilities, resolveCapabilities } from "../capabilities.ts";
-import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
+import { resolveCapabilities } from "../capabilities.ts";
 import { visibleOptions } from "../hidden.ts";
 import type { CliFallbackMode, CliNode, CliOption, CliPositional, CliProgram } from "../types.ts";
 import { isCliRouter } from "../types.ts";
-import { cliBuiltinCompletionGroup } from "./completion-group.ts";
-import { cliBuiltinInstallCommand } from "./install.ts";
-import { cliBuiltinMcpCommand } from "./mcp.ts";
-import { cliBuiltinVersionCommand } from "./version.ts";
+import { resolveBuiltins } from "./registry.ts";
 
 /** JSON-safe command node (no handlers). */
 export interface CliSchemaExport {
   key: string;
   description: string;
   notes?: string;
-  /** JSON Schema for structured stdout when set on the leaf `mcpTool`. */
+  /** JSON Schema for structured stdout when set on the leaf. */
   outputSchema?: Record<string, unknown>;
   options?: CliOption[];
   fallbackCommand?: string;
@@ -55,31 +51,10 @@ function exportBuiltinNode(cmd: CliNode): CliSchemaExport | null {
   return out;
 }
 
-function pushExportedBuiltin(builtins: CliSchemaExport[], cmd: CliNode): void {
-  const node = exportBuiltinNode(cmd);
-  if (node) {
-    builtins.push(node);
-  }
-}
-
 /** Built-in subtrees matching help visibility for `--schema` export. */
-export function exportPresentationBuiltins(
-  program: CliProgram,
-  caps?: CliCapabilities,
-): CliSchemaExport[] {
-  const resolved = caps ?? resolveCapabilities(program);
-  const builtins: CliSchemaExport[] = [];
-  pushExportedBuiltin(builtins, cliBuiltinCompletionGroup(program));
-  pushExportedBuiltin(builtins, cliBuiltinVersionCommand());
-  if (resolved.install) {
-    pushExportedBuiltin(builtins, cliBuiltinInstallCommand(program));
-  }
-  const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
-  if (docsGroup) {
-    pushExportedBuiltin(builtins, docsGroup);
-  }
-  if (resolved.mcp) {
-    pushExportedBuiltin(builtins, cliBuiltinMcpCommand(program));
-  }
-  return builtins;
+export function exportPresentationBuiltins(program: CliProgram): CliSchemaExport[] {
+  const caps = resolveCapabilities(program);
+  return resolveBuiltins(program, caps)
+    .map((cmd) => exportBuiltinNode(cmd))
+    .filter((node): node is CliSchemaExport => node !== null);
 }

package/src/builtins/index.ts

@@ -12,4 +12,5 @@ export {
   parseBuiltins,
   presentationBuiltins,
 } from "./presentation.ts";
+export { resolveBuiltins } from "./registry.ts";
 export { collectScopes, type ScopeRec } from "./scopes.ts";

package/src/builtins/install.ts

@@ -92,6 +92,19 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
     });
   }
 
+  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;
 }
 

package/src/builtins/mcp.ts

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

package/src/builtins/presentation.ts

@@ -1,28 +1,13 @@
 import type { CliCapabilities } from "../capabilities.ts";
 import { resolveCapabilities } from "../capabilities.ts";
-import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 import { presentationNode, visibleOptions } from "../hidden.ts";
 import type { CliLeaf, CliNode, CliProgram, CliRouter } from "../types.ts";
 import { isCliLeaf } from "../types.ts";
-import { cliBuiltinCompletionGroup } from "./completion-group.ts";
-import { cliBuiltinInstallCommand } from "./install.ts";
-import { cliBuiltinMcpCommand } from "./mcp.ts";
-import { cliBuiltinVersionCommand } from "./version.ts";
+import { resolveBuiltins } from "./registry.ts";
 
 /** All built-in command nodes for argv parsing (includes hidden builtins). */
 export function parseBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
-  const builtins: CliNode[] = [cliBuiltinCompletionGroup(program), cliBuiltinVersionCommand()];
-  if (caps.install) {
-    builtins.push(cliBuiltinInstallCommand(program));
-  }
-  const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
-  if (docsGroup) {
-    builtins.push(docsGroup);
-  }
-  if (caps.mcp) {
-    builtins.push(cliBuiltinMcpCommand(program));
-  }
-  return builtins;
+  return resolveBuiltins(program, caps);
 }
 
 /** Built-in subtrees visible in help, schema, and completions (hidden builtins omitted). */

package/src/builtins/registry.ts

@@ -0,0 +1,40 @@
+import type { CliCapabilities } from "../capabilities.ts";
+import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
+import type { CliNode, CliProgram } from "../types.ts";
+import { cliBuiltinCompletionGroup } from "./completion-group.ts";
+import { cliBuiltinConfigGroupIfEnabled } from "./config.ts";
+import { cliBuiltinInstallCommand } from "./install.ts";
+import { cliBuiltinMcpCommand } from "./mcp.ts";
+import { cliBuiltinVersionCommand } from "./version.ts";
+
+type BuiltinFactory = (program: CliProgram) => CliNode | null;
+
+function pushBuiltin(
+  builtins: CliNode[],
+  program: CliProgram,
+  factory: BuiltinFactory | null,
+): void {
+  if (!factory) {
+    return;
+  }
+  const node = factory(program);
+  if (node) {
+    builtins.push(node);
+  }
+}
+
+/** Capability-gated built-in command nodes in stable order (parse, help, export). */
+export function resolveBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
+  const builtins: CliNode[] = [];
+  pushBuiltin(builtins, program, (p) => cliBuiltinCompletionGroup(p));
+  pushBuiltin(builtins, program, () => cliBuiltinVersionCommand());
+  if (caps.install) {
+    pushBuiltin(builtins, program, (p) => cliBuiltinInstallCommand(p));
+  }
+  pushBuiltin(builtins, program, (p) => cliBuiltinDocsGroupIfEnabled(p) ?? null);
+  if (caps.mcp) {
+    pushBuiltin(builtins, program, (p) => cliBuiltinMcpCommand(p));
+  }
+  pushBuiltin(builtins, program, (p) => cliBuiltinConfigGroupIfEnabled(p) ?? null);
+  return builtins;
+}

package/src/capabilities.ts

@@ -3,6 +3,7 @@ Internal capability resolver — decides which platform builtins are active for
 Not exported from the public package barrel.
 */
 
+import { configCommandsEnabled } from "./config/entry.ts";
 import type { CliProgram } from "./types.ts";
 
 /** Platform builtins derived from program config and runtime. */
@@ -12,6 +13,7 @@ export interface CliCapabilities {
   install: boolean;
   docs: boolean;
   update: boolean;
+  configCommands: boolean;
 }
 
 /** Resolves which capabilities are enabled for a program. */
@@ -23,6 +25,7 @@ export function resolveCapabilities(program: CliProgram): CliCapabilities {
     install,
     docs: program.docs?.enabled === true,
     update: install && typeof program.install?.updateGetLatest === "function",
+    configCommands: configCommandsEnabled(program),
   };
 }
 
@@ -38,5 +41,48 @@ export function reservedCommandNames(caps: CliCapabilities): string[] {
   if (caps.mcp) {
     names.push("mcp");
   }
+  if (caps.configCommands) {
+    names.push("config");
+  }
   return names;
 }
+
+export type CapabilityFeature = "mcp" | "install" | "docs" | "config";
+
+/** Stderr message when a disabled built-in is invoked from the CLI. */
+export function capabilityDeniedMessage(feature: CapabilityFeature): string {
+  switch (feature) {
+    case "mcp":
+      return "MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n";
+    case "install":
+      return "install is disabled. Remove install.enabled: false from the program root.\n";
+    case "docs":
+      return "docs is not enabled. Set docs: { enabled: true } on the program root.\n";
+    case "config":
+      return "config commands are disabled. Set program.appConfig or enable config.commands.\n";
+  }
+}
+
+/** Exit 1 when argv[0] names a built-in that capabilities disallow. */
+export function assertBuiltinAllowed(argv: string[], caps: CliCapabilities): void {
+  if (argv.length < 1) {
+    return;
+  }
+  const first = argv[0];
+  if (first === "mcp" && !caps.mcp) {
+    process.stderr.write(capabilityDeniedMessage("mcp"));
+    process.exit(1);
+  }
+  if (first === "install" && !caps.install) {
+    process.stderr.write(capabilityDeniedMessage("install"));
+    process.exit(1);
+  }
+  if (first === "docs" && !caps.docs) {
+    process.stderr.write(capabilityDeniedMessage("docs"));
+    process.exit(1);
+  }
+  if (first === "config" && !caps.configCommands) {
+    process.stderr.write(capabilityDeniedMessage("config"));
+    process.exit(1);
+  }
+}

package/src/cli-errors.ts

@@ -0,0 +1,15 @@
+/*
+Handler error helper with contextual help.
+*/
+
+import { cliPresentationRoot } from "./builtins/presentation.ts";
+import type { CliContext } from "./context.ts";
+import { cliHelpRender } from "./help.ts";
+
+export function cliErrWithHelp(ctx: CliContext, msg: string): never {
+  const color = process.stderr.isTTY;
+  const line = color ? `\u001B[31m${msg}\u001B[0m` : msg;
+  process.stderr.write(`${line}\n`);
+  process.stderr.write(cliHelpRender(cliPresentationRoot(ctx.program), ctx.commandPath, true));
+  process.exit(1);
+}