argsbarg 6.1.2 → 6.1.3

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

@@ -0,0 +1,69 @@
+/*
+Ordered SQL migrations for the full-example SQLite database.
+*/
+
+import type { Database } from "bun:sqlite";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const MIGRATIONS_DIR = join(import.meta.dir, "migrations");
+
+const SCHEMA_MIGRATIONS_DDL = `CREATE TABLE IF NOT EXISTS schema_migrations (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+)`;
+
+interface MigrationFile {
+  version: number;
+  name: string;
+  path: string;
+}
+
+/** Sorted migration files under src/db/migrations (e.g. 001_workspaces.sql). */
+export function listMigrationFiles(dir = MIGRATIONS_DIR): MigrationFile[] {
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".sql"))
+    .map((name) => {
+      const match = /^(\d+)_(.+)\.sql$/.exec(name);
+      if (!match) {
+        throw new Error(`Invalid migration filename (expected NNN_name.sql): ${name}`);
+      }
+      return {
+        version: Number(match[1]),
+        name,
+        path: join(dir, name),
+      };
+    })
+    .sort((a, b) => a.version - b.version);
+}
+
+/** Highest applied migration version, or 0 when schema_migrations is empty. */
+export function appliedMigrationVersion(db: Database): number {
+  db.run(SCHEMA_MIGRATIONS_DDL);
+  const row = db.query("SELECT COALESCE(MAX(version), 0) AS version FROM schema_migrations").get() as {
+    version: number;
+  };
+  return row.version;
+}
+
+/** Apply pending migrations; returns how many files were applied. */
+export function migrate(db: Database, dir = MIGRATIONS_DIR): number {
+  db.run(SCHEMA_MIGRATIONS_DDL);
+  let applied = 0;
+  for (const migration of listMigrationFiles(dir)) {
+    const seen = db.query("SELECT 1 AS ok FROM schema_migrations WHERE version = ?").get(migration.version) as {
+      ok: number;
+    } | null;
+    if (seen) {
+      continue;
+    }
+    const sql = readFileSync(migration.path, "utf8");
+    db.transaction(() => {
+      db.run(sql);
+      db.run("INSERT INTO schema_migrations (version, name) VALUES (?, ?)", [migration.version, migration.name]);
+    })();
+    applied++;
+  }
+  return applied;
+}

package/examples/full-example/src/db/migrations/001_workspaces.sql

@@ -0,0 +1,6 @@
+-- Workspaces table for the full-example CRUD demo.
+CREATE TABLE IF NOT EXISTS workspaces (
+  id TEXT PRIMARY KEY NOT NULL,
+  name TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);

package/examples/full-example/src/db/tables/workspaces.ts

@@ -0,0 +1,66 @@
+import type { Database } from "bun:sqlite";
+
+/** One workspace row from the `workspaces` table. */
+export interface Workspace {
+  id: string;
+  name: string;
+}
+
+/** Workspace rows and CRUD queries. */
+export class WorkspacesTable {
+  private readonly listStmt;
+  private readonly getStmt;
+  private readonly insertStmt;
+  private readonly updateStmt;
+  private readonly deleteStmt;
+
+  constructor(readonly sqlite: Database) {
+    this.listStmt = sqlite.query("SELECT id, name FROM workspaces ORDER BY rowid");
+    this.getStmt = sqlite.query("SELECT id, name FROM workspaces WHERE id = ?");
+    this.insertStmt = sqlite.query("INSERT INTO workspaces (id, name) VALUES (?, ?)");
+    this.updateStmt = sqlite.query("UPDATE workspaces SET name = ? WHERE id = ?");
+    this.deleteStmt = sqlite.query("DELETE FROM workspaces WHERE id = ?");
+  }
+
+  /** All workspaces in insertion order. */
+  list(): Workspace[] {
+    return this.listStmt.all() as Workspace[];
+  }
+
+  /** Lookup workspace by id, or undefined when missing. */
+  get(id: string): Workspace | undefined {
+    const row = this.getStmt.get(id) as Workspace | null;
+    return row ?? undefined;
+  }
+
+  /** Create a workspace with a new id. */
+  create(name: string): Workspace {
+    const id = crypto.randomUUID();
+    this.insertStmt.run(id, name);
+    return { id, name };
+  }
+
+  /** Replace workspace name when id exists; otherwise undefined. */
+  replace(id: string, name: string): Workspace | undefined {
+    const result = this.updateStmt.run(name, id);
+    if (result.changes === 0) {
+      return undefined;
+    }
+    return { id, name };
+  }
+
+  /** Patch workspace name when id exists; otherwise undefined. */
+  patch(id: string, name: string): Workspace | undefined {
+    const existing = this.get(id);
+    if (!existing) {
+      return undefined;
+    }
+    this.updateStmt.run(name, id);
+    return { ...existing, name };
+  }
+
+  /** Remove workspace by id; true when a row was deleted. */
+  delete(id: string): boolean {
+    return this.deleteStmt.run(id).changes > 0;
+  }
+}

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

@@ -1,57 +1,32 @@
 /*
-Kitchen-sink CliProgram — every argsbarg builtin enabled; command registration only.
+Reference CliProgram — builtins on; command registration only.
 */
 
