argsbarg 6.1.2 → 6.1.3

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

@@ -1,6 +1,6 @@
 ---
 name: full_example
-description: Operates the full-example CLI (echo, status). Use when the user mentions full-example, echo, status, or related tasks.
+description: Operates the full-example CLI (echo, render-json, status, workspaces get, workspaces post, and 4 more). Use when the user mentions full-example, echo, render-json, status, or related tasks.
 ---
 <!-- Generated by full-example docs skill --save; do not edit. -->
 
@@ -20,14 +20,14 @@ full-example <subcommand> [options] [args]
 ## Commands
 
 - **`full-example echo`** — Echo a message (MCP-friendly leaf).
-- **`full-example status`** — Show resolved config and app version. (flags: --json)
-
-## Configuration
-
-- **apiToken** (`apiToken` (env: `FULL_EXAMPLE_API_TOKEN`)) — Create at https://example.com/settings/tokens
-- **defaultRegion** (`defaultRegion`) — AWS region for API calls.
-- **maxRetries** (`maxRetries`) — HTTP retry count (0–10).
-- **prefs** (`prefs`) — Local cache preferences (not exported to env).
+- **`full-example render-json`** — Echo a JSON message (schema-first JSON leaf demo).
+- **`full-example status`** — Show app version. (flags: --json)
+- **`full-example workspaces get`** — List workspaces.
+- **`full-example workspaces post`** — Create a workspace.
+- **`full-example workspaces :id get`** — Get one workspace.
+- **`full-example workspaces :id put`** — Replace a workspace.
+- **`full-example workspaces :id patch`** — Patch a workspace name.
+- **`full-example workspaces :id delete`** — Delete a workspace.
 
 ## Pitfalls
 
@@ -35,7 +35,7 @@ full-example <subcommand> [options] [args]
 
 ## Reference
 
-For full detail, open `reference.md` in this skill directory (same as `full-example docs api`).
+For full detail, open `reference.md` in this skill directory (same as `full-example docs cli`).
 
 ## Cursor install location
 

package/examples/full-example/justfile

@@ -21,6 +21,16 @@ 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
 
@@ -31,7 +41,7 @@ dev *ARGS:
 # Regenerate consumer docs under ./docs/
 docgen: schemagen
     @just run docs cli-schema --save
-    @just run docs api --save
+    @just run docs cli --save
     @just run docs skill --save
     @just run docs mcp --save
     @just run docs http --save

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

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

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

@@ -1,14 +1,14 @@
 /*
-Status leaf — demonstrates outputSchema and ctx.appConfig.
+Status leaf — demonstrates outputSchema.
 */
 
 import { type CliLeaf, CliOptionKind } from "argsbarg";
-import { outputSchema } from "./__generated__/index.ts";
+import { StatusJsonOutputSchema } from "./__generated__";
 import type { StatusJsonOutput } from "./types.ts";
 
 export const statusCommand = {
   key: "status",
-  description: "Show resolved config and app version.",
+  description: "Show app version.",
   options: [
     {
       name: "json",
@@ -16,21 +16,13 @@ export const statusCommand = {
       kind: CliOptionKind.Presence,
     },
   ],
-  outputSchema,
+  outputSchema: StatusJsonOutputSchema,
   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,
-    };
+    const out: StatusJsonOutput = { 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/full-example/src/commands/status/types.ts

@@ -1,19 +1,6 @@
 /** JSON stdout for `full-example status --json`. */
+/** @sg */
 export interface StatusJsonOutput {
-  /** Resolved AWS region. */
-  defaultRegion?: string;
-  /** Resolved retry count. */
-  maxRetries?: number;
-  /** Whether apiToken is set (value never included). */
-  apiTokenSet: boolean;
   /** App version from program root. */
   version: string;
 }
-
-/** Returns status JSON (identity helper for schema generation). */
-export function buildStatusJson(output: StatusJsonOutput): StatusJsonOutput {
-  return output;
-}
-
-/** Schemagen root for leaf outputSchema. */
-export type outputType = StatusJsonOutput;

package/examples/full-example/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/full-example/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/full-example/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/full-example/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/full-example/src/commands/workspaces/types.ts

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

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

@@ -0,0 +1,101 @@
+/*
+App-wide in-memory SQLite database.
+*/
+
+import { Database } from "bun:sqlite";
+import type { InvokeHookContext, ReadinessContext } from "argsbarg";
+import { migrate } from "./migrate.ts";
+import { WorkspacesTable } from "./tables/workspaces.ts";
+
+const DEFAULT_RETRY_DELAY_MS = 200;
+const MAX_RETRY_DELAY_MS = 5000;
+
+/**
+ * Single SQLite database for this app.
+ * Migrations run on construction; table accessors hang off {@link workspaces}.
+ */
+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(readonly sqlite: Database) {
+    migrate(sqlite);
+    this.workspaces = new WorkspacesTable(sqlite);
+  }
+
+  /** Open a fresh in-memory database with foreign keys enabled. */
+  static open(): AppDb {
+    const sqlite = new Database(":memory:", { create: true });
+    sqlite.run("PRAGMA foreign_keys = ON");
+    return new AppDb(sqlite);
+  }
+
+  /** Open with bounded backoff, retrying until SQLite accepts connections (HTTP/MCP startup). */
+  static openWithRetry(delayMs = DEFAULT_RETRY_DELAY_MS): AppDb {
+    let attempt = 0;
+    while (true) {
+      try {
+        const appDb = AppDb.open();
+        appDb.ping();
+        return appDb;
+      } catch {
+        attempt++;
+        Bun.sleepSync(Math.min(delayMs * attempt, MAX_RETRY_DELAY_MS));
+      }
+    }
+  }
+
+  /** 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?.close();
+    AppDb.db = AppDb.open();
+  }
+
+  /**
+   * 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;
+    if (!appDb) {
+      return false;
+    }
+    try {
+      appDb.ping();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Verify SQLite responds to a trivial query. */
+  ping(): void {
+    this.sqlite.query("SELECT 1 AS ok").get();
+  }
+
+  /** Close the underlying database handle. */
+  close(): void {
+    this.sqlite.close();
+  }
+}

package/examples/full-example/src/db/migrate.test.ts

@@ -0,0 +1,35 @@
+import { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { appliedMigrationVersion, listMigrationFiles, migrate } from "./migrate.ts";
+
+function openTestDb(): Database {
+  const db = new Database(":memory:", { create: true });
+  db.run("PRAGMA foreign_keys = ON");
+  return db;
+}
+
+describe("migrate", () => {
+  let db: Database;
+
+  beforeEach(() => {
+    db = openTestDb();
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  test("lists migration files in version order", () => {
+    const files = listMigrationFiles();
+    expect(files.length).toBeGreaterThan(0);
+    expect(files[0]?.name).toBe("001_workspaces.sql");
+  });
+
+  test("applies pending migrations once", () => {
+    expect(appliedMigrationVersion(db)).toBe(0);
+    expect(migrate(db)).toBe(1);
+    expect(appliedMigrationVersion(db)).toBe(1);
+    expect(migrate(db)).toBe(0);
+    expect(db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'workspaces'").get()).toBeTruthy();
+  });
+});