argsbarg 6.1.9 → 6.2.0

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

@@ -0,0 +1,57 @@
+---
+id: full-example-json
+name: full-example-json
+description: Operates the full-example-json CLI (echo, render-json, status, workspaces get, workspaces post, and 4 more). Use when the user mentions full-example-json, echo, render-json, status, or related tasks.
+enabled: true
+---
+<!-- Generated by full-example-json docs skill --save; do not edit. -->
+
+
+# full-example-json
+
+Argsbarg schema-first copy template (@sg schemagen, JSON schemas, REST CRUD)
+
+## Execution
+
+Invoke via shell:
+
+```bash
+full-example-json <subcommand> [options] [args]
+```
+
+## Commands
+
+- **`full-example-json echo`** — Echo a message (MCP-friendly leaf).
+- **`full-example-json render-json`** — Echo a JSON message (schema-first JSON leaf demo).
+- **`full-example-json status`** — Show app version. (flags: --json)
+- **`full-example-json workspaces get`** — List workspaces.
+- **`full-example-json workspaces post`** — Create a workspace.
+- **`full-example-json workspaces :id get`** — Get one workspace.
+- **`full-example-json workspaces :id put`** — Replace a workspace.
+- **`full-example-json workspaces :id patch`** — Patch a workspace name.
+- **`full-example-json workspaces :id delete`** — Delete a workspace.
+
+## Pitfalls
+
+- Pass `--` before arguments that look like flags.
+
+## Reference
+
+For full detail, open `reference.md` in this skill directory (same as `full-example-json docs cli`).
+
+## Install location
+
+Install follows the [.agents protocol](https://dotagentsprotocol.com/):
+
+- Auto-install: `full-example-json configure --sync --yes` when `skill.enabled` → `~/.agents/skills/full-example-json/`
+- 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-json ~/.claude/skills/full-example-json
+```
+
+Project override (optional): `.agents/skills/full-example-json/`
+

package/examples/full-example-json/justfile

@@ -0,0 +1,171 @@
+set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
+
+export PATH := justfile_directory() + "/node_modules/.bin:" + env_var("PATH")
+
+cli_key := `bun scripts/print-identity.ts key`
+tap_org := `bun scripts/print-identity.ts tapOrg`
+tap_repo := `bun scripts/print-identity.ts tapRepo`
+tap := `bun scripts/print-identity.ts tap`
+release_repo := `bun scripts/print-identity.ts releaseRepo`
+tap_git_url := "git@github.com:" + release_repo + ".git"
+brew_prefix := `brew --prefix`
+tap_parent := brew_prefix + "/Library/Taps/" + tap_org
+tap_path := tap_parent + "/homebrew-" + tap_repo
+
+# List available recipes (default)
+_:
+    @just --list
+
+# Compile the CLI binary to dist/full-example
+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
+
+# demo the HTTP API
+demo-http:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    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
+
+# 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
+    @just run docs cli-schema --save
+    @just run docs cli --save
+    @just run docs skill --save
+    @just run docs mcp --save
+    @just run docs http --save
+    @just run docs openapi --save
+
+alias fmt := format
+
+# Format and lint sources (auto-fix)
+format:
+    bun run biome check ./src ./scripts --write --unsafe
+
+# Run the HTTP server
+http:
+    @just run http
+
+# Alias for backward compatibility
+install: install-local
+
+# Refresh skills and MCP without reinstalling the formula
+sync-artifacts:
+    just run configure --sync --yes
+
+# Dev install: build, stage dev formula, brew install, restore release formula
+install-local: build
+    @brew untap {{tap}} 2>/dev/null || true
+    mkdir -p {{tap_parent}}
+    ln -sfn '{{justfile_directory()}}' {{tap_path}}
+    bun scripts/dev-formula.ts install
+    brew install --formula {{tap}}/{{cli_key}}
+    bun scripts/dev-formula.ts reset
+    @echo ""
+    @echo "Next: {{cli_key}} configure"
+
+# Remove local dev install, then install from GitHub tap (requires gh auth login)
+install-production: uninstall
+    brew tap {{release_repo}} {{tap_git_url}}
+    brew install --formula {{release_repo}}/{{cli_key}}
+    @echo ""
+    @echo "Next: {{cli_key}} configure"
+
+# Alias for backward compatibility
+reinstall: reinstall-local
+
+# Rebuild binary and swap into Cellar (run install-local first)
+reinstall-local: build
+    install -m 755 dist/{{cli_key}} "$(brew --prefix {{cli_key}})/bin/{{cli_key}}"
+
+# Lint sources without writing
+lint:
+    bun run biome check ./src ./scripts
+
+# Run the CLI from source once
+run *ARGS:
+    bun ./src/index.ts {{ARGS}}
+
+# Generate JSON Schema artifacts from TypeScript types
+schemagen:
+    argsbarg schemagen
+
+# Install bun/npm dependencies
+# Install bun/npm dependencies and generate schemas
+setup:
+    bun install
+    just schemagen
+
+# Run unit tests (after check)
+test: check
+    bun test .
+
+# Bump version, build, publish; or pass --purge to delete stale GitHub releases
+release *ARGS:
+    bun scripts/release.ts {{ARGS}}
+
+# Install release formula from tap and run formula test
+test-release:
+    brew untap {{tap}} 2>/dev/null || true
+    mkdir -p {{tap_parent}}
+    ln -sfn '{{justfile_directory()}}' {{tap_path}}
+    brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    brew install --formula {{tap}}/{{cli_key}}
+    brew test {{cli_key}}
+
+# Typecheck without emitting build artifacts
+typecheck:
+    bun run tsc --noEmit
+
+# Undo just install-local: agent artifacts first, then formula
+uninstall: uninstall-artifacts uninstall-formula
+
+# Remove agent artifacts only (skills, MCP)
+uninstall-artifacts:
+    just run configure --remove-all --yes
+
+# Remove app config file only
+uninstall-config:
+    just run configure --remove-config --yes
+
+# Remove formula and untap
+uninstall-formula:
+    @brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    @brew uninstall --formula {{tap}}/{{cli_key}}-local 2>/dev/null || true
+    @brew untap {{tap}} 2>/dev/null || true
+
+# Remove release formula (does not untap)
+uninstall-release:
+    @brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+
+# Remove release formula and untap
+uninstall-release-tap:
+    @brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    @brew untap {{tap}} 2>/dev/null || true

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

@@ -0,0 +1,22 @@
+{
+  "name": "full-example-json",
+  "private": true,
+  "type": "module",
+  "module": "src/index.ts",
+  "description": "Argsbarg schema-first copy template (@sg schemagen; not published to npm).",
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "scripts": {
+    "biome": "biome",
+    "start": "bun run src/index.ts"
+  },
+  "dependencies": {
+    "argsbarg": "file:../.."
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@types/bun": "^1.3.12",
+    "typescript": "^5.9.3"
+  }
+}

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

@@ -0,0 +1,12 @@
+/** CLI identity — substituted by `argsbarg create`. */
+
+export const createIdentity = {
+  key: "full-example-json",
+  className: "FullExampleJson",
+  tap: "bdombro/bun-argsbarg",
+  homepage: "https://github.com/bdombro/bun-argsbarg",
+  releaseRepo: "bdombro/bun-argsbarg",
+  desc: "Argsbarg schema-first copy template (@sg schemagen, JSON schemas, REST CRUD)",
+  envPrefix: "FULL_EXAMPLE_JSON",
+  template: "json",
+} as const;

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

@@ -0,0 +1,97 @@
+#!/usr/bin/env bun
+/**
+ * Stage or restore the dev Homebrew formula for `just install-local`.
+ * `install` — back up release `Formula/full-example.rb` and write a `file://` dev formula.
+ * `reset` — restore the release formula from backup.
+ */
+
+import { createHash } from "node:crypto";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createIdentity } from "./create-identity.ts";
+import { renderDevFormula } from "./formula-shared.ts";
+
+const { key } = createIdentity;
+const root = join(import.meta.dir, "..");
+const stagingDir = join(root, "Formula", ".staging");
+const stagingPath = join(stagingDir, key);
+const formulaPath = join(root, "Formula", `${key}.rb`);
+const backupPath = join(stagingDir, `${key}.rb.bak`);
+const programPath = join(root, "src/program.ts");
+
+type Command = "install" | "reset";
+
+function usage(): never {
+  process.stderr.write("Usage: bun scripts/dev-formula.ts <install|reset>\n");
+  process.exit(1);
+}
+
+function parseCommand(argv: string[]): Command {
+  const cmd = argv[2];
+  if (cmd === "install" || cmd === "reset") {
+    return cmd;
+  }
+  usage();
+}
+
+function backupReleaseFormula(): void {
+  if (!existsSync(formulaPath)) {
+    return;
+  }
+  mkdirSync(stagingDir, { recursive: true });
+  copyFileSync(formulaPath, backupPath);
+}
+
+function restoreReleaseFormula(): void {
+  if (!existsSync(backupPath)) {
+    return;
+  }
+  copyFileSync(backupPath, formulaPath);
+  unlinkSync(backupPath);
+}
+
+function readVersion(): string {
+  const content = readFileSync(programPath, "utf8");
+  const match = /version:\s*"([^"]+)"/.exec(content);
+  if (!match?.[1]) {
+    process.stderr.write(`Could not read version from ${programPath}\n`);
+    process.exit(1);
+  }
+  return match[1];
+}
+
+function stageDevFormula(): void {
+  const distPath = join(root, "dist", key);
+  if (!existsSync(distPath)) {
+    process.stderr.write(`Missing binary: ${distPath} (run just build first)\n`);
+    process.exit(1);
+  }
+  mkdirSync(stagingDir, { recursive: true });
+  copyFileSync(distPath, stagingPath);
+  chmodSync(stagingPath, 0o755);
+
+  const sha256 = createHash("sha256").update(readFileSync(stagingPath)).digest("hex");
+  writeFileSync(formulaPath, renderDevFormula(stagingPath, readVersion(), sha256), "utf8");
+}
+
+function install(): void {
+  backupReleaseFormula();
+  stageDevFormula();
+  console.log(`Wrote dev formula: ${formulaPath}`);
+}
+
+function reset(): void {
+  if (!existsSync(backupPath)) {
+    console.log("No dev formula backup to restore.");
+    return;
+  }
+  restoreReleaseFormula();
+  console.log(`Restored ${formulaPath}`);
+}
+
+const command = parseCommand(process.argv);
+if (command === "install") {
+  install();
+} else {
+  reset();
+}

