argsbarg 4.1.0 → 5.0.1

package/examples/config-app/schema.ts

@@ -1,37 +0,0 @@
-/*
-Inline draft-07 JSON Schema for AppConfig.
-Production apps commit generated JSON and import via configSchemas.ts — see docs/config-schema.md.
-*/
-
-import type { AppConfig } from "./types.ts";
-
-/** JSON Schema root for program.appConfig.jsonSchema (hand-written stand-in for schemagen). */
-export const APP_CONFIG_JSON_SCHEMA = {
-  $schema: "http://json-schema.org/draft-07/schema#",
-  type: "object",
-  additionalProperties: false,
-  required: ["apiToken", "maxRetries"],
-  properties: {
-    apiToken: { type: "string", minLength: 1 },
-    defaultRegion: { type: "string", default: "us-east-1" },
-    maxRetries: { type: "integer", minimum: 0, maximum: 10, default: 3 },
-    prefs: {
-      type: "object",
-      additionalProperties: false,
-      required: ["ttl"],
-      properties: {
-        ttl: { type: "integer", minimum: 1 },
-      },
-    },
-  },
-} as const satisfies Record<string, unknown>;
-
-/** Compile-time check that schema keys align with AppConfig (documentation only). */
-type _SchemaKeys = keyof typeof APP_CONFIG_JSON_SCHEMA.properties;
-type _ConfigKeys = keyof AppConfig;
-const _assertKeysAlign: _SchemaKeys extends _ConfigKeys
-  ? _ConfigKeys extends _SchemaKeys
-    ? true
-    : never
-  : never = true;
-void _assertKeysAlign;

package/examples/config-app/types.ts

@@ -1,19 +0,0 @@
-/**
- * Config schema
- *
- * Application settings persisted in a flat JSON file (`program.appConfig`).
- * In a production app, generate `APP_CONFIG_JSON_SCHEMA` from this interface
- * with ts-json-schema-generator — see docs/config-schema.md.
- */
-export interface AppConfig {
-  /** API token from the provider dashboard. */
-  apiToken: string;
-  /** AWS region (default us-east-1). */
-  defaultRegion?: string;
-  /** HTTP retry count (default 3). */
-  maxRetries: number;
-  /** Local preferences (file-only; not mapped to process.env). */
-  prefs?: {
-    ttl: number;
-  };
-}

package/examples/consumer-app/README.md

@@ -1,56 +0,0 @@
-# consumer-app
-
-**Kitchen-sink argsbarg reference** — copy this layout when bootstrapping a production CLI. For a minimal `program.appConfig` intro, see [`../config-app/`](../config-app/).
-
-## What this demonstrates
-
-| Area | Files / wiring |
-| --- | --- |
-| All builtins | `completion`, `version`, `install` (+ `--update`), `docs`, `mcp`, `config get`/`set` |
-| `program.appConfig` | `src/types.ts` (`AppConfig`) → `schemas/configSchemas.ts` |
-| `outputSchema` | `src/commands/status/types.ts` (`StatusJsonOutput`) → `schemas/outputSchemas.ts` |
-| Schemagen | `scripts/schemagen.ts` + `scripts/schemagen/discover-schema-roots.ts` |
-| Handler access | `ctx.appConfig` in `src/program.ts` |
-| MCP doc topics | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled |
-| Package import | `from "argsbarg"` (not relative to argsbarg `src/`) |
-
-## Quick start (in this repo)
-
-```bash
-cd examples/consumer-app
-bun install
-bun run schemagen   # after changing src/**/types.ts
-CONSUMER_APP_API_TOKEN=dev bun run start status --json
-CONSUMER_APP_API_TOKEN=dev bun run start config get apiToken --json
-CONSUMER_APP_API_TOKEN=dev bun run start docs readme
-```
-
-## Copy into a new app
-
-1. Copy this directory into your repo (e.g. `apps/my-cli/`).
-2. Set `"argsbarg": "^<version>"` in `package.json` (replace `file:../..`).
-3. Run `bun run schemagen` and commit `schemas/generated/` + bridge `.ts` files.
-4. Copy [`node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc`](../../docs/templates/cursor/rules/cli-program.mdc) to `.cursor/rules/`.
-
-## Schemagen markers
-
-| Marker in interface JSDoc | Artifact |
-| --- | --- |
-| `Config schema` | `schemas/configSchemas.ts` + `schemas/generated/*-config.json` |
-| `JSON payload` | `schemas/outputSchemas.ts` + `schemas/generated/*.json` |
-
-Discovery walks `src/**/types.ts` only.
-
-## Environment
-
-| Variable | Purpose |
-| --- | --- |
-| `CONSUMER_APP_API_TOKEN` | Overrides `apiToken` via `program.appConfig` env mapping |
-
-## Maintainers (argsbarg repo)
-
-When adding or changing builtins, update this example and run:
-
-```bash
-just consumer-app-schemagen
-```

