argsbarg 3.6.4 → 4.0.0

package/src/paths/host.ts

@@ -0,0 +1,40 @@
+/*
+Shared host path primitives for install, config, and skill modules.
+*/
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Resolves the user home directory (`$HOME` when set). */
+export function userHome(): string {
+  return process.env.HOME ?? homedir();
+}
+
+/** Expands a leading `~` or `~/` in a path using {@link userHome}. */
+export function expandTilde(path: string): string {
+  if (path.startsWith("~/")) {
+    return join(userHome(), path.slice(2));
+  }
+  if (path === "~") {
+    return userHome();
+  }
+  return path;
+}
+
+/** XDG config base directory (`$XDG_CONFIG_HOME` or `~/.config`). */
+export function xdgConfigHome(home = userHome()): string {
+  return process.env.XDG_CONFIG_HOME ?? join(home, ".config");
+}
+
+/** Windows `%APPDATA%` (or `~/AppData/Roaming`). */
+export function appDataHome(home = userHome()): string {
+  return process.env.APPDATA ?? join(home, "AppData", "Roaming");
+}
+
+/** OS-appropriate base directory for app config files. */
+export function appConfigHome(home = userHome()): string {
+  if (process.platform === "win32") {
+    return appDataHome(home);
+  }
+  return xdgConfigHome(home);
+}

package/src/schema.ts

@@ -13,7 +13,7 @@ import {
   leafOutputSchema,
 } from "./types.ts";
 
