@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.4

package/dist/lib/server/api/versioning.js

@@ -0,0 +1,231 @@
+import * as z from 'zod/v4';
+import { failureClass } from '../../failure-class';
+import { createErrorResponse } from './response';
+import { settle } from './settled';
+import { kitLogger } from '../../kit-logger';
+const logger = kitLogger('vibeskit-versioning');
+/**
+ * API Versioning Strategy for Vibes
+ *
+ * Supports multiple versioning methods:
+ * 1. URL path versioning: /api/v1/endpoint
+ * 2. Header versioning: Accept: application/vnd.vibes.v1+json
+ * 3. Query parameter: ?version=1
+ */
+export const CURRENT_VERSION = '1.0.0';
+export const SUPPORTED_VERSIONS = ['1.0.0'];
+export const DEFAULT_VERSION = '1.0.0';
+/**
+ * Parse version string into structured format
+ */
+export function parseVersion(versionString) {
+    const match = versionString.match(/^(\d+)\.(\d+)\.(\d+)$/);
+    if (!match) {
+        throw new Error(`Invalid version format: ${versionString}`);
+    }
+    const [, major, minor, patch] = match;
+    return {
+        major: parseInt(major, 10),
+        minor: parseInt(minor, 10),
+        patch: parseInt(patch, 10),
+        string: versionString
+    };
+}
+/**
+ * Compare two API versions
+ */
+export function compareVersions(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    return a.patch - b.patch;
+}
+/**
+ * Check if version is supported
+ */
+export function isVersionSupported(version) {
+    return SUPPORTED_VERSIONS.includes(version);
+}
+/**
+ * Extract API version from request
+ */
+export function extractVersion(event) {
+    // 1. Check URL path (/api/v1/...)
+    const pathMatch = event.url.pathname.match(/^\/api\/v(\d+(?:\.\d+\.\d+)?)/);
+    if (pathMatch) {
+        const versionStr = pathMatch[1].includes('.') ? pathMatch[1] : `${pathMatch[1]}.0.0`;
+        if (isVersionSupported(versionStr)) {
+            return parseVersion(versionStr);
+        }
+    }
+    // 2. Check Accept header (Accept: application/vnd.vibes.v1+json)
+    const acceptHeader = event.request.headers.get('accept');
+    if (acceptHeader) {
+        const headerMatch = acceptHeader.match(/application\/vnd\.vibes\.v(\d+(?:\.\d+\.\d+)?)\+json/);
+        if (headerMatch) {
+            const versionStr = headerMatch[1].includes('.') ? headerMatch[1] : `${headerMatch[1]}.0.0`;
+            if (isVersionSupported(versionStr)) {
+                return parseVersion(versionStr);
+            }
+        }
+    }
+    // 3. Check query parameter (?version=1.0.0)
+    const versionParam = event.url.searchParams.get('version');
+    if (versionParam && isVersionSupported(versionParam)) {
+        return parseVersion(versionParam);
+    }
+    // 4. Default to current version
+    return parseVersion(DEFAULT_VERSION);
+}
+/**
+ * Middleware to handle API versioning
+ */
+export function withVersioning(endpoints) {
+    return async (event) => {
+        const served = await settle(() => serveVersioned(endpoints, event));
+        if (!served.ok) {
+            logger.warn('Version handling failed', { reason: failureClass(served.error) });
+            return createErrorResponse('Error processing API version', 'VERSION_ERROR', 500);
+        }
+        return served.value;
+    };
+}
+async function serveVersioned(endpoints, event) {
+    const requestedVersion = extractVersion(event);
+    const endpointKey = `${event.request.method}:${event.route.id}`;
+    const versionedEndpoints = endpoints.get(endpointKey);
+    if (!versionedEndpoints) {
+        return createErrorResponse('Endpoint not found', 'ENDPOINT_NOT_FOUND', 404);
+    }
+    // Find exact version match
+    let matchingEndpoint = versionedEndpoints.find((ep) => compareVersions(ep.version, requestedVersion) === 0);
+    // If no exact match, find highest compatible version
+    if (!matchingEndpoint) {
+        const compatibleEndpoints = versionedEndpoints
+            .filter((ep) => compareVersions(ep.version, requestedVersion) <= 0)
+            .sort((a, b) => compareVersions(b.version, a.version));
+        matchingEndpoint = compatibleEndpoints[0];
+    }
+    if (!matchingEndpoint) {
+        return createErrorResponse(`API version ${requestedVersion.string} is not supported`, 'UNSUPPORTED_VERSION', 400);
+    }
+    // Add deprecation warnings
+    const response = await matchingEndpoint.handler(event);
+    if (matchingEndpoint.deprecated) {
+        response.headers.set('Warning', '299 - "This API version is deprecated"');
+        if (matchingEndpoint.deprecationDate) {
+            response.headers.set('Deprecation', matchingEndpoint.deprecationDate.toUTCString());
+        }
+        if (matchingEndpoint.sunsetDate) {
+            response.headers.set('Sunset', matchingEndpoint.sunsetDate.toUTCString());
+        }
+    }
+    // Add version information to response headers
+    response.headers.set('API-Version', matchingEndpoint.version.string);
+    response.headers.set('API-Supported-Versions', SUPPORTED_VERSIONS.join(', '));
+    return response;
+}
+/**
+ * Create versioned endpoint registration
+ */
+export function createVersionedEndpoint(version, handler, options = {}) {
+    return {
+        version: parseVersion(version),
+        handler,
+        ...options
+    };
+}
+/**
+ * Migration utilities for version upgrades
+ */
+export class VersionMigrator {
+    migrations = new Map();
+    /**
+     * Register a migration function for version transition
+     */
+    registerMigration(fromVersion, toVersion, migrator) {
+        const key = `${fromVersion}->${toVersion}`;
+        this.migrations.set(key, migrator);
+    }
+    /**
+     * Migrate data from one version to another
+     */
+    migrate(data, fromVersion, toVersion) {
+        const key = `${fromVersion}->${toVersion}`;
+        const migrator = this.migrations.get(key);
+        if (!migrator) {
+            throw new Error(`No migration path from version ${fromVersion} to ${toVersion}`);
+        }
+        return migrator(data);
+    }
+    /**
+     * Auto-migrate through multiple versions if needed
+     */
+    autoMigrate(data, fromVersion, toVersion) {
+        const from = parseVersion(fromVersion);
+        const to = parseVersion(toVersion);
+        if (compareVersions(from, to) === 0) {
+            return data; // No migration needed
+        }
+        // For now, we only support direct migrations
+        // In the future, we could implement path-finding for multi-step migrations
+        return this.migrate(data, fromVersion, toVersion);
+    }
+}
+/**
+ * Create the global version migrator instance
+ */
+export const globalMigrator = new VersionMigrator();
+// A payload gains the new field; a record keeps its own fields, any other value becomes just the field.
+const withNewField = z
+    .looseObject({})
+    .catch({})
+    .transform((record) => ({ ...record, newField: 'defaultValue' }));
+// Register example migrations
+globalMigrator.registerMigration('1.0.0', '1.1.0', (data) => {
+    // Example: Add new field with default value
+    const items = z.array(withNewField).safeParse(data);
+    return items.success ? items.data : withNewField.parse(data);
+});
+/**
+ * Utility to get version info for documentation
+ */
+export function getVersionInfo() {
+    const deprecated = []; // Will be populated as versions are deprecated
+    return {
+        current: CURRENT_VERSION,
+        supported: SUPPORTED_VERSIONS,
+        deprecated
+    };
+}
+/**
+ * Content negotiation helper
+ */
+export function negotiateContentType(acceptHeader) {
+    if (!acceptHeader) {
+        return { type: 'json' };
+    }
+    // Check for versioned content types
+    const versionedJsonMatch = acceptHeader.match(/application\/vnd\.vibes\.v(\d+(?:\.\d+\.\d+)?)\+json/);
+    if (versionedJsonMatch) {
+        return {
+            type: 'json',
+            version: versionedJsonMatch[1].includes('.')
+                ? versionedJsonMatch[1]
+                : `${versionedJsonMatch[1]}.0.0`
+        };
+    }
+    // Standard content types
+    if (acceptHeader.includes('application/json')) {
+        return { type: 'json' };
+    }
+    if (acceptHeader.includes('application/xml') || acceptHeader.includes('text/xml')) {
+        return { type: 'xml' };
+    }
+    if (acceptHeader.includes('application/yaml') || acceptHeader.includes('text/yaml')) {
+        return { type: 'yaml' };
+    }
+    // Default to JSON
+    return { type: 'json' };
+}

