argsbarg 5.1.16 → 6.0.1

package/examples/full-example/docs/openapi.json

@@ -0,0 +1,222 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "full-example",
+    "version": "1.0.0",
+    "description": "Argsbarg full example reference app"
+  },
+  "paths": {
+    "/tools/echo": {
+      "post": {
+        "operationId": "echo",
+        "summary": "echo — Echo a message (MCP-friendly leaf).",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json; charset=utf-8": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "message": {
+                    "type": "string",
+                    "description": "Text to print."
+                  }
+                },
+                "additionalProperties": false,
+                "required": [
+                  "message"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful tool invocation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid arguments or help requested",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    },
+                    "exitCode": {
+                      "type": "integer"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Unknown tool",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Handler error",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/tools/status": {
+      "post": {
+        "operationId": "status",
+        "summary": "status — Show resolved config and app version.",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json; charset=utf-8": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "json": {
+                    "type": "boolean",
+                    "description": "Emit JSON."
+                  }
+                },
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful tool invocation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$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 `full-example status --json`.",
+                  "definitions": {}
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid arguments or help requested",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    },
+                    "exitCode": {
+                      "type": "integer"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Unknown tool",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Handler error",
+            "content": {
+              "application/json; charset=utf-8": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/examples/full-example/docs/skill.md

@@ -0,0 +1,46 @@
+---
+name: full_example
+description: Operates the full-example CLI (echo, status). Use when the user mentions full-example, echo, status, or related tasks.
+---
+<!-- Generated by full-example docs skill --save; do not edit. -->
+
+
+# full-example
+
+Argsbarg full example reference app
+
+## Execution
+
+Invoke via shell:
+
+```bash
+full-example <subcommand> [options] [args]
+```
+
+## Commands
+
+- **`full-example echo`** — Echo a message (MCP-friendly leaf).
+- **`full-example status`** — Show resolved config and app version. (flags: --json)
+
+## Configuration
+
+- **apiToken** (`apiToken` (env: `FULL_EXAMPLE_API_TOKEN`)) — Create at https://example.com/settings/tokens
+- **defaultRegion** (`defaultRegion`) — AWS region for API calls.
+- **maxRetries** (`maxRetries`) — HTTP retry count (0–10).
+- **prefs** (`prefs`) — Local cache preferences (not exported to env).
+
+## Pitfalls
+
+- Pass `--` before arguments that look like flags.
+
+## Reference
+
+For full detail, open `reference.md` in this skill directory (same as `full-example docs api`).
+
+## Cursor install location
+
+- Project: `.cursor/skills/full_example/`
+- Global: `~/.cursor/skills/full_example/`
+
+Do not install under `~/.cursor/skills-cursor/` (reserved for Cursor built-ins).
+

package/examples/full-example/justfile

@@ -27,10 +27,14 @@ check: schemagen format typecheck
 dev *ARGS:
     bun --watch ./src/index.ts {{ARGS}}
 
-# Regenerate docs/schema.json and docs/skill.md
+# Regenerate consumer docs under ./docs/
 docgen: schemagen
-    @just run docs schema --save
+    @just run docs cli-schema --save
+    @just run docs api --save
     @just run docs skill --save
+    @just run docs mcp --save
+    @just run docs http --save
+    @just run docs openapi --save
 
 alias fmt := format
 

package/examples/full-example/schemas/generated/app-config.json

@@ -35,6 +35,6 @@
     "maxRetries"
   ],
   "additionalProperties": false,
-  "description": "Config schema\n\nApplication settings for `full-example` (`program.appConfig`).",
+  "description": "Application settings for `full-example` (`program.appConfig`).",
   "definitions": {}
 }

package/examples/full-example/schemas/generated/status.json

@@ -23,6 +23,6 @@
     "apiTokenSet",
     "version"
   ],
-  "description": "JSON payload for `full-example status --json`.",
+  "description": "JSON stdout for `full-example status --json`.",
   "definitions": {}
 }

package/examples/full-example/scripts/dev-formula.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 /**
  * Stage or restore the dev Homebrew formula for `just install-local`.
- * `install` — back up release `Formula/{key}.rb` and write a `file://` dev formula.
+ * `install` — back up release `Formula/full-example.rb` and write a `file://` dev formula.
  * `reset` — restore the release formula from backup.
  */
 

package/examples/full-example/scripts/schemagen/discover-schema-roots.test.ts

@@ -5,19 +5,19 @@ 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", () => {
+  test("finds AppConfig and StatusJsonOutput in schema-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",
+      path: "src/config/schema-types.ts",
       outfile: "app-config.json",
       exportName: "APP_CONFIG_JSON_SCHEMA",
     });
     expect(output).toMatchObject({
       typeName: "StatusJsonOutput",
-      relFile: "src/commands/status/types.ts",
+      path: "src/commands/status/schema-types.ts",
       outfile: "status.json",
       exportName: "STATUS_JSON_OUTPUT_SCHEMA",
     });

package/examples/full-example/scripts/schemagen/discover-schema-roots.ts

