argsbarg 3.6.4 → 4.0.0

package/examples/consumer-app/bun.lock

@@ -0,0 +1,75 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "consumer-app-example",
+      "dependencies": {
+        "argsbarg": "file:../..",
+      },
+      "devDependencies": {
+        "ts-json-schema-generator": "^2.3.0",
+        "typescript": "^5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@biomejs/biome": ["@biomejs/biome@2.5.1", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.1", "@biomejs/cli-darwin-x64": "2.5.1", "@biomejs/cli-linux-arm64": "2.5.1", "@biomejs/cli-linux-arm64-musl": "2.5.1", "@biomejs/cli-linux-x64": "2.5.1", "@biomejs/cli-linux-x64-musl": "2.5.1", "@biomejs/cli-win32-arm64": "2.5.1", "@biomejs/cli-win32-x64": "2.5.1" }, "bin": { "biome": "bin/biome" } }, "sha512-IXWLCxKmae+rI7LOHS1B3EbVisQ6GRAWbhN9msa6KjNCyFWrvKZWR4oUdinaNssrV852OrSHuSPa95h1GPJc7Q=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-npqDzvqv7vFaWRiNN1Te71siRgPaqS9MpqgYCdP/CrUbkJ7ApezaeaKjueKHRN/JH/6lRjJQAHi8acQDCAz22w=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-RgwTqPAM8g2tn1j+b5oRjF/DbSBX8a4gwojtuG9XuhfK7GgomvZ9+T+tqjXiVbjLEeGJOoL6VEk8mvRTVeSybw=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-yhV35CzZh38VyMvTEXi3JTjxZBs++oCKK9KG8vB6VI5+uvQvZNR3BFWEKKzuOmx9DJJj7sQpZ4LQJcmbGTs3+Q=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-WMcvMLgByyTqVxGlq918NBBYliq9FRR9GAQVETHb+VjGVqXCZFfHlZHC1FX4ibuYY/Hg6TJE3rHU0xVrdJXNRw=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.1", "", { "os": "linux", "cpu": "x64" }, "sha512-J/7uHSX7NfoYDI7HijAkd8lnQIOrRb2W7j3X+tw4R+N5ExvXGsyXFiGdQcfcxfOmNQmZVSQOCDk757fwpzqQcg=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.1", "", { "os": "linux", "cpu": "x64" }, "sha512-ANTowtlLmPYm5yeMckWY8Xzb9Ix+JJP3tgHR/n6xRj1VWyIzzWtfRfih9hv9VmClwadpBvZduISZIbBsIlYG3A=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-zgXnKNgWPC4iPF7Y1lR3STUeCUuZRpD6IiOrC7TZTlh0Lx6FiVUT05myuMQHQ9D+1cc7uyMldi4forE6lp0ivQ=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.1", "", { "os": "win32", "cpu": "x64" }, "sha512-6uxpR9hvaglANkZemeSiN/FhYgkGasrEGn267eXIWvjrjJ2LhDlk251IhjVJq6MXzkV2/bcXwLwSroLyPtqRZg=="],
+
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
+    "@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
+
+    "@types/node": ["@types/node@26.0.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA=="],
+
+    "argsbarg": ["argsbarg@file:../..", { "devDependencies": { "@biomejs/biome": "^2.5.0", "@types/bun": "^1.3.12", "typescript": "^5.9.3" }, "bin": { "argsbarg": "src/index.ts" } }],
+
+    "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
+
+    "brace-expansion": ["brace-expansion@5.0.6", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
+
+    "glob": ["glob@13.0.6", "", { "dependencies": { "minimatch": "^10.2.2", "minipass": "^7.1.3", "path-scurry": "^2.0.2" } }, "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw=="],
+
+    "json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
+
+    "lru-cache": ["lru-cache@11.5.1", "", {}, "sha512-RPimw/7aMdv2oqRrxKwvZXcPfwBrn/JZ2xYcY9Hus/6LaS3VOAKVWKWgNLCFSiOm1ESXinjsDlidVU7JlnCN2A=="],
+
+    "minimatch": ["minimatch@10.2.5", "", { "dependencies": { "brace-expansion": "^5.0.5" } }, "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg=="],
+
+    "minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
+
+    "normalize-path": ["normalize-path@3.0.0", "", {}, "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA=="],
+
+    "path-scurry": ["path-scurry@2.0.2", "", { "dependencies": { "lru-cache": "^11.0.0", "minipass": "^7.1.2" } }, "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg=="],
+
+    "safe-stable-stringify": ["safe-stable-stringify@2.5.0", "", {}, "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA=="],
+
+    "ts-json-schema-generator": ["ts-json-schema-generator@2.9.0", "", { "dependencies": { "@types/json-schema": "^7.0.15", "commander": "^14.0.3", "glob": "^13.0.6", "json5": "^2.2.3", "normalize-path": "^3.0.0", "safe-stable-stringify": "^2.5.0", "tslib": "^2.8.1", "typescript": "^5.9.3" }, "bin": { "ts-json-schema-generator": "bin/ts-json-schema-generator.js" } }, "sha512-NR5ZE108uiPtBHBJNGnhwoUaUx5vWTDJzDFG9YlRoqxPU76n+5FClRh92dcGgysbe1smRmYalM9Saj97GW1J4Q=="],
+
+    "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+  }
+}

package/examples/consumer-app/capabilities.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveCapabilities } from "../../src/capabilities.ts";
+import { CliOptionKind, type CliProgram } from "../../src/types.ts";
+
+const programSource = readFileSync(join(import.meta.dir, "src/program.ts"), "utf8");
+
+/** Mirror of consumer-app/src/program.ts capability flags (in-repo types only). */
+const sinkProgram = {
+  key: "consumer-app",
+  version: "1.0.0",
+  description: "Sink reference.",
+  appConfig: {
+    entries: {
+      apiToken: { description: "Token.", env: "CONSUMER_APP_API_TOKEN" },
+    },
+  },
+  docs: {
+    enabled: true,
+    topics: { readme: { text: "# readme\n" } },
+  },
+  mcpServer: { enabled: true },
+  install: {
+    updateGetLatest: async () => ({ path: "/bin/app", version: "1.0.0" }),
+  },
+  commands: [
+    {
+      key: "status",
+      description: "Status.",
+      handler: () => {},
+    },
+    {
+      key: "echo",
+      description: "Echo.",
+      options: [
+        {
+          name: "message",
+          description: "Message.",
+          kind: CliOptionKind.String,
+          required: true,
+        },
+      ],
+      handler: () => {},
+    },
+  ],
+} satisfies CliProgram;
+
+describe("consumer-app sink", () => {
+  test("program source enables every builtin flag", () => {
+    expect(programSource).toContain("mcpServer: {");
+    expect(programSource).toContain("enabled: true");
+    expect(programSource).toContain("docs:");
+    expect(programSource).toContain("updateGetLatest");
+    expect(programSource).toContain("appConfig:");
+    expect(programSource).toContain("outputSchema:");
+  });
+
+  test("resolveCapabilities matches full sink shape", () => {
+    expect(resolveCapabilities(sinkProgram)).toEqual({
+      completion: true,
+      mcp: true,
+      install: true,
+      docs: true,
+      update: true,
+      configCommands: true,
+    });
+  });
+});

package/examples/consumer-app/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "consumer-app-example",
+  "private": true,
+  "type": "module",
+  "description": "Argsbarg kitchen-sink reference app (copy template; not published to npm).",
+  "scripts": {
+    "schemagen": "bun run scripts/schemagen.ts",
+    "start": "bun run src/main.ts"
+  },
+  "dependencies": {
+    "argsbarg": "file:../.."
+  },
+  "devDependencies": {
+    "ts-json-schema-generator": "^2.3.0",
+    "typescript": "^5.9.3"
+  }
+}