package/dist/lib/server/api-presets.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Quick-start endpoint configuration presets and config combiners.
+ *
+ * Split out from `server/index.ts` so that barrel can stay a pure
+ * re-export shape — siblings like `helpers/index.ts`, `hooks/index.ts`,
+ * and `handles/index.ts` all emit `.d.ts` cleanly under svelte-package
+ * because they only re-export. `quick`/`combine` are this package's only
+ * original-content exports in the server tree.
+ */
+import type { ValidationConfig, CachingConfig, BillingConfig, VibesConfig } from '../types';
+/**
+ * Quick-start helpers for common patterns.
+ *
+ * Each method returns a `Partial<VibesConfig>` — explicit return-type
+ * annotations are load-bearing for declaration emit. Without them,
+ * `svelte-package` / `svelte2tsx` resolves the type by walking the
+ * inference graph through `auth.*`/`rateLimit.*`/etc., and silently
+ * skips emitting `dist/server/api-presets.d.ts` (a confirmed
+ * upstream svelte2tsx behavior — see commit message). Pattern matches
+ * the sibling `helpers/auth.ts` which has `export const auth: AuthHelper`
+ * for the same reason.
+ */
+export interface QuickPresets {
+    public: () => Partial<VibesConfig>;
+    auth: () => Partial<VibesConfig>;
+    admin: () => Partial<VibesConfig>;
+    ai: () => Partial<VibesConfig>;
+    chat: () => Partial<VibesConfig>;
+    upload: () => Partial<VibesConfig>;
+    search: () => Partial<VibesConfig>;
+    read: (resourceType: string, paramName?: string) => Partial<VibesConfig>;
+    write: (permissions: string[]) => Partial<VibesConfig>;
+    list: (permissions?: string[]) => Partial<VibesConfig>;
+}
+export declare const quick: QuickPresets;
+/**
+ * Combine multiple configurations
+ */
+export declare const combine: {
+    /** Merge multiple vibes configs */
+    configs: (...configs: Partial<VibesConfig>[]) => VibesConfig;
+    /** Add validation to existing config */
+    withValidation: (config: VibesConfig, validation: ValidationConfig) => VibesConfig;
+    /** Add caching to existing config */
+    withCache: (config: VibesConfig, caching: CachingConfig) => VibesConfig;
+    /** Add billing to existing config */
+    withBilling: (config: VibesConfig, billing: BillingConfig) => VibesConfig;
+};

