@webflow/webflow-cli 1.21.0 → 1.22.0-next.0

package/dist/cloud-scaffolds/registry.ts

@@ -0,0 +1,132 @@
+import type { FrameworkDefinition } from "./types";
+import { ScaffoldError } from "./types";
+
+/**
+ * Central registry of supported framework scaffolds.
+ * To add a new framework: add one entry here.
+ *
+ * Scaffold versioning convention
+ * ------------------------------
+ * Each scaffold repo (`Webflow-Examples/hello-world-*`) carries a `vN` branch
+ * per breaking change in the scaffold contract — i.e. the shape of
+ * `webflow.json`, required config files, or anything else the CLI relies on
+ * being there. Branches are NOT bumped with every CLI major; only when we
+ * actually break the contract. Most CLI releases keep using the same `vN`.
+ *
+ * The CLI always pulls from the `vN` branch its code expects, so older CLI
+ * installs keep working forever.
+ *
+ * Workflow when introducing a breaking change in the scaffold contract:
+ *   1. Branch `vN+1` from `main` in each scaffold repo.
+ *   2. Apply the breaking change on `vN+1` (and on `main`, which tracks the
+ *      latest stable version for humans browsing the repo on GitHub).
+ *   3. Bump every `ref` below from `vN` to `vN+1` in the CLI release that
+ *      ships the breaking change.
+ *
+ * Old `vN` branches stay frozen — we don't backport fixes.
+ */
+export const FRAMEWORK_REGISTRY: Record<string, FrameworkDefinition> = {
+  "astro-minimal": {
+    id: "astro-minimal",
+    name: "Astro",
+    source: {
+      type: "github",
+      repo: "Webflow-Examples/hello-world-astro",
+      ref: "v1",
+    },
+  },
+  "nextjs-minimal": {
+    id: "nextjs-minimal",
+    name: "Next.js",
+    source: {
+      type: "github",
+      repo: "Webflow-Examples/hello-world-nextjs",
+      ref: "v1",
+    },
+  },
+  astro: {
+    id: "astro",
+    name: "Astro (site-attached)",
+    source: {
+      type: "github",
+      repo: "Webflow-Examples/hello-world-astro-devlink",
+      ref: "v1",
+    },
+  },
+  nextjs: {
+    id: "nextjs",
+    name: "Next.js (site-attached)",
+    source: {
+      type: "github",
+      repo: "Webflow-Examples/hello-world-nextjs-devlink",
+      ref: "v1",
+    },
+  },
+};
+
+/**
+ * Get framework definition by ID.
+ * @throws ScaffoldError if framework is not supported
+ */
+export function getFrameworkDefinition(
+  scaffoldId: string
+): FrameworkDefinition {
+  const def = FRAMEWORK_REGISTRY[scaffoldId];
+  if (!def) {
+    const supported = Object.keys(FRAMEWORK_REGISTRY);
+    throw new ScaffoldError(
+      `Unsupported framework: "${scaffoldId}". Supported: ${supported.join(
+        ", "
+      )}`,
+      scaffoldId,
+      supported
+    );
+  }
+  return def;
+}
+
+/**
+ * List all supported scaffold IDs (for --new mode).
+ */
+export function listSupportedScaffoldIds(): string[] {
+  return Object.keys(FRAMEWORK_REGISTRY);
+}
+
+/**
+ * List framework names (without -minimal) for prompts.
+ * e.g. ["astro", "nextjs"] — deduplicated
+ */
+export function getAvailableFrameworkNames(): string[] {
+  return [
+    ...new Set(
+      listSupportedScaffoldIds().map((id) => id.replace(/-minimal$/, ""))
+    ),
+  ];
+}
+
+/**
+ * List scaffold IDs for --existing mode (site-attached, full scaffolds).
+ */
+export function listExistingScaffoldIds(): string[] {
+  return ["astro", "nextjs"];
+}
+
+/**
+ * Map framework name (e.g. "astro") to scaffold ID (e.g. "astro-minimal").
+ * Used when user selects "astro" and we need the minimal scaffold.
+ */
+export function toMinimalScaffoldId(frameworkName: string): string {
+  const normalized = frameworkName.replace(/-minimal$/, "");
+  const scaffoldId = `${normalized}-minimal`;
+  if (!FRAMEWORK_REGISTRY[scaffoldId]) {
+    const supported = listSupportedScaffoldIds();
+    throw new ScaffoldError(
+      `No minimal scaffold for "${frameworkName}". Supported: ${supported.join(
+        ", "
+      )}`,
+      scaffoldId,
+      supported
+    );
+  }
+  return scaffoldId;
+}

package/dist/cloud-scaffolds/types.ts

@@ -0,0 +1,68 @@
+/**
+ * GitHub-based scaffold source.
+ * Used when fetching from a public GitHub repository.
+ */
+export interface GitHubScaffoldSource {
+  type: "github";
+  /** Repository in "owner/repo" format */
+  repo: string;
+  /** Branch or tag. Default: "main" */
+  ref?: string;
+}
+
+/**
+ * Local scaffold source.
+ * Used when reading from bundled scaffold directories.
+ */
+export interface LocalScaffoldSource {
+  type: "local";
+  /** Path to scaffold directory (relative to dist root or absolute) */
+  path: string;
+}
+
+/**
+ * Union of supported scaffold sources.
+ * Each variant has only the properties it needs — no optional repo on local.
+ * The `type` discriminant enables TypeScript narrowing.
+ */
+export type ScaffoldSource = GitHubScaffoldSource | LocalScaffoldSource;
+
+/**
+ * Definition of a supported framework scaffold.
+ * Single entry point for adding new frameworks.
+ */
+export interface FrameworkDefinition {
+  /** Unique ID used in CLI (e.g. "astro-minimal", "nextjs-minimal") */
+  id: string;
+  /** Display name for prompts */
+  name: string;
+  /** Where to fetch the scaffold content */
+  source: ScaffoldSource;
+}
+
+/**
+ * Result of fetching scaffold content.
+ * Used by applyScaffold to write files.
+ */
+export interface ScaffoldContent {
+  /** Scaffold identifier */
+  scaffoldId: string;
+  /** Absolute paths to scaffold files */
+  files: string[];
+  /** Root directory of the scaffold (for path resolution) */
+  extractionRoot: string;
+}
+
+/**
+ * Error thrown when a scaffold is not found or unsupported.
+ */
+export class ScaffoldError extends Error {
+  constructor(
+    message: string,
+    public readonly scaffoldId?: string,
+    public readonly supportedIds?: string[]
+  ) {
+    super(message);
+    this.name = "ScaffoldError";
+  }
+}