argsbarg 6.1.10 → 6.2.2

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

@@ -1,13 +1,15 @@
 ---
-name: full_example
-description: Operates the full-example CLI (echo, render-json, status, workspaces get, workspaces post, and 4 more). Use when the user mentions full-example, echo, render-json, status, or related tasks.
+id: full-example
+name: full-example
+description: Operates the full-example CLI (echo, status). Use when the user mentions full-example, echo, status, or related tasks.
+enabled: true
 ---
 <!-- Generated by full-example docs skill --save; do not edit. -->
 
 
 # full-example
 
-Argsbarg full example reference app
+Argsbarg CLI copy template (MCP, HTTP, configure, skills; no schemagen)
 
 ## Execution
 
@@ -20,14 +22,7 @@ full-example <subcommand> [options] [args]
 ## Commands
 
 - **`full-example echo`** — Echo a message (MCP-friendly leaf).
-- **`full-example render-json`** — Echo a JSON message (schema-first JSON leaf demo).
 - **`full-example status`** — Show app version. (flags: --json)
-- **`full-example workspaces get`** — List workspaces.
-- **`full-example workspaces post`** — Create a workspace.
-- **`full-example workspaces :id get`** — Get one workspace.
-- **`full-example workspaces :id put`** — Replace a workspace.
-- **`full-example workspaces :id patch`** — Patch a workspace name.
-- **`full-example workspaces :id delete`** — Delete a workspace.
 
 ## Pitfalls
 
@@ -37,10 +32,19 @@ full-example <subcommand> [options] [args]
 
 For full detail, open `reference.md` in this skill directory (same as `full-example docs cli`).
 
-## Cursor install location
+## Install location
 
-- Project: `.cursor/skills/full_example/`
-- Global: `~/.cursor/skills/full_example/`
+Install follows the https://dotagentsprotocol.com:
 
-Do not install under `~/.cursor/skills-cursor/` (reserved for Cursor built-ins).
+- Auto-install: `full-example configure --sync --yes` when `skill.enabled` → `~/.agents/skills/full-example/`
+- Cursor and most coding agents read `~/.agents/skills/` natively
+
+**Claude Code (manual):** symlink or copy into Claude's skill directory:
+
+```bash
+mkdir -p ~/.claude/skills
+ln -sf ~/.agents/skills/full-example ~/.claude/skills/full-example
+```
+
+Project override (optional): `.agents/skills/full-example/`
 

package/examples/full-example/justfile

@@ -21,18 +21,8 @@ build:
     bun build ./src/index.ts --compile --outfile=dist/{{cli_key}}
     @rm -f .*.bun-build
 
