veryfront 0.1.215 → 0.1.217

package/esm/src/extensions/interfaces/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Barrel export for all extension contract interfaces.
+ *
+ * Every export is a pure TypeScript type -- no runtime code is emitted.
+ *
+ * @module extensions/interfaces
+ */
+import "../../../_dnt.polyfills.js";
+export type { BundleOptions, BundleOutput, Bundler, BundleResult, BundlerPlugin, BundlerPluginBuild, TransformOptions, TransformResult, } from "./bundler.js";
+export type { CacheStore } from "./cache-store.js";
+export type { CSSProcessOptions, CSSProcessor, CSSProcessResult } from "./css-processor.js";
+export type { ContentTransformer, ContentTransformOptions, ContentTransformResult, } from "./content-transformer.js";
+export type { DatabaseClient, QueryResult } from "./database-client.js";
+export type { AuthProvider, SignOptions, TokenPayload, VerifyOptions } from "./auth-provider.js";
+export type { SpanData, TracingExporter } from "./tracing-exporter.js";
+export type { AIModelProvider, ChatMessage, CompletionOptions, CompletionResult, ContentPart, StreamChunk, ToolDefinition, } from "./ai-model-provider.js";
+export type { EmbeddingOptions, EmbeddingProvider, EmbeddingResult } from "./embedding-provider.js";
+export type { ASTNode, CodeParser, GenerateOptions, GenerateResult, NodePath, ParseOptions, TraverseVisitor, } from "./code-parser.js";
+export type { Schema, SchemaValidator, ValidationFailure, ValidationIssue, ValidationResult, ValidationSuccess, } from "./schema-validator.js";
+export type { NodeCompat } from "./node-compat.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/src/extensions/interfaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/src/extensions/interfaces/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,4BAA4B,CAAC;AAEpC,YAAY,EACV,aAAa,EACb,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,GAChB,MAAM,cAAc,CAAC;AAGtB,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG5F,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGjG,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGvE,YAAY,EACV,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,cAAc,GACf,MAAM,wBAAwB,CAAC;AAGhC,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAGpG,YAAY,EACV,OAAO,EACP,UAAU,EACV,eAAe,EACf,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACV,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/esm/src/extensions/interfaces/index.js

@@ -0,0 +1,9 @@
+/**
+ * Barrel export for all extension contract interfaces.
+ *
+ * Every export is a pure TypeScript type -- no runtime code is emitted.
+ *
+ * @module extensions/interfaces
+ */
+// Bundler
+import "../../../_dnt.polyfills.js";

package/esm/src/extensions/interfaces/node-compat.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Contract interface for Node.js compatibility shims.
+ *
+ * Default implementation: `@veryfront/ext-node-compat`
+ *
+ * @module extensions/interfaces/node-compat
+ */
+/**
+ * NodeCompat contract interface.
+ *
+ * Implementations provide access to Node.js-compatible APIs in
+ * environments where native Node modules are unavailable (e.g. Deno).
+ *
+ * Each getter returns the module's namespace object, matching the
+ * shape of the corresponding Node.js built-in.
+ */
+export interface NodeCompat {
+    /** Return a Node-compatible `fs` module (sync + async + promises). */
+    getFS(): unknown;
+    /** Return a Node-compatible `path` module. */
+    getPath(): unknown;
+    /** Return a Node-compatible `WebSocket` constructor. */
+    getWebSocket(): unknown;
+}
+//# sourceMappingURL=node-compat.d.ts.map

package/esm/src/extensions/interfaces/node-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-compat.d.ts","sourceRoot":"","sources":["../../../../src/src/extensions/interfaces/node-compat.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,KAAK,IAAI,OAAO,CAAC;IACjB,8CAA8C;IAC9C,OAAO,IAAI,OAAO,CAAC;IACnB,wDAAwD;IACxD,YAAY,IAAI,OAAO,CAAC;CACzB"}

package/esm/src/extensions/interfaces/node-compat.js