package/dist/lib/server/api-presets.js

@@ -0,0 +1,94 @@
+import { auth, rateLimit, rateLimitPatterns, cache, cachePatterns, billingPatterns, body, query, params } from './helpers';
+export const quick = {
+    /** Public endpoint with standard rate limiting */
+    public: () => ({
+        auth: auth.public(),
+        rateLimit: rateLimit.standard()
+    }),
+    /** Authenticated endpoint with standard setup - NO caching by default for safety */
+    auth: () => ({
+        auth: auth.required(),
+        rateLimit: rateLimit.standard()
+    }),
+    /** Admin-only endpoint */
+    admin: () => ({
+        auth: auth.adminOnly(),
+        rateLimit: rateLimit.generous()
+    }),
+    /** AI generation endpoint with billing */
+    ai: () => ({
+        auth: auth.required(),
+        rateLimit: rateLimitPatterns.aiGeneration(),
+        billing: billingPatterns.aiTextGeneration(),
+        validation: { body: body.textContent }
+    }),
+    /** Chat endpoint with real-time features */
+    chat: () => ({
+        auth: auth.required(),
+        rateLimit: rateLimitPatterns.chatMessages(),
+        caching: cache.none()
+    }),
+    /** File upload endpoint */
+    upload: () => ({
+        auth: auth.required(),
+        rateLimit: rateLimitPatterns.fileUpload()
+    }),
+    /** Search endpoint with caching */
+    search: () => ({
+        auth: auth.required(),
+        rateLimit: rateLimitPatterns.search(),
+        caching: cachePatterns.searchResults(),
+        validation: { query: query.search }
+    }),
+    /** CRUD read endpoint — caller's own resource (`<resourceType>:read:own`). */
+    read: (resourceType, _paramName = 'id') => ({
+        auth: auth.permissions([`${resourceType}:read:own`]),
+        rateLimit: rateLimit.standard(),
+        caching: cache.medium(),
+        validation: { params: params.id }
+    }),
+    /** CRUD write endpoint */
+    write: (permissions) => ({
+        auth: auth.permissions(permissions),
+        rateLimit: rateLimit.standard(),
+        validation: { body: body.nameDescription }
+    }),
+    /** List/pagination endpoint */
+    list: (permissions) => ({
+        auth: permissions ? auth.permissions(permissions) : auth.required(),
+        rateLimit: rateLimit.generous(),
+        caching: cache.medium(),
+        validation: { query: query.pagination }
+    })
+};
+/**
+ * Combine multiple configurations
+ */
+export const combine = {
+    /** Merge multiple vibes configs */
+    configs: (...configs) => {
+        return configs.reduce((merged, config) => ({
+            ...merged,
+            ...config,
+            auth: config.auth ? { ...merged.auth, ...config.auth } : merged.auth,
+            validation: config.validation
+                ? { ...merged.validation, ...config.validation }
+                : merged.validation
+        }), {});
+    },
+    /** Add validation to existing config */
+    withValidation: (config, validation) => ({
+        ...config,
+        validation: { ...config.validation, ...validation }
+    }),
+    /** Add caching to existing config */
+    withCache: (config, caching) => ({
+        ...config,
+        caching
+    }),
+    /** Add billing to existing config */
+    withBilling: (config, billing) => ({
+        ...config,
+        billing
+    })
+};

