@vxil/config 0.2.0 → 0.3.1

package/README.md

@@ -0,0 +1,72 @@
+# @vxil/config
+
+`defineConfig()` — one typed source of truth for a whole Vxil backend.
+
+A `vxil.config.ts` in your repo declares every feature you have enabled, your
+CMS content model, your deployed functions, your secret *references* and your
+seed data. `vxil push` compiles it to a manifest and applies it. Nothing in this
+file is ever executed by Vxil — config is data.
+
+```bash
+npm i -D @vxil/config
+```
+
+> The CLI that reads this file is **`@vxil/cli`** (it installs the `vxil`
+> command). The bare `vxil` package name is blocked on npm — never `npm i vxil`.
+
+## Use it
+
+```ts
+// vxil.config.ts
+import { defineConfig } from '@vxil/config';
+
+export default defineConfig({
+  features: {
+    cms: { enabled: true },
+    files: { enabled: true },
+    notifications: { enabled: true, fromEmail: 'noreply@acme.com' },
+  },
+  cms: {
+    collections: {
+      posts: {
+        fields: {
+          title: { type: 'string', required: true, indexSlot: 's1' },
+          body: { type: 'text' },
+        },
+      },
+    },
+  },
+});
+```
+
+```bash
+npx @vxil/cli plan      # dry-run diff against the live tenant
+npx @vxil/cli push      # apply, idempotent
+npx @vxil/cli gen       # emit the per-tenant typed client
+```
+
+## What it gives you
+
+- **Real autocomplete.** `defineConfig` is a typed identity function: it returns
+  its argument verbatim, and the types come from
+  [`@vxil/feature-configs`](https://www.npmjs.com/package/@vxil/feature-configs),
+  the same schemas the platform validates against. A knob that does not exist is
+  a compile error in your editor, not a 422 at push time.
+- **The whole backend in one file.** Features, the CMS content model (collections,
+  field types, index slots, uniqueness, lifecycle hook expressions), functions,
+  secret references and seed data — one declarative object.
+- **Secrets by reference, never by value.** A config carries `secret:<name>`; the
+  value is set once with `vxil secrets set` and never lands in your repo.
+- **Versioned, concurrent-safe applies.** Every push is an If-Match write against
+  an immutable config version, so two people (or a person and CI) cannot silently
+  clobber each other — and `vxil versions` / `vxil rollback` undo one.
+
+## Related
+
+- [`@vxil/cli`](https://www.npmjs.com/package/@vxil/cli) — the `vxil` command.
+- [`@vxil/feature-configs`](https://www.npmjs.com/package/@vxil/feature-configs) — the feature schemas and their `Static<>` types.
+- [`@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/index.d.ts

@@ -23,9 +23,34 @@ export interface FieldDef {
      *  cannot reconcile surface as a visible plan warning, never a silent no-op. */
     unique?: boolean;
     /** Per-relation-field delete behavior (cms.md §11): bounded, atomic fan-out
-     *  when the referenced item is deleted. Same carriage + reconcile behavior
-     *  as `unique`. */
-    onDelete?: 'cascade' | 'set_null';
+     *  when the referenced item is deleted — or `restrict` (§11.1), which REFUSES
+     *  the delete with 409 `referenced` while a live reference exists. Same
+     *  carriage + reconcile behavior as `unique`. */
+    onDelete?: 'cascade' | 'set_null' | 'restrict';
+    /** FIELD-LEVEL READ SECURITY (cms.md §18): the end-user ORG ROLE slugs allowed
+     *  to READ this field. Omitted/`[]` = ungated (every caller sees it — today's
+     *  behavior). A non-empty list is FAIL-SAFE: in VERIFIED end-user mode the
+     *  field is OMITTED from every read (get / list / query / `$expand` at any
+     *  depth / the write-response echo / read-hook payloads) unless the session's
+     *  verified `roles` claim intersects the list, it is UNQUERYABLE (a filter /
+     *  sort / group-by naming it is a 422, so it cannot be a value oracle), and it
+     *  is NEVER served on the anonymous public lane. A trusted SERVER caller (an
+     *  API key with no end-user session) still sees every field — this gates END
+     *  USERS, not the tenant. ≤16 entries, each `^[a-z0-9][a-z0-9_-]{0,31}$` (the
+     *  `orgs` role alphabet). The gate
+     *  never affects WRITES. Carried by BOTH push paths and alterable in place. */
+    readRoles?: string[];
+}
+/** One config-declared per-record ACTION button (cms.md §17): exactly ONE
+ *  human-initiated step — pressing it invokes the deployed tenant function `fn`
+ *  with `{ collection, item_id, action, actor, item }` and returns its result.
+ *  No conditions, no chaining, no scheduling. `key` matches
+ *  /^[a-z][a-z0-9_]{0,31}$/, `fn` is a function name (/^[a-z][a-z0-9-]{0,47}$/),
+ *  ≤8 per collection. */
+export interface CmsActionDef {
+    key: string;
+    label: string;
+    fn: string;
 }
 /** The CANONICAL field-attribute name set (config-side spelling), DERIVED from
  *  `FieldDef` itself so it can never drift from the authoring type: it is every
@@ -51,7 +76,7 @@ export type CoversFieldAttrs<Covered extends FieldAttrName> = [
 export interface CollectionDef {
     singular?: string;
     fields: Record<string, FieldDef>;
-    /** End-user owner-scoping (docs/end-user-principals-design.md §5.1): names an
+    /** End-user owner-scoping (https://vxil.com/docs/guide/09-security-and-multitenancy): names an
      *  existing `string` field on this collection that holds the owner (end-user)
      *  id. When set, the cms worker auto-scopes owned reads/writes to the VERIFIED
      *  end-user principal in end-user mode (default-deny) — and is a no-op in
@@ -66,10 +91,24 @@ export interface CollectionDef {
      *  with a regression test on each — an attribute read by no enforcing path ships
      *  inert (the validation.unique / owner_field precedent). */
     public?: boolean;
+    /** Per-record action buttons (cms.md §17): `[{ 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/
+     *  :key` invokes `fn` once. Carried by BOTH push paths (create + reconcile on
+     *  existing collections — config is the source of truth; `[]`/absent clears). */
+    actions?: CmsActionDef[];
 }
+/** The auth lifecycle events an `authHook` binding may subscribe to (F4-30,
+ * auth wave 2026-09-10) — a CLOSED union; ONE event per binding, one audit
+ * event → one function invocation, no branching inside vxil:
+ *   user.created    — auth.user.created  { user_id, method, is_anonymous }
+ *   session.created — auth.session.created { user_id, session_id }
+ *   session.revoked — auth.session.revoked { user_id, session_id, reason }
+ *   signin.failure  — auth.signin.failure { email_hash | user_id, reason } */
+export type AuthHookEvent = 'user.created' | 'session.created' | 'session.revoked' | 'signin.failure';
 /** A function trigger (the §7.3 crossing). cmsHook fires on a CMS write;
- * authHook is the post-signup hook (fires on `auth.user.created`,
- * at-least-once, ~1min fanout latency). */
+ * authHook fires on ONE auth lifecycle event (default `user.created` — the
+ * post-signup hook; at-least-once, ~1min fanout latency). */
 export type FunctionTrigger = {
     kind: 'http';
     path?: string;
@@ -88,7 +127,7 @@ export type FunctionTrigger = {
     event: 'beforeCreate' | 'beforeUpdate' | 'beforeWrite';
 } | {
     kind: 'authHook';
-    event?: 'user.created';
+    event?: AuthHookEvent;
 };
 /** A deployed tenant function — source in functions/, deployed on `vxil push`. */
 export interface FunctionDef {
@@ -99,9 +138,9 @@ export interface FunctionDef {
      *  functions:write, secrets:write rejected; payments:write / notifications:send /
      *  users:* allowed as owner-granted business scopes). */
     scopes?: string[];
-    /** tenant_secrets refs injected under KEK_FUNCTIONS (productization). */
+    /** Names of tenant secrets injected into the function at invoke time. */
     secrets?: string[];
-    /** Outbound-Worker host allowlist (deny-by-default egress guard). */
+    /** Outbound host allowlist (deny-by-default egress guard). */
     egressAllow?: string[];
     limits?: {
         cpuMs?: number;
@@ -132,7 +171,7 @@ export interface SeedSpec {
         email?: string;
     }[];
 }
-/** The released API majors (docs/feature-versioning.md §3), a CLOSED union —
+/** The released API majors (see https://vxil.com/docs/guide/12-going-to-production), a CLOSED union —
  *  `'v1'` is the only released major, so `apiVersion: 'v2'` is a COMPILE error
  *  until a v2 GAs. `defineConfig` also validates it at runtime against
  *  `RELEASED_API_VERSIONS`. */
@@ -144,7 +183,7 @@ export declare const RELEASED_API_VERSIONS: readonly ApiVersion[];
 export interface VxilConfig {
     /** target environment label; resolved to a baseUrl by `vxil link` / `--env`. */
     env?: string;
-    /** Pin the API major the CLI targets (default `'v1'`, docs/feature-versioning.md).
+    /** Pin the API major the CLI targets (default `'v1'`; see https://vxil.com/docs/guide/12-going-to-production).
      *  Path-major, per-platform: a breaking change ships as a new major on a new
      *  path with a ≥6-month deprecation window. `VXIL_API_VERSION` overrides this
      *  for a one-off invocation. */

package/dist/index.js

@@ -9,7 +9,7 @@ export function defineConfig(c) {
     if (c.apiVersion !== undefined && !RELEASED_API_VERSIONS.includes(c.apiVersion)) {
         throw new Error(`vxil.config: apiVersion '${String(c.apiVersion)}' is not a released API major ` +
             `(released: ${RELEASED_API_VERSIONS.map((v) => `'${v}'`).join(', ')}). ` +
-            'A new major ships as a new path with its own deprecation window — see docs/feature-versioning.md.');
+            'A new major ships as a new path with its own deprecation window — see https://vxil.com/docs/guide/12-going-to-production.');
     }
     return c;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vxil/config",
-  "version": "0.2.0",
-  "description": "defineConfig() — one typed source of truth for a whole vxil backend (features + CMS schema + functions + secret refs + seed). INTERNAL workspace package: bundled into the published `vxil` package's `vxil/config` subpath, not published separately.",
+  "version": "0.3.1",
+  "description": "Typed vxil.config.ts authoring for the vxil backend platform — defineConfig, feature and cms field definitions (published for @vxil/cli).",
   "license": "MIT",
   "homepage": "https://vxil.com",
   "repository": {
@@ -22,7 +22,7 @@
     "src"
   ],
   "dependencies": {
-    "@vxil/feature-configs": "0.2.0"
+    "@vxil/feature-configs": "0.3.1"
   },
   "publishConfig": {
     "access": "public"

package/src/index.test.ts

@@ -23,6 +23,6 @@ describe('defineConfig', () => {
     expect(() => defineConfig({ apiVersion: 'v2' as 'v1', features: {} }))
       .toThrow(/apiVersion 'v2' is not a released API major/);
     expect(() => defineConfig({ apiVersion: 'latest' as 'v1' }))
-      .toThrow(/feature-versioning\.md/);
+      .toThrow(/docs\/guide\/12-going-to-production/);
   });
 });

package/src/index.ts

@@ -7,7 +7,7 @@
 // §7.3-consistent — config is DATA; the only tenant CODE that crosses into vxil
 // is (a) the Lane-A hook expressions (a closed sandbox) and (b) the functions/
 // sources (the paid, opt-in, egress-guarded crossing). Everything here is
-// declarative. See docs/vxil-cli-sdk-code-experience-design.md §3.
+// declarative. See https://vxil.com/docs/guide/05-typed-sdk-and-cli.
 import type {
   NotificationsConfig, JobsConfig, AuthConfig, RateLimitsConfig, FilesConfig,
   WebhooksConfig, CommentsConfig, CmsConfig, McpConfig, RealtimeConfig,
@@ -42,9 +42,35 @@ export interface FieldDef {
    *  cannot reconcile surface as a visible plan warning, never a silent no-op. */
   unique?: boolean;
   /** Per-relation-field delete behavior (cms.md §11): bounded, atomic fan-out
-   *  when the referenced item is deleted. Same carriage + reconcile behavior
-   *  as `unique`. */
-  onDelete?: 'cascade' | 'set_null';
+   *  when the referenced item is deleted — or `restrict` (§11.1), which REFUSES
+   *  the delete with 409 `referenced` while a live reference exists. Same
+   *  carriage + reconcile behavior as `unique`. */
+  onDelete?: 'cascade' | 'set_null' | 'restrict';
+  /** FIELD-LEVEL READ SECURITY (cms.md §18): the end-user ORG ROLE slugs allowed
+   *  to READ this field. Omitted/`[]` = ungated (every caller sees it — today's
+   *  behavior). A non-empty list is FAIL-SAFE: in VERIFIED end-user mode the
+   *  field is OMITTED from every read (get / list / query / `$expand` at any
+   *  depth / the write-response echo / read-hook payloads) unless the session's
+   *  verified `roles` claim intersects the list, it is UNQUERYABLE (a filter /
+   *  sort / group-by naming it is a 422, so it cannot be a value oracle), and it
+   *  is NEVER served on the anonymous public lane. A trusted SERVER caller (an
+   *  API key with no end-user session) still sees every field — this gates END
+   *  USERS, not the tenant. ≤16 entries, each `^[a-z0-9][a-z0-9_-]{0,31}$` (the
+   *  `orgs` role alphabet). The gate
+   *  never affects WRITES. Carried by BOTH push paths and alterable in place. */
+  readRoles?: string[];
+}
+
+/** One config-declared per-record ACTION button (cms.md §17): exactly ONE
+ *  human-initiated step — pressing it invokes the deployed tenant function `fn`
+ *  with `{ collection, item_id, action, actor, item }` and returns its result.
+ *  No conditions, no chaining, no scheduling. `key` matches
+ *  /^[a-z][a-z0-9_]{0,31}$/, `fn` is a function name (/^[a-z][a-z0-9-]{0,47}$/),
+ *  ≤8 per collection. */
+export interface CmsActionDef {
+  key: string;
+  label: string;
+  fn: string;
 }
 
 /** The CANONICAL field-attribute name set (config-side spelling), DERIVED from
@@ -72,7 +98,7 @@ export type CoversFieldAttrs<Covered extends FieldAttrName> =
 export interface CollectionDef {
   singular?: string;
   fields: Record<string, FieldDef>;
-  /** End-user owner-scoping (docs/end-user-principals-design.md §5.1): names an
+  /** End-user owner-scoping (https://vxil.com/docs/guide/09-security-and-multitenancy): names an
    *  existing `string` field on this collection that holds the owner (end-user)
    *  id. When set, the cms worker auto-scopes owned reads/writes to the VERIFIED
    *  end-user principal in end-user mode (default-deny) — and is a no-op in
@@ -87,18 +113,33 @@ export interface CollectionDef {
    *  with a regression test on each — an attribute read by no enforcing path ships
    *  inert (the validation.unique / owner_field precedent). */
   public?: boolean;
+  /** Per-record action buttons (cms.md §17): `[{ 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/
+   *  :key` invokes `fn` once. Carried by BOTH push paths (create + reconcile on
+   *  existing collections — config is the source of truth; `[]`/absent clears). */
+  actions?: CmsActionDef[];
 }
 
+/** The auth lifecycle events an `authHook` binding may subscribe to (F4-30,
+ * auth wave 2026-09-10) — a CLOSED union; ONE event per binding, one audit
+ * event → one function invocation, no branching inside vxil:
+ *   user.created    — auth.user.created  { user_id, method, is_anonymous }
+ *   session.created — auth.session.created { user_id, session_id }
+ *   session.revoked — auth.session.revoked { user_id, session_id, reason }
+ *   signin.failure  — auth.signin.failure { email_hash | user_id, reason } */
+export type AuthHookEvent = 'user.created' | 'session.created' | 'session.revoked' | 'signin.failure';
+
 /** A function trigger (the §7.3 crossing). cmsHook fires on a CMS write;
- * authHook is the post-signup hook (fires on `auth.user.created`,
- * at-least-once, ~1min fanout latency). */
+ * authHook fires on ONE auth lifecycle event (default `user.created` — the
+ * post-signup hook; at-least-once, ~1min fanout latency). */
 export type FunctionTrigger =
   | { kind: 'http'; path?: string }
   | { kind: 'cron'; schedule: string }
   | { kind: 'queue'; source: string }
   | { kind: 'webhook'; source: string }
   | { kind: 'cmsHook'; collection: string; event: 'beforeCreate' | 'beforeUpdate' | 'beforeWrite' }
-  | { kind: 'authHook'; event?: 'user.created' };
+  | { kind: 'authHook'; event?: AuthHookEvent };
 
 /** A deployed tenant function — source in functions/, deployed on `vxil push`. */
 export interface FunctionDef {
@@ -109,9 +150,9 @@ export interface FunctionDef {
    *  functions:write, secrets:write rejected; payments:write / notifications:send /
    *  users:* allowed as owner-granted business scopes). */
   scopes?: string[];
-  /** tenant_secrets refs injected under KEK_FUNCTIONS (productization). */
+  /** Names of tenant secrets injected into the function at invoke time. */
   secrets?: string[];
-  /** Outbound-Worker host allowlist (deny-by-default egress guard). */
+  /** Outbound host allowlist (deny-by-default egress guard). */
   egressAllow?: string[];
   limits?: { cpuMs?: number; timeoutMs?: number; memoryMb?: number };
   enabled?: boolean;
@@ -132,7 +173,7 @@ export interface SeedSpec {
   users?: { id: string; email?: string }[];
 }
 
-/** The released API majors (docs/feature-versioning.md §3), a CLOSED union —
+/** The released API majors (see https://vxil.com/docs/guide/12-going-to-production), a CLOSED union —
  *  `'v1'` is the only released major, so `apiVersion: 'v2'` is a COMPILE error
  *  until a v2 GAs. `defineConfig` also validates it at runtime against
  *  `RELEASED_API_VERSIONS`. */
@@ -147,7 +188,7 @@ export interface VxilConfig {
   /** target environment label; resolved to a baseUrl by `vxil link` / `--env`. */
   env?: string;
 
-  /** Pin the API major the CLI targets (default `'v1'`, docs/feature-versioning.md).
+  /** Pin the API major the CLI targets (default `'v1'`; see https://vxil.com/docs/guide/12-going-to-production).
    *  Path-major, per-platform: a breaking change ships as a new major on a new
    *  path with a ≥6-month deprecation window. `VXIL_API_VERSION` overrides this
    *  for a one-off invocation. */
@@ -204,7 +245,7 @@ export function defineConfig(c: VxilConfig): VxilConfig {
     throw new Error(
       `vxil.config: apiVersion '${String(c.apiVersion)}' is not a released API major ` +
         `(released: ${RELEASED_API_VERSIONS.map((v) => `'${v}'`).join(', ')}). ` +
-        'A new major ships as a new path with its own deprecation window — see docs/feature-versioning.md.',
+        'A new major ships as a new path with its own deprecation window — see https://vxil.com/docs/guide/12-going-to-production.',
     );
   }
   return c;