@vxil/feature-configs 0.3.0 → 0.3.1

package/README.md

@@ -0,0 +1,58 @@
+# @vxil/feature-configs
+
+The typed config schemas for every Vxil feature — the shapes a `vxil.config.ts`
+is built on, published so your editor and your CI can read the same contract the
+platform validates against.
+
+```bash
+npm i -D @vxil/feature-configs
+```
+
+Most people never import this directly: writing
+[`defineConfig`](https://www.npmjs.com/package/@vxil/config) gives you these
+types automatically. Reach for it when you want to validate a manifest yourself,
+generate config, or type a helper.
+
+## What's in it
+
+- **One schema per feature**, all 19 of them — `NotificationsConfigSchema`,
+  `AuthConfigSchema`, `CmsConfigSchema`, `PaymentsConfigSchema`,
+  `FunctionsConfigSchema`, … — plus the matching `Static<>` types
+  (`NotificationsConfig`, `AuthConfig`, …).
+- **`FEATURE_KEYS`** — the canonical feature list, and **`FEATURE_SCHEMAS`** —
+  the key → schema map.
+- **`validateFeatureConfig(feature, raw)`** — the exact validation the control
+  plane runs, returning `{ ok, errors }` with JSON-pointer-style messages. Use it
+  in a pre-commit hook or a test to fail on a bad config before you push it.
+- **`hooks`** (`@vxil/feature-configs/hooks`) — the CMS lifecycle-hook expression
+  grammar: the same closed, sandboxed parser/validator the server uses, so a
+  malformed `validate` / `derive` expression is caught in your editor.
+
+```ts
+import { validateFeatureConfig, FEATURE_KEYS } from '@vxil/feature-configs';
+
+const result = validateFeatureConfig('notifications', {
+  enabled: true,
+  fromEmail: 'noreply@acme.com',
+});
+if (!result.ok) throw new Error(result.errors.join('\n'));
+```
+
+## Why the schemas are small on purpose
+
+Every feature's config is capped at a fixed number of top-level leaves. A knob
+earns its slot by having a reader; one that nothing reads gets deleted rather
+than left to rot as a promise the product does not keep. That is why the schemas
+here are the whole truth about what a feature can be configured to do — and why
+a version bump may *remove* a knob that was never wired. Removals are listed in
+the feature reference at [vxil.com](https://vxil.com).
+
+## Related
+
+- [`@vxil/config`](https://www.npmjs.com/package/@vxil/config) — `defineConfig()`.
+- [`@vxil/cli`](https://www.npmjs.com/package/@vxil/cli) — the `vxil` command (`plan` / `push` / `gen`).
+- [`@vxil/sdk`](https://www.npmjs.com/package/@vxil/sdk) — the typed runtime client.
+
+Docs: [vxil.com](https://vxil.com) · Dashboard: [vxil.com/dashboard](https://vxil.com/dashboard)
+
+MIT © techmaker.io

package/dist/hooks.d.ts

@@ -10,7 +10,7 @@ export declare const HOOK_LIMITS: {
     readonly maxReadHooksPerCollection: 10;
 };
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (docs/end-user-principals-design.md §5.6) — read-only and
+ *  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`

package/dist/hooks.js

@@ -1,4 +1,4 @@
-// CMS lifecycle hooks — the SAFE expression engine (docs/cms-lifecycle-hooks-rung2-design.md, Lane A).
+// CMS lifecycle hooks — the SAFE expression engine (https://vxil.com/docs/guide/07-validation-and-hooks).
 //
 // A "code-based" lifecycle hook is a small EXPRESSION the tenant authors. Three kinds:
 //   - validate: the expression must evaluate truthy or the write is REJECTED (422)
@@ -17,8 +17,8 @@
 // CROSS-ROW AGGREGATION STAYS OUT — BY DESIGN. Read hooks are a pure function
 // of ONE row (+ `now`): there are no new root variables, no array/aggregate
 // functions, no access to sibling rows or other collections. Counts/sums/
-// group-bys across rows are the §5 identity-fork anti-item (docs/features/
-// cms.md §6.7) and must never enter this engine.
+// group-bys across rows are the identity-fork anti-item (function territory:
+// vxil.com/docs/guide/07-validation-and-hooks) and must never enter this engine.
 //
 // SAFETY (the "not malicious" guarantee) is structural, not heuristic:
 //   * No JS is executed. `eval`/`Function`/the host runtime are never touched. The
@@ -61,7 +61,7 @@ export const HOOK_LIMITS = {
 };
 // ── allow-lists ─────────────────────────────────────────────────────────────
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (docs/end-user-principals-design.md §5.6) — read-only and
+ *  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`

package/dist/index.js

@@ -452,7 +452,7 @@ export const FilesConfigSchema = Type.Object({
         // object storage is cheap but the SQL-database-resident metadata + abuse aren't (pricing re-audit
         // 2026-07-10). 5 GiB/object, 1 TiB/tenant absolute; true PER-TIER clamps
         // (Free/Dev 10 GB · Team 50 GB · Business 256 GB) are a follow-up needing the
-        // tenant tier threaded to files-v1 (docs/pricing-model-analysis.md §6).
+        // tenant tier threaded to files-v1 (plan tiers).
         maxObjectBytes: Type.Integer({ default: 100 * 1024 * 1024, minimum: 1, maximum: 5 * 1024 * 1024 * 1024 }),
         maxTotalBytes: Type.Integer({ default: 10 * 1024 * 1024 * 1024, minimum: 1, maximum: 1024 * 1024 * 1024 * 1024 }),
         maxObjectCount: Type.Integer({ default: 100000, minimum: 1, maximum: 100_000_000 }),
@@ -536,7 +536,7 @@ export const CmsConfigSchema = Type.Object({
         maxExpandFields: Type.Integer({ default: 5, minimum: 1, maximum: 25 }),
         maxComputedFieldsPerCollection: Type.Integer({ default: 10, minimum: 1, maximum: 50 }),
     }, { default: {} }),
-    // Code-based lifecycle hooks (docs/cms-lifecycle-hooks-rung2-design.md, Lane A):
+    // Code-based lifecycle hooks (https://vxil.com/docs/guide/07-validation-and-hooks):
     // a tenant-authored SAFE expression. Write events (beforeCreate/beforeUpdate/
     // beforeWrite) run in-transaction — `validate` rejects the write, `derive`
     // computes a persisted field. Read events shape the RESPONSE only: `validate`
@@ -1044,9 +1044,9 @@ export const FunctionsConfigSchema = Type.Object({
             collection: Type.Optional(Type.String()), // cmsHook: the CMS collection slug
             event: Type.Optional(Type.String()), // cmsHook: beforeCreate|beforeUpdate|beforeWrite · authHook: 'user.created'
         }), { maxItems: 8 })),
-        scriptRef: Type.String(), // content-hashed WfP script name: fn-<tenant>-<name>-<sha>
+        scriptRef: Type.String(), // content-hashed hosted-script name: fn-<tenant>-<name>-<sha>
         scopes: Type.Optional(Type.Array(Type.String())), // clamped via DENY_FUNCTION_SCOPES at deploy (admin/*/features:write/functions:write/secrets:write)
-        secrets: Type.Optional(Type.Array(Type.String())), // tenant_secrets refs (KEK_FUNCTIONS)
+        secrets: Type.Optional(Type.Array(Type.String())), // names of tenant secrets injected at invoke time
         egressAllow: Type.Optional(Type.Array(Type.String())), // Outbound Worker allowlist hosts
         limits: Type.Optional(Type.Object({
             cpuMs: Type.Integer(),
@@ -1064,7 +1064,7 @@ export const FunctionsConfigSchema = Type.Object({
         })),
     }))),
 });
-// copilot feature (docs/copilot-agents-sku-design.md §4). Re-declared to match
+// copilot feature (https://vxil.com/docs/guide/11-copilot-agents). Re-declared to match
 // workers/copilot-v1/src/config.ts's exported CopilotConfigSchema (one shape,
 // two consumers — keep the two definitions byte-identical). A thin COMPOSITION
 // layer over ai + vector-search + rag + mcp: it owns the AGENT layer (persona,
@@ -1511,7 +1511,7 @@ export function validateFeatureConfig(feature, raw) {
         if (errs.length)
             return { ok: false, errors: errs.slice(0, 10) };
     }
-    // Cross-field rules: copilot (docs/copilot-agents-sku-design.md §4). Pure
+    // Cross-field rules: copilot (https://vxil.com/docs/guide/11-copilot-agents). Pure
     // rules only — cross-feature resolutions (collection existence, directiveRef
     // → ai.templates) are deferred to runtime, which fails soft with the
     // capability-surface envelope. Tool-NAME existence runs only when the mcp
@@ -1557,7 +1557,7 @@ export function validateFeatureConfig(feature, raw) {
     return { ok: true, errors: [], value: withDefaults };
 }
 // ─────────────────────────────────────────────────────────────────────────────
-// PLANNER GROUNDING (roadmap §4.6.E; docs/ai-planner-design.md §2).
+// PLANNER GROUNDING (https://vxil.com/docs/guide/10-agents-and-mcp).
 // FEATURE_KEYS is the literal feature list the planner catalog is projected
 // from; the planner-catalog CI gate asserts set-equality with
 // Object.keys(FEATURE_SCHEMAS), so adding a feature without extending this

package/dist/readmodels.js

@@ -1,4 +1,4 @@
-// cms-rel B5/E config-write gates (docs/cms-relational-depth-options.md §3/§4)
+// cms-rel B5/E config-write gates (read models + transactions — https://vxil.com/docs/guide/04-data-with-cms)
 // — the hooks.ts sibling: PURE structural validation of the `readModels` and
 // `cdc` bags at config-write time (the anti-malice-gate pattern). The grammar
 // (fn/rank allow-lists, arity caps, window bounds, dotted-term shape) is

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.3.0",
-  "description": "TypeBox config schemas for every vxil feature — the typed manifests vxil.config.ts is built on. INTERNAL workspace package: bundled into the published `vxil` package (via @vxil/config), not published separately.",
+  "version": "0.3.1",
+  "description": "The per-feature configuration schemas and validators behind vxil.config.ts (published for @vxil/cli and @vxil/config).",
   "license": "MIT",
   "homepage": "https://vxil.com",
   "repository": {

package/src/hooks.ts

@@ -1,4 +1,4 @@
-// CMS lifecycle hooks — the SAFE expression engine (docs/cms-lifecycle-hooks-rung2-design.md, Lane A).
+// CMS lifecycle hooks — the SAFE expression engine (https://vxil.com/docs/guide/07-validation-and-hooks).
 //
 // A "code-based" lifecycle hook is a small EXPRESSION the tenant authors. Three kinds:
 //   - validate: the expression must evaluate truthy or the write is REJECTED (422)
@@ -17,8 +17,8 @@
 // CROSS-ROW AGGREGATION STAYS OUT — BY DESIGN. Read hooks are a pure function
 // of ONE row (+ `now`): there are no new root variables, no array/aggregate
 // functions, no access to sibling rows or other collections. Counts/sums/
-// group-bys across rows are the §5 identity-fork anti-item (docs/features/
-// cms.md §6.7) and must never enter this engine.
+// group-bys across rows are the identity-fork anti-item (function territory:
+// vxil.com/docs/guide/07-validation-and-hooks) and must never enter this engine.
 //
 // SAFETY (the "not malicious" guarantee) is structural, not heuristic:
 //   * No JS is executed. `eval`/`Function`/the host runtime are never touched. The
@@ -63,7 +63,7 @@ export const HOOK_LIMITS = {
 
 // ── allow-lists ─────────────────────────────────────────────────────────────
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (docs/end-user-principals-design.md §5.6) — read-only and
+ *  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`

package/src/index.ts

@@ -564,7 +564,7 @@ export const FilesConfigSchema = Type.Object({
       // object storage is cheap but the SQL-database-resident metadata + abuse aren't (pricing re-audit
       // 2026-07-10). 5 GiB/object, 1 TiB/tenant absolute; true PER-TIER clamps
       // (Free/Dev 10 GB · Team 50 GB · Business 256 GB) are a follow-up needing the
-      // tenant tier threaded to files-v1 (docs/pricing-model-analysis.md §6).
+      // tenant tier threaded to files-v1 (plan tiers).
       maxObjectBytes: Type.Integer({ default: 100 * 1024 * 1024, minimum: 1, maximum: 5 * 1024 * 1024 * 1024 }),
       maxTotalBytes: Type.Integer({ default: 10 * 1024 * 1024 * 1024, minimum: 1, maximum: 1024 * 1024 * 1024 * 1024 }),
       maxObjectCount: Type.Integer({ default: 100000, minimum: 1, maximum: 100_000_000 }),
@@ -678,7 +678,7 @@ export const CmsConfigSchema = Type.Object({
     },
     { default: {} },
   ),
-  // Code-based lifecycle hooks (docs/cms-lifecycle-hooks-rung2-design.md, Lane A):
+  // Code-based lifecycle hooks (https://vxil.com/docs/guide/07-validation-and-hooks):
   // a tenant-authored SAFE expression. Write events (beforeCreate/beforeUpdate/
   // beforeWrite) run in-transaction — `validate` rejects the write, `derive`
   // computes a persisted field. Read events shape the RESPONSE only: `validate`
@@ -1373,9 +1373,9 @@ export const FunctionsConfigSchema = Type.Object({
             { maxItems: 8 },
           ),
         ),
-        scriptRef: Type.String(), // content-hashed WfP script name: fn-<tenant>-<name>-<sha>
+        scriptRef: Type.String(), // content-hashed hosted-script name: fn-<tenant>-<name>-<sha>
         scopes: Type.Optional(Type.Array(Type.String())), // clamped via DENY_FUNCTION_SCOPES at deploy (admin/*/features:write/functions:write/secrets:write)
-        secrets: Type.Optional(Type.Array(Type.String())), // tenant_secrets refs (KEK_FUNCTIONS)
+        secrets: Type.Optional(Type.Array(Type.String())), // names of tenant secrets injected at invoke time
         egressAllow: Type.Optional(Type.Array(Type.String())), // Outbound Worker allowlist hosts
         limits: Type.Optional(
           Type.Object({
@@ -1405,7 +1405,7 @@ export const FunctionsConfigSchema = Type.Object({
 //   defaultLimits.memoryMb leaves.)
 export type FunctionsConfig = Static<typeof FunctionsConfigSchema>;
 
-// copilot feature (docs/copilot-agents-sku-design.md §4). Re-declared to match
+// copilot feature (https://vxil.com/docs/guide/11-copilot-agents). Re-declared to match
 // workers/copilot-v1/src/config.ts's exported CopilotConfigSchema (one shape,
 // two consumers — keep the two definitions byte-identical). A thin COMPOSITION
 // layer over ai + vector-search + rag + mcp: it owns the AGENT layer (persona,
@@ -1922,7 +1922,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     }
     if (errs.length) return { ok: false, errors: errs.slice(0, 10) };
   }
-  // Cross-field rules: copilot (docs/copilot-agents-sku-design.md §4). Pure
+  // Cross-field rules: copilot (https://vxil.com/docs/guide/11-copilot-agents). Pure
   // rules only — cross-feature resolutions (collection existence, directiveRef
   // → ai.templates) are deferred to runtime, which fails soft with the
   // capability-surface envelope. Tool-NAME existence runs only when the mcp
@@ -1973,7 +1973,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// PLANNER GROUNDING (roadmap §4.6.E; docs/ai-planner-design.md §2).
+// PLANNER GROUNDING (https://vxil.com/docs/guide/10-agents-and-mcp).
 // FEATURE_KEYS is the literal feature list the planner catalog is projected
 // from; the planner-catalog CI gate asserts set-equality with
 // Object.keys(FEATURE_SCHEMAS), so adding a feature without extending this

package/src/readmodels.ts

@@ -1,4 +1,4 @@
-// cms-rel B5/E config-write gates (docs/cms-relational-depth-options.md §3/§4)
+// cms-rel B5/E config-write gates (read models + transactions — https://vxil.com/docs/guide/04-data-with-cms)
 // — the hooks.ts sibling: PURE structural validation of the `readModels` and
 // `cdc` bags at config-write time (the anti-malice-gate pattern). The grammar
 // (fn/rank allow-lists, arity caps, window bounds, dotted-term shape) is