argsbarg 5.1.0 → 5.1.1

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +595,8 @@ 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.1...HEAD
+[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

@@ -64,7 +64,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "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. */