argsbarg 4.1.0 → 5.0.1

package/src/types.ts

@@ -202,6 +202,26 @@ export interface CliUpdateArtifact {
 /** Fetches the latest release binary for `install --update`. */
 export type CliUpdateGetLatest = (ctx: { version: string }) => Promise<CliUpdateArtifact>;
 
+/** Context passed to {@link CliAppConfigEntry.resolve} for one config key. */
+export interface CliAppConfigResolveContext {
+  /** Schema key being resolved. */
+  key: string;
+  /** Entry metadata for this key. */
+  entry: CliAppConfigEntry;
+  /** Program root (read-only). */
+  program: CliProgram;
+  /** Raw value from the config file, if any. */
+  fileValue: unknown;
+  /** Non-empty host env string when `entry.env` is set; otherwise `undefined`. */
+  envValue: string | undefined;
+}
+
+/**
+ * Optional fallback resolver for one config key (e.g. `gh auth token` when `GH_TOKEN` is unset).
+ * Return `undefined` to continue resolution (env, then default).
+ */
+export type CliAppConfigResolveFn = (ctx: CliAppConfigResolveContext) => unknown;
+
 /**
  * Metadata overlay for one key in {@link CliAppConfig.entries}.
  * Types and validation come from {@link CliAppConfig.jsonSchema} when set; otherwise all values are strings.
@@ -222,6 +242,11 @@ export interface CliAppConfigEntry {
   sensitive?: boolean;
   /** When set: non-empty `process.env[env]` overrides file; value exported after resolve. */
   env?: string;
+  /**
+   * Optional fallback after file when env is empty.
+   * Return `undefined` to fall back to `env` (if set) and schema defaults.
+   */
+  resolve?: CliAppConfigResolveFn;
 }
 
 /**
@@ -236,23 +261,24 @@ export interface CliAppConfig {
   entries: Record<string, CliAppConfigEntry>;
 }
 
-export interface CliInstallConfig {
-  /** When `false`, hide/disable `install` (default: enabled). */
+/** Opt-out for the `completion` built-in (default: enabled). */
+export interface CliCompletionConfig {
+  /** When `false`, hide/disable `completion` (default: enabled). */
+  enabled?: boolean;
+}
+
+export interface CliConfigureConfig {
+  /** When `false`, hide/disable `configure` (default: enabled). */
   enabled?: boolean;
   /**
-   * Default agent integration for full install (`install --all`).
-   * - `'mcp'` when `mcpServer.enabled` (default): MCP targets in `--all`; paired skills excluded.
-   * - `'skill'` when MCP is off (default): skill targets in `--all`; paired MCP excluded.
-   * - `'both'`: install MCP and skill for the same host when both are available.
+   * Default agent integration for sync (`configure --sync`).
+   * - `'mcp'` when `mcpServer.enabled` (default): MCP targets in sync; paired skills excluded.
+   * - `'skill'` when MCP is off (default): skill targets in sync; paired MCP excluded.
+   * - `'both'`: sync MCP and skill for the same host when both are available.
    */
   agentIntegration?: InstallAgentIntegration;
-  /** Per-artifact gates for full install/uninstall. See {@link resolveEffectiveInstallTargets}. */
-  targets?: CliInstallTargets;
-  /**
-   * When set, enables `install --update` on the program root.
-   * Should download or locate the latest release binary and return its path.
-   */
-  updateGetLatest?: CliUpdateGetLatest;
+  /** Per-artifact gates for configure sync and interactive wizard. See {@link resolveEffectiveInstallTargets}. */
+  targets?: CliConfigureTargets;
 }
 
 /** Agent integration mode for install — MCP vs shell skill per host. */
@@ -264,7 +290,7 @@ export type InstallTargetSpec =
   | {
       /** When false, artifact is never installed (even with scoped CLI flags). Default true. */
       enabled?: boolean;
-      /** When true, included in bare `install` / `install --all`. Default varies by key. */
+      /** When true, included in `configure --sync`. Default varies by key. */
       includedInAll?: boolean;
     };
 
@@ -273,9 +299,9 @@ export interface ResolvedInstallTarget {
   includedInAll: boolean;
 }
 
