@qontinui/ui-bridge-native 0.6.11 → 0.6.13

package/dist/core/param-schema.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Parameter-schema validation for component actions.
+ *
+ * Plan `2026-08-20-ui-bridge-action-declaration-shape`, Phase 2.
+ *
+ * `ComponentAction.paramSchema` is **published to agents** — it is spread onto
+ * `/control/components` and `/control/component/:id` by
+ * `server/handlers.ts` `annotateComponentWithInvocationPaths`, and four live
+ * runner consumers read it off the wire. Until Phase 2 nothing enforced it, so
+ * an agent that read the schema and sent conforming params had no guarantee
+ * the handler agreed. That is worse than publishing nothing: it invites trust
+ * it cannot honour. This module is what makes the declaration enforceable.
+ *
+ * ---------------------------------------------------------------------------
+ * THE SUPPORTED SUBSET — this is a CROSS-REPO CONTRACT
+ * ---------------------------------------------------------------------------
+ *
+ * `qontinui-runner` reads these same schemas
+ * (`workflow_generation/wrapper_manifest.rs`, `commands/command_interpreter.rs`,
+ * `bin/wrappers_mcp.rs`), and `command_interpreter.rs` feeds one to an LLM and
+ * asks it to produce conforming args. So the grammar below is not a private
+ * implementation detail — changing it changes what those consumers may emit.
+ *
+ * **No dependency.** `@qontinui/ui-bridge` ships to browsers and has exactly
+ * one runtime dependency (`dom-accessibility-api`). A full JSON Schema
+ * validator (`ajv` and friends) would be the SDK's first heavyweight runtime
+ * dep, which the plan rejected on bundle size. Hence a hand-implemented subset,
+ * documented here rather than inferred from the code.
+ *
+ * **Two accepted top-level shapes**, because `useUIComponent`'s own author-
+ * facing doc has always sanctioned both:
+ *
+ * 1. **Object-schema form** — the shape `paramSchemaOf()`
+ *    (`@qontinui/ui-bridge-wrapper`) emits:
+ *
+ *    ```jsonc
+ *    { "type": "object",
+ *      "properties": { "username": { "type": "string" },
+ *                      "remember": { "type": "boolean" } },
+ *      "required": ["username"],
+ *      "additionalProperties": false }
+ *    ```
+ *
+ * 2. **Map form** — the lightweight shorthand the doc describes as
+ *    "a map of `{ paramName: "string" | "number" | ... }`":
+ *
+ *    ```jsonc
+ *    { "username": "string", "count": { "type": "integer", "minimum": 1 } }
+ *    ```
+ *
+ * **Disambiguation rule** (deterministic, no heuristics). The schema is read as
+ * form 1 **iff** either:
+ *
+ * - it carries a `properties` object; or
+ * - `type === "object"` **and every other top-level key is a JSON Schema
+ *   object-applicable keyword** ({@link OBJECT_SCHEMA_KEYWORDS}).
+ *
+ * Everything else is form 2. So `{ "type": "string" }` is a map declaring one
+ * param named `type` of type `string`, not a top-level string schema — a
+ * params bag is always an object, so a non-object top-level `type` cannot be
+ * describing the bag.
+ *
+ * ⚠️ **The second clause is load-bearing, and a naive `type === "object"` test
+ * is a silent-validation-loss bug.** Consider the map form
+ * `{ "type": "object", "id": "string" }` — an action taking a param literally
+ * named `type` whose hint is `"object"`, plus an `id`. Reading that as form 1
+ * would find no `properties`, express no constraint, and **silently drop every
+ * sibling declaration in the map**: `validateActionParams(schema, { id: 12345 })`
+ * would answer `{ valid: true }` for a schema that plainly says `id` is a
+ * string. `id` is not an object keyword, so the keyword test sends it to form 2
+ * and both params validate. A param named `type` is not exotic — it is one of
+ * the most common names there is.
+ *
+ * The one genuinely ambiguous input is a bare `{ "type": "object" }`: it is
+ * both an empty object schema and a one-entry map declaring a param named
+ * `type` of type `object`. It is read as form 1 (the empty object schema),
+ * which constrains nothing either way, so the choice is unobservable except in
+ * combination with `additionalProperties: false` — where form 1 is clearly the
+ * intended reading.
+ *
+ * ### Map form is a TYPE hint, never a REQUIREDNESS hint
+ *
+ * A bare string value in map form is read as a type name **only when it is one
+ * of the seven JSON Schema primitive names** — `string`, `number`, `integer`,
+ * `boolean`, `object`, `array`, `null` — which is exactly `paramSchemaOf`'s
+ * own `PRIMITIVE_TYPES` set. **Any other string is prose and constrains
+ * nothing.**
+ *
+ * That is not defensive coding, it is the corpus: a census of every literal
+ * `paramSchema` in the fleet (2026-08-22) found ~50 map-form declarations in
+ * `qontinui-runner` alone whose values are human-readable hints, not types —
+ * `{ count: "number (>= 1, defaults to 1)", account: "string — either a Claude
+ * account label … or the literal \"best\"" }`. Reading `"number (>= 1,
+ * defaults to 1)"` as a type name would make every one of them unvalidatable
+ * noise. The file that declares them says so itself: *"loose `Record<string,
+ * unknown>` with hint strings, no runtime validation"*.
+ *
+ * For the same reason, **map form never marks anything required.** It has no
+ * `required` array and no other way to express optionality, and most of those
+ * ~50 real declarations describe params that are explicitly optional in their
+ * own prose ("defaults to 1", "optional initial prompt"). Requiring by default
+ * would report a violation on nearly every real call. An author who needs
+ * required params writes form 1, which has a keyword for it.
+ *
+ * **Optionality in form 1** is exactly `required`: a property is required iff
+ * listed there. Note `paramSchemaOf` **omits `required` entirely** when every
+ * field is optional, so its absence means "nothing required", never "malformed".
+ *
+ * `optional: true` is not a JSON Schema keyword — it is this monorepo's
+ * convention on `paramSchemaOf`'s *input* descriptors, and `paramSchemaOf`
+ * strips it before the schema reaches the wire. It is honoured here (form 2
+ * only) purely so an unstripped input-shaped object is read the same way.
+ *
+ * **Recognised property keywords** — everything else is IGNORED:
+ *
+ * | Keyword | Applies to | Meaning |
+ * |---|---|---|
+ * | `type` | any | `"string" \| "number" \| "integer" \| "boolean" \| "object" \| "array" \| "null"`, or an array of those (union — a value matching any member passes). Any OTHER type name constrains nothing (`paramSchemaOf` passes unknown names through verbatim, so they do occur) |
+ * | `enum` | any | value must equal one of the listed JSON values |
+ * | `const` | any | value must equal this JSON value |
+ * | `properties` | objects | per-key sub-schemas, applied recursively |
+ * | `required` | objects | array of key names that must be present |
+ * | `additionalProperties` | objects | when exactly `false`, keys absent from `properties` are rejected — **including when the schema declares no `properties` at all**, which is the natural spelling of "takes no params". Any other value is ignored |
+ * | `items` | arrays | one sub-schema applied to every element, recursively |
+ * | `minimum` / `maximum` | numbers | inclusive bounds |
+ * | `minLength` / `maxLength` | strings | inclusive bounds on `.length` |
+ * | `pattern` | strings | ECMAScript regex, unanchored. An uncompilable **or catastrophically-backtracking** pattern is ignored, never a failure — see {@link MAX_PATTERN_LENGTH} |
+ *
+ * **⚠ Anything outside this table is IGNORED, never rejected.** `description`,
+ * `default`, `title`, `format`, `examples`, `$schema`, `$ref`, `oneOf`,
+ * `anyOf`, `allOf`, `not`, `patternProperties`, `minItems`, `exclusiveMinimum`
+ * … all pass silently. This is deliberate and load-bearing: a schema outside
+ * this subset is still *valid JSON Schema*, and rejecting an unrecognised
+ * keyword would convert a documentation nicety into a hard invocation failure
+ * for every author who wrote a richer schema than this validator reads. An
+ * unreadable schema means "no constraint expressed here", not "invalid".
+ * The same rule applies one level up: a `paramSchema` that is not a plain
+ * object at all (`null`, an array, a string) expresses no constraint and
+ * validates everything.
+ *
+ * **No coercion.** `"5"` does not satisfy `{"type":"number"}`. The runner's
+ * LLM router is already instructed to "coerce numeric tokens to numbers"
+ * (`command_interpreter.rs`), so coercing here would hide that contract rather
+ * than enforce it.
+ *
+ * ### A validator must return a verdict, never throw
+ *
+ * {@link validateActionParams} is called at an invocation seam whose only
+ * generic failure label is `UB-ACTION-FAILED` — "the handler failed". A
+ * validator that throws would therefore be reported as a *handler* fault, and
+ * the author would go debug code that never ran. Two inputs could do it, and
+ * both are **author-supplied schema data**, not caller params:
+ *
+ * - **A self-referential schema.** `const s = { type: 'object', properties: {} };
+ *   s.properties.self = s;` recurses until `RangeError: Maximum call stack size
+ *   exceeded`. Bounded by {@link MAX_SCHEMA_DEPTH}: past that depth the walk
+ *   stops and expresses no further constraint (the ignore-don't-reject rule,
+ *   applied to depth).
+ * - **A catastrophically-backtracking `pattern`.** This one does not throw at
+ *   all — it *hangs*, which no `try`/`catch` can rescue. Guarded before
+ *   compilation by {@link MAX_PATTERN_LENGTH} and a nested-quantifier test,
+ *   the same pair `control/action-executor.ts` already applies to a
+ *   caller-supplied `srcPattern`.
+ *
+ * The seams wrap the call anyway (belt and braces) and report a validator
+ * fault distinguishably from a handler fault — see the executors.
+ *
+ * ---------------------------------------------------------------------------
+ * DUPLICATE — deliberately not an import
+ * ---------------------------------------------------------------------------
+ *
+ * DUPLICATE OF `@qontinui/ui-bridge` `src/core/param-schema.ts` — DELIBERATELY
+ * NOT AN IMPORT, for the same reason as `core/abortable.ts` beside it:
+ * `@qontinui/ui-bridge` is an OPTIONAL peerDependency of this package and is
+ * absent from `dependencies`, so a consumer may install
+ * `@qontinui/ui-bridge-native` alone; importing from it would resolve inside
+ * this monorepo and then fail for that consumer.
+ *
+ * KEEP IN SYNC with `@qontinui/ui-bridge` `src/core/param-schema.ts`. The
+ * module has no imports and touches no DOM or Node API — only `RegExp`,
+ * `JSON`, `Set` and `Number`, all present in React Native. The documented
+ * subset above is a cross-repo contract, so the two copies drifting is a
+ * contract break, not a style nit.
+ */
+/** Which rule rejected a value. Machine-readable; pairs with `message`. */
+export type ParamSchemaKeyword = 'required' | 'type' | 'enum' | 'const' | 'additionalProperties' | 'minimum' | 'maximum' | 'minLength' | 'maxLength' | 'pattern';
+/**
+ * One rejected parameter. `path` is the whole point — an agent told only
+ * "invalid params" cannot fix anything, so every issue names the param it is
+ * about.
+ */
+export interface ParamSchemaIssue {
+    /**
+     * Location of the offending value, in dotted/bracketed form relative to the
+     * params object: `"username"`, `"filter.status"`, `"ids[2]"`. Empty string
+     * means the params object itself.
+     */
+    path: string;
+    /** Which rule rejected it. */
+    keyword: ParamSchemaKeyword;
+    /** What the schema demanded, rendered for a human/agent reader. */
+    expected: string;
+    /** What was actually supplied, rendered compactly. Absent for `required`. */
+    received?: string;
+    /** One-line explanation naming both the param and the reason. */
+    message: string;
+}
+/** Outcome of {@link validateActionParams}. */
+export interface ParamValidationResult {
+    valid: boolean;
+    /** Empty iff `valid`. */
+    issues: ParamSchemaIssue[];
+}
+/**
+ * What the executor does with a schema violation.
+ *
+ * - `'enforce'` — reject the invocation before the handler runs, with
+ *   `errorCode: 'UB-ACTION-REJECTED'` and the issue list attached.
+ * - `'warn'` — log the violation and invoke the handler anyway.
+ * - `'off'` — skip validation entirely (no schema walk, no allocation).
+ */
+export type ParamValidationMode = 'enforce' | 'warn' | 'off';
+/**
+ * **`'warn'`.** Decided on the plan's priority order — *powerful features →
+ * scalability → robustness → clean code* — not on backward compatibility,
+ * which is explicitly not a factor on this project.
+ *
+ * The feature Phase 2 delivers is *an enforceable declaration*, and warn mode
+ * delivers all of it except the refusal: the schema is walked, the violating
+ * param is named, and the violation is reported. Enforcement is one call to
+ * {@link setDefaultParamValidationMode} away, per deployment.
+ *
+ * What arming `'enforce'` by default would buy is the refusal — and the
+ * population it would refuse first is not attackers, it is the fleet's own
+ * schemas. Nothing has ever validated these declarations, so on the balance of
+ * evidence some existing `paramSchema` values are wrong about their own
+ * handlers rather than the callers being wrong about the schema; a validator
+ * armed on day one reports that as the caller's failure. Worse, the largest
+ * live producer of action params is a *model*:
+ * `qontinui-runner/src-tauri/src/commands/command_interpreter.rs` asks an LLM
+ * for "args whose keys match the chosen action's `paramSchema`", and that
+ * failure surfaces to a user running a slash command. Defaulting to enforce
+ * would convert a documentation defect into a user-visible outage on a
+ * population that was never measured.
+ *
+ * Robustness — third in the order, and the tiebreaker here — argues the same
+ * way: the robust move is to collect violations from a validator that has
+ * never seen production traffic before letting it refuse anything. A default
+ * that fails open and is *observable* beats a default that fails closed and is
+ * *unmeasured*.
+ */
+export declare const DEFAULT_PARAM_VALIDATION_MODE: ParamValidationMode;
+/**
+ * Arm or disarm validation process-wide. Call once at app boot; each
+ * invocation may still override it via `executeComponentAction`'s
+ * `{ paramValidation }` option.
+ */
+export declare function setDefaultParamValidationMode(mode: ParamValidationMode): void;
+/** The mode an invocation gets when it does not pass one. */
+export declare function getDefaultParamValidationMode(): ParamValidationMode;
+/** Test/teardown helper: restore {@link DEFAULT_PARAM_VALIDATION_MODE}. */
+export declare function resetDefaultParamValidationMode(): void;
+/**
+ * Validate `params` against an action's `paramSchema`.
+ *
+ * Returns `{ valid: true, issues: [] }` for anything the documented subset
+ * cannot read — that is the ignore-don't-reject rule, and it is why a schema
+ * this validator does not understand can never fail an invocation.
+ *
+ * @param schema the action's declared `paramSchema` (any shape; unreadable
+ *   shapes constrain nothing)
+ * @param params the params the caller supplied. `undefined` is treated as an
+ *   empty object, so a schema with required properties still reports them.
+ */
+export declare function validateActionParams(schema: unknown, params: unknown): ParamValidationResult;
+/**
+ * One-line summary of a violation set, naming the action and every offending
+ * param. Used as the `error` / `message` string at every invocation seam so
+ * the three trees phrase the rejection identically.
+ */
+export declare function formatParamValidationFailure(componentId: string, actionId: string, issues: ParamSchemaIssue[]): string;
+//# sourceMappingURL=param-schema.d.ts.map

package/dist/core/param-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param-schema.d.ts","sourceRoot":"","sources":["../../src/core/param-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuLG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,MAAM,GACN,MAAM,GACN,OAAO,GACP,sBAAsB,GACtB,SAAS,GACT,SAAS,GACT,WAAW,GACX,WAAW,GACX,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,yBAAyB;IACzB,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,6BAA6B,EAAE,mBAA4B,CAAC;AAIzE;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAE7E;AAED,6DAA6D;AAC7D,wBAAgB,6BAA6B,IAAI,mBAAmB,CAEnE;AAED,2EAA2E;AAC3E,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AA6hBD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,OAAO,GACd,qBAAqB,CA0CvB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,gBAAgB,EAAE,GACzB,MAAM,CAGR"}