@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/engine/detect-project/scripts/json_get.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * json_get.js — read values from a JSON file for shell scripts and SKILL.md
+ * steps, so the skills need Node only (no jq).
+ *
+ * A path is dot-separated keys; a segment ending in [] iterates an array or
+ * object's values ("reasons[].code"). "." is the whole document. Like jq's
+ * `//`, null, false and missing values fall back to the default.
+ *
+ * Usage:
+ *   node json_get.js <file> <path> [default]     print a value (arrays: one item per line)
+ *   node json_get.js --length <file> <path>      print the length (0 when missing)
+ *   node json_get.js --join <sep> <file> <path>  join the values with <sep>
+ *   node json_get.js --count <file> <path> <key>=<value>
+ *                                                count values whose <key> equals <value>
+ *   node json_get.js --exists <file> <path>      exit 0 when present and not null/false
+ *   node json_get.js --valid <file>...           exit 0 when every file parses as JSON
+ *
+ * A missing path with no default prints "null", as jq -r does.
+ */
+
+const fs = require('fs');
+
+function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+/** Resolve a path to its list of values (more than one when a segment iterates). */
+function resolve(doc, path) {
+    let values = [doc];
+    if (path === '.' || path === '') return values;
+    for (const raw of path.replace(/^\./, '').split('.')) {
+        const iterate = raw.endsWith('[]');
+        const key = iterate ? raw.slice(0, -2) : raw;
+        const next = [];
+        for (const value of values) {
+            const child = key === '' ? value : lookup(value, key);
+            if (!iterate) next.push(child);
+            else if (Array.isArray(child)) next.push(...child);
+            else if (child !== null && typeof child === 'object') next.push(...Object.values(child));
+        }
+        values = next;
+    }
+    return values;
+}
+
+function lookup(value, key) {
+    if (Array.isArray(value) && /^\d+$/.test(key)) return value[Number(key)];
+    if (value !== null && typeof value === 'object' && Object.hasOwn(value, key)) return value[key];
+    return undefined;
+}
+
+function present(value) {
+    return value !== undefined && value !== null && value !== false;
+}
+
+function format(value) {
+    if (value === undefined || value === null) return 'null';
+    if (typeof value === 'string') return value;
+    if (typeof value === 'object') return JSON.stringify(value, null, 2);
+    return String(value);
+}
+
+function lengthOf(value) {
+    if (Array.isArray(value) || typeof value === 'string') return value.length;
+    if (value !== null && typeof value === 'object') return Object.keys(value).length;
+    return 0;
+}
+
+function main(argv) {
+    const mode = argv[0]?.startsWith('--') ? argv.shift() : '--get';
+    const out = text => process.stdout.write(text + '\n');
+
+    switch (mode) {
+        case '--get': {
+            const [file, path, fallback] = argv;
+            if (!file || !path) usage();
+            const values = resolve(readJson(file), path).filter(present);
+            if (values.length) {
+                const [only] = values;
+                out(values.length === 1 && Array.isArray(only) ? only.map(format).join('\n') : values.map(format).join('\n'));
+            } else {
+                out(fallback ?? 'null');
+            }
+            return 0;
+        }
+        case '--length': {
+            const [file, path] = argv;
+            if (!file || !path) usage();
+            out(String(lengthOf(resolve(readJson(file), path)[0])));
+            return 0;
+        }
+        case '--join': {
+            const [sep, file, path] = argv;
+            if (sep === undefined || !file || !path) usage();
+            out(resolve(readJson(file), path).filter(present).map(format).join(sep));
+            return 0;
+        }
+        case '--count': {
+            const [file, path, condition] = argv;
+            if (!file || !path || !condition?.includes('=')) usage();
+            const [key, expected] = [condition.slice(0, condition.indexOf('=')), condition.slice(condition.indexOf('=') + 1)];
+            const matches = resolve(readJson(file), path).filter(value => format(lookup(value, key)) === expected);
+            out(String(matches.length));
+            return 0;
+        }
+        case '--exists': {
+            const [file, path] = argv;
+            if (!file || !path) usage();
+            try { return resolve(readJson(file), path).some(present) ? 0 : 1; }
+            catch { return 1; }
+        }
+        case '--valid': {
+            if (!argv.length) usage();
+            let status = 0;
+            for (const file of argv) {
+                try { readJson(file); }
+                catch (error) { process.stderr.write(`${file}: ${error.message}\n`); status = 1; }
+            }
+            return status;
+        }
+        default:
+            usage();
+    }
+}
+
+function usage() {
+    process.stderr.write('Usage: json_get.js [--length|--join <sep>|--count|--exists|--valid] <file> <path> [default]\n');
+    process.exit(2);
+}
+
+if (require.main === module) {
+    try { process.exitCode = main(process.argv.slice(2)); }
+    catch (error) {
+        process.stderr.write(`json_get: ${error.message}\n`);
+        process.exitCode = 1;
+    }
+}
+
+module.exports = { resolve, lengthOf };