-/** Per-artifact gates for full install/uninstall. See {@link resolveEffectiveInstallTargets}. */
-export interface CliInstallTargets {
-  /** Copy app to `~/.local/bin/<key>`. Default includedInAll true (opt-out). */
+/** Per-artifact gates for configure. See {@link resolveEffectiveInstallTargets}. */
+export interface CliConfigureTargets {
+  /** App binary status only (Homebrew PATH); no self-install. */
   app?: InstallTargetSpec;
   /** ChatGPT desktop MCP. Default false. */
   chatgptMcp?: InstallTargetSpec;
@@ -289,9 +315,7 @@ export interface CliInstallTargets {
   codexMcp?: InstallTargetSpec;
   /** Codex skill. Default false. */
   codexSkill?: InstallTargetSpec;
-  /** Shell completions for detected shells. Default includedInAll true (opt-out). */
-  completions?: InstallTargetSpec;
-  /** App config: wizard on install, file removal on uninstall. Default includedInAll true. */
+  /** App config: interactive wizard step in `configure`. Default not in sync. */
   configure?: InstallTargetSpec;
   /** Cursor MCP. Default false. */
   cursorMcp?: InstallTargetSpec;
@@ -396,8 +420,10 @@ export type CliProgram = CliNode & {
   appConfig?: CliAppConfig;
   /** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
   mcpServer?: CliMcpServerConfig;
-  /** Opt-out and defaults for `install`. */
-  install?: CliInstallConfig;
+  /** Opt-out and defaults for `configure`. */
+  configure?: CliConfigureConfig;
+  /** Opt-out for shell completion generation (`completion bash|zsh|fish`). */
+  completion?: CliCompletionConfig;
   /** When set with `enabled: true`, enables the `docs` built-in command group. */
   docs?: CliDocsConfig;
 };

package/src/validate.ts

@@ -81,6 +81,11 @@ function validateConfigBlock(appConfigBlock: import("./types.ts").CliAppConfig):
       }
       envNames.add(entry.env);
     }
+    if (entry.resolve !== undefined && typeof entry.resolve !== "function") {
+      throw new CliSchemaValidationError(
+        `program.appConfig.entries['${key}'].resolve must be a function when set`,
+      );
+    }
   }
 
   const jsonSchema = appConfigBlock.jsonSchema;
@@ -122,28 +127,28 @@ function installTargetExplicitTruthy(spec: InstallTargetSpec | undefined): boole
   return spec.enabled !== false;
 }
 
