argsbarg 7.0.10 → 7.1.0

package/examples/mcp-plugin/src/db/index.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import type { ReadinessContext } from "argsbarg";
+import { AppDb } from ".";
+
+describe("AppDb", () => {
+  let appDb: AppDb;
+
+  beforeEach(() => {
+    appDb = AppDb.open();
+  });
+
+  afterEach(() => {
+    appDb.close();
+  });
+
+  test("workspace CRUD round trip", () => {
+    const workspaces = appDb.workspaces;
+    expect(workspaces.list()).toEqual([]);
+    const created = workspaces.create("alpha");
+    expect(workspaces.get(created.id)).toEqual(created);
+    expect(workspaces.list()).toEqual([created]);
+    expect(workspaces.patch(created.id, "beta")).toEqual({ ...created, name: "beta" });
+    expect(workspaces.replace(created.id, "gamma")).toEqual({ id: created.id, name: "gamma" });
+    expect(workspaces.delete(created.id)).toBe(true);
+    expect(workspaces.get(created.id)).toBeUndefined();
+  });
+
+  test("ping succeeds on open database", () => {
+    expect(() => appDb.ping()).not.toThrow();
+  });
+});
+
+describe("AppDb.openWithRetry", () => {
+  test("opens an in-memory database", () => {
+    const appDb = AppDb.openWithRetry(1);
+    try {
+      appDb.workspaces.create("retry-ok");
+      expect(appDb.workspaces.list()).toHaveLength(1);
+    } finally {
+      appDb.close();
+    }
+  });
+});
+
+describe("AppDb.attach", () => {
+  test("sets ctx.locals.db", () => {
+    const locals = {} as import("argsbarg").CliLocals;
+    AppDb.attach({ locals, invocation: "cli" });
+    locals.db.workspaces.create("attached");
+    expect(locals.db.workspaces.list()).toHaveLength(1);
+  });
+});
+
+describe("AppDb.checkReadiness", () => {
+  test("returns false before server database is initialized", () => {
+    const runtime = {
+      state: {},
+      program: { key: "t", description: "d" },
+      surface: "http" as const,
+    };
+    const ctx = {
+      program: runtime.program,
+      surface: "http" as const,
+      appConfig: { read: () => ({}) },
+      runtime,
+    } as unknown as ReadinessContext;
+    expect(AppDb.checkReadiness(ctx)).toBe(false);
+  });
+
+  test("returns true when sqlite responds", () => {
+    AppDb.resetForTests();
+    const runtime = {
+      state: { db: AppDb.open() },
+      program: { key: "t", description: "d" },
+      surface: "http" as const,
+    };
+    const ctx = {
+      program: runtime.program,
+      surface: "http" as const,
+      appConfig: { read: () => ({}) },
+      runtime,
+    } as unknown as ReadinessContext;
+    expect(AppDb.checkReadiness(ctx)).toBe(true);
+    (runtime.state.db as AppDb).close();
+  });
+});

package/examples/mcp-plugin/src/db/index.ts