package/engine/detect-project/scripts/merge_json.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * merge_json.js — deep-merge a JSON patch into a JSON file in place.
+ *
+ * Objects merge key by key; arrays and scalars in the patch replace the
+ * target's value. Keys absent from the patch are kept, so stamped fields such
+ * as app_type/app_type_source survive an enrichment merge. A null in the patch
+ * sets the key to null (it does not delete it).
+ *
+ * Usage:
+ *   node merge_json.js <target.json> <patch.json>
+ *   node merge_json.js <target.json> -        (patch on stdin)
+ */
+
+const fs = require('fs');
+
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function merge(target, patch) {
+    if (!isObject(target) || !isObject(patch)) return patch;
+    const result = { ...target };
+    for (const [key, value] of Object.entries(patch)) {
+        result[key] = isObject(value) && isObject(result[key]) ? merge(result[key], value) : value;
+    }
+    return result;
+}
+
+function main(argv) {
+    const [targetFile, patchFile] = argv;
+    if (!targetFile || !patchFile) {
+        process.stderr.write('Usage: merge_json.js <target.json> <patch.json|->\n');
+        return 2;
+    }
+    const target = JSON.parse(fs.readFileSync(targetFile, 'utf8'));
+    const patch = JSON.parse(fs.readFileSync(patchFile === '-' ? 0 : patchFile, 'utf8'));
+    fs.writeFileSync(targetFile, JSON.stringify(merge(target, patch), null, 2) + '\n');
+    return 0;
+}
+
+if (require.main === module) {
+    try { process.exitCode = main(process.argv.slice(2)); }
+    catch (error) {
+        process.stderr.write(`merge_json: ${error.message}\n`);
+        process.exitCode = 1;
+    }
+}
+
+module.exports = { merge };