package/examples/consumer-app/src/main.ts

@@ -1,15 +0,0 @@
-#!/usr/bin/env bun
-/*
-Kitchen-sink argsbarg consumer reference.
-
-  cd examples/consumer-app && bun install && bun run schemagen
-  CONSUMER_APP_API_TOKEN=dev bun run start status --json
-  CONSUMER_APP_API_TOKEN=dev bun run start config get
-  CONSUMER_APP_API_TOKEN=dev bun run start docs readme
-*/
-
-import { Cli } from "argsbarg";
-import { program } from "./program.ts";
-
-const cli = new Cli(program);
-await cli.run();

package/examples/consumer-app/src/program.ts

@@ -1,108 +0,0 @@
-/*
-Kitchen-sink CliProgram — every argsbarg builtin enabled.
-*/
-
-import {
-  type CliAppConfig,
-  type CliAppConfigEntry,
-  CliOptionKind,
-  type CliProgram,
-} from "argsbarg";
-import readmeText from "../README.md" with { type: "text" };
-import { APP_CONFIG_JSON_SCHEMA } from "../schemas/configSchemas.ts";
-import { STATUS_JSON_OUTPUT_SCHEMA } from "../schemas/outputSchemas.ts";
-import type { StatusJsonOutput } from "./commands/status/types.ts";
-
-const configSchema = {
-  apiToken: {
-    description: "Create at https://example.com/settings/tokens",
-    env: "CONSUMER_APP_API_TOKEN",
-    sensitive: true,
-  },
-  defaultRegion: {
-    description: "AWS region for API calls.",
-    required: false,
-  },
-  maxRetries: {
-    description: "HTTP retry count (0–10).",
-  },
-  prefs: {
-    description: "Local cache preferences (not exported to env).",
-    required: false,
-  },
-} as const satisfies Record<string, CliAppConfigEntry>;
-
-export const program = {
-  key: "consumer-app",
-  version: "1.0.0",
-  description: "Argsbarg kitchen-sink reference — all builtins, schemagen, ctx.appConfig.",
-  appConfig: {
-    jsonSchema: APP_CONFIG_JSON_SCHEMA,
-    entries: configSchema,
-  } satisfies CliAppConfig,
-  docs: {
-    enabled: true,
-    topics: {
-      readme: {
-        text: readmeText,
-      },
-    },
-  },
-  mcpServer: {
-    enabled: true,
-    mcpd: true,
-    claudePlugin: true,
-  },
-  install: {
-    // Defaults: app + completions + configure; agentIntegration picks skill vs MCP for --all.
-    updateGetLatest: async () => ({
-      path: process.execPath,
-      version: "1.0.0",
-    }),
-  },
-  commands: [
-    {
-      key: "status",
-      description: "Show resolved config and app version.",
-      options: [
-        {
-          name: "json",
-          description: "Emit JSON.",
-          kind: CliOptionKind.Presence,
-        },
-      ],
-      outputSchema: STATUS_JSON_OUTPUT_SCHEMA,
-      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,
-        };
-        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"}`);
-        }
-      },
-    },
-    {
-      key: "echo",
-      description: "Echo a message (MCP-friendly leaf).",
-      options: [
-        {
-          name: "message",
-          description: "Text to print.",
-          kind: CliOptionKind.String,
-          required: true,
-        },
-      ],
-      handler: (ctx) => {
-        console.log(ctx.stringOpt("message") ?? "");
-      },
-    },
-  ],
-} satisfies CliProgram;

package/src/builtins/install.ts