package/examples/consumer-app/schemas/configSchemas.ts

@@ -0,0 +1,6 @@
+// Auto-generated by scripts/schemagen.ts — do not edit by hand.
+
+import app_config from "./generated/app-config.json";
+
+/** JSON Schema for program.appConfig.jsonSchema from `AppConfig`. */
+export const APP_CONFIG_JSON_SCHEMA = app_config as Record<string, unknown>;

package/examples/consumer-app/schemas/generated/app-config.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "apiToken": {
+      "type": "string",
+      "description": "API token from the provider dashboard."
+    },
+    "defaultRegion": {
+      "type": "string",
+      "description": "AWS region (default us-east-1).",
+      "default": "us-east-1"
+    },
+    "maxRetries": {
+      "type": "number",
+      "description": "HTTP retry count (default 3).",
+      "default": 3
+    },
+    "prefs": {
+      "type": "object",
+      "properties": {
+        "ttl": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "ttl"
+      ],
+      "additionalProperties": false,
+      "description": "Local preferences (file-only; not mapped to process.env)."
+    }
+  },
+  "required": [
+    "apiToken",
+    "maxRetries"
+  ],
+  "additionalProperties": false,
+  "description": "Config schema\n\nApplication settings for `consumer-app` (`program.appConfig`).",
+  "definitions": {}
+}

