launchframe 0.4.0 → 0.4.1

package/.windsurf/workflows/launchframe.md

@@ -0,0 +1,42 @@
+<!-- AUTO-GENERATED from .claude/skills/launchframe/SKILL.md — do not edit directly.
+     Run `node scripts/sync-skills.mjs` to regenerate. -->
+
+
+# Launchframe
+
+You are helping the user scaffold a **new** project from **the reference URL and SaaS idea from the user (see slash command arguments)**:
+
+- A **reference URL** (the website to copy later with `/clone-website`)
+- A **SaaS idea** string (headline / positioning for the generated landing page)
+
+## Parse inputs
+
+1. Split **the reference URL and SaaS idea from the user (see slash command arguments)** into:
+   - **URL** — First `http://` or `https://` URL. Normalize (trim, validate). If invalid or missing, ask once for a correct URL.
+   - **SaaS idea** — Everything after the URL, typically in quotes. Strip surrounding quotes. If empty, ask for a short product pitch.
+
+2. Optional flags the user might pass (same as the CLI): `--dir` / `-o` for output folder, `--skip-install` to skip `npm install`.
+
+## Run the published CLI
+
+Execute the scaffold using the **latest** package from npm (exact intent: **`launchframe@latest`**):
+
+```bash
+npx launchframe@latest "<url>" "<saas-idea>" [--dir <folder>] [--skip-install]
+```
+
+- Use shell-appropriate quoting (PowerShell vs bash). Escape embedded quotes in the SaaS idea.
+- **Output path:** The Launchframe CLI must not write **inside** the npm package / template directory itself (that would recurse). If the open workspace is this repository, run `npx` with `--dir` pointing to a **sibling** path (e.g. `..\\my-app` on Windows, `../my-app` on macOS/Linux) or ask the user for a folder **outside** the repo.
+- Prefer letting the CLI run `npm install` unless the user passed `--skip-install`.
+
+## After scaffold
+
+Tell the user:
+
+1. `cd` into the new project directory.
+2. `npm run dev` to preview the SaaS landing shell.
+3. Run **`/clone-website <same-reference-url>`** in that project so the agent can reverse-engineer the reference site into components, while keeping the SaaS idea from `launchframe.context.json` / `src/lib/launchframe-config.ts`.
+
+## Fallback (local dev only)
+
+If `npx launchframe@latest` is unavailable (offline), from a **checkout of this repo** you may run `node bin/launchframe.mjs "<url>" "<saas-idea>" ...` with the same rules for `--dir` outside the package root.

package/AGENTS.md

@@ -7,7 +7,7 @@ This version has breaking changes — APIs, conventions, and file structure may
 # Website Reverse-Engineer Template
 
 ## What This Is
-A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — just run `/clone-website <url1> [<url2> ...]`.
+A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — start a **new** project with **`/launchframe <url> "your saas idea"`** (runs **`npx launchframe@latest`**), or work in the current repo and run **`/clone-website <url1> [<url2> ...]`** to clone into this tree.
 
 ## Tech Stack
 - **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
@@ -35,6 +35,7 @@ A reusable template for reverse-engineering any website into a clean, modern Nex
 - **No personal aesthetic changes during emulation phase** — match 1:1 first, customize later
 - **Real content** — use actual text and assets from the target site, not placeholders
 - **Beauty-first** — every pixel matters
