@cloverleaf/reference-impl 0.3.0 → 0.3.1

package/README.md

@@ -52,12 +52,43 @@ Two JSON config files in `config/` (overridable per consumer project):
 - `config/ui-paths.json` — glob patterns that trigger UI Reviewer (default: `site/**`)
 - `config/qa-rules.json` — per-package test commands
 
+### Customizing for your repo
+
+The package ships with cloverleaf-flavored defaults in `config/`. Your repo overrides any of them by placing a file of the same name at `<repoRoot>/.cloverleaf/config/<name>.json`. Consumer override is a **full replacement** — your file becomes the complete source of truth for that config.
+
+Available overrides:
+
+| Override file | Purpose |
+|---|---|
+| `.cloverleaf/config/ui-paths.json` | Controls `detect-ui-paths` — which diffs trigger the `ui-review` state |
+| `.cloverleaf/config/qa-rules.json` | Per-package test commands for the QA agent |
+| `.cloverleaf/config/affected-routes.json` | Rules for mapping diffs to site routes (UI Reviewer scope); includes `contentRoutes` for content-collection mapping |
+| `.cloverleaf/config/astro-base.json` | Explicit Astro `base` path — avoids best-effort parsing of `astro.config.*` |
+
+Example `affected-routes.json` override for a Next.js project:
+
+```json
+{
+  "pageRoots": ["apps/web/app/"],
+  "globalPatterns": ["apps/web/components/**", "apps/web/styles/**"],
+  "routeScope": ["apps/web/**"],
+  "contentRoutes": {}
+}
+```
+
+Example `astro-base.json`:
+
+```json
+{ "base": "/my-docs" }
+```
+
+All overrides are read fresh on every skill invocation; no caching. Edit and the next `/cloverleaf-run` picks it up.
+
 ### Known limitations
 
 - Concurrent `/cloverleaf-run` on the same repo may race on preview ports.
 - UI Reviewer visual diff + multi-viewport deferred to v0.4.
 - QA does not produce HTML reports (no `report_uri`).
-- Astro `base` path is parsed best-effort; if misdetected, UI Reviewer may return escalate.
 
 ### Prerequisites for UI Reviewer
 

package/VERSION

@@ -1 +1 @@
-0.3.0
+0.3.1

package/config/affected-routes.json

@@ -8,5 +8,6 @@
     "site/astro.config.*",
     "site/src/content/**"
   ],
-  "routeScope": ["site/src/**", "site/public/**"]
+  "routeScope": ["site/src/**", "site/public/**"],
+  "contentRoutes": {}
 }

package/dist/affected-routes.mjs

@@ -34,8 +34,31 @@ export function loadDefaultConfig() {
         pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
         globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
         routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+        contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+            ? doc.contentRoutes
+            : {},
     };
 }
+export function loadAffectedRoutesConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'affected-routes.json');
+    if (existsSync(consumerPath)) {
+        try {
+            const doc = JSON.parse(readFileSync(consumerPath, 'utf-8'));
+            return {
+                pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
+                globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
+                routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+                contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+                    ? doc.contentRoutes
+                    : {},
+            };
+        }
+        catch {
+            // fall through
+        }
+    }
+    return loadDefaultConfig();
+}
 export function computeAffectedRoutes(changedFiles, config) {
     const routes = new Set();
     let inScopeButUnmatched = false;
@@ -55,6 +78,16 @@ export function computeAffectedRoutes(changedFiles, config) {
             routes.add(mapped);
             continue;
         }
+        // contentRoutes: map content-collection files to specific routes
+        for (const [pattern, route] of Object.entries(config.contentRoutes)) {
+            if (globToRegex(pattern).test(file)) {
+                routes.add(route);
+                mapped = route;
+                break;
+            }
+        }
+        if (mapped)
+            continue;
         if (matchesAny(file, config.routeScope)) {
             inScopeButUnmatched = true;
         }

package/dist/cli.mjs

@@ -20,8 +20,10 @@ import { advanceStatus } from './state.mjs';
 import { emitGateDecision } from './events.mjs';
 import { writeFeedback, latestFeedback } from './feedback.mjs';
 import { nextTaskId, inferProject } from './ids.mjs';
-import { matchesUiPaths, loadDefaultPatterns } from './ui-paths.mjs';
-import { computeAffectedRoutes, loadDefaultConfig } from './affected-routes.mjs';
+import { matchesUiPaths } from './ui-paths.mjs';
+import { loadUiPathsConfig } from './ui-paths.mjs';
+import { computeAffectedRoutes } from './affected-routes.mjs';
+import { loadAffectedRoutesConfig } from './affected-routes.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -177,7 +179,7 @@ try {
                 console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
                 process.exit(2);
             }