@@ -0,0 +1,8 @@
+/**
+ * Contract interface for Node.js compatibility shims.
+ *
+ * Default implementation: `@veryfront/ext-node-compat`
+ *
+ * @module extensions/interfaces/node-compat
+ */
+export {};

package/esm/src/extensions/interfaces/schema-validator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Contract interface for schema validation.
+ *
+ * Default implementation: `@veryfront/ext-zod`
+ *
+ * @module extensions/interfaces/schema-validator
+ */
+/** An opaque schema definition that validates and infers type `T`. */
+export interface Schema<T = unknown> {
+    /** Brand field for nominal typing -- not used at runtime. */
+    readonly _output: T;
+}
+/** A single validation issue with location context. */
+export interface ValidationIssue {
+    /** Dot-path to the offending field (e.g. `"user.email"`). */
+    path: (string | number)[];
+    /** Human-readable error message. */
+    message: string;
+    /** Machine-readable error code. */
+    code?: string;
+}
+/** Successful validation outcome. */
+export interface ValidationSuccess<T> {
+    success: true;
+    /** Parsed and validated data. */
+    data: T;
+}
+/** Failed validation outcome. */
+export interface ValidationFailure {
+    success: false;
+    /** List of issues found during validation. */
+    issues: ValidationIssue[];
+}
+/** Discriminated union of validation outcomes. */
+export type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
+/**
+ * SchemaValidator contract interface.
+ *
+ * Implementations validate unknown input against a typed schema and
+ * return a discriminated success/failure result.
+ */
+export interface SchemaValidator {
+    /** Validate `data` against the given schema. */
+    validate<T>(schema: Schema<T>, data: unknown): ValidationResult<T>;
+}
+//# sourceMappingURL=schema-validator.d.ts.map

package/esm/src/extensions/interfaces/schema-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-validator.d.ts","sourceRoot":"","sources":["../../../../src/src/extensions/interfaces/schema-validator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,sEAAsE;AACtE,MAAM,WAAW,MAAM,CAAC,CAAC,GAAG,OAAO;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;CACrB;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qCAAqC;AACrC,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,OAAO,EAAE,IAAI,CAAC;IACd,iCAAiC;IACjC,IAAI,EAAE,CAAC,CAAC;CACT;AAED,iCAAiC;AACjC,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,8CAA8C;IAC9C,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,kDAAkD;AAClD,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;CACpE"}

package/esm/src/extensions/interfaces/schema-validator.js

@@ -0,0 +1,8 @@
+/**
+ * Contract interface for schema validation.
+ *
+ * Default implementation: `@veryfront/ext-zod`
+ *
+ * @module extensions/interfaces/schema-validator
+ */
+export {};

