argsbarg 6.1.1 → 6.1.3

package/src/{install → configure/artifacts}/target-plan-build.ts

@@ -1,5 +1,5 @@
-import { resolveCapabilities } from "../capabilities.ts";
-import type { CliProgram } from "../types.ts";
+import type { CliProgram } from "~/core/types.ts";
+import { resolveCapabilities } from "~/runtime/capabilities.ts";
 import type { InstallPaths } from "./paths.ts";
 import { mcpCategoryEnabled } from "./target-effective.ts";
 import { INSTALL_TARGETS, installTargetForKey } from "./target-registry.ts";

package/src/{install → configure/artifacts}/target-registry.ts

@@ -1,9 +1,9 @@
 import type { InstallTarget } from "./target-base.ts";
 import type { SkillInstallTarget } from "./target-skill.ts";
 import type { CliInstallArtifactKey, InstallActionKind } from "./target-types.ts";
-import { INSTALL_TARGETS } from "./targets/index.ts";
+import { INSTALL_TARGETS } from "./targets";
 
-export { INSTALL_TARGETS } from "./targets/index.ts";
+export { INSTALL_TARGETS } from "./targets";
 
 export const INSTALL_ARTIFACT_KEYS: CliInstallArtifactKey[] = INSTALL_TARGETS.map((t) => t.key);
 

package/src/{install → configure/artifacts}/target-scope.ts