package/engine/detect-project/scripts/recommend_model_tier.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * recommend_model_tier.js — classify the model capability needed for mockups.
+ *
+ * This is deliberately a cache-only postprocessor. detect-project has already
+ * paid the cost of resolving routes, chrome, runtime editors, and CSS health;
+ * repeating that exploration in another skill would waste both time and model
+ * tokens. The parent application maps low/medium/high to current model IDs.
+ *
+ * Usage:
+ *   node recommend_model_tier.js <project_map.json> <branding.json>
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const POLICY_VERSION = 'heuristic-v1';
+const VALID_APP_TYPES = new Set(['web', 'terminal', 'mobile', 'desktop', 'win32', 'macos', 'game']);
+const SPECIALIZED_APP_TYPES = new Set(['terminal', 'mobile', 'desktop', 'win32', 'macos']);
+const SHELL_REGION_KEYS = [
+    'top_bar', 'titlebar', 'menu_bar', 'global_sidebar', 'primary_sidebar',
+    'secondary_sidebar', 'statusbar', 'toolbar', 'account_area',
+];
+const INDEX_KEYS = ['route_index', 'screen_index', 'command_index', 'dialog_index', 'view_index'];
+
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function objectValues(value) {
+    return isObject(value) ? Object.values(value) : [];
+}
+
+function indexCount(map) {
+    return Math.max(0, ...INDEX_KEYS.map(key => objectValues(map[key]).length));
+}
+
+function shellMetrics(shell) {
+    if (!isObject(shell)) return { navItems: 0, persistentRegions: 0 };
+    const navItems = Array.isArray(shell.nav_items) ? shell.nav_items.length : 0;
+    const persistentRegions = SHELL_REGION_KEYS.filter(key => {
+        const value = shell[key];
+        if (Array.isArray(value)) return value.length > 0;
+        if (isObject(value)) return Object.keys(value).length > 0;
+        return typeof value === 'string' ? value.trim().length > 0 : Boolean(value);
+    }).length;
+    return { navItems, persistentRegions };
+}
+
+function maxSourceFanout(map) {
+    let max = 0;
+    for (const key of INDEX_KEYS) {
+        for (const entry of objectValues(map[key])) {
+            if (!isObject(entry)) continue;
+            const expanded = Array.isArray(entry.partials_expanded) ? entry.partials_expanded.length : 0;
+            max = Math.max(max, expanded);
+        }
+    }
+    return max;
+}
+
+function runtimeMetrics(map) {
+    const layouts = Array.isArray(map.layouts) ? map.layouts : [];
+    const recipes = layouts
+        .map(layout => isObject(layout) ? layout.runtime_chrome : null)
+        .filter(isObject);
+    let maxRegions = 0;
+    let maxStates = 0;
+    let populatedCanvas = false;
+    for (const recipe of recipes) {
+        const regions = Array.isArray(recipe.regions) ? recipe.regions : [];
+        const states = Array.isArray(recipe.states) ? recipe.states : [];
+        maxRegions = Math.max(maxRegions, regions.length);
+        maxStates = Math.max(maxStates, states.length);
+        populatedCanvas ||= regions.some(region => isObject(region)
+            && region.placement === 'canvas'
+            && (region.content_mode === 'populated' || region.media_expectation === 'required'));
+    }
+    return { count: recipes.length, maxRegions, maxStates, populatedCanvas };
+}
+
+function hasCanvasSceneAnatomy(map, appType) {
+    if (appType !== 'game') return false;
+    return objectValues(map.route_index).some(entry => isObject(entry)
+        && entry.method === 'CANVAS'
+        && isObject(entry.scene_anatomy)
+        && Array.isArray(entry.scene_anatomy.layers)
+        && entry.scene_anatomy.layers.length > 0);
+}
+
+function normalizedFramework(map, branding) {
+    const raw = map.framework || branding.framework || '';
+    return String(raw).trim().toLowerCase();
+}
+
+function isKnownWebFramework(framework) {
+    return Boolean(framework) && !['custom', 'unknown', 'none', '?'].includes(framework);
+}
+
+function classify(projectMap, branding = {}) {
+    if (!isObject(projectMap)) throw new Error('project map must be a JSON object');
+    if (!isObject(branding)) throw new Error('branding cache must be a JSON object');
+
+    const framework = normalizedFramework(projectMap, branding);
+    const rawAppType = typeof projectMap.app_type === 'string'
+        ? projectMap.app_type.trim().toLowerCase() : '';
+    // Older web caches predate app_type. Preserve their useful classification
+    // when a known web framework makes the intended surface unambiguous.
+    const appType = rawAppType || (isKnownWebFramework(framework) ? 'web' : '');
+    const layouts = Array.isArray(projectMap.layouts) ? projectMap.layouts.length : 0;
+    const surfaces = indexCount(projectMap);
+    const shell = shellMetrics(projectMap.app_shell);
+    const sourceFanout = maxSourceFanout(projectMap);
+    const runtime = runtimeMetrics(projectMap);
+    const fallbackCss = branding.compilation_method === 'fallback_synthesis'
+        || (isObject(projectMap.css_build) && projectMap.css_build.method === 'fallback_synthesis');
+
+    let score = 0;
+    let hardHigh = false;
+    let mediumFloor = false;
+    const reasons = [];
+    const add = (code, weight, evidence, options = {}) => {
+        score += weight;
+        reasons.push({ code, weight, evidence });
+        hardHigh ||= Boolean(options.hardHigh);
+        mediumFloor ||= Boolean(options.mediumFloor);
+    };
+
+    const complexRuntime = runtime.count > 0
+        && (runtime.maxRegions >= 4 || runtime.maxStates >= 3 || runtime.populatedCanvas);
+    if (complexRuntime) {
+        add('complex_runtime_surface', 7, {
+            recipe_count: runtime.count,
+            max_regions: runtime.maxRegions,
+            max_states: runtime.maxStates,
+            populated_canvas: runtime.populatedCanvas,
+        }, { hardHigh: true });
+    } else if (runtime.count > 0) {
+        add('runtime_mounted_ui', 3, { recipe_count: runtime.count }, { mediumFloor: true });
+    }
+
+    if (hasCanvasSceneAnatomy(projectMap, appType)) {
+        add('canvas_scene_anatomy', 7, { app_type: appType }, { hardHigh: true });
+    }
+
+    const richDesktop = appType === 'desktop'
+        && surfaces >= 8
+        && shell.persistentRegions >= 3;
+    if (richDesktop) {
+        add('rich_desktop_workspace', 7, {
+            surface_count: surfaces,
+            persistent_shell_regions: shell.persistentRegions,
+        }, { hardHigh: true });
+    } else if (SPECIALIZED_APP_TYPES.has(appType)) {
+        add('specialized_app_surface', 2, { app_type: appType }, { mediumFloor: true });
+    }
+
+    if (fallbackCss) {
+        add('fallback_css_synthesis', 2, {
+            compilation_method: 'fallback_synthesis',
+        }, { mediumFloor: true });
+    }
+
+    if (appType === 'web' && !isKnownWebFramework(framework)) {
+        add('custom_or_unknown_web_framework', 2, {
+            framework: framework || null,
+        }, { mediumFloor: true });
+    }
+
+    if (!VALID_APP_TYPES.has(appType)) {
+        add('unknown_project_surface', 3, {
+            app_type: rawAppType || null,
+            framework: framework || null,
+        }, { mediumFloor: true });
+    }
+
+    if (sourceFanout >= 8) {
+        add('deep_source_fanout', 2, { max_partials_expanded: sourceFanout });
+    }
+    if (layouts >= 5) add('multiple_layouts', 1, { layout_count: layouts });
+    if (surfaces >= 25) add('many_user_surfaces', 1, { surface_count: surfaces });
+    if (shell.navItems >= 8 || shell.persistentRegions >= 3) {
+        add('complex_persistent_shell', 1, {
+            nav_item_count: shell.navItems,
+            persistent_region_count: shell.persistentRegions,
+        });
+    }
+
+    let tier = score >= 7 ? 'high' : score >= 3 ? 'medium' : 'low';
+    if (hardHigh) tier = 'high';
+    else if (mediumFloor && tier === 'low') tier = 'medium';
+
+    if (reasons.length === 0) {
+        reasons.push({
+            code: 'straightforward_project_structure',
+            weight: 0,
+            evidence: { app_type: appType || null, framework: framework || null },
+        });
+    }
+
+    return {
+        schema_version: 1,
+        policy_version: POLICY_VERSION,
+        tier,
+        score,
+        source: 'heuristic',
+        reasons,
+    };
+}
+
+function readJson(file, label) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (error) {
+        throw new Error(`cannot read ${label} '${file}': ${error.message}`);
+    }
+}
+
+function writeJsonAtomic(file, value) {
+    const temp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.tmp`);
+    fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`);
+    fs.renameSync(temp, file);
+}
+
+function main() {
+    const [mapArg, brandingArg] = process.argv.slice(2);
+    if (!mapArg || !brandingArg) {
+        console.error('Usage: node recommend_model_tier.js <project_map.json> <branding.json>');
+        process.exit(1);
+    }
+    try {
+        const mapPath = path.resolve(mapArg);
+        const brandingPath = path.resolve(brandingArg);
+        const map = readJson(mapPath, 'project map');
+        const branding = readJson(brandingPath, 'branding cache');
+        map.mockup_model_recommendation = classify(map, branding);
+        writeJsonAtomic(mapPath, map);
+        const recommendation = map.mockup_model_recommendation;
+        const reasonCodes = recommendation.reasons.map(reason => reason.code).join(', ');
+        console.log(`mockup model tier: ${recommendation.tier} `
+            + `(score ${recommendation.score}; ${reasonCodes})`);
+    } catch (error) {
+        console.error(`ERROR: ${error.message}`);
+        process.exit(1);
+    }
+}
+
+if (require.main === module) main();
+
+module.exports = { classify, POLICY_VERSION };

