argsbarg 4.1.0 → 5.0.1

package/examples/full-example/justfile

@@ -0,0 +1,134 @@
+set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
+
+HOMEBREW_NO_AUTO_UPDATE := "1"
+HOMEBREW_NO_INSTALL_CLEANUP := "1"
+HOMEBREW_NO_ENV_HINTS := "1"
+
+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`
+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
+
+# Run schemagen, git diff check, typecheck, and format
+check: schemagen
+    git diff --exit-code schemas/
+    just typecheck
+    just format
+
+# Run the CLI from source with optional args; restarts on file changes
+dev *ARGS:
+    bun --watch ./src/index.ts {{ARGS}}
+
+# Regenerate docs/schema.json and docs/skill.md
+docgen: schemagen
+    @just run docs schema --save
+    @just run docs skill --save
+
+alias fmt := format
+
+# Format and lint sources (auto-fix)
+format:
+    bun run biome check ./src ./scripts --write
+
+# 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, write dev formula, symlink tap, brew install
+install-local: build
+    @bun scripts/gen-dev-formula.ts
+    @brew untap {{tap}} 2>/dev/null || true
+    mkdir -p {{tap_parent}}
+    ln -sfn '{{justfile_directory()}}' {{tap_path}}
+    brew install --formula {{tap}}/{{cli_key}}
+    @echo ""
+    @echo "Next: {{cli_key}} configure"
+
+# Remove local dev install, then install from GitHub tap
+install-production: uninstall
+    brew tap {{tap}}
+    brew install --formula {{tap}}/{{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:
+    bun run schemagen
+    just format
+
+# Install bun/npm dependencies
+setup:
+    bun install
+
+# Run unit tests (after check)
+test: check
+    bun test .
+
+# 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/{consumer-app → full-example}/package.json

@@ -1,16 +1,23 @@
 {
-  "name": "consumer-app-example",
+  "name": "full-example",
   "private": true,
   "type": "module",
-  "description": "Argsbarg kitchen-sink reference app (copy template; not published to npm).",
+  "module": "src/index.ts",
+  "description": "Argsbarg full example reference app (copy template; not published to npm).",
+  "engines": {
+    "bun": ">=1.3"
+  },
   "scripts": {
+    "biome": "biome",
     "schemagen": "bun run scripts/schemagen.ts",
-    "start": "bun run src/main.ts"
+    "start": "bun run src/index.ts"
   },
   "dependencies": {
     "argsbarg": "file:../.."
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@types/bun": "^1.3.12",
     "ts-json-schema-generator": "^2.3.0",
     "typescript": "^5.9.3"
   }

package/examples/{consumer-app → full-example}/schemas/generated/app-config.json

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

package/examples/{consumer-app → full-example}/schemas/generated/status.json

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

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

@@ -0,0 +1,11 @@
+/** CLI identity — substituted by `argsbarg create`. */
+
+export const createIdentity = {
+  key: "full-example",
+  className: "FullExample",
+  tap: "local/full-example",
+  homepage: "https://github.com/bdombro/bun-argsbarg",
+  releaseRepo: "bdombro/bun-argsbarg",
+  desc: "Argsbarg full example reference app",
+  envPrefix: "FULL_EXAMPLE",
+} as const;

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

@@ -0,0 +1,73 @@
+/** Shared Ruby fragments embedded in Homebrew formulae. */
+
+import { createIdentity } from "./create-identity.ts";
+
+const { key, className, desc, homepage, releaseRepo } = createIdentity;
+
+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 formulaCaveatsRuby = `def caveats
+    <<~EOS
+      Run \`${key} configure\` to set up agent artifacts and app config (interactive).
+    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;
+  version: string;
+  sha256: string;
+}
+
+export function releaseFormulaUrl(version: string): string {
+  return `https://github.com/${releaseRepo}/releases/download/v${version}/${key}`;
+}
+
+export function renderFormula(coords: FormulaCoords): string {
+  return `class ${className} < Formula
+  desc "${desc}"
+  homepage "${homepage}"
+  url "${coords.url}"
+  version "${coords.version}"
+  sha256 "${coords.sha256}"
+{dependsOnBlock}
+  ${formulaInstallRuby}
+
+  ${formulaPostInstallRuby}
+
+  ${formulaCaveatsRuby}
+
+  ${formulaTestRuby}
+end
+`;
+}
+
+export function renderReleaseFormula(version: string, sha256: string): string {
+  return renderFormula({
+    url: releaseFormulaUrl(version),
+    version,
+    sha256,
+  });
+}
+
+export function renderDevFormula(stagingPath: string, version: string, sha256: string): string {
+  return renderFormula({
+    url: `file://${stagingPath}`,
+    version,
+    sha256,
+  });
+}

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

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+/** Generate Formula/full-example.rb for local dev install (same formula as release; file:// URL only). */
+
+import { createHash } from "node:crypto";
+import { chmodSync, copyFileSync, mkdirSync, readFileSync, 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 distPath = join(root, "dist", key);
+const stagingDir = join(root, "Formula", ".staging");
+const stagingPath = join(stagingDir, key);
+
+mkdirSync(stagingDir, { recursive: true });
+copyFileSync(distPath, stagingPath);
+chmodSync(stagingPath, 0o755);
+
+const binary = readFileSync(stagingPath);
+const sha256 = createHash("sha256").update(binary).digest("hex");
+const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version as string;
+
+const out = join(root, "Formula", `${key}.rb`);
+writeFileSync(out, renderDevFormula(stagingPath, version, sha256), "utf8");
+console.log(`Wrote ${out}`);

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

@@ -0,0 +1,27 @@
+#!/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|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,
+};
+
+const value = values[field];
+if (value === undefined) {
+  console.error(`Unknown field: ${field}`);
+  process.exit(1);
+}
+process.stdout.write(value);

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

