@supportpages.io/wtfm 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * sanitize_css.js — Strip un-compilable framework directives from a CSS file.
+ *
+ * When we fall back to inlining source CSS (rather than running the project's
+ * build pipeline), compile-time directives like @tailwind, @apply, @theme,
+ * @plugin, @custom-variant, @config, @source, @utility, @layer, and
+ * @import "tailwindcss" leak into the output. Browsers can't parse those —
+ * they silently break styling for everything after the first malformed rule.
+ * This sanitizer strips them in place.
+ *
+ * Usage: node sanitize_css.js <css_file>
+ */
+
+const fs = require('fs');
+
+const BAD_DIRECTIVES = [
+    /^@tailwind\b[^;]*;?\s*$/,
+    /^@theme\b/,
+    /^@plugin\b[^;]*;?\s*$/,
+    /^@custom-variant\b[^;]*;?\s*$/,
+    /^@apply\b[^;]*;?\s*$/,
+    /^@config\b[^;]*;?\s*$/,
+    /^@source\b[^;]*;?\s*$/,
+    /^@utility\b/,
+    /^@import\s+["']tailwindcss[^;]*;?\s*$/,
+];
+
+function count(text, ch) {
+    return text.split(ch).length - 1;
+}
+
+/** Return { cleaned, removed }. */
+function sanitize(css) {
+    const cleaned = [];
+    let removed = 0;
+    let skipDepth = 0; // brace depth for multi-line blocks like @theme { ... }
+
+    for (const line of css.split('\n')) {
+        const stripped = line.trim();
+
+        if (skipDepth > 0) {
+            skipDepth += count(stripped, '{') - count(stripped, '}');
+            removed += 1;
+            continue;
+        }
+
+        if (BAD_DIRECTIVES.some(pattern => pattern.test(stripped))) {
+            removed += 1;
+            if (stripped.includes('{')) skipDepth = count(stripped, '{') - count(stripped, '}');
+            continue;
+        }
+
+        cleaned.push(line);
+    }
+
+    return { cleaned: cleaned.join('\n'), removed };
+}
+
+function main() {
+    if (process.argv.length !== 3) {
+        process.stderr.write('Usage: sanitize_css.js <css_file>\n');
+        process.exit(1);
+    }
+
+    const cssFile = process.argv[2];
+    const css = fs.readFileSync(cssFile, 'utf8');
+    const { cleaned, removed } = sanitize(css);
+
+    if (removed > 0) {
+        fs.writeFileSync(cssFile, cleaned);
+        process.stderr.write(`Sanitized ${cssFile}: removed ${removed} directive line(s) ` +
+            `(${[...css].length} → ${[...cleaned].length} bytes)\n`);
+    } else {
+        process.stderr.write('CSS clean — no directives to remove\n');
+    }
+}
+
+if (require.main === module) main();
+
+module.exports = { sanitize };

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * classify_surface.sh — surface vs code-only repositories: a full-stack Rails
+ * app and an Express app with views are web; Rails API mode, an Express JSON
+ * API and a Go library are none (mailer templates and test fixtures don't
+ * count as an interface); a cobra CLI stays terminal and a React Native app
+ * mobile; a frontend framework dependency alone is enough for web.
+ */
+'use strict';
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const SCRIPT = path.join(__dirname, 'classify_surface.sh');
+
+function write(root, rel, text = '') { const p = path.join(root, rel); fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, text); }
+function classify(files) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'surface-'));
+    for (const [rel, text] of Object.entries(files)) write(root, rel, text);
+    const out = execFileSync('bash', [SCRIPT, root], { encoding: 'utf8' });
+    fs.rmSync(root, { recursive: true, force: true });
+    return Object.fromEntries(out.trim().split('\n').map(line => line.split(/=(.*)/s).slice(0, 2)));
+}
+const RAILS = { Gemfile: "gem 'rails'\n", 'config/routes.rb': 'Rails.application.routes.draw do\nend\n' };
+
+// Full-stack Rails: views are an interface.
+assert.strictEqual(classify({
+    ...RAILS,
+    'app/views/layouts/application.html.erb': '<html></html>',
+    'app/views/plans/index.html.erb': '<h1>Plans</h1>',
+    'app/assets/stylesheets/application.css': 'body {}',
+}).surface, 'web');
+
+// Rails API mode, even with mailer templates.
+let r = classify({
+    ...RAILS,
+    'config/application.rb': 'module App\n  class Application < Rails::Application\n    config.api_only = true\n  end\nend\n',
+    'app/views/user_mailer/welcome.html.erb': '<p>Hi</p>',
+});
+assert.strictEqual(r.surface, 'none');
+assert.strictEqual(r.source, 'auto');
+assert.match(r.reason, /api_only/);
+
+// Rails without api_only whose only templates are mailers and test fixtures: no interface.
+assert.strictEqual(classify({
+    ...RAILS,
+    'app/views/user_mailer/welcome.html.erb': '<p>Hi</p>',
+    'app/views/user_mailer/reset.html.erb': '<p>Reset</p>',
+    'test/fixtures/files/page.html': '<p>x</p>',
+    'spec/support/page.html': '<p>x</p>',
+}).surface, 'none');
+
+// Express JSON API vs Express app with views.
+const EXPRESS = { 'package.json': JSON.stringify({ dependencies: { express: '^4' } }), 'src/server.js': 'app.get("/api", ...)' };
+r = classify(EXPRESS);
+assert.strictEqual(r.surface, 'none');
+assert.strictEqual(r.source, 'auto');
+assert.strictEqual(classify({ ...EXPRESS, 'views/index.ejs': '<h1/>', 'views/login.ejs': '<form/>', 'public/app.css': 'a{}' }).surface, 'web');
+
+// A frontend framework dependency alone is an interface (templates may live in .js).
+assert.strictEqual(classify({ 'package.json': JSON.stringify({ dependencies: { vue: '^3' } }) }).surface, 'web');
+
+// Go library: nothing to classify, nothing to depict.
+r = classify({ 'go.mod': 'module example.com/lib\n', 'lib.go': 'package lib\n' });
+assert.strictEqual(r.surface, 'none');
+assert.strictEqual(r.source, 'default');
+
+// Non-web verdicts are interfaces as they stand.
+assert.strictEqual(classify({ 'go.mod': 'module example.com/cli\n\nrequire github.com/spf13/cobra v1.8.0\n', 'main.go': 'package main\n' }).surface, 'terminal');
+assert.strictEqual(classify({ 'package.json': JSON.stringify({ dependencies: { 'react-native': '0.74.0' } }) }).surface, 'mobile');
+
+// A Node CLI with no CLI framework (the SupportPages Writer shape): a bin, an
+// MCP server dependency and vendored engine templates/styles is terminal.
+r = classify({
+    'package.json': JSON.stringify({ bin: { writer: 'scripts/cli.mjs' }, dependencies: { '@modelcontextprotocol/sdk': '^1', '@clack/prompts': '1.6.0' } }),
+    'scripts/cli.mjs': '#!/usr/bin/env node',
+    'engine/detect-project/assets/tailwind-fallback.css': 'a{}',
+    'engine/detect-project/assets/webtui.css': 'b{}',
+    'engine/generate-illustrated-article/templates/page.html': '<html/>',
+    'engine/generate-illustrated-article/templates/step.html': '<html/>',
+    '.rtfm/branding.css': 'x{}', '.rtfm/previews/a.html': '<p/>', 'output/articles/x/block_a.html': '<p/>', 'output/articles/x/branding.css': 'y{}',
+});
+assert.strictEqual(r.surface, 'terminal');
+assert.match(r.reason, /bin/);
+// A bin beside a frontend framework is still a web app (e.g. a dev-server CLI).
+assert.strictEqual(classify({ 'package.json': JSON.stringify({ bin: { app: 'cli.js' }, dependencies: { 'react-dom': '^18' } }) }).surface, 'web');
+// A Node web app with its own views that also ships a bin stays web.
+assert.strictEqual(classify({ ...EXPRESS, 'package.json': JSON.stringify({ bin: { app: 'bin/app' }, dependencies: { express: '^4' } }),
+    'views/index.ejs': '<h1/>', 'views/login.ejs': '<form/>', 'public/app.css': 'a{}' }).surface, 'web');
+// Vendored assets alone never make a server a web app.
+assert.strictEqual(classify({ ...EXPRESS, 'engine/a.css': 'a{}', 'engine/b.css': 'b{}', 'third_party/c.html': '<p/>' }).surface, 'none');
+
+// A missing directory is none, not an error.
+assert.strictEqual(execFileSync('bash', [SCRIPT, '/nonexistent/dir'], { encoding: 'utf8' }).split('\n')[0], 'surface=none');
+
+// classify_workspace.js: every checkout under a root, sorted, non-repos skipped.
+const { classifyWorkspace } = require('./classify_workspace.js');
+const ws = fs.mkdtempSync(path.join(os.tmpdir(), 'surface-ws-'));
+write(ws, 'acme-web/.git/HEAD'); write(ws, 'acme-web/package.json', JSON.stringify({ dependencies: { 'react-dom': '^18' } }));
+write(ws, 'acme-api/.git/HEAD'); write(ws, 'acme-api/package.json', JSON.stringify({ dependencies: { express: '^4' } }));
+write(ws, 'notes/readme.md', 'not a repo');
+assert.deepStrictEqual(classifyWorkspace(ws).map(r => [r.directory, r.surface]), [['acme-api', 'none'], ['acme-web', 'web']]);
+assert.deepStrictEqual(classifyWorkspace(path.join(ws, 'missing')), []);
+fs.rmSync(ws, { recursive: true, force: true });
+
+console.log('classify_surface tests passed');

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

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+'use strict';
+
+// Tests for the Node helpers that replaced the Python scripts and jq filters.
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { sanitize } = require('./sanitize_css.js');
+const { overrideCss } = require('./theme_overrides.js');
+const { merge } = require('./merge_json.js');
+const { check } = require('./check_project_map.js');
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'detect-helpers-'));
+const run = (script, args) => spawnSync(process.execPath, [path.join(__dirname, script), ...args], { encoding: 'utf8' });
+const write = (name, value) => {
+    const file = path.join(tmp, name);
+    fs.writeFileSync(file, typeof value === 'string' ? value : JSON.stringify(value));
+    return file;
+};
+
+// sanitize_css: directives and their blocks go, everything else stays.
+{
+    const { cleaned, removed } = sanitize('@import "tailwindcss";\n@theme {\n  --x: 1;\n  inner { }\n}\n.keep { a: b; }\n  @apply foo;\n@plugin "x";\n');
+    assert.strictEqual(cleaned, '.keep { a: b; }\n');
+    assert.strictEqual(removed, 7);
+}
+
+// theme_overrides: expected output captured from the Python implementation.
+{
+    const detect = {
+        theme_overrides: {
+            colors: { primary: '#3366ff', secondary: '#ff6600', dark: 'null', x: '' },
+            custom_colors: { brand_blue: '#123456', empty: '' },
+            fonts: { body: 'Inter, sans-serif', heading: 'Poppins' },
+            border_radius: '6px',
+            extra_css: '@tailwind base;\n.foo { color: red; }\n  @apply p-4;\n@layer x {\n.bar{}\n',
+        },
+    };
+    assert.strictEqual(overrideCss(detect, 'bootstrap'), '\n/* Theme overrides from project variables */\n:root {\n  --bs-primary: #3366ff;\n  --bs-primary-rgb: 51, 102, 255;\n  --bs-secondary: #ff6600;\n  --bs-secondary-rgb: 255, 102, 0;\n  --bs-body-font-family: Inter, sans-serif;\n  --bs-heading-font-family: Poppins;\n  --bs-border-radius: 6px;\n}\n.text-brand-blue { color: #123456 !important; }\n.bg-brand-blue { background-color: #123456 !important; }\n.btn-primary { background-color: #3366ff; border-color: #3366ff; }\n.btn-primary:hover { background-color: #3366ff; border-color: #3366ff; opacity: 0.9; }\n.btn-outline-primary { color: #3366ff; border-color: #3366ff; }\n.btn-outline-primary:hover { background-color: #3366ff; border-color: #3366ff; color: #fff; }\na { color: #3366ff; }\n.text-primary { color: #3366ff !important; }\n.bg-primary { background-color: #3366ff !important; }\n.btn-secondary { background-color: #ff6600; border-color: #ff6600; }\n\n/* Extra project overrides */\n.foo { color: red; }\n.bar{}\n');
+    assert.strictEqual(overrideCss(detect, 'tailwind'), '\n/* Theme overrides from project variables */\n:root {\n  --color-primary: #3366ff;\n  --color-secondary: #ff6600;\n  font-family: Inter, sans-serif;\n  --font-heading: Poppins;\n  --radius: 6px;\n}\nh1, h2, h3, h4, h5, h6 { font-family: Poppins; }\n.text-primary { color: #3366ff; }\n.bg-primary { background-color: #3366ff; }\n.text-secondary { color: #ff6600; }\n.bg-secondary { background-color: #ff6600; }\n.text-brand-blue { color: #123456; }\n.bg-brand-blue { background-color: #123456; }\n\n/* Extra project overrides */\n.foo { color: red; }\n.bar{}\n');
+    // Skill-style detection maps default_colors/scss_vars when no theme colours exist.
+    const skillStyle = overrideCss({ default_colors: { primary: '#0ea5e9', accent: '#f43f5e' }, scss_vars: { 'body-color': '#111' } }, 'custom');
+    assert(skillStyle.includes('  --color-secondary: #f43f5e;'));
+    assert(skillStyle.includes('  --color-body_color: #111;'));
+    // An invalid hex colour fails the run, as the caller treats that as "no overrides".
+    assert.throws(() => overrideCss({ theme_overrides: { colors: { primary: '#zz0000' } } }, 'bootstrap'));
+}
+
+// json_get: jq-compatible reads used by the SKILL.md summaries.
+{
+    const file = write('map.json', {
+        framework: 'bootstrap', has_tui: false, css_files: ['a.css', null, 'b.css'],
+        route_index: { a: { method: 'CANVAS' }, b: { method: 'GET' }, c: { method: 'CANVAS' } },
+        mockup_model_recommendation: { tier: 'medium', reasons: [{ code: 'r1' }, { code: 'r2' }] },
+    });
+    const out = args => run('json_get.js', args).stdout.trim();
+    assert.strictEqual(out([file, 'framework', 'none']), 'bootstrap');
+    assert.strictEqual(out([file, 'missing', 'none']), 'none');
+    assert.strictEqual(out([file, 'missing']), 'null');
+    assert.strictEqual(out([file, 'has_tui', 'false']), 'false');
+    assert.strictEqual(out([file, 'css_files[]', '']), 'a.css\nb.css');
+    assert.strictEqual(out(['--length', file, 'route_index']), '3');
+    assert.strictEqual(out(['--length', file, 'missing']), '0');
+    assert.strictEqual(out(['--join', ', ', file, 'mockup_model_recommendation.reasons[].code']), 'r1, r2');
+    assert.strictEqual(out(['--count', file, 'route_index[]', 'method=CANVAS']), '2');
+    assert.strictEqual(run('json_get.js', ['--exists', file, 'route_index.a']).status, 0);
+    assert.strictEqual(run('json_get.js', ['--exists', file, 'route_index.z']).status, 1);
+    assert.strictEqual(run('json_get.js', ['--valid', file]).status, 0);
+    assert.strictEqual(run('json_get.js', ['--valid', write('bad.json', '{bad')]).status, 1);
+}
+
+// write_branding: web merges the detect output; patch modes keep existing fields.
+{
+    const brandDir = fs.mkdtempSync(path.join(tmp, 'brand-'));
+    fs.writeFileSync(path.join(brandDir, 'branding-detect.json'), JSON.stringify({ framework: 'tailwind', google_fonts: ['x'] }));
+    assert.strictEqual(run('write_branding.js', ['web', brandDir, 'tailwind_v4', ' 1234']).status, 0);
+    const web = JSON.parse(fs.readFileSync(path.join(brandDir, 'branding.json'), 'utf8'));
+    assert.deepStrictEqual({ ...web, generated_at: undefined }, {
+        framework: 'tailwind', google_fonts: ['x'], compiled_css_path: 'branding.css',
+        compilation_method: 'tailwind_v4', compiled_css_bytes: 1234, generated_at: undefined,
+    });
+    assert.match(web.generated_at, /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$/);
+
+    const branding = path.join(brandDir, 'branding.json');
+    assert.strictEqual(run('write_branding.js', ['game', branding, 'phaser', '320', '180', '1280', '720', '55']).status, 0);
+    const game = JSON.parse(fs.readFileSync(branding, 'utf8'));
+    assert.strictEqual(game.framework, 'tailwind');
+    assert.deepStrictEqual(game.canvas_size, { width: 320, height: 180 });
+    assert.strictEqual(game.compiled_css_bytes, 55);
+    assert.strictEqual(run('write_branding.js', ['game', branding, 'phaser', '320', 'abc', '1', '1', '1']).status, 1);
+    assert.strictEqual(run('write_branding.js', ['win32', branding]).status, 2);
+}
+
+// merge_json: objects merge, arrays replace, omitted keys survive.
+assert.deepStrictEqual(
+    merge({ app_type: 'web', route_index: { a: { x: 1 } }, layouts: [1] }, { route_index: { b: { y: 2 } }, layouts: [2, 3] }),
+    { app_type: 'web', route_index: { a: { x: 1 }, b: { y: 2 } }, layouts: [2, 3] },
+);
+
+// check_project_map: the gates that replaced the jq validation.
+{
+    const state = id => ({
+        id, kind: 'overview', topic_tags: ['t'], instructional_priority: 'orientation', canvas_presentation: 'full',
+        screenshot_required: true, visible_regions: ['top'], required_regions: [], required_strings: [], source_files: [],
+    });
+    const web = {
+        app_type: 'web', app_type_source: 'hint', schema_version: 5, dir_map: {},
+        layouts: [{
+            name: 'app',
+            runtime_chrome: {
+                source_kind: 'repo', source_files: [],
+                regions: [{ id: 'top', placement: 'top', required: true, appearance: 'bar', required_strings: [], source_files: [], items: [{ id: 'i', kind: 'k', description: 'd', required_strings: [] }] }],
+                states: [state('a'), state('b'), state('c')],
+            },
+        }],
+    };
+    assert.deepStrictEqual(check('web', web), []);
+    const tooMany = structuredClone(web);
+    tooMany.layouts[0].runtime_chrome.states.push(state('d'));
+    assert.match(check('web', tooMany).join('\n'), /at most 3 states/);
+    const badPlacement = structuredClone(web);
+    badPlacement.layouts[0].runtime_chrome.regions[0].placement = 'middle';
+    assert.match(check('web', badPlacement).join('\n'), /placement/);
+
+    const codebase = fs.mkdtempSync(path.join(tmp, 'rails-'));
+    fs.mkdirSync(path.join(codebase, 'config'));
+    fs.writeFileSync(path.join(codebase, 'config', 'routes.rb'), '');
+    assert.match(check('web', web, codebase).join('\n'), /route_index/);
+
+    const game = { app_type: 'game', app_type_source: 'hint', game_metadata: {}, app_shell: null, route_index: { play: { method: 'CANVAS', scene_anatomy: { layers: ['bg'] } } } };
+    assert.deepStrictEqual(check('game', game), []);
+    assert.match(check('game', { ...game, route_index: { play: { method: 'CANVAS', scene_anatomy: { layers: [] } } } }).join('\n'), /layers/);
+    assert.match(check('mobile', { app_type: 'web', app_type_source: 'x' }).join('\n'), /app_type must be "mobile"/);
+    assert.strictEqual(run('check_project_map.js', ['game', write('game.json', game)]).status, 0);
+}
+
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log('node helper tests passed');

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

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { classify, POLICY_VERSION } = require('./recommend_model_tier.js');
+
+const classifier = path.join(__dirname, 'recommend_model_tier.js');
+const webBranding = { framework: 'rails', compilation_method: 'source_compile' };
+
+function shell(regionCount = 0, navItems = 0) {
+    const out = { nav_items: Array.from({ length: navItems }, (_, index) => ({ label: `Item ${index}` })) };
+    const keys = ['top_bar', 'titlebar', 'menu_bar', 'global_sidebar', 'primary_sidebar', 'secondary_sidebar'];
+    keys.slice(0, regionCount).forEach(key => { out[key] = `${key} definition`; });
+    return out;
+}
+
+function routes(count, fanout = 0) {
+    return Object.fromEntries(Array.from({ length: count }, (_, index) => [
+        `route-${index}`,
+        { path: `/route-${index}`, partials_expanded: Array.from({ length: fanout }, (__, part) => `part-${part}`) },
+    ]));
+}
+
+function expectTier(name, map, branding, tier) {
+    const recommendation = classify(map, branding);
+    assert.strictEqual(recommendation.tier, tier, `${name}: ${JSON.stringify(recommendation)}`);
+    assert.strictEqual(recommendation.policy_version, POLICY_VERSION);
+    assert(!JSON.stringify(recommendation).match(/claude|gpt|codex|cursor|opus|sonnet/i),
+        `${name}: recommendation leaked a concrete model or harness`);
+    return recommendation;
+}
+
+// Representative project shapes.
+expectTier('server-rendered web app', {
+    app_type: 'web', framework: 'rails', layouts: Array.from({ length: 7 }, () => ({})),
+    route_index: routes(6), app_shell: null,
+}, webBranding, 'low');
+
+expectTier('WordPress Site Editor runtime', {
+    app_type: 'web', framework: 'custom', route_index: routes(29), app_shell: shell(2, 11),
+    layouts: [{ runtime_chrome: {
+        regions: Array.from({ length: 11 }, (_, index) => ({ placement: index === 2 ? 'canvas' : 'left' })),
+        states: Array.from({ length: 8 }, () => ({})),
+    }}],
+}, { framework: 'custom', compilation_method: 'source_compile' }, 'high');
+
+expectTier('desktop database workspace', {
+    app_type: 'desktop', framework: 'vue', layouts: [], route_index: routes(14), app_shell: shell(6, 3),
+}, { framework: 'vue', compilation_method: 'source_compile' }, 'high');
+
+for (const [name, map] of [
+    ['Immich-style mobile app', { app_type: 'mobile', framework: 'mobile', screen_index: routes(20), app_shell: shell(1, 4) }],
+    ['Notepad++-style Win32 app', { app_type: 'win32', framework: 'win32', dialog_index: routes(20), app_shell: shell(1, 13) }],
+    ['TGT-style terminal app', { app_type: 'terminal', framework: 'terminal', command_index: routes(8), app_shell: null }],
+    ['Transmission-style macOS app', { app_type: 'macos', framework: 'macos', view_index: routes(12), app_shell: shell(2, 0) }],
+]) expectTier(name, map, { framework: map.framework }, 'medium');
+
+expectTier('canvas game', {
+    app_type: 'game', framework: 'custom', layouts: [], route_index: {
+        play: { method: 'CANVAS', scene_anatomy: { layers: ['background', 'player'] } },
+    },
+}, { framework: 'custom' }, 'high');
+
+expectTier('simple runtime mount', {
+    app_type: 'web', framework: 'rails', layouts: [{ runtime_chrome: { regions: [{}], states: [{}] } }],
+    route_index: routes(3),
+}, webBranding, 'medium');
+
+expectTier('fallback CSS floor', {
+    app_type: 'web', framework: 'tailwind', layouts: [], route_index: routes(3),
+}, { framework: 'tailwind', compilation_method: 'fallback_synthesis' }, 'medium');
+
+expectTier('unknown metadata is conservative', { layouts: [], route_index: {} }, {}, 'medium');
+
+const boundaryMedium = expectTier('medium score boundary', {
+    app_type: 'web', framework: 'rails', layouts: Array.from({ length: 5 }, () => ({})),
+    route_index: routes(25), app_shell: shell(0, 8),
+}, webBranding, 'medium');
+assert.strictEqual(boundaryMedium.score, 3);
+
+expectTier('high score boundary', {
+    app_type: 'web', framework: 'custom', layouts: Array.from({ length: 5 }, () => ({})),
+    route_index: routes(25, 8), app_shell: shell(0, 8),
+}, { framework: 'custom' }, 'high');
+
+assert.throws(() => classify([], {}), /project map must be a JSON object/);
+assert.throws(() => classify({}, []), /branding cache must be a JSON object/);
+
+// Exercise the actual CLI, atomic write, replacement, and byte-stable rerun.
+{
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rtfm-model-tier-'));
+    const mapPath = path.join(root, 'project_map.json');
+    const brandingPath = path.join(root, 'branding.json');
+    fs.writeFileSync(mapPath, JSON.stringify({
+        app_type: 'web', framework: 'rails', layouts: [], route_index: routes(2),
+        mockup_model_recommendation: { tier: 'stale', reasons: ['stale'] },
+    }, null, 2));
+    fs.writeFileSync(brandingPath, JSON.stringify(webBranding));
+    let proc = spawnSync(process.execPath, [classifier, mapPath, brandingPath], { encoding: 'utf8' });
+    assert.strictEqual(proc.status, 0, proc.stderr);
+    const first = fs.readFileSync(mapPath, 'utf8');
+    const parsed = JSON.parse(first);
+    assert.strictEqual(parsed.mockup_model_recommendation.tier, 'low');
+    assert(!JSON.stringify(parsed.mockup_model_recommendation).includes('stale'));
+    proc = spawnSync(process.execPath, [classifier, mapPath, brandingPath], { encoding: 'utf8' });
+    assert.strictEqual(proc.status, 0, proc.stderr);
+    assert.strictEqual(fs.readFileSync(mapPath, 'utf8'), first);
+    fs.writeFileSync(mapPath, '{ malformed json');
+    proc = spawnSync(process.execPath, [classifier, mapPath, brandingPath], { encoding: 'utf8' });
+    assert.notStrictEqual(proc.status, 0);
+    assert.match(proc.stderr, /cannot read project map/);
+    fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log('model tier recommendation tests passed');

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

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * resolve_route_chains.js + the census resolver on a synthetic monorepo:
+ * tsconfig `paths` (JSONC, alias keys containing "/*"), a workspace package
+ * with `exports` + a barrel, a locally-defined sub-component, SvelteKit `$lib`,
+ * an Angular selector, the Rails controller→view convention, layout chains,
+ * kind inheritance, `partials_expanded` fill-without-overwrite, exit 0 on
+ * missing input.
+ */
+'use strict';
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const SCRIPT = path.join(__dirname, 'resolve_route_chains.js');
+const census = require('./include_census.js');
+
+function write(root, rel, text) { const p = path.join(root, rel); fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, text); }
+function run(mapPath, root, extra = []) {
+    return execFileSync('node', [SCRIPT, mapPath, root, ...extra], { encoding: 'utf8' });
+}
+
+function fixture() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rrc-'));
+    write(root, 'package.json', JSON.stringify({ name: 'mono', workspaces: ['apps/*', 'packages/*'] }));
+    // apps/web — JSONC tsconfig whose alias key carries "/*" (a regex stripper would eat it)
+    write(root, 'apps/web/package.json', JSON.stringify({ name: '@mono/web' }));
+    write(root, 'apps/web/tsconfig.json', `{
+  /* base */
+  "compilerOptions": {
+    "baseUrl": ".", // comment after
+    "paths": { "~/*": ["modules/*"], "@ui/*": ["../../packages/ui/src/*"] },
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+}`);
+    write(root, 'apps/web/app/things/page.tsx', `import Shell from "~/shell/Shell";
+import { DataTable, StatusBadge } from "@mono/ui/components/table";
+import { HeaderBar } from "@ui/HeaderBar";
+import { FancyModal } from "@mono/ui/components/modal";
+const LocalRow = () => <tr><td>local</td></tr>;
+export default function Page({ admin }) {
+  return (<Shell>
+    <HeaderBar />
+    <DataTable><LocalRow /><StatusBadge /></DataTable>
+    {admin && <AdminPanel />}
+    <FancyModal />
+  </Shell>);
+}
+import { AdminPanel } from "~/admin/AdminPanel";
+`);
+    write(root, 'apps/web/modules/shell/Shell.tsx', `import { SideNav } from "~/shell/SideNav";
+export default function Shell({ children }) { return <div><SideNav /><main>{children}</main></div>; }`);
+    write(root, 'apps/web/modules/shell/SideNav.tsx', `export const SideNav = () => <nav><a>Things</a></nav>;`);
+    write(root, 'apps/web/modules/admin/AdminPanel.tsx', `import { DangerZone } from "~/admin/DangerZone";
+export const AdminPanel = () => <section><DangerZone /></section>;`);
+    write(root, 'apps/web/modules/admin/DangerZone.tsx', `export const DangerZone = () => <p>danger</p>;`);
+    write(root, 'apps/web/app/layout.tsx', `import Shell from "~/shell/Shell";
+export default function L({ children }) { return <Shell>{children}</Shell>; }`);
+    // packages/ui — workspace package with exports + barrel
+    write(root, 'packages/ui/package.json', JSON.stringify({ name: '@mono/ui', exports: { './components/table': './components/table/index.ts', './components/modal': './components/modal/index.ts' } }));
+    write(root, 'packages/ui/components/table/index.ts', `export { DataTable } from "./DataTable";\nexport * from "./StatusBadge";`);
+    write(root, 'packages/ui/components/table/DataTable.tsx', `export const DataTable = ({ children }) => <table>{children}</table>;`);
+    write(root, 'packages/ui/components/table/StatusBadge.tsx', `export const StatusBadge = () => <span/>;`);
+    write(root, 'packages/ui/components/modal/index.ts', `export { FancyModal } from "./FancyModal";`);
+    write(root, 'packages/ui/components/modal/FancyModal.tsx', `import { ModalFooter } from "./ModalFooter";\nexport const FancyModal = () => <div role="dialog"><ModalFooter/></div>;`);
+    write(root, 'packages/ui/components/modal/ModalFooter.tsx', `export const ModalFooter = () => <footer/>;`);
+    write(root, 'packages/ui/src/HeaderBar.tsx', `export const HeaderBar = () => <header>Things</header>;`);
+    // apps/kit — SvelteKit with $lib
+    write(root, 'apps/kit/package.json', JSON.stringify({ name: '@mono/kit' }));
+    write(root, 'apps/kit/src/routes/albums/+page.svelte', `<script>\n  import Albums from '$lib/components/Albums.svelte';\n</script>\n<Albums />`);
+    write(root, 'apps/kit/src/lib/components/Albums.svelte', `<ul><li>Album</li></ul>`);
+    // apps/ng — Angular selectors
+    write(root, 'apps/ng/package.json', JSON.stringify({ name: '@mono/ng' }));
+    write(root, 'apps/ng/src/main.ts', ``);
+    write(root, 'apps/ng/src/app/dash/dash.component.html', `<pngx-page-header></pngx-page-header>\n<ng-container></ng-container>\n<pngx-stats-widget />`);
+    write(root, 'apps/ng/src/app/common/page-header/page-header.component.ts', `@Component({ selector: 'pngx-page-header', templateUrl: './page-header.component.html' })\nexport class PageHeaderComponent {}`);
+    write(root, 'apps/ng/src/app/common/page-header/page-header.component.html', `<h1>Header</h1>`);
+    write(root, 'apps/ng/src/app/dash/widgets/stats/stats.component.ts', `@Component({ selector: 'pngx-stats-widget', templateUrl: './stats.component.html' })\nexport class StatsComponent {}`);
+    write(root, 'apps/ng/src/app/dash/widgets/stats/stats.component.html', `<p>Stats</p>`);
+    // Rails convention
+    write(root, 'app/views/things/index.html.erb', `<%= render "layouts/header" %>\n<h1>Things</h1>`);
+    write(root, 'app/views/layouts/_header.html.erb', `<header/>`);
+    const map = {
+        route_index: {
+            things: { method: 'GET', path: '/things', primary_view: 'apps/web/app/things/page.tsx', layout: 'root' },
+            albums: { method: 'GET', path: '/albums', primary_view: 'apps/kit/src/routes/albums/+page.svelte', partials_expanded: ['already/listed.svelte'] },
+            dash: { method: 'GET', path: '/dash', primary_view: 'apps/ng/src/app/dash/dash.component.html' },
+            rails_things: { method: 'GET', path: '/rails/things', controller: 'things#index' },
+            ghost: { method: 'GET', path: '/ghost', primary_view: 'apps/web/app/missing.tsx' },
+        },
+        layouts: [{ name: 'root', path: 'apps/web/app/layout.tsx', chrome: [] }],
+    };
+    const mapPath = path.join(root, 'project_map.json');
+    fs.writeFileSync(mapPath, JSON.stringify(map, null, 2));
+    return { root, mapPath };
+}
+
+// ── resolver unit checks ────────────────────────────────────────────────────
+{
+    const { root } = fixture();
+    const from = path.join(root, 'apps/web/app/things');
+    assert.strictEqual(census.resolveModule('~/shell/Shell', from, root), path.join(root, 'apps/web/modules/shell/Shell.tsx'), 'tsconfig paths alias (JSONC with "/*" keys)');
+    assert.strictEqual(census.resolveModule('@ui/HeaderBar', from, root), path.join(root, 'packages/ui/src/HeaderBar.tsx'), 'alias into a sibling package');
+    assert.strictEqual(census.resolveModule('@mono/ui/components/table', from, root), path.join(root, 'packages/ui/components/table/index.ts'), 'workspace package exports entry');
+    assert.strictEqual(census.followBarrel(census.resolveModule('@mono/ui/components/table', from, root), 'DataTable', root), path.join(root, 'packages/ui/components/table/DataTable.tsx'), 'barrel export { X } from');
+    assert.strictEqual(census.followBarrel(census.resolveModule('@mono/ui/components/table', from, root), 'StatusBadge', root), path.join(root, 'packages/ui/components/table/StatusBadge.tsx'), 'barrel export * from');
+    assert.strictEqual(census.resolveModule('react', from, root), null, 'bare external stays unresolved');
+    const refs = census.includeRefs(root, 'apps/web/app/things/page.tsx');
+    const byName = Object.fromEntries(refs.map(r => [r.name, r]));
+    assert(!('LocalRow' in byName), 'a component defined in the same file is not an include');
+    assert.strictEqual(byName.Shell.file, 'apps/web/modules/shell/Shell.tsx');
+    assert.strictEqual(byName.AdminPanel.guarded, true, '&& guard');
+    assert.strictEqual(byName.FancyModal.overlay, true, 'modal by name');
+    const ng = Object.fromEntries(census.includeRefs(root, 'apps/ng/src/app/dash/dash.component.html').map(r => [r.name, r]));
+    assert.strictEqual(ng['pngx-page-header'].file, 'apps/ng/src/app/common/page-header/page-header.component.html', 'angular selector → template');
+    assert.strictEqual(ng['pngx-stats-widget'].file, 'apps/ng/src/app/dash/widgets/stats/stats.component.html');
+    assert(!('ng-container' in ng), 'framework tags skipped');
+    fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ── script end-to-end ───────────────────────────────────────────────────────
+{
+    const { root, mapPath } = fixture();
+    const out = run(mapPath, root, ['--json', path.join(root, 'report.json')]);
+    assert(/4 route\(s\) resolved/.test(out), out);
+    assert(/1 skipped/.test(out), out);
+    assert(/1 layout chain\(s\)/.test(out), out);
+    const pm = JSON.parse(fs.readFileSync(mapPath, 'utf8'));
+    const things = pm.route_index.things;
+    const files = things.render_chain.map(c => c.file);
+    const kind = f => things.render_chain.find(c => c.file === f).kind;
+    assert(files.includes('apps/web/modules/shell/Shell.tsx'), 'alias import in chain');
+    assert(files.includes('apps/web/modules/shell/SideNav.tsx'), 'depth-2 through the alias');
+    assert(files.includes('packages/ui/components/table/DataTable.tsx'), 'barrel followed to the component');
+    assert(files.includes('packages/ui/components/table/StatusBadge.tsx'), 'export * barrel followed');
+    assert(!files.includes('packages/ui/components/table/index.ts'), 'the barrel itself is not a chain file');
+    assert.strictEqual(kind('apps/web/modules/admin/AdminPanel.tsx'), 'conditional');
+    assert.strictEqual(kind('apps/web/modules/admin/DangerZone.tsx'), 'conditional', 'inherits the parent guard');
+    assert.strictEqual(kind('packages/ui/components/modal/FancyModal.tsx'), 'overlay');
+    assert.strictEqual(kind('packages/ui/components/modal/ModalFooter.tsx'), 'overlay', 'inherits overlay-ness');
+    assert.strictEqual(kind('apps/web/modules/shell/Shell.tsx'), 'unconditional');
+    assert.deepStrictEqual(things.partials_expanded, things.render_chain.filter(c => c.kind === 'unconditional').map(c => c.file), 'partials_expanded filled from the unconditional chain');
+    assert.strictEqual(things.render_chain_stats.files, things.render_chain.length);
+    assert.strictEqual(things.render_chain_stats.truncated, false);
+    assert(things.render_chain_stats.unresolved >= 0);
+    assert.deepStrictEqual(pm.route_index.albums.partials_expanded, ['already/listed.svelte'], 'existing partials_expanded never overwritten');
+    assert.deepStrictEqual(pm.route_index.albums.render_chain.map(c => c.file), ['apps/kit/src/lib/components/Albums.svelte'], '$lib resolves against the owning package');
+    assert.deepStrictEqual(pm.route_index.dash.render_chain.map(c => c.file).sort(), ['apps/ng/src/app/common/page-header/page-header.component.html', 'apps/ng/src/app/dash/widgets/stats/stats.component.html'].sort(), 'angular chain');
+    assert.strictEqual(pm.route_index.rails_things.primary_view, 'app/views/things/index.html.erb', 'rails convention fallback');
+    assert.strictEqual(pm.route_index.rails_things.primary_view_source, 'convention');
+    assert.deepStrictEqual(pm.route_index.rails_things.render_chain.map(c => c.file), ['app/views/layouts/_header.html.erb']);
+    assert(!pm.route_index.ghost.render_chain, 'unreadable primary_view is skipped untouched');
+    assert.deepStrictEqual(pm.layouts[0].render_chain.map(c => c.file), ['apps/web/modules/shell/Shell.tsx', 'apps/web/modules/shell/SideNav.tsx'], 'layout chain');
+    assert.strictEqual(pm.route_chain_resolver.version, 1);
+    const report = JSON.parse(fs.readFileSync(path.join(root, 'report.json'), 'utf8'));
+    assert.strictEqual(report.resolved, 4); assert.strictEqual(report.skipped, 1);
+    // caps
+    const again = run(mapPath, root, ['--max-files', '2']);
+    const capped = JSON.parse(fs.readFileSync(mapPath, 'utf8')).route_index.things;
+    assert.strictEqual(capped.render_chain.length, 2); assert.strictEqual(capped.render_chain_stats.truncated, true);
+    assert(again.includes('resolve_route_chains'));
+    // idempotent re-run keeps partials_expanded from the first (uncapped) pass
+    assert(capped.partials_expanded.length > 2, 'filled partials_expanded survives a re-run');
+    fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ── never fails a detect ────────────────────────────────────────────────────
+{
+    const out = run('/nonexistent/project_map.json', os.tmpdir());
+    assert(/usage/.test(out));
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rrc-'));
+    const mp = path.join(root, 'project_map.json');
+    fs.writeFileSync(mp, '{"framework":"rails"}');
+    assert(/no route_index/.test(run(mp, root)));
+    fs.writeFileSync(mp, '{not json');
+    assert(/unreadable/.test(run(mp, root)));
+    fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log('resolve_route_chains tests passed');