@vxil/config 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+import type { NotificationsConfig, JobsConfig, AuthConfig, RateLimitsConfig, FilesConfig, WebhooksConfig, CommentsConfig, CmsConfig, McpConfig, RealtimeConfig, PresenceConfig, OrgsConfig, ActivityFeedConfig, VectorSearchConfig, AiConfig, RagConfig, PaymentsConfig, FunctionsConfig, CopilotConfig } from '@vxil/feature-configs';
+/** The 9 CMS field types (workers/cms-v1 core.ts FIELD_TYPES). */
+export type FieldType = 'string' | 'text' | 'int' | 'float' | 'bool' | 'datetime' | 'json' | 'relation' | 'file';
+/** The 8 fixed CMS index-slot columns (4 string · 2 numeric · 2 datetime). */
+export type IndexSlot = 's1' | 's2' | 's3' | 's4' | 'n1' | 'n2' | 't1' | 't2';
+/** A single CMS field declaration — mirrors the cms-v1 FieldInput wire shape. */
+export interface FieldDef {
+    type: FieldType;
+    required?: boolean;
+    validation?: Record<string, unknown>;
+    /** map to an index slot to make the field filterable-by-range / sortable. */
+    indexSlot?: IndexSlot;
+    /** required when type === 'relation' — the target collection slug. */
+    relationTo?: string;
+    computed?: boolean;
+    compute?: unknown;
+}
+/** A CMS collection-as-code: collection slug → fields. */
+export interface CollectionDef {
+    singular?: string;
+    fields: Record<string, FieldDef>;
+    /** End-user owner-scoping (docs/end-user-principals-design.md §5.1): 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
+     *  server-caller mode. NOT an RLS predicate; a single declarative flag the
+     *  typed worker consults. Omit for shared/reference collections. */
+    ownerField?: string;
+}
+/** 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). */
+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';
+};
+/** A deployed tenant function — source in functions/, deployed on `vxil push`. */
+export interface FunctionDef {
+    /** path to the ES-module entrypoint, e.g. ./functions/<name>.ts */
+    entry: string;
+    trigger?: FunctionTrigger;
+    /** clamped by DENY_FUNCTION_SCOPES at deploy (admin, wildcard, features:write,
+     *  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). */
+    secrets?: string[];
+    /** Outbound-Worker host allowlist (deny-by-default egress guard). */
+    egressAllow?: string[];
+    limits?: {
+        cpuMs?: number;
+        timeoutMs?: number;
+        memoryMb?: number;
+    };
+    enabled?: boolean;
+    /** optional typed contract surfaced by `vxil gen` (Level 1, §4.5). */
+    signature?: {
+        input?: unknown;
+        output?: unknown;
+    };
+}
+/** A secret REFERENCE (never a value). `vxil secrets set <name>` writes the value. */
+export interface SecretRef {
+    /** which feature's KEK the value is envelope-encrypted under. */
+    feature: string;
+    description?: string;
+}
+/** Optional deterministic seed, applied via the per-feature import bundle. */
+export interface SeedSpec {
+    cms?: {
+        collection: string;
+        items: Record<string, unknown>[];
+    }[];
+    users?: {
+        id: string;
+        email?: string;
+    }[];
+}
+/** The released API majors (docs/feature-versioning.md §3), 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`. */
+export type ApiVersion = 'v1';
+/** The released majors `defineConfig` validates `apiVersion` against. Widened
+ *  only by a real v2. */
+export declare const RELEASED_API_VERSIONS: readonly ApiVersion[];
+/** The whole vxil backend, declared in one typed, version-controlled file. */
+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).
+     *  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. */
+    apiVersion?: ApiVersion;
+    /** (a) PER-feature CONFIG — the same 15-leaf TypeBox manifests, validated by the
+     *  same Value.Default/Clean pipeline the server uses. Keys match FEATURE_SCHEMAS
+     *  exactly (note the hyphenated ids). */
+    features?: {
+        notifications?: Partial<NotificationsConfig>;
+        jobs?: Partial<JobsConfig>;
+        auth?: Partial<AuthConfig>;
+        'rate-limits'?: Partial<RateLimitsConfig>;
+        files?: Partial<FilesConfig>;
+        webhooks?: Partial<WebhooksConfig>;
+        comments?: Partial<CommentsConfig>;
+        cms?: Partial<CmsConfig>;
+        mcp?: Partial<McpConfig>;
+        realtime?: Partial<RealtimeConfig>;
+        presence?: Partial<PresenceConfig>;
+        orgs?: Partial<OrgsConfig>;
+        'activity-feed'?: Partial<ActivityFeedConfig>;
+        'vector-search'?: Partial<VectorSearchConfig>;
+        ai?: Partial<AiConfig>;
+        rag?: Partial<RagConfig>;
+        payments?: Partial<PaymentsConfig>;
+        functions?: Partial<FunctionsConfig>;
+        copilot?: Partial<CopilotConfig>;
+    };
+    /** (b) CMS SCHEMA-AS-CODE — collections + fields. `push` reconciles them
+     *  additively against GET /v1/cms/collections (no destructive drops without
+     *  --allow-destructive). Lane-A hooks stay in features.cms.hooks (config). */
+    cms?: {
+        collections?: Record<string, CollectionDef>;
+    };
+    /** (c) FUNCTIONS — name → trigger/scopes/egress/entry; sources in functions/. */
+    functions?: Record<string, FunctionDef>;
+    /** (d) SECRETS — REFERENCES ONLY, never values. */
+    secrets?: Record<string, SecretRef>;
+    /** (e) SEED DATA — optional. */
+    seed?: SeedSpec;
+}
+/** A typed identity function: returns its argument so the CLI can compile it.
+ *  The one runtime check is `apiVersion` — a mistyped/unreleased pin (possible
+ *  from JS callers with no compile gate, or a stale generated value) fails fast
+ *  here rather than 404-ing every request against a nonexistent major. */
+export declare function defineConfig(c: VxilConfig): VxilConfig;
+/** Authoring helper for split-out cms/<name>.ts collection modules (§6a).
+ *  `field('title', 'string', { required: true, indexSlot: 's1' })`. */
+export declare function field(type: FieldType, opts?: Omit<FieldDef, 'type'>): FieldDef;
+/** Authoring helper for a collection module: `export default collection({...})`. */
+export declare function collection(def: CollectionDef): CollectionDef;