+- **DOM crawl priority** — when walking the target page, emphasize **images** (raster, responsive sources, CSS backgrounds), **SVGs** (inline icons, sprites, masks), then **motion** (keyframes, transitions, scroll/time-driven animation, libraries). Scrape and save real assets from the DOM/network first; **create** a stand-in image or vector only when fetch/blocking prevents extraction, and label substitutes clearly in research notes so the clone stays auditable
 
 ## Project Structure
 ```
@@ -60,6 +61,6 @@ scripts/            # Asset download scripts
 ## MOST IMPORTANT NOTES
 - When launching Claude Code agent teams, ALWAYS have each teammate work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly since you are basically serving the orchestrator role and have full context to our goals, work given, work achieved, and desired outcomes.
 - After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
-- After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
+- After editing `.claude/skills/*/SKILL.md` (for example `clone-website` or `launchframe`), run `node scripts/sync-skills.mjs` to regenerate skill and command files for all platforms.
 
 @docs/research/INSPECTION_GUIDE.md

package/README.md

@@ -2,7 +2,7 @@
 
 <a href="https://github.com/JCodesMore/ai-website-cloner-template/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a> <a href="https://github.com/JCodesMore/ai-website-cloner-template/stargazers"><img src="https://img.shields.io/github/stars/JCodesMore/ai-website-cloner-template?style=flat" alt="Stars" /></a> <a href="https://discord.gg/hrTSX5yTpB"><img src="https://img.shields.io/discord/1400896964597383279?label=discord" alt="Discord" /></a>
 
-Scaffold a Next.js + shadcn/ui project from **a reference URL you want to copy** plus **your SaaS idea** that drives landing-page positioning. Then run `/clone-website` so your AI agent reverse-engineers the reference layout while preserving your messaging inputs (`launchframe.context.json`, `docs/research/LAUNCHFRAME.md`, `src/lib/launchframe-config.ts`).
+Scaffold a Next.js + shadcn/ui project from **a reference URL you want to copy** plus **your SaaS idea** that drives landing-page positioning. Use **`npx launchframe@latest`** or the slash command **`/launchframe <url> "your idea"`** to scaffold, then run **`/clone-website`** so your AI agent reverse-engineers the reference layout while preserving your messaging inputs (`launchframe.context.json`, `docs/research/LAUNCHFRAME.md`, `src/lib/launchframe-config.ts`).
 
 **Recommended: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with Opus 4.7 for best results** — but works with a variety of AI coding agents.
 
@@ -14,7 +14,17 @@ Scaffold a Next.js + shadcn/ui project from **a reference URL you want to copy**
 
 ## Quick Start
 
-### CLI (recommended)
+### AI agents (slash command)
+
+In Cursor, Claude Code, Continue, and other synced tools:
+
+```text
+/launchframe https://example.com "Your SaaS idea in plain language"
+```
+
+The agent runs **`npx launchframe@latest`** with those arguments (see `.cursor/commands/launchframe.md`). Output must be **outside** the template package directory when developing from a clone of this repo — use `--dir ../my-app` or an absolute path.
+
+### CLI (same as slash command)
 
 From an empty folder (or anywhere you want the project folder created):
 
@@ -22,6 +32,8 @@ From an empty folder (or anywhere you want the project folder created):
 npx launchframe@latest https://example.com "Your SaaS idea in plain language"
 ```
 
+Scaffolding copies the full template at the repository root — including **hidden agent config** (for example `.cursor/`, `.claude/`, `.github/`, `.amazonq/`, `.augment/`, and other dotfiles) so tools see the same rules and commands as this template.
+
 Optional flags:
 
 - `--dir my-app` / `-o my-app` — output folder name (default: `<hostname>-launchframe`)
@@ -39,7 +51,7 @@ Open your AI agent and run `/clone-website <same-reference-url>` so it rebuilds
 ### Git template (advanced)
 
 1. Clone this repository and `npm install`
-2. Replace `src/lib/launchframe-config.ts` or run `npx launchframe ...` into a fresh folder
+2. Replace `src/lib/launchframe-config.ts` or run `npx launchframe@latest ...` into a fresh folder
 3. Run `/clone-website <target-url>` from your agent
 
 > Using a different agent? Open `AGENTS.md` for project instructions — most agents pick it up automatically.

package/bin/launchframe.mjs

@@ -12,21 +12,27 @@ 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",
+/**
+ * Never copy these root entries into a scaffolded app (build artifacts, VCS, the CLI itself).
+ * All other root files and folders are copied as-is — including every dotfile and dot-directory
+ * so AI agents see the same agent rules, skills, and IDE metadata as this template.
+ */
+const SKIP_DIR_NAMES = new Set([
+  "bin",
+  "node_modules",
+  ".git",
+  ".next",
+  "dist",
+  "out",
+  "coverage",
+  ".turbo",
 ]);
 