package/examples/full-example-json/scripts/formula-shared.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  buildReleaseArchive,
+  releaseArchiveName,
+  releaseFormulaUrl,
+  selectStaleReleaseTags,
+} from "./formula-shared.ts";
+
+describe("releaseArchiveName", () => {
+  test("returns key.zip", () => {
+    expect(releaseArchiveName()).toBe("full-example-json.zip");
+  });
+});
+
+describe("releaseFormulaUrl", () => {
+  test("points at zip asset on GitHub releases", () => {
+    expect(releaseFormulaUrl("1.2.3")).toBe(
+      "https://github.com/bdombro/bun-argsbarg/releases/download/v1.2.3/full-example-json.zip",
+    );
+  });
+});
+
+describe("selectStaleReleaseTags", () => {
+  test("returns empty for zero or one release", () => {
+    expect(selectStaleReleaseTags([])).toEqual([]);
+    expect(selectStaleReleaseTags([{ tagName: "v1.0.0", publishedAt: "2026-01-01T00:00:00Z" }])).toEqual([]);
+  });
+
+  test("keeps newest by publishedAt and returns the rest", () => {
+    const releases = [
+      { tagName: "v1.0.0", publishedAt: "2026-01-01T00:00:00Z" },
+      { tagName: "v1.1.0", publishedAt: "2026-02-01T00:00:00Z" },
+      { tagName: "v1.0.1", publishedAt: "2026-01-15T00:00:00Z" },
+    ];
+    expect(selectStaleReleaseTags(releases)).toEqual(["v1.0.1", "v1.0.0"]);
+  });
+});
+
+describe("buildReleaseArchive", () => {
+  const workDirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of workDirs.splice(0)) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("creates zip with binary at archive root and matching sha256", async () => {
+    const work = mkdtempSync(join(tmpdir(), "argsbarg-release-zip-"));
+    workDirs.push(work);
+    const binaryPath = join(work, "full-example-json");
+    writeFileSync(binaryPath, "#!/bin/sh\necho hi\n", { mode: 0o755 });
+
+    const { archivePath, sha256 } = await buildReleaseArchive(binaryPath);
+
+    expect(archivePath).toBe(`${binaryPath}.zip`);
+    const onDisk = createHash("sha256").update(readFileSync(archivePath)).digest("hex");
+    expect(sha256).toBe(onDisk);
+
+    const listing = execFileSync("unzip", ["-l", archivePath], { encoding: "utf8" });
+    expect(listing).toContain("full-example-json");
+  });
+});