package/dist/index.js

@@ -0,0 +1,24 @@
+/** The released majors `defineConfig` validates `apiVersion` against. Widened
+ *  only by a real v2. */
+export const RELEASED_API_VERSIONS = ['v1'];
+/** A typed identity function: returns its argument so the CLI can compile it.
+ *  The one runtime check is `apiVersion` — a mistyped/unreleased pin (possible
+ *  from JS callers with no compile gate, or a stale generated value) fails fast
+ *  here rather than 404-ing every request against a nonexistent major. */
+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.');
+    }
+    return c;
+}
+/** Authoring helper for split-out cms/<name>.ts collection modules (§6a).
+ *  `field('title', 'string', { required: true, indexSlot: 's1' })`. */
+export function field(type, opts = {}) {
+    return { type, ...opts };
+}
+/** Authoring helper for a collection module: `export default collection({...})`. */
+export function collection(def) {
+    return def;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@vxil/config",
+  "version": "0.1.0",
+  "description": "defineConfig() \u2014 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.",
+  "license": "MIT",
+  "homepage": "https://vxil.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/techmakerdev/vxil.git",
+    "directory": "packages/config"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "@vxil/feature-configs": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { defineConfig, RELEASED_API_VERSIONS } from './index.js';
+
+describe('defineConfig', () => {
+  it('is an identity function (returns its argument verbatim)', () => {
+    const cfg = { features: { cms: {} } };
+    expect(defineConfig(cfg)).toBe(cfg);
+  });
+
+  it('accepts the released apiVersion', () => {
+    const cfg = defineConfig({ apiVersion: 'v1', features: {} });
+    expect(cfg.apiVersion).toBe('v1');
+    expect(RELEASED_API_VERSIONS).toEqual(['v1']);
+  });
+
+  it('accepts a config without apiVersion (optional; defaults to v1 at the CLI)', () => {
+    expect(() => defineConfig({ features: {} })).not.toThrow();
+  });
+
+  it('throws on an unreleased apiVersion (fail-fast, actionable message)', () => {
+    // A JS caller (no compile gate) or a stale generated value must be rejected
+    // at load, not silently 404 every request.
+    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/);
+  });
+});