-const SKIP_ROOT_FILES = new Set(["package-lock.json"]);
+const SKIP_ROOT_FILES = new Set([
+  "package-lock.json",
+  ".DS_Store",
+  "Thumbs.db",
+]);
 
 function printHelp() {
   console.log(`
@@ -46,6 +52,8 @@ Options:
 
 Note:
   The output folder must not live inside the Launchframe package directory (the folder that contains this CLI).
+  Scaffolding copies every root file and folder from the template (including dotfiles such as .cursor, .claude,
+  .github, etc.) except build/cache directories, so your AI tools see the same rules and commands as upstream.
 
 Example:
   npx launchframe@latest https://stripe.com "AI invoicing for freelancers"
@@ -133,9 +141,6 @@ function tsStringLiteral(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;
 }

package/docs/research/INSPECTION_GUIDE.md

@@ -4,6 +4,16 @@
 
 This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
 
+## Priority: media, SVGs, and motion (do this early)
+
+When crawling the DOM and network, **tackle these before fine-tuning copy or spacing**:
+
+1. **Raster imagery** — Every `<img>`, `<picture>` / `source`, `srcset` / `sizes`, CDN URLs, lazy-loaded `data-src`, `loading="lazy"` nodes, **CSS `background-image`** on the element and ancestors (including `::before` / `::after`), masks that use `url()`, `<video>` still / poster frames. Prefer **downloading** originals via scripts or MCP; if a URL is blocked or session-gated, **export a screenshot** of the element’s bounding box at a crisp DPR and store it under `public/images/`, and note the substitute in the spec.
+2. **SVGs** — Inline `<svg>`, `<use>` / sprite sheets, **SVG in CSS** (`mask-image`, `background-image`), favicons as SVG, logo marks. Prefer extracting path/viewBox into React components or static files under `public/` — **recreate** from a screenshot/trace only when the markup is obfuscated or blocked.
+3. **Motion & animation** — Inspect Styles for `animation`, `animation-name`, `animation-timeline`, `transition`, `transform`, `@keyframes`; check for libraries (Framer Motion, GSAP, Lottie, Lenis). Capture **durations, easings, delays, fill-modes**, scroll/view triggers, and `prefers-reduced-motion` handling. Motion often defines perceived quality — do not leave it as an afterthought.
+
+Then continue with typography, spacing, and component structure as usual.
+
 ## Phase 1: Visual Audit
 
 ### Screenshots to Capture

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchframe",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "private": false,
   "description": "Scaffold a Next.js app from a reference URL plus your SaaS idea — AI-ready website cloning",
   "author": "JCodesMore",
@@ -62,7 +62,9 @@
     ".gemini",
     ".opencode",
     ".windsurf",
-    ".github"
+    ".github",
+    ".amazonq",
+    ".augment"
   ],
   "scripts": {
     "dev": "next dev",

package/scripts/sync-skills.mjs

@@ -1,111 +1,124 @@
 #!/usr/bin/env node
 
 /**
- * Generates clone-website command/skill files for all supported AI coding platforms.
- * Source of truth: .claude/skills/clone-website/SKILL.md
+ * Generates invokable skill/command files for all supported AI coding platforms.
+ * Source of truth: `.claude/skills/<skill-id>/SKILL.md` (YAML frontmatter + markdown body).
  *
  * Usage: node scripts/sync-skills.mjs
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+const SKILLS = [
+  {
+    id: "clone-website",
+    sourceRel: ".claude/skills/clone-website/SKILL.md",
+    shortDesc: "Reverse-engineer and clone any website as a pixel-perfect replica",
+    plainSubstitution: "the target URL provided by the user",
+    augmentArgumentHint: "<url>",
+  },
+  {
+    id: "launchframe",
+    sourceRel: ".claude/skills/launchframe/SKILL.md",
+    shortDesc:
+      "Scaffold a Next.js app with npx launchframe@latest from a reference URL and SaaS idea",
+    plainSubstitution:
+      "the reference URL and SaaS idea from the user (see slash command arguments)",
+    augmentArgumentHint: "<url> \"<saas-idea>\"",
+  },
+];
 
-const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
-const SOURCE = join(ROOT, '.claude', 'skills', 'clone-website', 'SKILL.md');
-
-// --- Parse source skill ---
-
-let raw;
-try {
-  raw = readFileSync(SOURCE, 'utf8').replace(/\r\n/g, '\n');
-} catch {
-  console.error(`Error: Source skill not found at .claude/skills/clone-website/SKILL.md`);
-  process.exit(1);
+function write(relPath, content) {
+  const full = join(ROOT, relPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content, "utf8");
+  console.log(`  \u2713 ${relPath}`);
 }
 
-const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-if (!match) {
-  console.error('Error: Could not parse SKILL.md frontmatter');
-  process.exit(1);
+function parseSkill(sourceRel) {
+  const full = join(ROOT, sourceRel);
+  const raw = readFileSync(full, "utf8").replace(/\r\n/g, "\n");
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) {
+    throw new Error(`Could not parse frontmatter: ${sourceRel}`);
+  }
+  return { raw, body: match[2] };
 }
 
-const body = match[2];
-const shortDesc = 'Reverse-engineer and clone any website as a pixel-perfect replica';
+function syncSkill(skill) {
+  const { id, sourceRel, shortDesc, plainSubstitution, augmentArgumentHint } = skill;
+
+  let parsed;
+  try {
+    parsed = parseSkill(sourceRel);
+  } catch (e) {
+    console.error(e.message || e);
+    process.exit(1);
+  }
+
+  const { raw, body } = parsed;
+  const noArgs = (text) => text.replace(/\$ARGUMENTS/g, plainSubstitution);
+  const header =
+    `<!-- AUTO-GENERATED from ${sourceRel} \u2014 do not edit directly.\n` +
+    `     Run \`node scripts/sync-skills.mjs\` to regenerate. -->\n\n`;
+
+  console.log(`\nSyncing ${id}...\n  Source: ${sourceRel}\n`);
+
+  write(`.codex/skills/${id}/SKILL.md`, raw);
+  write(`.github/skills/${id}/SKILL.md`, raw);
+
+  write(`.cursor/commands/${id}.md`, header + noArgs(body));
+
+  write(`.windsurf/workflows/${id}.md`, header + noArgs(body));
+
+  const geminiBody = body.replace(/\$ARGUMENTS/g, "{{args}}");
+  write(
+    `.gemini/commands/${id}.toml`,
+    `# AUTO-GENERATED from ${sourceRel}\n` +
+      `# Run \`node scripts/sync-skills.mjs\` to regenerate.\n\n` +
+      `description = ${JSON.stringify(shortDesc)}\n\n` +
+      `[prompt]\ntext = '''\n${geminiBody}\n'''\n`,
+  );
+
+  write(
+    `.opencode/commands/${id}.md`,
+    `---\ndescription: ${JSON.stringify(shortDesc)}\n---\n${header}${body}`,
+  );
+
+  write(
+    `.augment/commands/${id}.md`,
+    `---\ndescription: ${JSON.stringify(shortDesc)}\nargument-hint: ${JSON.stringify(augmentArgumentHint)}\n---\n${header}${body}`,
+  );
+
+  write(
+    `.continue/commands/${id}.md`,
+    `---\nname: ${id}\ndescription: ${JSON.stringify(shortDesc)}\ninvokable: true\n---\n${header}${body}`,
+  );
+
+  write(
+    `.amazonq/cli-agents/${id}.json`,
+    JSON.stringify(
+      {
+        name: id,
+        description: shortDesc,
+        prompt: noArgs(body),
+        fileContext: ["AGENTS.md", "docs/research/**"],
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+}
 
-// --- Helpers ---
+console.log("Syncing skills to all platforms...");
 
-function write(relPath, content) {
-  const full = join(ROOT, relPath);
-  mkdirSync(dirname(full), { recursive: true });
-  writeFileSync(full, content, 'utf8');
-  console.log(`  \u2713 ${relPath}`);
+for (const skill of SKILLS) {
+  syncSkill(skill);
 }
 
-const HEADER =
-  '<!-- AUTO-GENERATED from .claude/skills/clone-website/SKILL.md \u2014 do not edit directly.\n' +
-  '     Run `node scripts/sync-skills.mjs` to regenerate. -->\n\n';
-
-const noArgs = (text) => text.replace(/\$ARGUMENTS/g, 'the target URL provided by the user');
-
-// --- Generate ---
-
-console.log('Syncing clone-website skill to all platforms...');
-console.log(`  Source: .claude/skills/clone-website/SKILL.md\n`);
-
-// 1. Codex CLI — same SKILL.md format, same $ARGUMENTS syntax
-write('.codex/skills/clone-website/SKILL.md', raw);
-
-// 2. GitHub Copilot — same SKILL.md format
-write('.github/skills/clone-website/SKILL.md', raw);
-
-// 3. Cursor — plain markdown, no argument substitution support
-write('.cursor/commands/clone-website.md', HEADER + noArgs(body));
-
-// 4. Windsurf — markdown workflow
-write('.windsurf/workflows/clone-website.md', HEADER + noArgs(body));
-
-// 5. Gemini CLI — TOML format, {{args}} for arguments
-const geminiBody = body.replace(/\$ARGUMENTS/g, '{{args}}');
-write(
-  '.gemini/commands/clone-website.toml',
-  `# AUTO-GENERATED from .claude/skills/clone-website/SKILL.md\n` +
-    `# Run \`node scripts/sync-skills.mjs\` to regenerate.\n\n` +
-    `description = "${shortDesc}"\n\n` +
-    `[prompt]\ntext = '''\n${geminiBody}\n'''\n`
-);
-
-// 6. OpenCode — markdown + YAML frontmatter, $ARGUMENTS works natively
-write(
-  '.opencode/commands/clone-website.md',
-  `---\ndescription: "${shortDesc}"\n---\n${HEADER}${body}`
-);
-
-// 7. Augment Code — markdown + YAML frontmatter
-write(
-  '.augment/commands/clone-website.md',
-  `---\ndescription: "${shortDesc}"\nargument-hint: "<url>"\n---\n${HEADER}${body}`
-);
-
-// 8. Continue — prompt file with invokable: true
-write(
-  '.continue/commands/clone-website.md',
-  `---\nname: clone-website\ndescription: "${shortDesc}"\ninvokable: true\n---\n${HEADER}${body}`
-);
-
-// 9. Amazon Q — JSON agent definition
-write(
-  '.amazonq/cli-agents/clone-website.json',
-  JSON.stringify(
-    {
-      name: 'clone-website',
-      description: shortDesc,
-      prompt: noArgs(body),
-      fileContext: ['AGENTS.md', 'docs/research/**'],
-    },
-    null,
-    2
-  ) + '\n'
-);
-
-console.log('\nDone! 9 platform command files generated from source skill.');
+const totalFiles = SKILLS.length * 9;
+console.log(`\nDone! ${totalFiles} platform files generated (${SKILLS.length} skills \u00d7 9 targets).`);