@webflow/cloud-app 0.1.0-beta.10

package/dist/frameworks/base.d.ts

@@ -0,0 +1,134 @@
+import type { BuildContext, BuildOutput, FrameworkInfo, PackageJson, WebflowJson, DetectionResult, AdapterPackage, IntegrationPackage, WebflowLoaderConfig, NodeVersionRequirement } from './types';
+export declare abstract class FrameworkBuilder {
+    /**
+     * Canonical framework name (e.g. 'nextjs', 'astro', 'vite').
+     * Subclasses override this static field; matches `info.name` on the instance.
+     */
+    static frameworkName: string;
+    protected ctx: BuildContext;
+    constructor(ctx: BuildContext);
+    /**
+     * Framework identification. Returns info about this specific framework and version.
+     */
+    abstract get info(): FrameworkInfo;
+    /**
+     * Detect if this builder handles the project.
+     *
+     * Returns true if this builder can handle the project. Detection order in the
+     * registry determines precedence (first match wins).
+     */
+    static detect(_packageJson: PackageJson, _webflowJson?: WebflowJson): DetectionResult;
+    /**
+     * Detect this framework from a built output directory.
+     *
+     * Used at deploy time when webflow.json may be missing (e.g. CLI-built
+     * output). Each framework recognizes its own bundled artifact signature
+     * inside `cwd`. Default returns false; frameworks that can be detected from
+     * output override.
+     */
+    static detectFromBuiltOutput(_cwd: string): boolean;
+    /**
+     * Static deploy metadata: framework name + entrypoint + deployment type.
+     *
+     * Same shape as `getOutputDeployMetadata()` but callable without constructing
+     * a builder, so the deploy phase (which has no BuildContext) can use it.
+     */
+    static getOutputDeployMetadata(): BuildOutput;
+    /**
+     * Validate that the project meets requirements for this framework.
+     *
+     * @throws FrameworkValidationError if validation fails
+     */
+    abstract validate(): Promise<void>;
+    /**
+     * Install required dependencies that are missing. Should be idempotent.
+     */
+    abstract installDependencies(): Promise<void>;
+    /**
+     * Prepare configuration files (astro.config, wrangler.json, etc.). Handles
+     * renaming user configs and merging with templates.
+     */
+    abstract prepareConfig(): Promise<void>;
+    /**
+     * Get the build command to execute, e.g. "astro build",
+     * "opennextjs-cloudflare build". Returns null for frameworks with no build
+     * step (the no-framework static builder), in which case the host skips the
+     * build phase.
+     */
+    abstract getBuildCommand(): string | null;
+    /**
+     * Instance accessor for deploy metadata. Wraps the static method on the
+     * concrete class so existing instance-based call sites keep working.
+     */
+    getOutputDeployMetadata(): BuildOutput;
+    /** Get the wrangler template path for this framework. */
+    abstract getWranglerTemplatePath(): string;
+    /**
+     * Get the Cloudflare adapter package to install. Returns null if the
+     * framework doesn't need one (e.g., pure SPA).
+     */
+    abstract getCloudflareAdapter(): AdapterPackage | null;
+    /**
+     * Get Webflow-specific integrations required for Webflow component support.
+     * Installed in addition to user dependencies.
+     */
+    abstract getRequiredIntegrations(): IntegrationPackage[];
+    /**
+     * Get the Webflow loader configuration for image optimization. Returns null
+     * if the framework doesn't need a loader.
+     */
+    abstract getWebflowLoader(): WebflowLoaderConfig | null;
+    /**
+     * Get Node.js version requirements for this framework. Returns null if no
+     * specific version is required.
+     */
+    abstract getNodeVersionRequirement(): NodeVersionRequirement | null;
+    /**
+     * Post-build hook for any cleanup or modifications. Called after the build
+     * command succeeds.
+     */
+    postBuild(): Promise<void>;
+    /**
+     * Get additional config files to copy (beyond webflow-loader). Returns an
+     * array of full paths to files that should be copied to the project root.
+     */
+    getAdditionalConfigFiles(): string[];
+    /**
+     * Get patterns for user config files that need to be renamed, e.g.
+     * ['astro.config.mjs', 'astro.config.ts', 'astro.config.js'].
+     */
+    getUserConfigPatterns(): string[];
+    /**
+     * Resolve the user's installed framework version from package.json, coerced
+     * to a valid semver string (e.g. "14.2.3"). Returns undefined when the
+     * package isn't in the user's deps or the version spec can't be coerced.
+     *
+     * Subclasses override to point at the correct npm package (`next`, `astro`,
+     * `vite`). The default returns undefined — when that happens the producer
+     * omits `framework_version` from webflow.json (the field is optional under
+     * the deploy contract).
+     */
+    getFrameworkVersion(): string | undefined;
+    /** Check if a dependency exists in package.json (deps or devDeps). */
+    protected hasDependency(name: string): boolean;
+    /** Get a dependency version from package.json (deps or devDeps). */
+    protected getDependencyVersion(name: string): string | undefined;
+    /**
+     * Read a dependency's version spec from the user's package.json and coerce it
+     * to a valid semver string. Returns undefined when the package isn't installed
+     * or the spec doesn't coerce (e.g. `workspace:*`, `latest`, a git URL). Used
+     * by `getFrameworkVersion` overrides.
+     */
+    protected resolveFrameworkVersion(pkgName: string): string | undefined;
+    /** Logger port from context. */
+    protected get log(): import("..").Logger;
+    /** Command-runner port from context. */
+    protected get runCommand(): import("..").CommandRunner;
+    /** Telemetry port from context. */
+    protected get telemetry(): import("..").Telemetry;
+    /** Filesystem port from context. */
+    protected get fs(): import("..").FileSystemPort;
+    /** Working directory (the build workspace) from context. */
+    protected get cwd(): string;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/frameworks/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/frameworks/base.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,WAAW,EACX,WAAW,EACX,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,SAAS,CAAC;AAEjB,8BAAsB,gBAAgB;IACpC;;;OAGG;IACH,MAAM,CAAC,aAAa,SAAM;IAE1B,SAAS,CAAC,GAAG,EAAE,YAAY,CAAC;gBAEhB,GAAG,EAAE,YAAY;IAQ7B;;OAEG;IACH,QAAQ,KAAK,IAAI,IAAI,aAAa,CAAC;IAEnC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,WAAW,EAAE,YAAY,CAAC,EAAE,WAAW,GAAG,eAAe;IAIrF;;;;;;;OAOG;IACH,MAAM,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAInD;;;;;OAKG;IACH,MAAM,CAAC,uBAAuB,IAAI,WAAW;IAI7C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAE7C;;;OAGG;IACH,QAAQ,CAAC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAEvC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,IAAI,MAAM,GAAG,IAAI;IAEzC;;;OAGG;IACH,uBAAuB,IAAI,WAAW;IAItC,yDAAyD;IACzD,QAAQ,CAAC,uBAAuB,IAAI,MAAM;IAM1C;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,IAAI,cAAc,GAAG,IAAI;IAEtD;;;OAGG;IACH,QAAQ,CAAC,uBAAuB,IAAI,kBAAkB,EAAE;IAExD;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,IAAI,mBAAmB,GAAG,IAAI;IAEvD;;;OAGG;IACH,QAAQ,CAAC,yBAAyB,IAAI,sBAAsB,GAAG,IAAI;IAMnE;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;OAGG;IACH,wBAAwB,IAAI,MAAM,EAAE;IAIpC;;;OAGG;IACH,qBAAqB,IAAI,MAAM,EAAE;IAIjC;;;;;;;;;OASG;IACH,mBAAmB,IAAI,MAAM,GAAG,SAAS;IAQzC,sEAAsE;IACtE,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAK9C,oEAAoE;IACpE,SAAS,CAAC,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKhE;;;;;OAKG;IACH,SAAS,CAAC,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMtE,gCAAgC;IAChC,SAAS,KAAK,GAAG,wBAEhB;IAED,wCAAwC;IACxC,SAAS,KAAK,UAAU,+BAEvB;IAED,mCAAmC;IACnC,SAAS,KAAK,SAAS,2BAEtB;IAED,oCAAoC;IACpC,SAAS,KAAK,EAAE,gCAEf;IAED,4DAA4D;IAC5D,SAAS,KAAK,GAAG,WAEhB;CACF"}

package/dist/frameworks/base.js

@@ -0,0 +1,175 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrameworkBuilder = void 0;
+/**
+ * Abstract base class for framework builders.
+ *
+ * Each framework (Astro, Next.js, Vite) extends this class to implement
+ * framework-specific build logic. The base is framework-agnostic and reaches
+ * the outside world only through the ports carried on `BuildContext`.
+ */
+const semver = __importStar(require("semver"));
+class FrameworkBuilder {
+    /**
+     * Canonical framework name (e.g. 'nextjs', 'astro', 'vite').
+     * Subclasses override this static field; matches `info.name` on the instance.
+     */
+    static frameworkName = '';
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * Detect if this builder handles the project.
+     *
+     * Returns true if this builder can handle the project. Detection order in the
+     * registry determines precedence (first match wins).
+     */
+    static detect(_packageJson, _webflowJson) {
+        return { detected: false };
+    }
+    /**
+     * Detect this framework from a built output directory.
+     *
+     * Used at deploy time when webflow.json may be missing (e.g. CLI-built
+     * output). Each framework recognizes its own bundled artifact signature
+     * inside `cwd`. Default returns false; frameworks that can be detected from
+     * output override.
+     */
+    static detectFromBuiltOutput(_cwd) {
+        return false;
+    }
+    /**
+     * Static deploy metadata: framework name + entrypoint + deployment type.
+     *
+     * Same shape as `getOutputDeployMetadata()` but callable without constructing
+     * a builder, so the deploy phase (which has no BuildContext) can use it.
+     */
+    static getOutputDeployMetadata() {
+        throw new Error('getOutputDeployMetadata must be implemented by the framework subclass');
+    }
+    /**
+     * Instance accessor for deploy metadata. Wraps the static method on the
+     * concrete class so existing instance-based call sites keep working.
+     */
+    getOutputDeployMetadata() {
+        return this.constructor.getOutputDeployMetadata();
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // OPTIONAL METHODS WITH DEFAULT IMPLEMENTATIONS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Post-build hook for any cleanup or modifications. Called after the build
+     * command succeeds.
+     */
+    async postBuild() {
+        // Default: no-op
+    }
+    /**
+     * Get additional config files to copy (beyond webflow-loader). Returns an
+     * array of full paths to files that should be copied to the project root.
+     */
+    getAdditionalConfigFiles() {
+        return [];
+    }
+    /**
+     * Get patterns for user config files that need to be renamed, e.g.
+     * ['astro.config.mjs', 'astro.config.ts', 'astro.config.js'].
+     */
+    getUserConfigPatterns() {
+        return [];
+    }
+    /**
+     * Resolve the user's installed framework version from package.json, coerced
+     * to a valid semver string (e.g. "14.2.3"). Returns undefined when the
+     * package isn't in the user's deps or the version spec can't be coerced.
+     *
+     * Subclasses override to point at the correct npm package (`next`, `astro`,
+     * `vite`). The default returns undefined — when that happens the producer
+     * omits `framework_version` from webflow.json (the field is optional under
+     * the deploy contract).
+     */
+    getFrameworkVersion() {
+        return undefined;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PROTECTED HELPER METHODS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /** Check if a dependency exists in package.json (deps or devDeps). */
+    hasDependency(name) {
+        const { packageJson } = this.ctx;
+        return name in (packageJson.dependencies || {}) || name in (packageJson.devDependencies || {});
+    }
+    /** Get a dependency version from package.json (deps or devDeps). */
+    getDependencyVersion(name) {
+        const { packageJson } = this.ctx;
+        return packageJson.dependencies?.[name] || packageJson.devDependencies?.[name];
+    }
+    /**
+     * Read a dependency's version spec from the user's package.json and coerce it
+     * to a valid semver string. Returns undefined when the package isn't installed
+     * or the spec doesn't coerce (e.g. `workspace:*`, `latest`, a git URL). Used
+     * by `getFrameworkVersion` overrides.
+     */
+    resolveFrameworkVersion(pkgName) {
+        const spec = this.getDependencyVersion(pkgName);
+        if (!spec)
+            return undefined;
+        return semver.coerce(spec)?.version;
+    }
+    /** Logger port from context. */
+    get log() {
+        return this.ctx.log;
+    }
+    /** Command-runner port from context. */
+    get runCommand() {
+        return this.ctx.runCommand;
+    }
+    /** Telemetry port from context. */
+    get telemetry() {
+        return this.ctx.telemetry;
+    }
+    /** Filesystem port from context. */
+    get fs() {
+        return this.ctx.fs;
+    }
+    /** Working directory (the build workspace) from context. */
+    get cwd() {
+        return this.ctx.cwd;
+    }
+}
+exports.FrameworkBuilder = FrameworkBuilder;
+//# sourceMappingURL=base.js.map

package/dist/frameworks/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/frameworks/base.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;GAMG;AACH,+CAAiC;AAejC,MAAsB,gBAAgB;IACpC;;;OAGG;IACH,MAAM,CAAC,aAAa,GAAG,EAAE,CAAC;IAEhB,GAAG,CAAe;IAE5B,YAAY,GAAiB;QAC3B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAWD;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,YAAyB,EAAE,YAA0B;QACjE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC7B,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,qBAAqB,CAAC,IAAY;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,uBAAuB;QAC5B,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC3F,CAAC;IA4BD;;;OAGG;IACH,uBAAuB;QACrB,OAAQ,IAAI,CAAC,WAAuC,CAAC,uBAAuB,EAAE,CAAC;IACjF,CAAC;IAiCD,8EAA8E;IAC9E,gDAAgD;IAChD,8EAA8E;IAE9E;;;OAGG;IACH,KAAK,CAAC,SAAS;QACb,iBAAiB;IACnB,CAAC;IAED;;;OAGG;IACH,wBAAwB;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;OAGG;IACH,qBAAqB;QACnB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;;;;;;;OASG;IACH,mBAAmB;QACjB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,8EAA8E;IAC9E,2BAA2B;IAC3B,8EAA8E;IAE9E,sEAAsE;IAC5D,aAAa,CAAC,IAAY;QAClC,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC;QACjC,OAAO,IAAI,IAAI,CAAC,WAAW,CAAC,YAAY,IAAI,EAAE,CAAC,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;IACjG,CAAC;IAED,oEAAoE;IAC1D,oBAAoB,CAAC,IAAY;QACzC,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC;QACjC,OAAO,WAAW,CAAC,YAAY,EAAE,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,eAAe,EAAE,CAAC,IAAI,CAAC,CAAC;IACjF,CAAC;IAED;;;;;OAKG;IACO,uBAAuB,CAAC,OAAe;QAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI;YAAE,OAAO,SAAS,CAAC;QAC5B,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACtC,CAAC;IAED,gCAAgC;IAChC,IAAc,GAAG;QACf,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACtB,CAAC;IAED,wCAAwC;IACxC,IAAc,UAAU;QACtB,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC;IAC7B,CAAC;IAED,mCAAmC;IACnC,IAAc,SAAS;QACrB,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;IAC5B,CAAC;IAED,oCAAoC;IACpC,IAAc,EAAE;QACd,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACrB,CAAC;IAED,4DAA4D;IAC5D,IAAc,GAAG;QACf,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACtB,CAAC;;AApNH,4CAqNC"}

package/dist/frameworks/errors.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Custom error types for framework builders.
+ *
+ * These errors carry remediation hints, documentation links, and
+ * framework-specific context so hosts can render actionable failures.
+ */
+export interface FrameworkErrorOptions {
+    cause?: Error;
+    remediation?: string;
+    documentationUrl?: string;
+}
+/**
+ * Base error for all framework-related errors.
+ * Includes optional remediation hints and documentation links.
+ */
+export declare class FrameworkError extends Error {
+    readonly remediation?: string;
+    readonly documentationUrl?: string;
+    readonly cause?: unknown;
+    constructor(message: string, options?: FrameworkErrorOptions);
+    /**
+     * Format the error for display, including remediation if available.
+     */
+    toDisplayString(): string;
+}
+/**
+ * Thrown when project validation fails.
+ *
+ * Examples:
+ * - Wrong Node.js version
+ * - Missing required dependencies
+ * - Invalid configuration
+ * - Unsupported framework version
+ */
+export declare class FrameworkValidationError extends FrameworkError {
+    constructor(message: string, options?: FrameworkErrorOptions);
+}
+export interface FrameworkBuildErrorOptions extends FrameworkErrorOptions {
+    buildCommand?: string;
+}
+/**
+ * Thrown when the build command fails.
+ * Includes framework-specific debugging hints.
+ */
+export declare class FrameworkBuildError extends FrameworkError {
+    readonly buildCommand?: string;
+    constructor(message: string, options?: FrameworkBuildErrorOptions);
+    toDisplayString(): string;
+}
+export interface FrameworkConfigErrorOptions extends FrameworkErrorOptions {
+    configFile?: string;
+}
+/**
+ * Thrown when configuration is invalid or cannot be processed.
+ *
+ * Examples:
+ * - Malformed astro.config.mjs
+ * - Invalid wrangler.json
+ * - Missing required config fields
+ */
+export declare class FrameworkConfigError extends FrameworkError {
+    readonly configFile?: string;
+    constructor(message: string, options?: FrameworkConfigErrorOptions);
+    toDisplayString(): string;
+}
+/**
+ * Thrown when framework cannot be detected.
+ */
+export declare class FrameworkDetectionError extends FrameworkError {
+    constructor(message: string, options?: FrameworkErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/frameworks/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/frameworks/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrC,SAAgB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1C,SAAyB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAE7B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB;IAa5D;;OAEG;IACH,eAAe,IAAI,MAAM;CAU1B;AAMD;;;;;;;;GAQG;AACH,qBAAa,wBAAyB,SAAQ,cAAc;gBAC9C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB;CAI7D;AAMD,MAAM,WAAW,0BAA2B,SAAQ,qBAAqB;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;IACrD,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAC;gBAE1B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B;IAMxD,eAAe,IAAI,MAAM;CAOnC;AAMD,MAAM,WAAW,2BAA4B,SAAQ,qBAAqB;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,2BAA2B;IAMzD,eAAe,IAAI,MAAM;CAOnC;AAMD;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,cAAc;gBAC7C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB;CAI7D"}

package/dist/frameworks/errors.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Custom error types for framework builders.
+ *
+ * These errors carry remediation hints, documentation links, and
+ * framework-specific context so hosts can render actionable failures.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrameworkDetectionError = exports.FrameworkConfigError = exports.FrameworkBuildError = exports.FrameworkValidationError = exports.FrameworkError = void 0;
+/**
+ * Base error for all framework-related errors.
+ * Includes optional remediation hints and documentation links.
+ */
+class FrameworkError extends Error {
+    remediation;
+    documentationUrl;
+    cause;
+    constructor(message, options) {
+        super(message);
+        this.name = 'FrameworkError';
+        this.cause = options?.cause;
+        this.remediation = options?.remediation;
+        this.documentationUrl = options?.documentationUrl;
+        // Maintains proper stack trace for where error was thrown (V8 engines)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Format the error for display, including remediation if available.
+     */
+    toDisplayString() {
+        let result = this.message;
+        if (this.remediation) {
+            result += `\n\nHow to fix: ${this.remediation}`;
+        }
+        if (this.documentationUrl) {
+            result += `\n\nDocumentation: ${this.documentationUrl}`;
+        }
+        return result;
+    }
+}
+exports.FrameworkError = FrameworkError;
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation Error
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Thrown when project validation fails.
+ *
+ * Examples:
+ * - Wrong Node.js version
+ * - Missing required dependencies
+ * - Invalid configuration
+ * - Unsupported framework version
+ */
+class FrameworkValidationError extends FrameworkError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'FrameworkValidationError';
+    }
+}
+exports.FrameworkValidationError = FrameworkValidationError;
+/**
+ * Thrown when the build command fails.
+ * Includes framework-specific debugging hints.
+ */
+class FrameworkBuildError extends FrameworkError {
+    buildCommand;
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'FrameworkBuildError';
+        this.buildCommand = options?.buildCommand;
+    }
+    toDisplayString() {
+        let result = super.toDisplayString();
+        if (this.buildCommand) {
+            result += `\n\nBuild command: ${this.buildCommand}`;
+        }
+        return result;
+    }
+}
+exports.FrameworkBuildError = FrameworkBuildError;
+/**
+ * Thrown when configuration is invalid or cannot be processed.
+ *
+ * Examples:
+ * - Malformed astro.config.mjs
+ * - Invalid wrangler.json
+ * - Missing required config fields
+ */
+class FrameworkConfigError extends FrameworkError {
+    configFile;
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'FrameworkConfigError';
+        this.configFile = options?.configFile;
+    }
+    toDisplayString() {
+        let result = super.toDisplayString();
+        if (this.configFile) {
+            result += `\n\nConfig file: ${this.configFile}`;
+        }
+        return result;
+    }
+}
+exports.FrameworkConfigError = FrameworkConfigError;
+// ─────────────────────────────────────────────────────────────────────────────
+// Detection Error
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Thrown when framework cannot be detected.
+ */
+class FrameworkDetectionError extends FrameworkError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'FrameworkDetectionError';
+    }
+}
+exports.FrameworkDetectionError = FrameworkDetectionError;
+//# sourceMappingURL=errors.js.map

