@techninja/clearstack 0.4.16 → 0.4.20

package/docs/OG_METADATA_SPEC.md

@@ -24,14 +24,14 @@ Both are driven by the same `clearstack.routes.json` config and data sources.
   "/trait/:slug": {
     "title": "{slug.name}",
     "description": "{slug.description}",
-    "image": "{slug.cover_image.url}",
-    "data": "src/data/trait_manifest.json:traits",
+    "image": "{slug.image}",
+    "data": "data/traits-og.json",
     "ogTemplate": "trait"
   },
   "/shop/product/:sku": {
     "title": "{sku.name} | {store.name}",
     "description": "{sku.description}",
-    "image": "{store.url}{sku.images.0}",
+    "image": "{sku.images.0}",
     "data": "src/data/products.json",
     "ogTemplate": "product"
   }
@@ -111,6 +111,53 @@ clearstack build all --url=https://mysite.com --site=MySite --out=dist
 | `--logo` | Logo path or URL                   |
 | `--slug` | Single item slug (fast iteration)  |
 
+## Cloudflare Pages Routing
+
+Cloudflare Pages evaluates `_redirects` **before** checking the filesystem.
+The standard SPA catch-all `/* /index.html 200` will intercept all pre-rendered
+pages before they can be served. Since CF Pages serves `.html` files natively
+for extensionless URLs when a matching file exists on the filesystem, no extra
+rewrite rules are needed — just ensure the catch-all is the **only** rule and
+that it comes after any explicit redirects:
+
+```
+/old-path /new-path 301
+/* /index.html 200
+```
+
+The pre-rendered files (`shop/product/SM-TEE.html`) will be served directly by
+CF Pages' static file layer before the `_redirects` rules are evaluated.
+
+## Canonical Tags
+
+Inject `<link rel="canonical">` into every pre-rendered page so Google
+deduplicates the static HTML shell from the SPA view at the same URL. Do this
+as a post-processing step in `build.js` after `buildOG` runs:
+
+```js
+import { readdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function injectCanonicals(distDir, baseUrl) {
+  const prefixes = ['shop/product', 'trait', 'gene'];
+  for (const prefix of prefixes) {
+    const dir = resolve(distDir, prefix);
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith('.html')) continue;
+      const slug = file.slice(0, -5);
+      const url = `${baseUrl}/${prefix}/${slug}`;
+      const filePath = resolve(dir, file);
+      let html = readFileSync(filePath, 'utf-8');
+      if (!html.includes('rel="canonical"')) {
+        html = html.replace('</head>', `  <link rel="canonical" href="${url}" />\n  </head>`);
+        writeFileSync(filePath, html);
+      }
+    }
+  }
+}
+```
+
 ## Requirements
 
 - Zero config for basic cases (route title + description → OG tags)

package/lib/watch-runner.js