@@ -0,0 +1,21 @@
+/*
+Echo leaf — minimal MCP-friendly command.
+*/
+
+import { type CliLeaf, CliOptionKind } from "argsbarg";
+
+export const echoCommand = {
+  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 CliLeaf;

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

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

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

@@ -0,0 +1,36 @@
+/*
+Status leaf — demonstrates outputSchema and ctx.appConfig.
+*/
+
+import { type CliLeaf, CliOptionKind } from "argsbarg";
+import { STATUS_JSON_OUTPUT_SCHEMA } from "../../../schemas/outputSchemas.ts";
+import type { StatusJsonOutput } from "./types.ts";
+
+export const statusCommand = {
+  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"}`);
+    }
+  },
+} satisfies CliLeaf;

package/examples/{consumer-app → full-example}/src/commands/status/types.ts

@@ -1,4 +1,4 @@
-/** JSON payload for `consumer-app status --json`. */
+/** JSON payload for `full-example status --json`. */
 export interface StatusJsonOutput {
   /** Resolved AWS region. */
   defaultRegion?: string;

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

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+/*
+Thin CLI entry — delegates to argsbarg runtime.
+*/
+
+import { Cli } from "argsbarg";
+import { program } from "./program.ts";
+
+const cli = new Cli(program);
+await cli.run();

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

@@ -0,0 +1,57 @@
+/*
+Kitchen-sink CliProgram — every argsbarg builtin enabled; command registration only.
+*/
+
+import type { CliAppConfig, CliAppConfigEntry, CliProgram } from "argsbarg";
+import readmeText from "../README.md" with { type: "text" };
+import { APP_CONFIG_JSON_SCHEMA } from "../schemas/configSchemas.ts";
+import { createIdentity } from "../scripts/create-identity.ts";
+import { echoCommand } from "./commands/echo/command.ts";
+import { statusCommand } from "./commands/status/command.ts";
+
+const configSchema = {
+  apiToken: {
+    description: "Create at https://example.com/settings/tokens",
+    env: `${createIdentity.envPrefix}_API_TOKEN`,
+    sensitive: true,
+  },
+  defaultRegion: {
+    description: "AWS region for API calls.",
+    required: false,
+  },
+  maxRetries: {
+    description: "HTTP retry count (0–10).",
+    required: false,
+  },
+  prefs: {
+    description: "Local cache preferences (not exported to env).",
+    required: false,
+  },
+} as const satisfies Record<string, CliAppConfigEntry>;
+
+export const program = {
+  key: createIdentity.key,
+  version: "1.0.0",
+  description: createIdentity.desc,
+  appConfig: {
+    jsonSchema: APP_CONFIG_JSON_SCHEMA,
+    entries: configSchema,
+  } satisfies CliAppConfig,
+  docs: {
+    enabled: true,
+    topics: {
+      readme: {
+        text: readmeText,
+      },
+    },
+  },
+  mcpServer: {
+    enabled: true,
+    mcpd: true,
+    claudePlugin: true,
+  },
+  configure: {
+    // Defaults: agentIntegration picks skill vs MCP for sync; app config is opt-in in interactive configure.
+  },
+  commands: [echoCommand, statusCommand],
+} satisfies CliProgram;

package/examples/{consumer-app → full-example}/src/types.ts

@@ -1,7 +1,7 @@
 /**
  * Config schema
  *
- * Application settings for `consumer-app` (`program.appConfig`).
+ * Application settings for `full-example` (`program.appConfig`).
  */
 export interface AppConfig {
   /** API token from the provider dashboard. */

package/examples/nested.ts

@@ -21,9 +21,7 @@ const program = {
       readme: { text: "# nested.ts\n\nNested groups demo.\n" },
     },
   },
-  install: {
-    updateGetLatest: async () => ({ path: process.execPath, version: pkg.version }),
-  },
+  configure: {},
   commands: [
     {
       key: "stat",