@@ -0,0 +1,77 @@
+/*
+App-wide in-memory database store.
+*/
+
+import type { InvokeHookContext, ReadinessContext } from "argsbarg";
+import { WorkspacesTable } from "./tables/workspaces.ts";
+
+/**
+ * Single in-memory store for this app.
+ */
+export class AppDb {
+  /** CLI singleton; server invocations use `runtime.state.db` instead. */
+  private static db: AppDb | undefined;
+
+  /** Workspace rows and queries for this connection. */
+  readonly workspaces: WorkspacesTable;
+
+  constructor() {
+    this.workspaces = new WorkspacesTable();
+  }
+
+  /** Open a fresh in-memory database. */
+  static open(): AppDb {
+    return new AppDb();
+  }
+
+  /** Open with bounded backoff (HTTP/MCP startup). */
+  static openWithRetry(_delayMs = 200): AppDb {
+    return AppDb.open();
+  }
+
+  /** Shared database for non-server invocations (lazy CLI singleton). */
+  static openDb(): AppDb {
+    AppDb.db ??= AppDb.open();
+    return AppDb.db;
+  }
+
+  /** Replace the CLI singleton with a fresh in-memory database (tests). */
+  static resetForTests(): void {
+    AppDb.db = AppDb.open();
+  }
+
+  /** Close connection resources. */
+  close(): void {}
+
+  /** Ping to verify readiness. */
+  ping(): void {}
+
+  /**
+   * Wire `ctx.locals.db` before handlers run.
+   * Server runtimes open with retry into `runtime.state.db`; CLI uses {@link openDb}.
+   */
+  static attach(
+    ctx: Pick<InvokeHookContext, "locals" | "invocation"> & { runtime?: InvokeHookContext["runtime"] },
+  ): void {
+    if (ctx.runtime && (ctx.invocation === "http" || ctx.invocation === "mcp")) {
+      ctx.runtime.state.db ??= AppDb.openWithRetry();
+      ctx.locals.db = ctx.runtime.state.db;
+      return;
+    }
+    ctx.locals.db = AppDb.openDb();
+  }
+
+  /** Readiness probe: ping `runtime.state.db` when the server database is open. */
+  static checkReadiness(ctx: ReadinessContext): boolean {
+    const appDb = ctx.runtime?.state?.db as AppDb | undefined;
+    if (!appDb) {
+      return false;
+    }
+    try {
+      appDb.ping();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/examples/mcp-plugin/src/db/tables/workspaces.ts

@@ -0,0 +1,58 @@
+/*
+Workspace rows and in-memory CRUD operations.
+*/
+
+/** One workspace row from the workspaces store. */
+export interface Workspace {
+  id: string;
+  name: string;
+}
+
+/** In-memory workspace rows and CRUD queries. */
+export class WorkspacesTable {
+  private readonly items = new Map<string, Workspace>();
+
+  /** All workspaces in insertion order. */
+  list(): Workspace[] {
+    return Array.from(this.items.values());
+  }
+
+  /** Lookup workspace by id, or undefined when missing. */
+  get(id: string): Workspace | undefined {
+    return this.items.get(id);
+  }
+
+  /** Create a workspace with a new id. */
+  create(name: string): Workspace {
+    const id = crypto.randomUUID();
+    const workspace: Workspace = { id, name };
+    this.items.set(id, workspace);
+    return workspace;
+  }
+
+  /** Replace workspace name when id exists; otherwise undefined. */
+  replace(id: string, name: string): Workspace | undefined {
+    if (!this.items.has(id)) {
+      return undefined;
+    }
+    const updated: Workspace = { id, name };
+    this.items.set(id, updated);
+    return updated;
+  }
+
+  /** Patch workspace name when id exists; otherwise undefined. */
+  patch(id: string, name: string): Workspace | undefined {
+    const existing = this.items.get(id);
+    if (!existing) {
+      return undefined;
+    }
+    const updated: Workspace = { ...existing, name };
+    this.items.set(id, updated);
+    return updated;
+  }
+
+  /** Delete workspace by id; true if deleted, false if not found. */
+  delete(id: string): boolean {
+    return this.items.delete(id);
+  }
+}

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

@@ -0,0 +1,32 @@
+/*
+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,
+  version: "1.0.0",
+} satisfies CliProgram;

package/examples/mcp-plugin/src/types/argsbarg.d.ts

@@ -0,0 +1,11 @@
+import type { AppDb } from "../db/index.ts";
+
+declare module "argsbarg" {
+  interface CliLocals {
+    db: AppDb;
+  }
+
+  interface ServerState {
+    db?: AppDb;
+  }
+}

package/examples/mcp-plugin/src/types/md.d.ts

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

package/examples/mcp-plugin/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/index.d.ts

@@ -319,10 +319,20 @@ export interface CliMcpBundleConfig {
 		email?: string;
 		url?: string;
 	};
+	/** Human-readable display name for plugin manifests. */
+	displayName?: string;
+	/** Homepage URL for plugin manifests. */
+	homepage?: string;
 	/** Repo-relative path to a PNG icon copied into the bundle. */
 	icon?: string;
+	/** Software license identifier (e.g. "MIT", "Apache-2.0"). */
+	license?: string;
 	/** Manifest `long_description` (defaults to program description). */
 	longDescription?: string;
+	/** Repository URL for plugin manifests. */
+	repository?: string;
+	/** Custom relative path to repository skills directory (defaults to `skills/<dirName>`). */
+	skillsDir?: string;
 }
 /**
  * Enables `myapp mcp` and MCP stdio server metadata (program root only).
@@ -340,6 +350,8 @@ export interface CliMcpServerConfig {
 	mcpd?: boolean;
 	/** When `true`, `mcp bundle` also writes `dist/claude-plugin/<name>.zip`. Default false. */
 	claudePlugin?: boolean;
+	/** When `true`, `mcp bundle` also writes `dist/cursor-plugin/<name>.zip`. Default false. */
+	cursorPlugin?: boolean;
 	/** Resource URI for schema export (default: `<sanitized root key>://schema`). */
 	schemaResourceUri?: string;
 	/**

package/package.json

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

package/src/builtins/mcp.ts

@@ -51,7 +51,7 @@ export function cliBuiltinMcpCommand(program: CliProgram): CliRouter {
 
   const bundle: CliLeaf = {
     key: "bundle",
-    description: "Pack dist MCP artifacts (`.mcpb`, Claude Code plugin zip) from dist/<key>.",
+    description: "Pack dist MCP artifacts (`.mcpb`, Claude Code plugin zip, Cursor plugin zip) from dist/<key>.",
     handler: () => {},
   };
 

package/src/cli-tool/create.test.ts

@@ -83,10 +83,15 @@ describe("argsbarg create", () => {
     const tree = renderCreateTree(baseOpts({ key: "testapp" }));
     expect(tree.has("justfile")).toBe(true);
     expect(tree.has("scripts/create-identity.ts")).toBe(true);
+    expect(tree.has("scripts/print-identity.ts")).toBe(false);
     expect(tree.has("skills/testapp/SKILL.md")).toBe(true);
     const identity = tree.get("scripts/create-identity.ts");
     expect(identity).toContain('key: "testapp"');
     expect(identity).toContain('template: "cli"');
+    const justfile = tree.get("justfile") ?? "";
+    expect(justfile).not.toContain("print-identity");
+    expect(justfile).toContain("testapp");
+    expect(justfile).toContain("local/testapp/testapp");
     expect(tree.has("src/commands/render-json/command.ts")).toBe(false);
   });
 

package/src/cli-tool/create.ts

@@ -5,7 +5,7 @@ import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import pkg from "../../package.json" with { type: "json" };
 
-export type CreateTemplateId = "cli" | "json";
+export type CreateTemplateId = "cli" | "json" | "plugin";
 
 export interface CreateTemplateSpec {
   id: CreateTemplateId;
@@ -27,9 +27,16 @@ export const CREATE_TEMPLATES: CreateTemplateSpec[] = [
     displayName: "full-example-json",
     description: "Same shell plus @sg schemagen, input/outputSchema validation, JSON HTTP leaves, and REST CRUD demo.",
   },
+  {
+    id: "plugin",
+    dirName: "mcp-plugin",
+    displayName: "mcp-plugin",
+    description: "Agent MCP plugin copy template for Cursor and Claude Code marketplaces.",
+  },
 ];
 
 export function normalizeCreateTemplateId(value: string | undefined): CreateTemplateId {
+  if (value === "plugin" || value === "mcp-plugin") return "plugin";
   return value === "json" ? "json" : "cli";
 }
 
@@ -282,6 +289,7 @@ export function substituteTemplateContent(content: string, opts: CreateOptions):
     [tmpl.desc, opts.desc],
     [tmpl.className, opts.className],
     [tmpl.key, opts.key],
+    [`## ${tmpl.key} conventions`, `## ${opts.key} conventions`],
     [`**${tmpl.key} conventions:**`, `**${opts.key} conventions:**`],
     ["**App-specific conventions:**", `**${opts.key} conventions:**`],
   ];

package/src/config/manifest.ts

@@ -60,3 +60,59 @@ export function buildPluginMcpEnvMapping(program: CliProgram): Record<string, st
   }
   return Object.keys(out).length > 0 ? out : undefined;
 }
+
+/**
+ * Plugin mcp.json env mapping for Cursor from program.appConfig env entries.
+ */
+export function buildCursorPluginMcpEnvMapping(
+  /** CLI program schema. */
+  program: CliProgram,
+): Record<string, string> | undefined {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return undefined;
+  }
+  const out: Record<string, string> = {};
+  for (const entry of Object.values(appConfig.entries)) {
+    if (!entry.env) {
+      continue;
+    }
+    out[entry.env] = `\${${entry.env}}`;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Builds Cursor plugin variables schema from program.appConfig env-mapped entries.
+ */
+export function buildCursorPluginVariables(
+  /** CLI program schema. */
+  program: CliProgram,
+): Record<string, unknown> | undefined {
+  const appConfig = program.appConfig;
+  if (!appConfig) {
+    return undefined;
+  }
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const entry of Object.values(appConfig.entries)) {
+    if (!entry.env) {
+      continue;
+    }
+    properties[entry.env] = {
+      type: "string",
+      ...(entry.description ? { description: entry.description } : {}),
+    };
+    if (entry.required) {
+      required.push(entry.env);
+    }
+  }
+  if (Object.keys(properties).length === 0) {
+    return undefined;
+  }
+  return {
+    type: "object",
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+  };
+}

package/src/config/resolve.test.ts

@@ -120,9 +120,9 @@ describe("config/resolve", () => {
     const resolveProgram: CliProgram = {
       ...program,
       appConfig: {
-        ...program.appConfig!,
+        ...program.appConfig,
         entries: {
-          ...program.appConfig!.entries,
+          ...program.appConfig?.entries,
           apiToken: {
             description: "Token.",
             env: "API_TOKEN",
@@ -146,9 +146,9 @@ describe("config/resolve", () => {
     const resolveProgram: CliProgram = {
       ...program,
       appConfig: {
-        ...program.appConfig!,
+        ...program.appConfig,
         entries: {
-          ...program.appConfig!.entries,
+          ...program.appConfig?.entries,
           apiToken: {
             description: "Token.",
             env: "API_TOKEN",
@@ -173,9 +173,9 @@ describe("config/resolve", () => {
     const resolveProgram: CliProgram = {
       ...program,
       appConfig: {
-        ...program.appConfig!,
+        ...program.appConfig,
         entries: {
-          ...program.appConfig!.entries,
+          ...program.appConfig?.entries,
           apiToken: {
             description: "Token.",
             env: "API_TOKEN",
@@ -199,9 +199,9 @@ describe("config/resolve", () => {
     const resolveProgram: CliProgram = {
       ...program,
       appConfig: {
-        ...program.appConfig!,
+        ...program.appConfig,
         entries: {
-          ...program.appConfig!.entries,
+          ...program.appConfig?.entries,
           apiToken: {
             description: "Token.",
             env: "API_TOKEN",
@@ -227,9 +227,9 @@ describe("config/resolve", () => {
     const resolveProgram: CliProgram = {
       ...program,
       appConfig: {
-        ...program.appConfig!,
+        ...program.appConfig,
         entries: {
-          ...program.appConfig!.entries,
+          ...program.appConfig?.entries,
           apiToken: {
             description: "Token.",
             env: "API_TOKEN",
@@ -258,9 +258,9 @@ describe("config/resolve", () => {
     const resolveProgram: CliProgram = {
       ...program,
       appConfig: {
-        ...program.appConfig!,
+        ...program.appConfig,
         entries: {
-          ...program.appConfig!.entries,
+          ...program.appConfig?.entries,
           apiToken: {
             description: "Token.",
             env: "API_TOKEN",

package/src/configure/configure.test.ts

@@ -156,14 +156,16 @@ describe("uninstall plan", () => {
     const detected = buildDetectedSnapshot(fixture, paths);
     const ctx = buildTargetPlanContext(fixture, paths, {}, detected);
     const target = installTargetForKey("skill");
-    expect(target).toBeDefined();
-    const actions = target!.planUninstall({
+    if (!target) throw new Error("expected skill install target");
+    const actions = target.planUninstall({
       ...ctx,
       mode: "uninstall-scoped",
       include: (key) => key === "skill",
     });
     expect(actions).toHaveLength(1);
-    expect(actions[0]!.run().length).toBeGreaterThan(0);
+    const action = actions[0];
+    if (!action) throw new Error("expected uninstall action");
+    expect(action.run().length).toBeGreaterThan(0);
     expect(existsSync(paths.agentsSkillDir)).toBe(false);
   });
 });

package/src/core/parse.test.ts

@@ -15,6 +15,7 @@ import {
   enumMcpFixture,
   nestedDocsFallbackFixture,
   nestedMcpFixture,
+  requireMcpTool,
   testProgram,
   varargsReadFixture,
 } from "../test/fixtures.ts";
@@ -920,7 +921,7 @@ test("cliSchemaExport resolves {argsbarg:program} in consumer notes", () => {
 
 test("Enum option inputSchema includes enum array", () => {
   const tools = collectMcpTools(enumMcpFixture);
-  const run = tools.find((t) => t.name === "run")!;
+  const run = requireMcpTool(tools, "run");
   const schema = run.inputSchema as { properties: { mode: { enum?: string[] } } };
   expect(schema.properties.mode.enum).toEqual(["dev", "prod"]);
 });
@@ -1291,28 +1292,28 @@ test("varargs unknown flag errors", async () => {
 
 test("mcpToolCallToArgv rejects comma-separated string for varargs", () => {
   const tools = collectMcpTools(nestedMcpFixture);
-  const read = tools.find((t) => t.name === "read")!;
+  const read = requireMcpTool(tools, "read");
   const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: "a,b" });
   expect(argv).toEqual({ error: expect.stringContaining("JSON array") });
 });
 
 test("mcpToolCallToArgv rejects bare string for varargs", () => {
   const tools = collectMcpTools(nestedMcpFixture);
-  const read = tools.find((t) => t.name === "read")!;
+  const read = requireMcpTool(tools, "read");
   const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: "a" });
   expect(argv).toEqual({ error: expect.stringContaining("JSON array") });
 });
 
 test("mcpToolCallToArgv array varargs unchanged", () => {
   const tools = collectMcpTools(nestedMcpFixture);
-  const read = tools.find((t) => t.name === "read")!;
+  const read = requireMcpTool(tools, "read");
   const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: ["a", "b"] });
   expect(argv).toEqual(["read", "a", "b"]);
 });
 
 test("mcpToolCallToArgv empty array varargs errors when required", () => {
   const tools = collectMcpTools(nestedMcpFixture);
-  const read = tools.find((t) => t.name === "read")!;
+  const read = requireMcpTool(tools, "read");
   const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: [] });
   expect(argv).toEqual({ error: "Missing argument: files" });
 });

package/src/core/types.ts

@@ -163,10 +163,20 @@ export interface CliMcpBundleConfig {
     email?: string;
     url?: string;
   };
+  /** Human-readable display name for plugin manifests. */
+  displayName?: string;
+  /** Homepage URL for plugin manifests. */
+  homepage?: string;
   /** Repo-relative path to a PNG icon copied into the bundle. */
   icon?: string;
+  /** Software license identifier (e.g. "MIT", "Apache-2.0"). */
+  license?: string;
   /** Manifest `long_description` (defaults to program description). */
   longDescription?: string;
+  /** Repository URL for plugin manifests. */
+  repository?: string;
+  /** Custom relative path to repository skills directory (defaults to `skills/<dirName>`). */
+  skillsDir?: string;
 }
 
 /**
@@ -185,6 +195,8 @@ export interface CliMcpServerConfig {
   mcpd?: boolean;
   /** When `true`, `mcp bundle` also writes `dist/claude-plugin/<name>.zip`. Default false. */
   claudePlugin?: boolean;
+  /** When `true`, `mcp bundle` also writes `dist/cursor-plugin/<name>.zip`. Default false. */
+  cursorPlugin?: boolean;
   /** Resource URI for schema export (default: `<sanitized root key>://schema`). */
   schemaResourceUri?: string;
   /**

package/src/exports/mcp.ts

@@ -4,3 +4,15 @@ MCP bundle export (`argsbarg/mcp`). @experimental
 
 export type { McpBundlePaths, PackMcpBundleOpts } from "../mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "../mcp/bundle.ts";
+export {
+  defaultClaudePluginPaths,
+  generatePluginManifest,
+  generatePluginMcpJson,
+  packClaudePlugin,
+} from "../mcp/claude.ts";
+export {
+  defaultCursorPluginPaths,
+  generateCursorPluginManifest,
+  generateCursorPluginMcpJson,
+  packCursorPlugin,
+} from "../mcp/cursor.ts";