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

package/dist/cloud-scaffolds/__tests__/fetcher.test.ts

@@ -0,0 +1,249 @@
+import * as fs from "fs";
+import * as path from "path";
+import os from "os";
+import * as tar from "tar";
+import {
+  fetchScaffoldContent,
+  getScaffoldContent,
+  getScaffoldFromLocal,
+} from "../fetcher";
+import * as registry from "../registry";
+import { ScaffoldError } from "../types";
+
+jest.mock("../registry");
+jest.mock("../../../utils/logger", () => ({
+  __esModule: true,
+  default: {
+    spinner: jest.fn(() => ({
+      succeed: jest.fn(),
+      fail: jest.fn(),
+      warn: jest.fn(),
+      info: jest.fn(),
+    })),
+  },
+}));
+
+const mockGetFrameworkDefinition =
+  registry.getFrameworkDefinition as jest.MockedFunction<
+    typeof registry.getFrameworkDefinition
+  >;
+const mockToMinimalScaffoldId =
+  registry.toMinimalScaffoldId as jest.MockedFunction<
+    typeof registry.toMinimalScaffoldId
+  >;
+
+describe("scaffold fetcher", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "fetcher-test-"));
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe("getScaffoldFromLocal", () => {
+    it("returns ScaffoldContent from local directory", async () => {
+      const scaffoldDir = path.join(tempDir, "scaffold");
+      fs.mkdirSync(scaffoldDir, { recursive: true });
+      fs.writeFileSync(path.join(scaffoldDir, "package.json"), "{}");
+      fs.mkdirSync(path.join(scaffoldDir, "src"), { recursive: true });
+      fs.writeFileSync(path.join(scaffoldDir, "src", "index.ts"), "// test");
+
+      mockGetFrameworkDefinition.mockReturnValue({
+        id: "test-minimal",
+        name: "Test",
+        source: {
+          type: "local",
+          path: path.resolve(scaffoldDir),
+        },
+      });
+
+      const result = await getScaffoldFromLocal("test-minimal");
+
+      expect(result.scaffoldId).toBe("test-minimal");
+      expect(result.extractionRoot).toBe(scaffoldDir);
+      expect(result.files).toHaveLength(2);
+      expect(result.files).toContain(path.join(scaffoldDir, "package.json"));
+      expect(result.files).toContain(path.join(scaffoldDir, "src", "index.ts"));
+    });
+
+    it("throws ScaffoldError when source is not local", async () => {
+      mockGetFrameworkDefinition.mockReturnValue({
+        id: "astro-minimal",
+        name: "Astro",
+        source: {
+          type: "github",
+          repo: "Webflow-Examples/hello-world-astro",
+          ref: "main",
+        },
+      });
+
+      await expect(getScaffoldFromLocal("astro-minimal")).rejects.toThrow(
+        ScaffoldError
+      );
+      await expect(getScaffoldFromLocal("astro-minimal")).rejects.toThrow(
+        "does not have a local source"
+      );
+    });
+
+    it("throws ScaffoldError when directory does not exist", async () => {
+      const missingPath = path.resolve(path.join(tempDir, "nonexistent"));
+
+      mockGetFrameworkDefinition.mockReturnValue({
+        id: "test-minimal",
+        name: "Test",
+        source: { type: "local", path: missingPath },
+      });
+
+      await expect(getScaffoldFromLocal("test-minimal")).rejects.toThrow(
+        ScaffoldError
+      );
+      await expect(getScaffoldFromLocal("test-minimal")).rejects.toThrow(
+        "Scaffold directory not found"
+      );
+    });
+  });
+
+  describe("fetchScaffoldContent", () => {
+    it("dispatches to getScaffoldFromLocal for local source", async () => {
+      const scaffoldDir = path.join(tempDir, "scaffold");
+      fs.mkdirSync(scaffoldDir, { recursive: true });
+      fs.writeFileSync(path.join(scaffoldDir, "package.json"), "{}");
+
+      mockGetFrameworkDefinition.mockReturnValue({
+        id: "test-minimal",
+        name: "Test",
+        source: { type: "local", path: path.resolve(scaffoldDir) },
+      });
+
+      const result = await fetchScaffoldContent("test-minimal");
+
+      expect(result.scaffoldId).toBe("test-minimal");
+      expect(result.files).toHaveLength(1);
+    });
+
+    it("fetches from GitHub and returns ScaffoldContent", async () => {
+      // Create a minimal tarball matching GitHub structure: owner-repo-sha/
+      const topLevelDir = "Webflow-Examples-hello-world-astro-abc123";
+      const tarballDir = path.join(tempDir, "tarball-src");
+      fs.mkdirSync(path.join(tarballDir, topLevelDir), { recursive: true });
+      fs.writeFileSync(
+        path.join(tarballDir, topLevelDir, "package.json"),
+        '{"name":"test"}'
+      );
+
+      const tarballPath = path.join(tempDir, "archive.tar.gz");
+      await tar.create(
+        {
+          gzip: true,
+          file: tarballPath,
+          cwd: tarballDir,
+        },
+        [topLevelDir]
+      );
+      const tarballBuffer = fs.readFileSync(tarballPath);
+
+      const originalFetch = globalThis.fetch;
+      const arrayBuffer = tarballBuffer.buffer.slice(
+        tarballBuffer.byteOffset,
+        tarballBuffer.byteOffset + tarballBuffer.byteLength
+      );
+      globalThis.fetch = jest.fn().mockResolvedValue({
+        ok: true,
+        arrayBuffer: () => Promise.resolve(arrayBuffer),
+      });
+
+      mockGetFrameworkDefinition.mockReturnValue({
+        id: "astro-minimal",
+        name: "Astro",
+        source: {
+          type: "github",
+          repo: "Webflow-Examples/hello-world-astro",
+          ref: "main",
+        },
+      });
+
+      try {
+        const result = await fetchScaffoldContent("astro-minimal");
+
+        expect(result.scaffoldId).toBe("astro-minimal");
+        expect(result.files).toHaveLength(1);
+        expect(result.files[0]).toContain("package.json");
+        expect(result.extractionRoot).toContain(topLevelDir);
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+
+    it("throws ScaffoldError when GitHub fetch fails", async () => {
+      const originalFetch = globalThis.fetch;
+      globalThis.fetch = jest.fn().mockResolvedValue({
+        ok: false,
+        status: 404,
+        statusText: "Not Found",
+      });
+
+      mockGetFrameworkDefinition.mockReturnValue({
+        id: "astro-minimal",
+        name: "Astro",
+        source: {
+          type: "github",
+          repo: "Webflow-Examples/hello-world-astro",
+          ref: "main",
+        },
+      });
+
+      try {
+        await expect(fetchScaffoldContent("astro-minimal")).rejects.toThrow(
+          ScaffoldError
+        );
+        await expect(fetchScaffoldContent("astro-minimal")).rejects.toThrow(
+          "Failed to fetch scaffold from GitHub"
+        );
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+  });
+
+  describe("getScaffoldContent", () => {
+    it("resolves framework name to minimal ID and fetches", async () => {
+      const scaffoldDir = path.join(tempDir, "scaffold");
+      fs.mkdirSync(scaffoldDir, { recursive: true });
+      fs.writeFileSync(path.join(scaffoldDir, "package.json"), "{}");
+
+      mockToMinimalScaffoldId.mockReturnValue("astro-minimal");
+      mockGetFrameworkDefinition.mockReturnValue({
+        id: "astro-minimal",
+        name: "Astro",
+        source: { type: "local", path: path.resolve(scaffoldDir) },
+      });
+
+      const result = await getScaffoldContent("astro");
+
+      expect(mockToMinimalScaffoldId).toHaveBeenCalledWith("astro");
+      expect(result.scaffoldId).toBe("astro-minimal");
+      expect(result.files).toHaveLength(1);
+    });
+
+    it("passes through full scaffold ID unchanged", async () => {
+      const scaffoldDir = path.join(tempDir, "scaffold");
+      fs.mkdirSync(scaffoldDir, { recursive: true });
+      fs.writeFileSync(path.join(scaffoldDir, "package.json"), "{}");
+
+      mockGetFrameworkDefinition.mockReturnValue({
+        id: "astro-minimal",
+        name: "Astro",
+        source: { type: "local", path: path.resolve(scaffoldDir) },
+      });
+
+      const result = await getScaffoldContent("astro-minimal");
+
+      expect(mockToMinimalScaffoldId).not.toHaveBeenCalled();
+      expect(result.scaffoldId).toBe("astro-minimal");
+    });
+  });
+});

package/dist/cloud-scaffolds/__tests__/registry.test.ts

@@ -0,0 +1,134 @@
+import {
+  FRAMEWORK_REGISTRY,
+  getAvailableFrameworkNames,
+  getFrameworkDefinition,
+  listSupportedScaffoldIds,
+  toMinimalScaffoldId,
+} from "../registry";
+import { ScaffoldError } from "../types";
+
+describe("scaffold registry", () => {
+  describe("getFrameworkDefinition", () => {
+    it("returns definition for astro-minimal", () => {
+      const def = getFrameworkDefinition("astro-minimal");
+      expect(def.id).toBe("astro-minimal");
+      expect(def.name).toBe("Astro");
+      expect(def.source.type).toBe("github");
+      if (def.source.type === "github") {
+        expect(def.source.repo).toBe("Webflow-Examples/hello-world-astro");
+        expect(def.source.ref).toBe("v1");
+      }
+    });
+
+    it("returns definition for nextjs-minimal", () => {
+      const def = getFrameworkDefinition("nextjs-minimal");
+      expect(def.id).toBe("nextjs-minimal");
+      expect(def.name).toBe("Next.js");
+      expect(def.source.type).toBe("github");
+      if (def.source.type === "github") {
+        expect(def.source.repo).toBe("Webflow-Examples/hello-world-nextjs");
+      }
+    });
+
+    it("returns definition for astro (site-attached)", () => {
+      const def = getFrameworkDefinition("astro");
+      expect(def.id).toBe("astro");
+      expect(def.name).toBe("Astro (site-attached)");
+      expect(def.source.type).toBe("github");
+      if (def.source.type === "github") {
+        expect(def.source.repo).toBe(
+          "Webflow-Examples/hello-world-astro-devlink"
+        );
+      }
+    });
+
+    it("returns definition for nextjs (site-attached)", () => {
+      const def = getFrameworkDefinition("nextjs");
+      expect(def.id).toBe("nextjs");
+      expect(def.name).toBe("Next.js (site-attached)");
+      expect(def.source.type).toBe("github");
+      if (def.source.type === "github") {
+        expect(def.source.repo).toBe(
+          "Webflow-Examples/hello-world-nextjs-devlink"
+        );
+      }
+    });
+
+    it("throws ScaffoldError for unsupported scaffold ID", () => {
+      expect(() => getFrameworkDefinition("remix-minimal")).toThrow(
+        ScaffoldError
+      );
+      expect(() => getFrameworkDefinition("remix-minimal")).toThrow(
+        'Unsupported framework: "remix-minimal"'
+      );
+    });
+
+    it("includes supported IDs in ScaffoldError", () => {
+      try {
+        getFrameworkDefinition("unknown");
+        fail("Expected ScaffoldError");
+      } catch (err) {
+        expect(err).toBeInstanceOf(ScaffoldError);
+        expect((err as ScaffoldError).scaffoldId).toBe("unknown");
+        expect((err as ScaffoldError).supportedIds).toContain("astro-minimal");
+        expect((err as ScaffoldError).supportedIds).toContain("nextjs-minimal");
+        expect((err as ScaffoldError).supportedIds).toContain("astro");
+        expect((err as ScaffoldError).supportedIds).toContain("nextjs");
+      }
+    });
+  });
+
+  describe("listSupportedScaffoldIds", () => {
+    it("returns all registry keys", () => {
+      const ids = listSupportedScaffoldIds();
+      expect(ids).toEqual(
+        expect.arrayContaining([
+          "astro-minimal",
+          "nextjs-minimal",
+          "astro",
+          "nextjs",
+        ])
+      );
+      expect(ids).toHaveLength(Object.keys(FRAMEWORK_REGISTRY).length);
+    });
+  });
+
+  describe("getAvailableFrameworkNames", () => {
+    it("returns framework names without -minimal suffix", () => {
+      const names = getAvailableFrameworkNames();
+      expect(names).toEqual(expect.arrayContaining(["astro", "nextjs"]));
+      expect(names).toHaveLength(2);
+    });
+  });
+
+  describe("toMinimalScaffoldId", () => {
+    it("maps astro to astro-minimal", () => {
+      expect(toMinimalScaffoldId("astro")).toBe("astro-minimal");
+    });
+
+    it("maps nextjs to nextjs-minimal", () => {
+      expect(toMinimalScaffoldId("nextjs")).toBe("nextjs-minimal");
+    });
+
+    it("passes through astro-minimal unchanged", () => {
+      expect(toMinimalScaffoldId("astro-minimal")).toBe("astro-minimal");
+    });
+
+    it("throws ScaffoldError for unsupported framework", () => {
+      expect(() => toMinimalScaffoldId("remix")).toThrow(ScaffoldError);
+      expect(() => toMinimalScaffoldId("remix")).toThrow(
+        'No minimal scaffold for "remix"'
+      );
+    });
+
+    it("includes supported IDs in ScaffoldError", () => {
+      try {
+        toMinimalScaffoldId("vue");
+        fail("Expected ScaffoldError");
+      } catch (err) {
+        expect(err).toBeInstanceOf(ScaffoldError);
+        expect((err as ScaffoldError).supportedIds).toBeDefined();
+      }
+    });
+  });
+});

package/dist/cloud-scaffolds/fetcher.ts

@@ -0,0 +1,205 @@
+import * as fs from "fs";
+import fsExtra from "fs-extra";
+import * as path from "path";
+import * as os from "os";
+import * as tar from "tar";
+import { getFrameworkDefinition, toMinimalScaffoldId } from "./registry";
+import type { ScaffoldContent } from "./types";
+import { ScaffoldError } from "./types";
+import logger from "../../utils/logger";
+
+const GITHUB_TARBALL_BASE = "https://github.com";
+
+/**
+ * Get scaffold content for a framework.
+ * Resolves the scaffold ID (e.g. "astro" -> "astro-minimal") and fetches.
+ *
+ * @param frameworkOrScaffoldId - "astro", "nextjs", or full "astro-minimal", "nextjs-minimal"
+ * @returns ScaffoldContent ready for applyScaffold
+ */
+export async function getScaffoldContent(
+  frameworkOrScaffoldId: string
+): Promise<ScaffoldContent> {
+  const scaffoldId = frameworkOrScaffoldId.endsWith("-minimal")
+    ? frameworkOrScaffoldId
+    : toMinimalScaffoldId(frameworkOrScaffoldId);
+  return fetchScaffoldContent(scaffoldId);
+}
+
+/**
+ * Get scaffold content from the configured source (github or local).
+ * Dispatches to the appropriate fetcher based on source.type.
+ */
+export async function fetchScaffoldContent(
+  scaffoldId: string
+): Promise<ScaffoldContent> {
+  const def = getFrameworkDefinition(scaffoldId);
+
+  if (def.source.type === "github") {
+    return fetchScaffoldFromGitHub(scaffoldId);
+  }
+  return getScaffoldFromLocal(scaffoldId);
+}
+
+/**
+ * Get scaffold content from local filesystem.
+ */
+export async function getScaffoldFromLocal(
+  scaffoldId: string
+): Promise<ScaffoldContent> {
+  const def = getFrameworkDefinition(scaffoldId);
+
+  if (def.source.type !== "local") {
+    throw new ScaffoldError(
+      `Scaffold "${scaffoldId}" does not have a local source`,
+      scaffoldId
+    );
+  }
+
+  // path is relative to dist/ (e.g. "cloud-scaffolds/astro-minimal") or absolute
+  const scaffoldPath = path.isAbsolute(def.source.path)
+    ? def.source.path
+    : path.join(__dirname, def.source.path);
+  if (!fs.existsSync(scaffoldPath)) {
+    throw new ScaffoldError(
+      `Scaffold directory not found: ${scaffoldPath}`,
+      scaffoldId
+    );
+  }
+
+  const files = await listFilesRecursive(scaffoldPath);
+  return { scaffoldId, files, extractionRoot: scaffoldPath };
+}
+
+/**
+ * Download and extract a scaffold from GitHub.
+ * Uses the tarball API; no git dependency.
+ */
+async function fetchScaffoldFromGitHub(
+  scaffoldId: string
+): Promise<ScaffoldContent> {
+  const def = getFrameworkDefinition(scaffoldId);
+
+  if (def.source.type !== "github") {
+    throw new ScaffoldError(
+      `Scaffold "${scaffoldId}" does not have a GitHub source`,
+      scaffoldId
+    );
+  }
+
+  const ref = def.source.ref ?? "main";
+  const tarballUrl = `${GITHUB_TARBALL_BASE}/${def.source.repo}/archive/${ref}.tar.gz`;
+
+  const extractDir = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), `webflow-scaffold-${scaffoldId}-`)
+  );
+
+  const downloadSpinner = logger.spinner(
+    `Downloading scaffold (${def.source.repo}@${ref})`
+  );
+
+  try {
+    let response: Response;
+    try {
+      response = await fetch(tarballUrl, {
+        redirect: "follow",
+        headers: { "User-Agent": "webflow-cli" },
+      });
+    } catch (fetchErr) {
+      downloadSpinner.fail("Download failed");
+      throw new ScaffoldError(
+        `Failed to fetch scaffold from GitHub: ${
+          fetchErr instanceof Error ? fetchErr.message : String(fetchErr)
+        }. Repo: ${def.source.repo}, ref: ${ref}`,
+        scaffoldId
+      );
+    }
+
+    if (!response.ok) {
+      downloadSpinner.fail(
+        `GitHub returned ${response.status} ${response.statusText}`
+      );
+      throw new ScaffoldError(
+        `Failed to fetch scaffold from GitHub: ${response.status} ${response.statusText}. ` +
+          `Repo: ${def.source.repo}, ref: ${ref}`,
+        scaffoldId
+      );
+    }
+
+    const buffer = Buffer.from(await response.arrayBuffer());
+    downloadSpinner.succeed("Downloaded scaffold");
+
+    const unpackSpinner = logger.spinner("Unpacking scaffold");
+    try {
+      await extractTarball(buffer, extractDir);
+      unpackSpinner.succeed("Scaffold ready");
+    } catch (unpackErr) {
+      unpackSpinner.fail("Unpack failed");
+      throw unpackErr;
+    }
+
+    const entries = await fs.promises.readdir(extractDir);
+    const topLevelDir = entries[0];
+    if (!topLevelDir || entries.length !== 1) {
+      throw new ScaffoldError(
+        `Unexpected tarball structure for ${def.source.repo}`,
+        scaffoldId
+      );
+    }
+
+    const extractionRoot = path.join(extractDir, topLevelDir);
+    const files = await listFilesRecursive(extractionRoot);
+
+    return {
+      scaffoldId,
+      files,
+      extractionRoot,
+    };
+  } catch (err) {
+    try {
+      fsExtra.removeSync(extractDir);
+    } catch {
+      // Ignore cleanup errors
+    }
+    if (err instanceof ScaffoldError) throw err;
+    throw new ScaffoldError(
+      `Failed to fetch scaffold "${scaffoldId}": ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      scaffoldId
+    );
+  }
+}
+
+async function extractTarball(buffer: Buffer, destDir: string): Promise<void> {
+  const tmpFile = path.join(
+    os.tmpdir(),
+    `webflow-scaffold-${Date.now()}.tar.gz`
+  );
+  await fs.promises.writeFile(
+    tmpFile,
+    new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)
+  );
+  try {
+    await tar.extract({ file: tmpFile, cwd: destDir });
+  } finally {
+    await fs.promises.unlink(tmpFile).catch(() => {
+      // Ignore cleanup errors
+    });
+  }
+}
+
+async function listFilesRecursive(dirPath: string): Promise<string[]> {
+  const result: string[] = [];
+  const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...(await listFilesRecursive(fullPath)));
+    } else {
+      result.push(fullPath);
+    }
+  }
+  return result;
+}

package/dist/cloud-scaffolds/index.ts

@@ -0,0 +1,19 @@
+export {
+  getScaffoldContent,
+  fetchScaffoldContent,
+  getScaffoldFromLocal,
+} from "./fetcher";
+export {
+  FRAMEWORK_REGISTRY,
+  getFrameworkDefinition,
+  listSupportedScaffoldIds,
+  listExistingScaffoldIds,
+  getAvailableFrameworkNames,
+  toMinimalScaffoldId,
+} from "./registry";
+export type {
+  FrameworkDefinition,
+  ScaffoldContent,
+  ScaffoldSource,
+} from "./types";
+export { ScaffoldError } from "./types";