@@ -1,6 +1,6 @@
-import { resolveCapabilities } from "../capabilities.ts";
-import { appConfigFileExists } from "../config/file.ts";
-import type { CliConfigureTargets, CliProgram } from "../types.ts";
+import { appConfigFileExists } from "~/config/file.ts";
+import type { CliConfigureTargets, CliProgram } from "~/core/types.ts";
+import { resolveCapabilities } from "~/runtime/capabilities.ts";
 import type { InstallPaths } from "./paths.ts";
 import {
   type InstallPlanMode,

package/src/{install → configure/artifacts}/target-skill.ts

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import type { CliProgram } from "../types.ts";
+import type { CliProgram } from "~/core/types.ts";
 import { displayInstallPath, type InstallPaths } from "./paths.ts";
 import { InstallTarget } from "./target-base.ts";
 import type {

package/src/{install → configure/artifacts}/target-types.ts

@@ -1,7 +1,7 @@
-import type { CliProgram } from "../types.ts";
+import type { CliProgram } from "~/core/types.ts";
 import type { InstallPaths } from "./paths.ts";
 
-export type { InstallTargetSpec, ResolvedInstallTarget } from "../types.ts";
+export type { InstallTargetSpec, ResolvedInstallTarget } from "~/core/types.ts";
 
 export type InstallPlanMode = "install-all" | "install-scoped" | "uninstall-all" | "uninstall-scoped" | "refresh";
 

package/src/{install → configure/artifacts}/targets/app.ts

@@ -1,7 +1,6 @@
-import type { CliProgram } from "../../types.ts";
-import { isExternallyManagedBinary } from "../binary-placement.ts";
-import type { InstallPaths } from "../paths.ts";
-import { InstallTarget } from "../target-base.ts";
+import { isExternallyManagedBinary } from "~/configure/artifacts/binary-placement.ts";
+import type { InstallPaths } from "~/configure/artifacts/paths.ts";
+import { InstallTarget } from "~/configure/artifacts/target-base.ts";
 import type {
   DetectedSnapshot,
   InstallAction,
@@ -9,7 +8,8 @@ import type {
   InstallStatus,
   TargetPlanContext,
   UninstallAction,
-} from "../target-types.ts";
+} from "~/configure/artifacts/target-types.ts";
+import type { CliProgram } from "~/core/types.ts";
 
 /** Reports app install location (Homebrew PATH or legacy ~/.local/bin). No self-install actions. */
 class AppInstallTarget extends InstallTarget {

package/src/{install → configure/artifacts}/targets/chatgpt-mcp.ts

@@ -1,5 +1,5 @@
-import { chatGptDesktopPresent, userHome } from "../paths.ts";
-import { McpJsonInstallTarget } from "../target-mcp-json.ts";
+import { chatGptDesktopPresent, userHome } from "~/configure/artifacts/paths.ts";
+import { McpJsonInstallTarget } from "~/configure/artifacts/target-mcp-json.ts";
 
 export const chatgptMcpTarget = new McpJsonInstallTarget({
   key: "chatgptMcp",

package/src/{install → configure/artifacts}/targets/claude-code-mcp.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { userHome } from "../paths.ts";
-import { McpJsonInstallTarget } from "../target-mcp-json.ts";
+import { userHome } from "~/configure/artifacts/paths.ts";
+import { McpJsonInstallTarget } from "~/configure/artifacts/target-mcp-json.ts";
 
 export const claudeCodeMcpTarget = new McpJsonInstallTarget({
   key: "claudeCodeMcp",

package/src/{install → configure/artifacts}/targets/claude-desktop-mcp.ts

@@ -1,5 +1,5 @@
-import { claudeDesktopPresent, userHome } from "../paths.ts";
-import { McpJsonInstallTarget } from "../target-mcp-json.ts";
+import { claudeDesktopPresent, userHome } from "~/configure/artifacts/paths.ts";
+import { McpJsonInstallTarget } from "~/configure/artifacts/target-mcp-json.ts";
 
 export const claudeDesktopMcpTarget = new McpJsonInstallTarget({
   key: "claudeDesktopMcp",

package/src/{install → configure/artifacts}/targets/claude-skill.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { userHome } from "../paths.ts";
-import { SkillInstallTarget } from "../target-skill.ts";
+import { userHome } from "~/configure/artifacts/paths.ts";
+import { SkillInstallTarget } from "~/configure/artifacts/target-skill.ts";
 
 export const claudeSkillTarget = new SkillInstallTarget({
   key: "claudeSkill",

package/src/{install → configure/artifacts}/targets/codex-mcp.ts

@@ -1,11 +1,11 @@
-import { codexOnPath } from "../mcp-codex.ts";
+import { codexOnPath } from "~/configure/artifacts/mcp-codex.ts";
 import {
   checkCodexMcpConflict,
   codexMcpHasServer,
   McpCliInstallTarget,
   mergeCodexMcpConfig,
   removeCodexMcpConfig,
-} from "../target-mcp-cli.ts";
+} from "~/configure/artifacts/target-mcp-cli.ts";
 
 export const codexMcpTarget = new McpCliInstallTarget({
   key: "codexMcp",

package/src/{install → configure/artifacts}/targets/codex-skill.ts

@@ -1,5 +1,5 @@
-import { codexOnPath } from "../mcp-codex.ts";
-import { SkillInstallTarget } from "../target-skill.ts";
+import { codexOnPath } from "~/configure/artifacts/mcp-codex.ts";
+import { SkillInstallTarget } from "~/configure/artifacts/target-skill.ts";
 
 export const codexSkillTarget = new SkillInstallTarget({
   key: "codexSkill",

package/src/{install → configure/artifacts}/targets/configure.ts

@@ -1,7 +1,6 @@
-import { appConfigInstalled, displayAppConfigPath, uninstallAppConfig } from "../../config/file.ts";
-import type { CliProgram, InstallAgentIntegration } from "../../types.ts";
-import type { InstallPaths } from "../paths.ts";
-import { InstallTarget } from "../target-base.ts";
+import { appConfigInstalled, displayAppConfigPath, uninstallAppConfig } from "~/config/file.ts";
+import type { InstallPaths } from "~/configure/artifacts/paths.ts";
+import { InstallTarget } from "~/configure/artifacts/target-base.ts";
 import type {
   DetectedSnapshot,
   InstallAction,
@@ -9,7 +8,8 @@ import type {
   InstallStatus,
   TargetPlanContext,
   UninstallAction,
-} from "../target-types.ts";
+} from "~/configure/artifacts/target-types.ts";
+import type { CliProgram, InstallAgentIntegration } from "~/core/types.ts";
 
 /** App config file (interactive configure / wizard). */
 class ConfigureInstallTarget extends InstallTarget {

package/src/{install → configure/artifacts}/targets/cursor-mcp.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { userHome } from "../paths.ts";
-import { McpJsonInstallTarget } from "../target-mcp-json.ts";
+import { userHome } from "~/configure/artifacts/paths.ts";
+import { McpJsonInstallTarget } from "~/configure/artifacts/target-mcp-json.ts";
 
 export const cursorMcpTarget = new McpJsonInstallTarget({
   key: "cursorMcp",

package/src/{install → configure/artifacts}/targets/cursor-skill.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { userHome } from "../paths.ts";
-import { SkillInstallTarget } from "../target-skill.ts";
+import { userHome } from "~/configure/artifacts/paths.ts";
+import { SkillInstallTarget } from "~/configure/artifacts/target-skill.ts";
 
 export const cursorSkillTarget = new SkillInstallTarget({
   key: "cursorSkill",

package/src/{install → configure/artifacts}/targets/index.ts

@@ -1,4 +1,4 @@
-import type { InstallTarget } from "../target-base.ts";
+import type { InstallTarget } from "~/configure/artifacts/target-base.ts";
 import { appTarget } from "./app.ts";
 import { chatgptMcpTarget } from "./chatgpt-mcp.ts";
 import { claudeCodeMcpTarget } from "./claude-code-mcp.ts";

package/src/{install → configure/artifacts}/targets/openclaw-mcp.ts

@@ -1,11 +1,11 @@
-import { openclawOnPath } from "../mcp-openclaw.ts";
+import { openclawOnPath } from "~/configure/artifacts/mcp-openclaw.ts";
 import {
   checkOpenclawMcpConflict,
   McpCliInstallTarget,
   mergeOpenclawMcpConfig,
   openclawMcpHasServer,
   removeOpenclawMcpConfig,
-} from "../target-mcp-cli.ts";
+} from "~/configure/artifacts/target-mcp-cli.ts";
 
 export const openclawMcpTarget = new McpCliInstallTarget({
   key: "openclawMcp",

package/src/{install → configure/artifacts}/targets/openclaw-skill.ts

@@ -1,8 +1,8 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { openclawOnPath } from "../mcp-openclaw.ts";
-import { userHome } from "../paths.ts";
-import { SkillInstallTarget } from "../target-skill.ts";
+import { openclawOnPath } from "~/configure/artifacts/mcp-openclaw.ts";
+import { userHome } from "~/configure/artifacts/paths.ts";
+import { SkillInstallTarget } from "~/configure/artifacts/target-skill.ts";
 
 export const openclawSkillTarget = new SkillInstallTarget({
   key: "openclawSkill",

package/src/{install → configure/artifacts}/targets/opencode-mcp.ts

@@ -1,4 +1,3 @@
-import type { CliProgram } from "../../types.ts";
 import {
   checkOpenCodeMcpConflict,
   detectOpenCodeMcpConfigPath,
@@ -6,9 +5,9 @@ import {
   mergeOpenCodeMcpConfig,
   opencodePresent,
   removeOpenCodeMcpConfig,
-} from "../mcp-opencode.ts";
-import { displayInstallPath, type InstallPaths, userHome } from "../paths.ts";
-import { InstallTarget } from "../target-base.ts";
+} from "~/configure/artifacts/mcp-opencode.ts";
+import { displayInstallPath, type InstallPaths, userHome } from "~/configure/artifacts/paths.ts";
+import { InstallTarget } from "~/configure/artifacts/target-base.ts";
 import type {
   DetectedSnapshot,
   InstallAction,
@@ -16,7 +15,8 @@ import type {
   InstallStatus,
   TargetPlanContext,
   UninstallAction,
-} from "../target-types.ts";
+} from "~/configure/artifacts/target-types.ts";
+import type { CliProgram } from "~/core/types.ts";
 
 function resolveConfigPath(paths: InstallPaths, home: string): string {
   return detectOpenCodeMcpConfigPath(home, paths.mcpName) ?? paths.opencodeMcpPath;

package/src/{install → configure/artifacts}/targets/opencode-skill.ts

@@ -1,6 +1,6 @@
-import { opencodePresent } from "../mcp-opencode.ts";
-import { userHome } from "../paths.ts";
-import { SkillInstallTarget } from "../target-skill.ts";
+import { opencodePresent } from "~/configure/artifacts/mcp-opencode.ts";
+import { userHome } from "~/configure/artifacts/paths.ts";
+import { SkillInstallTarget } from "~/configure/artifacts/target-skill.ts";
 
 export const opencodeSkillTarget = new SkillInstallTarget({
   key: "opencodeSkill",

package/src/{install → configure/artifacts}/targets.test.ts

@@ -3,7 +3,7 @@ Tests for install/targets module behavior.
 */
 
 import { describe, expect, test } from "bun:test";
-import type { CliProgram } from "../types.ts";
+import type { CliProgram } from "~/core/types.ts";
 import { normalizeInstallRawOpts } from "./normalize.ts";
 import { normalizeUninstallRawOpts } from "./normalize-uninstall.ts";
 import { resolveAgentIntegration, resolveEffectiveInstallTargets } from "./target-effective.ts";

package/src/{install → configure/artifacts}/uninstall.ts

@@ -1,5 +1,5 @@
 import { existsSync, rmSync } from "node:fs";
-import type { CliProgram } from "../types.ts";
+import type { CliProgram } from "~/core/types.ts";
 import type { InstallPaths } from "./paths.ts";
 import { buildUninstallPlanFromTargets } from "./target-plan-build.ts";
 import { skillTargetForUninstallSummary } from "./target-registry.ts";

package/src/configure/configure.test.ts

@@ -6,22 +6,22 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { appConfigFileExists } from "../config/file.ts";
+import { appConfigFileExists } from "~/config/file.ts";
 import {
   appConfigHasEntries,
   formatConfigureMutationSummary,
   parseConfigureOpts,
   validateConfigureOpts,
-} from "../configure/index.ts";
-import { Cli } from "../index.ts";
-import { detectInstalledArtifacts } from "../install/detect-installed.ts";
-import { parseInstallOpts } from "../install/opts.ts";
-import { resolveClaudeDesktopMcpPath, resolveInstallPaths } from "../install/paths.ts";
-import { buildInstallPlan, buildUpdatePlan } from "../install/plan.ts";
-import { installTargetForKey } from "../install/target-registry.ts";
-import { buildDetectedSnapshot, buildTargetPlanContext } from "../install/target-scope.ts";
-import { buildUninstallPlan } from "../install/uninstall.ts";
-import type { CliProgram } from "../types.ts";
+} from "~/configure";
+import type { CliProgram } from "~/core/types.ts";
+import { Cli } from "~/index";
+import { detectInstalledArtifacts } from "./artifacts/detect-installed.ts";
+import { parseInstallOpts } from "./artifacts/opts.ts";
+import { resolveClaudeDesktopMcpPath, resolveInstallPaths } from "./artifacts/paths.ts";
+import { buildInstallPlan, buildUpdatePlan } from "./artifacts/plan.ts";
+import { installTargetForKey } from "./artifacts/target-registry.ts";
+import { buildDetectedSnapshot, buildTargetPlanContext } from "./artifacts/target-scope.ts";
+import { buildUninstallPlan } from "./artifacts/uninstall.ts";
 
 const fixture: CliProgram = {
   key: "testapp",

package/src/configure/index.ts

@@ -2,22 +2,24 @@
 Interactive and automated `configure` command orchestration (agent artifacts and app config).
 */
 
-import { resolveCapabilities } from "../capabilities.ts";
-import { displayAppConfigPath, runConfigure } from "../config/bootstrap.ts";
-import { ensureAppConfigFile } from "../config/file.ts";
-import { resolveInstallPaths } from "../install/paths.ts";
-import { buildInstallPlan, buildUpdatePlan } from "../install/plan.ts";
+import { displayAppConfigPath, runConfigure } from "~/config/bootstrap.ts";
+import { ensureAppConfigFile } from "~/config/file.ts";
+import type { CliProgram } from "~/core/types.ts";
+import { resolveCapabilities } from "~/runtime/capabilities.ts";
+import { cliSkillInstall, skillTargetFromActionKind } from "~/skill/install.ts";
+import { resolveInstallPaths } from "./artifacts/paths.ts";
+import { buildInstallPlan, buildUpdatePlan } from "./artifacts/plan.ts";
 import {
   installErr,
   installInfo,
   installOut,
   printInstallStatus,
   writeInteractiveInstallIntro,
-} from "../install/status.ts";
-import { resolveEffectiveInstallTargets } from "../install/target-effective.ts";
-import { runTargetPreflight } from "../install/target-plan-build.ts";
-import { INSTALL_TARGETS, installTargetForKey } from "../install/target-registry.ts";
-import { buildDetectedSnapshot, buildTargetPlanContext } from "../install/target-scope.ts";
+} from "./artifacts/status.ts";
+import { resolveEffectiveInstallTargets } from "./artifacts/target-effective.ts";
+import { runTargetPreflight } from "./artifacts/target-plan-build.ts";
+import { INSTALL_TARGETS, installTargetForKey } from "./artifacts/target-registry.ts";
+import { buildDetectedSnapshot, buildTargetPlanContext } from "./artifacts/target-scope.ts";
 import type {
   CliInstallArtifactKey,
   InstallAction,
@@ -25,10 +27,8 @@ import type {
   InstallOpts,
   TargetPlanContext,
   UninstallAction,
-} from "../install/target-types.ts";
-import { buildUninstallPlan, skillDirFromUninstallSummary, uninstallSkillDir } from "../install/uninstall.ts";
-import { cliSkillInstall, skillTargetFromActionKind } from "../skill/install.ts";
-import type { CliProgram } from "../types.ts";
+} from "./artifacts/target-types.ts";
+import { buildUninstallPlan, skillDirFromUninstallSummary, uninstallSkillDir } from "./artifacts/uninstall.ts";
 import { artifactPromptLabel, promptTargetAction } from "./prompt.ts";
 
 /** True when interactive `configure` should auto-run the app config wizard. */

package/src/configure/prompt.ts

@@ -2,8 +2,8 @@
 TTY prompts for per-target install, skip, or uninstall during interactive `configure`.
 */
 
-import type { CliInstallArtifactKey } from "../install/target-types.ts";
-import { readPromptLine } from "../prompt.ts";
+import { readPromptLine } from "~/prompt.ts";
+import type { CliInstallArtifactKey } from "./artifacts/target-types.ts";
 
 /** Human-readable labels for each install artifact key in interactive prompts. */
 const LABELS: Record<CliInstallArtifactKey, string> = {

package/src/{context.ts → core/context.ts}

@@ -7,14 +7,22 @@ It keeps handlers small with a typed read API for flags, strings, numbers, and c
 parsed values.
 */
 
-import type { AnyAppConfigSnapshot } from "./config/context.ts";
-import { EmptyAppConfigSnapshot } from "./config/context.ts";
+import type { AnyAppConfigSnapshot } from "~/config/context.ts";
+import { EmptyAppConfigSnapshot } from "~/config/context.ts";
+import { strictParseDouble } from "~/utils.ts";
 import { parseCommaList, parseDate, parseDateTime, parseDurationMs } from "./formats.ts";
 import { loadLeafInputs, readJsonOptionValue } from "./leaf-inputs.ts";
 import { normalizeRespondOptions, writeRespondBodyToStdout } from "./respond.ts";
-import type { CliInvocation, CliLeaf, CliNode, CliProgram, CliRespondOptions } from "./types.ts";
+import type {
+  CliInvocation,
+  CliLeaf,
+  CliLocals,
+  CliNode,
+  CliProgram,
+  CliRespondOptions,
+  ServerRuntime,
+} from "./types.ts";
 import { isCliLeaf, isCliRouter } from "./types.ts";
-import { strictParseDouble } from "./utils.ts";
 
 /** Coerced leaf inputs keyed by option and positional names. */
 export type CliLeafInputs = Record<string, boolean | number | string | string[] | unknown | undefined>;
@@ -25,15 +33,21 @@ export type CliLeafInputs = Record<string, boolean | number | string | string[]
 export class CliContext {
   readonly appName: string;
   readonly commandPath: string[];
-  readonly args: string[];
+  args: string[];
   readonly program: CliProgram;
-  readonly opts: Record<string, string>;
+  opts: Record<string, string>;
   readonly invocation: CliInvocation;
   readonly appConfig: AnyAppConfigSnapshot;
   /** Original flat tool arguments for API/MCP invocations (when provided). */
   readonly toolArgs?: Record<string, unknown>;
+  /** Path parameter values from `:param` router descent. */
+  readonly pathParams: Record<string, string>;
   /** Pipable Json option values read from stdin before the handler (CLI only). */
   readonly preloadedJson: Record<string, unknown>;
+  /** Per-invocation bag; `beforeInvoke` may write. */
+  readonly locals: CliLocals;
+  /** Shared server state for HTTP/MCP invocations. */
+  runtime?: ServerRuntime;
 
   private response?: CliRespondOptions;
   private leafInputsCache?: CliLeafInputs;
@@ -49,6 +63,9 @@ export class CliContext {
     appConfig: AnyAppConfigSnapshot = new EmptyAppConfigSnapshot(program),
     toolArgs?: Record<string, unknown>,
     preloadedJson: Record<string, unknown> = {},
+    pathParams: Record<string, string> = {},
+    locals: CliLocals = {} as CliLocals,
+    runtime?: ServerRuntime,
   ) {
     this.appName = appName;
     this.commandPath = commandPath;
@@ -59,6 +76,9 @@ export class CliContext {
     this.appConfig = appConfig;
     this.toolArgs = toolArgs;
     this.preloadedJson = preloadedJson;
+    this.pathParams = pathParams;
+    this.locals = locals;
+    this.runtime = runtime;
   }
 
   /**
@@ -173,20 +193,6 @@ export class CliContext {
     return this.inputs as T;
   }
 
-  /**
-   * @deprecated Use {@link inputs} or {@link inputsAs}.
-   */
-  readLeafInputs(): CliLeafInputs {
-    return this.inputs;
-  }
-
-  /**
-   * @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs.
-   */
-  readLeafInputsAsync(): Promise<CliLeafInputs> {
-    return Promise.resolve(this.readLeafInputs());
-  }
-
   private _leafNode(): CliLeaf | undefined {
     let node: CliNode = this.program;
     for (const seg of this.commandPath) {

package/src/core/json-leaf.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, test } from "bun:test";
+import { Cli } from "~/index";
+import { ParseKind, parse } from "./parse.ts";
+import { CliOptionKind, type CliProgram, CliSchemaValidationError } from "./types.ts";
+import { cliValidateProgram } from "./validate.ts";
+
+const bodySchema = {
+  type: "object",
+  properties: {
+    format: { type: "string", enum: ["pdf", "html"] },
+    invoice: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  required: ["format", "invoice"],
+  additionalProperties: false,
+} as const;
+
+function jsonLeafProgram() {
+  return {
+    key: "json-leaf-test",
+    version: "1.0.0",
+    description: "json leaf tests",
+    commands: [
+      {
+        key: "render",
+        description: "Render from JSON body",
+        kind: "json",
+        inputSchema: bodySchema,
+        handler: (ctx) => ctx.inputsAs<{ format: string; invoice: { id: string } }>(),
+      },
+    ],
+  } satisfies CliProgram;
+}
+
+describe("kind: json leaf", () => {
+  test("validate requires inputSchema and forbids options/positionals", () => {
+    expect(() =>
+      cliValidateProgram({
+        key: "bad",
+        version: "1",
+        description: "bad",
+        commands: [{ key: "x", description: "x", kind: "json", handler: () => {} }],
+      }),
+    ).toThrow(CliSchemaValidationError);
+
+    expect(() =>
+      cliValidateProgram({
+        key: "bad",
+        version: "1",
+        description: "bad",
+        commands: [
+          {
+            key: "x",
+            description: "x",
+            kind: "json",
+            inputSchema: bodySchema,
+            options: [{ name: "f", description: "f", kind: CliOptionKind.String }],
+            handler: () => {},
+          },
+        ],
+      }),
+    ).toThrow(CliSchemaValidationError);
+
+    expect(() =>
+      cliValidateProgram({
+        key: "bad",
+        version: "1",
+        description: "bad",
+        commands: [
+          {
+            key: "x",
+            description: "x",
+            kind: "json",
+            inputSchema: bodySchema,
+            positionals: [{ name: "file", description: "file", kind: CliOptionKind.String }],
+            handler: () => {},
+          },
+        ],
+      }),
+    ).toThrow(CliSchemaValidationError);
+  });
+
+  test("parse rejects CLI flags on json leaf", () => {
+    const root = jsonLeafProgram();
+    const pr = parse(root, ["render", "--format", "pdf"]);
+    expect(pr.kind).toBe(ParseKind.Error);
+    expect(pr.errorMsg).toContain("JSON commands do not accept options");
+  });
+
+  test("parse accepts JSON positional", () => {
+    const root = jsonLeafProgram();
+    const pr = parse(root, ["render", '{"format":"pdf","invoice":{"id":"1"}}']);
+    expect(pr.kind).toBe(ParseKind.Ok);
+    expect(pr.args).toEqual(['{"format":"pdf","invoice":{"id":"1"}}']);
+  });
+
+  test("invoke reads body from toolArgs", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render"], {
+      invocation: "http",
+      toolArgs: { format: "pdf", invoice: { id: "INV-1" } },
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ format: "pdf", invoice: { id: "INV-1" } });
+  });
+
+  test("invoke reads body from JSON positional argv", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render", '{"format":"html","invoice":{"id":"2"}}'], {
+      invocation: "mcp",
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ format: "html", invoice: { id: "2" } });
+  });
+
+  test("invoke errors when body missing", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render"], { invocation: "http" });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toContain("Missing JSON input");
+  });
+
+  test("invoke validates inputSchema before handler", async () => {
+    let called = false;
+    const base = jsonLeafProgram();
+    const program = {
+      ...base,
+      commands: [
+        {
+          ...base.commands[0],
+          handler: () => {
+            called = true;
+          },
+        },
+      ],
+    } satisfies CliProgram;
+    const cli = new Cli(program);
+    const result = await cli.invoke(["render"], {
+      invocation: "http",
+      toolArgs: { format: "pdf", invoice: { id: 123 } },
+    });
+    expect(result.kind).toBe("error");
+    expect(called).toBe(false);
+  });
+
+  test("non-object JSON body returns error", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render", '"not-an-object"'], { invocation: "cli" });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toContain("JSON input must be a JSON object");
+  });
+});