@@ -1,5 +1,5 @@
 /*
-Discovers schema roots in src (recursive) types.ts files by JSDoc markers.
+Discovers schema roots in schema-types.ts files via configType / inputType / outputType exports.
 Copy per consumer repo — see docs/output-schema.md and docs/config-schema.md.
 */
 
@@ -7,87 +7,142 @@ import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 import {
   configSchemaExportName,
+  inputSchemaExportName,
   outfileForConfigType,
+  outfileForInputType,
   outfileForOutputType,
   outputSchemaExportName,
 } from "./naming.ts";
 
-export type SchemaRootKind = "config" | "output";
+export type SchemaRootKind = "config" | "input" | "output";
+
+export type SchemaRole = "configType" | "inputType" | "outputType";
 
 export interface SchemaRoot {
   kind: SchemaRootKind;
   typeName: string;
-  /** Path relative to project root (e.g. src/types.ts). */
-  relFile: string;
+  /** Path relative to project root (e.g. src/config/schema-types.ts). */
+  path: string;
   outfile: string;
   exportName: string;
 }
 
-const CONFIG_MARKER = "Config schema";
-const OUTPUT_MARKER = "JSON payload";
+const SCHEMA_TYPES_FILE = "schema-types.ts";
+
+const ROLE_EXPORT_RE = /export\s+type\s+(configType|inputType|outputType)\s*=\s*(\w+)/g;
 
-const INTERFACE_RE = /\/\*\*([\s\S]*?)\*\/\s*export\s+interface\s+(\w+)/g;
+const ROLE_TO_KIND: Record<SchemaRole, SchemaRootKind> = {
+  configType: "config",
+  inputType: "input",
+  outputType: "output",
+};
 
-function listTypesTsFiles(srcDir: string, baseDir: string, out: string[]): void {
+function listSchemaTypesFiles(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);
+      listSchemaTypesFiles(full, baseDir, out);
       continue;
     }
-    if (ent === "types.ts") {
+    if (ent === SCHEMA_TYPES_FILE) {
       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`);
+/** True when `typeName` is declared in this file (not a re-export alias to another module). */
+function isTypeDefinedInFile(text: string, typeName: string): boolean {
+  if (new RegExp(`export\\s+interface\\s+${typeName}\\b`).test(text)) {
+    return true;
   }
-  if (!hasConfig && !hasOutput) {
-    return undefined;
+  if (new RegExp(`export\\s+type\\s+${typeName}\\s*=`).test(text)) {
+    return !["configType", "inputType", "outputType"].includes(typeName);
   }
-  if (hasConfig) {
+  return false;
+}
+
+function rootForRole(role: SchemaRole, typeName: string, path: string): SchemaRoot {
+  const kind = ROLE_TO_KIND[role];
+  if (kind === "config") {
     return {
-      kind: "config",
+      kind,
       typeName,
-      relFile,
+      path,
       outfile: outfileForConfigType(typeName),
       exportName: configSchemaExportName(typeName),
     };
   }
+  if (kind === "input") {
+    return {
+      kind,
+      typeName,
+      path,
+      outfile: outfileForInputType(typeName),
+      exportName: inputSchemaExportName(typeName),
+    };
+  }
   return {
-    kind: "output",
+    kind,
     typeName,
-    relFile,
+    path,
     outfile: outfileForOutputType(typeName),
     exportName: outputSchemaExportName(typeName),
   };
 }
 
-/** Find all schema roots under `src/` in files named types.ts. */
+function discoverFromFile(path: string, text: string): SchemaRoot[] {
+  const rolesSeen = new Set<SchemaRole>();
+  const roots: SchemaRoot[] = [];
+
+  for (const match of text.matchAll(ROLE_EXPORT_RE)) {
+    const role = match[1] as SchemaRole | undefined;
+    const typeName = match[2];
+    if (!role || !typeName) {
+      continue;
+    }
+    if (rolesSeen.has(role)) {
+      throw new Error(`${path}: duplicate export type ${role}`);
+    }
+    rolesSeen.add(role);
+    if (!isTypeDefinedInFile(text, typeName)) {
+      continue;
+    }
+    roots.push(rootForRole(role, typeName, path));
+  }
+
+  return roots;
+}
+
+/** Find all schema roots under `src/` in files named schema-types.ts. */
 export function discoverSchemaRoots(projectRoot: string): SchemaRoot[] {
   const srcDir = join(projectRoot, "src");
   const files: string[] = [];
-  listTypesTsFiles(srcDir, projectRoot, files);
+  listSchemaTypesFiles(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);
+  const typeOwners = new Map<string, string>();
+
+  for (const relPath of files.sort()) {
+    const text = readFileSync(join(projectRoot, relPath), "utf8");
+    for (const root of discoverFromFile(relPath, text)) {
+      const prev = typeOwners.get(root.typeName);
+      if (prev) {
+        throw new Error(
+          `${relPath}: duplicate schema root type ${root.typeName} (already declared in ${prev})`,
+        );
       }
+      typeOwners.set(root.typeName, relPath);
+      roots.push(root);
     }
   }
+
+  const configRoots = roots.filter((r) => r.kind === "config");
+  if (configRoots.length > 1) {
+    throw new Error(
+      `multiple config schema roots: ${configRoots.map((r) => `${r.typeName} (${r.path})`).join(", ")}`,
+    );
+  }
+
   return roots;
 }

package/examples/full-example/scripts/schemagen/naming.ts

@@ -16,6 +16,23 @@ export function camelToScreamingSnake(name: string): string {
   return camelToKebab(name).replace(/-/g, "_").toUpperCase();
 }
 
+/** Generated JSON filename for a tool-input schema root. */
+export function outfileForInputType(typeName: string): string {
+  if (typeName.endsWith("ToolInput")) {
+    return `${camelToKebab(typeName.slice(0, -"ToolInput".length))}-tool-input.json`;
+  }
+  return `${camelToKebab(typeName)}-tool-input.json`;
+}
+
+/** Bridge export constant for a tool-input schema root. */
+export function inputSchemaExportName(typeName: string): string {
+  if (typeName.endsWith("ToolInput")) {
+    const base = typeName.slice(0, -"ToolInput".length);
+    return `${camelToScreamingSnake(base)}_TOOL_INPUT_SCHEMA`;
+  }
+  return `${camelToScreamingSnake(typeName)}_TOOL_INPUT_SCHEMA`;
+}
+
 /** Generated JSON filename for an output-schema root type. */
 export function outfileForOutputType(typeName: string): string {
   if (typeName.endsWith("JsonOutput")) {

package/examples/full-example/scripts/schemagen.ts

@@ -1,5 +1,5 @@
 /*
-Generate JSON Schema artifacts and bridge modules from discovered types.ts roots.
+Generate JSON Schema artifacts and bridge modules from discovered schema-types.ts roots.
 */
 
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -13,7 +13,7 @@ const generatedDir = join(projectRoot, "schemas", "generated");
 
 function generateJson(root: SchemaRoot): Record<string, unknown> {
   const generator = createGenerator({
-    path: join(projectRoot, root.relFile),
+    path: join(projectRoot, root.path),
     type: root.typeName,
     tsconfig: join(projectRoot, "tsconfig.json"),
     topRef: false,
@@ -52,6 +52,7 @@ function writeBridge(path: string, scriptName: string, roots: SchemaRoot[], bann
 
 const roots = discoverSchemaRoots(projectRoot);
 const configRoots = roots.filter((r) => r.kind === "config");
+const inputRoots = roots.filter((r) => r.kind === "input");
 const outputRoots = roots.filter((r) => r.kind === "output");
 
 mkdirSync(generatedDir, { recursive: true });
@@ -70,6 +71,14 @@ writeBridge(
   configRoots,
   "JSON Schema for program.appConfig.jsonSchema from",
 );
+if (inputRoots.length > 0) {
+  writeBridge(
+    join(projectRoot, "schemas", "inputSchemas.ts"),
+    "schemagen.ts",
+    inputRoots,
+    "JSON Schema for leaf inputSchema from",
+  );
+}
 writeBridge(
   join(projectRoot, "schemas", "outputSchemas.ts"),
   "schemagen.ts",
@@ -77,4 +86,6 @@ writeBridge(
   "JSON Schema for leaf outputSchema from",
 );
 
-console.log(`config roots: ${configRoots.length}, output roots: ${outputRoots.length}`);
+console.log(
+  `config roots: ${configRoots.length}, input roots: ${inputRoots.length}, output roots: ${outputRoots.length}`,
+);

package/examples/full-example/src/commands/echo/command.ts

@@ -16,6 +16,11 @@ export const echoCommand = {
     },
   ],
   handler: (ctx) => {
-    console.log(ctx.stringOpt("message") ?? "");
+    const message = ctx.stringOpt("message") ?? "";
+    if (ctx.invocation === "cli") {
+      console.log(message);
+      return;
+    }
+    return message;
   },
 } satisfies CliLeaf;

package/examples/full-example/src/commands/status/schema-types.ts

@@ -0,0 +1,14 @@
+/** JSON stdout for `full-example 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;
+}
+
+/** Schemagen root for leaf outputSchema. */
+export type outputType = StatusJsonOutput;

package/examples/full-example/src/commands/status/types.ts

@@ -1,11 +1 @@
-/** JSON payload for `full-example 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;
-}
+export type { StatusJsonOutput } from "./schema-types.ts";

package/examples/full-example/src/{types.ts → config/schema-types.ts}

@@ -1,6 +1,4 @@
 /**
- * Config schema
- *
  * Application settings for `full-example` (`program.appConfig`).
  */
 export interface AppConfig {
@@ -21,3 +19,6 @@ export interface AppConfig {
     ttl: number;
   };
 }
+
+/** Schemagen root for program.appConfig.jsonSchema. */
+export type configType = AppConfig;

package/examples/full-example/src/program.ts

@@ -50,5 +50,8 @@ export const program = {
     mcpd: true,
     claudePlugin: true,
   },
+  apiServer: {
+    enabled: true,
+  },
   commands: [echoCommand, statusCommand],
 } satisfies CliProgram;