-const RESERVED = new Set(["completion", "install", "docs", "mcp", "version"]);
+const RESERVED = new Set(["completion", "install", "docs", "mcp", "version", "config"]);
 
 function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport | null {
   if (cmd.hidden) {

package/src/skill/generate.ts

@@ -2,6 +2,7 @@
 This module generates Agent Skills content (SKILL.md + reference.md) from a CLI schema.
 */
 
+import { defaultConfigEntryTitle } from "../config/entry.ts";
 import { generateApiGuide } from "../docs/api-guide.ts";
 import { collectMcpTools, type McpToolDef, sanitizeToolSegment } from "../mcp/tools.ts";
 import { collectOptionDefs } from "../parse.ts";
@@ -60,13 +61,24 @@ function formatCommandEntry(root: CliProgram, tool: McpToolDef): string {
   if (varargs.length > 0) {
     line += ` (varargs: ${varargs.map((p) => p.name).join(", ")})`;
   }
-  const env = tool.leaf.mcpTool?.requiresEnv;
-  if (env && env.length > 0) {
-    line += ` [requires env: ${env.join(", ")}]`;
-  }
   return line;
 }
 
+function buildConfigurationSection(root: CliProgram): string[] {
+  const schema = root.appConfig?.entries;
+  if (!schema || Object.keys(schema).length === 0) {
+    return [];
+  }
+  const lines = ["## Configuration", ""];
+  for (const [key, entry] of Object.entries(schema)) {
+    const label = entry.title ?? defaultConfigEntryTitle(key);
+    const envNote = entry.env ? ` (env: \`${entry.env}\`)` : "";
+    lines.push(`- **${label}** (\`${key}\`${envNote}) — ${entry.description}`);
+  }
+  lines.push("");
+  return lines;
+}
+
 /** Builds SKILL.md body for the given target. */
 function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): string {
   const name = sanitizeToolSegment(root.key);
@@ -104,11 +116,12 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     lines.push("");
   }
 
+  lines.push(...buildConfigurationSection(root));
+
   lines.push(
     "## Pitfalls",
     "",
     "- Pass `--` before arguments that look like flags.",
-    "- Commands marked `[requires env: ...]` need those variables set in the shell.",
     "",
     "## Reference",
     "",

package/src/skill/hint.ts

@@ -40,3 +40,21 @@ export function applySkillInstallHints(
     referenceMd: insertGeneratedHint(referenceMd, hint),
   };
 }
+
+/** Hint for `mcp bundle` plugin skill output. */
+export function skillBundleHint(program: CliProgram): string {
+  return generatedFileHtmlComment(`${program.key} mcp bundle`);
+}
+
+/** Applies bundle hints to SKILL.md (after frontmatter) and reference.md. */
+export function applySkillBundleHints(
+  program: CliProgram,
+  skillMd: string,
+  referenceMd: string,
+): { skillMd: string; referenceMd: string } {
+  const hint = skillBundleHint(program);
+  return {
+    skillMd: insertGeneratedHint(skillMd, hint, { afterFrontmatter: true }),
+    referenceMd: insertGeneratedHint(referenceMd, hint),
+  };
+}

package/src/skill/install.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { userHome } from "../paths/host.ts";
 import type { CliProgram } from "../types.ts";
 import { generateSkillBundle, type SkillTarget } from "./generate.ts";
 import { applySkillInstallHints } from "./hint.ts";
@@ -13,10 +13,6 @@ export interface SkillInstallOpts {
   dry?: boolean;
 }
 
-function userHome(): string {
-  return process.env.HOME ?? homedir();
-}
-
 function resolveSkillDir(target: SkillTarget, dirName: string, global: boolean): string {
   const base = global
     ? join(userHome(), target === "cursor" ? ".cursor" : ".claude", "skills")

package/src/test-fixtures.ts

@@ -0,0 +1,192 @@
+import type { CliProgram } from "./types.ts";
+import { CliFallbackMode, CliOptionKind } from "./types.ts";
+
+export function testProgram(
+  prog: Record<string, unknown> & { key: string; description: string },
+): CliProgram {
+  return { version: "0.0.0", ...prog } as CliProgram;
+}
+
+export const nestedMcpFixture = testProgram({
+  key: "nested.ts",
+  description: "Nested groups demo.",
+  version: "1.0.0",
+  mcpServer: { enabled: true },
+  commands: [
+    {
+      key: "stat",
+      description: "File metadata.",
+      options: [
+        {
+          name: "json",
+          description: "Emit handler output as JSON.",
+          kind: CliOptionKind.Presence,
+        },
+      ],
+      commands: [
+        {
+          key: "owner",
+          description: "Ownership helpers.",
+          commands: [
+            {
+              key: "lookup",
+              description: "Resolve owner info.",
+              options: [
+                {
+                  name: "user-name",
+                  description: "User to look up.",
+                  kind: CliOptionKind.String,
+                  shortName: "u",
+                },
+              ],
+              positionals: [
+                {
+                  name: "path",
+                  description: "File or directory.",
+                  kind: CliOptionKind.String,
+                },
+              ],
+              handler: () => {},
+            },
+          ],
+        },
+      ],
+    },
+    {
+      key: "read",
+      description: "Print the first line of each file.",
+      positionals: [
+        {
+          name: "files",
+          description: "Paths to read.",
+          kind: CliOptionKind.String,
+          argMax: 0,
+        },
+      ],
+      handler: () => {},
+    },
+    {
+      key: "hidden",
+      description: "Internal debug.",
+      mcpTool: { enabled: false },
+      handler: () => {},
+    },
+  ],
+  fallbackCommand: "read",
+  fallbackMode: CliFallbackMode.MissingOrUnknown,
+});
+
+/** Sends NDJSON MCP requests to a subprocess and collects responses by id. */
+export async function mcpRequest(
+  requests: object[],
+  opts?: { script?: string; env?: Record<string, string> },
+): Promise<Map<string | number, object>> {
+  const script = opts?.script ?? "examples/nested.ts";
+  const proc = Bun.spawn(["bun", "run", script, "mcp"], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+    env: opts?.env ? { ...process.env, ...opts.env } : process.env,
+  });
+
+  const input = requests.map((r) => `${JSON.stringify(r)}\n`).join("");
+  proc.stdin.write(input);
+  proc.stdin.end();
+
+  const timeout = setTimeout(() => proc.kill(), 10_000);
+  const stdout = await new Response(proc.stdout).text();
+  await proc.exited;
+  clearTimeout(timeout);
+
+  const byId = new Map<string | number, object>();
+  for (const line of stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const msg = JSON.parse(trimmed) as { id?: string | number };
+    if (msg.id !== undefined) {
+      byId.set(msg.id, msg);
+    }
+  }
+  return byId;
+}
+
+export const enumMcpFixture = testProgram({
+  key: "app",
+  description: "",
+  mcpServer: { enabled: true },
+  commands: [
+    {
+      key: "run",
+      description: "Run with mode.",
+      options: [
+        {
+          name: "mode",
+          description: "Mode.",
+          kind: CliOptionKind.Enum,
+          choices: ["dev", "prod"],
+          required: true,
+        },
+      ],
+      handler: () => {},
+    },
+  ],
+});
+
+export function varargsReadFixture(): CliProgram {
+  return testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "read",
+        description: "Read files.",
+        options: [
+          {
+            name: "json",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "files",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 0,
+            argMax: 0,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  });
+}
+
+export function nestedDocsFallbackFixture(): CliProgram {
+  return testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "docs",
+        description: "Documentation commands.",
+        fallbackCommand: "guide",
+        fallbackMode: CliFallbackMode.MissingOnly,
+        commands: [
+          {
+            key: "guide",
+            description: "User guide.",
+            handler: () => {},
+          },
+          {
+            key: "api",
+            description: "API reference.",
+            handler: () => {},
+          },
+        ],
+      },
+    ],
+  });
+}