package/examples/consumer-app/schemas/generated/status.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "defaultRegion": {
+      "type": "string",
+      "description": "Resolved AWS region."
+    },
+    "maxRetries": {
+      "type": "number",
+      "description": "Resolved retry count."
+    },
+    "apiTokenSet": {
+      "type": "boolean",
+      "description": "Whether apiToken is set (value never included)."
+    },
+    "version": {
+      "type": "string",
+      "description": "App version from program root."
+    }
+  },
+  "required": [
+    "apiTokenSet",
+    "version"
+  ],
+  "description": "JSON payload for `consumer-app status --json`.",
+  "definitions": {}
+}

package/examples/consumer-app/schemas/outputSchemas.ts

@@ -0,0 +1,6 @@
+// Auto-generated by scripts/schemagen.ts — do not edit by hand.
+
+import status from "./generated/status.json";
+
+/** JSON Schema for leaf outputSchema from `StatusJsonOutput`. */
+export const STATUS_JSON_OUTPUT_SCHEMA = status as Record<string, unknown>;

package/examples/consumer-app/scripts/schemagen/discover-schema-roots.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { discoverSchemaRoots } from "./discover-schema-roots.ts";
+
+const projectRoot = join(import.meta.dir, "../..");
+
+describe("discover-schema-roots", () => {
+  test("finds AppConfig and StatusJsonOutput in src types.ts files", () => {
+    const roots = discoverSchemaRoots(projectRoot);
+    const config = roots.find((r) => r.kind === "config");
+    const output = roots.find((r) => r.kind === "output");
+    expect(config).toMatchObject({
+      typeName: "AppConfig",
+      relFile: "src/types.ts",
+      outfile: "app-config.json",
+      exportName: "APP_CONFIG_JSON_SCHEMA",
+    });
+    expect(output).toMatchObject({
+      typeName: "StatusJsonOutput",
+      relFile: "src/commands/status/types.ts",
+      outfile: "status.json",
+      exportName: "STATUS_JSON_OUTPUT_SCHEMA",
+    });
+  });
+});

package/examples/consumer-app/scripts/schemagen/discover-schema-roots.ts

@@ -0,0 +1,93 @@
+/*
+Discovers schema roots in src (recursive) types.ts files by JSDoc markers.
+Copy per consumer repo — see docs/output-schema.md and docs/config-schema.md.
+*/
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import {
+  configSchemaExportName,
+  outfileForConfigType,
+  outfileForOutputType,
+  outputSchemaExportName,
+} from "./naming.ts";
+
+export type SchemaRootKind = "config" | "output";
+
+export interface SchemaRoot {
+  kind: SchemaRootKind;
+  typeName: string;
+  /** Path relative to project root (e.g. src/types.ts). */
+  relFile: string;
+  outfile: string;
+  exportName: string;
+}
+
+const CONFIG_MARKER = "Config schema";
+const OUTPUT_MARKER = "JSON payload";
+
+const INTERFACE_RE = /\/\*\*([\s\S]*?)\*\/\s*export\s+interface\s+(\w+)/g;
+
+function listTypesTsFiles(srcDir: string, baseDir: string, out: string[]): void {
+  for (const ent of readdirSync(srcDir)) {
+    const full = join(srcDir, ent);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      listTypesTsFiles(full, baseDir, out);
+      continue;
+    }
+    if (ent === "types.ts") {
+      out.push(relative(baseDir, full));
+    }
+  }
+}
+
+function classifyRoot(jsDoc: string, typeName: string, relFile: string): SchemaRoot | undefined {
+  const hasConfig = jsDoc.includes(CONFIG_MARKER);
+  const hasOutput = jsDoc.includes(OUTPUT_MARKER);
+  if (hasConfig && hasOutput) {
+    throw new Error(`${relFile}: ${typeName} has both Config schema and JSON payload markers`);
+  }
+  if (!hasConfig && !hasOutput) {
+    return undefined;
+  }
+  if (hasConfig) {
+    return {
+      kind: "config",
+      typeName,
+      relFile,
+      outfile: outfileForConfigType(typeName),
+      exportName: configSchemaExportName(typeName),
+    };
+  }
+  return {
+    kind: "output",
+    typeName,
+    relFile,
+    outfile: outfileForOutputType(typeName),
+    exportName: outputSchemaExportName(typeName),
+  };
+}
+
+/** Find all schema roots under `src/` in files named types.ts. */
+export function discoverSchemaRoots(projectRoot: string): SchemaRoot[] {
+  const srcDir = join(projectRoot, "src");
+  const files: string[] = [];
+  listTypesTsFiles(srcDir, projectRoot, files);
+  const roots: SchemaRoot[] = [];
+  for (const relFile of files.sort()) {
+    const text = readFileSync(join(projectRoot, relFile), "utf8");
+    for (const match of text.matchAll(INTERFACE_RE)) {
+      const jsDoc = match[1] ?? "";
+      const typeName = match[2];
+      if (!typeName) {
+        continue;
+      }
+      const root = classifyRoot(jsDoc, typeName, relFile);
+      if (root) {
+        roots.push(root);
+      }
+    }
+  }
+  return roots;
+}

