@webflow/cloud-app 0.1.0-beta.7

package/dist/frameworks/astro/templates/v6/webflow-loader.ts

@@ -0,0 +1,112 @@
+/**
+ * Webflow Image Loader for Astro 6
+ *
+ * This is the same loader as Astro 5 — it handles image optimization through
+ * Cloudflare's image resizing service.
+ *
+ * Note: Astro 6 defaults to 'cloudflare-binding' for imageService, but we use
+ * 'custom' to maintain compatibility with our CDN setup.
+ */
+import type { ExternalImageService, ImageTransform, AstroConfig } from 'astro';
+
+function normalizeSrc(src: string, deployUrl?: string, mountPath?: string) {
+  // For local assets, include the mount path but not the deploy url, and remove the leading slash
+  if (deployUrl && src.startsWith(deployUrl)) {
+    return `${src.slice(deployUrl.length)}`.slice(1);
+  } else if (mountPath && src.startsWith(mountPath)) {
+    return src.slice(1);
+  } else if (src.startsWith('/')) {
+    return `${mountPath}${src}`.slice(1);
+  }
+  return src;
+}
+
+// Default implementation copied from Astro's baseService
+function getTargetDimensions(options: ImageTransform) {
+  let targetWidth = options.width;
+  let targetHeight = options.height;
+
+  // For ESM imported images, calculate missing dimensions based on aspect ratio
+  if (typeof options.src === 'object' && 'width' in options.src && 'height' in options.src) {
+    const aspectRatio = options.src.width / options.src.height;
+    if (targetHeight && !targetWidth) {
+      targetWidth = Math.round(targetHeight * aspectRatio);
+    } else if (targetWidth && !targetHeight) {
+      targetHeight = Math.round(targetWidth / aspectRatio);
+    } else if (!targetWidth && !targetHeight) {
+      targetWidth = options.src.width;
+      targetHeight = options.src.height;
+    }
+  }
+
+  return {
+    targetWidth,
+    targetHeight,
+  };
+}
+
+const cloudflareLoader: ExternalImageService = {
+  getURL(options: ImageTransform, imageConfig: AstroConfig['image']) {
+    const normalizedSrc = normalizeSrc(
+      typeof options.src === 'object' ? options.src.src : options.src,
+      imageConfig.service.config.deployUrl,
+      imageConfig.service.config.mountPath,
+    );
+    // Our cloudflare zone doesn't allow optimizing external images for security reasons, so just load the original image
+    // For now, also skip optimization for images hosted on regular webflow sites (cdn.website-files.com)
+    // because optimizing them would result in two bandwidth charges: one from the website-files zone (for the full image)
+    // and one from the cosmic.webflow.services zone (for the resized image)
+    if (normalizedSrc.startsWith('http://') || normalizedSrc.startsWith('https://')) {
+      return normalizedSrc;
+    }
+
+    const supportedOptions = ['width', 'height', 'quality', 'format'];
+    const params = [];
+    for (const option of supportedOptions) {
+      if (options[option]) {
+        params.push(`${option}=${options[option]}`);
+      }
+    }
+
+    const workerUrl = imageConfig.service.config.deployUrl;
+    // Skip resizing svgs, since it doesn't do anything
+    const isSvg =
+      typeof options.src === 'object' ? options.src.format === 'svg' : options.src.endsWith('.svg');
+    if (isSvg || params.length === 0) {
+      return `${workerUrl}/${normalizedSrc}`;
+    }
+
+    const paramsString = params.join(',');
+    return `${workerUrl}/cdn-cgi/image/${paramsString}/${normalizedSrc}`;
+  },
+
+  // Default implementation copied from Astro's baseService
+  getHTMLAttributes(options: ImageTransform) {
+    const { targetWidth, targetHeight } = getTargetDimensions(options);
+    const {
+      src,
+      width,
+      height,
+      format,
+      quality,
+      densities,
+      widths,
+      formats,
+      layout,
+      priority,
+      fit,
+      position,
+      ...attributes
+    } = options;
+
+    return {
+      ...attributes,
+      width: targetWidth,
+      height: targetHeight,
+      loading: attributes.loading ?? 'lazy',
+      decoding: attributes.decoding ?? 'async',
+    };
+  },
+};
+
+export default cloudflareLoader;

package/dist/frameworks/astro/templates/v6/wrangler.json

@@ -0,0 +1,9 @@
+{
+  "name": "cosmic-builder-dry-run",
+  "main": "@astrojs/cloudflare/entrypoints/server",
+  "compatibility_date": "2025-03-03",
+  "compatibility_flags": ["nodejs_compat"],
+  "assets": {
+    "directory": "./dist/client"
+  }
+}

package/dist/frameworks/astro/templates/v7/astro.config.mjs.template

