stitchkit 0.110.4 → 0.110.5

package/CHANGELOG.md

@@ -15,6 +15,12 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.110.5] - 2026-10-15
+
+### Added
+
+- `stitchkit/cli`: `--field:=JSON` assigns a whole JSON value, including explicit `null` for nullable fields, through the existing schema-driven parser. Ordinary `--field null` remains the string `"null"`; optional omission stays absent. Native/discovered help advertises the syntax; malformed JSON and conflicting assignments refuse before dispatch.
+
 ## [0.110.4] - 2026-10-15
 
 ### Fixed

package/dist/entrypoints/cli.js

@@ -16,7 +16,7 @@ import {
   renderCliView2,
   pollUntilDone2,
   createCli2
-} from "../index-2tazbwhv.js";
+} from "../index-n7hrpngg.js";
 import"../index-fynr93w4.js";
 import"../index-ct75c3at.js";
 import"../index-q6crhe1n.js";

package/dist/entrypoints/tools.js

@@ -74,7 +74,7 @@ import {
   WaitTimeoutError,
   runWaitOperation,
   createCli2
-} from "../index-2tazbwhv.js";
+} from "../index-n7hrpngg.js";
 import {
   ManagedFilePathSchema2,
   ManagedFileRefSchema2

package/dist/{index-2tazbwhv.js → index-n7hrpngg.js}

@@ -830,88 +830,28 @@ function routeCliArgv2(argv, defaultCommand) {
 // src/tools/cli/args.ts
 import { z as z2 } from "zod";
 
-// src/tools/cli/args-view.ts
-function resolveCliView(flags, ascending) {
-  if (flags.size === 0) {
-    if (ascending) {
-      throw new CliArgumentError2("--ascending orders a record view; pass --sort with it");
-    }
-    return;
-  }
-  const countBy = flags.get("count-by");
-  const sum = flags.get("sum");
-  const table = flags.get("table");
-  const by = flags.get("by");
-  const rawTop = flags.get("top");
-  const named = [
-    ["--count-by", countBy],
-    ["--sum", sum]
-  ].filter(([, value]) => value !== undefined);
-  if (named.length > 1) {
-    throw new CliArgumentError2(`${named.map(([flag]) => flag).join(" and ")} ask for different shapes — pass one`);
-  }
-  let top;
-  if (rawTop !== undefined) {
-    top = Number(rawTop);
-    if (!Number.isInteger(top) || top <= 0) {
-      throw new CliArgumentError2("--top must be a positive whole number");
-    }
-  }
-  const sort = flags.get("sort");
-  if (table !== undefined || sort !== undefined) {
-    if (countBy !== undefined || sum !== undefined) {
-      throw new CliArgumentError2(`${table !== undefined ? "--table" : "--sort"} lists records; --count-by and --sum aggregate them — pass one`);
-    }
-    if (by !== undefined) {
-      throw new CliArgumentError2("--by groups a view; a record view orders with --sort");
-    }
-    if (top !== undefined && sort === undefined) {
-      throw new CliArgumentError2("--top needs --sort here: unordered records have no n largest");
-    }
-    let fields;
-    if (table !== undefined) {
-      fields = table.split(",").map((field) => field.trim()).filter(Boolean);
-      if (fields.length === 0)
-        throw new CliArgumentError2("--table needs at least one field");
-    }
-    return {
-      kind: "records",
-      ...sort !== undefined && { sort },
-      ...ascending && { ascending },
-      ...top !== undefined && { top },
-      ...fields && { table: fields }
-    };
-  }
-  if (ascending) {
-    throw new CliArgumentError2("--ascending orders a record view; pass --sort with it");
-  }
-  if (sum !== undefined) {
-    if (top !== undefined && by === undefined) {
-      throw new CliArgumentError2("--top needs --by: a single sum has nothing to rank");
-    }
-    return {
-      kind: "sum",
-      field: sum,
-      ...by !== undefined && { by },
-      ...top !== undefined && { top }
-    };
-  }
-  if (countBy !== undefined) {
-    if (by !== undefined) {
-      throw new CliArgumentError2("--count-by already names the grouping field; drop --by");
-    }
-    return { kind: "count", field: countBy, ...top !== undefined && { top } };
-  }
-  if (by !== undefined) {
-    if (top === undefined) {
-      throw new CliArgumentError2("--by groups a view; pass --count-by, --sum or --top with it");
-    }
-    return { kind: "count", field: by, top };
+// src/tools/cli/args-json.ts
+function cliFieldOption(option, fields) {
+  const json = option.inline && option.name.endsWith(":") && !fields.has(option.name);
+  const name = json ? option.name.slice(0, -1) : option.name;
+  return { name, json };
+}
+function appendCliFieldValue(raw, jsonFields, name, value, info, json) {
+  appendCliOptionValue(raw, name, value, json || jsonFields.has(name) ? { kind: "other" } : info);
+  if (json)
+    jsonFields.add(name);
+}
+function coerceCliFieldValue(info, values, label, json) {
+  if (!json)
+    return coerceField(info, values, label);
+  try {
+    return safeJsonParse(values[0] ?? "");
+  } catch (cause) {
+    throw new CliArgumentError2(`${label} expects valid JSON`, { cause });
   }
-  throw new CliArgumentError2("--top needs --sort, --by, --count-by or --sum to rank");
 }
 
-// src/tools/cli/args.ts
+// src/tools/cli/args-tokens.ts
 function readCliTokens(argv, fields, fieldFor, config) {
   const options = {
     json: false,
@@ -921,13 +861,14 @@ function readCliTokens(argv, fields, fieldFor, config) {
     help: false
   };
   const flags = new Map;
+  const jsonFields = new Set;
   const literalBooleanFlags = new Set;
   const frameworkFlags = new Map;
   const viewFlags = new Map;
   let ascending = false;
   const positionals = [];
-  const pushFlag = (name, value) => {
-    appendCliOptionValue(flags, name, value, fieldFor(name));
+  const pushFlag = (name, value, json = false) => {
+    appendCliFieldValue(flags, jsonFields, name, value, fieldFor(name), json);
   };
   let optionsEnded = false;
   for (let i = 0;i < argv.length; i++) {
@@ -980,10 +921,13 @@ function readCliTokens(argv, fields, fieldFor, config) {
     const option = classifyLongOptionToken(tok);
     if (!option)
       throw new CliArgumentError2(`Unknown option "${tok}"`);
-    const { name } = option;
+    const { name, json } = cliFieldOption(option, fields);
     let { value } = option;
     if (name.length === 0)
       throw new CliArgumentError2("Invalid empty option name");
+    if (json && RESERVED_CLI_OPTIONS.has(name)) {
+      throw new CliArgumentError2(`--${name} is a framework option and does not accept :=JSON`);
+    }
     if (option.globalKind === "boolean") {
       const separate = value === undefined ? separateBoolValue(argv[i + 1]) : undefined;
       if (separate !== undefined)
@@ -1061,12 +1005,103 @@ function readCliTokens(argv, fields, fieldFor, config) {
         throw new CliArgumentError2(`--${name} requires a value`);
       }
     }
-    pushFlag(name, value);
+    pushFlag(name, value, json);
   }
-  return { options, flags, literalBooleanFlags, viewFlags, ascending, positionals };
+  return {
+    options,
+    flags,
+    jsonFields,
+    literalBooleanFlags,
+    viewFlags,
+    ascending,
+    positionals
+  };
 }
+
+// src/tools/cli/args-view.ts
+function resolveCliView(flags, ascending) {
+  if (flags.size === 0) {
+    if (ascending) {
+      throw new CliArgumentError2("--ascending orders a record view; pass --sort with it");
+    }
+    return;
+  }
+  const countBy = flags.get("count-by");
+  const sum = flags.get("sum");
+  const table = flags.get("table");
+  const by = flags.get("by");
+  const rawTop = flags.get("top");
+  const named = [
+    ["--count-by", countBy],
+    ["--sum", sum]
+  ].filter(([, value]) => value !== undefined);
+  if (named.length > 1) {
+    throw new CliArgumentError2(`${named.map(([flag]) => flag).join(" and ")} ask for different shapes — pass one`);
+  }
+  let top;
+  if (rawTop !== undefined) {
+    top = Number(rawTop);
+    if (!Number.isInteger(top) || top <= 0) {
+      throw new CliArgumentError2("--top must be a positive whole number");
+    }
+  }
+  const sort = flags.get("sort");
+  if (table !== undefined || sort !== undefined) {
+    if (countBy !== undefined || sum !== undefined) {
+      throw new CliArgumentError2(`${table !== undefined ? "--table" : "--sort"} lists records; --count-by and --sum aggregate them — pass one`);
+    }
+    if (by !== undefined) {
+      throw new CliArgumentError2("--by groups a view; a record view orders with --sort");
+    }
+    if (top !== undefined && sort === undefined) {
+      throw new CliArgumentError2("--top needs --sort here: unordered records have no n largest");
+    }
+    let fields;
+    if (table !== undefined) {
+      fields = table.split(",").map((field) => field.trim()).filter(Boolean);
+      if (fields.length === 0)
+        throw new CliArgumentError2("--table needs at least one field");
+    }
+    return {
+      kind: "records",
+      ...sort !== undefined && { sort },
+      ...ascending && { ascending },
+      ...top !== undefined && { top },
+      ...fields && { table: fields }
+    };
+  }
+  if (ascending) {
+    throw new CliArgumentError2("--ascending orders a record view; pass --sort with it");
+  }
+  if (sum !== undefined) {
+    if (top !== undefined && by === undefined) {
+      throw new CliArgumentError2("--top needs --by: a single sum has nothing to rank");
+    }
+    return {
+      kind: "sum",
+      field: sum,
+      ...by !== undefined && { by },
+      ...top !== undefined && { top }
+    };
+  }
+  if (countBy !== undefined) {
+    if (by !== undefined) {
+      throw new CliArgumentError2("--count-by already names the grouping field; drop --by");
+    }
+    return { kind: "count", field: countBy, ...top !== undefined && { top } };
+  }
+  if (by !== undefined) {
+    if (top === undefined) {
+      throw new CliArgumentError2("--by groups a view; pass --count-by, --sum or --top with it");
+    }
+    return { kind: "count", field: by, top };
+  }
+  throw new CliArgumentError2("--top needs --sort, --by, --count-by or --sum to rank");
+}
+
+// src/tools/cli/args.ts
 function buildToolArgs(tokens, fields, fieldFor, declaredPositionals, allowUnknown) {
-  const { flags, literalBooleanFlags, positionals } = tokens;
+  const { flags, jsonFields, literalBooleanFlags, positionals } = tokens;
   const toolArgs = {};
   const fillable = declaredPositionals === undefined ? [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name) : [...declaredPositionals];
   const variadicTail = declaredPositionals !== undefined && fields.get(fillable[fillable.length - 1] ?? "")?.kind === "array" ? fillable[fillable.length - 1] : undefined;
@@ -1105,16 +1140,23 @@ function buildToolArgs(tokens, fields, fieldFor, declaredPositionals, allowUnkno
       throw new CliArgumentError2(`--${root} conflicts with --${dotted} — pass one form, not both`);
     }
   }
+  for (const key of jsonFields) {
+    for (const other of flags.keys()) {
+      if (other.startsWith(`${key}.`) || key.startsWith(`${other}.`)) {
+        throw new CliArgumentError2(`--${key} conflicts with --${other} — pass one form, not both`);
+      }
+    }
+  }
   for (const [key, values] of flags) {
     const info = fieldFor(key);
     const exactLiteralBoolean = literalBooleanFlags.has(key) && fields.has(key);
     if (key.includes(".") && !exactLiteralBoolean) {
       const root = key.split(".")[0] ?? key;
-      const value = info === undefined && allowUnknown && !fields.has(root) ? looseCoerce(values[0] ?? "") : coerceField(info, values, `--${key}`);
+      const value = !jsonFields.has(key) && info === undefined && allowUnknown && !fields.has(root) ? looseCoerce(values[0] ?? "") : coerceCliFieldValue(info, values, `--${key}`, jsonFields.has(key));
       setNested(toolArgs, key.split("."), value);
       continue;
     }
-    toolArgs[key] = coerceField(info, values, `--${key}`);
+    toolArgs[key] = coerceCliFieldValue(info, values, `--${key}`, jsonFields.has(key));
   }
   return toolArgs;
 }
@@ -1146,6 +1188,7 @@ function extractCliGlobalOptions2(argv, schema) {
   const fields = describeSchemaFields(schema);
   const rest = [];
   const raw = new Map;
+  const jsonFields = new Set;
   let ended = false;
   for (let i = 0;i < argv.length; i++) {
     const token = argv[i];
@@ -1154,8 +1197,9 @@ function extractCliGlobalOptions2(argv, schema) {
     if (!ended && token === "--")
       ended = true;
     const option = ended ? undefined : classifyLongOptionToken(token);
-    const info = option && option.globalKind === undefined ? fields.get(option.name) : undefined;
-    if (!option || !info) {
+    const field = option ? cliFieldOption(option, fields) : undefined;
+    const info = field && option?.globalKind === undefined ? fields.get(field.name) : undefined;
+    if (!option || !field || !info) {
       rest.push(token);
       continue;
     }
@@ -1174,11 +1218,11 @@ function extractCliGlobalOptions2(argv, schema) {
         throw new CliArgumentError2(`--${option.name} requires a value`);
       }
     }
-    appendCliOptionValue(raw, option.name, value, info);
+    appendCliFieldValue(raw, jsonFields, field.name, value, info, field.json);
   }
   const args = {};
   for (const [name, values] of raw) {
-    args[name] = coerceField(fields.get(name), values, `--${name}`);
+    args[name] = coerceCliFieldValue(fields.get(name), values, `--${name}`, jsonFields.has(name));
   }
   let coerced;
   try {
@@ -1664,6 +1708,20 @@ function constraintLabel(schema) {
 function fieldTypeLabel(schema) {
   return `<${typeLabel(schema)}>${constraintLabel(schema)}`;
 }
+function nullableField(schema) {
+  if (schema.type === "null")
+    return true;
+  if (Array.isArray(schema.type) && schema.type.includes("null"))
+    return true;
+  return Array.isArray(schema.anyOf) && schema.anyOf.some((member) => isRecord(member) && nullableField(member));
+}
+function jsonValueHelp(fields) {
+  const example = fields.find((field) => nullableField(field.schema))?.name;
+  return [
+    "Assign a whole JSON value with --field:=JSON; the declared schema still validates it.",
+    ...example === undefined ? [] : [`JSON null: --${example}:=null. The literal string stays --${example} null.`]
+  ];
+}
 function padRight(text, width) {
   return text.length >= width ? text : text + " ".repeat(width - text.length);
 }
@@ -1717,6 +1775,7 @@ function renderTopHelp(input) {
   for (const [flag, desc] of GLOBAL_OPTIONS)
     lines.push(`  ${padRight(flag, optWidth)}  ${desc}`);
   lines.push(...applicationOptionLines(input.applicationOptions));
+  lines.push("", ...jsonValueHelp(input.applicationOptions));
   lines.push("", `Run "${name} <command> --help" for command-specific flags.`);
   return `${lines.join(`
 `)}
@@ -1763,7 +1822,7 @@ function renderCommandHelp(name, command, descriptor, applicationOptions = []) {
     if (flag !== undefined) {
       lines.push("", `A boolean flag is on alone or takes true/false: --${flag}, --${flag} false, --no-${flag}`);
     }
-    lines.push("");
+    lines.push("", ...jsonValueHelp(fields), "");
   }
   const applicationLines = applicationOptionLines(applicationOptions);
   if (applicationLines.length > 0)

package/dist/tools/cli/args-json.d.ts

@@ -0,0 +1,12 @@
+import { type FieldInfo } from './args-fields.js';
+import type { CliLongOptionToken } from './args-route.js';
+/** An inline := assigns a whole JSON value; an exact declared colon name stays literal. */
+export declare function cliFieldOption(option: CliLongOptionToken, fields: ReadonlyMap<string, FieldInfo>): {
+    name: string;
+    json: boolean;
+};
+/** Whole JSON assignments cannot accumulate or mix with repeated element flags. */
+export declare function appendCliFieldValue(raw: Map<string, string[]>, jsonFields: Set<string>, name: string, value: string, info: FieldInfo | undefined, json: boolean): void;
+/** JSON assigns a value without scalar coercion; the command schema still validates it. */
+export declare function coerceCliFieldValue(info: FieldInfo | undefined, values: string[], label: string, json: boolean): unknown;
+//# sourceMappingURL=args-json.d.ts.map

package/dist/tools/cli/args-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args-json.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-json.ts"],"names":[],"mappings":"AACA,OAAO,EAAqC,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvD,2FAA2F;AAC3F,wBAAgB,cAAc,CAC5B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GACrC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAIjC;AAED,mFAAmF;AACnF,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAC1B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,IAAI,EAAE,OAAO,GACZ,IAAI,CAQN;AAED,2FAA2F;AAC3F,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,OAAO,GACZ,OAAO,CAOT"}

package/dist/tools/cli/args-tokens.d.ts

@@ -0,0 +1,27 @@
+import type { CliRunOptions } from './args.js';
+import { type describeSchemaFields, type FieldInfo } from './args-fields.js';
+type CliConfigForParse = {
+    allowUnknown?: boolean;
+    optionAliases?: ReadonlyMap<string, string>;
+};
+type FieldResolver = (name: string) => FieldInfo | undefined;
+/** One invocation's argv, sorted into what each token is for. */
+export interface CliTokens {
+    options: CliRunOptions;
+    /** Raw values per flag, in order; only an array field may have several. */
+    flags: Map<string, string[]>;
+    jsonFields: Set<string>;
+    /** Boolean presence and aliases name exact fields, even when the name has a dot. */
+    literalBooleanFlags: Set<string>;
+    viewFlags: Map<string, string>;
+    ascending: boolean;
+    positionals: string[];
+}
+/**
+ * Phase one: tokenise. Every refusal about the SHAPE of the command line —
+ * an unknown option, a missing value, a prototype-polluting name, a repeated
+ * non-array flag — happens here, before its raw multiplicity can be lost.
+ */
+export declare function readCliTokens(argv: readonly string[], fields: ReturnType<typeof describeSchemaFields>, fieldFor: FieldResolver, config: CliConfigForParse): CliTokens;
+export {};
+//# sourceMappingURL=args-tokens.d.ts.map

package/dist/tools/cli/args-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args-tokens.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-tokens.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,SAAS,EAGf,MAAM,eAAe,CAAC;AAWvB,KAAK,iBAAiB,GAAG;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C,CAAC;AACF,KAAK,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAAC;AAE7D,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,aAAa,CAAC;IACvB,2EAA2E;IAC3E,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,oFAAoF;IACpF,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,EAC/C,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,iBAAiB,GACxB,SAAS,CAqKX"}

package/dist/tools/cli/args.d.ts

@@ -44,6 +44,10 @@ export interface ParsedCliArgs {
     /** The CLI-behaviour flags. */
     options: CliRunOptions;
 }
+/**
+ * Parse one command's argv against its schema: lexical/coerced flags, explicit
+ * `--field:=JSON`, dotted paths, boolean presence and declared positionals.
+ */
 export declare function parseCliArgs(argv: string[], schema: z.ZodType | undefined, config?: {
     allowUnknown?: boolean;
     knownFields?: readonly string[];

package/dist/tools/cli/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoBxB,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAGjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAiSD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAsBf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAkDvB"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAMjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AA6GD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAsBf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAyDvB"}

package/dist/tools/cli/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/help.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AA+GvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CASrC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAqCT;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,EAClC,kBAAkB,GAAE,SAAS,eAAe,EAAO,GAClD,MAAM,CA6DR"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/help.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAkIvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CASrC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAsCT;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,EAClC,kBAAkB,GAAE,SAAS,eAAe,EAAO,GAClD,MAAM,CA6DR"}

package/llms/cli.2.txt

@@ -183,11 +183,16 @@ the code (so `exitCodes` can map it instead of every remote failure exiting `1`)
 the message the operator needs, and the error's own class — a plain `Error` is
 an *unexpected* error to the runner, which would print a code frame of the framework
 bundle before the JSON failure and scrub it to `INTERNAL_SERVER_ERROR`.
-A structured `{ error, details }` body is relayed as the contract error it
+A `tools/call` response with `isError: true` and a structured `{ error, details }` body is relayed as the contract error it
 is, on every transport; anything else fails as `UPSTREAM_TOOL_ERROR` carrying
 what the server did send. Not `INTERNAL_SERVER_ERROR`, because nothing of ours
 broke.
 
+The CLI writes this refusal to stderr, leaves stdout empty and exits with the
+mapped nonzero error code (`1` for an unmapped code). A successful response may
+contain an ordinary field named `error`; its payload alone does not establish a
+tool failure.
+
 **On the CLI a discovered command prints the answer, not the envelope.**
 `tools/call` returns `{ content: [...], structuredContent? }`, and an agent mount
 needs exactly that — the parts are what a model is shown. The CLI is different in
@@ -266,7 +271,7 @@ SDK nor the `ai` peer.
 |--------|------|---------|
 | `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
-| `parseCliArgs` | function | argv → typed tool args against a schema (advanced) |
+| `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical (advanced) |
 | `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |
 | `extractCliGlobalOptions` | function | lift the application's own global options out of argv before routing (advanced) |
 | `coerceJsonArgs` | function | the second half of `parseCliArgs` — parse array/object values a consumer sends itself, including discovered MCP object guards restored from JSON Schema, without the `stitchkit/tools` barrel |

package/llms/cli.txt

@@ -247,6 +247,23 @@ string, the schema says what it should be:
 | `z.record(z.string(), z.unknown())` | `--data '{"code":"007"}'` or `--data.code=007` → `"007"` |
 | `.optional()` / `.default()` | not required                           |
 
+Use the inline `:=` form to assign a whole JSON value without scalar coercion:
+
+```bash
+myapp upsert --productId:=null --count:=null
+myapp upsert --productId null            # the literal string "null"
+myapp upsert --productId:='"null"'        # the same string, written as JSON
+```
+
+`null` is accepted only when the unchanged command schema permits it. Omitting an
+optional field leaves it absent; it does not imply `null`. The same syntax works
+for application global options and dotted leaves (`--settings.note:=null`). A
+JSON assignment supplies the whole field, so an array uses one assignment such as
+`--tags:='["a","b"]'`; mixing it with repeated element flags or another assignment
+is refused. Invalid JSON is a usage error before the handler runs. Framework
+options such as `--json` retain their existing grammar. An exact declared field
+name ending in `:` retains its existing inline spelling.
+
 Primitive literals use the same coercion through optional, nullable and default wrappers and as
 array elements. A literal set whose members have different primitive types stays lexical because
 argv has no type tag: for `z.literal([7, '007'])`, `--value 007` remains the string `"007"` rather

package/llms-full.txt

@@ -9773,6 +9773,23 @@ string, the schema says what it should be:
 | `z.record(z.string(), z.unknown())` | `--data '{"code":"007"}'` or `--data.code=007` → `"007"` |
 | `.optional()` / `.default()` | not required                           |
 
+Use the inline `:=` form to assign a whole JSON value without scalar coercion:
+
+```bash
+myapp upsert --productId:=null --count:=null
+myapp upsert --productId null            # the literal string "null"
+myapp upsert --productId:='"null"'        # the same string, written as JSON
+```
+
+`null` is accepted only when the unchanged command schema permits it. Omitting an
+optional field leaves it absent; it does not imply `null`. The same syntax works
+for application global options and dotted leaves (`--settings.note:=null`). A
+JSON assignment supplies the whole field, so an array uses one assignment such as
+`--tags:='["a","b"]'`; mixing it with repeated element flags or another assignment
+is refused. Invalid JSON is a usage error before the handler runs. Framework
+options such as `--json` retain their existing grammar. An exact declared field
+name ending in `:` retains its existing inline spelling.
+
 Primitive literals use the same coercion through optional, nullable and default wrappers and as
 array elements. A literal set whose members have different primitive types stays lexical because
 argv has no type tag: for `z.literal([7, '007'])`, `--value 007` remains the string `"007"` rather
@@ -10635,11 +10652,16 @@ the code (so `exitCodes` can map it instead of every remote failure exiting `1`)
 the message the operator needs, and the error's own class — a plain `Error` is
 an *unexpected* error to the runner, which would print a code frame of the framework
 bundle before the JSON failure and scrub it to `INTERNAL_SERVER_ERROR`.
-A structured `{ error, details }` body is relayed as the contract error it
+A `tools/call` response with `isError: true` and a structured `{ error, details }` body is relayed as the contract error it
 is, on every transport; anything else fails as `UPSTREAM_TOOL_ERROR` carrying
 what the server did send. Not `INTERNAL_SERVER_ERROR`, because nothing of ours
 broke.
 
+The CLI writes this refusal to stderr, leaves stdout empty and exits with the
+mapped nonzero error code (`1` for an unmapped code). A successful response may
+contain an ordinary field named `error`; its payload alone does not establish a
+tool failure.
+
 **On the CLI a discovered command prints the answer, not the envelope.**
 `tools/call` returns `{ content: [...], structuredContent? }`, and an agent mount
 needs exactly that — the parts are what a model is shown. The CLI is different in
@@ -23158,7 +23180,7 @@ SDK nor the `ai` peer.
 |--------|------|---------|
 | `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
-| `parseCliArgs` | function | argv → typed tool args against a schema (advanced) |
+| `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical (advanced) |
 | `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |
 | `extractCliGlobalOptions` | function | lift the application's own global options out of argv before routing (advanced) |
 | `coerceJsonArgs` | function | the second half of `parseCliArgs` — parse array/object values a consumer sends itself, including discovered MCP object guards restored from JSON Schema, without the `stitchkit/tools` barrel |

package/llms.txt

@@ -18,7 +18,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.7 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 43.8 KB → [llms/cli.2.txt](llms/cli.2.txt) 20.2 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 44.6 KB → [llms/cli.2.txt](llms/cli.2.txt) 20.6 KB
 - **stitchkit/cli/publish**: [llms/cli-publish.txt](llms/cli-publish.txt) 1.5 KB
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.110.4",
+  "version": "0.110.5",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",