package/engine/detect-project/scripts/resolve_route_chains.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * resolve_route_chains.js — fill route_index[*].render_chain deterministically.
+ *
+ * Why: on component-tree apps (React/Svelte/Next monorepos) the screen behind a
+ * route is 30–50 files deep, and the route index the model writes in STEP 4.6
+ * records only the primary view. Every article run then rediscovers the chain
+ * by grepping the repo (twenty: 270 bash reads, 16 min to the first image).
+ * The chain is static per commit, so it belongs in the cache.
+ *
+ * What: for every route_index entry with a resolvable `primary_view`, walk the
+ * include tree with the article skill's include census (shared module —
+ * ERB/ViewComponent, JSX/Vue/Svelte, Blade/Livewire, Django/Jinja/Twig, Razor,
+ * Phoenix/Angular, PHP requires) recursively, and write
+ *
+ *   render_chain: [{file, via, depth, kind}]      kind ∈ unconditional|overlay|conditional
+ *   render_chain_stats: {files, unresolved, max_depth, truncated}
+ *
+ * plus `partials_expanded` when the entry has none (the unconditional files, in
+ * discovery order — the field the article skill already consumes). Existing
+ * `partials_expanded` values are never overwritten. Unresolvable references
+ * (bare package imports, dynamic includes) are counted, not invented.
+ *
+ * Usage: resolve_route_chains.js <project_map.json> <project_dir> [--max-files N] [--max-depth N] [--json <report>]
+ * Exit 0 always (a cache enrichment must never fail a detect); prints a summary.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const census = require('./include_census.js');
+
+const MAX_FILES = 80;
+const MAX_DEPTH = 6;
+const SKIP_EXT_RE = /\.(?:json|ya?ml|arb|po|css|scss|sass|less|svg|png|jpe?g|gif|webp|ico|woff2?|ttf|md|txt|lock|d\.ts)$/i;
+const SKIP_PATH_RE = /(?:^|\/)(?:node_modules|vendor|dist|build|\.next|\.svelte-kit|test|tests|__tests__|spec|stories?)\//;
+
+function resolveChain(root, primaryView, maxFiles, maxDepth) {
+    const chain = [];
+    const seen = new Set([primaryView]);
+    let unresolved = 0, truncated = false, maxSeen = 0;
+    // BFS so the shallow, always-rendered pieces come first and a cap cuts the deep tail.
+    const queue = [{ file: primaryView, depth: 0, inherited: 'unconditional' }];
+    while (queue.length) {
+        const { file, depth, inherited } = queue.shift();
+        if (depth >= maxDepth) continue;
+        let refs;
+        try { refs = census.includeRefs(root, file); } catch { continue; }
+        for (const ref of refs) {
+            if (!ref.file) { unresolved++; continue; }
+            if (SKIP_EXT_RE.test(ref.file) || SKIP_PATH_RE.test(ref.file)) continue;
+            if (seen.has(ref.file)) continue;
+            if (chain.length >= maxFiles) { truncated = true; break; }
+            seen.add(ref.file);
+            // A piece inherits its parent's condition: an unconditional include of a
+            // conditional include is conditional for the screen.
+            let kind = ref.overlay ? 'overlay' : (ref.guarded ? 'conditional' : 'unconditional');
+            if (inherited === 'overlay' && kind === 'unconditional') kind = 'overlay';
+            if (inherited === 'conditional' && kind === 'unconditional') kind = 'conditional';
+            chain.push({ file: ref.file, via: file, depth: depth + 1, kind });
+            maxSeen = Math.max(maxSeen, depth + 1);
+            queue.push({ file: ref.file, depth: depth + 1, inherited: kind });
+        }
+        if (truncated) break;
+    }
+    return { chain, stats: { files: chain.length, unresolved, max_depth: maxSeen, truncated } };
+}
+
+function main() {
+    const args = process.argv.slice(2);
+    const positional = args.filter(a => !a.startsWith('--'));
+    const opt = (name, dflt) => { const i = args.indexOf(name); return i >= 0 && args[i + 1] ? args[i + 1] : dflt; };
+    const mapPath = positional[0];
+    const root = path.resolve(positional[1] || process.cwd());
+    const maxFiles = parseInt(opt('--max-files', MAX_FILES), 10) || MAX_FILES;
+    const maxDepth = parseInt(opt('--max-depth', MAX_DEPTH), 10) || MAX_DEPTH;
+    const reportPath = opt('--json', null);
+    if (!mapPath || !fs.existsSync(mapPath)) {
+        console.log('resolve_route_chains: usage: resolve_route_chains.js <project_map.json> <project_dir> [--max-files N] [--max-depth N] [--json report]');
+        return 0;
+    }
+    let pm;
+    try { pm = JSON.parse(fs.readFileSync(mapPath, 'utf8')); } catch (e) {
+        console.log(`resolve_route_chains: project_map.json unreadable (${e.message}) — nothing changed`);
+        return 0;
+    }
+    const ri = pm.route_index;
+    if (!ri || typeof ri !== 'object' || Array.isArray(ri)) {
+        console.log('resolve_route_chains: no route_index object — nothing to resolve');
+        return 0;
+    }
+    const report = { resolved: 0, skipped: 0, total_files: 0, routes: {}, layouts: {} };
+    const readable = p => { try { return !!p && fs.statSync(path.join(root, p)).isFile(); } catch { return false; } };
+    for (const [key, entry] of Object.entries(ri)) {
+        if (!entry || typeof entry !== 'object') { report.skipped++; continue; }
+        let pv = typeof entry.primary_view === 'string' ? entry.primary_view.replace(/^\/+/, '') : null;
+        if (!pv && typeof entry.controller === 'string' && /^[\w/]+#\w+$/.test(entry.controller)) {
+            // Rails convention: `things#index` renders app/views/things/index.html.erb
+            // unless the action says otherwise; recorded as the derivation it is.
+            const [ctrl, action] = entry.controller.split('#');
+            for (const ext of ['.html.erb', '.html.haml', '.html.slim']) {
+                const cand = `app/views/${ctrl}/${action}${ext}`;
+                if (readable(cand)) { pv = cand; entry.primary_view = cand; entry.primary_view_source = 'convention'; break; }
+            }
+        }
+        if (!readable(pv)) { report.skipped++; continue; }
+        const { chain, stats } = resolveChain(root, pv, maxFiles, maxDepth);
+        entry.render_chain = chain;
+        entry.render_chain_stats = stats;
+        if (!Array.isArray(entry.partials_expanded) || !entry.partials_expanded.length) {
+            entry.partials_expanded = chain.filter(c => c.kind === 'unconditional').map(c => c.file);
+        }
+        report.routes[key] = { primary_view: pv, ...stats };
+        report.resolved++; report.total_files += stats.files;
+    }
+    // The recorded layouts are the shell: resolve their chains once too, so a run
+    // opens the shell's real files instead of re-deriving them from `chrome`.
+    if (Array.isArray(pm.layouts)) for (const lay of pm.layouts) {
+        const lp = lay && typeof lay.path === 'string' ? lay.path.replace(/^\/+/, '') : null;
+        if (!readable(lp)) continue;
+        const { chain, stats } = resolveChain(root, lp, maxFiles, maxDepth);
+        lay.render_chain = chain; lay.render_chain_stats = stats;
+        report.layouts[lay.name || lp] = { path: lp, ...stats };
+    }
+    pm.route_chain_resolver = { version: 1, generated_at: new Date().toISOString(), max_files: maxFiles, max_depth: maxDepth };
+    fs.writeFileSync(mapPath, JSON.stringify(pm, null, 2) + '\n');
+    if (reportPath) fs.writeFileSync(reportPath, JSON.stringify(report, null, 2) + '\n');
+    const deep = Object.entries(report.routes).filter(([, s]) => s.files >= 10).length;
+    const layN = Object.keys(report.layouts).length;
+    console.log(`resolve_route_chains: ${report.resolved} route(s) resolved (${report.total_files} chain files, ${deep} route(s) with ≥10), ${report.skipped} skipped (no readable primary_view); ${layN} layout chain(s)`);
+    return 0;
+}
+
+if (require.main === module) process.exitCode = main();
+module.exports = { resolveChain };

