@getcoherent/cli 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @coherent/cli
+
+CLI for **Coherent Design Method** — generate and maintain Next.js apps with a single design-system config.
+
+## Install
+
+```bash
+npm install -g @coherent/cli
+```
+
+## Quick Start
+
+```bash
+# In an empty directory (or new repo)
+coherent init
+npm install
+coherent preview
+```
+
+- **App:** http://localhost:3000  
+- **Design System:** http://localhost:3000/design-system  
+- **Docs:** http://localhost:3000/design-system/docs  
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `coherent init` | Create project: config, app, design-system viewer, docs. Non-interactive (optional provider flag). |
+| `coherent chat "<request>"` | Parse NL, update config, regenerate pages/components/nav (e.g. add page, change tokens). |
+| `coherent preview` | Start Next.js dev server. |
+| `coherent export` | Production build; optional Vercel/Netlify config. |
+| `coherent status` | Print config summary (pages, components). |
+| `coherent components` | List registered components. |
+
+## Two Workflows
+
+After `coherent init` you can:
+
+1. **Work in Cursor/IDE** — Edit `design-system.config.ts`, `app/`, `components/`; hot reload. Best for fine-grained control.
+2. **Use `coherent chat`** — e.g. `coherent chat "add pricing page"` to scaffold pages/components and sync config/nav. Best for fast generation.
+
+**Tip:** Use chat for structure, then Cursor for details. Commit before each `coherent chat` and run `git diff` after.
+
+## Examples (chat)
+
+```bash
+coherent chat "add dashboard page with stats cards"
+coherent chat "add Button, Card, Input from shadcn"
+coherent chat "add contact page with form"
+coherent chat "change primary color to #6366f1"
+```
+
+## API Key
+
+For `coherent init` (discovery) and `coherent chat` you need an AI provider key:
+
+- **Anthropic (default):** `ANTHROPIC_API_KEY`
+- **OpenAI:** `OPENAI_API_KEY`
+
+Put in `.env` in the project root or export in the shell. In Cursor, keys are often auto-detected.
+
+## Docs
+
+- Root repo: [README](../../README.md) and [QUICK_REFERENCE.md](../../QUICK_REFERENCE.md)
+- Project context and workflows: [CONTEXT.md](../../CONTEXT.md) §7
+
+## License
+
+MIT

package/bin/coherent

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/index.js')

package/dist/backup-DRQUCHM5.js

@@ -0,0 +1,11 @@
+import {
+  createBackup,
+  listBackups,
+  restoreBackup
+} from "./chunk-N2S7FM57.js";
+import "./chunk-3RG5ZIWI.js";
+export {
+  createBackup,
+  listBackups,
+  restoreBackup
+};

package/dist/chunk-3RG5ZIWI.js

@@ -0,0 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export {
+  __require
+};

package/dist/chunk-N2S7FM57.js

