@vxil/cli 0.17.0 → 0.19.0

package/dist/_vxil-feature-configs-hooks.d.ts

@@ -10,12 +10,16 @@ export declare const HOOK_LIMITS: {
     readonly maxReadHooksPerCollection: 10;
 };
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only and
- *  populated ONLY on the READ path (runReadHooks); on the write path and in
- *  server-caller mode it is null, exactly like `before` on a create. It carries
- *  `caller.endUserId` (the verified session sub, or null) and `caller.principal`
- *  ('end_user' | 'tenant'). It is the missing "caller/session context" a read
- *  hook keys on to redact/derive per-viewer. */
+ *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only.
+ *  It carries `caller.endUserId` (the verified session sub, or null),
+ *  `caller.principal` ('end_user' | 'tenant') and `caller.roles` (the VERIFIED
+ *  session role claims of the signed-in session — never a body or header
+ *  value; null in server-caller mode). READ hooks always get it
+ *  (server mode: `{ endUserId: null, principal: 'tenant', roles: null }`).
+ *  WRITE hooks get it in verified end-user mode only; on a
+ *  server write it is null, exactly like `before` on a create — so a role rule
+ *  reads `isNull(caller) || contains(caller.roles, 'manager')`. `contains` on
+ *  an array is exact element membership. */
 export declare const HOOK_ROOT_VARS: readonly ["item", "before", "now", "caller"];
 /** The ONLY callable functions. Each is pure + deterministic + bounded. */
 export declare const HOOK_FUNCTIONS: readonly ["min", "max", "abs", "round", "floor", "ceil", "sqrt", "pow", "sign", "len", "lower", "upper", "trim", "substr", "contains", "startsWith", "endsWith", "concat", "coalesce", "ifNull", "not", "isNull", "number", "string", "bool", "daysBetween", "yearsBetween"];