package/esm/src/extensions/interfaces/tracing-exporter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Contract interface for tracing/telemetry exporters.
+ *
+ * Default implementation: `@veryfront/ext-opentelemetry`
+ *
+ * @module extensions/interfaces/tracing-exporter
+ */
+/** Data describing a single trace span. */
+export interface SpanData {
+    /** Unique span identifier. */
+    spanId: string;
+    /** Trace identifier this span belongs to. */
+    traceId: string;
+    /** Parent span identifier, if any. */
+    parentSpanId?: string;
+    /** Human-readable operation name. */
+    name: string;
+    /** Span kind (`client`, `server`, `internal`, `producer`, `consumer`). */
+    kind: "client" | "server" | "internal" | "producer" | "consumer";
+    /** Start time as a Unix timestamp in milliseconds. */
+    startTime: number;
+    /** End time as a Unix timestamp in milliseconds. */
+    endTime: number;
+    /** Key-value attributes attached to the span. */
+    attributes: Record<string, string | number | boolean>;
+    /** Status of the span. */
+    status: {
+        code: "ok" | "error" | "unset";
+        message?: string;
+    };
+}
+/**
+ * TracingExporter contract interface.
+ *
+ * Implementations export collected trace spans to an observability
+ * backend (e.g. Jaeger, Zipkin, OTLP collector).
+ */
+export interface TracingExporter {
+    /** Export a batch of completed spans. */
+    export(spans: SpanData[]): Promise<void>;
+    /** Flush pending data and release resources. */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=tracing-exporter.d.ts.map

package/esm/src/extensions/interfaces/tracing-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing-exporter.d.ts","sourceRoot":"","sources":["../../../../src/src/extensions/interfaces/tracing-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,QAAQ;IACvB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;IACjE,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACtD,0BAA0B;IAC1B,MAAM,EAAE;QAAE,IAAI,EAAE,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,gDAAgD;IAChD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/esm/src/extensions/interfaces/tracing-exporter.js

@@ -0,0 +1,8 @@
+/**
+ * Contract interface for tracing/telemetry exporters.
+ *
+ * Default implementation: `@veryfront/ext-opentelemetry`
+ *
+ * @module extensions/interfaces/tracing-exporter
+ */
+export {};

package/esm/src/extensions/loader.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Extension loader — topological sort, lifecycle management, preset flattening.
+ *
+ * @module extensions/loader
+ */
+import type { ExtensionLogger, ResolvedExtension } from "./types.js";
+export declare class ExtensionLoader {
+    private logger;
+    private setupOrder;
+    constructor(logger: ExtensionLogger);
+    /**
+     * Flatten presets: extensions with `extends` are replaced by their children.
+     * Recurses through nested presets; throws on cyclic `extends` graphs rather
+     * than stack-overflowing.
+     */
+    flattenPresets(extensions: ResolvedExtension[]): ResolvedExtension[];
+    private flattenPresetsInner;
+    /**
+     * Topological sort: providers load before consumers.
+     * Throws on circular dependencies.
+     */
+    topologicalSort(extensions: ResolvedExtension[]): ResolvedExtension[];
+    /**
+     * Run the full setup lifecycle for all extensions.
+     * If called while extensions are already loaded, tears them down first.
+     */
+    setupAll(extensions: ResolvedExtension[], projectConfig: Record<string, unknown>): Promise<void>;
+    /**
+     * Teardown all loaded extensions in reverse order.
+     */
+    teardownAll(): Promise<void>;
+}
+//# sourceMappingURL=loader.d.ts.map

package/esm/src/extensions/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/src/extensions/loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,KAAK,EAA+B,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAElG,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,UAAU,CAA2B;gBAEjC,MAAM,EAAE,eAAe;IAInC;;;;OAIG;IACH,cAAc,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE;IAIpE,OAAO,CAAC,mBAAmB;IA8B3B;;;OAGG;IACH,eAAe,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE;IA6ErE;;;OAGG;IACG,QAAQ,CACZ,UAAU,EAAE,iBAAiB,EAAE,EAC/B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,IAAI,CAAC;IA4EhB;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAcnC"}

package/esm/src/extensions/loader.js

@@ -0,0 +1,209 @@
+/**
+ * Extension loader — topological sort, lifecycle management, preset flattening.
+ *
+ * @module extensions/loader
+ */
+import { CIRCULAR_DEPENDENCY_ERROR, EXTENSION_CONFLICT_ERROR, EXTENSION_VALIDATION_ERROR, } from "./errors.js";
+import { register, reset, resolve as resolveContract, tryResolve } from "./contracts.js";
+import { auditCapabilities } from "./capabilities.js";
+import { detectConflicts, selectContractProviders, validateExtension } from "./validation.js";
+export class ExtensionLoader {
+    logger;
+    setupOrder = [];
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Flatten presets: extensions with `extends` are replaced by their children.
+     * Recurses through nested presets; throws on cyclic `extends` graphs rather
+     * than stack-overflowing.
+     */
+    flattenPresets(extensions) {
+        return this.flattenPresetsInner(extensions, new Set());
+    }
+    flattenPresetsInner(extensions, path) {
+        const result = [];
+        for (const resolved of extensions) {
+            const ext = resolved.extension;
+            if (ext.extends && ext.extends.length > 0) {
+                if (path.has(ext)) {
+                    throw EXTENSION_VALIDATION_ERROR.create({
+                        message: `Circular preset extends chain detected via "${ext.name}"`,
+                    });
+                }
+                path.add(ext);
+                const children = ext.extends.map((child) => ({
+                    extension: child,
+                    source: resolved.source,
+                    origin: resolved.origin,
+                }));
+                result.push(...this.flattenPresetsInner(children, path));
+                path.delete(ext);
+            }
+            else {
+                result.push(resolved);
+            }
+        }
+        return result;
+    }
+    /**
+     * Topological sort: providers load before consumers.
+     * Throws on circular dependencies.
+     */
+    topologicalSort(extensions) {
+        const providerOf = new Map();
+        const extByName = new Map();
+        const consumesContracts = new Map();
+        for (const resolved of extensions) {
+            const ext = resolved.extension;
+            extByName.set(ext.name, resolved);
+            if (ext.provides) {
+                for (const contract of Object.keys(ext.provides)) {
+                    providerOf.set(contract, ext.name);
+                }
+            }
+            const contracts = ext.capabilities
+                .filter((c) => c.type === "contract")
+                .map((c) => c.name);
+            if (contracts.length > 0) {
+                consumesContracts.set(ext.name, contracts);
+            }
+        }
+        // Build adjacency list
+        const graph = new Map();
+        const inDegree = new Map();
+        for (const resolved of extensions) {
+            const name = resolved.extension.name;
+            if (!graph.has(name))
+                graph.set(name, new Set());
+            if (!inDegree.has(name))
+                inDegree.set(name, 0);
+        }
+        for (const [consumer, contracts] of consumesContracts) {
+            for (const contract of contracts) {
+                const provider = providerOf.get(contract);
+                if (provider && provider !== consumer) {
+                    const edges = graph.get(provider);
+                    if (!edges.has(consumer)) {
+                        edges.add(consumer);
+                        inDegree.set(consumer, (inDegree.get(consumer) || 0) + 1);
+                    }
+                }
+            }
+        }
+        // Kahn's algorithm
+        const queue = [];
+        for (const [name, degree] of inDegree) {
+            if (degree === 0)
+                queue.push(name);
+        }
+        const sorted = [];
+        while (queue.length > 0) {
+            const name = queue.shift();
+            sorted.push(extByName.get(name));
+            for (const dependent of graph.get(name) || []) {
+                const newDegree = (inDegree.get(dependent) || 1) - 1;
+                inDegree.set(dependent, newDegree);
+                if (newDegree === 0)
+                    queue.push(dependent);
+            }
+        }
+        if (sorted.length !== extByName.size) {
+            const unsorted = [...extByName.values()]
+                .filter((r) => !sorted.includes(r))
+                .map((r) => r.extension.name);
+            throw CIRCULAR_DEPENDENCY_ERROR.create({
+                message: `Circular extension dependency detected among: ${unsorted.join(", ")}`,
+            });
+        }
+        return sorted;
+    }
+    /**
+     * Run the full setup lifecycle for all extensions.
+     * If called while extensions are already loaded, tears them down first.
+     */
+    async setupAll(extensions, projectConfig) {
+        // Idempotent: teardownAll clears setupOrder and resets the contract
+        // registry even when nothing is loaded yet.
+        await this.teardownAll();
+        // Check for contract conflicts before loading
+        const conflicts = detectConflicts(extensions);
+        if (conflicts.length > 0) {
+            const details = conflicts
+                .map((c) => `"${c.contract}" provided by: ${c.providers.map((p) => p.name).join(", ")}`)
+                .join("; ");
+            throw EXTENSION_CONFLICT_ERROR.create({
+                message: `Extension conflicts detected: ${details}`,
+            });
+        }
+        // Precompute the priority winner per contract so that a lower-priority
+        // provider later in the iteration order cannot overwrite the winning impl
+        // via register(). Without this, merged inputs (config -> package ->
+        // project -> local-file) silently invert the documented source priority.
+        const contractWinner = selectContractProviders(extensions);
+        for (const resolved of extensions) {
+            const ext = resolved.extension;
+            const issues = validateExtension(ext);
+            if (issues.length > 0) {
+                throw EXTENSION_VALIDATION_ERROR.create({
+                    message: `Extension "${ext.name}" is invalid:\n  ${issues.join("\n  ")}`,
+                });
+            }
+            auditCapabilities(ext.name, ext.capabilities, this.logger);
+            if (ext.provides) {
+                for (const [contract, impl] of Object.entries(ext.provides)) {
+                    if (contractWinner.get(contract) === resolved) {
+                        register(contract, impl);
+                    }
+                }
+            }
+            if (ext.setup) {
+                const ctx = {
+                    get: (contract) => tryResolve(contract),
+                    require: (contract) => resolveContract(contract),
+                    provide: (contract, impl) => register(contract, impl),
+                    config: projectConfig,
+                    logger: this.logger,
+                };
+                try {
+                    await ext.setup(ctx);
+                }
+                catch (err) {
+                    // Best-effort teardown of the partially-initialized extension so
+                    // any resources it opened before throwing get a chance to close.
+                    if (ext.teardown) {
+                        try {
+                            await ext.teardown();
+                        }
+                        catch (teardownErr) {
+                            this.logger.error(`Error during rollback teardown of "${ext.name}":`, teardownErr);
+                        }
+                    }
+                    // Roll back everything loaded so far and clear the registry.
+                    await this.teardownAll();
+                    throw err;
+                }
+            }
+            this.setupOrder.push(resolved);
+            this.logger.info(`Extension "${ext.name}" v${ext.version} loaded from ${resolved.source}`);
+        }
+    }
+    /**
+     * Teardown all loaded extensions in reverse order.
+     */
+    async teardownAll() {
+        const reversed = [...this.setupOrder].reverse();
+        for (const resolved of reversed) {
+            if (resolved.extension.teardown) {
+                try {
+                    await resolved.extension.teardown();
+                }
+                catch (err) {
+                    this.logger.error(`Error tearing down "${resolved.extension.name}":`, err);
+                }
+            }
+        }
+        this.setupOrder = [];
+        reset();
+    }
+}

package/esm/src/extensions/orchestrate.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Extension orchestration pipeline.
+ *
+ * Discovers, loads, merges, sorts, and runs setup for every extension
+ * contributed by the four sources (config, package, project, local-file).
+ * Invoked once by `bootstrap()` after config resolution.
+ *
+ * @module extensions/orchestrate
+ */
+import * as defaultDiscovery from "./discovery.js";
+import { loadExtensionFactory as defaultLoadFactory } from "./factory-loader.js";
+import { ExtensionLoader } from "./loader.js";
+import type { ExtensionConfigEntry, ExtensionLogger } from "./types.js";
+/**
+ * Options for `orchestrateExtensions`.
+ *
+ * The `discovery` and `loadFactory` fields are test seams — they are not
+ * part of the stable public API and default to the real implementations.
+ */
+export interface OrchestrateOptions {
+    projectDir: string;
+    config: {
+        extensions?: ExtensionConfigEntry[];
+    };
+    logger: ExtensionLogger;
+    /** @internal Override discovery functions in tests. */
+    discovery?: {
+        discoverPackageExtensions: typeof defaultDiscovery.discoverPackageExtensions;
+        discoverProjectExtensions: typeof defaultDiscovery.discoverProjectExtensions;
+        discoverLocalExtensions: typeof defaultDiscovery.discoverLocalExtensions;
+        mergeExtensions: typeof defaultDiscovery.mergeExtensions;
+    };
+    /** @internal Override factory loading in tests. */
+    loadFactory?: typeof defaultLoadFactory;
+}
+/**
+ * Run the full extension pipeline against a resolved project config.
+ *
+ * Pipeline:
+ *   1. Split `config.extensions` into resolved entries and disable directives.
+ *   2. Discover extensions from package, project, and local sources.
+ *   3. Skip loading factories for package- and project-source extensions whose
+ *      names appear in the disable set (local-file names are not reliable
+ *      pre-load and are filtered after `mergeExtensions`).
+ *   4. Dynamic-import factories for every remaining discovered path.
+ *   5. Merge sources honoring priority `config > package > project > local-file`.
+ *   6. Construct an `ExtensionLoader` and run `setupAll`.
+ *
+ * On factory error during `setup()`, `ExtensionLoader.setupAll` performs
+ * partial rollback internally. The error is re-thrown unchanged so callers
+ * can surface the extension name to the user.
+ */
+export declare function orchestrateExtensions(options: OrchestrateOptions): Promise<ExtensionLoader>;
+//# sourceMappingURL=orchestrate.d.ts.map

package/esm/src/extensions/orchestrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate.d.ts","sourceRoot":"","sources":["../../../src/src/extensions/orchestrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,gBAAgB,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,oBAAoB,IAAI,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEV,oBAAoB,EACpB,eAAe,EAGhB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE;QAAE,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAA;KAAE,CAAC;IAChD,MAAM,EAAE,eAAe,CAAC;IACxB,uDAAuD;IACvD,SAAS,CAAC,EAAE;QACV,yBAAyB,EAAE,OAAO,gBAAgB,CAAC,yBAAyB,CAAC;QAC7E,yBAAyB,EAAE,OAAO,gBAAgB,CAAC,yBAAyB,CAAC;QAC7E,uBAAuB,EAAE,OAAO,gBAAgB,CAAC,uBAAuB,CAAC;QACzE,eAAe,EAAE,OAAO,gBAAgB,CAAC,eAAe,CAAC;KAC1D,CAAC;IACF,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,kBAAkB,CAAC;CACzC;AAmCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,eAAe,CAAC,CA4E1B"}

package/esm/src/extensions/orchestrate.js

@@ -0,0 +1,116 @@
+/**
+ * Extension orchestration pipeline.
+ *
+ * Discovers, loads, merges, sorts, and runs setup for every extension
+ * contributed by the four sources (config, package, project, local-file).
+ * Invoked once by `bootstrap()` after config resolution.
+ *
+ * @module extensions/orchestrate
+ */
+import { basename, dirname } from "../../deps/jsr.io/@std/path/1.1.4/mod.js";
+import * as defaultDiscovery from "./discovery.js";
+import { loadExtensionFactory as defaultLoadFactory } from "./factory-loader.js";
+import { ExtensionLoader } from "./loader.js";
+function isDisableDirective(entry) {
+    return (typeof entry === "object" &&
+        entry !== null &&
+        "enabled" in entry &&
+        entry.enabled === false);
+}
+/**
+ * Extract the extension name from a project-extension path.
+ *
+ * Project extensions live under `<baseDir>/extensions/<name>/...`. Discovery
+ * emits either `<baseDir>/extensions/<name>/src/index.ts` or
+ * `<baseDir>/extensions/<name>/index.ts`. This walks parent directories until
+ * it finds the ancestor whose parent is `extensions/`.
+ */
+function projectExtensionNameFromPath(path) {
+    let current = dirname(path);
+    // Safety limit in case of a malformed path that never reaches a root.
+    for (let i = 0; i < 8; i++) {
+        const parent = dirname(current);
+        if (basename(parent) === "extensions") {
+            return basename(current);
+        }
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return undefined;
+}
+/**
+ * Run the full extension pipeline against a resolved project config.
+ *
+ * Pipeline:
+ *   1. Split `config.extensions` into resolved entries and disable directives.
+ *   2. Discover extensions from package, project, and local sources.
+ *   3. Skip loading factories for package- and project-source extensions whose
+ *      names appear in the disable set (local-file names are not reliable
+ *      pre-load and are filtered after `mergeExtensions`).
+ *   4. Dynamic-import factories for every remaining discovered path.
+ *   5. Merge sources honoring priority `config > package > project > local-file`.
+ *   6. Construct an `ExtensionLoader` and run `setupAll`.
+ *
+ * On factory error during `setup()`, `ExtensionLoader.setupAll` performs
+ * partial rollback internally. The error is re-thrown unchanged so callers
+ * can surface the extension name to the user.
+ */
+export async function orchestrateExtensions(options) {
+    const { projectDir, config, logger } = options;
+    const disc = options.discovery ?? defaultDiscovery;
+    const loadFactory = options.loadFactory ?? defaultLoadFactory;
+    const configEntries = Array.isArray(config.extensions) ? config.extensions : [];
+    const disables = [];
+    const configResolved = [];
+    for (const entry of configEntries) {
+        if (isDisableDirective(entry)) {
+            disables.push(entry);
+        }
+        else {
+            configResolved.push({
+                extension: entry,
+                source: "config",
+                origin: "veryfront.config",
+            });
+        }
+    }
+    // Build the disabled-names set early so we can skip dynamic imports for
+    // extensions the user has explicitly turned off. A factory whose module
+    // fails to import or invoke would otherwise take down bootstrap even
+    // though the user asked for it to be disabled.
+    const disabledNames = new Set(disables.map((d) => d.name));
+    const [packageHits, projectPaths, localPaths] = await Promise.all([
+        disc.discoverPackageExtensions(projectDir),
+        disc.discoverProjectExtensions(projectDir),
+        disc.discoverLocalExtensions(projectDir),
+    ]);
+    // Package hits carry the package name directly — filter before loading.
+    const enabledPackageNames = packageHits
+        .map((hit) => hit.packageName)
+        .filter((name) => !disabledNames.has(name));
+    // Project paths have the shape `<projectDir>/extensions/<name>/src/index.ts`
+    // (or `<projectDir>/extensions/<name>/index.ts`). `mergeExtensions` is the
+    // safety net for any path whose name cannot be derived.
+    const enabledProjectPaths = projectPaths.filter((path) => {
+        const name = projectExtensionNameFromPath(path);
+        return name === undefined || !disabledNames.has(name);
+    });
+    // Local-file paths cannot be reliably filtered pre-load: the filename
+    // (`foo.extension.ts`) is not guaranteed to match the extension name
+    // declared by the factory. `mergeExtensions` applies the post-hoc filter.
+    const packageResolved = await loadAllFactories(enabledPackageNames, "package", loadFactory);
+    const projectResolved = await loadAllFactories(enabledProjectPaths, "project", loadFactory);
+    const localResolved = await loadAllFactories(localPaths, "local-file", loadFactory);
+    const merged = disc.mergeExtensions(configResolved, packageResolved, projectResolved, localResolved, disables);
+    const loader = new ExtensionLoader(logger);
+    await loader.setupAll(merged, config);
+    return loader;
+}
+async function loadAllFactories(paths, source, loadFactory) {
+    const resolved = [];
+    for (const path of paths) {
+        resolved.push(await loadFactory(path, source));
+    }
+    return resolved;
+}

package/esm/src/extensions/recommendations.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Maps contract names to recommended first-party extension packages.
+ *
+ * @module extensions/recommendations
+ */
+export declare function getRecommendation(contractName: string): string | undefined;
+//# sourceMappingURL=recommendations.d.ts.map

package/esm/src/extensions/recommendations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendations.d.ts","sourceRoot":"","sources":["../../../src/src/extensions/recommendations.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiBH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1E"}

package/esm/src/extensions/recommendations.js

@@ -0,0 +1,22 @@
+/**
+ * Maps contract names to recommended first-party extension packages.
+ *
+ * @module extensions/recommendations
+ */
+const recommendations = new Map([
+    ["Bundler", "@veryfront/ext-esbuild"],
+    ["CacheStore", "@veryfront/ext-redis"],
+    ["CSSProcessor", "@veryfront/ext-tailwind"],
+    ["ContentTransformer", "@veryfront/ext-mdx"],
+    ["DatabaseClient", "@veryfront/ext-postgres"],
+    ["AuthProvider", "@veryfront/ext-jwt"],
+    ["TracingExporter", "@veryfront/ext-opentelemetry"],
+    ["AIModelProvider", "@veryfront/ext-openai"],
+    ["EmbeddingProvider", "@veryfront/ext-embeddings"],
+    ["CodeParser", "@veryfront/ext-babel"],
+    ["SchemaValidator", "@veryfront/ext-zod"],
+    ["NodeCompat", "@veryfront/ext-node-compat"],
+]);
+export function getRecommendation(contractName) {
+    return recommendations.get(contractName);
+}