package/examples/consumer-app/scripts/schemagen/naming.ts

@@ -0,0 +1,82 @@
+/*
+Maps discovered schema root type names to generated filenames and bridge export constants.
+Matches conventions in docs/output-schema.md and docs/config-schema.md.
+*/
+
+/** kebab-case from PascalCase segments. */
+export function camelToKebab(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+/** SCREAMING_SNAKE from PascalCase. */
+export function camelToScreamingSnake(name: string): string {
+  return camelToKebab(name).replace(/-/g, "_").toUpperCase();
+}
+
+/** Generated JSON filename for an output-schema root type. */
+export function outfileForOutputType(typeName: string): string {
+  if (typeName.endsWith("JsonOutput")) {
+    return `${camelToKebab(typeName.slice(0, -"JsonOutput".length))}.json`;
+  }
+  if (typeName.endsWith("OpResult")) {
+    return `${camelToKebab(typeName.slice(0, -"OpResult".length))}-op-result.json`;
+  }
+  if (typeName.endsWith("Output")) {
+    return `${camelToKebab(typeName.slice(0, -"Output".length))}.json`;
+  }
+  if (typeName.endsWith("Result")) {
+    return `${camelToKebab(typeName.slice(0, -"Result".length))}.json`;
+  }
+  return `${camelToKebab(typeName)}.json`;
+}
+
+/** Bridge export constant for an output-schema root. */
+export function outputSchemaExportName(typeName: string): string {
+  if (typeName.endsWith("JsonOutput")) {
+    const base = typeName.slice(0, -"JsonOutput".length);
+    return `${camelToScreamingSnake(base)}_JSON_OUTPUT_SCHEMA`;
+  }
+  if (typeName.endsWith("OpResult")) {
+    const base = typeName.slice(0, -"OpResult".length);
+    return `${camelToScreamingSnake(base)}_OP_RESULT_OUTPUT_SCHEMA`;
+  }
+  if (typeName.endsWith("Output")) {
+    const base = typeName.slice(0, -"Output".length);
+    return `${camelToScreamingSnake(base)}_OUTPUT_SCHEMA`;
+  }
+  if (typeName.endsWith("Result")) {
+    const base = typeName.slice(0, -"Result".length);
+    return `${camelToScreamingSnake(base)}_RESULT_OUTPUT_SCHEMA`;
+  }
+  return `${camelToScreamingSnake(typeName)}_OUTPUT_SCHEMA`;
+}
+
+/** Generated JSON filename for a config-schema root (typically AppConfig → app-config.json). */
+export function outfileForConfigType(typeName: string): string {
+  if (typeName.endsWith("Config")) {
+    return `${camelToKebab(typeName.slice(0, -"Config".length))}-config.json`;
+  }
+  return `${camelToKebab(typeName)}-config.json`;
+}
+
+/** Bridge export constant for a config-schema root (AppConfig → APP_CONFIG_JSON_SCHEMA). */
+export function configSchemaExportName(typeName: string): string {
+  if (typeName.endsWith("Config")) {
+    const base = typeName.slice(0, -"Config".length);
+    return `${camelToScreamingSnake(base)}_CONFIG_JSON_SCHEMA`;
+  }
+  return `${camelToScreamingSnake(typeName)}_CONFIG_JSON_SCHEMA`;
+}
+
+/** Import path basename for a generated JSON file (no extension). */
+export function jsonImportBasename(outfile: string): string {
+  return outfile.replace(/\.json$/, "");
+}
+
+/** Safe import binding for a generated JSON file (no extension, hyphens → underscores). */
+export function jsonImportVar(outfile: string): string {
+  return jsonImportBasename(outfile).replace(/-/g, "_");
+}

package/examples/consumer-app/scripts/schemagen.ts

@@ -0,0 +1,76 @@
+/*
+Generate JSON Schema artifacts and bridge modules from discovered types.ts roots.
+*/
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createGenerator } from "ts-json-schema-generator";
+import { discoverSchemaRoots, type SchemaRoot } from "./schemagen/discover-schema-roots.ts";
+import { jsonImportVar } from "./schemagen/naming.ts";
+
+const projectRoot = join(import.meta.dir, "..");
+const generatedDir = join(projectRoot, "schemas", "generated");
+
+function generateJson(root: SchemaRoot): Record<string, unknown> {
+  const generator = createGenerator({
+    path: join(projectRoot, root.relFile),
+    type: root.typeName,
+    tsconfig: join(projectRoot, "tsconfig.json"),
+    topRef: false,
+    skipTypeCheck: false,
+    jsDoc: "extended",
+    additionalProperties: root.kind === "config" ? false : undefined,
+  });
+  const schema = generator.createSchema(root.typeName) as Record<string, unknown>;
+  if (root.kind === "config") {
+    schema.additionalProperties = false;
+  }
+  return schema;
+}
+
+function writeBridge(path: string, scriptName: string, roots: SchemaRoot[], banner: string): void {
+  const lines = [`// Auto-generated by scripts/${scriptName} — do not edit by hand.`, ""];
+  for (const root of roots) {
+    const varName = jsonImportVar(root.outfile);
+    lines.push(`import ${varName} from "./generated/${root.outfile}";`);
+  }
+  if (roots.length > 0) {
+    lines.push("");
+  }
+  for (const root of roots) {
+    const varName = jsonImportVar(root.outfile);
+    lines.push(`/** ${banner} \`${root.typeName}\`. */`);
+    lines.push(`export const ${root.exportName} = ${varName} as Record<string, unknown>;`);
+    lines.push("");
+  }
+  writeFileSync(path, `${lines.join("\n")}`);
+}
+
+const roots = discoverSchemaRoots(projectRoot);
+const configRoots = roots.filter((r) => r.kind === "config");
+const outputRoots = roots.filter((r) => r.kind === "output");
+
+mkdirSync(generatedDir, { recursive: true });
+
+for (const root of roots) {
+  const schema = generateJson(root);
+  const outPath = join(generatedDir, root.outfile);
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, `${JSON.stringify(schema, null, 2)}\n`);
+  console.log(`wrote schemas/generated/${root.outfile} (${root.typeName})`);
+}
+
+writeBridge(
+  join(projectRoot, "schemas", "configSchemas.ts"),
+  "schemagen.ts",
+  configRoots,
+  "JSON Schema for program.appConfig.jsonSchema from",
+);
+writeBridge(
+  join(projectRoot, "schemas", "outputSchemas.ts"),
+  "schemagen.ts",
+  outputRoots,
+  "JSON Schema for leaf outputSchema from",
+);
+
+console.log(`config roots: ${configRoots.length}, output roots: ${outputRoots.length}`);