package/engine/detect-project/scripts/run_css_build.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# run_css_build.sh — run an LLM-supplied CSS build command with a timeout, then
+# validate the expected output CSS was produced. detect-project STEP 3 uses this to
+# run a project-specific compile it discovered — a Tailwind v4 CLI invocation with
+# `--content` globs, a project's own `mix assets.build` / `npm run build:css`, etc.
+# — without each run reinventing timeout + validation. The mechanics are
+# deterministic; the LLM supplies the command (and templates the output path into it).
+#
+# Usage:  run_css_build.sh <project_dir> <output_css> <timeout_secs> -- <command...>
+#         The <command...> is expected to write CSS to <output_css> (e.g. `... -o <output_css>`).
+# Exit:   0 if <output_css> exists and is non-trivial (>2KB); 1 otherwise.
+
+set -u
+
+PROJECT_DIR="$1"; OUTPUT_CSS="$2"; TIMEOUT="${3:-180}"; shift 3
+[ "${1:-}" = "--" ] && shift
+
+_timeout() {
+    if command -v gtimeout &>/dev/null; then gtimeout "$@";
+    elif command -v timeout &>/dev/null; then timeout "$@";
+    else shift; "$@"; fi
+}
+
+if [ ! -d "$PROJECT_DIR" ]; then echo "  run_css_build: project_dir not found: $PROJECT_DIR" >&2; exit 1; fi
+if [ "$#" -eq 0 ]; then echo "  run_css_build: no command given" >&2; exit 1; fi
+
+echo "  run_css_build: (cwd=$PROJECT_DIR, timeout ${TIMEOUT}s) $*" >&2
+( cd "$PROJECT_DIR" && _timeout "$TIMEOUT" "$@" ) >/tmp/css_build.log 2>&1
+rc=$?
+if [ "$rc" -ne 0 ]; then
+    echo "  build command exited $rc" >&2
+    tail -12 /tmp/css_build.log >&2
+fi
+
+if [ -f "$OUTPUT_CSS" ] && [ "$(wc -c < "$OUTPUT_CSS" 2>/dev/null || echo 0)" -gt 2000 ]; then
+    echo "  build OK: $OUTPUT_CSS ($(wc -c < "$OUTPUT_CSS") bytes)" >&2
+    exit 0
+fi
+echo "  build produced no usable CSS at $OUTPUT_CSS" >&2
+exit 1