argsbarg 5.1.0 → 5.1.2

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.2] - 2026-07-04
+
+### Changed
+
+- **Private GitHub release installs** — release formulae use `GitHubPrivateReleaseDownloadStrategy` (GitHub API + `GitHub::API.credentials` / `HOMEBREW_GITHUB_API_TOKEN`); `just install-production` and `just test-release` export the token (with `gh auth token` fallback). Documented in `docs/distribution-homebrew.md`.
+
+## [5.1.1] - 2026-07-04
+
+### Fixed
+
+- **Configure without MCP** — skill-only apps (`mcpServer` unset) no longer prompt for MCP host config during interactive `configure`; MCP install targets default to disabled unless `mcpServer.enabled` is true.
+
+### Changed
+
+- **Internal DRY refactors** — shared bash/zsh completion simulate emitters, module-level `errorResult()` in the parser, unified configure stdin prompt via `readPromptLine`, and a shared `mcpServerRequiredForArtifact` predicate linking install defaults with schema validation.
+
 ## [5.1.0] - 2026-07-04
 
 ### Changed
@@ -585,7 +601,9 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.1.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.1.2...HEAD
+[5.1.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.2
+[5.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.1
 [5.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.0
 [5.0.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.3
 [5.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.2

package/docs/configure.md

@@ -14,6 +14,8 @@ brew install <tap>/<key>
 
 Upgrade with `brew upgrade <key>`. Shell completions are installed by Homebrew during `brew install`. Users must configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
 
+Private GitHub release assets require `HOMEBREW_GITHUB_API_TOKEN` at install time — see [distribution-homebrew.md](distribution-homebrew.md#end-user-install).
+
 **Uninstall the binary:** remove agent artifacts first (while the CLI is still on PATH), then `brew uninstall`:
 
 ```bash
@@ -64,7 +66,7 @@ Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remo
 | Cursor skill | Y/n prompt | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
 | Claude skill | Y/n prompt | `~/.claude/skills/<dir>/` when `~/.claude` exists |
 | Codex / OpenCode / OpenClaw skills | Y/n prompt | Agent-specific dirs when available |
-| MCP config | Y/n prompt | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop |
+| MCP config | Y/n prompt when `mcpServer.enabled` | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop |
 | App config | auto-runs wizard | Interactive wizard writes `~/.local/lib/<key>/config.json` |
 
 ### Externally managed binary (Homebrew)

package/docs/distribution-homebrew.md

@@ -20,6 +20,16 @@ brew install <tap>/{key}
 {key} configure   # when app config is required
 ```
 
+For **private or internal GitHub repos**, release formulae attach `HOMEBREW_GITHUB_API_TOKEN` when downloading the binary. Export a PAT with `repo` scope (or rely on `gh auth login` — `just install-production` and `just test-release` fall back to `gh auth token`):
+
+```bash
+export HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)"
+brew tap <org>/<repo> git@github.com:<org>/<repo>.git
+brew install <tap>/{key}
+```
+
+Local dev installs (`just install-local`) use a `file://` staging URL and do not need the token.
+
 ### Developer install
 
 ```bash
@@ -56,6 +66,15 @@ def post_install
 end
 ```
 
+Release formulae generated by `scripts/formula-shared.ts` embed a `GitHubPrivateReleaseDownloadStrategy` that resolves the release asset through the GitHub API at download time and authenticates with `GitHub::API.credentials` (backed by `HOMEBREW_GITHUB_API_TOKEN`, `gh auth`, or other Homebrew GitHub credential sources):
+
+```ruby
+url "https://github.com/<org>/<repo>/releases/download/vX.Y.Z/{key}",
+    using: GitHubPrivateReleaseDownloadStrategy
+```
+
+Local dev formulae (`just install-local`) use a plain `file://` URL and do not need the token.
+
 Completions require users to configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
 
 **Why configure is separate from `post_install`:** the wizard is interactive (TTY + prompts for secrets). Formula `post_install` runs non-interactively during `brew install` and in CI (`brew test`). Apps with `appConfig` print a one-line configure hint in formula `caveats` instead.

package/docs/output-schema.md

@@ -43,7 +43,7 @@ Production CLIs with several JSON commands tend to use **codegen** so types, han
 
 ## Recommended pipeline (copy per repo)
 
-No shared npm package — each app copies the same **contract**. Reference implementations: **sqsp-qa-tools**, **idp-trees**, **sqsp-i18n-tools** (see each repo’s `docs/architecture.md` for which commands use which schema root).
+No shared npm package — each app copies the same **contract**. Reference implementations: **sqsp-qa-manager**, **idp-trees**, **poc-sqsp-i18n-tools** (see each repo’s `docs/architecture.md` for which commands use which schema root).
 
 ```mermaid
 flowchart LR

package/examples/full-example/README.md

@@ -59,8 +59,8 @@ Requires [Homebrew](https://brew.sh) and a compiled binary at `dist/full-example
 just build
 just install-local              # first-time dev formula (`just install` is an alias)
 just reinstall-local            # fast binary swap during development
-just install-production         # uninstall local dev, install from GitHub tap
-just test-release
+just install-production         # uninstall local dev, install from GitHub tap (needs HOMEBREW_GITHUB_API_TOKEN for private repos)
+just test-release               # same token requirement when formula uses a GitHub release URL
 ```
 
 Undo a local dev install:

package/examples/full-example/justfile

@@ -8,6 +8,8 @@ cli_key := `bun scripts/print-identity.ts key`
 tap_org := `bun scripts/print-identity.ts tapOrg`
 tap_repo := `bun scripts/print-identity.ts tapRepo`
 tap := `bun scripts/print-identity.ts tap`
+release_repo := `bun scripts/print-identity.ts releaseRepo`
+tap_git_url := "git@github.com:" + release_repo + ".git"
 brew_prefix := `brew --prefix`
 tap_parent := brew_prefix + "/Library/Taps/" + tap_org
 tap_path := tap_parent + "/homebrew-" + tap_repo
@@ -59,12 +61,15 @@ install-local: build
     @echo ""
     @echo "Next: {{cli_key}} configure"
 
-# Remove local dev install, then install from GitHub tap
+# Remove local dev install, then install from GitHub tap (private release assets need HOMEBREW_GITHUB_API_TOKEN)
 install-production: uninstall
-    brew tap {{tap}}
-    brew install --formula {{tap}}/{{cli_key}}
-    @echo ""
-    @echo "Next: {{cli_key}} configure"
+    #!/usr/bin/env bash
+    set -eu -o pipefail
+    source scripts/ensure-brew-github-token.sh
+    brew tap {{release_repo}} {{tap_git_url}}
+    brew install --formula {{release_repo}}/{{cli_key}}
+    echo ""
+    echo "Next: {{cli_key}} configure"
 
 # Alias for backward compatibility
 reinstall: reinstall-local
@@ -96,10 +101,13 @@ test: check
 
 # Install release formula from tap and run formula test
 test-release:
-    @brew untap {{tap}} 2>/dev/null || true
+    #!/usr/bin/env bash
+    set -eu -o pipefail
+    source scripts/ensure-brew-github-token.sh
+    brew untap {{tap}} 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
-    @brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
     brew install --formula {{tap}}/{{cli_key}}
     brew test {{cli_key}}
 

package/examples/full-example/scripts/ensure-brew-github-token.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Ensure HOMEBREW_GITHUB_API_TOKEN is set for private GitHub release downloads.
+: "${HOMEBREW_GITHUB_API_TOKEN:=$(gh auth token 2>/dev/null || true)}"
+if [[ -z "${HOMEBREW_GITHUB_API_TOKEN}" ]]; then
+  echo "HOMEBREW_GITHUB_API_TOKEN is required to download private GitHub release assets." >&2
+  echo "Export a GitHub PAT with repo scope, or run: gh auth login" >&2
+  exit 1
+fi
+export HOMEBREW_GITHUB_API_TOKEN

package/examples/full-example/scripts/formula-shared.ts

@@ -30,8 +30,51 @@ export const formulaTestRuby = `test do
 
 export interface FormulaCoords {
   url: string;
+  urlStanza: string;
   version: string;
   sha256: string;
+  /** When true, embed {@link githubPrivateReleaseDownloadStrategyRuby} in the formula class. */
+  privateRelease?: boolean;
+}
+
+/** Resolves private GitHub release assets via the API at download time. */
+export const githubPrivateReleaseDownloadStrategyRuby = `  class GitHubPrivateReleaseDownloadStrategy < CurlDownloadStrategy
+    def initialize(url, name, version, **meta)
+      super
+      pattern = %r{https://github\\.com/([^/]+)/([^/]+)/releases/download/([^/]+)/(\\S+)}
+      match = url.match(pattern)
+      raise CurlDownloadStrategyError, "Invalid GitHub release URL: #{url}" unless match
+      @owner, @repo, @tag, @filename = match.captures
+    end
+
+    private
+
+    def _fetch(url:, resolved_url: resolved_download_url, timeout:)
+      curl_download resolved_download_url,
+                    "--header", "Accept: application/octet-stream",
+                    "--header", "Authorization: Bearer #{GitHub::API.credentials}",
+                    to: temporary_path
+    end
+
+    def resolved_download_url
+      @resolved_download_url ||= begin
+        asset = GitHub.get_release(@owner, @repo, @tag).fetch("assets")
+          .find { |a| a["name"] == @filename }
+        raise CurlDownloadStrategyError, "Release asset not found: #{@filename}" unless asset
+        asset.fetch("url")
+      end
+    end
+  end`;
+
+/** Homebrew `url` for local dev staging paths. */
+export function devUrlStanza(url: string): string {
+  return `url "${url}"`;
+}
+
+/** Homebrew `url` for GitHub release assets (uses {@link githubPrivateReleaseDownloadStrategyRuby}). */
+export function releaseUrlStanza(url: string): string {
+  return `url "${url}",
+      using: GitHubPrivateReleaseDownloadStrategy`;
 }
 
 export function releaseFormulaUrl(version: string): string {
@@ -39,10 +82,11 @@ export function releaseFormulaUrl(version: string): string {
 }
 
 export function renderFormula(coords: FormulaCoords): string {
+  const strategy = coords.privateRelease ? `${githubPrivateReleaseDownloadStrategyRuby}\n\n  ` : "";
   return `class ${className} < Formula
-  desc "${desc}"
+  ${strategy}desc "${desc}"
   homepage "${homepage}"
-  url "${coords.url}"
+  ${coords.urlStanza}
   version "${coords.version}"
   sha256 "${coords.sha256}"
 {dependsOnBlock}
@@ -58,16 +102,21 @@ end
 }
 
 export function renderReleaseFormula(version: string, sha256: string): string {
+  const url = releaseFormulaUrl(version);
   return renderFormula({
-    url: releaseFormulaUrl(version),
+    url,
+    urlStanza: releaseUrlStanza(url),
     version,
     sha256,
+    privateRelease: true,
   });
 }
 
 export function renderDevFormula(stagingPath: string, version: string, sha256: string): string {
+  const url = `file://${stagingPath}`;
   return renderFormula({
-    url: `file://${stagingPath}`,
+    url,
+    urlStanza: devUrlStanza(url),
     version,
     sha256,
   });

package/examples/full-example/scripts/print-identity.ts

@@ -5,7 +5,7 @@ import { createIdentity } from "./create-identity.ts";
 
 const field = process.argv[2];
 if (!field) {
-  console.error("Usage: bun scripts/print-identity.ts <key|className|tap|tapOrg|tapRepo|envPrefix>");
+  console.error("Usage: bun scripts/print-identity.ts <key|className|tap|tapOrg|tapRepo|releaseRepo|envPrefix>");
   process.exit(1);
 }
 
@@ -17,6 +17,7 @@ const values: Record<string, string> = {
   tapOrg: tapOrg ?? "",
   tapRepo: tapRepo ?? "",
   envPrefix: createIdentity.envPrefix,
+  releaseRepo: createIdentity.releaseRepo,
 };
 
 const value = values[field];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "5.1.0",
+  "version": "5.1.2",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/builtins/completion-bash.ts

@@ -1,4 +1,5 @@
 import { CliOptionKind, type CliRouter } from "../types.ts";
+import { emitConsumeLong, emitConsumeShort, emitMatchChild } from "./completion-simulate-shared.ts";
 import { collectScopes, type ScopeRec } from "./scopes.ts";
 import {
   escShellSingleQuoted,
@@ -8,105 +9,6 @@ import {
   mainName,
 } from "./shell-helpers.ts";
 
-function emitConsumeLong(ident: string, scopes: ScopeRec[]): string {
-  let o = "_${ident}_nac_consume_long() {\n".replace("${ident}", ident);
-  o += '  local sid="$1" w="$2" nw="$3"\n';
-  o += "  case $sid in\n";
-  for (const [i, sc] of scopes.entries()) {
-    o += `    ${i})\n`;
-    o += "      case $w in\n";
-    o +=
-      "        " +
-      kHelpLong +
-      "|${kHelpLong}=*|${kHelpShort}) echo 1 ;;\n"
-        .replace(/\$\{kHelpLong\}/g, kHelpLong)
-        .replace(/\$\{kHelpShort\}/g, kHelpShort);
-    for (const op of sc.opts) {
-      const base = `--${op.name}`;
-      if (op.kind === "presence") {
-        o += `        ${base}${"|${base}=*) echo 1 ;;\n".replace(/\$\{base\}/g, base)}`;
-      } else {
-        o += `        ${base}=*) echo 1 ;;\n`;
-        o += `        ${base}) echo 2 ;;\n`;
-      }
-    }
-    o += "        *) echo 0 ;;\n";
-    o += "      esac\n";
-    o += "      ;;\n";
-  }
-  o += "    *) echo 0 ;;\n";
-  o += "  esac\n";
-  o += "}\n";
-  return o;
-}
-
-function emitConsumeShort(ident: string, scopes: ScopeRec[]): string {
-  let o = "_${ident}_nac_consume_short() {\n".replace("${ident}", ident);
-  o += '  local sid="$1" w="$2"\n';
-  o += "  case $sid in\n";
-  for (const [i, sc] of scopes.entries()) {
-    o += `    ${i})\n`;
-    o += "      local rest=${w#-}\n";
-    o += "      local ch\n";
-    o += "      local saw=0\n";
-    o += "      while [[ -n $rest ]]; do\n";
-    o += "        ch=${rest:0:1}\n";
-    o += "        rest=${rest:1}\n";
-    o += "        case $ch in\n";
-    let boolChars = "";
-    for (const op of sc.opts) {
-      if (!op.shortName) continue;
-      if (op.kind === "presence") {
-        boolChars += `${op.shortName}|`;
-      } else {
-        o += `          ${op.shortName})\n`;
-        o += "            if [[ $saw -ne 0 || -n $rest ]]; then echo 0; return; fi\n";
-        o += "            echo 2; return ;;\n";
-      }
-    }
-    if (boolChars.length > 0) {
-      boolChars = boolChars.slice(0, -1);
-      o += `          ${boolChars}) ;;\n`;
-    }
-    o += "          *) echo 0; return ;;\n";
-    o += "        esac\n";
-    o += "        saw=1\n";
-    o += "      done\n";
-    o += "      echo 1\n";
-    o += "      ;;\n";
-  }
-  o += "    *) echo 0 ;;\n";
-  o += "  esac\n";
-  o += "}\n";
-  return o;
-}
-
-function emitMatchChild(
-  ident: string,
-  scopes: ScopeRec[],
-  pathIndex: Record<string, number>,
-): string {
-  let o = "_${ident}_nac_match_child() {\n".replace("${ident}", ident);
-  o += '  local sid="$1" w="$2"\n';
-  o += "  case $sid in\n";
-  for (const [sid, sc] of scopes.entries()) {
-    if (sc.kids.length === 0) continue;
-    o += `    ${sid})\n`;
-    o += "      case $w in\n";
-    for (const ch of sc.kids) {
-      const childPath = sc.path === "" ? ch.key : `${sc.path}/${ch.key}`;
-      const cid = pathIndex[childPath] ?? 0;
-      o += `        ${ch.key}) echo ${cid}; return 0 ;;\n`;
-    }
-    o += "      esac\n";
-    o += "      ;;\n";
-  }
-  o += "  esac\n";
-  o += "  return 1\n";
-  o += "}\n";
-  return o;
-}
-
 function emitSimulate(ident: string): string {
   let o = "_${ident}_nac_simulate() {\n".replace("${ident}", ident);
   o += "  local i=1 sid=0 w steps next\n";
@@ -247,7 +149,7 @@ export function completionBashScript(schema: CliRouter): string {
   }
 
   out += emitConsumeLong(ident, scopes);
-  out += emitConsumeShort(ident, scopes);
+  out += emitConsumeShort(ident, scopes, "bash");
   out += emitMatchChild(ident, scopes, pathIndex);
   out += emitSimulate(ident);
   out += emitEnumReplyBash(ident, scopes);

package/src/builtins/completion-simulate-shared.ts

@@ -0,0 +1,120 @@
+/*
+Shared shell completion emitters for bash and zsh simulate helpers.
+Generates _nac_consume_long, _nac_consume_short, and _nac_match_child functions
+used while walking argv to determine completion scope.
+*/
+
+import type { ScopeRec } from "./scopes.ts";
+import { kHelpLong, kHelpShort } from "./shell-helpers.ts";
+
+/** Which shell dialect to emit for bundled short-flag parsing. */
+export type CompletionShellDialect = "bash" | "zsh";
+
+/** Emits `_<ident>_nac_consume_long` — identical for bash and zsh. */
+export function emitConsumeLong(ident: string, scopes: ScopeRec[]): string {
+  let o = "_${ident}_nac_consume_long() {\n".replace("${ident}", ident);
+  o += '  local sid="$1" w="$2" nw="$3"\n';
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    o += `    ${i})\n`;
+    o += "      case $w in\n";
+    o +=
+      "        " +
+      kHelpLong +
+      "|${kHelpLong}=*|${kHelpShort}) echo 1 ;;\n"
+        .replace(/\$\{kHelpLong\}/g, kHelpLong)
+        .replace(/\$\{kHelpShort\}/g, kHelpShort);
+    for (const op of sc.opts) {
+      const base = `--${op.name}`;
+      if (op.kind === "presence") {
+        o += `        ${base}${"|${base}=*) echo 1 ;;\n".replace(/\$\{base\}/g, base)}`;
+      } else {
+        o += `        ${base}=*) echo 1 ;;\n`;
+        o += `        ${base}) echo 2 ;;\n`;
+      }
+    }
+    o += "        *) echo 0 ;;\n";
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "    *) echo 0 ;;\n";
+  o += "  esac\n";
+  o += "}\n";
+  return o;
+}
+
+/** Emits `_<ident>_nac_consume_short`; dialect selects substring syntax. */
+export function emitConsumeShort(
+  ident: string,
+  scopes: ScopeRec[],
+  dialect: CompletionShellDialect,
+): string {
+  const firstChar = dialect === "bash" ? "ch=${rest:0:1}" : "ch=${rest[1,1]}";
+  const restAdvance = dialect === "bash" ? "rest=${rest:1}" : "rest=${rest[2,-1]}";
+
+  let o = "_${ident}_nac_consume_short() {\n".replace("${ident}", ident);
+  o += '  local sid="$1" w="$2"\n';
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    o += `    ${i})\n`;
+    o += "      local rest=${w#-}\n";
+    o += "      local ch\n";
+    o += "      local saw=0\n";
+    o += "      while [[ -n $rest ]]; do\n";
+    o += `        ${firstChar}\n`;
+    o += `        ${restAdvance}\n`;
+    o += "        case $ch in\n";
+    let boolChars = "";
+    for (const op of sc.opts) {
+      if (!op.shortName) continue;
+      if (op.kind === "presence") {
+        boolChars += `${op.shortName}|`;
+      } else {
+        o += `          ${op.shortName})\n`;
+        o += "            if [[ $saw -ne 0 || -n $rest ]]; then echo 0; return; fi\n";
+        o += "            echo 2; return ;;\n";
+      }
+    }
+    if (boolChars.length > 0) {
+      boolChars = boolChars.slice(0, -1);
+      o += `          ${boolChars}) ;;\n`;
+    }
+    o += "          *) echo 0; return ;;\n";
+    o += "        esac\n";
+    o += "        saw=1\n";
+    o += "      done\n";
+    o += "      echo 1\n";
+    o += "      ;;\n";
+  }
+  o += "    *) echo 0 ;;\n";
+  o += "  esac\n";
+  o += "}\n";
+  return o;
+}
+
+/** Emits `_<ident>_nac_match_child` — identical for bash and zsh. */
+export function emitMatchChild(
+  ident: string,
+  scopes: ScopeRec[],
+  pathIndex: Record<string, number>,
+): string {
+  let o = "_${ident}_nac_match_child() {\n".replace("${ident}", ident);
+  o += '  local sid="$1" w="$2"\n';
+  o += "  case $sid in\n";
+  for (const [sid, sc] of scopes.entries()) {
+    if (sc.kids.length === 0) continue;
+    o += `    ${sid})\n`;
+    o += "      case $w in\n";
+    for (const ch of sc.kids) {
+      const childPath = sc.path === "" ? ch.key : `${sc.path}/${ch.key}`;
+      const cid = pathIndex[childPath] ?? 0;
+      o += `        ${ch.key}) echo ${cid}; return 0 ;;\n`;
+    }
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "  esac\n";
+  o += "  return 1\n";
+  o += "}\n";
+  return o;
+}

package/src/builtins/completion-zsh.ts

@@ -1,4 +1,5 @@
 import { CliOptionKind, type CliRouter } from "../types.ts";
+import { emitConsumeLong, emitConsumeShort, emitMatchChild } from "./completion-simulate-shared.ts";
 import { collectScopes, type ScopeRec } from "./scopes.ts";
 import {
   escShellSingleQuoted,
@@ -53,105 +54,6 @@ function emitScopeArraysZsh(ident: string, scopes: ScopeRec[]): string {
   return out;
 }
 
-function emitConsumeLongZsh(ident: string, scopes: ScopeRec[]): string {
-  let o = "_${ident}_nac_consume_long() {\n".replace("${ident}", ident);
-  o += '  local sid="$1" w="$2" nw="$3"\n';
-  o += "  case $sid in\n";
-  for (const [i, sc] of scopes.entries()) {
-    o += `    ${i})\n`;
-    o += "      case $w in\n";
-    o +=
-      "        " +
-      kHelpLong +
-      "|${kHelpLong}=*|${kHelpShort}) echo 1 ;;\n"
-        .replace(/\$\{kHelpLong\}/g, kHelpLong)
-        .replace(/\$\{kHelpShort\}/g, kHelpShort);
-    for (const op of sc.opts) {
-      const base = `--${op.name}`;
-      if (op.kind === "presence") {
-        o += `        ${base}${"|${base}=*) echo 1 ;;\n".replace(/\$\{base\}/g, base)}`;
-      } else {
-        o += `        ${base}=*) echo 1 ;;\n`;
-        o += `        ${base}) echo 2 ;;\n`;
-      }
-    }
-    o += "        *) echo 0 ;;\n";
-    o += "      esac\n";
-    o += "      ;;\n";
-  }
-  o += "    *) echo 0 ;;\n";
-  o += "  esac\n";
-  o += "}\n";
-  return o;
-}
-
-function emitConsumeShortZsh(ident: string, scopes: ScopeRec[]): string {
-  let o = "_${ident}_nac_consume_short() {\n".replace("${ident}", ident);
-  o += '  local sid="$1" w="$2"\n';
-  o += "  case $sid in\n";
-  for (const [i, sc] of scopes.entries()) {
-    o += `    ${i})\n`;
-    o += "      local rest=${w#-}\n";
-    o += "      local ch\n";
-    o += "      local saw=0\n";
-    o += "      while [[ -n $rest ]]; do\n";
-    o += "        ch=${rest[1,1]}\n";
-    o += "        rest=${rest[2,-1]}\n";
-    o += "        case $ch in\n";
-    let boolChars = "";
-    for (const op of sc.opts) {
-      if (!op.shortName) continue;
-      if (op.kind === "presence") {
-        boolChars += `${op.shortName}|`;
-      } else {
-        o += `          ${op.shortName})\n`;
-        o += "            if [[ $saw -ne 0 || -n $rest ]]; then echo 0; return; fi\n";
-        o += "            echo 2; return ;;\n";
-      }
-    }
-    if (boolChars.length > 0) {
-      boolChars = boolChars.slice(0, -1);
-      o += `          ${boolChars}) ;;\n`;
-    }
-    o += "          *) echo 0; return ;;\n";
-    o += "        esac\n";
-    o += "        saw=1\n";
-    o += "      done\n";
-    o += "      echo 1\n";
-    o += "      ;;\n";
-  }
-  o += "    *) echo 0 ;;\n";
-  o += "  esac\n";
-  o += "}\n";
-  return o;
-}
-
-function emitMatchChildZsh(
-  ident: string,
-  scopes: ScopeRec[],
-  pathIndex: Record<string, number>,
-): string {
-  let o = "_${ident}_nac_match_child() {\n".replace("${ident}", ident);
-  o += '  local sid="$1" w="$2"\n';
-  o += "  case $sid in\n";
-  for (const [sid, sc] of scopes.entries()) {
-    if (sc.kids.length === 0) continue;
-    o += `    ${sid})\n`;
-    o += "      case $w in\n";
-    for (const ch of sc.kids) {
-      const childPath = sc.path === "" ? ch.key : `${sc.path}/${ch.key}`;
-      const cid = pathIndex[childPath] ?? 0;
-      o += `        ${ch.key}) echo ${cid}; return 0 ;;\n`;
-    }
-    o += "      esac\n";
-    o += "      ;;\n";
-  }
-  o += "  esac\n";
-  o += "  return 1\n";
-  o += "}\n";
-  return o;
-}
-
 function emitSimulateZsh(ident: string): string {
   let o = "_${ident}_nac_simulate() {\n".replace("${ident}", ident);
   o += "  local i=2 sid=0 w steps next\n";
@@ -264,9 +166,9 @@ export function completionZshScript(schema: CliRouter): string {
 
   let out = `#compdef ${schema.key}\n\n`;
   out += emitScopeArraysZsh(ident, scopes);
-  out += emitConsumeLongZsh(ident, scopes);
-  out += emitConsumeShortZsh(ident, scopes);
-  out += emitMatchChildZsh(ident, scopes, pathIndex);
+  out += emitConsumeLong(ident, scopes);
+  out += emitConsumeShort(ident, scopes, "zsh");
+  out += emitMatchChild(ident, scopes, pathIndex);
   out += emitSimulateZsh(ident);
   out += emitEnumReplyZsh(ident, scopes);
   out += emitMainBodyZsh(schema, ident);

package/src/configure/prompt.ts

@@ -2,8 +2,8 @@
 TTY prompts for per-target install, skip, or uninstall during interactive `configure`.
 */
 
-import { readSync } from "node:fs";
 import type { CliInstallArtifactKey } from "../install/target-types.ts";
+import { readPromptLine } from "../prompt.ts";
 
 /** Human-readable labels for each install artifact key in interactive prompts. */
 const LABELS: Record<CliInstallArtifactKey, string> = {
@@ -35,9 +35,7 @@ export type TargetPromptAction = "install" | "skip" | "uninstall";
 export function promptTargetAction(label: string, installed: boolean): TargetPromptAction | null {
   const hint = installed ? `${label} [y/N]: ` : `${label} [Y/n]: `;
   process.stderr.write(hint);
-  const buf = Buffer.alloc(256);
-  const n = readSync(0, buf, { length: 256 });
-  const ans = buf.toString("utf8", 0, n).trim().toLowerCase();
+  const ans = readPromptLine().trim().toLowerCase();
   if (installed) {
     if (ans === "n") return "uninstall";
     return "skip";

package/src/install/install-validate.test.ts

@@ -63,4 +63,15 @@ describe("validateConfigureConfig", () => {
     };
     expect(() => cliValidateProgram(program)).not.toThrow();
   });
+
+  test("rejects explicit MCP target without mcpServer", () => {
+    const program: CliProgram = {
+      ...base,
+      configure: {
+        agentIntegration: "both",
+        targets: { cursorMcp: true },
+      },
+    };
+    expect(() => cliValidateProgram(program)).toThrow(/mcpServer\.enabled/);
+  });
 });

package/src/install/target-effective.ts

@@ -7,7 +7,12 @@ import type {
   InstallTargetSpec,
 } from "../types.ts";
 import type { InstallPaths } from "./paths.ts";
-import { AGENT_PAIRS, INSTALL_ARTIFACT_KEYS, installTargetForKey } from "./target-registry.ts";
+import {
+  AGENT_PAIRS,
+  INSTALL_ARTIFACT_KEYS,
+  installTargetForKey,
+  mcpServerRequiredForArtifact,
+} from "./target-registry.ts";
 import type { CliInstallArtifactKey, InstallPlanMode } from "./target-types.ts";
 
 export type { InstallTargetSpec, ResolvedInstallTarget } from "../types.ts";
@@ -44,9 +49,13 @@ export function resolveInstallTargetSpec(
 function artifactDefaults(
   key: CliInstallArtifactKey,
   integration: InstallAgentIntegration,
+  mcpServerEnabled: boolean,
 ): { enabled: boolean; includedInAll: boolean } {
   const target = installTargetForKey(key);
   const includedInAll = target?.defaultIncludedInAll(integration) ?? false;
+  if (!mcpServerRequiredForArtifact(key, mcpServerEnabled)) {
+    return { enabled: false, includedInAll: false };
+  }
   return { enabled: true, includedInAll };
 }
 
@@ -86,7 +95,10 @@ export function resolveEffectiveInstallTargets(
   const user = configure?.targets;
   const out = {} as Record<CliInstallArtifactKey, { enabled: boolean; includedInAll: boolean }>;
   for (const key of INSTALL_ARTIFACT_KEYS) {
-    out[key] = resolveInstallTargetSpec(user?.[key], artifactDefaults(key, integration));
+    out[key] = resolveInstallTargetSpec(
+      user?.[key],
+      artifactDefaults(key, integration, mcpEnabled),
+    );
   }
   applyAgentPairDedupe(out, user, integration);
   return out;

package/src/install/target-registry.ts

@@ -37,6 +37,23 @@ export function installTargetForKey(key: CliInstallArtifactKey): InstallTarget |
   return targetByKey.get(key);
 }
 
+/** True when the artifact key is an MCP install target (requires mcpServer.enabled). */
+export function isMcpArtifactKey(key: CliInstallArtifactKey): boolean {
+  return installTargetForKey(key)?.category === "mcp";
+}
+
+/**
+ * MCP install targets are inactive without mcpServer.enabled.
+ * Defaults: artifactDefaults in target-effective.ts.
+ * Explicit spec rejection: validateConfigureConfig in validate.ts.
+ */
+export function mcpServerRequiredForArtifact(
+  key: CliInstallArtifactKey,
+  mcpServerEnabled: boolean,
+): boolean {
+  return !isMcpArtifactKey(key) || mcpServerEnabled;
+}
+
 /** Lookup by plan action kind. */
 export function installTargetForActionKind(kind: InstallActionKind): InstallTarget | undefined {
   return INSTALL_TARGETS.find((t) => t.actionKind === kind);

package/src/install/targets.test.ts

@@ -50,7 +50,9 @@ describe("resolveEffectiveInstallTargets", () => {
     const program: Pick<CliProgram, "mcpServer"> = {};
     const t = resolveEffectiveInstallTargets(undefined, program);
     expect(t.cursorSkill.includedInAll).toBe(true);
+    expect(t.cursorSkill.enabled).toBe(true);
     expect(t.cursorMcp.includedInAll).toBe(false);
+    expect(t.cursorMcp.enabled).toBe(false);
   });
 
   test("mcp mode includes MCP in --all not paired skills", () => {

package/src/parse.ts

@@ -249,21 +249,6 @@ function finishLeaf(
   optionDefs: CliOption[],
   forcePositionalsIn: boolean,
 ): ParseResult {
-  /** Builds a parse error for positional consumption failures. */
-  function errorResult(msg: string): ParseResult {
-    const pr: ParseResult = {
-      kind: ParseKind.Error,
-      path: [],
-      opts: {},
-      args: [],
-      helpExplicit: false,
-      helpPath: [],
-      errorMsg: msg,
-      errorHelpPath: path,
-    };
-    return pr;
-  }
-
   let idx = startIdx;
   const args: string[] = [];
   let forcePositionals = forcePositionalsIn;
@@ -273,7 +258,7 @@ function finishLeaf(
     if (argMax === 1) {
       if (argMin >= 1) {
         if (idx >= argv.length) {
-          return errorResult(`Missing positional argument: ${p.name}`);
+          return errorResult(`Missing positional argument: ${p.name}`, path, []);
         }
         args.push(argv[idx]);
         idx += 1;
@@ -308,7 +293,7 @@ function finishLeaf(
           // MUST be false — lenient mode swallows unknown flags as positionals silently
           const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
           if (tailRep.report.err) {
-            return errorResult(tailRep.report.err);
+            return errorResult(tailRep.report.err, path, []);
           }
           if (tailRep.report.sawDoubleDash) {
             forcePositionals = true;
@@ -317,7 +302,7 @@ function finishLeaf(
             idx = tailRep.nextIndex;
             continue;
           }
-          return errorResult(`Unexpected option token: ${tok}`);
+          return errorResult(`Unexpected option token: ${tok}`, path, []);
         }
 
         args.push(tok);
@@ -332,13 +317,17 @@ function finishLeaf(
       }
     }
     if (count < argMin) {
-      return errorResult(`Expected at least ${argMin} argument(s) for ${p.name}, got ${count}`);
+      return errorResult(
+        `Expected at least ${argMin} argument(s) for ${p.name}, got ${count}`,
+        path,
+        [],
+      );
     }
   }
 
   if (idx < argv.length) {
     if (forcePositionals) {
-      return errorResult("Unexpected extra arguments");
+      return errorResult("Unexpected extra arguments", path, []);
     }
 
     if (isHelpTok(argv[idx])) {
@@ -347,12 +336,12 @@ function finishLeaf(
 
     const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
     if (tailRep.report.err) {
-      return errorResult(tailRep.report.err);
+      return errorResult(tailRep.report.err, path, []);
     }
     idx = tailRep.nextIndex;
 
     if (idx < argv.length) {
-      return errorResult("Unexpected extra arguments");
+      return errorResult("Unexpected extra arguments", path, []);
     }
   }
 
@@ -370,6 +359,24 @@ function finishLeaf(
 
 // ── Main Parser ───────────────────────────────────────────────────────────────
 
+/** Builds a user-error parse result; `path` defaults to `errorHelpPath`. */
+function errorResult(
+  errorMsg: string,
+  errorHelpPath: string[] = [],
+  path: string[] = errorHelpPath,
+): ParseResult {
+  return {
+    kind: ParseKind.Error,
+    path,
+    opts: {},
+    args: [],
+    helpExplicit: false,
+    helpPath: [],
+    errorMsg,
+    errorHelpPath,
+  };
+}
+
 /** Builds a help-request result for the current routing path. */
 function helpResult(p: string[], explicit: boolean): ParseResult {
   return {
@@ -401,16 +408,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
   // Consume root-level options first
   const rootRep = consumeOptions(root.options ?? [], rootLenient, argv, i, opts);
   if (rootRep.report.err) {
-    return {
-      kind: ParseKind.Error,
-      path: [],
-      opts: {},
-      args: [],
-      helpExplicit: false,
-      helpPath: [],
-      errorMsg: rootRep.report.err,
-      errorHelpPath: [],
-    };
+    return errorResult(rootRep.report.err);
   }
   i = rootRep.nextIndex;
   let forcePositionals = rootRep.report.sawDoubleDash;
@@ -436,16 +434,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
       cmdName = root.fallbackCommand;
       node = findChild(root.commands, cmdName);
       if (!node) {
-        return {
-          kind: ParseKind.Error,
-          path: [],
-          opts: {},
-          args: [],
-          helpExplicit: false,
-          helpPath: [],
-          errorMsg: `Unknown command: ${cmdName}`,
-          errorHelpPath: path,
-        };
+        return errorResult(`Unknown command: ${cmdName}`, path, []);
       }
     } else {
       return helpResult([], false);
@@ -469,34 +458,20 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
         cmdName = fallbackCommand;
         node = findChild(root.commands, cmdName);
         if (!node) {
-          return {
-            kind: ParseKind.Error,
-            path: [],
-            opts: {},
-            args: [],
-            helpExplicit: false,
-            helpPath: [],
-            errorMsg: `Unknown command: ${cmdName}`,
-            errorHelpPath: path,
-          };
+          return errorResult(`Unknown command: ${cmdName}`, path, []);
         }
       } else {
         cmdName = peek;
         if (!forcePositionals) i += 1;
         node = findChild(root.commands, cmdName);
         if (!node) {
-          return {
-            kind: ParseKind.Error,
-            path: [],
-            opts: {},
-            args: [],
-            helpExplicit: false,
-            helpPath: [],
-            errorMsg: forcePositionals
+          return errorResult(
+            forcePositionals
               ? `Expected subcommand but got positional: ${cmdName}`
               : `Unknown command: ${cmdName}`,
-            errorHelpPath: path,
-          };
+            path,
+            [],
+          );
         }
       }
     }
@@ -504,16 +479,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
 
   path.push(cmdName);
   if (!node) {
-    return {
-      kind: ParseKind.Error,
-      path,
-      opts: {},
-      args: [],
-      helpExplicit: false,
-      helpPath: [],
-      errorMsg: `Unknown command: ${cmdName}`,
-      errorHelpPath: path,
-    };
+    return errorResult(`Unknown command: ${cmdName}`, path);
   }
   let current = node;
 
@@ -522,16 +488,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
     if (!forcePositionals) {
       const orep = consumeOptions(collectOptionDefs(root, path), false, argv, i, opts);
       if (orep.report.err) {
-        return {
-          kind: ParseKind.Error,
-          path,
-          opts: {},
-          args: [],
-          helpExplicit: false,
-          helpPath: [],
-          errorMsg: orep.report.err,
-          errorHelpPath: path,
-        };
+        return errorResult(orep.report.err, path);
       }
       i = orep.nextIndex;
       if (orep.report.sawDoubleDash) {
@@ -576,16 +533,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
 
     const tok = argv[i];
     if (!forcePositionals && tok.startsWith("-")) {
-      return {
-        kind: ParseKind.Error,
-        path,
-        opts: {},
-        args: [],
-        helpExplicit: false,
-        helpPath: [],
-        errorMsg: `Unexpected option token: ${tok}`,
-        errorHelpPath: path,
-      };
+      return errorResult(`Unexpected option token: ${tok}`, path);
     }
 
     if (!forcePositionals && isCliRouter(current)) {
@@ -614,18 +562,12 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
         }
       }
 
-      return {
-        kind: ParseKind.Error,
-        path,
-        opts: {},
-        args: [],
-        helpExplicit: false,
-        helpPath: [],
-        errorMsg: forcePositionals
+      return errorResult(
+        forcePositionals
           ? `Expected subcommand but got positional: ${tok}`
           : `Unknown subcommand: ${tok}`,
-        errorHelpPath: path,
-      };
+        path,
+      );
     }
 
     if (!isCliLeaf(current)) {
@@ -656,29 +598,11 @@ export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
 
   for (const seg of pr.path) {
     if (!isCliRouter(node)) {
-      return {
-        kind: ParseKind.Error,
-        path: pr.path,
-        opts: {},
-        args: [],
-        helpExplicit: false,
-        helpPath: [],
-        errorMsg: "Internal path error",
-        errorHelpPath: pr.path,
-      };
+      return errorResult("Internal path error", pr.path);
     }
     const ch = findChild(node.commands, seg);
     if (!ch) {
-      return {
-        kind: ParseKind.Error,
-        path: pr.path,
-        opts: {},
-        args: [],
-        helpExplicit: false,
-        helpPath: [],
-        errorMsg: "Internal path error",
-        errorHelpPath: pr.path,
-      };
+      return errorResult("Internal path error", pr.path);
     }
     defs.push(...(ch.options ?? []));
     node = ch;
@@ -693,60 +617,24 @@ export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
 
   for (const d of defs) {
     if (d.required && !(d.name in opts)) {
-      return {
-        kind: ParseKind.Error,
-        path: pr.path,
-        opts: {},
-        args: [],
-        helpExplicit: false,
-        helpPath: [],
-        errorMsg: `Missing required option: --${d.name}`,
-        errorHelpPath: pr.path,
-      };
+      return errorResult(`Missing required option: --${d.name}`, pr.path);
     }
   }
 
   for (const [k, v] of Object.entries(opts)) {
     const d = findOptionByName(defs, k);
     if (!d) {
-      return {
-        kind: ParseKind.Error,
-        path: pr.path,
-        opts: {},
-        args: [],
-        helpExplicit: false,
-        helpPath: [],
-        errorMsg: `Unknown option key: ${k}`,
-        errorHelpPath: pr.path,
-      };
+      return errorResult(`Unknown option key: ${k}`, pr.path);
     }
     if (d.kind === CliOptionKind.Number) {
       if (!fullStringIsDouble(v)) {
-        return {
-          kind: ParseKind.Error,
-          path: pr.path,
-          opts: {},
-          args: [],
-          helpExplicit: false,
-          helpPath: [],
-          errorMsg: `Invalid number for option --${k}: ${v}`,
-          errorHelpPath: pr.path,
-        };
+        return errorResult(`Invalid number for option --${k}: ${v}`, pr.path);
       }
     }
     if (d.kind === CliOptionKind.Enum) {
       const choices = d.choices ?? [];
       if (!choices.includes(v)) {
-        return {
-          kind: ParseKind.Error,
-          path: pr.path,
-          opts: {},
-          args: [],
-          helpExplicit: false,
-          helpPath: [],
-          errorMsg: `Option --${k}: '${v}' is not one of: ${choices.join(", ")}`,
-          errorHelpPath: pr.path,
-        };
+        return errorResult(`Option --${k}: '${v}' is not one of: ${choices.join(", ")}`, pr.path);
       }
     }
     if (d.kind === CliOptionKind.String && (d.format !== undefined || d.pattern !== undefined)) {
@@ -759,16 +647,7 @@ export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
             : err instanceof Error
               ? err.message
               : String(err);
-        return {
-          kind: ParseKind.Error,
-          path: pr.path,
-          opts: {},
-          args: [],
-          helpExplicit: false,
-          helpPath: [],
-          errorMsg: `Invalid value for option --${k}: ${msg}`,
-          errorHelpPath: pr.path,
-        };
+        return errorResult(`Invalid value for option --${k}: ${msg}`, pr.path);
       }
     }
   }

package/src/validate.ts

@@ -6,7 +6,7 @@ import { reservedCommandNames, resolveCapabilities } from "./capabilities.ts";
 import { reservedDocsTopicResourceUris } from "./docs/mcp-resources.ts";
 import { DOCS_BUILTIN_TOPIC_KEYS } from "./docs/resolve.ts";
 import { validateFormatValue } from "./formats.ts";
-import { AGENT_PAIRS } from "./install/target-registry.ts";
+import { AGENT_PAIRS, MCP_KEYS, mcpServerRequiredForArtifact } from "./install/target-registry.ts";
 import { resolveMcpSchemaUri } from "./mcp/tools.ts";
 import {
   type CliLeaf,
@@ -150,6 +150,8 @@ function validateConfigureConfig(program: CliProgram): void {
   const integration: InstallAgentIntegration =
     configure.agentIntegration ?? (program.mcpServer?.enabled === true ? "mcp" : "skill");
 
+  const mcpEnabled = program.mcpServer?.enabled === true;
+
   for (const [mcpKey, skillKey] of AGENT_PAIRS) {
     const mcpSpec = targets[mcpKey];
     const skillSpec = targets[skillKey];
@@ -174,6 +176,15 @@ function validateConfigureConfig(program: CliProgram): void {
       );
     }
   }
+
+  for (const mcpKey of MCP_KEYS) {
+    if (
+      !mcpServerRequiredForArtifact(mcpKey, mcpEnabled) &&
+      installTargetExplicitTruthy(targets[mcpKey])
+    ) {
+      throw new CliSchemaValidationError(`configure.targets.${mcpKey} requires mcpServer.enabled`);
+    }
+  }
 }
 
 /** Validates a program schema. */