@@ -1,136 +0,0 @@
-import { resolveCapabilities } from "../capabilities.ts";
-import { type CliLeaf, type CliOption, CliOptionKind, type CliProgram } from "../types.ts";
-
-/** Install command options (dynamic: `--mcp` only when MCP is enabled). */
-export function installBuiltinOptions(root: CliProgram): CliOption[] {
-  const opts: CliOption[] = [
-    {
-      name: "all",
-      description:
-        "Install the default set (app, shell completions, and configuration when supported).",
-      kind: CliOptionKind.Presence,
-    },
-    {
-      name: "app",
-      description: "Copy this app to your install directory (default ~/.local/bin).",
-      kind: CliOptionKind.Presence,
-    },
-    {
-      name: "completions",
-      description:
-        "Install bash, zsh, and fish tab-completion scripts (each skipped silently if that shell is not on PATH).",
-      kind: CliOptionKind.Presence,
-    },
-    {
-      name: "skill",
-      description:
-        "Install agent skills for Cursor, Claude, and other supported AI tools on this machine.",
-      kind: CliOptionKind.Presence,
-    },
-  ];
-
-  if (resolveCapabilities(root).mcp) {
-    opts.push({
-      name: "mcp",
-      description:
-        "Add MCP server configuration for Cursor, Claude Code, and other supported agents.",
-      kind: CliOptionKind.Presence,
-    });
-  }
-
-  if (root.appConfig) {
-    opts.push({
-      name: "configure",
-      description:
-        "Run the configuration wizard (install), or remove the config file (--uninstall).",
-      kind: CliOptionKind.Presence,
-    });
-  }
-
-  opts.push(
-    {
-      name: "status",
-      description: "Print what is currently installed (read-only).",
-      kind: CliOptionKind.Presence,
-    },
-    {
-      name: "reinstall",
-      description: "Refresh everything already installed for this app.",
-      kind: CliOptionKind.Presence,
-    },
-  );
-
-  if (resolveCapabilities(root).update) {
-    opts.push({
-      name: "update",
-      description: "Download the latest release and refresh installed files.",
-      kind: CliOptionKind.Presence,
-    });
-  }
-
-  opts.push(
-    {
-      name: "uninstall",
-      description:
-        "Remove installed files (--all removes everything; use individual flags to remove one category).",
-      kind: CliOptionKind.Presence,
-    },
-    {
-      name: "from",
-      description: "App executable to copy (default: running executable). Used with --reinstall.",
-      kind: CliOptionKind.String,
-    },
-    {
-      name: "yes",
-      description: "Skip the confirmation prompt.",
-      kind: CliOptionKind.Presence,
-      shortName: "y",
-    },
-    {
-      name: "dry",
-      description: "Show what would change without writing files.",
-      kind: CliOptionKind.Presence,
-    },
-    {
-      name: "json",
-      description: "Print changed paths (install/update/uninstall) or status JSON on stdout.",
-      kind: CliOptionKind.Presence,
-    },
-  );
-
-  return opts;
-}
-
-/** Builds the `install` built-in command. */
-export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
-  const app = root.key;
-  const notesLines = [
-    "First-time setup:",
-    `  ${app} install --yes`,
-    "",
-    "Refresh after upgrading:",
-    `  ${app} install --reinstall`,
-  ];
-  if (resolveCapabilities(root).update) {
-    notesLines.push("", "Upgrade to latest release:", `  ${app} install --update`);
-  }
-  notesLines.push(
-    "",
-    "See what is installed:",
-    `  ${app} install --status`,
-    "",
-    "Remove everything installed with --all:",
-    `  ${app} install --uninstall --all --yes`,
-    "",
-    "Use --dry to preview changes without writing files.",
-    "Use --json for machine-readable output.",
-  );
-  return {
-    key: "install",
-    description:
-      "Install this app, shell completions, agent skills, and MCP config on your machine.",
-    options: installBuiltinOptions(root),
-    notes: notesLines.join("\n"),
-    handler: () => {},
-  };
-}

package/src/install/app.ts

