@vxil/config 0.3.0 → 0.4.0

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

@@ -76,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
@@ -118,7 +118,14 @@ export type FunctionTrigger = {
 } | {
     kind: 'queue';
     source: string;
-} | {
+}
+/** `webhook`: the function is woken by a webhook_subscription fan-out whose
+ *  target_url is `<edge>/v1/internal/fn/trigger/<name>?tenant=<id>`. `source` is
+ *  an event-name PREFIX filter (e.g. 'payments.'), enforced at delivery — a
+ *  non-matching event is ACK-200 skipped. Declaring the binding is what opts the
+ *  function into event delivery; a receiver that declares only `cron` keeps the
+ *  older cron+{} wake. */
+ | {
     kind: 'webhook';
     source: string;
 } | {
@@ -138,14 +145,38 @@ 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[];
+    /** Per-function resource declarations. Both optional; both clamped server-side.
+     *  `memoryMb` was REMOVED (2026-09-18): memory is fixed by the managed runtime
+     *  and is not per-dispatch selectable. A config that still declares it pushes
+     *  fine — the key is stripped, and `vxil plan --explain` marks it DROPPED. */
     limits?: {
+        /** per-dispatch isolate CPU ceiling, ms (5..300000). Only ever TIGHTENS the
+         *  platform cap.
+         *
+         *  IT ALSO RAISES YOUR BILL on a metered tenant, and that is worth reading
+         *  twice: it raises (never lowers) the per-invoke credit reserve, whose floor
+         *  is the manifest default — and the reserve is the CEILING the pro-rated
+         *  settle clamps into, because the settle can never commit more than the hold
+         *  it releases from. So an invoke whose wall time exceeds `defaultLimits.cpuMs`
+         *  (50) settles at its MEASURED wall-ms instead of being capped at 50:
+         *  declaring `cpuMs: 1000` makes an 800 ms invoke cost 800 instead of 50.
+         *  Declaring only `timeoutMs` leaves metering byte-identical.
+         *
+         *  It does NOT affect anyone else's availability: the account-wide daily
+         *  capacity budget counts the platform's own per-invoke estimate, never this
+         *  value (workers/functions-v1/src/capacity.ts `capacityReserveCpuMs`). */
         cpuMs?: number;
+        /** wall budget for ONE outbound fetch this function makes, ms (1000..120000,
+         *  default 30000). Not a whole-invocation budget: three 25 s fetches still
+         *  take 75 s. The invocation is bounded separately by the platform's own
+         *  deadline (`FN_MAX_INVOKE_MS`, default ≥ 5 minutes), which raising this
+         *  value widens with you. The vxil API callback leg keeps the platform's
+         *  own 30 s bound. */
         timeoutMs?: number;
-        memoryMb?: number;
     };
     enabled?: boolean;
     /** optional typed contract surfaced by `vxil gen` (Level 1, §4.5). */
@@ -171,7 +202,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`. */
@@ -183,7 +214,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.3.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.4.0",
+  "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.3.0"
+    "@vxil/feature-configs": "0.4.0"
   },
   "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,
@@ -98,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
@@ -137,6 +137,12 @@ export type FunctionTrigger =
   | { kind: 'http'; path?: string }
   | { kind: 'cron'; schedule: string }
   | { kind: 'queue'; source: string }
+  /** `webhook`: the function is woken by a webhook_subscription fan-out whose
+   *  target_url is `<edge>/v1/internal/fn/trigger/<name>?tenant=<id>`. `source` is
+   *  an event-name PREFIX filter (e.g. 'payments.'), enforced at delivery — a
+   *  non-matching event is ACK-200 skipped. Declaring the binding is what opts the
+   *  function into event delivery; a receiver that declares only `cron` keeps the
+   *  older cron+{} wake. */
   | { kind: 'webhook'; source: string }
   | { kind: 'cmsHook'; collection: string; event: 'beforeCreate' | 'beforeUpdate' | 'beforeWrite' }
   | { kind: 'authHook'; event?: AuthHookEvent };
@@ -150,11 +156,39 @@ 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 };
+  /** Per-function resource declarations. Both optional; both clamped server-side.
+   *  `memoryMb` was REMOVED (2026-09-18): memory is fixed by the managed runtime
+   *  and is not per-dispatch selectable. A config that still declares it pushes
+   *  fine — the key is stripped, and `vxil plan --explain` marks it DROPPED. */
+  limits?: {
+    /** per-dispatch isolate CPU ceiling, ms (5..300000). Only ever TIGHTENS the
+     *  platform cap.
+     *
+     *  IT ALSO RAISES YOUR BILL on a metered tenant, and that is worth reading
+     *  twice: it raises (never lowers) the per-invoke credit reserve, whose floor
+     *  is the manifest default — and the reserve is the CEILING the pro-rated
+     *  settle clamps into, because the settle can never commit more than the hold
+     *  it releases from. So an invoke whose wall time exceeds `defaultLimits.cpuMs`
+     *  (50) settles at its MEASURED wall-ms instead of being capped at 50:
+     *  declaring `cpuMs: 1000` makes an 800 ms invoke cost 800 instead of 50.
+     *  Declaring only `timeoutMs` leaves metering byte-identical.
+     *
+     *  It does NOT affect anyone else's availability: the account-wide daily
+     *  capacity budget counts the platform's own per-invoke estimate, never this
+     *  value (workers/functions-v1/src/capacity.ts `capacityReserveCpuMs`). */
+    cpuMs?: number;
+    /** wall budget for ONE outbound fetch this function makes, ms (1000..120000,
+     *  default 30000). Not a whole-invocation budget: three 25 s fetches still
+     *  take 75 s. The invocation is bounded separately by the platform's own
+     *  deadline (`FN_MAX_INVOKE_MS`, default ≥ 5 minutes), which raising this
+     *  value widens with you. The vxil API callback leg keeps the platform's
+     *  own 30 s bound. */
+    timeoutMs?: number;
+  };
   enabled?: boolean;
   /** optional typed contract surfaced by `vxil gen` (Level 1, §4.5). */
   signature?: { input?: unknown; output?: unknown };
@@ -173,7 +207,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`. */
@@ -188,7 +222,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. */
@@ -245,7 +279,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;