@@ -0,0 +1,34 @@
+// Generated by the Webflow Cloud builder. Merge logic lives in ./astro.config.webflow.ts.
+import { defineConfig } from 'astro/config';
+import { readFileSync } from 'node:fs';
+import cloudflare from '@astrojs/cloudflare';
+import react from '@astrojs/react';
+import userConfig from './clouduser.astro.config';
+import { withWebflowOverrides } from './astro.config.webflow';
+
+// Detect React 19+ so we know whether to alias react-dom/server -> .edge.
+let isReact19 = false;
+try {
+  const pkg = JSON.parse(readFileSync('./package.json', 'utf8'));
+  const reactVersion = pkg.dependencies?.react || pkg.devDependencies?.react || '';
+  // Match versions like "19", "^19", "~19", "19.0.0", "^19.0.0", etc.
+  isReact19 = /(?:^|[^\d])19(?:\.|$)/.test(reactVersion);
+} catch {
+  // Could not read package.json, assume not React 19.
+}
+
+export default defineConfig(
+  withWebflowOverrides(userConfig, {
+    mountPath: '${COSMIC_MOUNT_PATH}',
+    deployUrl: '${COSMIC_DEPLOY_URL}',
+    adapter: cloudflare({
+      imageService: 'custom',
+      // Note: platformProxy removed in Astro 6+ — workerd runs natively via @cloudflare/vite-plugin.
+    }),
+    reactIntegration: react(),
+    // Only React 19+ has react-dom/server.edge. React 18 has only .browser, which doesn't run in edge runtimes.
+    reactDomServerAlias: import.meta.env.PROD && isReact19
+      ? { 'react-dom/server': 'react-dom/server.edge' }
+      : undefined,
+  })
+);

package/dist/frameworks/astro/templates/v7/webflow-loader.ts

@@ -0,0 +1,113 @@
+/**
+ * Webflow Image Loader for Astro 7
+ *
+ * This is the same loader as Astro 5 and 6 - it handles image optimization
+ * through Cloudflare's image resizing service.
+ *
+ * Note: Astro 7 defaults to 'cloudflare-binding' for imageService,
+ * but we use 'custom' to maintain compatibility with our CDN setup.
+ */
+
+import type { ExternalImageService, ImageTransform, AstroConfig } from 'astro';
+
+function normalizeSrc(src: string, deployUrl?: string, mountPath?: string) {
+  // For local assets, include the mount path but not the deploy url, and remove the leading slash
+  if (deployUrl && src.startsWith(deployUrl)) {
+    return `${src.slice(deployUrl.length)}`.slice(1);
+  } else if (mountPath && src.startsWith(mountPath)) {
+    return src.slice(1);
+  } else if (src.startsWith('/')) {
+    return `${mountPath}${src}`.slice(1);
+  }
+  return src;
+}
+
+// Default implementation copied from Astro's baseService
+function getTargetDimensions(options: ImageTransform) {
+  let targetWidth = options.width;
+  let targetHeight = options.height;
+
+  // For ESM imported images, calculate missing dimensions based on aspect ratio
+  if (typeof options.src === 'object' && 'width' in options.src && 'height' in options.src) {
+    const aspectRatio = options.src.width / options.src.height;
+    if (targetHeight && !targetWidth) {
+      targetWidth = Math.round(targetHeight * aspectRatio);
+    } else if (targetWidth && !targetHeight) {
+      targetHeight = Math.round(targetWidth / aspectRatio);
+    } else if (!targetWidth && !targetHeight) {
+      targetWidth = options.src.width;
+      targetHeight = options.src.height;
+    }
+  }
+
+  return {
+    targetWidth,
+    targetHeight,
+  };
+}
+
+const cloudflareLoader: ExternalImageService = {
+  getURL(options: ImageTransform, imageConfig: AstroConfig['image']) {
+    const normalizedSrc = normalizeSrc(
+      typeof options.src === 'object' ? options.src.src : options.src,
+      imageConfig.service.config.deployUrl,
+      imageConfig.service.config.mountPath,
+    );
+    // Our cloudflare zone doesn't allow optimizing external images for security reasons, so just load the original image
+    // For now, also skip optimization for images hosted on regular webflow sites (cdn.website-files.com)
+    // because optimizing them would result in two bandwidth charges: one from the website-files zone (for the full image)
+    // and one from the cosmic.webflow.services zone (for the resized image)
+    if (normalizedSrc.startsWith('http://') || normalizedSrc.startsWith('https://')) {
+      return normalizedSrc;
+    }
+
+    const supportedOptions = ['width', 'height', 'quality', 'format'];
+    const params = [];
+    for (const option of supportedOptions) {
+      if (options[option]) {
+        params.push(`${option}=${options[option]}`);
+      }
+    }
+
+    const workerUrl = imageConfig.service.config.deployUrl;
+    // Skip resizing svgs, since it doesn't do anything
+    const isSvg =
+      typeof options.src === 'object' ? options.src.format === 'svg' : options.src.endsWith('.svg');
+    if (isSvg || params.length === 0) {
+      return `${workerUrl}/${normalizedSrc}`;
+    }
+
+    const paramsString = params.join(',');
+    return `${workerUrl}/cdn-cgi/image/${paramsString}/${normalizedSrc}`;
+  },
+
+  // Default implementation copied from Astro's baseService
+  getHTMLAttributes(options: ImageTransform) {
+    const { targetWidth, targetHeight } = getTargetDimensions(options);
+    const {
+      src,
+      width,
+      height,
+      format,
+      quality,
+      densities,
+      widths,
+      formats,
+      layout,
+      priority,
+      fit,
+      position,
+      ...attributes
+    } = options;
+
+    return {
+      ...attributes,
+      width: targetWidth,
+      height: targetHeight,
+      loading: attributes.loading ?? 'lazy',
+      decoding: attributes.decoding ?? 'async',
+    };
+  },
+};
+
+export default cloudflareLoader;

package/dist/frameworks/astro/templates/v7/wrangler.json

@@ -0,0 +1,9 @@
+{
+  "name": "cosmic-builder-dry-run",
+  "main": "@astrojs/cloudflare/entrypoints/server",
+  "compatibility_date": "2025-03-03",
+  "compatibility_flags": ["nodejs_compat"],
+  "assets": {
+    "directory": "./dist/client"
+  }
+}

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). CLD-1785.
+     */
+    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). CLD-1785.
+     */
+    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"}