package/src/types.ts

@@ -141,12 +141,6 @@ export interface CliMcpServerConfig {
    * and shell exports that MCP hosts (e.g. Cursor) don't inherit.
    */
   shellEnv?: boolean | string;
-  /**
-   * Path to a .env file loaded into process.env at MCP server start, after shellEnv.
-   * Supports `~` expansion. Warns on stderr if the file does not exist.
-   * Always overwrites — envFile is authoritative for its keys.
-   */
-  envFile?: string;
   /**
    * Custom MCP resources exposed alongside the built-in schema resource.
    * URIs must be unique and must not equal schemaResourceUri.
@@ -183,12 +177,6 @@ export interface CliMcpToolConfig {
    * Default: auto-generated from command path and description.
    */
   description?: string;
-  /**
-   * Environment variable names required at runtime.
-   * Appended to auto-generated MCP tool descriptions; enforced at tools/call time.
-   * Empty string counts as absent.
-   */
-  requiresEnv?: string[];
   /**
    * @deprecated Set `outputSchema` on the leaf command instead.
    */
@@ -210,6 +198,42 @@ export interface CliUpdateArtifact {
 /** Fetches the latest release binary for `install --update`. */
 export type CliUpdateGetLatest = (ctx: { version: string }) => Promise<CliUpdateArtifact>;
 
+/**
+ * Metadata overlay for one key in {@link CliAppConfig.entries}.
+ * Types and validation come from {@link CliAppConfig.jsonSchema} when set; otherwise all values are strings.
+ */
+export interface CliAppConfigEntry {
+  /** Help text for prompts, MCP manifests, and generated docs. */
+  description: string;
+  /** Short label in host UIs and CLI prompts. Default: the config key. */
+  title?: string;
+  /** Default when `jsonSchema` is omitted (all-string mode). */
+  default?: string;
+  /** When `false`, optional for bootstrap and MCP enforcement. Default: `true`. */
+  required?: boolean;
+  /**
+   * Mask stdin during prompts and redact on `config get`.
+   * Default: `/key|token|secret|password/i.test(name)`.
+   */
+  sensitive?: boolean;
+  /** When set: non-empty `process.env[env]` overrides file; value exported after resolve. */
+  env?: string;
+}
+
+/**
+ * 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; mcpSet?: boolean };
+  /** Block JSON Schema (draft-07). When omitted, synthesize all-string schema from `entries`. */
+  jsonSchema?: Record<string, unknown>;
+  /** Per-key metadata; keys must match `jsonSchema.properties` when `jsonSchema` is set. */
+  entries: Record<string, CliAppConfigEntry>;
+}
+
 export interface CliInstallConfig {
   /** When `false`, hide/disable `install` (default: enabled). */
   enabled?: boolean;
@@ -301,12 +325,14 @@ export type CliRouter = CliNodeBase & {
 export type CliNode = CliLeaf | CliRouter;
 
 /**
- * Program root passed to `cliRun` / `cliInvoke`.
+ * Program root passed to {@link Cli}.
  * May be a leaf or router, plus optional program-level MCP and install config.
  */
 export type CliProgram = CliNode & {
   /** Program version (printed by the `version` built-in and MCP serverInfo). */
   version: string;
+  /** Schema-driven app config file, bootstrap, and MCP metadata. */
+  appConfig?: CliAppConfig;
   /** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
   mcpServer?: CliMcpServerConfig;
   /** Opt-out and defaults for `install`. */

package/src/validate.ts

@@ -43,6 +43,67 @@ function validateDocsConfig(docs: import("./types.ts").CliDocsConfig): void {
   }
 }
 
+/** Validates `program.appConfig` on the program root. */
+function validateConfigBlock(appConfigBlock: import("./types.ts").CliAppConfig): void {
+  const entries = appConfigBlock.entries;
+  if (typeof entries !== "object" || entries === null || Array.isArray(entries)) {
+    throw new CliSchemaValidationError("program.appConfig.entries must be an object");
+  }
+
+  const envNames = new Set<string>();
+  for (const [key, entry] of Object.entries(entries)) {
+    if (key.length === 0) {
+      throw new CliSchemaValidationError(
+        "program.appConfig.entries keys must be non-empty strings",
+      );
+    }
+    if (entry === undefined || typeof entry !== "object") {
+      throw new CliSchemaValidationError(`program.appConfig.entries['${key}'] must be an object`);
+    }
+    const description = entry.description;
+    if (typeof description !== "string" || description.trim().length === 0) {
+      throw new CliSchemaValidationError(
+        `program.appConfig.entries['${key}'].description must be a non-empty string`,
+      );
+    }
+    if (entry.env !== undefined) {
+      if (typeof entry.env !== "string" || entry.env.length === 0) {
+        throw new CliSchemaValidationError(
+          `program.appConfig.entries['${key}'].env must be a non-empty string when set`,
+        );
+      }
+      if (envNames.has(entry.env)) {
+        throw new CliSchemaValidationError(`Duplicate program.appConfig env mapping: ${entry.env}`);
+      }
+      envNames.add(entry.env);
+    }
+  }
+
+  const jsonSchema = appConfigBlock.jsonSchema;
+  if (jsonSchema !== undefined) {
+    if (typeof jsonSchema !== "object" || jsonSchema === null || Array.isArray(jsonSchema)) {
+      throw new CliSchemaValidationError(
+        "program.appConfig.jsonSchema must be a JSON Schema object (not null or an array)",
+      );
+    }
+    const properties = jsonSchema.properties;
+    if (properties !== undefined) {
+      if (typeof properties !== "object" || properties === null || Array.isArray(properties)) {
+        throw new CliSchemaValidationError(
+          "program.appConfig.jsonSchema.properties must be an object when set",
+        );
+      }
+      for (const key of Object.keys(entries)) {
+        if (!(key in properties)) {
+          throw new CliSchemaValidationError(
+            `program.appConfig.entries key '${key}' is missing from jsonSchema.properties`,
+          );
+        }
+      }
+    }
+  }
+}
+
 /** Validates a program schema. */
 export function cliValidateProgram(program: CliProgram): void {
   if (!program.version || program.version.trim().length === 0) {
@@ -65,6 +126,10 @@ export function cliValidateProgram(program: CliProgram): void {
     validateDocsConfig(program.docs);
   }
 
+  if (program.appConfig !== undefined) {
+    validateConfigBlock(program.appConfig);
+  }
+
   if (program.install?.updateGetLatest !== undefined) {
     if (program.install.enabled === false) {
       throw new CliSchemaValidationError(
@@ -108,6 +173,11 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
         `docs is only supported on the program root (not on ${node.key})`,
       );
     }
+    if (rogue.appConfig !== undefined) {
+      throw new CliSchemaValidationError(
+        `appConfig is only supported on the program root (not on ${node.key})`,
+      );
+    }
   }
 
   if (isCliLeaf(node)) {

package/src/completion.ts

@@ -1,13 +0,0 @@
-/*
-Re-export shim — completion emitters and built-in trees live in ./builtins/.
-*/
-
-export {
-  cliBuiltinCompletionGroup,
-  cliBuiltinInstallCommand,
-  cliBuiltinMcpCommand,
-  cliPresentationRoot,
-  completionBashScript,
-  completionFishScript,
-  completionZshScript,
-} from "./builtins/index.ts";