-/** Validates `program.install` targets and agentIntegration. */
-function validateInstallConfig(program: CliProgram): void {
-  const install = program.install;
-  if (!install) return;
+/** Validates `program.configure` targets and agentIntegration. */
+function validateConfigureConfig(program: CliProgram): void {
+  const configure = program.configure;
+  if (!configure) return;
 
-  if ("prefix" in install) {
+  if ("prefix" in configure) {
     throw new CliSchemaValidationError(
-      "install.prefix removed; app installs to ~/.local/bin/<key>",
+      "configure.prefix removed; app binary installs via Homebrew",
     );
   }
 
-  if (!install.targets) return;
+  if (!configure.targets) return;
 
-  const targets = install.targets;
+  const targets = configure.targets;
   if ("allSkills" in targets || "allMcps" in targets) {
     throw new CliSchemaValidationError(
-      "install.targets.allSkills/allMcps removed; use agentIntegration and per-key targets",
+      "configure.targets.allSkills/allMcps removed; use agentIntegration and per-key targets",
     );
   }
 
   const integration: InstallAgentIntegration =
-    install.agentIntegration ?? (program.mcpServer?.enabled === true ? "mcp" : "skill");
+    configure.agentIntegration ?? (program.mcpServer?.enabled === true ? "mcp" : "skill");
 
   for (const [mcpKey, skillKey] of AGENT_PAIRS) {
     const mcpSpec = targets[mcpKey];
@@ -154,18 +159,18 @@ function validateInstallConfig(program: CliProgram): void {
 
     if (mcpOn && skillOn && integration !== "both") {
       throw new CliSchemaValidationError(
-        `install.targets: ${host} has both MCP and skill configured; set agentIntegration: 'both' or disable one side`,
+        `configure.targets: ${host} has both MCP and skill configured; set agentIntegration: 'both' or disable one side`,
       );
     }
 
     if (integration === "skill" && mcpOn) {
       throw new CliSchemaValidationError(
-        `install.targets.${mcpKey} requires agentIntegration: 'both' when agentIntegration is 'skill'`,
+        `configure.targets.${mcpKey} requires agentIntegration: 'both' when agentIntegration is 'skill'`,
       );
     }
     if (integration === "mcp" && skillOn) {
       throw new CliSchemaValidationError(
-        `install.targets.${skillKey} requires agentIntegration: 'both' when agentIntegration is 'mcp'`,
+        `configure.targets.${skillKey} requires agentIntegration: 'both' when agentIntegration is 'mcp'`,
       );
     }
   }
@@ -197,19 +202,8 @@ export function cliValidateProgram(program: CliProgram): void {
     validateConfigBlock(program.appConfig);
   }
 
-  if (program.install?.updateGetLatest !== undefined) {
-    if (program.install.enabled === false) {
-      throw new CliSchemaValidationError(
-        "install.updateGetLatest requires install to be enabled (omit install.enabled: false)",
-      );
-    }
-    if (typeof program.install.updateGetLatest !== "function") {
-      throw new CliSchemaValidationError("install.updateGetLatest must be a function");
-    }
-  }
-
-  if (program.install !== undefined) {
-    validateInstallConfig(program);
+  if (program.configure !== undefined) {
+    validateConfigureConfig(program);
   }
 
   const caps = resolveCapabilities(program);
@@ -234,9 +228,9 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
         `mcpServer is only supported on the program root (not on ${node.key})`,
       );
     }
-    if (rogue.install !== undefined) {
+    if (rogue.configure !== undefined) {
       throw new CliSchemaValidationError(
-        `install is only supported on the program root (not on ${node.key})`,
+        `configure is only supported on the program root (not on ${node.key})`,
       );
     }
     if (rogue.docs !== undefined) {

package/docs/install.md

@@ -1,290 +0,0 @@
-# Install command
-
-The `install` built-in installs the app, shell completions, agent skills, and MCP config. Opt out with `install: { enabled: false }` on the program root.
-
-## End-user install
-
-Ship a compiled binary (or app bundle). Users install interactively — no `--yes` required when stdin is a TTY:
-
-- **Terminal:** run `./myapp`, `myapp`, or `myapp install` (bare `install` is equivalent to `--all`).
-- **macOS app:** double-click the `.app`; when the binary is not yet on PATH and stdin is a TTY, launching with no arguments bootstraps to **`myapp install`**.
-
-Interactive flow prints a **`{app} Setup`** banner, a numbered plan, and a confirm prompt. When the app needs API keys or other settings, a **`Configuration Setup`** section runs after install (or immediately for **`install --configure`**).
-
-**Uninstall is CLI-only** — there is no GUI uninstaller. Users run:
-
-```bash
-myapp install --uninstall          # remove all detected artifacts
-myapp install --uninstall --app    # scoped removal
-```
-
-Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--reinstall`**, **`--update`**) — see [Confirmation](#confirmation).
-
-## Quick start (automation)
-
-```bash
-# First-time setup (bare `install` is equivalent to `--all`)
-myapp install --yes
-
-# Or explicitly
-myapp install --all --yes
-
-# Refresh after upgrading (re-copy running app + refresh detected artifacts in scope)
-myapp install --reinstall
-
-# Upgrade to latest release (when this app supports remote updates)
-myapp install --update
-
-# See what is installed
-myapp install --status
-
-# Remove everything detected on disk (bare `install --uninstall` is equivalent to `--uninstall --all`)
-myapp install --uninstall --yes
-```
-
-## What gets installed
-
-| Target | Flag | Destination |
-| --- | --- | --- |
-| App | `--app` | `~/.local/bin/<key>` |
-| Bash completion | `--completions` | `~/.bash_completion.d/<key>` + `.bashrc` PATH snippet |
-| Zsh completion | `--completions` | `~/.zsh/completions/_<key>` + `.zshrc` fpath snippet |
-| Fish completion | `--completions` | `~/.config/fish/completions/<key>.fish` |
-| Cursor skill | `--skill` | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
-| Claude skill | `--skill` | `~/.claude/skills/<dir>/` when `~/.claude` exists |
-| Codex / OpenCode / OpenClaw skills | `--skill` | Agent-specific dirs when the agent home or CLI is available |
-| MCP config | `--mcp` | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop (when app data exists). ChatGPT web uses Connectors — see `docs mcp` |
-| App config | `--configure` | Interactive wizard writes app settings; `--uninstall --configure` removes the file |
-
-### Default `--all` behavior
-
-Bare **`install`** and **`install --all`** install targets with **`includedInAll: true`**. Core defaults:
-
-- **Always included:** `app`, `completions`, `configure` (wizard when `program.appConfig` is set)
-- **Agent integration** (`install.agentIntegration`, default from `mcpServer.enabled`):
-  - **`skill`** (default when MCP off): all `*Skill` keys in `--all`; paired `*Mcp` keys excluded
-  - **`mcp`** (default when `mcpServer.enabled`): all `*Mcp` keys in `--all`; paired skills excluded
-  - **`both`**: MCP and skill for the same host when available
-
-Desktop-only MCP hosts (`claudeDesktopMcp`, `chatgptMcp`) follow the MCP side only — no skill pair.
-
-Scoped flags (`--app`, `--completions`, `--configure`) run that artifact category. **`--skill`** and **`--mcp`** install only targets enabled by `agentIntegration` and per-key `install.targets`. Honor `enabled: false` as a hard off.
-
-Use **`install --status --json`** to preview effective targets (`effective.all`, `effective.mcp`, `effective.skill`) before installing.
-
-### Asymmetric uninstall
-
-- **`install --uninstall --all`** (including bare **`install --uninstall`**) removes **every detected artifact type**, ignoring `install.targets`.
-- Scoped uninstall (`--app`, `--skill`, …) removes only that category.
-
-Missing targets are skipped silently (no error if nothing is on disk or a shell/agent directory does not exist). Shells not on PATH are skipped silently (no warnings).
-
-## `install.targets`
-
-Configure which artifacts participate in `--all`, `--reinstall`, and `--update`:
-
-```typescript
-install: {
-  agentIntegration: "mcp", // | "skill" | "both" — default from mcpServer.enabled
-  targets: {
-    app: { includedInAll: false },
-    chatgptMcp: false,
-    cursorSkill: { includedInAll: true },
-  },
-},
-```
-
-`InstallTargetSpec` is `boolean` or `{ enabled?: boolean; includedInAll?: boolean }`. Shorthand `true` enables the target with default `includedInAll`; `false` disables it.
-
-Artifact keys: `app`, `chatgptMcp`, `claudeCodeMcp`, `claudeDesktopMcp`, `claudeSkill`, `codexMcp`, `codexSkill`, `completions`, `configure`, `cursorMcp`, `cursorSkill`, `openclawMcp`, `openclawSkill`, `opencodeMcp`, `opencodeSkill`.
-
-Conflicting targets (e.g. both `cursorMcp` and `cursorSkill` without `agentIntegration: 'both'`) fail at program validation time.
-
-## Examples
-
-### MCP CLI (default)
-
-```typescript
-const program = {
-  key: "myapp",
-  version: "1.0.0",
-  description: "…",
-  mcpServer: { enabled: true },
-  install: {}, // agentIntegration defaults to "mcp"
-  // …
-} satisfies CliProgram;
-```
-
-Bare **`myapp install --yes`** installs the app, completions, configure wizard (when `appConfig` is set), and MCP hosts — not shell skills for paired agents.
-
-### Shell-only CLI (default)
-
-```typescript
-const program = {
-  key: "myapp",
-  version: "1.0.0",
-  description: "…",
-  install: {}, // agentIntegration defaults to "skill"
-  // …
-} satisfies CliProgram;
-```
-
-Bare install includes agent skills (when each host is available), not MCP config.
-
-### Overrides
-
-```typescript
-install: {
-  agentIntegration: "both", // MCP + skill on the same host
-  targets: {
-    chatgptMcp: false, // opt out of one MCP host
-    app: { includedInAll: false }, // skip app on --all
-  },
-},
-```
-
-Preview resolved targets: **`myapp install --status --json`**.
-
-## Configuration
-
-On the program root:
-
-```typescript
-install: {
-  enabled: false,       // opt out of the install built-in
-  updateGetLatest: async ({ version }) => {
-    // download or locate latest release; return { path, version, cleanup }
-    return { path: "/tmp/myapp", version: "2.0.0" };
-  },
-}
-```
-
-When `updateGetLatest` is set, ArgsBarg adds **`install --update`** (download latest release and reinstall installed artifacts in scope).
-
-### GitHub releases (`ghReleaseUpdateGetLatest`)
-
-For compiled apps published via `gh release`, wire a hook without hand-rolling download logic:
-
-```typescript
-import {
-  createGhFetchLatest,
-  createGhVersionCheck,
-  ghReleaseUpdateGetLatest,
-} from "argsbarg";
-
-const cachePath = path.join(configDir, "version-check.json");
-
-install: {
-  updateGetLatest: ghReleaseUpdateGetLatest({
-    repo: "owner/repo",
-    asset: "myapp",
-    tempPrefix: "myapp-update.",
-    cachePath,
-  }),
-}
-
-// Optional: summary notice + background refresh
-const versionCheck = createGhVersionCheck({
-  currentVersion: "1.0.0",
-  commandName: "myapp",
-  cachePath,
-  fetchLatest: createGhFetchLatest({ repo: "owner/repo" }),
-});
-versionCheck.getUpdateNotice();
-versionCheck.refreshIfStale();
-```
-
-Requires `gh` on PATH and `gh auth login`. Consumers keep app-specific config only (~15 lines).
-
-## App config (`program.appConfig`)
-
-When `program.appConfig` is set on the program root, ArgsBarg manages a flat JSON config file:
-
-```typescript
-appConfig: {
-  entries: {
-    apiToken: {
-      description: "Create at https://example.com/settings/tokens",
-      env: "API_TOKEN",
-      sensitive: true,
-    },
-  },
-},
-```
-
-Config file path: `~/.local/lib/<sanitized-key>/config.json`.
-
-| Flag | Description |
-| --- | --- |
-| `--configure` | Interactive prompt for each setting; writes or updates the config file. On full install, the wizard runs automatically when configuration is in scope. Standalone **`install --configure`** runs the wizard only (no other install steps). |
-| `--uninstall --configure` | Remove the config directory (`~/.local/lib/<key>/`) |
-| `--status` | Shows config path and which required keys are set or missing |
-
-**Configure UX** (TTY):
-
-```
-Configuration Setup
-
-API token (API_TOKEN)
-  Create at https://example.com/settings/tokens
-  Current: REDACTED
-  Value (Enter to copy from env):
-```
-
-Non-sensitive vars show the current value; first-time setup omits the `Current:` line. When the current value comes from a mapped environment variable, Enter copies it into `config.json`; otherwise Enter keeps the existing file value. At runtime, a non-empty mapped environment variable always wins over `config.json` (the file is the fallback when env is unset).
-
-## Flags
-
-### Target flags
-
-| Flag | Description |
-| --- | --- |
-| `--all` | Install the default set (app, shell completions, and configuration when supported) |
-| `--app` | Copy this app to the install directory |
-| `--completions` | Install bash, zsh, and fish tab-completion scripts |
-| `--skill` | Install agent skills for Cursor, Claude, and other supported AI tools |
-| `--mcp` | Add MCP server configuration for Cursor, Claude Code, and other supported agents |
-| `--configure` | Run the configuration wizard (install) or remove the config file (`--uninstall`) |
-
-### Operation flags
-
-| Flag | Description |
-| --- | --- |
-| `--status` | Read-only inventory |
-| `--reinstall` | Refresh everything already installed (implies `--yes`; no numbered confirm) |
-| `--update` | Download the latest release and refresh installed files (implies `--yes`) |
-| `--uninstall` | Remove installed files (`--all` removes everything; use individual flags for one category) |
-| `--from <path>` | App executable to copy with `--reinstall` / `--update` (default: running executable) |
-
-### Behavior flags
-
-| Flag | Description |
-| --- | --- |
-| `--yes`, `-y` | Skip confirmation (required for non-TTY unless `--json`, `--reinstall`, or `--update`) |
-| `--dry` | Preview changes; per-step messages on stderr with `[dry run]` |
-| `--json` | Machine-readable output on stdout (implies `--yes`) |
-
-## Confirmation
-
-Install and uninstall (except `--yes`, `--json`, `--dry`, `--reinstall`, `--update`) print a **`{app} Setup`** banner on stderr, then a numbered list of planned actions on stdout. Reply **`y`** for all, **`n`** or Enter to abort, or numbers for a subset. On **install**, when the plan includes the app as item **1**, it is always installed (prompt example: **`2,3`**); MCP and other targets need the binary on PATH. On **uninstall**, use any subset (e.g. **`1,3`**). After you confirm, **`Done.`** prints on stderr. Per-step progress is suppressed until you confirm; the final **`Installed N file(s).`** summary still prints.
-
-## MCP merge behavior
-
-When `--mcp` runs, entries are merged into host config with:
-
-```json
-{ "command": "<root.key>", "args": ["mcp"] }
-```
-
-If an existing entry differs, the command exits with an error unless `--yes` is passed (then it overwrites). MCP conflict checks run only for hosts present in the current plan.
-
-## Opt out
-
-```typescript
-const cli = {
-  key: "myapp",
-  description: "...",
-  install: { enabled: false },
-  // ...
-} satisfies CliProgram;
-```

package/docs/templates/cursor/rules/cli-program.mdc

@@ -1,31 +0,0 @@
----
-description: Argsbarg schema — read framework docs before editing CLI commands
-globs: "src/**/commands/**/*.{ts,tsx},src/index.{ts,tsx}"
-alwaysApply: false
----
-
-When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
-
-1. **Read** `node_modules/argsbarg/docs/cli-program.md` (required — authoritative guide).
-2. MCP tools, varargs, `inputSchema` → also `node_modules/argsbarg/docs/mcp.md`.
-3. JSON stdout / `outputSchema` guide and codegen → `node_modules/argsbarg/docs/output-schema.md`.
-4. App config / `program.appConfig` guide and codegen → `node_modules/argsbarg/docs/config-schema.md`.
-5. `install`, `install.targets`, completions, skills → `node_modules/argsbarg/docs/install.md`.
-6. Bundled `docs` built-in → `node_modules/argsbarg/docs/bundled-docs.md`.
-7. **Examples** (shipped under `node_modules/argsbarg/examples/`):
-   - Concepts / minimal config → `examples/config-app/`
-   - **Copy template** (all builtins, schemagen, `outputSchema`) → `examples/consumer-app/`
-
-**Hard rules** (details and examples are in the docs above — do not contradict them):
-
-- Reserved root commands: `completion`, `install`, `mcp`, `version`, `docs`, `update`, `config`.
-- `satisfies CliProgram` / `CliLeaf`; action-oriented `description` on root, commands, options, and positionals.
-- Omit `mcpTool` unless genuinely CLI-only (`enabled: false`) or an irreducible wire limit — fix schema and headless handlers first.
-- Interactive leaves: one headless path for MCP, non-TTY CLI, and `--yes` / `--dry-run` / `--json` (`shouldRunHeadless*`, `requireYesInNonTty`); not raw `isTTY`.
-- String options: `format` / `default` / `pattern` per `cli-program.md`; `readLeafInputs()` for multi-flag leaves.
-- Varargs (`argMax: 0`): CLI space-separated; MCP JSON array only — no comma-splitting positionals.
-- Multi-surface leaves (Ink + headless + MCP): one **`read*Flags(ctx)`** per command (or shared family helper + extensions); one **`resolve*Input(flags)`** for cross-field rules — handler reads ctx once, all paths share the struct.
-- JSON stdout: `outputSchema` on the leaf from generated constants in `outputSchemas.ts` — see `output-schema.md`; mark roots with **`JSON payload`** JSDoc in `src/**/types.ts`; do not hand-edit `src/schemas/generated/` or `outputSchemas.ts`.
-- App config: `program.appConfig.jsonSchema` from generated `configSchemas.ts` — see `config-schema.md`; mark roots with **`Config schema`** JSDoc; prefer the layout in `node_modules/argsbarg/examples/consumer-app/` when adding new schema roots.
-
-**App-specific conventions:** replace this line with a `**<your-app> conventions:**` section (bullets only). Keep it at the bottom of this file — `just consumer-dev` / `just consumers-sync` in the argsbarg repo refresh the template above and preserve this block. Do not duplicate `cli-program.md` here; link paths and patterns only. For a second rule file (e.g. `.cursor/argsbarg.mdc`), that is fine too.

package/examples/config-app/main.ts

@@ -1,20 +0,0 @@
-#!/usr/bin/env bun
-/*
-Multi-file consumer example for program.appConfig.
-
-Files:
-  types.ts   — AppConfig interface (Config schema JSDoc marker for schemagen)
-  schema.ts  — APP_CONFIG_JSON_SCHEMA (inline; production apps generate this)
-  program.ts — CliProgram with appConfig block and commands using ctx.appConfig
-
-Try:
-  CONFIG_APP_API_TOKEN=dev bun ./examples/config-app/main.ts show --json
-  CONFIG_APP_API_TOKEN=dev bun ./examples/config-app/main.ts config get
-  CONFIG_APP_API_TOKEN=dev bun ./examples/config-app/main.ts ping
-*/
-
-import { Cli } from "../../src/index.ts";
-import { program } from "./program.ts";
-
-const cli = new Cli(program);
-await cli.run();

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;