-import type { CliAppConfig, CliAppConfigEntry, CliProgram } from "argsbarg";
+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 { configSchema } from "./config/__generated__/index.ts";
-
-const configEntries = {
-  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>;
+import { workspacesCommand } from "./commands/workspaces/command.ts";
+import { AppDb } from "./db";
 
 export const program = {
   key: createIdentity.key,
   version: "1.0.0",
   description: createIdentity.desc,
-  appConfig: {
-    jsonSchema: configSchema,
-    entries: configEntries,
-  } satisfies CliAppConfig,
   docs: {
-    enabled: true,
     topics: {
       readme: {
         text: readmeText,
       },
     },
   },
-  mcpServer: {
-    enabled: true,
-    mcpd: true,
-    claudePlugin: true,
-  },
-  apiServer: {
-    enabled: true,
+  mcpServer: { enabled: true },
+  httpServer: { enabled: true },
+  readiness: AppDb.checkReadiness,
+  hooks: {
+    beforeInvoke: AppDb.attach,
   },
-  commands: [echoCommand, statusCommand],
+  commands: [echoCommand, renderJsonCommand, statusCommand, workspacesCommand],
 } satisfies CliProgram;

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

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

package/examples/full-example/tsconfig.json

@@ -8,7 +8,10 @@
     "noEmit": true,
     "strict": true,
     "skipLibCheck": true,
-    "types": ["bun"]
+    "types": ["bun"],
+    "paths": {
+      "~/*": ["./src/*"]
+    }
   },
-  "include": ["src/**/*.ts", "scripts/**/*.ts"]
+  "include": ["src/**/*.ts", "src/**/*.d.ts", "scripts/**/*.ts"]
 }

package/examples/mcp-test.ts

@@ -3,7 +3,7 @@
 MCP test fixture for subprocess integration tests only.
 */
 
-import { Cli, CliOptionKind, type CliProgram } from "../src/index.ts";
+import { Cli, CliOptionKind, type CliProgram } from "../src/index";
 
 const program = {
   key: "mcp-test",
@@ -30,7 +30,6 @@ const program = {
     ],
   },
   docs: {
-    enabled: true,
     topics: {
       readme: { text: "# MCP test readme\n" },
     },

package/examples/minimal.ts

@@ -8,18 +8,12 @@ It demonstrates the minimal Bun integration path.
 */
 
 import pkg from "../package.json" with { type: "json" };
-import { Cli, CliOptionKind, type CliProgram } from "../src/index.ts";
+import { Cli, CliOptionKind, type CliProgram } from "../src/index";
 
 const program = {
   key: "minimal.ts",
   version: pkg.version,
   description: "Tiny demo.",
-  docs: {
-    enabled: true,
-    topics: {
-      readme: { text: "# minimal.ts\n\nTiny demo.\n" },
-    },
-  },
   positionals: [
     {
       name: "name",

package/examples/nested.ts

@@ -8,7 +8,7 @@ It demonstrates how the schema scales beyond one command.
 */
 
 import pkg from "../package.json" with { type: "json" };
-import { Cli, CliFallbackMode, CliOptionKind, type CliProgram } from "../src/index.ts";
+import { Cli, CliFallbackMode, CliOptionKind, type CliProgram } from "../src/index";
 
 const program = {
   key: "nested.ts",
@@ -16,7 +16,6 @@ const program = {
   description: "Nested groups demo.",
   mcpServer: { enabled: true },
   docs: {
-    enabled: true,
     topics: {
       readme: { text: "# nested.ts\n\nNested groups demo.\n" },
     },

package/examples/option-required.ts

@@ -8,7 +8,7 @@ It demonstrates the minimal Bun integration path.
 */
 
 import pkg from "../package.json" with { type: "json" };
-import { Cli, CliOptionKind, type CliProgram, isInteractiveTty } from "../src/index.ts";
+import { Cli, CliOptionKind, type CliProgram, isInteractiveTty } from "../src/index";
 
 const program = {
   key: "option-required.ts",

package/examples/servers.ts

@@ -4,10 +4,10 @@ This example shows the smallest end-to-end CLI+MCP+API setup.
 It includes one command, a couple of options, and a direct call to the runtime so
 readers can copy the pattern into their own scripts quickly.
 
-Demonstrates: `servers.ts hello`, MCP tool `hello`, and `POST /tools/hello`.
+Demonstrates: `servers.ts hello`, MCP tool `hello`, and `POST /api/hello`.
 
 Ex API Call:
-curl -s -X POST http://127.0.0.1:3000/tools/hello \
+curl -s -X POST http://127.0.0.1:3000/api/hello \
   -H 'content-type: application/json' \
   -d '{"name":"alice"}'
 Ex API Response:
@@ -17,16 +17,15 @@ Ex API Response:
 */
 
 import pkg from "../package.json" with { type: "json" };
-import { Cli, CliOptionKind, type CliProgram } from "../src/index.ts";
+import { Cli, CliOptionKind, type CliProgram } from "../src/index";
 
 const program = {
   key: "servers.ts",
   version: pkg.version,
   description: "Tiny demo.",
   mcpServer: { enabled: true },
-  apiServer: { enabled: true },
+  httpServer: { enabled: true },
   docs: {
-    enabled: true,
     topics: {
       readme: { text: "# servers.ts\n\nServers demo.\n" },
     },