argsbarg 4.1.0 → 4.1.1

package/examples/config-app/program.ts

@@ -1,78 +0,0 @@
-/*
-CliProgram for the config-app example — program.appConfig with jsonSchema + metadata overlay.
-*/
-
-import pkg from "../../package.json" with { type: "json" };
-import {
-  type CliAppConfig,
-  type CliAppConfigEntry,
-  CliOptionKind,
-  type CliProgram,
-} from "../../src/index.ts";
-import { APP_CONFIG_JSON_SCHEMA } from "./schema.ts";
-
-const configSchema = {
-  apiToken: {
-    description: "Create at https://example.com/settings/tokens",
-    env: "CONFIG_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: "config-app",
-  version: pkg.version,
-  description: "Demonstrates program.appConfig, ctx.appConfig, and built-in config get/set.",
-  appConfig: {
-    jsonSchema: APP_CONFIG_JSON_SCHEMA,
-    entries: configSchema,
-  } satisfies CliAppConfig,
-  commands: [
-    {
-      key: "show",
-      description: "Print resolved config (secrets redacted).",
-      options: [
-        {
-          name: "json",
-          description: "Emit JSON.",
-          kind: CliOptionKind.Presence,
-        },
-      ],
-      handler: (ctx) => {
-        const out = {
-          defaultRegion: ctx.appConfig.get("defaultRegion"),
-          maxRetries: ctx.appConfig.get("maxRetries"),
-          prefs: ctx.appConfig.get("prefs"),
-          apiTokenSet: ctx.appConfig.get("apiToken") !== undefined,
-        };
-        if (ctx.hasFlag("json")) {
-          console.log(JSON.stringify(out, null, 2));
-        } else {
-          console.log(`region=${out.defaultRegion ?? "(not set)"}`);
-          console.log(`maxRetries=${out.maxRetries ?? "(not set)"}`);
-          console.log(`prefs=${out.prefs ? JSON.stringify(out.prefs) : "(not set)"}`);
-          console.log(`apiToken=${out.apiTokenSet ? "set" : "missing"}`);
-        }
-      },
-    },
-    {
-      key: "ping",
-      description: "Require apiToken and print a short confirmation.",
-      handler: (ctx) => {
-        const token = ctx.appConfig.require("apiToken");
-        console.log(`ok (token length ${String(token).length})`);
-      },
-    },
-  ],
-} satisfies CliProgram;

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/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;
-}

package/src/install/targets/completions.ts

@@ -1,133 +0,0 @@
-import { existsSync } from "node:fs";
-import type { CliProgram } from "../../types.ts";
-import { installCompletions, uninstallCompletions } from "../completions.ts";
-import { displayInstallPath, type InstallPaths } from "../paths.ts";
-import { detectShells } from "../shell.ts";
-import { InstallTarget } from "../target-base.ts";
-import type {
-  DetectedSnapshot,
-  InstallAction,
-  InstalledArtifacts,
-  InstallStatus,
-  TargetPlanContext,
-  UninstallAction,
-} from "../target-types.ts";
-
-type ShellKind = "bash" | "zsh" | "fish";
-
-interface ShellCompletionSpec {
-  shell: ShellKind;
-  label: string;
-  path: (paths: InstallPaths) => string;
-  detectedKey: "bashCompletion" | "zshCompletion" | "fishCompletion";
-}
-
-const SHELLS: ShellCompletionSpec[] = [
-  {
-    shell: "bash",
-    label: "bash completion",
-    path: (p) => p.bashCompletion,
-    detectedKey: "bashCompletion",
-  },
-  {
-    shell: "zsh",
-    label: "zsh completion",
-    path: (p) => p.zshCompletion,
-    detectedKey: "zshCompletion",
-  },
-  {
-    shell: "fish",
-    label: "fish completion",
-    path: (p) => p.fishCompletion,
-    detectedKey: "fishCompletion",
-  },
-];
-
-/** Shell tab-completion scripts (bash / zsh / fish). */
-class CompletionsInstallTarget extends InstallTarget {
-  readonly key = "completions" as const;
-  readonly actionKind = "completions" as const;
-  readonly category = "core" as const;
-
-  isAvailable(_root: CliProgram, _paths: InstallPaths): boolean {
-    return true;
-  }
-
-  isDetected(paths: InstallPaths, _root: CliProgram): boolean {
-    return SHELLS.some((s) => existsSync(s.path(paths)));
-  }
-
-  applyDetected(paths: InstallPaths, _root: CliProgram, out: InstalledArtifacts): void {
-    for (const s of SHELLS) {
-      out[s.detectedKey] = existsSync(s.path(paths));
-    }
-  }
-
-  protected isDetectedFromSnapshot(detected: DetectedSnapshot): boolean {
-    return detected.bashCompletion || detected.zshCompletion || detected.fishCompletion;
-  }
-
-  protected formatStatusLine(_paths: InstallPaths, _root: CliProgram): string {
-    return "";
-  }
-
-  protected assignStatusLine(_status: InstallStatus, _line: string): void {}
-
-  contributeStatus(
-    paths: InstallPaths,
-    _root: CliProgram,
-    detected: InstalledArtifacts,
-    status: InstallStatus,
-  ): void {
-    if (detected.bashCompletion) {
-      status.bashCompletion = displayInstallPath(paths.bashCompletion);
-    }
-    if (detected.zshCompletion) {
-      status.zshCompletion = displayInstallPath(paths.zshCompletion);
-    }
-    if (detected.fishCompletion) {
-      status.fishCompletion = displayInstallPath(paths.fishCompletion);
-    }
-  }
-
-  protected buildInstallActions(ctx: TargetPlanContext): InstallAction[] {
-    const shells = detectShells();
-    const actions: InstallAction[] = [];
-    const refresh = ctx.mode === "refresh";
-
-    for (const s of SHELLS) {
-      const onPath = shells[s.shell];
-      const path = s.path(ctx.paths);
-      const wasInstalled = ctx.detected[s.detectedKey];
-      if (!onPath || (refresh && !wasInstalled)) continue;
-
-      actions.push({
-        kind: "completions",
-        summary: `${s.label}: ${displayInstallPath(path)}`,
-        message: `Writing ${s.label} to ${displayInstallPath(path)}`,
-        run: () => {
-          const all = installCompletions(ctx.root, ctx.paths, ctx.dry);
-          return all.filter((p) => p === path);
-        },
-      });
-    }
-    return actions;
-  }
-
-  protected buildUninstallActions(ctx: TargetPlanContext): UninstallAction[] {
-    const actions: UninstallAction[] = [];
-    for (const s of SHELLS) {
-      if (!ctx.detected[s.detectedKey]) continue;
-      const path = s.path(ctx.paths);
-      actions.push({
-        kind: "completions",
-        summary: `${s.label}: ${displayInstallPath(path)}`,
-        message: `Removing ${s.label} ${displayInstallPath(path)}`,
-        run: () => uninstallCompletions(ctx.paths, ctx.dry).filter((p) => p === path),
-      });
-    }
-    return actions;
-  }
-}
-
-export const completionsTarget = new CompletionsInstallTarget();