stitchkit 0.110.4 → 0.110.6

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/process/group-diagnostics.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+declare const ObservationSchema: z.ZodObject<{
+    failure: z.ZodEnum<{
+        deadline: "deadline";
+        observation: "observation";
+    }>;
+    groupId: z.ZodNumber;
+    observations: z.ZodNumber;
+    lastStates: z.ZodArray<z.ZodString>;
+    elapsedMs: z.ZodNumber;
+}, z.core.$strip>;
+type Observation = z.infer<typeof ObservationSchema>;
+/** Only this internal error carries process-state diagnostics safe to promote. */
+export declare class GroupSettlementError extends Error {
+    constructor(message: string, observation: Observation, cause?: unknown);
+}
+/** Bounded cause traversal; arbitrary caller messages never become cleanup diagnostics. */
+export declare function groupSettlementDiagnostics(cause: unknown): Observation[];
+export {};
+//# sourceMappingURL=group-diagnostics.d.ts.map

package/dist/process/group-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-diagnostics.d.ts","sourceRoot":"","sources":["../../src/process/group-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,iBAAiB;;;;;;;;;iBAMrB,CAAC;AACH,KAAK,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAGrD,kFAAkF;AAClF,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,GAAE,OAAqB,EAKlF;CACF;AAQD,2FAA2F;AAC3F,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,EAAE,CA+BxE"}

package/dist/process/group-settlement.d.ts

@@ -1,5 +1,5 @@
 /** `killpg(..., 0)` also sees Linux zombies; only live members can still perform work. */
 export declare function hasLiveGroupMember(table: string, group: number): boolean;
 /** A delivered SIGKILL is asynchronous; do not report cleanup until every group member is dead. */
-export declare function waitForProcessGroupExit(pid: number | undefined, deadline: number): Promise<void>;
+export declare function waitForProcessGroupExit(pid: number | undefined, deadline: number, killLiveMembers?: () => Promise<boolean>): Promise<void>;
 //# sourceMappingURL=group-settlement.d.ts.map

package/dist/process/group-settlement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group-settlement.d.ts","sourceRoot":"","sources":["../../src/process/group-settlement.ts"],"names":[],"mappings":"AAIA,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQxE;AAmBD,mGAAmG;AACnG,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA0Bf"}
+{"version":3,"file":"group-settlement.d.ts","sourceRoot":"","sources":["../../src/process/group-settlement.ts"],"names":[],"mappings":"AAKA,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQxE;AAgBD,mGAAmG;AACnG,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC,CAmDf"}

package/dist/process/group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/process/group.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAIpF,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAYpE,MAAM;IACN,MAAM;EAIT;AAeD,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CASpF;AAsCD,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB/E;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,gBAAgB,GAAG;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAC/E,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,6BAA6B,CAAC;IACtC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CAyBnB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAItE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAMxF"}
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/process/group.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAKpF,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAYpE,MAAM;IACN,MAAM;EAIT;AAeD,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CASpF;AAyCD,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB/E;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,gBAAgB,GAAG;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAC/E,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,6BAA6B,CAAC;IACtC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CAyBnB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAQtE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAMxF"}

package/dist/server/bun.d.ts

@@ -1,3 +1,4 @@
+import { type ProxyOriginConfig } from './proxy-origin.js';
 import { type ManagedServerHandle } from './shutdown.js';
 import type { SocketIOServerLifecycle } from './socket-io.js';
 import type { FetchComposition, FetchHandler, HandlerConfig, RawRoute, RawRouteContext } from './types.js';
@@ -26,6 +27,14 @@ export type UnixListenConfig = string | {
 };
 /** Bun-specific server config layered over the Fetch-clean handler config. */
 export interface BunServerConfig extends BunHandlerConfig, BunFetchComposition {
+    /**
+     * Restore the external scheme behind one trusted TCP ingress, before composition.
+     * The ingress must overwrite Host and X-Forwarded-Proto and remove Forwarded,
+     * X-Forwarded-Host and X-Forwarded-Port. Trusted requests require exactly one
+     * `http` or `https` proto; malformed/conflicting headers receive 400.
+     * Host/tenant authorization remains application-owned. Independent of trustProxy.
+     */
+    proxyOrigin?: ProxyOriginConfig;
     port?: number;
     hostname?: string;
     /**

package/dist/server/bun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/server/bun.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC9C,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AACtD,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAExD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1D,KAAK,qBAAqB,GAAG,eAAe,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAChF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,mBAAmB;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,iGAAiG;IACjG,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;AA+F7D,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAgMrE"}
+{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/server/bun.ts"],"names":[],"mappings":"AAGA,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC9C,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AACtD,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAExD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1D,KAAK,qBAAqB,GAAG,eAAe,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAChF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,mBAAmB;IAC5E;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,iGAAiG;IACjG,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;AA+F7D,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAqMrE"}

package/dist/server/proxy-origin.d.ts

@@ -0,0 +1,12 @@
+import type { BunServer } from './bun.js';
+/** One TCP ingress that overwrites Host/proto and strips competing URL headers. */
+export interface ProxyOriginConfig {
+    /** Match the real socket peer, never a forwarded client IP. */
+    trustedPeer: (socketIp: string) => boolean;
+}
+/** Bun associates requestIP, timeout and upgrade with the original native request. */
+export declare function createProxyOrigin(policy: ProxyOriginConfig): {
+    bind(server: BunServer): void;
+    normalize(request: Request, server: BunServer): Request | Response;
+};
+//# sourceMappingURL=proxy-origin.d.ts.map

package/dist/server/proxy-origin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-origin.d.ts","sourceRoot":"","sources":["../../src/server/proxy-origin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC5C;AAUD,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB;IAKvD,IAAI,SAAS,SAAS,GAAG,IAAI;IAQ7B,SAAS,UAAU,OAAO,UAAU,SAAS,GAAG,OAAO,GAAG,QAAQ;EAgCrE"}

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