@vxil/config 0.3.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

@@ -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
@@ -138,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;
@@ -171,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`. */
@@ -183,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.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.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.3.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,
@@ -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
@@ -150,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;
@@ -173,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`. */
@@ -188,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. */
@@ -245,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;