@@ -42,6 +42,7 @@ export function runKeys(specRows, keys, ctx) {
     const elapsed = ((Date.now() - t0) / 1000).toFixed(1) + 's';
     row.result = typeof raw === 'boolean' ? { pass: raw } : raw;
     row.pass = row.result.pass;
+    if (row.pass) row.ranAt = Date.now();
     row.detail = row.pass
       ? `${row.result.detail ?? (row.result.files ? `${row.result.files} files` : '')} (${elapsed})`
       : (row.result.violations?.length

package/lib/watch-ui.js

@@ -1,79 +1,16 @@
 /**
- * Spec watch UI — rendering, split candidates, violation extraction.
+ * Spec watch UI — rendering and violation display.
+ * Split candidate detection and violation extraction live in watch-violations.js.
  * Widget construction lives in watch-widgets.js.
  * @module lib/watch-ui
  */
 
-import { readFileSync, existsSync } from 'node:fs';
-import { resolve } from 'node:path';
 import { screen, statusBox, divider, logBox, getSpin, getCopyNote } from './watch-widgets.js';
 
 export { setQuit } from './watch-widgets.js';
+export { splitCandidates, extractViolations } from './watch-violations.js';
 
-// ── Split candidate detection ─────────────────────────────────────────────────
-
-/**
- * Suggest split seams for a file that exceeds the line limit.
- * Prefers `// SPLIT CANDIDATE:` comments, falls back to heuristics.
- * @param {string} filePath absolute path
- * @returns {string[]}
- */
-export function splitCandidates(filePath) {
-  if (!existsSync(filePath)) return [];
-  const lines = readFileSync(filePath, 'utf-8').split('\n');
-  const explicit = [];
-  lines.forEach((l, i) => {
-    const m = l.match(/\/\/\s*SPLIT CANDIDATE:\s*(.+)/i);
-    if (m) explicit.push(`  L${i + 1}: ${m[1].trim()}`);
-  });
-  if (explicit.length) return explicit;
-
-  const seams = [];
-  lines.forEach((l, i) => {
-    // Only exported functions/classes are meaningful split boundaries
-    if (/^export (async function|function|class)/.test(l)) seams.push(i + 1);
-  });
-  if (seams.length < 2) return [];
-  const suggestions = [];
-  for (let i = 0; i < seams.length - 1 && suggestions.length < 3; i++) {
-    const start = seams[i], end = seams[i + 1] - 1;
-    if (end - start < 10) continue;
-    // Peek at the function name for a more useful suggestion
-    const nameMatch = lines[start - 1]?.match(/^export (?:async )?function (\w+)/);
-    const hint = nameMatch ? `→ ${nameMatch[1]}()` : 'consider extracting';
-    suggestions.push(`  L${start}-${end}: ${hint}`);
-  }
-  return suggestions;
-}
-
-// ── Violation extraction ──────────────────────────────────────────────────────
-
-/**
- * Process a failed check row into violation tuples for the log panel.
- * @param {object} row
- * @param {string} projectDir
- * @returns {string[][]}
- */
-export function extractViolations(row, projectDir) {
-  if (row.pass) return [];
-  if (row.result?.violations?.length) {
-    return row.result.violations.map((v) => {
-      if (v.spec !== undefined) return [v.file, `import '${v.spec}' → use #prefix/ alias`];
-      const candidates = splitCandidates(resolve(projectDir, v.file));
-      return [v.file, `${v.lines} lines (max ${v.max}, +${v.lines - v.max} over)`, ...candidates];
-    });
-  }
-  if (row.result?.errors?.length) {
-    const errors = row.result.errors;
-    // Prettier: [warn] src/file.js — expand each into its own entry
-    const prettierFiles = errors.map((l) => l.match(/^\[warn\]\s+(.+\.\w+)$/)?.[1]).filter(Boolean);
-    if (prettierFiles.length) return prettierFiles.map((f) => [f, 'formatting — run npm run format']);
-    return [[row.label ?? row.name ?? row.key, errors.slice(0, 5).join('\n')]];
-  }
-  return [];
-}
-
-// ── Render ────────────────────────────────────────────────────────────────────
+// ── Row rendering ─────────────────────────────────────────────────────────────
 
 /** @param {object} r */
 function rowIcon(r) {
@@ -85,11 +22,40 @@ function rowIcon(r) {
   }
   if (r.pass === null) return '{grey-fg}' + getSpin() + '{/}';
   if (r.pass)          return '{green-fg}ok{/}';
+  if (r.keyBinding)    return '{grey-fg}–{/} ';
   return '{red-fg}!{/} ';
 }
 
+/** @param {number} ms @returns {string} */
+function timeAgo(ms) {
+  const s = Math.floor((Date.now() - ms) / 1000);
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  return `${Math.floor(m / 60)}h ago`;
+}
+
 /** @param {object} r @param {number} w */
-const rowLine = (r, w) => { const n = (r.label ?? r.name ?? r.key).padEnd(w); return ` ${rowIcon(r)} ${r.pass === false ? `{red-fg}${n}{/}` : n}  ${r.detail ? `{grey-fg}${r.detail}{/}` : ''}`; };
+const rowLine = (r, w) => {
+  const n = (r.label ?? r.name ?? r.key).padEnd(w);
+  const isIdle = r.pass === false && r.keyBinding;
+  const name = (!isIdle && r.pass === false) ? `{red-fg}${n}{/}` : n;
+  const detail = isIdle
+    ? `{grey-fg}${r.ranAt ? timeAgo(r.ranAt) : `press ${r.keyBinding} to run`}{/}`
+    : (r.detail ? `{grey-fg}${r.detail}{/}` : '');
+  return ` ${rowIcon(r)} ${name}  ${detail}`;
+};
+
+// ── Status box helpers ────────────────────────────────────────────────────────
+
+/** @param {object[]} rows @param {string} lastCheck @param {string[]} watchDirs */
+function statusContent(rows, lastCheck, watchDirs) {
+  const w = Math.max(...rows.map((r) => (r.label ?? r.name ?? r.key).length));
+  return [...rows.map((r) => rowLine(r, w)), '',
+    `{grey-fg} watching ${watchDirs.join(', ')}   last check: ${lastCheck}{/}${getCopyNote()}`];
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
 
 /**
  * Render the dashboard.
@@ -99,14 +65,11 @@ const rowLine = (r, w) => { const n = (r.label ?? r.name ?? r.key).padEnd(w); re
  * @param {string[][]} violations
  */
 export function render(rows, lastCheck, watchDirs, violations) {
-  const w = Math.max(...rows.map((r) => (r.label ?? r.name ?? r.key).length));
-  const statusLines = rows.map((r) => rowLine(r, w));
-  statusLines.push('');
-  statusLines.push(`{grey-fg} watching ${watchDirs.join(', ')}   last check: ${lastCheck}{/}${getCopyNote()}`);
-  statusBox.setContent(statusLines.join('\n'));
-  statusBox.height = statusLines.length;
+  const lines = statusContent(rows, lastCheck, watchDirs);
+  statusBox.setContent(lines.join('\n'));
+  statusBox.height = lines.length;
 
-  const statusHeight = statusLines.length + 1;
+  const statusHeight = lines.length + 1;
   divider.top = statusHeight;
   logBox.top = statusHeight + 1;
 
@@ -139,7 +102,6 @@ export function destroyScreen() {
 
 /** Refresh just the status box — used for transient notes like copy confirmation. */
 export function renderNote(rows, lastCheck, watchDirs) {
-  const w = Math.max(...rows.map((r) => (r.label ?? r.name ?? r.key).length));
-  statusBox.setContent([...rows.map((r) => rowLine(r, w)), '', `{grey-fg} watching ${watchDirs.join(', ')}   last check: ${lastCheck}{/}${getCopyNote()}`].join('\n'));
+  statusBox.setContent(statusContent(rows, lastCheck, watchDirs).join('\n'));
   screen.render();
 }

package/lib/watch-violations.js

@@ -0,0 +1,66 @@
+/**
+ * Violation extraction and split candidate detection for the spec watch dashboard.
+ * @module lib/watch-violations
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/**
+ * Suggest split seams for a file that exceeds the line limit.
+ * Prefers `// SPLIT CANDIDATE:` comments, falls back to heuristics.
+ * @param {string} filePath absolute path
+ * @returns {string[]}
+ */
+export function splitCandidates(filePath) {
+  if (!existsSync(filePath)) return [];
+  const lines = readFileSync(filePath, 'utf-8').split('\n');
+  const explicit = [];
+  lines.forEach((l, i) => {
+    const m = l.match(/\/\/\s*SPLIT CANDIDATE:\s*(.+)/i);
+    if (m) explicit.push(`  L${i + 1}: ${m[1].trim()}`);
+  });
+  if (explicit.length) return explicit;
+
+  const seams = [];
+  lines.forEach((l, i) => {
+    // Only exported functions/classes are meaningful split boundaries
+    if (/^export (async function|function|class)/.test(l)) seams.push(i + 1);
+  });
+  if (seams.length < 2) return [];
+  const suggestions = [];
+  for (let i = 0; i < seams.length - 1 && suggestions.length < 3; i++) {
+    const start = seams[i], end = seams[i + 1] - 1;
+    if (end - start < 10) continue;
+    // Peek at the function name for a more useful suggestion
+    const nameMatch = lines[start - 1]?.match(/^export (?:async )?function (\w+)/);
+    const hint = nameMatch ? `→ ${nameMatch[1]}()` : 'consider extracting';
+    suggestions.push(`  L${start}-${end}: ${hint}`);
+  }
+  return suggestions;
+}
+
+/**
+ * Process a failed check row into violation tuples for the log panel.
+ * @param {object} row
+ * @param {string} projectDir
+ * @returns {string[][]}
+ */
+export function extractViolations(row, projectDir) {
+  if (row.pass) return [];
+  if (row.result?.violations?.length) {
+    return row.result.violations.map((v) => {
+      if (v.spec !== undefined) return [v.file, `import '${v.spec}' → use #prefix/ alias`];
+      const candidates = splitCandidates(resolve(projectDir, v.file));
+      return [v.file, `${v.lines} lines (max ${v.max}, +${v.lines - v.max} over)`, ...candidates];
+    });
+  }
+  if (row.result?.errors?.length) {
+    const errors = row.result.errors;
+    // Prettier: [warn] src/file.js — expand each into its own entry
+    const prettierFiles = errors.map((l) => l.match(/^\[warn\]\s+(.+\.\w+)$/)?.[1]).filter(Boolean);
+    if (prettierFiles.length) return prettierFiles.map((f) => [f, 'formatting — run npm run format']);
+    return [[row.label ?? row.name ?? row.key, errors.slice(0, 5).join('\n')]];
+  }
+  return [];
+}

package/lib/watch.js

@@ -17,7 +17,7 @@ import { screen, outer } from './watch-widgets.js';
 /**
  *
  */
-function toRow(check) { return { ...check, pass: null, detail: '', result: null }; }
+function toRow(check) { return { ...check, pass: check.keyBinding ? false : null, detail: '', result: null }; }
 
 /**
  *
@@ -78,6 +78,13 @@ export async function startWatch(projectDir) {
   render(rows, lastCheck.value, watchDirs, currentViolations.value);
   run(new Set(specRows.filter((r) => !r.keyBinding).map((r) => r.key)));
 
+  // Refresh idle key-bound rows so "X ago" detail stays current.
+  const idleTimer = setInterval(() => {
+    if (specRows.some((r) => r.keyBinding && r.pass === false && r.ranAt))
+      render(rows, lastCheck.value, watchDirs, currentViolations.value);
+  }, 30_000);
+  idleTimer.unref();
+
   setupFix(specRows, cmds, ctx, pending, timers, run);
 
   setupLifecycle({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.4.16",
+  "version": "0.4.20",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {
@@ -23,6 +23,7 @@
   "scripts": {
     "start": "node src/server.js",
     "dev": "node --watch --env-file=.env --env-file=.env.local src/server.js",
+    "docs": "node scripts/sync-docs.js",
     "setup": "node scripts/vendor-deps.js && node scripts/build-icons.js",
     "test": "node scripts/test.js",
     "spec": "node --env-file=.env scripts/spec.js",

package/templates/shared/docs/clearstack/OG_METADATA_SPEC.md

@@ -24,14 +24,14 @@ Both are driven by the same `clearstack.routes.json` config and data sources.
   "/trait/:slug": {
     "title": "{slug.name}",
     "description": "{slug.description}",
-    "image": "{slug.cover_image.url}",
-    "data": "src/data/trait_manifest.json:traits",
+    "image": "{slug.image}",
+    "data": "data/traits-og.json",
     "ogTemplate": "trait"
   },
   "/shop/product/:sku": {
     "title": "{sku.name} | {store.name}",
     "description": "{sku.description}",
-    "image": "{store.url}{sku.images.0}",
+    "image": "{sku.images.0}",
     "data": "src/data/products.json",
     "ogTemplate": "product"
   }
@@ -111,6 +111,53 @@ clearstack build all --url=https://mysite.com --site=MySite --out=dist
 | `--logo` | Logo path or URL                   |
 | `--slug` | Single item slug (fast iteration)  |
 
+## Cloudflare Pages Routing
+
+Cloudflare Pages evaluates `_redirects` **before** checking the filesystem.
+The standard SPA catch-all `/* /index.html 200` will intercept all pre-rendered
+pages before they can be served. Since CF Pages serves `.html` files natively
+for extensionless URLs when a matching file exists on the filesystem, no extra
+rewrite rules are needed — just ensure the catch-all is the **only** rule and
+that it comes after any explicit redirects:
+
+```
+/old-path /new-path 301
+/* /index.html 200
+```
+
+The pre-rendered files (`shop/product/SM-TEE.html`) will be served directly by
+CF Pages' static file layer before the `_redirects` rules are evaluated.
+
+## Canonical Tags
+
+Inject `<link rel="canonical">` into every pre-rendered page so Google
+deduplicates the static HTML shell from the SPA view at the same URL. Do this
+as a post-processing step in `build.js` after `buildOG` runs:
+
+```js
+import { readdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function injectCanonicals(distDir, baseUrl) {
+  const prefixes = ['shop/product', 'trait', 'gene'];
+  for (const prefix of prefixes) {
+    const dir = resolve(distDir, prefix);
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith('.html')) continue;
+      const slug = file.slice(0, -5);
+      const url = `${baseUrl}/${prefix}/${slug}`;
+      const filePath = resolve(dir, file);
+      let html = readFileSync(filePath, 'utf-8');
+      if (!html.includes('rel="canonical"')) {
+        html = html.replace('</head>', `  <link rel="canonical" href="${url}" />\n  </head>`);
+        writeFileSync(filePath, html);
+      }
+    }
+  }
+}
+```
+
 ## Requirements
 
 - Zero config for basic cases (route title + description → OG tags)