argsbarg 6.1.9 → 6.2.0

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 [.agents protocol](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,25 +21,31 @@ 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":
+# Run typecheck and format
+check: format typecheck
+
+# demo the HTTP API
+demo-http:
     #!/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
+    bun ./src/index.ts http --port 13000 &
+    trap 'kill $! 2>/dev/null || true' EXIT
+    until curl -sf http://127.0.0.1:13000/health/liveness >/dev/null; do sleep 0.1; done
+
+# demo a CLI command
+demo-cli:
+    @just run {{cli_key}} status
 
-# Run schemagen, typecheck, and format
-check: schemagen format typecheck
+# demo a CLI command
+demo-help:
+    @just run {{cli_key}} --help
 
 # Run the CLI from source with optional args; restarts on file changes
 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
@@ -53,6 +59,10 @@ alias fmt := format
 format:
     bun run biome check ./src ./scripts --write --unsafe
 
+# Run the HTTP server
+http:
+    @just run http
+
 # Alias for backward compatibility
 install: install-local
 
@@ -93,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/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 `.cursor/rules/cli-program.mdc` |
+| **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
+```