package/examples/full-example-json/scripts/formula-shared.ts

@@ -0,0 +1,170 @@
+/** Shared Ruby fragments embedded in Homebrew formulae. */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { $ } from "bun";
+import { createIdentity } from "./create-identity.ts";
+
+const { key, className, desc, homepage, releaseRepo } = createIdentity;
+
+/** GitHub release row used by {@link selectStaleReleaseTags}. */
+export interface ReleaseTag {
+  tagName: string;
+  publishedAt: string;
+}
+
+export const formulaInstallRuby = `def install
+    bin.install "${key}"
+    chmod 0755, bin/"${key}"
+    generate_completions_from_executable(bin/"${key}", "completion", base_name: "${key}")
+  end`;
+
+export const formulaPostInstallRuby = `def post_install
+    system bin/"${key}", "configure", "--sync", "--yes"
+  end`;
+
+export const formulaUninstallRuby = `def uninstall
+    system bin/"${key}", "configure", "--remove-all", "--yes"
+  end`;
+
+export const formulaCaveatsRuby = `def caveats
+    <<~EOS
+      Run \`${key} 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`;
+
+export const formulaTestRuby = `test do
+    assert_match version.to_s, shell_output("#{bin}/${key} version")
+    assert_predicate bash_completion/"${key}", :exist?
+    assert_predicate zsh_completion/"_${key}", :exist?
+    assert_predicate fish_completion/"${key}.fish", :exist?
+  end`;
+
+export interface FormulaCoords {
+  url: string;
+  urlStanza: string;
+  version: string;
+  /** SHA-256 hex digest of the release archive at `url` (zip for GitHub releases). */
+  sha256: string;
+  /** When true, embed {@link githubPrivateReleaseDownloadStrategyRuby} in the formula class. */
+  privateRelease?: boolean;
+}
+
+/** Release asset filename on GitHub (zip containing the bare binary at archive root). */
+export function releaseArchiveName(): string {
+  return `${key}.zip`;
+}
+
+/** Build `{binaryPath}.zip` from a compiled binary; return archive path and sha256 of the zip. */
+export async function buildReleaseArchive(binaryPath: string): Promise<{ archivePath: string; sha256: string }> {
+  const archivePath = `${binaryPath}.zip`;
+  const result = await $`zip -j -9 ${archivePath} ${binaryPath}`.nothrow();
+  if (result.exitCode !== 0) {
+    throw new Error(`zip failed: ${result.stderr}`);
+  }
+  const sha256 = createHash("sha256").update(readFileSync(archivePath)).digest("hex");
+  return { archivePath, sha256 };
+}
+
+/** Tags to delete when keeping only the newest release (sorted by `publishedAt` desc). */
+export function selectStaleReleaseTags(releases: ReleaseTag[]): string[] {
+  if (releases.length <= 1) {
+    return [];
+  }
+  const sorted = [...releases].sort((a, b) => b.publishedAt.localeCompare(a.publishedAt));
+  return sorted.slice(1).map((r) => r.tagName);
+}
+
+/** GitHub `org/repo` slug for release and purge commands. */
+export const releaseRepoSlug = releaseRepo;
+
+/** Resolves private GitHub release assets via the API at download time. */
+export const githubPrivateReleaseDownloadStrategyRuby = `  # Private/internal releases: default CurlDownloadStrategy cannot fetch non-public
+  # GitHub release assets. Resolve the asset via the API and authenticate with
+  # GitHub::API.credentials (set up via \`gh auth login\` or HOMEBREW_GITHUB_API_TOKEN).
+  class GitHubPrivateReleaseDownloadStrategy < CurlDownloadStrategy
+    def initialize(url, name, version, **meta)
+      super
+      pattern = %r{https://github\\.com/([^/]+)/([^/]+)/releases/download/([^/]+)/(\\S+)}
+      match = url.match(pattern)
+      raise CurlDownloadStrategyError, "Invalid GitHub release URL: #{url}" unless match
+      @owner, @repo, @tag, @filename = match.captures
+    end
+
+    def _fetch(url:, resolved_url: resolved_download_url, timeout:)
+      curl_download resolved_download_url,
+                    "--header", "Accept: application/octet-stream",
+                    "--header", "Authorization: Bearer #{GitHub::API.credentials}",
+                    to: temporary_path
+    end
+
+    private
+
+    def resolved_download_url
+      @resolved_download_url ||= begin
+        asset = GitHub.get_release(@owner, @repo, @tag).fetch("assets")
+          .find { |a| a["name"] == @filename }
+        raise CurlDownloadStrategyError, "Release asset not found: #{@filename}" unless asset
+        asset.fetch("url")
+      end
+    end
+  end`;
+
+/** Homebrew `url` for local dev staging paths. */
+export function devUrlStanza(url: string): string {
+  return `url "${url}"`;
+}
+
+/** Homebrew `url` for GitHub release assets (uses {@link githubPrivateReleaseDownloadStrategyRuby}). */
+export function releaseUrlStanza(url: string): string {
+  return `url "${url}",
+      using: GitHubPrivateReleaseDownloadStrategy`;
+}
+
+export function releaseFormulaUrl(version: string): string {
+  return `https://github.com/${releaseRepo}/releases/download/v${version}/${releaseArchiveName()}`;
+}
+
+export function renderFormula(coords: FormulaCoords): string {
+  const strategyBlock = coords.privateRelease ? `\n${githubPrivateReleaseDownloadStrategyRuby}\n\n  ` : "";
+  return `class ${className} < Formula
+  desc "${desc}"
+  homepage "${homepage}"
+  version "${coords.version}"
+  sha256 "${coords.sha256}"
+
+  ${formulaInstallRuby}
+
+  ${formulaPostInstallRuby}
+
+  ${formulaUninstallRuby}
+
+  ${formulaCaveatsRuby}
+
+  ${formulaTestRuby}
+${strategyBlock}${coords.urlStanza}
+end
+`;
+}
+
+export function renderReleaseFormula(version: string, sha256: string): string {
+  const url = releaseFormulaUrl(version);
+  return renderFormula({
+    url,
+    urlStanza: releaseUrlStanza(url),
+    version,
+    sha256,
+    privateRelease: true,
+  });
+}
+
+export function renderDevFormula(stagingPath: string, version: string, sha256: string): string {
+  const url = `file://${stagingPath}`;
+  return renderFormula({
+    url,
+    urlStanza: devUrlStanza(url),
+    version,
+    sha256,
+  });
+}

package/examples/full-example-json/scripts/print-identity.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+/** Print a field from scripts/create-identity.ts for justfile backticks. */
+
+import { createIdentity } from "./create-identity.ts";
+
+const field = process.argv[2];
+if (!field) {
+  console.error("Usage: bun scripts/print-identity.ts <key|className|tap|tapOrg|tapRepo|releaseRepo|envPrefix>");
+  process.exit(1);
+}
+
+const [tapOrg, tapRepo] = createIdentity.tap.split("/");
+const values: Record<string, string> = {
+  key: createIdentity.key,
+  className: createIdentity.className,
+  tap: createIdentity.tap,
+  tapOrg: tapOrg ?? "",
+  tapRepo: tapRepo ?? "",
+  envPrefix: createIdentity.envPrefix,
+  releaseRepo: createIdentity.releaseRepo,
+};
+
+const value = values[field];
+if (value === undefined) {
+  console.error(`Unknown field: ${field}`);
+  process.exit(1);
+}
+process.stdout.write(value);