argsbarg 7.0.11 → 7.1.1

package/examples/mcp-plugin/scripts/release.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env bun
+/*
+Bump version, build standalone Node MCP server, and publish release tag.
+*/
+
+import * as fs from "node:fs";
+import { $ } from "bun";
+
+/** Allowed semver bump kinds for `scripts/release.ts`. */
+type Bump = "major" | "minor" | "patch";
+
+/** Parsed command-line options for release. */
+interface ReleaseOptions {
+  /** Semver segment to increment. */
+  bump?: Bump;
+  /** Whether running in dry-run mode. */
+  dryRun: boolean;
+  /** Whether confirmation is skipped. */
+  yes: boolean;
+}
+
+/** Path to program entrypoint defining the version. */
+const programPath = "src/program.ts";
+
+/** Path to Cursor plugin manifest. */
+const cursorManifestPath = ".cursor-plugin/plugin.json";
+
+/** Path to Claude Code plugin manifest. */
+const claudeManifestPath = ".claude-plugin/plugin.json";
+
+/** Entry point: release bump. */
+async function main(): Promise<void> {
+  const options = parseOptions(process.argv.slice(2));
+  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> [--yes] [--dry-run]\n",
+  );
+  process.exit(1);
+}
+
+/**
+ * Parses argv into release options.
+ */
+function parseOptions(
+  /** Command line arguments. */
+  argv: string[],
+): ReleaseOptions {
+  const yes = argv.includes("--yes");
+  const dryRun = argv.includes("--dry-run");
+  const bump = argv.find((a): a is Bump => a === "major" || a === "minor" || a === "patch");
+  for (const arg of argv) {
+    if (arg.startsWith("--") && arg !== "--yes" && arg !== "--dry-run") {
+      usage();
+    }
+  }
+  if (!bump) {
+    usage();
+  }
+  return { bump, dryRun, yes };
+}
+
+/**
+ * Full release pipeline for a semver bump.
+ */
+async function runRelease(
+  /** Increment segment. */
+  bump: Bump,
+  /** Parsed CLI options. */
+  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 docgenResult = await $`just docgen`.nothrow();
+  if (docgenResult.exitCode !== 0) process.exit(docgenResult.exitCode);
+
+  if (options.dryRun) {
+    console.log(`[dry-run] Would commit, tag v${newVersion}, and create GitHub release.`);
+    return;
+  }
+
+  await commitAndTag(newVersion);
+  await createGithubRelease(`v${newVersion}`);
+
+  console.log(`Released v${newVersion}`);
+}
+
+/**
+ * Reads the current version string 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;
+}
+
+/**
+ * Increments semver according to the specified bump level.
+ */
+function applyBump(
+  /** Existing version string. */
+  version: string,
+  /** Semver segment to increment. */
+  bump: Bump,
+): string {
+  const parts = version.split(".").map(Number) as [number, number, number];
+  if (bump === "major") {
+    return `${parts[0] + 1}.0.0`;
+  }
+  if (bump === "minor") {
+    return `${parts[0]}.${parts[1] + 1}.0`;
+  }
+  return `${parts[0]}.${parts[1]}.${parts[2] + 1}`;
+}
+
+/**
+ * Updates version in package.json, program.ts, and plugin manifests.
+ */
+function updateVersion(
+  /** Incremented version string. */
+  newVersion: string,
+): void {
+  const pkgPath = "package.json";
+  const pkgContent = fs.readFileSync(pkgPath, "utf-8");
+  fs.writeFileSync(
+    pkgPath,
+    pkgContent.replace(/"version":\s*"[^"]+"/, `"version": "${newVersion}"`),
+  );
+
+  const progContent = fs.readFileSync(programPath, "utf-8");
+  fs.writeFileSync(
+    programPath,
+    progContent.replace(/version:\s*"[^"]+"/, `version: "${newVersion}"`),
+  );
+
+  if (fs.existsSync(cursorManifestPath)) {
+    const cursorContent = fs.readFileSync(cursorManifestPath, "utf-8");
+    fs.writeFileSync(
+      cursorManifestPath,
+      cursorContent.replace(/"version":\s*"[^"]+"/, `"version": "${newVersion}"`),
+    );
+  }
+
+  if (fs.existsSync(claudeManifestPath)) {
+    const claudeContent = fs.readFileSync(claudeManifestPath, "utf-8");
+    fs.writeFileSync(
+      claudeManifestPath,
+      claudeContent.replace(/"version":\s*"[^"]+"/, `"version": "${newVersion}"`),
+    );
+  }
+}
+
+/**
+ * Prepends the new release section with date under [Unreleased] in CHANGELOG.md.
+ */
+function updateChangelog(
+  /** Incremented version string. */
+  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}`),
+  );
+}
+
+/**
+ * Stages all changes, creates a release commit, tags it, and pushes to remote.
+ */
+async function commitAndTag(
+  /** Incremented version string. */
+  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 release on GitHub.
+ */
+async function createGithubRelease(
+  /** Git release tag. */
+  tag: string,
+): Promise<void> {
+  await $`gh release create ${tag} --title ${tag} --generate-notes`;
+}
+
+await main();

package/examples/mcp-plugin/skills/mcp-plugin/SKILL.md

@@ -0,0 +1,59 @@
+---
+id: mcp-plugin
+name: mcp-plugin
+description: Operates the mcp-plugin CLI (echo, render-json, status, workspaces :id delete, workspaces :id get, and 4 more). Use when the user mentions mcp-plugin, echo, render-json, status, or related tasks.
+enabled: true
+---
+
+# mcp-plugin
+
+Argsbarg MCP plugin template for Cursor and Claude Code marketplaces (@sg schemagen, JSON schemas, REST CRUD)
+
+## Execution
+
+Invoke via shell:
+
+```bash
+mcp-plugin <subcommand> [options] [args]
+```
+
+## Options & Help Discovery
+
+- Run `mcp-plugin <subcommand> --help` to inspect flags, choices, and positional arguments before running unfamiliar subcommands.
+- Run `mcp-plugin --help` at the root for top-level options and command routing.
+
+## Commands
+
+- **`mcp-plugin echo`** — Echo a message (MCP-friendly leaf).
+- **`mcp-plugin render-json`** — Echo a JSON message (schema-first JSON leaf demo).
+- **`mcp-plugin status`** — Show app version.
+- **`mcp-plugin workspaces :id delete`** — Delete a workspace.
+- **`mcp-plugin workspaces :id get`** — Get one workspace.
+- **`mcp-plugin workspaces :id patch`** — Patch a workspace name.
+- **`mcp-plugin workspaces :id put`** — Replace a workspace.
+- **`mcp-plugin workspaces get`** — List workspaces.
+- **`mcp-plugin workspaces post`** — Create a workspace.
+
+## Workflow & Pitfalls
+
+- Always run `mcp-plugin <subcommand> --help` instead of guessing options or reading large doc files.
+- Pass `--` before arguments that look like flags.
+- Pass `--yes` for non-interactive execution when confirmation is required.
+- Pass `--json` when machine-readable structured output is supported.
+
+## Install location
+
+Install follows the https://dotagentsprotocol.com:
+
+- Auto-install: `mcp-plugin configure install` when `skill.enabled` → `~/.agents/skills/mcp-plugin/`
+- 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/mcp-plugin/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/mcp-plugin/src/commands/render-json/__generated__/RenderJsonInputSchema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "message": {
+      "type": "string",
+      "description": "Message to echo back."
+    }
+  },
+  "required": [
+    "message"
+  ],
+  "additionalProperties": false,
+  "definitions": {}
+}

package/examples/mcp-plugin/src/commands/render-json/__generated__/index.ts

@@ -0,0 +1,5 @@
+// Auto-generated by argsbarg schemagen — do not edit by hand.
+
+import RenderJsonInputSchemaJson from "./RenderJsonInputSchema.json";
+
+export const RenderJsonInputSchema = RenderJsonInputSchemaJson as Record<string, unknown>;

package/examples/mcp-plugin/src/commands/render-json/command.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { Cli, type CliProgram } from "argsbarg";
+import { renderJsonCommand, renderJsonTestProgram } from "./command.ts";
+
+const baseProgram = {
+  key: "full-example",
+  version: "1.0.0",
+  description: "Demo.",
+  httpServer: { enabled: true },
+  commands: [],
+} satisfies CliProgram;
+
+describe("render-json command", () => {
+  const program = renderJsonTestProgram(baseProgram);
+  const cli = new Cli(program);
+
+  test("HTTP invoke returns echoed message", async () => {
+    const result = await cli.invoke(["render-json"], {
+      invocation: "http",
+      toolArgs: { message: "hello" },
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ message: "hello" });
+  });
+
+  test("rejects invalid input before handler via inputSchema", async () => {
+    let handlerCalled = false;
+    const badProgram = renderJsonTestProgram({
+      ...baseProgram,
+      commands: [
+        {
+          ...renderJsonCommand,
+          handler: () => {
+            handlerCalled = true;
+          },
+        },
+      ],
+    });
+    const result = await new Cli(badProgram).invoke(["render-json"], {
+      invocation: "http",
+      toolArgs: { message: 123 },
+    });
+    expect(result.kind).toBe("error");
+    expect(handlerCalled).toBe(false);
+  });
+});

package/examples/mcp-plugin/src/commands/render-json/command.ts

@@ -0,0 +1,30 @@
+/*
+Render-json leaf — JSON body demo with schemagen inputSchema and ctx.inputsAs.
+*/
+
+import type { CliLeaf, CliProgram } from "argsbarg";
+import { RenderJsonInputSchema } from "./__generated__";
+import type { RenderJsonInput } from "./types.ts";
+
+export const renderJsonCommand = {
+  key: "render-json",
+  description: "Echo a JSON message (schema-first JSON leaf demo).",
+  kind: "json",
+  inputSchema: RenderJsonInputSchema,
+  handler: (ctx) => {
+    const { message } = ctx.inputsAs<RenderJsonInput>();
+    if (ctx.invocation === "cli") {
+      console.log(message);
+      return;
+    }
+    return { message };
+  },
+} satisfies CliLeaf;
+
+/** Program stub for colocated tests. */
+export function renderJsonTestProgram(base: CliProgram): CliProgram {
+  return {
+    ...base,
+    commands: [renderJsonCommand],
+  };
+}

package/examples/mcp-plugin/src/commands/render-json/types.ts

@@ -0,0 +1,9 @@
+/*
+Input types for the render-json demo leaf.
+*/
+
+/** @sg */
+export interface RenderJsonInput {
+  /** Message to echo back. */
+  message: string;
+}

package/examples/mcp-plugin/src/commands/status/__generated__/StatusJsonOutputSchema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "App version from program root."
+    }
+  },
+  "required": [
+    "version"
+  ],
+  "additionalProperties": false,
+  "definitions": {}
+}

package/examples/mcp-plugin/src/commands/status/__generated__/index.ts

@@ -0,0 +1,5 @@
+// Auto-generated by argsbarg schemagen — do not edit by hand.
+
+import StatusJsonOutputSchemaJson from "./StatusJsonOutputSchema.json";
+
+export const StatusJsonOutputSchema = StatusJsonOutputSchemaJson as Record<string, unknown>;

package/examples/mcp-plugin/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/mcp-plugin/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/mcp-plugin/src/commands/status/types.ts

@@ -0,0 +1,6 @@
+/** JSON stdout for `full-example status --json`. */
+/** @sg */
+export interface StatusJsonOutput {
+  /** App version from program root. */
+  version: string;
+}

package/examples/mcp-plugin/src/commands/workspaces/__generated__/WorkspaceNameInputSchema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Workspace display name."
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "additionalProperties": false,
+  "definitions": {}
+}

package/examples/mcp-plugin/src/commands/workspaces/__generated__/index.ts

@@ -0,0 +1,5 @@
+// Auto-generated by argsbarg schemagen — do not edit by hand.
+
+import WorkspaceNameInputSchemaJson from "./WorkspaceNameInputSchema.json";
+
+export const WorkspaceNameInputSchema = WorkspaceNameInputSchemaJson as Record<string, unknown>;

package/examples/mcp-plugin/src/commands/workspaces/command.test.ts

@@ -0,0 +1,58 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { Cli, type CliProgram } from "argsbarg";
+import { AppDb } from "../../db";
+import { workspacesTestProgram } from "./command.ts";
+
+const baseProgram = {
+  key: "full-example",
+  version: "1.0.0",
+  description: "Demo.",
+  httpServer: { enabled: true },
+  commands: [],
+  hooks: {
+    beforeInvoke: AppDb.attach,
+  },
+} satisfies CliProgram;
+
+describe("workspaces command", () => {
+  const program = workspacesTestProgram(baseProgram);
+  const cli = new Cli(program);
+
+  beforeEach(() => {
+    AppDb.resetForTests();
+  });
+
+  test("GET workspaces lists empty collection", async () => {
+    const result = await cli.invoke(["workspaces", "get"], { invocation: "http" });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ workspaces: [] });
+  });
+
+  test("POST workspaces creates resource", async () => {
+    const created = await cli.invoke(["workspaces", "post"], {
+      invocation: "http",
+      toolArgs: { name: "qa2" },
+    });
+    expect(created.kind).toBe("ok");
+    const body = created.response?.body as { id: string; name: string };
+    expect(body.name).toBe("qa2");
+    expect(body.id.length).toBeGreaterThan(0);
+
+    const got = await cli.invoke(["workspaces", body.id, "get"], { invocation: "http" });
+    expect(got.kind).toBe("ok");
+    expect(got.response?.body).toEqual(body);
+  });
+
+  test("CLI workspaces :id get resolves path param", async () => {
+    const created = await cli.invoke(["workspaces", "post"], {
+      invocation: "http",
+      toolArgs: { name: "cli-ws" },
+    });
+    expect(created.kind).toBe("ok");
+    const id = (created.response?.body as { id: string }).id;
+
+    const got = await cli.invoke(["workspaces", id, "get"], { invocation: "http" });
+    expect(got.kind).toBe("ok");
+    expect(got.response?.body).toEqual({ id, name: "cli-ws" });
+  });
+});

package/examples/mcp-plugin/src/commands/workspaces/command.ts

@@ -0,0 +1,94 @@
+/*
+Workspaces CRUD — demonstrates REST verbs, :id param routers, and ctx.inputs path params.
+*/
+
+import { type CliProgram, type CliRouter, cliErrWithHelp } from "argsbarg";
+import { WorkspaceNameInputSchema } from "./__generated__";
+
+function notFound(ctx: Parameters<typeof cliErrWithHelp>[0], id: string): never {
+  cliErrWithHelp(ctx, `Workspace not found: ${id}`);
+}
+
+export const workspacesCommand = {
+  key: "workspaces",
+  description: "Workspace collection and CRUD.",
+  commands: [
+    {
+      key: "get",
+      description: "List workspaces.",
+      handler: (ctx) => ({ workspaces: ctx.locals.db.workspaces.list() }),
+    },
+    {
+      key: "post",
+      description: "Create a workspace.",
+      inputSchema: WorkspaceNameInputSchema,
+      handler: (ctx) => {
+        const { name } = ctx.inputsAs<{ name: string }>();
+        return ctx.locals.db.workspaces.create(name);
+      },
+    },
+    {
+      key: ":id",
+      description: "One workspace by id.",
+      commands: [
+        {
+          key: "get",
+          description: "Get one workspace.",
+          handler: (ctx) => {
+            const id = ctx.inputsAs<{ id: string }>().id;
+            const ws = ctx.locals.db.workspaces.get(id);
+            if (!ws) {
+              notFound(ctx, id);
+            }
+            return ws;
+          },
+        },
+        {
+          key: "put",
+          description: "Replace a workspace.",
+          inputSchema: WorkspaceNameInputSchema,
+          handler: (ctx) => {
+            const { id, name } = ctx.inputsAs<{ id: string; name: string }>();
+            const ws = ctx.locals.db.workspaces.replace(id, name);
+            if (!ws) {
+              notFound(ctx, id);
+            }
+            return ws;
+          },
+        },
+        {
+          key: "patch",
+          description: "Patch a workspace name.",
+          inputSchema: WorkspaceNameInputSchema,
+          handler: (ctx) => {
+            const { id, name } = ctx.inputsAs<{ id: string; name: string }>();
+            const ws = ctx.locals.db.workspaces.patch(id, name);
+            if (!ws) {
+              notFound(ctx, id);
+            }
+            return ws;
+          },
+        },
+        {
+          key: "delete",
+          description: "Delete a workspace.",
+          handler: (ctx) => {
+            const id = ctx.inputsAs<{ id: string }>().id;
+            if (!ctx.locals.db.workspaces.delete(id)) {
+              notFound(ctx, id);
+            }
+            ctx.respond({ status: 204, body: "" });
+          },
+        },
+      ],
+    },
+  ],
+} satisfies CliRouter;
+
+/** Test program with workspaces registered. */
+export function workspacesTestProgram(base: CliProgram): CliProgram {
+  return {
+    ...base,
+    commands: [workspacesCommand],
+  };
+}

package/examples/mcp-plugin/src/commands/workspaces/types.ts

@@ -0,0 +1,6 @@
+/** Body for workspace create/replace/patch. */
+/** @sg */
+export interface WorkspaceNameInput {
+  /** Workspace display name. */
+  name: string;
+}