@@ -64,25 +68,41 @@ export declare class HookEvalError extends Error {
 /** Thrown by a `validate` hook whose expression is falsy — maps to a clean 422. */
 export declare class HookRejection extends Error {
 }
+/** A WRITE `validate` hook whose expression could not be evaluated (null
+ *  arithmetic, a missing operand, a bad date …). Still a HookEvalError — the
+ *  write is refused, never let through — but it carries the hook's id and its
+ *  declared `message`, so the API can show the end user the tenant's own copy
+ *  while keeping the engine detail for the developer. `message` stays the
+ *  engine detail. */
+export declare class HookValidateFault extends HookEvalError {
+    readonly hookId: string;
+    readonly tenantMessage: string | undefined;
+    constructor(hookId: string, tenantMessage: string | undefined, detail: string);
+}
 /** Parse a hook expression into an AST. Throws HookParseError on any malformed input. */
 export declare function parseExpr(src: string): Node;
 /** Walk the AST and reject anything outside the allow-list, plus depth bounds.
  *  Returns an array of human-readable errors (empty = safe). Pure, no eval. */
 export declare function validateAst(root: Node): string[];
-/** The VERIFIED caller/session context for read hooks (guide ch. 7). Read-only;
- *  present only on the read path in end-user mode. In server mode / write path
- *  the whole object is null. */
+/** The VERIFIED caller/session context for Lane-A hooks (guide ch. 7).
+ *  Read-only. Read hooks always get it; write hooks get it in verified end-user
+ *  mode only (a server write passes null — see HOOK_ROOT_VARS). */
 export interface HookCaller {
     /** the verified end-user session sub, or null in server-caller mode. */
     endUserId: string | null;
     /** 'end_user' when a session was verified at the edge, else 'tenant'. */
     principal: 'end_user' | 'tenant';
+    /** the VERIFIED session role claims of the signed-in session; `[]` for a
+     *  session without roles, null in server-caller mode. Optional so an older
+     *  caller object still reads
+     *  as "no roles". */
+    roles?: readonly string[] | null;
 }
 export interface HookContext {
     item: Record<string, unknown>;
     before: Record<string, unknown> | null;
     now: string;
-    /** verified caller/session context (read path only); null otherwise. */
+    /** verified caller/session context; null on a server write. */
     caller?: HookCaller | null;
 }
 /** A mutable step counter SHARED across many evalExpr calls (the read path's
@@ -116,7 +136,10 @@ export interface HookRunResult {
  *  Mutates a CLONE: derive hooks set fields; a validate hook that returns falsy
  *  throws HookRejection (→ the caller maps to a 422 and the tx rolls back).
  *  Throws HookEvalError on a runtime fault (also a clean 422, never a 500). */
-export declare function runWriteHooks(hooks: Record<string, HookDef> | undefined, collection: string, phase: 'create' | 'update', data: Record<string, unknown>, before: Record<string, unknown> | null, now: string): HookRunResult;
+export declare function runWriteHooks(hooks: Record<string, HookDef> | undefined, collection: string, phase: 'create' | 'update', data: Record<string, unknown>, before: Record<string, unknown> | null, now: string, 
+/** the VERIFIED end-user caller (endUserId + principal + roles) in
+ *  end-user mode; omitted / null on a server write (expressions see null). */
+caller?: HookCaller | null): HookRunResult;
 export interface ReadHookResult {
     /** Surviving rows in input order. Each is a SHALLOW COPY with a copied `data`
      *  bag — the caller's rows are never mutated and nothing here is persisted. */
@@ -143,8 +166,8 @@ export interface ReadHookResult {
  *  fire here, and read events never fire in runWriteHooks. */
 export declare function runReadHooks(hooks: Record<string, HookDef> | undefined, collection: string, rows: ReadonlyArray<Record<string, unknown>>, now: string, 
 /** verified caller/session context (guide ch. 7) — read-only, exposed to
- *  expressions as `caller.endUserId` / `caller.principal`. Omitted ⇒ null
- *  (server-caller mode). */
+ *  expressions as `caller.endUserId` / `caller.principal` / `caller.roles`.
+ *  Omitted ⇒ null (server-caller mode). */
 caller?: HookCaller | null): ReadHookResult;
 export interface ExprRef {
     root: 'item' | 'before' | 'now' | 'caller';
@@ -157,6 +180,36 @@ export type InferredType = 'number' | 'string' | 'boolean' | 'null' | 'unknown';
 /** Best-effort static type of an expression's result (its output). 'unknown' for
  *  member access / coalesce / mixed ternaries — never a false-positive mismatch. */
 export declare function inferType(nd: Node): InferredType;
+/** One declared field, as the typing pass needs it (cms field type + required). */
+export interface HookFieldInfo {
+    type: string;
+    required?: boolean;
+}
+/** collection → field → declared info. */
+export type HookFieldTypes = Record<string, Record<string, HookFieldInfo>>;
+/** Type one parsed expression against one collection's declared fields.
+ *  `errors` are shapes that can never work (refuse); `warnings` are shapes
+ *  that work only for some stored values (json vs a scalar, `+` on a text
+ *  field) and arithmetic on an optional field with no coalesce() — it faults
+ *  the hook whenever the field is missing. `present` lists fields a derive sets first. */
+export declare function checkHookExprTypes(root: Node, fields: Record<string, HookFieldInfo> | undefined, opts: {
+    kind: HookDef['kind'];
+    event: HookDef['event'];
+    present?: ReadonlySet<string> | undefined;
+}): {
+    errors: string[];
+    warnings: string[];
+};
+/** Project declared collections (`{ <name>: { fields: { <f>: { type, required? } } } }`
+ *  — the vxil.config / apply-bundle shape) onto HookFieldTypes. Malformed
+ *  entries are skipped: no declared field means no verdict. */
+export declare function hookFieldTypesOf(collections: unknown): HookFieldTypes;
+/** Type every hook whose collection the caller declares (see checkHookExprTypes).
+ *  Unparseable expressions are skipped — validateHookDef already reports them. */
+export declare function checkHookTypes(hooks: Record<string, HookDef> | undefined, fieldTypes: HookFieldTypes): {
+    errors: string[];
+    warnings: string[];
+};
 export type HlKind = 'num' | 'str' | 'fn' | 'var' | 'kw' | 'op' | 'ident' | 'ws' | 'err';
 /** Token-level highlighter over the FULL source (whitespace + bad chars kept),
  *  so a dashboard editor can render a colored overlay behind a textarea. */

package/dist/_vxil-feature-configs-readmodels.d.ts

@@ -35,4 +35,22 @@ interface CdcRuleLike {
 }
 /** Cross-field rule for CmsConfig.cdc (called from validateFeatureConfig). */
 export declare function validateCdcConfig(cdc: Record<string, CdcRuleLike> | undefined): string[];
+/** What a payload:'full' change-data rule must know about its target
+ *  collection's read gates. `readRoleFields`: fields with a non-empty
+ *  `readRoles`; `endUserAccess`: the collection's end-user access mode. */
+export interface CdcCollectionGates {
+    readRoleFields?: readonly string[];
+    endUserAccess?: 'readwrite' | 'read' | 'none';
+}
+/**
+ * A `payload: 'full'` change-data rule inlines the stored row into a realtime
+ * frame that every subscriber of the channel receives — it does not go through
+ * the read projection. So it must never target a collection whose reads are
+ * gated: a field with `readRoles` (the frame would carry the gated value), or
+ * an `endUserAccess` of 'read' / 'none' (the frame would bypass the
+ * collection's end-user gate). Pure; one problem line per offending ENABLED
+ * rule (an unknown collection is skipped). The safe shape is `payload: 'ids'`
+ * and a re-read through the cms, where every gate applies.
+ */
+export declare function cdcFullFramesOverGatedCollections(cdc: unknown, collections: Record<string, CdcCollectionGates>): string[];
 export {};

package/dist/_vxil-feature-configs.d.ts

@@ -78,9 +78,10 @@ export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObj
         maxAttempts: import("@sinclair/typebox").TInteger;
         backoff: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"exponential">, import("@sinclair/typebox").TLiteral<"linear">]>;
     }>>;
-    suppression: import("@sinclair/typebox").TObject<{
+    suppression: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         softBounceThreshold: import("@sinclair/typebox").TInteger;
-    }>;
+        testRecipients: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    }>>;
     rateLimit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         perDay: import("@sinclair/typebox").TInteger;
         perTenantSec: import("@sinclair/typebox").TInteger;
@@ -217,6 +218,7 @@ declare const OidcProviderSchema: import("@sinclair/typebox").TObject<{
         email: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         roles: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        rolePrefix: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
     allowedDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     autoLink: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
@@ -274,6 +276,7 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
                 email: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                 name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                 roles: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                rolePrefix: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             }>>;
             allowedDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
             autoLink: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
@@ -318,6 +321,8 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
         breachedPasswords: import("@sinclair/typebox").TBoolean;
         captchaSecretRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         allowedRedirectOrigins: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+        inviteOnly: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        allowedEmailDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     }>>;
 }>;
 /** The security bag as persisted (present ⇒ leaf defaults applied). */
@@ -632,6 +637,7 @@ export declare const RagConfigSchema: import("@sinclair/typebox").TObject<{
         topK: import("@sinclair/typebox").TInteger;
         mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"hybrid">, import("@sinclair/typebox").TLiteral<"vector">, import("@sinclair/typebox").TLiteral<"keyword">]>;
         minScore: import("@sinclair/typebox").TNumber;
+        minSimilarity: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
         rerank: import("@sinclair/typebox").TBoolean;
     }>;
     boosts: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
@@ -832,6 +838,9 @@ export declare const TEST_RECIPIENT_EMAIL_RE: RegExp;
 export declare const TEST_RECIPIENT_GLOB_RE: RegExp;
 export declare const TEST_RECIPIENT_E164_RE: RegExp;
 export declare function isTestRecipientPattern(entry: string): boolean;
+/** The MAIL subset of the grammar (notifications suppression.testRecipients):
+ * an exact email or an `*@domain` glob. */
+export declare function isMailTestRecipientPattern(entry: string): boolean;
 /** True iff `identifier` (an email today) matches one configured entry:
  * exact (case-insensitive) or the `*@domain` glob. +E.164 entries never match
  * an email. */

package/dist/config.d.ts

@@ -121,6 +121,17 @@ export interface CollectionDef {
      *  `vxil push --allow-destructive`. Any other value fails `vxil plan` /
      *  `vxil push` (it never falls back to 'readwrite'). */
     endUserAccess?: 'readwrite' | 'read' | 'none';
+    /** Role slugs one of which a VERIFIED end user must hold to WRITE this
+     *  collection (create, update, $inc, delete, publish, transaction step,
+     *  filtered delete, batch write, and an end-user delete's cascade into it) —
+     *  otherwise `403 role_required`. Reads are unaffected. Roles are the
+     *  session's verified role claims (its orgs roles — the
+     *  same ones `readRoles` and `caller.roles` in hooks see). Server keys are
+     *  never affected. Absent / `[]` = ungated. Up to 16 slugs
+     *  (`^[a-z0-9][a-z0-9_-]{0,31}$`). Stored on the collection (model data, not
+     *  a config leaf) and carried by BOTH push paths; widening (clearing, or
+     *  adding a role) needs `vxil push --allow-destructive`. */
+    writeRoles?: string[];
     /** Per-record action buttons (guide ch. 4): `[{ key, label, fn }]`, stored on
      *  the collection (model data, not a config leaf). The dashboard renders one
      *  button per action on each record row; `POST /v1/cms/items/:coll/:id/actions/