refira-cli 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,153 @@
+# Refira CLI
+
+A command-line tool and deterministic AI Agent Harness for designing and previewing standalone HTML5 and Tailwind CSS prototypes in Refira workspaces.
+
+Refira CLI enables autonomous coding agents (such as Google Antigravity, Claude Code, Cursor Agent, and Aider) and developers to interact directly with the Refira canvas, fetch design tokens, scaffold clean templates, and validate markup before publishing.
+
+---
+
+## Overview
+
+Refira is an AI design workspace that maintains persistent design context and renders prototypes inside sandboxed iframes. Refira CLI serves two purposes:
+1. **Developer & Agent CLI:** Manage sessions, pull design tokens, and push live page markup.
+2. **Deterministic Agent Harness:** Automatically lint markup with `htmlparser2` to enforce design consistency and prevent broken prototype states before code reaches the backend.
+
+---
+
+## Installation
+
+Run directly using NPX without installation:
+```bash
+npx refira-cli --help
+```
+
+Or install globally on your system:
+```bash
+npm install --global refira-cli
+```
+
+Verify installation:
+```bash
+refira --version
+```
+
+---
+
+## Command Reference
+
+### 1. Authentication
+
+#### `refira auth login`
+Authenticates against a Refira instance and stores credentials locally in `.refirarc` (or globally in `~/.refirarc`).
+
+```bash
+refira auth login --api-url https://api.refira.dev --api-key rfr_your_api_key
+```
+
+Options:
+- `--api-url <url>`: Refira backend API endpoint (default: `http://localhost:3001`).
+- `--api-key <key>`: Project-scoped API key with `rfr_` prefix.
+- `-g, --global`: Save credentials globally in user home directory.
+
+#### `refira auth status`
+Verifies the current session and displays project and user identifiers.
+
+```bash
+refira auth status
+```
+
+---
+
+### 2. Workspace Initialization
+
+#### `refira init`
+Connects to the project API, downloads design tokens, and deterministically generates operational guidelines for AI coding agents:
+- `AGENTS.md`: Operational instructions for Antigravity, Codex, Gemini CLI, and other agents.
+- `.cursorrules`: Rule definitions for Cursor.
+- `.agents/skills/refira/SKILL.md`: Design craftsmanship skill focusing on high-aesthetic UI execution.
+
+```bash
+refira init --project-id <project-uuid>
+```
+
+---
+
+### 3. Design Context & Tokens
+
+#### `refira context`
+Displays project design tokens (primary typography font, palette colors) and the existing page roster.
+
+```bash
+refira context
+```
+
+---
+
+### 4. Page Scaffolding
+
+#### `refira scaffold`
+Generates a standalone HTML5 starter template pre-configured with:
+- Google Fonts specified in project design tokens.
+- Tailwind CSS CDN and theme extensions.
+- Lucide Icons script.
+- Body content slot marking where agent layout markup should be placed.
+
+```bash
+refira scaffold --page checkout
+```
+
+Options:
+- `--page <slug>`: Required page slug (e.g., `checkout`, `dashboard`, `landing`).
+- `--output <path>`: Custom destination file path (default: `<slug>.html`).
+
+---
+
+### 5. Live Preview & Harness Validation
+
+#### `refira preview`
+Inspects an HTML markup file using the Refira Agent Harness. If violations are detected, execution halts with Exit Code 1 and actionable remediation instructions. If valid, the markup is streamed directly to the Refira Canvas.
+
+```bash
+refira preview checkout.html --page checkout
+```
+
+Arguments:
+- `<file>`: Path to the HTML file to inspect and preview.
+
+Options:
+- `--page <slug>`: Target page slug.
+
+---
+
+### 6. Agent Skill Installation
+
+#### `refira skill install`
+Installs the Refira design craftsmanship guide (`SKILL.md`) for AI agents.
+
+```bash
+# Local project installation (.agents/skills/refira/SKILL.md)
+refira skill install
+
+# Global installation (~/.agents/skills/refira/SKILL.md)
+refira skill install --global
+```
+
+---
+
+## Agent Harness Invariants
+
+All markup submitted via `refira preview` must conform to these strict architectural rules:
+
+| Rule | Status | Description |
+|---|---|---|
+| **Standalone HTML5 + Tailwind** | Required | Markup must be valid native HTML5 with Tailwind CSS utility classes. |
+| **No UI Frameworks** | Prohibited | React, Vue, Svelte, Angular, Solid, and JSX syntax (`className=`, `onClick={...}`, `<Component />`) are rejected. |
+| **No External / Inter-Page Navigation** | Prohibited | Prototypes run inside sandboxed iframes. Anchors (`<a href="...">`) pointing to external URLs or relative pages (e.g. `/checkout`) are rejected. Only in-page anchors (`href="#section"`) or placeholders (`href="#"`) are allowed. |
+| **No Raw Emojis in Markup** | Prohibited | Raw unicode emojis (e.g. rocket, fire, sparkles) in HTML text nodes or attributes are rejected to maintain professional aesthetic quality. Use Lucide Icons or Heroicons SVG elements instead. |
+| **Graphics & Animation Libraries** | Permitted | Standalone CDN scripts such as Three.js, GSAP, Spline Viewer, and Lucide Icons are explicitly allowed in document `<head>` or `<script>`. |
+
+---
+
+## License
+
+MIT License. Distributed as part of the Refira workspace ecosystem.

package/dist/index.js

@@ -1892,6 +1892,23 @@ var {
 } = exports_commander;
 
 // src/api-client.ts
+function extractFontFamily(typography, fallback = "Inter") {
+  if (!typography)
+    return fallback;
+  if (typeof typography.font_family === "string" && typography.font_family.trim().length > 0) {
+    return typography.font_family;
+  }
+  if (typography.primary && typeof typography.primary.font_family === "string" && typography.primary.font_family.trim().length > 0) {
+    return typography.primary.font_family;
+  }
+  for (const item of Object.values(typography)) {
+    if (item && typeof item === "object" && typeof item.font_family === "string") {
+      return item.font_family;
+    }
+  }
+  return fallback;
+}
+
 class CliApiClient {
   apiUrl;
   apiKey;
@@ -2047,18 +2064,22 @@ async function contextCommand(opts) {
   const client = new CliApiClient(config.apiUrl, config.apiKey);
   try {
     const data = await client.getProjectContext(projectId);
+    const projectName = data.context?.project_name ?? data.context?.project?.name ?? "Refira Project";
+    const resolvedProjectId = data.context?.project_id ?? data.context?.project?.id ?? projectId;
     console.log(`
 ======================================================================`);
-    console.log(`\uD83D\uDCE6 REFIRA DESIGN CONTEXT: ${data.context.project.name} (${data.context.project.id})`);
+    console.log(`\uD83D\uDCE6 REFIRA DESIGN CONTEXT: ${projectName} (${resolvedProjectId})`);
     console.log("======================================================================");
-    const font = data.context.tokens?.typography?.font_family || data.context.project.fontFamily || "Inter";
+    const font = extractFontFamily(data.context?.tokens?.typography, data.context?.project?.fontFamily ?? "Inter");
     console.log(`
 \uD83D\uDD24 Primary Typography: Google Fonts "${font}"`);
-    if (data.context.tokens?.color) {
+    const colorTokens = data.context?.tokens?.colors ?? data.context?.tokens?.color;
+    if (colorTokens) {
       console.log(`
 \uD83C\uDFA8 Design Color Tokens:`);
-      for (const [tokenName, tokenVal] of Object.entries(data.context.tokens.color)) {
-        console.log(`   --${tokenName}: ${tokenVal}`);
+      for (const [tokenName, tokenVal] of Object.entries(colorTokens)) {
+        const displayVal = typeof tokenVal === "string" ? tokenVal : tokenVal?.hex ?? tokenVal?.oklch ?? JSON.stringify(tokenVal);
+        console.log(`   --${tokenName}: ${displayVal}`);
       }
     }
     console.log(`
@@ -2201,8 +2222,8 @@ async function initCommand(opts) {
   const client = new CliApiClient(apiUrl, apiKey);
   try {
     const data = await client.getProjectContext(projectId);
-    const projectName = data.context.project.name || "Refira Project";
-    const fontFamily = data.context.tokens?.typography?.font_family || data.context.project.fontFamily || "Inter";
+    const projectName = data.context?.project_name ?? data.context?.project?.name ?? "Refira Project";
+    const fontFamily = extractFontFamily(data.context?.tokens?.typography, data.context?.project?.fontFamily ?? "Inter");
     const agentsGuide = generateAgentsGuide({
       projectName,
       projectId,
@@ -3898,9 +3919,16 @@ async function scaffoldCommand(opts) {
     try {
       const client = new CliApiClient(config.apiUrl, config.apiKey);
       const data = await client.getProjectContext(config.projectId);
-      projectName = data.context.project.name || projectName;
-      fontFamily = data.context.tokens?.typography?.font_family || data.context.project.fontFamily || fontFamily;
-      colorTokens = data.context.tokens?.color;
+      projectName = data.context?.project_name ?? data.context?.project?.name ?? projectName;
+      fontFamily = extractFontFamily(data.context?.tokens?.typography, data.context?.project?.fontFamily ?? fontFamily);
+      const colors = data.context?.tokens?.colors ?? data.context?.tokens?.color;
+      if (colors) {
+        const parsed = {};
+        for (const [k, v] of Object.entries(colors)) {
+          parsed[k] = typeof v === "string" ? v : v?.hex ?? v?.oklch ?? "";
+        }
+        colorTokens = parsed;
+      }
     } catch {}
   }
   const pageName = pageSlug.replace(/-/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
@@ -3939,7 +3967,7 @@ AI coding agents will automatically recognize this skill for high-aesthetic prot
 
 // src/index.ts
 var program2 = new Command2;
-program2.name("refira").description("Refira CLI tool and AI Agent Harness for deterministic prototype generation").version("0.1.0");
+program2.name("refira").description("Refira CLI tool and AI Agent Harness for deterministic prototype generation").version("0.1.2");
 var auth = program2.command("auth").description("Manage Refira API authentication and sessions");
 auth.command("login").description("Login to Refira using an API key").option("--api-url <url>", "Refira backend API base URL", "http://localhost:3001").option("--api-key <key>", "Project API key (rfr_...)").option("-g, --global", "Save credentials globally in user home directory", false).action(loginCommand);
 auth.command("status").description("Verify and display current Refira authentication session").action(statusCommand);

package/package.json

@@ -1,26 +1,25 @@
 {
   "name": "refira-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Refira CLI tool and AI Agent Harness for deterministic prototype generation",
   "type": "module",
   "bin": {
     "refira": "./dist/index.js"
   },
   "main": "./dist/index.js",
-  "files": ["dist"],
+  "files": ["dist", "README.md"],
   "scripts": {
     "build": "bun build src/index.ts --outfile dist/index.js --target node",
     "prepublishOnly": "bun run build",
     "test": "vitest run",
     "type-check": "tsc --noEmit"
   },
-  "dependencies": {
-    "@refira/shared": "workspace:*",
-    "commander": "^12.1.0",
-    "htmlparser2": "^9.1.0"
-  },
+  "dependencies": {},
   "devDependencies": {
+    "@refira/shared": "workspace:*",
     "@types/node": "^20.14.0",
+    "commander": "^12.1.0",
+    "htmlparser2": "^9.1.0",
     "typescript": "^5.5.4",
     "vitest": "^2.0.5"
   }