package/src/index.ts

@@ -0,0 +1,184 @@
+// @vxil/config — the typed source of truth for a whole vxil backend.
+//
+// `defineConfig` is a TYPED IDENTITY FUNCTION: it returns its argument verbatim
+// so `vxil push` can compile it to a JSON manifest. Type-checking happens in the
+// tenant's editor (real autocomplete from the @vxil/feature-configs Static<>
+// types); the control plane never executes this file. This keeps config-as-code
+// §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.
+import type {
+  NotificationsConfig, JobsConfig, AuthConfig, RateLimitsConfig, FilesConfig,
+  WebhooksConfig, CommentsConfig, CmsConfig, McpConfig, RealtimeConfig,
+  PresenceConfig, OrgsConfig, ActivityFeedConfig, VectorSearchConfig, AiConfig,
+  RagConfig, PaymentsConfig, FunctionsConfig, CopilotConfig,
+} from '@vxil/feature-configs';
+
+/** The 9 CMS field types (workers/cms-v1 core.ts FIELD_TYPES). */
+export type FieldType =
+  | 'string' | 'text' | 'int' | 'float' | 'bool' | 'datetime' | 'json' | 'relation' | 'file';
+
+/** The 8 fixed CMS index-slot columns (4 string · 2 numeric · 2 datetime). */
+export type IndexSlot = 's1' | 's2' | 's3' | 's4' | 'n1' | 'n2' | 't1' | 't2';
+
+/** A single CMS field declaration — mirrors the cms-v1 FieldInput wire shape. */
+export interface FieldDef {
+  type: FieldType;
+  required?: boolean;
+  validation?: Record<string, unknown>;
+  /** map to an index slot to make the field filterable-by-range / sortable. */
+  indexSlot?: IndexSlot;
+  /** required when type === 'relation' — the target collection slug. */
+  relationTo?: string;
+  computed?: boolean;
+  compute?: unknown;
+}
+
+/** A CMS collection-as-code: collection slug → fields. */
+export interface CollectionDef {
+  singular?: string;
+  fields: Record<string, FieldDef>;
+  /** End-user owner-scoping (docs/end-user-principals-design.md §5.1): 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
+   *  server-caller mode. NOT an RLS predicate; a single declarative flag the
+   *  typed worker consults. Omit for shared/reference collections. */
+  ownerField?: string;
+}
+
+/** 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). */
+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' };
+
+/** A deployed tenant function — source in functions/, deployed on `vxil push`. */
+export interface FunctionDef {
+  /** path to the ES-module entrypoint, e.g. ./functions/<name>.ts */
+  entry: string;
+  trigger?: FunctionTrigger;
+  /** clamped by DENY_FUNCTION_SCOPES at deploy (admin, wildcard, features:write,
+   *  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). */
+  secrets?: string[];
+  /** Outbound-Worker host allowlist (deny-by-default egress guard). */
+  egressAllow?: string[];
+  limits?: { cpuMs?: number; timeoutMs?: number; memoryMb?: number };
+  enabled?: boolean;
+  /** optional typed contract surfaced by `vxil gen` (Level 1, §4.5). */
+  signature?: { input?: unknown; output?: unknown };
+}
+
+/** A secret REFERENCE (never a value). `vxil secrets set <name>` writes the value. */
+export interface SecretRef {
+  /** which feature's KEK the value is envelope-encrypted under. */
+  feature: string;
+  description?: string;
+}
+
+/** Optional deterministic seed, applied via the per-feature import bundle. */
+export interface SeedSpec {
+  cms?: { collection: string; items: Record<string, unknown>[] }[];
+  users?: { id: string; email?: string }[];
+}
+
+/** The released API majors (docs/feature-versioning.md §3), 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`. */
+export type ApiVersion = 'v1';
+
+/** The released majors `defineConfig` validates `apiVersion` against. Widened
+ *  only by a real v2. */
+export const RELEASED_API_VERSIONS: readonly ApiVersion[] = ['v1'];
+
+/** The whole vxil backend, declared in one typed, version-controlled file. */
+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).
+   *  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. */
+  apiVersion?: ApiVersion;
+
+  /** (a) PER-feature CONFIG — the same 15-leaf TypeBox manifests, validated by the
+   *  same Value.Default/Clean pipeline the server uses. Keys match FEATURE_SCHEMAS
+   *  exactly (note the hyphenated ids). */
+  features?: {
+    notifications?: Partial<NotificationsConfig>;
+    jobs?: Partial<JobsConfig>;
+    auth?: Partial<AuthConfig>;
+    'rate-limits'?: Partial<RateLimitsConfig>;
+    files?: Partial<FilesConfig>;
+    webhooks?: Partial<WebhooksConfig>;
+    comments?: Partial<CommentsConfig>;
+    cms?: Partial<CmsConfig>;
+    mcp?: Partial<McpConfig>;
+    realtime?: Partial<RealtimeConfig>;
+    presence?: Partial<PresenceConfig>;
+    orgs?: Partial<OrgsConfig>;
+    'activity-feed'?: Partial<ActivityFeedConfig>;
+    'vector-search'?: Partial<VectorSearchConfig>;
+    ai?: Partial<AiConfig>;
+    rag?: Partial<RagConfig>;
+    payments?: Partial<PaymentsConfig>;
+    functions?: Partial<FunctionsConfig>;
+    copilot?: Partial<CopilotConfig>;
+  };
+
+  /** (b) CMS SCHEMA-AS-CODE — collections + fields. `push` reconciles them
+   *  additively against GET /v1/cms/collections (no destructive drops without
+   *  --allow-destructive). Lane-A hooks stay in features.cms.hooks (config). */
+  cms?: {
+    collections?: Record<string, CollectionDef>;
+  };
+
+  /** (c) FUNCTIONS — name → trigger/scopes/egress/entry; sources in functions/. */
+  functions?: Record<string, FunctionDef>;
+
+  /** (d) SECRETS — REFERENCES ONLY, never values. */
+  secrets?: Record<string, SecretRef>;
+
+  /** (e) SEED DATA — optional. */
+  seed?: SeedSpec;
+}
+
+/** A typed identity function: returns its argument so the CLI can compile it.
+ *  The one runtime check is `apiVersion` — a mistyped/unreleased pin (possible
+ *  from JS callers with no compile gate, or a stale generated value) fails fast
+ *  here rather than 404-ing every request against a nonexistent major. */
+export function defineConfig(c: VxilConfig): VxilConfig {
+  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.',
+    );
+  }
+  return c;
+}
+
+/** Authoring helper for split-out cms/<name>.ts collection modules (§6a).
+ *  `field('title', 'string', { required: true, indexSlot: 's1' })`. */
+export function field(
+  type: FieldType,
+  opts: Omit<FieldDef, 'type'> = {},
+): FieldDef {
+  return { type, ...opts };
+}
+
+/** Authoring helper for a collection module: `export default collection({...})`. */
+export function collection(def: CollectionDef): CollectionDef {
+  return def;
+}