-            const patterns = loadDefaultPatterns();
+            const { patterns } = loadUiPathsConfig(repoRoot);
             const result = matchesUiPaths(changed, patterns);
             process.stdout.write(`${result}\n`);
             process.exit(0);
@@ -204,7 +206,7 @@ try {
                 console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
                 process.exit(2);
             }
-            const config = loadDefaultConfig();
+            const config = loadAffectedRoutesConfig(repoRoot);
             const result = computeAffectedRoutes(changed, config);
             process.stdout.write(`${JSON.stringify(result)}\n`);
             process.exit(0);

package/dist/qa-rules.mjs

@@ -10,6 +10,21 @@ export function loadDefaultRules() {
     const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8'));
     return Array.isArray(doc.rules) ? doc.rules : [];
 }
+export function loadQaRulesConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'qa-rules.json');
+    if (existsSync(consumerPath)) {
+        try {
+            const doc = JSON.parse(readFileSync(consumerPath, 'utf-8'));
+            if (Array.isArray(doc.rules)) {
+                return doc.rules;
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    return loadDefaultRules();
+}
 export function selectTestCommands(changedFiles, rules) {
     return rules.filter((rule) => matchesUiPaths(changedFiles, rule.match));
 }

package/dist/ui-paths.mjs

@@ -17,6 +17,21 @@ function globToRegex(pattern) {
         .replace(/\u0000/g, '.*');
     return new RegExp(`^${regex}$`);
 }
+export function loadUiPathsConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'ui-paths.json');
+    if (existsSync(consumerPath)) {
+        try {
+            const doc = JSON.parse(readFileSync(consumerPath, 'utf-8'));
+            if (Array.isArray(doc.patterns)) {
+                return { patterns: doc.patterns };
+            }
+        }
+        catch {
+            // fall through to package default
+        }
+    }
+    return { patterns: loadDefaultPatterns() };
+}
 export function matchesUiPaths(changedFiles, patterns) {
     if (changedFiles.length === 0)
         return false;

package/lib/affected-routes.ts

@@ -9,6 +9,7 @@ export interface AffectedRoutesConfig {
   pageRoots: string[];
   globalPatterns: string[];
   routeScope: string[];
+  contentRoutes: Record<string, string>;
 }
 
 function globToRegex(pattern: string): RegExp {
@@ -42,9 +43,32 @@ export function loadDefaultConfig(): AffectedRoutesConfig {
     pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
     globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
     routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+    contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+      ? doc.contentRoutes
+      : {},
   };
 }
 
+export function loadAffectedRoutesConfig(repoRoot: string): AffectedRoutesConfig {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'affected-routes.json');
+  if (existsSync(consumerPath)) {
+    try {
+      const doc = JSON.parse(readFileSync(consumerPath, 'utf-8')) as Partial<AffectedRoutesConfig>;
+      return {
+        pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
+        globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
+        routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+        contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+          ? doc.contentRoutes
+          : {},
+      };
+    } catch {
+      // fall through
+    }
+  }
+  return loadDefaultConfig();
+}
+
 export function computeAffectedRoutes(
   changedFiles: string[],
   config: AffectedRoutesConfig
@@ -68,6 +92,15 @@ export function computeAffectedRoutes(
       routes.add(mapped);
       continue;
     }
+    // contentRoutes: map content-collection files to specific routes
+    for (const [pattern, route] of Object.entries(config.contentRoutes)) {
+      if (globToRegex(pattern).test(file)) {
+        routes.add(route);
+        mapped = route;
+        break;
+      }
+    }
+    if (mapped) continue;
     if (matchesAny(file, config.routeScope)) {
       inScopeButUnmatched = true;
     }

package/lib/cli.ts

@@ -21,8 +21,10 @@ import { advanceStatus } from './state.js';
 import { emitGateDecision } from './events.js';
 import { writeFeedback, latestFeedback } from './feedback.js';
 import { nextTaskId, inferProject } from './ids.js';
-import { matchesUiPaths, loadDefaultPatterns } from './ui-paths.js';
-import { computeAffectedRoutes, loadDefaultConfig } from './affected-routes.js';
+import { matchesUiPaths } from './ui-paths.js';
+import { loadUiPathsConfig } from './ui-paths.js';
+import { computeAffectedRoutes } from './affected-routes.js';
+import { loadAffectedRoutesConfig } from './affected-routes.js';
 import type { FeedbackEnvelope } from './feedback.js';
 
 function die(msg: string, code = 1): never {
@@ -186,7 +188,7 @@ try {
         console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
         process.exit(2);
       }
-      const patterns = loadDefaultPatterns();
+      const { patterns } = loadUiPathsConfig(repoRoot);
       const result = matchesUiPaths(changed, patterns);
       process.stdout.write(`${result}\n`);
       process.exit(0);
@@ -213,7 +215,7 @@ try {
         console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
         process.exit(2);
       }
-      const config = loadDefaultConfig();
+      const config = loadAffectedRoutesConfig(repoRoot);
       const result = computeAffectedRoutes(changed, config);
       process.stdout.write(`${JSON.stringify(result)}\n`);
       process.exit(0);

package/lib/qa-rules.ts

@@ -18,6 +18,21 @@ export function loadDefaultRules(): QaRule[] {
   return Array.isArray(doc.rules) ? doc.rules : [];
 }
 
+export function loadQaRulesConfig(repoRoot: string): QaRule[] {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'qa-rules.json');
+  if (existsSync(consumerPath)) {
+    try {
+      const doc = JSON.parse(readFileSync(consumerPath, 'utf-8')) as { rules?: QaRule[] };
+      if (Array.isArray(doc.rules)) {
+        return doc.rules;
+      }
+    } catch {
+      // fall through
+    }
+  }
+  return loadDefaultRules();
+}
+
 export function selectTestCommands(changedFiles: string[], rules: QaRule[]): QaRule[] {
   return rules.filter((rule) => matchesUiPaths(changedFiles, rule.match));
 }

package/lib/ui-paths.ts

@@ -20,6 +20,21 @@ function globToRegex(pattern: string): RegExp {
   return new RegExp(`^${regex}$`);
 }
 
+export function loadUiPathsConfig(repoRoot: string): { patterns: string[] } {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'ui-paths.json');
+  if (existsSync(consumerPath)) {
+    try {
+      const doc = JSON.parse(readFileSync(consumerPath, 'utf-8')) as { patterns?: string[] };
+      if (Array.isArray(doc.patterns)) {
+        return { patterns: doc.patterns };
+      }
+    } catch {
+      // fall through to package default
+    }
+  }
+  return { patterns: loadDefaultPatterns() };
+}
+
 export function matchesUiPaths(changedFiles: string[], patterns: string[]): boolean {
   if (changedFiles.length === 0) return false;
   const regexes = patterns.map(globToRegex);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

package/prompts/ui-reviewer.md

@@ -46,7 +46,10 @@ The `PLAYWRIGHT_BROWSERS_PATH` environment variable is set to `~/.cache/ms-playw
 
 4. Wait up to 30s for `http://localhost:{{preview_port}}/` to respond 200. If the server fails to start in 30s, kill it and return verdict `escalate`.
 
-5. Determine the site base path: read `astro.config.*` in the worktree for a `base: '<path>'` entry. Default to empty string if not found or unparseable.
+5. Determine the site base path:
+   1. Check `<repoRoot>/.cloverleaf/config/astro-base.json`. Expected shape: `{ "base": "<path>" }`. If present, use the `base` field verbatim and skip to step 6. (Consumer override — checked before parsing astro config.)
+   2. Otherwise, attempt to locate and parse an astro config file (common locations: `site/astro.config.mjs`, `astro.config.mjs` at repo root, `apps/web/astro.config.mjs`). This is best-effort; the v0.3 behavior is preserved. Consumers with non-conventional layouts should supply `astro-base.json` rather than relying on parse.
+   3. If both fail, treat base as empty string.
 
 6. For each route in `{{affected_routes}}` (or the crawl set, if `"all"`):
    - Construct URL `http://localhost:{{preview_port}}<base><route>`.

package/skills/cloverleaf-qa.md

@@ -21,7 +21,12 @@ description: Run the QA agent on a task in the `qa` state (full pipeline only).
 
 4. Load QA rules JSON:
    ```bash
-   cat ~/.claude/plugins/cloverleaf/config/qa-rules.json
+   # Consumer override takes precedence over the package default.
+   if [ -f "<repo_root>/.cloverleaf/config/qa-rules.json" ]; then
+     cat "<repo_root>/.cloverleaf/config/qa-rules.json"
+   else
+     cat ~/.claude/plugins/cloverleaf/config/qa-rules.json
+   fi
    ```
    Capture for the subagent as `qa_rules`.