coderio 1.0.1 → 1.0.3-alpha.1

package/README.md

@@ -54,12 +54,12 @@ https://github.com/user-attachments/assets/bd0c3f18-e98a-4050-bf22-46b198fadac2
 
 CodeRio can be seamlessly integrated into Cursor as a Skill. Simply input a prompt like **"Create a React project and restore this design with high fidelity,"** along with your output directory, Figma URL([Design Link](https://www.figma.com/design/c0UBII8lURfxZIY8W6tSDR/Top-16-Websites-of-2024---Awwwards--Community-?node-id=30-8264&t=FB3Hohq2nsH7ZFts-4)), and Token. The Agent will guide you step-by-step through the page generation process. For Landing Pages, it achieves **high-fidelity restoration**, accurately reproducing images and styles. It also automatically encapsulates reusable components (such as cards) and strictly adheres to **frontend development best practices**.
 
-
 https://github.com/user-attachments/assets/43817e97-ffd2-40e3-9d33-78ee55b2ec2d
 
 ## 🚀 Quick Start
 
 ### Option 1: CLI (Recommended 👍🏻)
+
 Best for one-click generation.
 
 #### 1. Prerequisites
@@ -79,48 +79,104 @@ npm install -g coderio
 pnpm add -g coderio
 ```
 
-> **Note for pnpm v9+ users**: If you see a warning about "Ignored build scripts", run:
->
-> ```bash
-> pnpm approve-builds
-> ```
->
-> This allows native dependencies (better-sqlite3) to compile properly.
+> **Note for pnpm v9+ users**: If you see a warning about "Ignored build scripts", run: `pnpm approve-builds` to allow native dependencies (better-sqlite3) to compile properly.
 >
 > **Note**: Validation features (e.g., `d2c --mode full`) require optional dependencies `playwright` and `sharp`. They are not bundled with coderio by default to keep installation lightweight. Please install them globally beforehand for smoother execution:
 >
 > ```bash
 > npm install -g playwright sharp
 > npx playwright install chromium
-> ``` 
+> ```
 
 #### 3. Configuration
 
-> **Important**: This tool requires an LLM with **multimodal (vision) capabilities** to analyze design screenshots.
-> We highly recommend using **`gemini-3-pro-preview`** for the best balance of performance and cost.
+> **Important**: Requires a **multimodal (vision)** model (Recommended: `gemini-3-pro-preview`).
 
-Create `~/.coderio/config.yaml` (Windows: `%USERPROFILE%\.coderio\config.yaml`) with:
+Create config file at `~/.coderio/config.yaml` (Windows: `%USERPROFILE%\.coderio\config.yaml`):
 
 ```yaml
 model:
-  provider: openai          # anthropic | openai | google
-  model: gemini-3-pro-preview
-  baseUrl: https://api.anthropic.com
-  apiKey: your-api-key-here
+    provider: openai # anthropic | openai | google
+    model: gemini-3-pro-preview
+    baseUrl: https://api.anthropic.com
+    apiKey: your-api-key-here
 
 figma:
-  token: your-figma-token-here
+    token: your-figma-token-here
 
 debug:
-  enabled: false
+    enabled: false # set 'true', if you want to save model and request information
+```
+
+#### 4. Usage
+
+```bash
+# Convert Figma design to code (default mode: code only)
+coderio d2c -s 'https://www.figma.com/design/your-file-id/...'
+
+# Full mode: Generate code + visual validation + auto-refinement
+coderio d2c -s 'https://www.figma.com/design/your-file-id/...' -m full
+```
+
+#### 5. Run Your Project
+
+```bash
+# Navigate to generated project
+cd coderio/<design-name_node-id>/my-app
+
+# Install dependencies
+pnpm install
+
+# Start dev server
+pnpm dev
+
+# 🎉 Open http://localhost:5173
+```
+
+#### 6. View Validation Report
+
+report path: coderio/<design-name_node-id>/process/validation/index.html
+
+#### 📖 All Commands
+
+| Command           | Alias | Description                                         |
+| ----------------- | ----- | --------------------------------------------------- |
+| `design2code`     | `d2c` | Full pipeline: Figma → Protocol → Code → Validation |
+| `design2protocol` | `d2p` | Extract design protocol only                        |
+| `protocol2code`   | `p2c` | Generate code from existing protocol                |
+| `validate`        | `val` | Run validation on generated code                    |
+| `images`          | -     | Download and process Figma assets                   |
+
+### Option 2: Docker
+
+Best for portable environments without Node.js installation.
+
+#### 1. Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/)
+- [Figma Personal Access Token](https://www.figma.com/developers/api#access-tokens)
+- LLM API Key ([Anthropic](https://console.anthropic.com/) | [OpenAI](https://platform.openai.com/) | [Google](https://aistudio.google.com/))
+
+> **For Windows Users:** The commands below use bash syntax (heredoc, `${PWD}`, `--network=host`, etc.) which are not compatible with CMD or PowerShell. Please use **WSL2** to run them:
+>
+> 1. Install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and a Linux distribution (e.g. Ubuntu)
+> 2. Install [Docker Desktop](https://docs.docker.com/desktop/install/windows-install/) and enable **WSL2 integration** in Settings → Resources → WSL Integration
+> 3. Open a WSL2 terminal (run `wsl` in CMD/PowerShell, or open Ubuntu from the Start menu)
+> 4. Run all the following commands inside the WSL2 terminal
+
+#### 2. Installation
+
+```bash
+docker pull crpi-p4hwwrt00km3axuk.cn-shanghai.personal.cr.aliyuncs.com/coderio/coderio
 ```
 
-<details>
-<summary><strong>macOS / Linux One-click Command</strong></summary>
+#### 3. Configuration
+
+Create a working directory and `config.yaml`:
 
 ```bash
-mkdir -p ~/.coderio
-cat > ~/.coderio/config.yaml << 'EOF'
+mkdir -p ./coderio-app && cd ./coderio-app
+cat > config.yaml << 'EOF'
 model:
   provider: openai          # anthropic | openai | google
   model: gemini-3-pro-preview
@@ -134,10 +190,19 @@ debug:
   enabled: false
 EOF
 ```
-</details>
 
 #### 4. Usage
 
+```bash
+docker run -ti --rm \
+  --network=host \
+  -v ${PWD}:/app \
+  -v ./config.yaml:/root/.coderio/config.yaml \
+  crpi-p4hwwrt00km3axuk.cn-shanghai.personal.cr.aliyuncs.com/coderio/coderio bash
+```
+
+Once inside the container, use CodeRio commands:
+
 ```bash
 # Convert Figma design to code (default mode: code only)
 coderio d2c -s 'https://www.figma.com/design/your-file-id/...'
@@ -163,37 +228,29 @@ pnpm dev
 
 #### 6. View Validation Report
 
-```bash
-# Open validation report in browser
-open coderio/<design-name_node-id>/process/validation/index.html
-```
+Generated files are mounted to your host machine. Open the validation report in your browser:
 
-#### 📖 All Commands
+```
+./coderio/<design-name_node-id>/process/validation/index.html
+```
 
-| Command           | Alias | Description                                         |
-| ----------------- | ----- | --------------------------------------------------- |
-| `design2code`     | `d2c` | Full pipeline: Figma → Protocol → Code → Validation |
-| `design2protocol` | `d2p` | Extract design protocol only                        |
-| `protocol2code`   | `p2c` | Generate code from existing protocol                |
-| `validate`        | `val` | Run validation on generated code                    |
-| `images`          | -     | Download and process Figma assets                   |
+### Option 3: Skill (Portable Embedded Workflow)
 
-### Option 2: Skill (Portable Embedded Workflow)
 Best for control and precision using AI Agents.
 
 **Prerequisites**:
 Copy the Skill file to your Cursor configuration directory:
-```bash
-mkdir -p ~/.cursor/skills/design-to-code
-cp docs/skills/SKILL.md ~/.cursor/skills/design-to-code/SKILL.md
-```
+
+Copy `skills\design-to-code` folder to `~\.cursor\skills` (Windows: `%USERPROFILE%\.cursor\skills`)
 
 **Using in Cursor**:
-1. Open Cursor Chat (`Cmd` + `L`).
+
+1. Open Cursor Chat.
 2. Type: **"Use design-to-code skill to convert this design: [Your Figma URL]"**
 3. The Agent will guide you step-by-step through protocol extraction and code generation.
 
 **Using in Claude Code**:
+
 1. Start Claude Code.
 2. Type: **"Read docs/skills/SKILL.md and perform design conversion: [Your Figma URL]"**
 

package/dist/cli.js

@@ -475,7 +475,7 @@ var AGENT_CONTEXT_WINDOW_TOKENS = 128e3;
 
 // src/cli/init.ts
 function registerCommands(program) {
-  const version = false ? "0.0.1" : "1.0.1";
+  const version = false ? "0.0.1" : "1.0.3-alpha.1";
   program.name(CLI_NAME).description(`${CLI_NAME} - Convert Figma designs to code`).version(version, "-v, -V, --version", "Output the version number").showHelpAfterError();
 }
 
@@ -594,16 +594,37 @@ var Workspace = class {
   }
   /**
    * Delete all files and directories inside the workspace
+   * @param workspace - The workspace structure
+   * @param preserve - Optional list of relative paths (from workspace root) to preserve from deletion
    */
-  deleteWorkspace(workspace) {
+  deleteWorkspace(workspace, preserve = []) {
     try {
-      if (fs2.existsSync(workspace.root)) {
-        const entries = fs2.readdirSync(workspace.root);
-        for (const entry of entries) {
-          const fullPath = path2.join(workspace.root, entry);
-          fs2.rmSync(fullPath, { recursive: true, force: true });
+      if (!fs2.existsSync(workspace.root)) return;
+      const preserveFiles = new Set(preserve.map((p) => path2.normalize(p)));
+      const preserveDirs = /* @__PURE__ */ new Set();
+      for (const p of preserveFiles) {
+        let dir = path2.dirname(p);
+        while (dir !== ".") {
+          preserveDirs.add(dir);
+          dir = path2.dirname(dir);
         }
       }
+      const deleteRecursive = (dirPath, relativeTo = "") => {
+        const entries = fs2.readdirSync(dirPath);
+        for (const entry of entries) {
+          const fullPath = path2.join(dirPath, entry);
+          const relPath = relativeTo ? path2.join(relativeTo, entry) : entry;
+          if (preserveFiles.has(relPath)) {
+            continue;
+          }
+          if (preserveDirs.has(relPath)) {
+            deleteRecursive(fullPath, relPath);
+          } else {
+            fs2.rmSync(fullPath, { recursive: true, force: true });
+          }
+        }
+      };
+      deleteRecursive(workspace.root);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       logger.printWarnLog(`Failed to delete workspace: ${errorMessage}`);
@@ -653,7 +674,7 @@ function saveDebugLog(requestInfo, responseInfo) {
     "------------response------------",
     JSON.stringify(responseInfo, null, 2)
   ].join("\n");
-  writeFile(workspaceManager.path?.debug ?? "", `fetch_${(/* @__PURE__ */ new Date()).toISOString()}.md`, debugContent);
+  writeFile(workspaceManager.path?.debug ?? "", `fetch_${(/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-")}.md`, debugContent);
 }
 async function get(url, config) {
   const response = await axios.get(url, config);
@@ -1418,10 +1439,13 @@ var FigmaTool = class {
     }
     const document2 = await fetchFigmaNode(fileId, nodeId, token);
     if (!document2 || !document2?.children?.length) {
-      return void 0;
+      throw new Error("Failed to fetch Figma document");
     }
     const images = await fetchFigmaImages(fileId, nodeId, token);
     const thumbnail = images?.[nodeId] || "";
+    if (!thumbnail) {
+      throw new Error("Failed to fetch Figma document thumbnail");
+    }
     document2.thumbnailUrl = thumbnail;
     const cleanedDocument = cleanFigma(document2);
     return cleanedDocument;
@@ -1553,7 +1577,7 @@ async function callModel(options) {
         "------------response------------",
         JSON.stringify(message.text, null, 2)
       ].join("\n");
-      writeFile(workspaceManager.path?.debug ?? "", `model_${(/* @__PURE__ */ new Date()).toISOString()}.md`, debugContent);
+      writeFile(workspaceManager.path?.debug ?? "", `model_${(/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-")}.md`, debugContent);
     }
     return message.text;
   } catch (error) {
@@ -2012,7 +2036,7 @@ var parseFigmaUrl = (url) => {
   if (!fileId || !nodeId) {
     throw new Error("Invalid Figma URL");
   }
-  return { fileId, name, nodeId, projectName: `${name}_${nodeId}` };
+  return { fileId, name, nodeId, projectName: `${name}_${nodeId.replace(/:/g, "_")}` };
 };
 
 // src/cli/d2p.ts
@@ -5706,21 +5730,45 @@ var FILE_NAMING_CONVENTION = `
       - NEVER use PascalCase or other names for filenames (e.g., DO NOT use \`MainFrame.tsx\` or \`Button.tsx\`).`;
 var OUTPUT_FORMAT = `
   <output_format>
-    If only one file (TSX) is needed:
+    **CRITICAL - Output Format Requirements:**
+    
+    **CASE 1: Single File (TSX only)**
+    - Return code wrapped in triple backticks with language identifier
+    - NO file name header needed
+    - Example:
     \`\`\`tsx
-    // code...
+    export default function Component() {
+      return <div>...</div>;
+    }
     \`\`\`
 
-    If multiple files are needed (e.g., TSX + Styles):
+    **CASE 2: Multiple Files (TSX + Styles)**
+    - **REQUIRED**: Each file MUST start with EXACTLY \`## \` (two hash symbols + one space) followed by filename
+    - **REQUIRED**: Filename must be complete with extension (e.g., \`index.tsx\`, \`index.module.css\`)
+    - **FORBIDDEN**: Do NOT use single \`#\`, do NOT omit filename, do NOT use other markers
+    - Follow this exact structure:
+    
     ## index.tsx
     \`\`\`tsx
-    // code...
+    export default function Component() {
+      return <div>...</div>;
+    }
     \`\`\`
 
     ## index.module.[css|less|scss]
     \`\`\`[css|less|scss]
-    // styles...
+    .container {
+      /* styles */
+    }
     \`\`\`
+    
+    **VALIDATION CHECKLIST (for multiple files):**
+    \u2713 Each file section starts with \`## \` (two hashes + space)
+    \u2713 Filename includes full extension
+    \u2713 Code wrapped in triple backticks with language
+    \u2717 DO NOT use \`# filename\` (single hash)
+    \u2717 DO NOT omit file headers
+    \u2717 DO NOT use other separators
   </output_format>`;
 function generateChildrenPropsInstructions(modes) {
   const instructions = [];
@@ -6333,6 +6381,14 @@ async function checkpointExists(checkpointer, threadId) {
     return false;
   }
 }
+async function clearCheckpoint(checkpointer, threadId) {
+  try {
+    await checkpointer.deleteThread(threadId);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.printWarnLog(`Failed to clear checkpoint: ${errorMessage}`);
+  }
+}
 async function promptCheckpointChoice(checkpointer, threadId) {
   const hasCheckpoint = await checkpointExists(checkpointer, threadId);
   if (!hasCheckpoint) {
@@ -6341,6 +6397,9 @@ async function promptCheckpointChoice(checkpointer, threadId) {
   const choice = await promptUserChoice();
   return choice === "resume";
 }
+async function clearThreadCheckpoint(checkpointer, threadId) {
+  await clearCheckpoint(checkpointer, threadId);
+}
 function initializeSqliteSaver(dbPath) {
   const dbDir = path14.dirname(dbPath);
   if (!fs11.existsSync(dbDir)) {
@@ -6356,13 +6415,13 @@ async function design2code(url, mode) {
   const urlInfo = parseFigmaUrl(url);
   const threadId = urlInfo.projectName;
   const workspace = workspaceManager.initWorkspace(threadId);
-  let checkpointer = initializeSqliteSaver(workspace.db);
+  const checkpointer = initializeSqliteSaver(workspace.db);
   const resume = await promptCheckpointChoice(checkpointer, threadId);
   logger.printInfoLog(`Starting design-to-code process for: ${urlInfo.projectName}`);
   if (resume !== true) {
-    workspaceManager.deleteWorkspace(workspace);
+    workspaceManager.deleteWorkspace(workspace, ["checkpoint/coderio-cli.db"]);
     logger.printInfoLog("Starting fresh...");
-    checkpointer = initializeSqliteSaver(workspace.db);
+    await clearThreadCheckpoint(checkpointer, threadId);
   } else {
     logger.printInfoLog("Resuming from cache...");
   }