@@ -0,0 +1,101 @@
+// src/utils/backup.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync, copyFileSync } from "fs";
+import { join, dirname } from "path";
+var BACKUP_DIR = ".coherent/backups";
+function findFiles(dir, suffix) {
+  if (!existsSync(dir)) return [];
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findFiles(full, suffix));
+    } else if (entry.name.endsWith(suffix)) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+var MAX_BACKUPS = 10;
+function getBackupRoot(projectRoot) {
+  return join(projectRoot, BACKUP_DIR);
+}
+function createBackup(projectRoot, message) {
+  const backupRoot = getBackupRoot(projectRoot);
+  const id = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const backupDir = join(backupRoot, id);
+  mkdirSync(backupDir, { recursive: true });
+  const filesToBackup = [
+    "design-system.config.ts",
+    "app/layout.tsx",
+    ...findFiles(join(projectRoot, "app"), "page.tsx").map((f) => f.slice(projectRoot.length + 1)),
+    ...findFiles(join(projectRoot, "components", "shared"), ".tsx").map((f) => f.slice(projectRoot.length + 1))
+  ];
+  const backedUp = [];
+  for (const relPath of filesToBackup) {
+    const src = join(projectRoot, relPath);
+    if (!existsSync(src)) continue;
+    const dest = join(backupDir, relPath);
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(src, dest);
+    backedUp.push(relPath);
+  }
+  const manifest = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    message,
+    files: backedUp
+  };
+  writeFileSync(join(backupDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  pruneOldBackups(backupRoot);
+  return id;
+}
+function restoreBackup(projectRoot, backupId) {
+  const backupRoot = getBackupRoot(projectRoot);
+  if (!existsSync(backupRoot)) return null;
+  const id = backupId || getLatestBackupId(backupRoot);
+  if (!id) return null;
+  const backupDir = join(backupRoot, id);
+  const manifestPath = join(backupDir, "manifest.json");
+  if (!existsSync(manifestPath)) return null;
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  for (const relPath of manifest.files) {
+    const src = join(backupDir, relPath);
+    const dest = join(projectRoot, relPath);
+    if (!existsSync(src)) continue;
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(src, dest);
+  }
+  return manifest;
+}
+function listBackups(projectRoot) {
+  const backupRoot = getBackupRoot(projectRoot);
+  if (!existsSync(backupRoot)) return [];
+  const dirs = readdirSync(backupRoot, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort().reverse();
+  const results = [];
+  for (const id of dirs) {
+    const manifestPath = join(backupRoot, id, "manifest.json");
+    if (!existsSync(manifestPath)) continue;
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+      results.push({ id, manifest });
+    } catch {
+    }
+  }
+  return results;
+}
+function getLatestBackupId(backupRoot) {
+  const dirs = readdirSync(backupRoot, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+  return dirs[dirs.length - 1];
+}
+function pruneOldBackups(backupRoot) {
+  const dirs = readdirSync(backupRoot, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+  while (dirs.length > MAX_BACKUPS) {
+    const oldest = dirs.shift();
+    rmSync(join(backupRoot, oldest), { recursive: true, force: true });
+  }
+}
+
+export {
+  createBackup,
+  restoreBackup,
+  listBackups
+};

package/dist/claude-QTRMGJ56.js

@@ -0,0 +1,363 @@
+import "./chunk-3RG5ZIWI.js";
+
+// src/utils/claude.ts
+import Anthropic from "@anthropic-ai/sdk";
+import { validateConfig } from "@getcoherent/core";
+var ClaudeClient = class _ClaudeClient {
+  client;
+  defaultModel;
+  constructor(apiKey, model) {
+    const key = apiKey || process.env.ANTHROPIC_API_KEY;
+    if (!key) {
+      throw new Error(
+        "ANTHROPIC_API_KEY not found in environment.\nPlease set it in your .env file or export it:\n  export ANTHROPIC_API_KEY=your_key_here"
+      );
+    }
+    this.client = new Anthropic({ apiKey: key });
+    this.defaultModel = model || process.env.CLAUDE_MODEL || "claude-sonnet-4-20250514";
+  }
+  /**
+   * Factory method for creating ClaudeClient
+   */
+  static create(apiKey, model) {
+    return new _ClaudeClient(apiKey, model);
+  }
+  /**
+   * Generate design system config from discovery results
+   */
+  async generateConfig(discovery) {
+    try {
+      const prompt = this.buildConfigPrompt(discovery);
+      const response = await this.client.messages.create({
+        model: this.defaultModel,
+        max_tokens: 4096,
+        messages: [
+          {
+            role: "user",
+            content: prompt
+          }
+        ],
+        system: this.getSystemPrompt()
+      });
+      const content = response.content[0];
+      if (content.type !== "text") {
+        throw new Error("Unexpected response type from Claude API");
+      }
+      const jsonText = this.extractJSON(content.text);
+      const config = JSON.parse(jsonText);
+      return validateConfig(config);
+    } catch (error) {
+      if (error instanceof Anthropic.APIError) {
+        if (error.status === 404 && error.error?.type === "not_found_error") {
+          throw new Error(
+            `\u274C Model not found: ${this.defaultModel}
+
+The specified Claude model is not available.
+Try setting a different model:
+  export CLAUDE_MODEL=claude-sonnet-4-20250514
+Or use the default model by removing CLAUDE_MODEL from your environment.`
+          );
+        }
+        throw new Error(
+          `Claude API error (${error.status}): ${error.message}
+Please check your API key and try again.`
+        );
+      }
+      if (error instanceof Error) {
+        throw new Error(`Failed to generate config: ${error.message}`);
+      }
+      throw new Error("Unknown error occurred while generating config");
+    }
+  }
+  /**
+   * Build prompt for config generation
+   */
+  buildConfigPrompt(discovery) {
+    const featuresList = Object.entries(discovery.features).filter(([_, enabled]) => enabled).map(([name]) => name).join(", ") || "none";
+    return `Generate a complete DesignSystemConfig JSON for the following project:
+
+Project Type: ${discovery.projectType}
+App Type: ${discovery.appType}
+Audience: ${discovery.audience}
+Visual Style: ${discovery.visualStyle}
+Primary Color: ${discovery.primaryColor}
+Dark Mode: ${discovery.darkMode ? "Yes" : "No"}
+Features: ${featuresList}
+${discovery.additionalRequirements ? `Additional Requirements: ${discovery.additionalRequirements}` : ""}
+
+Requirements:
+- Use 8pt grid system for spacing (0.25rem, 0.5rem, 1rem, 1.5rem, 2rem, 3rem, 4rem)
+- Ensure WCAG AA contrast (4.5:1 for text) for all colors
+- Generate dark mode colors based on primary color ${discovery.primaryColor}
+- Include commonly needed components for ${discovery.projectType} projects
+- Set appType to "${discovery.appType}" in settings
+- Enable stateManagement if SPA or authentication is needed
+- Use semantic color naming (primary, secondary, success, warning, error, info)
+- Set createdAt and updatedAt to current ISO timestamp
+
+Output ONLY valid JSON matching DesignSystemConfig schema. Do not include markdown code blocks or explanations.`;
+  }
+  /**
+   * Get system prompt for Claude
+   */
+  getSystemPrompt() {
+    return `You are a design system architect expert. Your task is to generate complete, valid DesignSystemConfig JSON objects.
+
+Key principles:
+- Always generate valid JSON that matches the DesignSystemConfig schema
+- Use semantic color tokens (primary, secondary, etc.) not hardcoded values
+- Ensure all required fields are present
+- Generate realistic, production-ready configurations
+- Follow 8pt grid system for spacing
+- Ensure WCAG AA contrast compliance
+- Include appropriate components for the project type
+
+Return ONLY the JSON object, no markdown, no code blocks, no explanations.`;
+  }
+  /**
+   * Extract JSON from Claude's response (handles markdown code blocks)
+   */
+  extractJSON(text) {
+    let jsonText = text.trim();
+    if (jsonText.startsWith("```")) {
+      const lines = jsonText.split("\n");
+      lines.shift();
+      if (lines[lines.length - 1].trim() === "```") {
+        lines.pop();
+      }
+      jsonText = lines.join("\n");
+    }
+    return jsonText.trim();
+  }
+  /**
+   * Test API connection
+   */
+  async testConnection() {
+    try {
+      await this.client.messages.create({
+        model: this.defaultModel,
+        max_tokens: 10,
+        messages: [
+          {
+            role: "user",
+            content: 'Say "OK"'
+          }
+        ]
+      });
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Parse modification request from natural language
+   */
+  async parseModification(prompt) {
+    try {
+      const response = await this.client.messages.create({
+        model: this.defaultModel,
+        max_tokens: 16384,
+        messages: [
+          {
+            role: "user",
+            content: prompt
+          }
+        ],
+        system: `You are a design system modification parser. 
+Parse natural language requests into structured ModificationRequest JSON.
+Always check component registry before creating new components.
+Return valid JSON only, no markdown. Use: { "requests": [ ... ], "uxRecommendations": "optional markdown" }
+CRITICAL: All string values in JSON must be on one line. Escape double quotes inside strings with \\". Do not include unescaped newlines or quotes in string values.`
+      });
+      if (response.stop_reason === "max_tokens") {
+        const err = new Error("AI response truncated (max_tokens reached)");
+        err.code = "RESPONSE_TRUNCATED";
+        throw err;
+      }
+      const content = response.content[0];
+      if (content.type !== "text") {
+        throw new Error("Unexpected response type from Claude API");
+      }
+      const jsonText = this.extractJSON(content.text);
+      const parsed = JSON.parse(jsonText);
+      if (Array.isArray(parsed)) {
+        return { requests: parsed };
+      }
+      const requests = parsed?.requests;
+      if (!Array.isArray(requests)) {
+        throw new Error('Expected "requests" array in response');
+      }
+      return {
+        requests,
+        uxRecommendations: typeof parsed.uxRecommendations === "string" && parsed.uxRecommendations.trim() ? parsed.uxRecommendations.trim() : void 0
+      };
+    } catch (error) {
+      if (error?.code === "RESPONSE_TRUNCATED") {
+        throw error;
+      }
+      if (error instanceof Anthropic.APIError) {
+        if (error.status === 404 && error.error?.type === "not_found_error") {
+          throw new Error(
+            `\u274C Model not found: ${this.defaultModel}
+
+The specified Claude model is not available.
+Try setting a different model:
+  export CLAUDE_MODEL=claude-sonnet-4-20250514
+Or use the default model by removing CLAUDE_MODEL from your environment.`
+          );
+        }
+        throw new Error(
+          `Claude API error (${error.status}): ${error.message}
+Please check your API key and try again.`
+        );
+      }
+      if (error instanceof Error) {
+        throw new Error(`Failed to parse modification: ${error.message}`);
+      }
+      throw new Error("Unknown error occurred while parsing modification");
+    }
+  }
+  /**
+   * Edit shared component code by instruction (Epic 2).
+   */
+  async editSharedComponentCode(currentCode, instruction, componentName) {
+    const response = await this.client.messages.create({
+      model: this.defaultModel,
+      max_tokens: 8192,
+      messages: [
+        {
+          role: "user",
+          content: `You are a React/Next.js component editor. Update the following component according to the user's instruction.
+
+Component name: ${componentName}
+
+Current code:
+\`\`\`tsx
+${currentCode}
+\`\`\`
+
+Instruction: ${instruction}
+
+Rules: Preserve "use client" if present. Use Tailwind and shadcn/ui patterns. Return ONLY the complete updated component code, no markdown fence, no explanation.`
+        }
+      ],
+      system: "Return only the raw TSX code, no markdown, no comments before or after."
+    });
+    const content = response.content[0];
+    if (content.type !== "text") throw new Error("Unexpected response type");
+    return content.text.trim().replace(/^```(?:tsx?|jsx?)\s*/i, "").replace(/\s*```$/i, "");
+  }
+  /**
+   * Edit existing page code by instruction. Returns full modified page code.
+   */
+  async editPageCode(currentCode, instruction, pageName, designConstraints) {
+    const constraintBlock = designConstraints ? `
+Design constraints (follow unless user explicitly overrides):
+${designConstraints}
+` : "";
+    const response = await this.client.messages.create({
+      model: this.defaultModel,
+      max_tokens: 16384,
+      messages: [
+        {
+          role: "user",
+          content: `You are a React/Next.js page editor. Modify the existing page according to the user's instruction.
+
+Page name: ${pageName}
+${constraintBlock}
+Current code:
+\`\`\`tsx
+${currentCode}
+\`\`\`
+
+Instruction: ${instruction}
+
+CRITICAL RULES:
+- Return the COMPLETE modified page code. Do NOT return partial code or snippets.
+- Preserve "use client" if present. Do NOT add export const metadata if "use client" is present.
+- Keep ALL existing content, structure, and functionality UNLESS the instruction says to change it.
+- If the user specifies exact CSS classes or colors \u2014 use them exactly, even if they conflict with design constraints.
+- Use Tailwind CSS and shadcn/ui patterns.
+- Return ONLY the raw TSX code, no markdown fence, no explanation.`
+        }
+      ],
+      system: "Return only the raw TSX code, no markdown, no comments before or after."
+    });
+    const content = response.content[0];
+    if (content.type !== "text") throw new Error("Unexpected response type");
+    return content.text.trim().replace(/^```(?:tsx?|jsx?)\s*/i, "").replace(/\s*```$/i, "");
+  }
+  /**
+   * Story 2.11: Replace inline block on page with shared component import and usage.
+   */
+  async replaceInlineWithShared(pageCode, sharedComponentCode, sharedComponentName, blockHint) {
+    const hint = blockHint ? ` Identify the block that corresponds to: "${blockHint}".` : "";
+    const response = await this.client.messages.create({
+      model: this.defaultModel,
+      max_tokens: 8192,
+      messages: [
+        {
+          role: "user",
+          content: `You are a React/Next.js page editor. Replace an INLINE block on the page with the shared component "${sharedComponentName}".
+
+PAGE CODE (find and replace one block):
+\`\`\`tsx
+${pageCode}
+\`\`\`
+
+SHARED COMPONENT (use this instead of the inline block):
+\`\`\`tsx
+${sharedComponentCode}
+\`\`\`
+
+Tasks:
+1.${hint} Find the inline block that matches or is similar to the shared component (e.g. same structure: hero, CTA, card section).
+2. Add an import at the top: import { ${sharedComponentName} } from '@/components/shared/${sharedComponentName.replace(/([A-Z])/g, (m) => "-" + m.toLowerCase()).replace(/^-/, "")}'
+   (Use kebab-case file name: HeroSection \u2192 hero-section, PricingCard \u2192 pricing-card.)
+3. Replace the inline block with <${sharedComponentName} /> (or with props if the shared component accepts them and the page needs different values).
+4. Return the COMPLETE updated page code. Preserve "use client" if present. No markdown fence, no explanation.`
+        }
+      ],
+      system: "Return only the raw TSX page code, no markdown, no comments before or after."
+    });
+    const content = response.content[0];
+    if (content.type !== "text") throw new Error("Unexpected response type");
+    return content.text.trim().replace(/^```(?:tsx?|jsx?)\s*/i, "").replace(/\s*```$/i, "");
+  }
+  /**
+   * Story 2.11 B2: Extract a block from page code as a standalone React component.
+   */
+  async extractBlockAsComponent(pageCode, blockHint, componentName) {
+    const response = await this.client.messages.create({
+      model: this.defaultModel,
+      max_tokens: 4096,
+      messages: [
+        {
+          role: "user",
+          content: `You are a React/Next.js refactoring assistant. Extract ONE section/block from the page code into a standalone React component.
+
+PAGE CODE:
+\`\`\`tsx
+${pageCode}
+\`\`\`
+
+Block to extract: "${blockHint}"
+
+Requirements:
+1. Find the block that matches "${blockHint}" (e.g. CTA section, hero, feature grid).
+2. Create a new component named ${componentName} that contains ONLY that block's JSX and logic.
+3. The component must be self-contained: export function ${componentName}() { ... } with "use client" if it uses hooks.
+4. Use the same imports (Button, Card, etc.) inside the component - include any needed import statements at the top.
+5. Return ONLY the complete component file content (no markdown fence, no explanation).`
+        }
+      ],
+      system: "Return only the raw TSX code for the extracted component, no markdown, no explanation."
+    });
+    const content = response.content[0];
+    if (content.type !== "text") throw new Error("Unexpected response type");
+    return content.text.trim().replace(/^```(?:tsx?|jsx?)\s*/i, "").replace(/\s*```$/i, "");
+  }
+};
+export {
+  ClaudeClient
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }