npm - refira-cli - Versions diffs - 0.1.1 → 0.1.3 - Mend

refira-cli 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -102,17 +102,19 @@ Options:
 ---
-### 5. Live Preview & Harness Validation
+### 5. Live Preview, Push & Harness Validation
-#### `refira preview`
+#### `refira push` (or `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 push checkout.html --page checkout
+# Alternatively:
 refira preview checkout.html --page checkout
 ```
 Arguments:
-- `<file>`: Path to the HTML file to inspect and preview.
+- `<file>`: Path to the HTML file to inspect and push/preview.
 Options:
 - `--page <slug>`: Target page slug.
@@ -136,15 +138,16 @@ refira skill install --global
 ## Agent Harness Invariants
-All markup submitted via `refira preview` must conform to these strict architectural rules:
+All markup submitted via `refira push` / `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 External / Inter-Page Navigation** | Prohibited | Prototypes run inside sandboxed iframes. Anchors (`<a href="...">`) pointing to external URLs, relative pages (e.g. `/checkout`), empty `href=""`, or `javascript:` navigation are rejected. Only in-page anchors (`href="#section"`) or placeholders (`href="#"`) are allowed. Target attributes (`target="_blank"`, `target="_top"`) and `<form action="...">` are prohibited. For interactive triggers, use `<button type="button">`. |
 | **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>`. |
+| **Mandatory Push Execution** | Required | AI agents are strictly forbidden from stopping after writing a local file. The task is only complete when `refira push` succeeds with exit code 0. |
 ---

package/dist/index.js CHANGED Viewed

@@ -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;
@@ -1947,6 +1964,19 @@ class CliApiClient {
     const body = await res.json();
     return body.data;
   }
+  async startGenerating(projectId, pageIdentifier) {
+    const url = `${this.apiUrl}/api/cli/projects/${projectId}/pages/${pageIdentifier}/start-generating`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: this.getHeaders()
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`Failed to signal generation start (${res.status}): ${err}`);
+    }
+    const body = await res.json();
+    return body.data;
+  }
 }
 // src/config.ts
@@ -2047,18 +2077,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(`
@@ -2098,7 +2132,7 @@ function generateAgentsGuide(opts) {
 1. **Output Format:** Standalone HTML5 + Tailwind CSS CDN only.
 2. **Typography:** Load and use Google Fonts "${opts.fontFamily}".
 3. **No UI Frameworks:** Prohibited from using React, Vue, Svelte, Angular, Solid, or JSX syntax (\`className=\`, \`onClick={...}\`, \`<Component />\`).
-4. **No Inter-Page Navigation:** Prohibited from using \`<a href="/path">\` or external links. Use in-page section hashes (e.g., \`href="#pricing"\`) or \`href="#"\`.
+4. **Strict Anchor & Navigation Invariant:** Prohibited from creating cross-page navigation, external links, empty \`href=""\`, or \`javascript:\` navigation in \`<a href="...">\`. Anchor links MUST point only to in-page section hashes (e.g. \`href="#pricing"\`) or dummy hash (\`href="#"\`). Target attributes (\`target="_blank"\`, \`target="_top"\`) and external \`<form action="...">\` are prohibited. For interactive triggers, use \`<button type="button">\`.
 5. **No Raw Emojis:** Do not include raw emojis (e.g. \uD83D\uDE80, \uD83D\uDCA1, \uD83D\uDD25) in HTML markup. Use SVG icon libraries (Lucide Icons or Heroicons).
 6. **Permitted Graphics:** Three.js, GSAP, Spline Viewer, and Lucide Icons via CDN are explicitly allowed.
@@ -2106,18 +2140,26 @@ function generateAgentsGuide(opts) {
 ## 2. Refira CLI Command Surface
 - \`refira context\`: Inspect project design tokens, colors, typography, and existing pages.
-- \`refira scaffold --page <slug>\`: Create a clean HTML5 starter template with tokens pre-configured.
-- \`refira preview <file.html> --page <slug>\`: Run the deterministic harness check and stream updates to Refira Canvas.
+- \`refira scaffold --page <slug>\`: Create a clean HTML5 starter template and trigger live generating indicator on Refira Canvas.
+- \`refira push <file.html> --page <slug>\` (or \`refira preview\`): Run the deterministic harness check and stream updates to Refira Canvas.
 - \`refira skill install [-g]\`: Re-install the Refira design craftsmanship skill.
 ---
 ## 3. Mandatory Execution Workflow
 1. Run \`refira context\` to understand the project theme and existing pages.
-2. Run \`refira scaffold --page <page-name>\` to generate the file.
+2. Run \`refira scaffold --page <page-name>\` to register the page and activate live canvas pulse.
 3. Write your UI layout within the specified body slot using Tailwind utility classes.
-4. Execute \`refira preview <page-name>.html --page <page-name>\`.
+4. Execute \`refira push <page-name>.html --page <page-name>\`.
 5. If the CLI exits with code 1, address every listed violation and retry until exit code 0.
+---
+## 4. Mandatory Delivery Invariant (Push to Canvas)
+- **Local HTML files are NOT the final deliverable.** Refira Canvas is the live source of truth.
+- **Strictly Prohibited:** Stopping, ending your response, or reporting completion to the user after only writing a local HTML file.
+- **Autonomous Execution:** You MUST execute \`refira push <file.html> --page <slug>\` via your command-line execution tool. Do NOT ask the user to run it manually.
+- **Success Criteria:** A task is ONLY complete when \`refira push\` succeeds with exit code 0 and streams to Refira Canvas.
 `;
 }
@@ -2177,9 +2219,10 @@ When presenting features, data, or product capabilities:
 ## 5. Prototype Workflow in Refira
 1. Check current tokens: \`refira context\`
-2. Generate base page: \`refira scaffold --page <slug>\`
+2. Generate base page & trigger canvas pulse: \`refira scaffold --page <slug>\`
 3. Fill layout using Tailwind classes applying the aesthetic principles above.
-4. Preview on canvas: \`refira preview <slug>.html --page <slug>\`
+4. Stream to Refira Canvas: \`refira push <slug>.html --page <slug>\`
+5. Mandatory: Never stop after writing local files. Always execute \`refira push\` to complete the task.
 `;
 }
@@ -2201,8 +2244,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,
@@ -3612,12 +3655,14 @@ function checkTagName(name, violations) {
 }
 function checkAttributes(name, attribs, violations) {
   for (const [attrKey, attrVal] of Object.entries(attribs)) {
-    if (attrKey === "className") {
+    const lowerAttr = attrKey.toLowerCase();
+    const lowerTag = name.toLowerCase();
+    if (lowerAttr === "classname") {
       violations.push({
         type: "JSX_ATTRIBUTE",
-        target: "className",
-        message: `Prohibited JSX attribute 'className' detected on <${name}>.`,
-        remediation: `Change 'className' to the standard HTML 'class' attribute.`
+        target: attrKey,
+        message: `Prohibited JSX attribute '${attrKey}' detected on <${name}>.`,
+        remediation: `Change '${attrKey}' to the standard HTML 'class' attribute.`
       });
     }
     if (/^on[A-Z]/.test(attrKey) || attrKey.startsWith("@") || attrKey.startsWith("v-") || attrKey.startsWith("*")) {
@@ -3628,15 +3673,52 @@ function checkAttributes(name, attribs, violations) {
         remediation: "Remove framework event bindings. Use vanilla HTML and minimal vanilla JavaScript if needed."
       });
     }
-    if (attrKey === "href" && name.toLowerCase() === "a") {
+    if (lowerAttr.startsWith("on") && (attrVal.includes("location") || attrVal.includes("window.open") || attrVal.includes("history."))) {
+      violations.push({
+        type: "NAVIGATION_PROHIBITED",
+        target: `${attrKey}="${attrVal}"`,
+        message: `Inline navigation script '${attrVal}' detected on <${name}>.`,
+        remediation: "Remove inline navigation scripts. Prototypes run in a sandboxed canvas and cannot navigate across pages."
+      });
+    }
+    if (lowerTag === "a") {
+      if (lowerAttr === "href") {
+        const trimmed = attrVal.trim();
+        const isSafeHash = trimmed.startsWith("#");
+        const isSafeVoid = trimmed === "javascript:void(0)" || trimmed === "javascript:;";
+        if (!isSafeHash && !isSafeVoid) {
+          violations.push({
+            type: "NAVIGATION_PROHIBITED",
+            target: `${attrKey}="${attrVal}"`,
+            message: `Cross-page or external navigation '<a ${attrKey}="${attrVal}">' is strictly prohibited.`,
+            remediation: 'Refira prototypes run in a sandboxed iframe. Anchor links must point to in-page section hashes (e.g. href="#features") or placeholder (href="#"). If you need action triggers, use <button type="button">.'
+          });
+        } else if (trimmed.includes("location") || trimmed.includes("window.open")) {
+          violations.push({
+            type: "NAVIGATION_PROHIBITED",
+            target: `${attrKey}="${attrVal}"`,
+            message: `Navigation statement detected inside href: '${attrVal}'.`,
+            remediation: "Remove navigation statements from href."
+          });
+        }
+      }
+      if (lowerAttr === "target" && attrVal.trim().length > 0) {
+        violations.push({
+          type: "NAVIGATION_PROHIBITED",
+          target: `${attrKey}="${attrVal}"`,
+          message: `Target attribute '${attrKey}="${attrVal}"' on <a> is prohibited.`,
+          remediation: "Remove the target attribute. Prototypes must remain within the Refira Canvas viewport."
+        });
+      }
+    }
+    if (lowerTag === "form" && lowerAttr === "action") {
       const trimmed = attrVal.trim();
-      const isInternal = trimmed.startsWith("#") || trimmed.startsWith("javascript:");
-      if (!isInternal && trimmed.length > 0) {
+      if (trimmed.length > 0 && !trimmed.startsWith("#") && !trimmed.startsWith("javascript:void")) {
         violations.push({
           type: "NAVIGATION_PROHIBITED",
-          target: `href="${attrVal}"`,
-          message: `Cross-page or external navigation '<a href="${attrVal}">' is prohibited.`,
-          remediation: `Refira prototypes run in a sandboxed iframe. Replace with in-page anchor (e.g. href="#features") or placeholder (href="#").`
+          target: `${attrKey}="${attrVal}"`,
+          message: `Form action '${attrVal}' is prohibited in standalone prototypes.`,
+          remediation: 'Remove or replace form action with action="#" or handle submission client-side without page reload.'
         });
       }
     }
@@ -3898,9 +3980,20 @@ 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;
+      }
+      try {
+        await client.startGenerating(config.projectId, pageSlug);
+        console.log(`✨ Activated live generation indicator on Refira Canvas for '${pageSlug}'`);
+      } catch {}
     } catch {}
   }
   const pageName = pageSlug.replace(/-/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
@@ -3916,8 +4009,10 @@ async function scaffoldCommand(opts) {
   console.log(`   Font: ${fontFamily}`);
   console.log("   Slot: <!-- [REFIRA CANVAS SLOT: START] -->");
   console.log(`
-Next step: Edit '${targetPath}', then execute:`);
-  console.log(`   refira preview ${targetPath} --page ${pageSlug}`);
+\uD83D\uDEA8 [MANDATORY AGENT COMPLETION GATE]:`);
+  console.log(`   1. Write your UI layout within the designated slot in '${targetPath}'.`);
+  console.log(`   2. You MUST execute: refira push ${targetPath} --page ${pageSlug}`);
+  console.log("   DO NOT stop your response or declare completion until `refira push` succeeds!");
 }
 // src/commands/skill.ts
@@ -3939,14 +4034,14 @@ 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.3");
 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);
 program2.command("init").description("Initialize a Refira project workspace, generating AGENTS.md, .cursorrules, and skills").requiredOption("--project-id <id>", "Target project UUID").option("--api-url <url>", "Refira backend API base URL").option("--api-key <key>", "Project API key (rfr_...)").action(initCommand);
 program2.command("context").description("Inspect design tokens, color palette, typography, and page roster").option("--project-id <id>", "Project UUID").action(contextCommand);
 program2.command("scaffold").description("Generate a clean HTML5 + Tailwind starter template for a page").requiredOption("--page <slug>", "Page slug (e.g. checkout, dashboard, landing)").option("--output <path>", "Destination file path").action(scaffoldCommand);
-program2.command("preview").description("Inspect HTML markup with Agent Harness and stream to Refira Canvas").argument("<file>", "Path to HTML file to preview").requiredOption("--page <slug>", "Target page slug").action(previewCommand);
+program2.command("preview").alias("push").description("Inspect HTML markup with Agent Harness and stream to Refira Canvas").argument("<file>", "Path to HTML file to preview").requiredOption("--page <slug>", "Target page slug").action(previewCommand);
 var skill = program2.command("skill").description("Manage Refira Agent Skills");
 skill.command("install").description("Install the Refira design craftsmanship skill (.agents/skills/refira/SKILL.md)").option("-g, --global", "Install globally into user home directory (~/.agents/skills/refira)", false).action(skillInstallCommand);
 program2.parse();

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "refira-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Refira CLI tool and AI Agent Harness for deterministic prototype generation",
   "type": "module",
   "bin": {