-# Apply SQL migrations in src/db/migrations/ to a SQLite database file
-migrate DB="./workspaces.db":
-    #!/usr/bin/env bash
-    set -euo pipefail
-    mkdir -p "$(dirname '{{DB}}')"
-    for f in $(ls src/db/migrations/*.sql | sort); do
-      echo "==> $f"
-      sqlite3 '{{DB}}' < "$f"
-    done
-
-# Run schemagen, typecheck, and format
-check: schemagen format typecheck
+# Run typecheck and format
+check: format typecheck
 
 # demo the HTTP API
 demo-http:
@@ -55,7 +45,7 @@ dev *ARGS:
     bun --watch ./src/index.ts {{ARGS}}
 
 # Regenerate consumer docs under ./docs/
-docgen: schemagen
+docgen:
     @just run docs cli-schema --save
     @just run docs cli --save
     @just run docs skill --save
@@ -113,15 +103,13 @@ lint:
 run *ARGS:
     bun ./src/index.ts {{ARGS}}
 
-# Generate JSON Schema artifacts from TypeScript types
+# Generate JSON Schema artifacts from TypeScript types (not used in this template)
 schemagen:
-    argsbarg schemagen
+    @echo "This CLI template has no @sg types. Use full-example-json or add /** @sg */ types first."
 
 # Install bun/npm dependencies
-# Install bun/npm dependencies and generate schemas
 setup:
     bun install
-    just schemagen
 
 # Run unit tests (after check)
 test: check

package/examples/full-example/scripts/create-identity.ts

@@ -6,6 +6,7 @@ export const createIdentity = {
   tap: "bdombro/bun-argsbarg",
   homepage: "https://github.com/bdombro/bun-argsbarg",
   releaseRepo: "bdombro/bun-argsbarg",
-  desc: "Argsbarg full example reference app",
+  desc: "Argsbarg CLI copy template (MCP, HTTP, configure, skills; no schemagen)",
   envPrefix: "FULL_EXAMPLE",
+  template: "cli",
 } as const;

package/examples/full-example/src/commands/status/command.test.ts

@@ -2,9 +2,9 @@ import { describe, expect, test } from "bun:test";
 import { statusCommand } from "./command.ts";
 
 describe("status command", () => {
-  test("exports outputSchema and json option", () => {
+  test("exports json option without outputSchema", () => {
     expect(statusCommand.key).toBe("status");
-    expect(statusCommand.outputSchema).toBeDefined();
+    expect(statusCommand.outputSchema).toBeUndefined();
     expect(statusCommand.options?.some((o) => o.name === "json")).toBe(true);
   });
 });

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

@@ -1,10 +1,8 @@
 /*
-Status leaf — demonstrates outputSchema.
+Status leaf — version with optional JSON stdout (no schemagen).
 */
 
 import { type CliLeaf, CliOptionKind } from "argsbarg";
-import { StatusJsonOutputSchema } from "./__generated__";
-import type { StatusJsonOutput } from "./types.ts";
 
 export const statusCommand = {
   key: "status",
@@ -16,13 +14,16 @@ export const statusCommand = {
       kind: CliOptionKind.Presence,
     },
   ],
-  outputSchema: StatusJsonOutputSchema,
   handler: (ctx) => {
-    const out: StatusJsonOutput = { version: ctx.program.version };
+    const out = { version: ctx.program.version };
     if (ctx.hasFlag("json")) {
       console.log(JSON.stringify(out, null, 2));
-    } else {
+      return;
+    }
+    if (ctx.invocation === "cli") {
       console.log(`version=${out.version}`);
+      return;
     }
+    return out;
   },
 } satisfies CliLeaf;

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

@@ -6,14 +6,10 @@ import type { CliProgram } from "argsbarg";
 import readmeText from "../README.md" with { type: "text" };
 import { createIdentity } from "../scripts/create-identity.ts";
 import { echoCommand } from "./commands/echo/command.ts";
-import { renderJsonCommand } from "./commands/render-json/command.ts";
 import { statusCommand } from "./commands/status/command.ts";
-import { workspacesCommand } from "./commands/workspaces/command.ts";
-import { AppDb } from "./db";
 
 export const program = {
-  key: createIdentity.key,
-  version: "1.0.0",
+  commands: [echoCommand, statusCommand],
   description: createIdentity.desc,
   docs: {
     topics: {
@@ -22,11 +18,9 @@ export const program = {
       },
     },
   },
+  key: createIdentity.key,
   mcpServer: { enabled: true },
   httpServer: { enabled: true },
-  readiness: AppDb.checkReadiness,
-  hooks: {
-    beforeInvoke: AppDb.attach,
-  },
-  commands: [echoCommand, renderJsonCommand, statusCommand, workspacesCommand],
+  skill: { enabled: true },
+  version: "1.0.0",
 } satisfies CliProgram;

package/examples/full-example-json/AGENTS.md

@@ -0,0 +1,86 @@
+# full-example-json
+
+## Tooling
+
+- Bun only (`bun`, `bunx`, `bun test`). No Node/npm/pnpm.
+
+## Documentation
+
+- `README.md` — user-facing install/commands
+- `docs/architecture.md` — maintainer internals (create if missing)
+- Generated: `just docgen` → `docs/cli.md`, `docs/cli-schema.json`, `docs/skill.md`
+
+<!-- argsbarg:managed -->
+
+## Argsbarg schema
+
+When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
+
+1. **Read** `node_modules/argsbarg/docs/cli-program.md` (required — authoritative guide).
+2. MCP tools, varargs, `inputSchema` → also `node_modules/argsbarg/docs/mcp.md`.
+3. JSON stdout / `outputSchema` guide and codegen → `node_modules/argsbarg/docs/output-schema.md`.
+4. App config / `program.appConfig` guide and codegen → `node_modules/argsbarg/docs/config-schema.md`.
+5. `configure`, `configure.targets`, Homebrew distribution → `node_modules/argsbarg/docs/configure.md` and `distribution-homebrew.md`.
+6. Bundled `docs` built-in → `node_modules/argsbarg/docs/bundled-docs.md`.
+7. **Examples** (shipped under `node_modules/argsbarg/examples/`):
+   - **Copy template** (all builtins, `@sg` schemagen, Homebrew justfile, `outputSchema`) → `examples/full-example/`
+
+**Hard rules** (details and examples are in the docs above — do not contradict them):
+
+- Reserved root commands: `completion`, `configure`, `mcp`, `version`, `docs`.
+- `satisfies CliProgram` / `CliLeaf`; action-oriented `description` on root, commands, options, and positionals.
+- Omit `mcpTool` unless genuinely CLI-only (`enabled: false`) or an irreducible wire limit — fix schema and headless handlers first.
+- Interactive leaves: one headless path for MCP, non-TTY CLI, and `--yes` / `--dry-run` / `--json` (`shouldRunHeadless*`, `requireYesInNonTty`); not raw `isTTY`.
+- String options: `format` / `default` / `pattern` per `cli-program.md`; `readLeafInputs()` for multi-flag leaves.
+- Varargs (`argMax: 0`): CLI space-separated; MCP JSON array only — no comma-splitting positionals.
+- Multi-surface leaves (Ink + headless + MCP): one **`read*Flags(ctx)`** per command (or shared family helper + extensions); one **`resolve*Input(flags)`** for cross-field rules — handler reads ctx once, all paths share the struct.
+- JSON stdout: `import { StatusJsonOutputSchema } from "./__generated__"` — declare `/** @sg */` on the type in `types.ts`; handlers import types from the same module.
+- App config (optional): `import { AppConfigSchema } from "./config/__generated__"` — `/** @sg */` on `AppConfig` in `src/config/types.ts`.
+
+## Code conventions
+
+### JSDoc
+
+Add doc comments for exported surfaces that are not obvious from the name alone: JSON output schemas, public types, and non-trivial algorithms. Skip comments on short test callbacks and pure re-export files.
+
+### Names
+
+Use names that describe the domain role, not generic placeholders like `data` or `handler`, except in very small scopes.
+
+### Structure
+
+After imports, put **exported** symbols first (alphabetical within each kind), then **module-private** helpers at the bottom. Use `~/…` only where you would otherwise use `../` (or deeper) to reach another module under `src/`. Same-directory (`./`) and child (`./foo/…`) imports stay relative. Use `.ts` extensions.
+
+### Module boundaries
+
+| Path | Owns | Must not |
+| --- | --- | --- |
+| `src/index.ts` | Thin entry: `new Cli(program).run()` | Inline leaf handlers, business logic |
+| `src/types/` | Global type declarations and module augmentations (e.g. `argsbarg.d.ts`, `md.d.ts`) | Runtime logic, imports from outside `types/` |
+| `src/program.ts` | `CliProgram` assembly: `docs`, `commands: […]` | Inline leaf handlers, business logic |
+| `src/db/` | `AppDb` (SQLite connect, migrate, domain access), `migrate.ts`, `migrations/*.sql` | Command handlers |
+| `src/commands/<name>/` | One user-facing command: `command.ts`, optional `types.ts` with `/** @sg */` | Shared helpers (lift to `src/db/`) |
+| `src/**/__generated__/` | Generated JSON Schema + `index.ts` re-exports | Hand-edited generated files |
+| `scripts/` | Dev tooling (formula helpers) | Production command paths |
+
+When adding commands: `src/commands/<name>/command.ts` + `types.ts` when schemas are needed; register in `program.ts` **alphabetically by command key**.
+
+**Argsbarg schema:** see Argsbarg schema section above.
+
+### Execution
+
+- **Runtime:** Bun (`just test`, `just dev`).
+- **Tests:** colocate `*.test.ts` next to the module.
+- **Schemagen:** after changing `/** @sg */` types in `src/`, run `just schemagen` (`__generated__/` is gitignored).
+
+### Abstractions
+
+Avoid needless extraction: keep single-use helpers in the calling file by default. Split only when reused elsewhere, the caller is large or hard to follow, or extraction clarifies a substantial unit. Do not create tiny one-off helpers.
+- ❌ `utils/formatX.ts` — 60-line helper used by one command
+- ✅ inline helper in that command file
+
+<!-- /argsbarg:managed -->
+
+**full-example-json conventions:**
+
+Replace with app-specific bullets.

package/examples/full-example-json/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/examples/full-example-json/Formula/full-example-json.rb

@@ -0,0 +1,35 @@
+class FullExampleJson < Formula
+  desc "Argsbarg schema-first copy template (@sg schemagen, JSON schemas, REST CRUD)"
+  homepage "https://github.com/bdombro/bun-argsbarg"
+  version "1.0.0"
+  sha256 "d6dbe3233152d2f51feca068b23e6fd133940232fb4bb7c3f08c2d1024c10c30"
+
+  def install
+    bin.install "full-example-json"
+    chmod 0755, bin/"full-example-json"
+    generate_completions_from_executable(bin/"full-example-json", "completion", base_name: "full-example-json")
+  end
+
+  def post_install
+    system bin/"full-example-json", "configure", "--sync", "--yes"
+  end
+
+  def uninstall
+    system bin/"full-example-json", "configure", "--remove-all", "--yes"
+  end
+
+  def caveats
+    <<~EOS
+      Run `full-example-json configure` to set up agent artifacts and app config (interactive).
+      Restart MCP chat apps (Cursor, Claude Desktop, etc.) after install or upgrade so they load the updated server.
+    EOS
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/full-example-json version")
+    assert_predicate bash_completion/"full-example-json", :exist?
+    assert_predicate zsh_completion/"_full-example-json", :exist?
+    assert_predicate fish_completion/"full-example-json.fish", :exist?
+  end
+url "file:///Users/briandombrowski/dev/bdombro/bun-argsbarg/examples/full-example-json/Formula/.staging/full-example-json"
+end

package/examples/full-example-json/README.md

@@ -0,0 +1,27 @@
+# full-example-json
+
+Argsbarg **schema-first copy template** — `@sg` schemagen, JSON Schema validation, REST CRUD demo (not a kitchen-sink product).
+
+For a CLI-only template without schemagen, use `examples/full-example/` or `argsbarg create --template cli`.
+
+## What's in this app
+
+- **Builtins enabled:** CLI, shell completion, `docs`, MCP, HTTP API, `configure`, agent skills
+- **Commands:**
+  - `echo` — simple flags/positionals
+  - `render-json` — `kind: "json"` leaf, schemagen `inputSchema`, `ctx.inputsAs`
+  - `status` — schemagen `outputSchema`, `--json`
+  - `workspaces` — REST CRUD, `:id` param routers, verb leaves, schemagen input schemas
+- **Tooling:** `@sg` schemagen, `just docgen`, Homebrew/just dev workflow, in-memory SQLite (`bun:sqlite`)
+
+## Quick start
+
+From a git checkout at this directory (requires [Homebrew](https://brew.sh), [just](https://just.systems), and [Bun](https://bun.sh)):
+
+```bash
+brew install just bun
+just setup
+just schemagen   # after changing @sg types in src/
+just run status --json
+just run docs readme
+```

package/examples/full-example-json/biome.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.0/schema.json",
+  "assist": { "actions": { "source": { "organizeImports": "on" } } },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "lineWidth": 120
+  },
+  "overrides": [
+    {
+      "includes": ["**/*.json"],
+      "formatter": { "enabled": false },
+      "linter": { "enabled": false }
+    }
+  ]
+}

package/examples/full-example-json/bun.lock

@@ -0,0 +1,48 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "consumer-app-example",
+      "dependencies": {
+        "argsbarg": "file:../..",
+      },
+      "devDependencies": {
+        "@biomejs/biome": "^2.5.0",
+        "@types/bun": "^1.3.12",
+        "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/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" } }],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "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/full-example-json/docs/README.md

