launchframe 0.3.0 → 0.4.0

package/bin/launchframe.mjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+/**
+ * Scaffold a Launchframe project: clone reference URL via AI workflow + SaaS landing copy.
+ * Usage: npx launchframe@latest <url> "<saas-idea>" [--dir=name] [--skip-install]
+ */
+
+import { cp, mkdir, readdir, readFile, writeFile } from "fs/promises";
+import { spawn } from "node:child_process";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, "..");
+
+const SKIP_DIR_NAMES = new Set(["bin", "node_modules", ".git", ".next", "dist", "out"]);
+
+/** Root dot-directories we ship for agent tooling */
+const ALLOW_DOT_DIRS = new Set([
+  ".cursor",
+  ".claude",
+  ".codex",
+  ".continue",
+  ".gemini",
+  ".opencode",
+  ".windsurf",
+  ".github",
+]);
+
+const SKIP_ROOT_FILES = new Set(["package-lock.json"]);
+
+function printHelp() {
+  console.log(`
+launchframe — scaffold a Next.js app for cloning a reference site + your SaaS idea
+
+Usage:
+  npx launchframe@latest <url> "<saas-idea>" [options]
+
+Arguments:
+  <url>           HTTPS URL of the site to reverse-engineer (visual reference)
+  "<saas-idea>"   Short pitch / positioning that should appear on the landing page
+
+Options:
+  --dir, -o       Output folder (default: first label of hostname + "-launchframe")
+  --skip-install  Do not run npm install after scaffolding
+  -h, --help      Show this message
+
+Note:
+  The output folder must not live inside the Launchframe package directory (the folder that contains this CLI).
+
+Example:
+  npx launchframe@latest https://stripe.com "AI invoicing for freelancers"
+`);
+}
+
+function parseArgs(argv) {
+  const out = {
+    url: null,
+    idea: null,
+    dir: null,
+    skipInstall: false,
+    help: false,
+  };
+
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") {
+      out.help = true;
+      continue;
+    }
+    if (a === "--skip-install") {
+      out.skipInstall = true;
+      continue;
+    }
+    if (a === "--dir" || a === "-o") {
+      out.dir = argv[++i];
+      continue;
+    }
+    if (a.startsWith("--dir=")) {
+      out.dir = a.slice("--dir=".length);
+      continue;
+    }
+    if (a.startsWith("-o=")) {
+      out.dir = a.slice("-o=".length);
+      continue;
+    }
+    positional.push(a);
+  }
+
+  if (positional[0]) out.url = positional[0];
+  if (positional[1]) out.idea = positional[1];
+
+  return out;
+}
+
+function validateUrl(raw) {
+  let u;
+  try {
+    u = new URL(raw);
+  } catch {
+    throw new Error(`Invalid URL: ${raw}`);
+  }
+  if (u.protocol !== "http:" && u.protocol !== "https:") {
+    throw new Error("URL must start with http:// or https://");
+  }
+  return u.href;
+}
+
+function defaultDirName(urlStr) {
+  try {
+    const host = new URL(urlStr).hostname.replace(/^www\./i, "");
+    const label = host.split(".")[0] || "site";
+    const safe = label.replace(/[^a-zA-Z0-9-_]/g, "-").toLowerCase();
+    return `${safe || "site"}-launchframe`;
+  } catch {
+    return "launchframe-app";
+  }
+
+}
+
+function slugFromDir(dir) {
+  const base = dir.replace(/\\/g, "/").split("/").filter(Boolean).pop() ?? "launchframe-app";
+  return base
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "") || "launchframe-app";
+}
+
+function tsStringLiteral(value) {
+  return JSON.stringify(value);
+}
+
+function shouldCopyRootEntry(baseName, isDirectory) {
+  if (SKIP_DIR_NAMES.has(baseName)) return false;
+  if (isDirectory && baseName.startsWith(".")) {
+    if (!ALLOW_DOT_DIRS.has(baseName)) return false;
+  }
+  if (!isDirectory && SKIP_ROOT_FILES.has(baseName)) return false;
+  return true;
+}
+
+/** Output cannot be inside the template package tree (would recurse while copying). */
+function isForbiddenOutput(packageRootAbs, destRootAbs) {
+  const pkg = resolve(packageRootAbs);
+  const dest = resolve(destRootAbs);
+  if (dest === pkg) return true;
+  const rel = relative(pkg, dest);
+  return Boolean(rel) && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+async function copyTemplateTree(sourceRoot, destRootAbs) {
+  await mkdir(destRootAbs, { recursive: true });
+  const entries = await readdir(sourceRoot, { withFileTypes: true });
+  const destResolved = resolve(destRootAbs);
+  for (const ent of entries) {
+    const from = join(sourceRoot, ent.name);
+    if (resolve(from) === destResolved) continue;
+    if (!shouldCopyRootEntry(ent.name, ent.isDirectory())) continue;
+    const to = join(destRootAbs, ent.name);
+    await cp(from, to, { recursive: true });
+  }
+}
+
+async function writeGeneratedPackageJson(destRoot, npmPackageName) {
+  const raw = await readFile(join(PKG_ROOT, "package.json"), "utf8");
+  const pkg = JSON.parse(raw);
+
+  const nextPkg = {
+    name: npmPackageName,
+    version: "0.1.0",
+    private: true,
+    description: pkg.description,
+    license: pkg.license,
+    engines: pkg.engines,
+    scripts: pkg.scripts,
+    dependencies: pkg.dependencies,
+    devDependencies: pkg.devDependencies,
+    keywords: pkg.keywords,
+  };
+
+  await writeFile(
+    join(destRoot, "package.json"),
+    `${JSON.stringify(nextPkg, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+async function writeLaunchframeArtifacts(destRoot, url, idea) {
+  const configTs = `/**
+ * Written by Launchframe CLI — edit freely after scaffolding.
+ */
+export const LAUNCHFRAME_SOURCE_URL = ${tsStringLiteral(url)} as const;
+
+export const LAUNCHFRAME_SAAS_IDEA = ${tsStringLiteral(idea)} as const;
+`;
+
+  await writeFile(join(destRoot, "src", "lib", "launchframe-config.ts"), configTs, "utf8");
+
+  const ctx = {
+    sourceUrl: url,
+    saasIdea: idea,
+    notes:
+      "Use /clone-website with sourceUrl for pixel-perfect extraction. Align landing copy with saasIdea.",
+  };
+  await writeFile(
+    join(destRoot, "launchframe.context.json"),
+    `${JSON.stringify(ctx, null, 2)}\n`,
+    "utf8",
+  );
+
+  const md = `# Launchframe context
+
+## Reference URL (clone target)
+
+${url}
+
+## SaaS idea (landing copy)
+
+${idea}
+
+When running \`/clone-website\`, pass the reference URL above. After structural cloning, rewrite headings and hero copy so they clearly communicate the SaaS idea while respecting attribution and copyright for third-party brands.
+`;
+
+  await mkdir(join(destRoot, "docs", "research"), { recursive: true });
+  await writeFile(join(destRoot, "docs", "research", "LAUNCHFRAME.md"), md, "utf8");
+}
+
+async function writeReadme(destRoot, npmPackageName, url, idea) {
+  const body = `# ${npmPackageName}
+
+Created with [\`launchframe\`](https://www.npmjs.com/package/launchframe).
+
+## Inputs
+
+- **Reference site:** ${url}
+- **SaaS idea:** ${idea}
+
+## Quick start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+Open your AI agent (Cursor, Claude Code, etc.) and run:
+
+\`\`\`
+/clone-website ${url}
+\`\`\`
+
+Keep the SaaS positioning from \`launchframe.context.json\` / \`src/lib/launchframe-config.ts\` when adapting cloned sections.
+
+See \`AGENTS.md\` for full agent instructions.
+`;
+
+  await writeFile(join(destRoot, "README.md"), body, "utf8");
+}
+
+function runNpmInstall(cwd) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn("npm", ["install"], {
+      cwd,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    child.on("exit", (code) => {
+      if (code === 0) resolvePromise();
+      else reject(new Error(`npm install exited with code ${code}`));
+    });
+    child.on("error", reject);
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (!args.url || !args.idea) {
+    console.error("Error: missing URL or SaaS idea.\n");
+    printHelp();
+    process.exit(1);
+  }
+
+  let url;
+  try {
+    url = validateUrl(args.url);
+  } catch (e) {
+    console.error(String(e.message));
+    process.exit(1);
+  }
+
+  const idea = args.idea.trim();
+  if (!idea) {
+    console.error("Error: SaaS idea cannot be empty.");
+    process.exit(1);
+  }
+
+  const dirName = args.dir?.trim() || defaultDirName(url);
+  const destRoot = resolve(process.cwd(), dirName);
+  const npmPackageName = slugFromDir(dirName);
+
+  if (isForbiddenOutput(PKG_ROOT, destRoot)) {
+    console.error(
+      "Output folder cannot be inside the Launchframe package directory. Run from a parent folder or choose another path.",
+    );
+    process.exit(1);
+  }
+
+  await mkdir(destRoot, { recursive: true });
+
+  await copyTemplateTree(PKG_ROOT, destRoot);
+
+  await writeGeneratedPackageJson(destRoot, npmPackageName);
+  await writeLaunchframeArtifacts(destRoot, url, idea);
+  await writeReadme(destRoot, npmPackageName, url, idea);
+
+  console.log(`\nCreated Launchframe project at ${destRoot}`);
+  console.log(`  Reference URL: ${url}`);
+  console.log(`  SaaS idea: ${idea}\n`);
+
+  if (!args.skipInstall) {
+    console.log("Running npm install...\n");
+    try {
+      await runNpmInstall(destRoot);
+      console.log("\nDone. Next: cd " + JSON.stringify(dirName) + " && npm run dev\n");
+    } catch (e) {
+      console.error(String(e.message));
+      console.error("\nDependencies were not installed. Run npm install inside the folder manually.\n");
+      process.exit(1);
+    }
+  } else {
+    console.log("Skipped npm install (--skip-install). Run npm install inside the folder.\n");
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/docs/research/INSPECTION_GUIDE.md

@@ -1,124 +1,80 @@
-# Website Inspection Guide
-
-## Priority (read first): media & motion
-
-Launchframe clones live pages for a **visual** result. Two things most often separate a convincing build from a hollow one:
-
-### 1. Images & video (do this before obsessing over utility classes)
-
-- [ ] **Every `<img>`** — `src` / `srcset` / `currentSrc`, `sizes`, `loading`, `decoding`, `alt`, intrinsic dimensions
-- [ ] **`<picture>` / `<source>`** — resolution switches, art direction, `type` (WebP/AVIF)
-- [ ] **Every `<video>`** — `src` + nested `<source>`, **poster**, `autoplay`, `loop`, `muted`, `playsinline`, `controls`
-- [ ] **Background images** — `background-image` on ancestors (hero stacks are often **layers** of img + gradient + PNG mockup)
-- [ ] **Lazy / below-fold** — scroll the page once before asset discovery so `data-src` / lazy-loaded URLs resolve if the site uses them
-- [ ] **Download** — mirror into `public/images/` and `public/videos/` with stable paths; list failures in `docs/research/EXTRACTION_LIMITATIONS.md`
-
-If automation hits a bot wall, **do not pretend extraction succeeded** — capture what you can from successful fetches and document gaps.
-
-### 2. Motion (prefer Framer Motion in this repo)
-
-- [ ] **Entrance** — fade/slide/scale on mount or on **scroll into view** (note threshold / `margin`)
-- [ ] **Stagger** — children animating in sequence (hero bullets, card grids)
-- [ ] **Scroll-linked** — progress, parallax, pinned sections (may combine with CSS `animation-timeline` or libs)
-- [ ] **Gestures** — drag, pan, hover follow (often Framer Motion)
-- [ ] **Implementation rule** — use **`framer-motion`** for anything beyond trivial single-property CSS `transition`. Record **duration, easing, delay, stagger**, and **trigger** (scroll, hover, tap) in specs.
-
-### 3. Idea-tailored illustration & motifs *(production landings)*
-
-When the reference page is **sparse** (mostly type + gray boxes) or after a **rebrand** the UI still reads generic, illustration is required — and it must be **unique to the SaaS idea** (`launchframe.config.json#idea`), not reusable wallpaper.
-
-- [ ] **Metaphor list** — 3–6 nouns/verbs derived from `idea`; every bespoke asset maps to ≥ one entry
-- [ ] **Uniqueness check** — If the scene works unchanged for another product category, revise
-- [ ] **Inline SVG** — hero shapes, dividers, card mini-scenes; note `viewBox`, **`currentColor`** vs fixed fills, **Idea tie-in** sentence per asset
-- [ ] **Pixel art / sprites** — only when character reinforces the metaphor; palette hex table; `imageRendering` / grid discipline
-- [ ] **Motif thread** — recurring element echoing hero + OG + favicon **for this product**, not a random geometric pattern
-- [ ] **Accent tokens** — primary/secondary roles aligned with idea personality (extract from reference or define in `:root`)
-- [ ] **Motion tiers A–E** — document with **reduced-motion** fallback (`prefers-reduced-motion`)
-
-See **`AGENTS.md` → Production polish for marketing landings** for tier definitions and folders (`src/components/marketing/art/`, `public/images/marketing/`).
-
----
-
-## How to Reverse-Engineer Any Website
-
-This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
-
-## Phase 1: Visual Audit
-
-### Screenshots to Capture
-- [ ] **Single-page landing — full scroll depth** — slow-scroll until lazy sections stabilize; **`fullPage`** / stitched capture so footer and below-fold bands are included (not viewport-only hero grabs)
-- [ ] Every distinct page — desktop, tablet, mobile
-- [ ] Dark mode variants (if applicable)
-- [ ] Light mode variants (if applicable)
-- [ ] Key interaction states (hover, active, open menus, modals)
-- [ ] Loading/skeleton states
-- [ ] Empty states
-- [ ] Error states
-- [ ] **Video frames** — capture a frame mid-play for reference if motion is subtle
-- [ ] **Hero / full-bleed** — wide crops where raster layers are easy to miss
-
-### Design Tokens to Extract
-- [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
-- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
-- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
-- [ ] **Border radius** — buttons, cards, avatars, inputs
-- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
-- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
-- [ ] **Icons** — which icon library? custom SVGs? sizes?
-- [ ] **Avatars** — sizes, shapes, fallback behavior
-- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
-- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
-
-## Phase 2: Component Inventory
-
-For each distinct UI component, document:
-1. **Name** — what would you call this component?
-2. **Structure** — what HTML elements / child components does it contain?
-3. **Variants** — does it have different sizes, colors, or states?
-4. **States** — default, hover, active, disabled, loading, error, empty
-5. **Responsive behavior** — how does it change at different breakpoints?
-6. **Interactions** — click, hover, focus, keyboard navigation
-7. **Animations** — transitions, entrance/exit, micro-interactions — **`framer-motion` vs CSS** and exact timing
-
-### Common Components to Look For
-- Navigation (top bar, sidebar, bottom bar)
-- Cards / list items
-- Buttons and links
-- Forms and inputs
-- Modals and dialogs
-- Dropdowns and menus
-- Tabs and segmented controls
-- Avatars and user badges
-- Loading skeletons
-- Toast notifications
-- Tooltips and popovers
-- **Video / Lottie / canvas** blocks (do not substitute with static mockups without documenting why)
-
-## Phase 3: Layout Architecture
-
-- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
-- [ ] **Column layout** — how many columns at each breakpoint?
-- [ ] **Max-width** — main content area max-width
-- [ ] **Sticky elements** — header, sidebar, floating buttons
-- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
-- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
-
-## Phase 4: Technical Stack Analysis
-
-- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
-- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
-- [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
-- [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
-- [ ] **Font loading** — Google Fonts, self-hosted, system fonts
-- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF — **mirror URLs you are allowed to fetch**
-- [ ] **Animation library** — site may use GSAP, Lottie, Rive, or CSS only — **in the Next.js clone, default to Framer Motion** unless a different lib is required for parity
-
-## Phase 5: Documentation Output
-
-After inspection, create these files in `docs/research/`:
-1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
-2. `COMPONENT_INVENTORY.md` — Every component with structure notes
-3. **`MEDIA_MANIFEST.md`** — (recommended) Table of every image/video/poster URL → local `public/` path or “blocked”
-4. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
-5. `INTERACTION_PATTERNS.md` — Animations: **CSS vs Framer Motion**, transitions, hover states
-6. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents (Framer Motion for React animation)
+# Website Inspection Guide
+
+## How to Reverse-Engineer Any Website
+
+This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
+
+## Phase 1: Visual Audit
+
+### Screenshots to Capture
+- [ ] Every distinct page — desktop, tablet, mobile
+- [ ] Dark mode variants (if applicable)
+- [ ] Light mode variants (if applicable)
+- [ ] Key interaction states (hover, active, open menus, modals)
+- [ ] Loading/skeleton states
+- [ ] Empty states
+- [ ] Error states
+
+### Design Tokens to Extract
+- [ ] **Colors** — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
+- [ ] **Typography** — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
+- [ ] **Spacing** — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
+- [ ] **Border radius** — buttons, cards, avatars, inputs
+- [ ] **Shadows/elevation** — card shadows, dropdown shadows, modal overlay
+- [ ] **Breakpoints** — when does the layout shift? (inspect with DevTools responsive mode)
+- [ ] **Icons** — which icon library? custom SVGs? sizes?
+- [ ] **Avatars** — sizes, shapes, fallback behavior
+- [ ] **Buttons** — all variants (primary, secondary, ghost, icon-only, danger)
+- [ ] **Inputs** — text fields, textareas, selects, checkboxes, toggles
+
+## Phase 2: Component Inventory
+
+For each distinct UI component, document:
+1. **Name** — what would you call this component?
+2. **Structure** — what HTML elements / child components does it contain?
+3. **Variants** — does it have different sizes, colors, or states?
+4. **States** — default, hover, active, disabled, loading, error, empty
+5. **Responsive behavior** — how does it change at different breakpoints?
+6. **Interactions** — click, hover, focus, keyboard navigation
+7. **Animations** — transitions, entrance/exit animations, micro-interactions
+
+### Common Components to Look For
+- Navigation (top bar, sidebar, bottom bar)
+- Cards / list items
+- Buttons and links
+- Forms and inputs
+- Modals and dialogs
+- Dropdowns and menus
+- Tabs and segmented controls
+- Avatars and user badges
+- Loading skeletons
+- Toast notifications
+- Tooltips and popovers
+
+## Phase 3: Layout Architecture
+
+- [ ] **Grid system** — CSS Grid? Flexbox? Fixed widths?
+- [ ] **Column layout** — how many columns at each breakpoint?
+- [ ] **Max-width** — main content area max-width
+- [ ] **Sticky elements** — header, sidebar, floating buttons
+- [ ] **Z-index layers** — navigation, modals, tooltips, overlays
+- [ ] **Scroll behavior** — infinite scroll, pagination, virtual scrolling
+
+## Phase 4: Technical Stack Analysis
+
+- [ ] **Framework** — React? Vue? Angular? Check `__NEXT_DATA__`, `__NUXT__`, `ng-version`
+- [ ] **CSS approach** — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
+- [ ] **State management** — Redux (check DevTools), React Query, Zustand, Pinia
+- [ ] **API patterns** — REST, GraphQL (check network tab for `/graphql` requests)
+- [ ] **Font loading** — Google Fonts, self-hosted, system fonts
+- [ ] **Image strategy** — CDN, lazy loading, srcset, WebP/AVIF
+- [ ] **Animation library** — Framer Motion, GSAP, CSS transitions only
+
+## Phase 5: Documentation Output
+
+After inspection, create these files in `docs/research/`:
+1. `DESIGN_TOKENS.md` — All extracted colors, typography, spacing
+2. `COMPONENT_INVENTORY.md` — Every component with structure notes
+3. `LAYOUT_ARCHITECTURE.md` — Page layouts, grid system, responsive behavior
+4. `INTERACTION_PATTERNS.md` — Animations, transitions, hover states
+5. `TECH_STACK_ANALYSIS.md` — What the site uses and our chosen equivalents