@@ -1,94 +0,0 @@
-import {
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import { dirname, join } from "node:path";
-import type { CliProgram } from "../types.ts";
-import type { InstallPaths } from "./paths.ts";
-import {
-  buildPathRcBlock,
-  buildZshFpathRcBlock,
-  detectShells,
-  hasRcBlock,
-  removeRcBlock,
-} from "./shell.ts";
-
-export interface AppInstallResult {
-  changedFiles: string[];
-  patchedBashRc: boolean;
-  patchedZshRc: boolean;
-}
-
-/** Copies the app executable to the install path and patches rc files when shells are detected. */
-export function installApp(
-  root: CliProgram,
-  paths: InstallPaths,
-  dry: boolean,
-  sourcePath: string = process.execPath,
-): AppInstallResult {
-  const changed: string[] = [];
-  const shells = detectShells();
-  let patchedBashRc = false;
-  let patchedZshRc = false;
-
-  if (!dry) {
-    mkdirSync(paths.appDir, { recursive: true });
-    copyFileSync(sourcePath, paths.appPath);
-  }
-  changed.push(paths.appPath);
-
-  if (shells.bash && existsSync(dirname(paths.bashRc))) {
-    const block = buildPathRcBlock(root.key, paths.appDir);
-    let content = existsSync(paths.bashRc) ? readFileSync(paths.bashRc, "utf8") : "";
-    if (!hasRcBlock(content, root.key, "path")) {
-      if (!content.endsWith("\n") && content.length > 0) content += "\n";
-      content += `${block}\n`;
-      if (!dry) writeFileSync(paths.bashRc, content, "utf8");
-      changed.push(paths.bashRc);
-      patchedBashRc = true;
-    }
-  }
-
-  if (shells.zsh) {
-    const completionsDir = join(dirname(paths.zshCompletion));
-    const block = buildZshFpathRcBlock(root.key, completionsDir);
-    let content = existsSync(paths.zshRc) ? readFileSync(paths.zshRc, "utf8") : "";
-    if (!hasRcBlock(content, root.key, "fpath")) {
-      if (!content.endsWith("\n") && content.length > 0) content += "\n";
-      content += `${block}\n`;
-      if (!dry) writeFileSync(paths.zshRc, content, "utf8");
-      changed.push(paths.zshRc);
-      patchedZshRc = true;
-    }
-  }
-
-  return { changedFiles: changed, patchedBashRc, patchedZshRc };
-}
-
-/** Removes the installed app and rc marker blocks. */
-export function uninstallApp(root: CliProgram, paths: InstallPaths, dry: boolean): string[] {
-  const changed: string[] = [];
-  if (existsSync(paths.appPath)) {
-    if (!dry) unlinkSync(paths.appPath);
-    changed.push(paths.appPath);
-  }
-
-  for (const [rcPath, tag] of [
-    [paths.bashRc, "path"],
-    [paths.zshRc, "fpath"],
-  ] as const) {
-    if (!existsSync(rcPath)) continue;
-    const content = readFileSync(rcPath, "utf8");
-    if (hasRcBlock(content, root.key, tag)) {
-      const next = removeRcBlock(content, root.key, tag);
-      if (!dry) writeFileSync(rcPath, next, "utf8");
-      changed.push(rcPath);
-    }
-  }
-
-  return changed;
-}

package/src/install/bootstrap.ts

@@ -1,22 +0,0 @@
-import { existsSync } from "node:fs";
-import type { CliProgram } from "../types.ts";
-import { resolveAppDir } from "./paths.ts";
-
-/** Rewrites empty argv to `install` when the app is not yet installed (TTY only). */
-export function maybeBootstrapInstallArgv(argv: string[], program: CliProgram): string[] {
-  if (argv.length !== 0) {
-    return argv;
-  }
-  if (program.install?.enabled === false) {
-    return argv;
-  }
-  if (!process.stdin.isTTY) {
-    return argv;
-  }
-  const appDir = resolveAppDir();
-  const appPath = `${appDir}/${program.key}`;
-  if (existsSync(appPath)) {
-    return argv;
-  }
-  return ["install"];
-}

package/src/install/completions.ts

@@ -1,56 +0,0 @@
-import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import {
-  completionBashScript,
-  completionFishScript,
-  completionZshScript,
-} from "../builtins/index.ts";
-import { cliPresentationRoot } from "../builtins/presentation.ts";
-import type { CliProgram } from "../types.ts";
-import type { InstallPaths } from "./paths.ts";
-import { detectShells } from "./shell.ts";
-
-/** Writes shell completion scripts for detected shells. */
-export function installCompletions(root: CliProgram, paths: InstallPaths, dry: boolean): string[] {
-  const changed: string[] = [];
-  const shells = detectShells();
-  const schema = cliPresentationRoot(root);
-
-  if (shells.bash) {
-    if (!dry) {
-      mkdirSync(dirname(paths.bashCompletion), { recursive: true });
-      writeFileSync(paths.bashCompletion, completionBashScript(schema), "utf8");
-    }
-    changed.push(paths.bashCompletion);
-  }
-
-  if (shells.zsh) {
-    if (!dry) {
-      mkdirSync(dirname(paths.zshCompletion), { recursive: true });
-      writeFileSync(paths.zshCompletion, completionZshScript(schema), "utf8");
-    }
-    changed.push(paths.zshCompletion);
-  }
-
-  if (shells.fish) {
-    if (!dry) {
-      mkdirSync(dirname(paths.fishCompletion), { recursive: true });
-      writeFileSync(paths.fishCompletion, completionFishScript(schema), "utf8");
-    }
-    changed.push(paths.fishCompletion);
-  }
-
-  return changed;
-}
-
-/** Removes shell completion files. */
-export function uninstallCompletions(paths: InstallPaths, dry: boolean): string[] {
-  const changed: string[] = [];
-  for (const p of [paths.bashCompletion, paths.zshCompletion, paths.fishCompletion]) {
-    if (existsSync(p)) {
-      if (!dry) unlinkSync(p);
-      changed.push(p);
-    }
-  }
-  return changed;
-}