@@ -0,0 +1,27 @@
+# full-example documentation
+
+Reference template for argsbarg consumer docgen. Every builtin is enabled in `src/program.ts`.
+
+| If you are… | Read |
+| --- | --- |
+| **Using the CLI** | [../README.md](../README.md) |
+| **Authoring argsbarg schema** | `node_modules/argsbarg/docs/cli-program.md` — see [`AGENTS.md`](../AGENTS.md) |
+| **HTTP API / curl** | [http.md](http.md) — generated; or run `full-example docs http` |
+| **MCP tools** | [mcp.md](mcp.md) — generated; or run `full-example docs mcp` |
+| **Full command tree (markdown)** | [cli.md](cli.md) — generated |
+| **Full command tree (JSON)** | [cli-schema.json](cli-schema.json) — generated |
+| **OpenAPI 3.1** | [openapi.json](openapi.json) — generated |
+| **Agent skill index** | [skill.md](skill.md) — generated |
+
+## Framework docs vs this directory
+
+| Layer | Contents |
+| --- | --- |
+| **Argsbarg framework** | How to author `CliProgram`, MCP, HTTP API | `node_modules/argsbarg/docs/` |
+| **This `docs/` folder** | *full-example* command tree and guides | `just docgen` |
+
+Do not hand-edit generated files. Refresh with:
+
+```bash
+just docgen
+```