package/dist/lib/server/app-bootstrap.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Canonical per-app vibeskit bootstrap preset.
+ *
+ * Every first-party web app (its `src/lib/app/vibeskit.ts`) used to
+ * carry a hand-rolled copy of the same `createVibesKit` block: a passthrough
+ * auth handler, the account-web billing adapter under the internal service
+ * token, the auth permissions adapter under `VIBES_AUTH_INTERNAL_TOKEN`, and
+ * optional Cloudflare Service Bindings. Fixes (lazy origin thunks, the
+ * AUTH_SERVICE binding, the init-crash guard) had to be hand-propagated to
+ * each copy. This preset owns that shape once; apps keep only their genuine
+ * variations as options.
+ *
+ * The preset is config/server-load safe: it never reads `$env/dynamic/*`,
+ * `import.meta.env`, or any SvelteKit app module — origins are passed in as
+ * plain strings or thunks (receiving the request's runtime port) by the
+ * consuming app.
+ *
+ * VIBES_AUTH_INTERNAL_TOKEN is required for cross-service auth permission
+ * calls when `authOrigin` is provided. The token is resolved per request
+ * through `runtime.resolveCredential`; an unresolved credential throws its
+ * typed error (no empty-token request is ever sent). Provision it in every
+ * deployment environment.
+ *
+ * [INSTRUMENTATION] The kit is created at module instantiation via the
+ * side-effect import in each app's `hooks.server.ts`. A throw there crashes
+ * the isolate before SvelteKit's error path exists → blind
+ * `scriptThrewException` with no stack. `createAppVibesKit` wraps the build
+ * so the stack is logged under a grep-able marker (`VIBES-INIT-CRASH <slug>`)
+ * before it propagates.
+ */
+import type { Handle } from '@sveltejs/kit';
+import type { Logger, VibesKit, VibesKitConfig } from '../types/kit.js';
+import type { VibesKitRuntimePort } from './locals.js';
+import { type KitLoggerFactory } from './runtime-bound-logger.js';
+/**
+ * An origin as a plain string, or a thunk resolved per call with the request's
+ * runtime port (may be async). Apps have no runtime at module load and must
+ * not read `$env`. Pass the catalog origin, e.g.
+ * `(runtime) => kitCatalogAppOrigin('account', kitCatalogEnvironmentId(runtime))`,
+ * or a host overlay `runtime.getEnv('PUBLIC_VIBES_ACCOUNT_ORIGIN')` falling
+ * through to that catalog default. Omit the option to skip the adapter.
+ */
+export type AppVibesKitOrigin = string | ((runtime: VibesKitRuntimePort) => string | Promise<string>);
+export { kitCatalogAppOrigin, kitCatalogEnvironmentId, loadKitConfig, loadKitConfigDefaults } from '../config/kit.config.descriptor.ts';
+export interface CreateAppVibesKitOptions<Runtime extends VibesKitRuntimePort = VibesKitRuntimePort> {
+    /** App slug used in the `VIBES-INIT-CRASH <slug>` init-failure marker. */
+    slug: string;
+    /**
+     * Routes that skip the auth redirect (globs supported). Default `['/']`.
+     */
+    publicRoutes?: string[];
+    /** Post-auth redirect target. Default `'/'`. */
+    redirectTo?: string;
+    /**
+     * Auth handler to compose with the kit. Default is a passthrough that
+     * just resolves the event — apps that own their session handle in
+     * `hooks.server.ts` (or ARE the identity surface) use the default.
+     */
+    authHandler?: Handle;
+    /**
+     * account-web origin for the billing adapter. Omit to skip the billing
+     * service entirely (identity surfaces like auth-web).
+     */
+    accountOrigin?: AppVibesKitOrigin;
+    /**
+     * Auth origin for the permissions adapter. Omit to skip the auth
+     * permissions service entirely.
+     */
+    authOrigin?: AppVibesKitOrigin;
+    /**
+     * Include the `ACCOUNT_SERVICE` Cloudflare Service Binding thunk on the
+     * billing adapter (falls back to public-HTTPS fetch when absent — local
+     * dev, non-CF runtimes). Default `true`.
+     */
+    useAccountServiceBinding?: boolean;
+    /**
+     * Include the `AUTH_SERVICE` Cloudflare Service Binding thunk on the
+     * permissions adapter (declared in wrangler.jsonc as
+     * `services: [{ binding: "AUTH_SERVICE", service: "vibes-auth" }]`).
+     * Default `false`.
+     */
+    useAuthServiceBinding?: boolean;
+    /** Billing configuration passthrough (e.g. `canonicalTiers`). */
+    billing?: NonNullable<VibesKitConfig['billing']>;
+    /**
+     * Logger injected into the kit (`services.logger`); every kit module logs
+     * through it. Pass a `Logger`, or a factory for a logger that belongs to a
+     * runtime (`(runtime) => getLogger('vibeskit', runtime)`): the kit has no
+     * runtime at module load, so it resolves the factory on the first runtime the
+     * host hands it (once per runtime) and drops entries before that. Omit for a
+     * silent kit.
+     */
+    logger?: Logger | KitLoggerFactory<Runtime>;
+}
+/**
+ * Build the standard first-party-app vibeskit instance: passthrough auth,
+ * account billing + auth permissions adapters under the shared internal
+ * service tokens, optional service bindings, wrapped in the
+ * `VIBES-INIT-CRASH <slug>` guard. See the module doc for the full contract.
+ */
+export declare function createAppVibesKit<Runtime extends VibesKitRuntimePort = VibesKitRuntimePort>(options: CreateAppVibesKitOptions<Runtime>): VibesKit;

package/dist/lib/server/app-bootstrap.js

@@ -0,0 +1,115 @@
+/**
+ * Canonical per-app vibeskit bootstrap preset.
+ *
+ * Every first-party web app (its `src/lib/app/vibeskit.ts`) used to
+ * carry a hand-rolled copy of the same `createVibesKit` block: a passthrough
+ * auth handler, the account-web billing adapter under the internal service
+ * token, the auth permissions adapter under `VIBES_AUTH_INTERNAL_TOKEN`, and
+ * optional Cloudflare Service Bindings. Fixes (lazy origin thunks, the
+ * AUTH_SERVICE binding, the init-crash guard) had to be hand-propagated to
+ * each copy. This preset owns that shape once; apps keep only their genuine
+ * variations as options.
+ *
+ * The preset is config/server-load safe: it never reads `$env/dynamic/*`,
+ * `import.meta.env`, or any SvelteKit app module — origins are passed in as
+ * plain strings or thunks (receiving the request's runtime port) by the
+ * consuming app.
+ *
+ * VIBES_AUTH_INTERNAL_TOKEN is required for cross-service auth permission
+ * calls when `authOrigin` is provided. The token is resolved per request
+ * through `runtime.resolveCredential`; an unresolved credential throws its
+ * typed error (no empty-token request is ever sent). Provision it in every
+ * deployment environment.
+ *
+ * [INSTRUMENTATION] The kit is created at module instantiation via the
+ * side-effect import in each app's `hooks.server.ts`. A throw there crashes
+ * the isolate before SvelteKit's error path exists → blind
+ * `scriptThrewException` with no stack. `createAppVibesKit` wraps the build
+ * so the stack is logged under a grep-able marker (`VIBES-INIT-CRASH <slug>`)
+ * before it propagates.
+ */
+import { settleNow } from '../attempt.js';
+import { createVibesKit } from '../instance.js';
+import { failureAsError } from './hooks/errors.js';
+import { createRuntimeBoundLogger, isRuntimeBoundLogger } from './runtime-bound-logger.js';
+import { createAccountBillingAdapter } from './services/account-billing-adapter.js';
+import { createAuthPermissionsAdapter } from './services/auth-permissions-adapter.js';
+import { ServiceBindingSchema } from './services/service-binding-runtime.js';
+export { kitCatalogAppOrigin, kitCatalogEnvironmentId, loadKitConfig, loadKitConfigDefaults } from "../config/kit.config.descriptor.js";
+/** Resolve a credential through the handed runtime; a failure throws its typed error. */
+async function resolveSecret(runtime, key) {
+    const result = await runtime.resolveCredential({ source: 'secret', key });
+    if (!result.ok)
+        throw result.error;
+    return result.value;
+}
+/**
+ * Build the standard first-party-app vibeskit instance: passthrough auth,
+ * account billing + auth permissions adapters under the shared internal
+ * service tokens, optional service bindings, wrapped in the
+ * `VIBES-INIT-CRASH <slug>` guard. See the module doc for the full contract.
+ */
+export function createAppVibesKit(options) {
+    const { slug, publicRoutes = ['/'], redirectTo = '/', authHandler: composedAuthHandler = ({ event, resolve }) => resolve(event), accountOrigin, authOrigin, useAccountServiceBinding = true, useAuthServiceBinding = false, billing, logger: declaredLogger } = options;
+    const logger = declaredLogger === undefined
+        ? undefined
+        : 'warn' in declaredLogger
+            ? declaredLogger
+            : createRuntimeBoundLogger(declaredLogger);
+    // The kit learns its runtime from the first handed one: every adapter call and
+    // every request through the handle chain carries it.
+    const bindLogger = (runtime) => {
+        if (isRuntimeBoundLogger(logger) && runtime)
+            logger.bind(runtime);
+    };
+    const authHandler = (input) => {
+        const locals = input.event.locals;
+        bindLogger(locals.runtime);
+        return composedAuthHandler(input);
+    };
+    const services = {};
+    if (accountOrigin !== undefined) {
+        const billingOptions = {
+            accountOrigin,
+            serviceToken: (runtime) => {
+                bindLogger(runtime);
+                return resolveSecret(runtime, 'VIBES_INTERNAL_SERVICE_TOKEN');
+            }
+        };
+        if (useAccountServiceBinding) {
+            billingOptions.accountBinding = (runtime) => runtime.getBinding('ACCOUNT_SERVICE', ServiceBindingSchema);
+        }
+        services.billing = createAccountBillingAdapter(billingOptions);
+    }
+    if (authOrigin !== undefined) {
+        const authOptions = {
+            authOrigin,
+            serviceToken: (runtime) => {
+                bindLogger(runtime);
+                return resolveSecret(runtime, 'VIBES_AUTH_INTERNAL_TOKEN');
+            }
+        };
+        if (useAuthServiceBinding) {
+            authOptions.authBinding = (runtime) => runtime.getBinding('AUTH_SERVICE', ServiceBindingSchema);
+        }
+        services.auth = createAuthPermissionsAdapter(authOptions);
+    }
+    if (logger)
+        services.logger = logger;
+    const kitConfig = {
+        auth: { handler: authHandler, publicRoutes, redirectTo }
+    };
+    if (billing)
+        kitConfig.billing = billing;
+    if (Object.keys(services).length > 0)
+        kitConfig.services = services;
+    const created = settleNow(() => createVibesKit(kitConfig));
+    if (created.ok)
+        return created.value;
+    // The marker travels in the thrown error's message, where a blind
+    // `scriptThrewException` still shows it, and the original failure (with its
+    // stack) rides as `cause`; the injected logger, when there is one, gets it too.
+    const marker = `[VIBES-INIT-CRASH ${slug}]`;
+    logger?.error(marker, failureAsError(created.error));
+    throw new Error(`${marker} ${failureAsError(created.error).message}`, { cause: created.error });
+}