package/dist/frameworks/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/frameworks/errors.ts"],"names":[],"mappings":"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"}

package/dist/frameworks/nextjs/adapter-resolver.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Cloudflare adapter version resolution for Next.js.
+ *
+ * `@opennextjs/cloudflare` declares a `next` peer dependency whose range moves
+ * with each release and sometimes carves out "dead zones" — Next.js versions
+ * that are newer than an old floor but excluded by a tighter upper bound (e.g.
+ * peer `>=15.5.18 <16 || >=16.2.6` excludes next@16.0.0–16.2.5). Installing the
+ * adapter with no version constraint always pulls the latest, so an app pinned
+ * inside a dead zone fails with a cryptic npm `ERESOLVE` before the build even
+ * starts.
+ *
+ * This module resolves the concrete Next.js version the app will install and
+ * picks the highest published adapter release whose peer range accepts it,
+ * pinning that version explicitly. When the version cannot be determined it
+ * signals a fallback to the previous "install latest" behaviour; when no
+ * release is compatible it raises an actionable error instead of letting npm
+ * fail opaquely.
+ *
+ * All metadata is read through the app's own npm configuration (`npm view` run
+ * in the app directory), so adapter selection and the subsequent install
+ * resolve against the same registry, scoped registry, and auth.
+ */
+import type { Logger } from '../../ports';
+/** A published adapter version and the Next.js range it declares as a peer. */
+export interface AdapterCandidate {
+    /** Concrete published version, e.g. "1.20.1". */
+    version: string;
+    /** Value of `peerDependencies.next`, or undefined if the version declares none. */
+    nextPeerRange?: string;
+}
+/**
+ * I/O the resolver depends on, injectable so unit tests can run without
+ * touching the network or the `npm` CLI. Both lookups take the app's `cwd` so
+ * they honor its npm configuration (registry, scoped registry, auth) — the same
+ * surface the subsequent install resolves against.
+ */
+export interface AdapterResolverIO {
+    /** Fetch every published adapter version and its `next` peer range. */
+    fetchAdapterCandidates: (adapterName: string, cwd: string) => Promise<AdapterCandidate[]>;
+    /**
+     * Resolve a package.json version spec to the concrete Next.js version npm
+     * would install, or null when it cannot be determined (local/workspace/git
+     * specs, an empty spec, or no matching published version).
+     */
+    resolveInstalledNextVersion: (nextSpec: string, cwd: string) => Promise<string | null>;
+}
+/**
+ * Pick the highest stable adapter version whose declared `next` peer range is
+ * satisfied by `installedNext`.
+ *
+ * Versions that declare no `next` peer dependency are ignored: they predate the
+ * adapter pinning Next.js and silently installing one would mask a real
+ * incompatibility. Prerelease adapter versions are ignored too. Returns null
+ * when nothing matches.
+ */
+export declare function selectAdapterVersion(installedNext: string, candidates: AdapterCandidate[]): string | null;
+/**
+ * Resolve the adapter version to install for a project pinned to `nextSpec`,
+ * reading all metadata through the app's npm config at `cwd`.
+ *
+ * - Returns a concrete version string to pin when a compatible release exists.
+ * - Returns null when the Next.js version can't be determined or the metadata
+ *   lookup fails — the caller should fall back to installing the latest adapter
+ *   (the previous behaviour), which is no worse than before.
+ * - Throws {@link FrameworkValidationError} when the Next.js version is known
+ *   but no published adapter release accepts it, surfacing a clear remediation
+ *   instead of a downstream npm `ERESOLVE`.
+ */
+export declare function resolveCompatibleAdapterVersion(log: Logger, adapterName: string, nextSpec: string, cwd: string, io?: AdapterResolverIO): Promise<string | null>;
+/** Production I/O: `npm view` run in the app's cwd. */
+export declare const defaultAdapterResolverIO: AdapterResolverIO;
+//# sourceMappingURL=adapter-resolver.d.ts.map

package/dist/frameworks/nextjs/adapter-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-resolver.d.ts","sourceRoot":"","sources":["../../../src/frameworks/nextjs/adapter-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAc1C,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,sBAAsB,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC1F;;;;OAIG;IACH,2BAA2B,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACxF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,gBAAgB,EAAE,GAC7B,MAAM,GAAG,IAAI,CAaf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,+BAA+B,CACnD,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,EAAE,GAAE,iBAA4C,GAC/C,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmDxB;AA2HD,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,EAAE,iBAGtC,CAAC"}