package/examples/consumer-app/src/commands/status/types.ts

@@ -0,0 +1,11 @@
+/** JSON payload for `consumer-app status --json`. */
+export interface StatusJsonOutput {
+  /** Resolved AWS region. */
+  defaultRegion?: string;
+  /** Resolved retry count. */
+  maxRetries?: number;
+  /** Whether apiToken is set (value never included). */
+  apiTokenSet: boolean;
+  /** App version from program root. */
+  version: string;
+}

package/examples/consumer-app/src/main.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env bun
+/*
+Kitchen-sink argsbarg consumer reference.
+
+  cd examples/consumer-app && bun install && bun run schemagen
+  CONSUMER_APP_API_TOKEN=dev bun run start status --json
+  CONSUMER_APP_API_TOKEN=dev bun run start config get
+  CONSUMER_APP_API_TOKEN=dev bun run start docs readme
+*/
+
+import { Cli } from "argsbarg";
+import { program } from "./program.ts";
+
+const cli = new Cli(program);
+await cli.run();

package/examples/consumer-app/src/program.ts

@@ -0,0 +1,116 @@
+/*
+Kitchen-sink CliProgram — every argsbarg builtin enabled.
+*/
+
+import {
+  type CliAppConfig,
+  type CliAppConfigEntry,
+  CliOptionKind,
+  type CliProgram,
+} from "argsbarg";
+import { APP_CONFIG_JSON_SCHEMA } from "../schemas/configSchemas.ts";
+import { STATUS_JSON_OUTPUT_SCHEMA } from "../schemas/outputSchemas.ts";
+import type { StatusJsonOutput } from "./commands/status/types.ts";
+
+const configPath = process.env.CONSUMER_APP_CONFIG_FILE;
+
+const configSchema = {
+  apiToken: {
+    description: "Create at https://example.com/settings/tokens",
+    env: "CONSUMER_APP_API_TOKEN",
+    sensitive: true,
+  },
+  defaultRegion: {
+    description: "AWS region for API calls.",
+    required: false,
+  },
+  maxRetries: {
+    description: "HTTP retry count (0–10).",
+  },
+  prefs: {
+    description: "Local cache preferences (not exported to env).",
+    required: false,
+  },
+} as const satisfies Record<string, CliAppConfigEntry>;
+
+export const program = {
+  key: "consumer-app",
+  version: "1.0.0",
+  description: "Argsbarg kitchen-sink reference — all builtins, schemagen, ctx.appConfig.",
+  appConfig: {
+    ...(configPath ? { path: configPath } : {}),
+    jsonSchema: APP_CONFIG_JSON_SCHEMA,
+    entries: configSchema,
+  } satisfies CliAppConfig,
+  docs: {
+    enabled: true,
+    topics: {
+      readme: {
+        text: "# consumer-app\n\nKitchen-sink argsbarg reference. Copy this layout into a new CLI repo.\n",
+      },
+    },
+  },
+  mcpServer: {
+    enabled: true,
+    resources: [
+      {
+        uri: "consumer-app://readme",
+        name: "readme",
+        description: "Bundled readme topic.",
+        mimeType: "text/plain",
+        load: () => "# consumer-app\n\nKitchen-sink reference.\n",
+      },
+    ],
+  },
+  install: {
+    updateGetLatest: async () => ({
+      path: process.execPath,
+      version: "1.0.0",
+    }),
+  },
+  commands: [
+    {
+      key: "status",
+      description: "Show resolved config and app version.",
+      options: [
+        {
+          name: "json",
+          description: "Emit JSON.",
+          kind: CliOptionKind.Presence,
+        },
+      ],
+      outputSchema: STATUS_JSON_OUTPUT_SCHEMA,
+      handler: (ctx) => {
+        const out: StatusJsonOutput = {
+          defaultRegion: ctx.appConfig.get("defaultRegion") as string | undefined,
+          maxRetries: ctx.appConfig.get("maxRetries") as number | undefined,
+          apiTokenSet: ctx.appConfig.get("apiToken") !== undefined,
+          version: ctx.program.version,
+        };
+        if (ctx.hasFlag("json")) {
+          console.log(JSON.stringify(out, null, 2));
+        } else {
+          console.log(`version=${out.version}`);
+          console.log(`region=${out.defaultRegion ?? "(not set)"}`);
+          console.log(`maxRetries=${out.maxRetries ?? "(not set)"}`);
+          console.log(`apiToken=${out.apiTokenSet ? "set" : "missing"}`);
+        }
+      },
+    },
+    {
+      key: "echo",
+      description: "Echo a message (MCP-friendly leaf).",
+      options: [
+        {
+          name: "message",
+          description: "Text to print.",
+          kind: CliOptionKind.String,
+          required: true,
+        },
+      ],
+      handler: (ctx) => {
+        console.log(ctx.stringOpt("message") ?? "");
+      },
+    },
+  ],
+} satisfies CliProgram;