argsbarg 6.1.10 → 6.2.2

package/examples/full-example-json/scripts/release.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env bun
+/** Bump version, build, publish zip release; optional `--purge` to drop stale GitHub releases. */
+
+import * as fs from "node:fs";
+import { stdin as input, stdout as output } from "node:process";
+import * as readline from "node:readline/promises";
+import { $ } from "bun";
+import { createIdentity } from "./create-identity.ts";
+import {
+  buildReleaseArchive,
+  type ReleaseTag,
+  releaseRepoSlug,
+  renderReleaseFormula,
+  selectStaleReleaseTags,
+} from "./formula-shared.ts";
+
+const { key } = createIdentity;
+const formulaPath = `Formula/${key}.rb`;
+const binaryPath = `dist/${key}`;
+const programPath = "src/program.ts";
+
+/** Allowed semver bump kinds for `scripts/release.ts`. */
+type Bump = "major" | "minor" | "patch";
+
+interface ReleaseOptions {
+  bump?: Bump;
+  purge: boolean;
+  yes: boolean;
+  dryRun: boolean;
+}
+
+/** Entry point: release bump, purge-only, or release then purge. */
+async function main(): Promise<void> {
+  const options = parseOptions(process.argv.slice(2));
+  if (options.purge && !options.bump) {
+    await purgeStaleReleases(options);
+    return;
+  }
+  if (!options.bump) {
+    usage();
+  }
+  await runRelease(options.bump, options);
+}
+
+/** Prints usage and exits. */
+function usage(): never {
+  process.stderr.write(
+    "Usage:\n" +
+      "  bun scripts/release.ts <major|minor|patch> [--purge]\n" +
+      "  bun scripts/release.ts --purge [--yes] [--dry-run]\n",
+  );
+  process.exit(1);
+}
+
+/** Parses argv into release options. */
+function parseOptions(argv: string[]): ReleaseOptions {
+  const yes = argv.includes("--yes");
+  const dryRun = argv.includes("--dry-run");
+  const purge = argv.includes("--purge");
+  const bump = argv.find((a): a is Bump => a === "major" || a === "minor" || a === "patch");
+  for (const arg of argv) {
+    if (arg.startsWith("--") && arg !== "--purge" && arg !== "--yes" && arg !== "--dry-run") {
+      usage();
+    }
+  }
+  if (!purge && !bump) {
+    usage();
+  }
+  return { bump, purge, yes, dryRun };
+}
+
+/** Full release pipeline for a semver bump. */
+async function runRelease(bump: Bump, options: ReleaseOptions): Promise<void> {
+  const testResult = await $`just test`.nothrow();
+  if (testResult.exitCode !== 0) process.exit(testResult.exitCode);
+
+  const currentVersion = readCurrentVersion();
+  const newVersion = applyBump(currentVersion, bump);
+  console.log(`Releasing ${currentVersion} → ${newVersion}`);
+
+  updateVersion(newVersion);
+  updateChangelog(newVersion);
+
+  const buildResult = await $`just build`.nothrow();
+  if (buildResult.exitCode !== 0) process.exit(buildResult.exitCode);
+
+  const archivePath = await updateReleaseFormula(newVersion);
+
+  const docgenResult = await $`just docgen`.nothrow();
+  if (docgenResult.exitCode !== 0) process.exit(docgenResult.exitCode);
+
+  await commitAndTag(newVersion);
+  await createGithubRelease(`v${newVersion}`, archivePath);
+
+  console.log(`Released v${newVersion}`);
+
+  if (options.purge) {
+    await purgeStaleReleases(options);
+  }
+}
+
+/** Applies a semver bump to `current` and returns the new version string. */
+function applyBump(current: string, bump: Bump): string {
+  const [major, minor, patch] = current.split(".").map(Number) as [number, number, number];
+  if (bump === "major") return `${major + 1}.0.0`;
+  if (bump === "minor") return `${major}.${minor + 1}.0`;
+  return `${major}.${minor}.${patch + 1}`;
+}
+
+/** Commits all staged changes, creates an annotated tag, and pushes both to origin. */
+async function commitAndTag(newVersion: string): Promise<void> {
+  await $`git add -A`;
+  await $`git commit -m ${`chore: release v${newVersion}`}`;
+  await $`git tag v${newVersion}`;
+  await $`git push`;
+  await $`git push origin v${newVersion}`;
+}
+
+/** Creates a GitHub release for `tag` with the zip archive attached. */
+async function createGithubRelease(tag: string, archivePath: string): Promise<void> {
+  await $`gh release create ${tag} ${archivePath} --title ${tag} --generate-notes`;
+}
+
+/** Reads the CLI version from `src/program.ts`. */
+function readCurrentVersion(): string {
+  const content = fs.readFileSync(programPath, "utf-8");
+  const match = /version:\s*"([^"]+)"/.exec(content);
+  if (!match) {
+    process.stderr.write(`Could not read version from ${programPath}\n`);
+    process.exit(1);
+  }
+  const version = match[1];
+  if (!version) {
+    process.stderr.write(`Could not read version from ${programPath}\n`);
+    process.exit(1);
+  }
+  const parts = version.split(".").map(Number);
+  if (parts.length !== 3 || parts.some(Number.isNaN)) {
+    process.stderr.write(`Invalid semver in ${programPath}: ${version}\n`);
+    process.exit(1);
+  }
+  return version;
+}
+
+/** Promotes `[Unreleased]` to a dated version section in `CHANGELOG.md`. */
+function updateChangelog(newVersion: string): void {
+  const changelogPath = "CHANGELOG.md";
+  const content = fs.readFileSync(changelogPath, "utf-8");
+  const date = new Date().toISOString().slice(0, 10);
+  fs.writeFileSync(
+    changelogPath,
+    content.replace(/^## \[Unreleased\]/m, `## [Unreleased]\n\n## [${newVersion}] - ${date}`),
+  );
+}
+
+/** Overwrites the version literal in `src/program.ts`. */
+function updateVersion(newVersion: string): void {
+  const content = fs.readFileSync(programPath, "utf-8");
+  fs.writeFileSync(programPath, content.replace(/version:\s*"[^"]+"/, `version: "${newVersion}"`));
+}
+
+/** Writes the release formula with zip URL and archive sha256; returns the archive path. */
+async function updateReleaseFormula(version: string): Promise<string> {
+  const { archivePath, sha256 } = await buildReleaseArchive(binaryPath);
+  fs.writeFileSync(formulaPath, renderReleaseFormula(version, sha256));
+  return archivePath;
+}
+
+/** Deletes all GitHub releases except the most recent. */
+async function purgeStaleReleases(options: ReleaseOptions): Promise<void> {
+  const list = await $`gh release list -R ${releaseRepoSlug} --json tagName,publishedAt`.nothrow();
+  if (list.exitCode !== 0) process.exit(list.exitCode);
+
+  const releases = JSON.parse(list.stdout.toString()) as ReleaseTag[];
+  const toDelete = selectStaleReleaseTags(releases);
+
+  if (toDelete.length === 0) {
+    console.log("No stale releases to delete.");
+    return;
+  }
+
+  console.log(`Will delete ${toDelete.length} release(s):`);
+  for (const tag of toDelete) {
+    console.log(`  ${tag}`);
+  }
+
+  if (options.dryRun) {
+    return;
+  }
+
+  if (!options.yes) {
+    if (!input.isTTY) {
+      process.stderr.write("Not a TTY; pass --yes to confirm purge.\n");
+      process.exit(1);
+    }
+    const rl = readline.createInterface({ input, output });
+    const answer = await rl.question("Delete these releases? [y/N] ");
+    rl.close();
+    if (answer.trim().toLowerCase() !== "y") {
+      console.log("Aborted.");
+      return;
+    }
+  }
+
+  for (const tag of toDelete) {
+    const del = await $`gh release delete ${tag} -R ${releaseRepoSlug} --yes`.nothrow();
+    if (del.exitCode !== 0) process.exit(del.exitCode);
+    console.log(`Deleted ${tag}`);
+  }
+}
+
+await main();

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

@@ -0,0 +1,26 @@
+/*
+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) => {
+    const message = ctx.stringOpt("message") ?? "";
+    if (ctx.invocation === "cli") {
+      console.log(message);
+      return;
+    }
+    return message;
+  },
+} satisfies CliLeaf;

package/examples/full-example-json/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-json/src/commands/status/command.ts

@@ -0,0 +1,28 @@
+/*
+Status leaf — demonstrates outputSchema.
+*/
+
+import { type CliLeaf, CliOptionKind } from "argsbarg";
+import { StatusJsonOutputSchema } from "./__generated__";
+import type { StatusJsonOutput } from "./types.ts";
+
+export const statusCommand = {
+  key: "status",
+  description: "Show app version.",
+  options: [
+    {
+      name: "json",
+      description: "Emit JSON.",
+      kind: CliOptionKind.Presence,
+    },
+  ],
+  outputSchema: StatusJsonOutputSchema,
+  handler: (ctx) => {
+    const out: StatusJsonOutput = { version: ctx.program.version };
+    if (ctx.hasFlag("json")) {
+      console.log(JSON.stringify(out, null, 2));
+    } else {
+      console.log(`version=${out.version}`);
+    }
+  },
+} satisfies CliLeaf;

package/examples/full-example-json/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-json/src/program.ts

@@ -0,0 +1,33 @@
+/*
+Reference CliProgram — builtins on; command registration only.
+*/
+
+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 = {
+  commands: [echoCommand, renderJsonCommand, statusCommand, workspacesCommand],
+  description: createIdentity.desc,
+  docs: {
+    topics: {
+      readme: {
+        text: readmeText,
+      },
+    },
+  },
+  hooks: {
+    beforeInvoke: AppDb.attach,
+  },
+  httpServer: { enabled: true },
+  key: createIdentity.key,
+  mcpServer: { enabled: true },
+  readiness: AppDb.checkReadiness,
+  skill: { enabled: true },
+  version: "1.0.0",
+} satisfies CliProgram;

package/examples/full-example-json/src/types/md.d.ts

@@ -0,0 +1,4 @@
+declare module "*.md" {
+  const text: string;
+  export default text;
+}

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

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["bun"],
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts", "scripts/**/*.ts"]
+}

package/examples/minimal.ts

@@ -11,9 +11,23 @@ import pkg from "../package.json" with { type: "json" };
 import { Cli, CliOptionKind, type CliProgram } from "../src/index";
 
 const program = {
-  key: "minimal.ts",
-  version: pkg.version,
   description: "Tiny demo.",
+  handler: (ctx) => {
+    const name = ctx.args[0] ?? "world";
+    if (ctx.hasFlag("verbose")) {
+      console.log("verbose mode");
+    }
+    console.log(`hello ${name}`);
+  },
+  key: "minimal.ts",
+  options: [
+    {
+      name: "verbose",
+      description: "Enable extra logging.",
+      kind: CliOptionKind.Presence,
+      shortName: "v",
+    },
+  ],
   positionals: [
     {
       name: "name",
@@ -23,21 +37,7 @@ const program = {
       argMax: 1,
     },
   ],
-  options: [
-    {
-      name: "verbose",
-      description: "Enable extra logging.",
-      kind: CliOptionKind.Presence,
-      shortName: "v",
-    },
-  ],
-  handler: (ctx) => {
-    const name = ctx.args[0] ?? "world";
-    if (ctx.hasFlag("verbose")) {
-      console.log("verbose mode");
-    }
-    console.log(`hello ${name}`);
-  },
+  version: pkg.version,
 } satisfies CliProgram;
 
 const cli = new Cli(program);

package/examples/nested.ts

@@ -11,16 +11,6 @@ import pkg from "../package.json" with { type: "json" };
 import { Cli, CliFallbackMode, CliOptionKind, type CliProgram } from "../src/index";
 
 const program = {
-  key: "nested.ts",
-  version: pkg.version,
-  description: "Nested groups demo.",
-  mcpServer: { enabled: true },
-  docs: {
-    topics: {
-      readme: { text: "# nested.ts\n\nNested groups demo.\n" },
-    },
-  },
-  configure: {},
   commands: [
     {
       key: "stat",
@@ -112,8 +102,18 @@ const program = {
       },
     },
   ],
+  configure: {},
+  description: "Nested groups demo.",
+  docs: {
+    topics: {
+      readme: { text: "# nested.ts\n\nNested groups demo.\n" },
+    },
+  },
   fallbackCommand: "read",
   fallbackMode: CliFallbackMode.MissingOrUnknown,
+  key: "nested.ts",
+  mcpServer: { enabled: true },
+  version: pkg.version,
 } satisfies CliProgram;
 
 const cli = new Cli(program);

package/examples/option-required.ts

@@ -11,9 +11,19 @@ import pkg from "../package.json" with { type: "json" };
 import { Cli, CliOptionKind, type CliProgram, isInteractiveTty } from "../src/index";
 
 const program = {
-  key: "option-required.ts",
-  version: pkg.version,
   description: "Demo of a required option.",
+  handler: (ctx) => {
+    const requiredAlways = ctx.stringOpt("requiredAlways");
+    if (requiredAlways === undefined) {
+      throw new Error("requiredAlways missing after validation");
+    }
+    const requiredNonTty = ctx.stringOpt("requiredNonTty") ?? "valueWhenOmitted";
+    const optional = ctx.stringOpt("optional") ?? "valueWhenOmitted";
+    console.log(`requiredAlways: ${requiredAlways}`);
+    console.log(`requiredNonTty: ${requiredNonTty}`);
+    console.log(`optional: ${optional}`);
+  },
+  key: "option-required.ts",
   options: [
     {
       name: "requiredAlways",
@@ -36,17 +46,7 @@ const program = {
       shortName: "o",
     },
   ],
-  handler: (ctx) => {
-    const requiredAlways = ctx.stringOpt("requiredAlways");
-    if (requiredAlways === undefined) {
-      throw new Error("requiredAlways missing after validation");
-    }
-    const requiredNonTty = ctx.stringOpt("requiredNonTty") ?? "valueWhenOmitted";
-    const optional = ctx.stringOpt("optional") ?? "valueWhenOmitted";
-    console.log(`requiredAlways: ${requiredAlways}`);
-    console.log(`requiredNonTty: ${requiredNonTty}`);
-    console.log(`optional: ${optional}`);
-  },
+  version: pkg.version,
 } satisfies CliProgram;
 
 const cli = new Cli(program);

package/examples/servers.ts

@@ -20,16 +20,6 @@ import pkg from "../package.json" with { type: "json" };
 import { Cli, CliOptionKind, type CliProgram } from "../src/index";
 
 const program = {
-  key: "servers.ts",
-  version: pkg.version,
-  description: "Tiny demo.",
-  mcpServer: { enabled: true },
-  httpServer: { enabled: true },
-  docs: {
-    topics: {
-      readme: { text: "# servers.ts\n\nServers demo.\n" },
-    },
-  },
   commands: [
     {
       key: "hello",
@@ -65,6 +55,16 @@ const program = {
       },
     },
   ],
+  description: "Tiny demo.",
+  docs: {
+    topics: {
+      readme: { text: "# servers.ts\n\nServers demo.\n" },
+    },
+  },
+  httpServer: { enabled: true },
+  key: "servers.ts",
+  mcpServer: { enabled: true },
+  version: pkg.version,
 } satisfies CliProgram;
 
 const cli = new Cli(program);

package/index.d.ts

@@ -533,22 +533,18 @@ export interface CliCompletionConfig {
 	/** When `false`, hide/disable `completion` (default: enabled). */
 	enabled?: boolean;
 }
+/** Opt-in agent skill install to `~/.agents/skills/<key>/` (default: disabled). */
+export interface CliSkillConfig {
+	/** When `true`, install and sync the agent skill via `configure --sync`. Default false when omitted. */
+	enabled?: boolean;
+}
 /** @experimental */
 export interface CliConfigureConfig {
 	/** When `false`, hide/disable `configure` (default: enabled). */
 	enabled?: boolean;
-	/**
-	 * Default agent integration for sync (`configure --sync`).
-	 * - `'mcp'` when `mcpServer.enabled` (default): MCP targets in sync; paired skills excluded.
-	 * - `'skill'` when MCP is off (default): skill targets in sync; paired MCP excluded.
-	 * - `'both'`: sync MCP and skill for the same host when both are available.
-	 */
-	agentIntegration?: InstallAgentIntegration;
 	/** Per-artifact gates for configure sync and interactive wizard. See {@link resolveEffectiveInstallTargets}. */
 	targets?: CliConfigureTargets;
 }
-/** Agent integration mode for install — MCP vs shell skill per host. */
-export type InstallAgentIntegration = "mcp" | "skill" | "both";
 /** Boolean or structured gate for one install artifact. */
 export type InstallTargetSpec = boolean | {
 	/** When false, artifact is never installed (even with scoped CLI flags). Default true. */
@@ -564,32 +560,8 @@ export interface ResolvedInstallTarget {
 export interface CliConfigureTargets {
 	/** App binary status only (Homebrew PATH); no self-install. */
 	app?: InstallTargetSpec;
-	/** ChatGPT desktop MCP. Default false. */
-	chatgptMcp?: InstallTargetSpec;
-	/** Claude Code MCP (`~/.claude.json`). Default false. */
-	claudeCodeMcp?: InstallTargetSpec;
-	/** Claude Desktop MCP. Default false. */
-	claudeDesktopMcp?: InstallTargetSpec;
-	/** Claude Code skill. Default false. */
-	claudeSkill?: InstallTargetSpec;
-	/** Codex MCP (`codex mcp add`). Default false. */
-	codexMcp?: InstallTargetSpec;
-	/** Codex skill. Default false. */
-	codexSkill?: InstallTargetSpec;
 	/** App config: interactive wizard step in `configure`. Default not in sync. */
 	configure?: InstallTargetSpec;
-	/** Cursor MCP. Default false. */
-	cursorMcp?: InstallTargetSpec;
-	/** Cursor skill. Default false. */
-	cursorSkill?: InstallTargetSpec;
-	/** OpenClaw MCP. Default false. */
-	openclawMcp?: InstallTargetSpec;
-	/** OpenClaw skill. Default false. */
-	openclawSkill?: InstallTargetSpec;
-	/** OpenCode MCP. Default false. */
-	opencodeMcp?: InstallTargetSpec;
-	/** OpenCode skill. Default false. */
-	opencodeSkill?: InstallTargetSpec;
 }
 /**
  * One bundled documentation topic for the `docs` built-in (program root only).
@@ -802,26 +774,28 @@ export interface CliLogConfig {
  * May be a leaf or router, plus optional program-level MCP and install config.
  */
 export type CliProgram = CliNode & {
-	/** Program version (printed by the `version` built-in and MCP serverInfo). */
-	version: string;
 	/** Schema-driven app config file, bootstrap, and MCP metadata. */
 	appConfig?: CliAppConfig;
-	/** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
-	mcpServer?: CliMcpServerConfig;
-	/** When set with `enabled: true`, enables the `http` built-in HTTP server. */
-	httpServer?: CliHttpServerConfig;
-	/** Opt-out and defaults for `configure`. */
-	configure?: CliConfigureConfig;
 	/** Opt-out for shell completion generation (`completion bash|zsh|fish`). */
 	completion?: CliCompletionConfig;
+	/** Opt-out and defaults for `configure`. */
+	configure?: CliConfigureConfig;
 	/** Opt-out and optional topics for the `docs` built-in (default: enabled). */
 	docs?: CliDocsConfig;
 	/** Invoke and error hooks for user commands on CLI, HTTP, and MCP. */
 	hooks?: CliProgramHooks;
-	/** Optional readiness probe for HTTP/MCP `GET /health/readiness` only. */
-	readiness?: (ctx: ReadinessContext) => boolean | Promise<boolean>;
+	/** When set with `enabled: true`, enables the `http` built-in HTTP server. */
+	httpServer?: CliHttpServerConfig;
 	/** Framework logging (stderr + optional file). */
 	log?: CliLogConfig;
+	/** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
+	mcpServer?: CliMcpServerConfig;
+	/** Optional readiness probe for HTTP/MCP `GET /health/readiness` only. */
+	readiness?: (ctx: ReadinessContext) => boolean | Promise<boolean>;
+	/** Opt-in agent skill (`~/.agents/skills/<key>/`). Default disabled when omitted. */
+	skill?: CliSkillConfig;
+	/** Program version (printed by the `version` built-in and MCP serverInfo). */
+	version: string;
 };
 /** True when the leaf accepts a pure JSON body (no CLI flags). */
 export declare function isJsonLeaf(leaf: CliLeaf): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "6.1.10",
+  "version": "6.2.2",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {