fimo 0.8.0 → 0.9.0-experimental.10

package/dist/scripts/frameworks/vite/routes.d.ts

@@ -0,0 +1,20 @@
+import { type RouteFileResolution, type RouteLike } from '../../routes/module-resolve.js';
+import type { DiscoveredRoute } from '../next/routes.js';
+/**
+ * Route discovery for Vite React SPAs: there is no file convention, so the
+ * routes live in react-router code. v1 reads LITERAL, ABSOLUTE paths from the
+ * two mainstream declaration shapes —
+ *
+ *   <Route path="/pricing" element={…} />          (JSX tree)
+ *   createBrowserRouter([{ path: '/pricing', … }])  (object form)
+ *
+ * — in files that import react-router. Relative child paths and index routes
+ * need the router's nesting semantics to resolve; they (and `*` wildcards)
+ * stay out of v1: the fimo-config route registry accepts manual entries for
+ * anything the scan cannot see, and scanned routes only ever ADD to it.
+ */
+export declare function discoverReactRouterDomRoutes(rootDir: string): DiscoveredRoute[];
+/** Registry-routed (frameworkRouteFiles): registry route ids → the SPA
+ *  component files that render them, via <Route element>/object-form route
+ *  declarations and import resolution (lazy() included). */
+export declare function resolveSpaRouteFiles(cwd: string, routes: Record<string, RouteLike>): RouteFileResolution[];

package/dist/scripts/frameworks/vite/routes.js

@@ -0,0 +1,143 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { discoveredRouteLabel } from '../../lib/humanize.js';
+import { componentImports, resolveModuleFile, walkFiles, } from '../../routes/module-resolve.js';
+const ROUTE_SOURCE = /\.(tsx|jsx|ts|js)$/;
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git']);
+/**
+ * Route discovery for Vite React SPAs: there is no file convention, so the
+ * routes live in react-router code. v1 reads LITERAL, ABSOLUTE paths from the
+ * two mainstream declaration shapes —
+ *
+ *   <Route path="/pricing" element={…} />          (JSX tree)
+ *   createBrowserRouter([{ path: '/pricing', … }])  (object form)
+ *
+ * — in files that import react-router. Relative child paths and index routes
+ * need the router's nesting semantics to resolve; they (and `*` wildcards)
+ * stay out of v1: the fimo-config route registry accepts manual entries for
+ * anything the scan cannot see, and scanned routes only ever ADD to it.
+ */
+export function discoverReactRouterDomRoutes(rootDir) {
+    const srcDir = join(rootDir, 'src');
+    const files = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (SKIP_DIRS.has(entry)) {
+                continue;
+            }
+            const full = join(dir, entry);
+            let isDir = false;
+            try {
+                isDir = statSync(full).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (isDir) {
+                walk(full);
+            }
+            else if (ROUTE_SOURCE.test(entry)) {
+                files.push(full);
+            }
+        }
+    };
+    walk(srcDir);
+    const routes = new Map();
+    for (const file of files) {
+        let code;
+        try {
+            code = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (!/from\s+['"]react-router(?:-dom)?['"]/.test(code)) {
+            continue;
+        }
+        const paths = [
+            ...[...code.matchAll(/<Route\b[^>]*\bpath\s*=\s*(?:"([^"]+)"|'([^']+)'|\{\s*(?:"([^"]+)"|'([^']+)')\s*\})/g)],
+            ...[...code.matchAll(/\bpath\s*:\s*(?:"([^"]+)"|'([^']+)')/g)],
+        ]
+            .map((match) => match.slice(1).find(Boolean))
+            .filter((path) => typeof path === 'string');
+        for (const raw of paths) {
+            if (!raw.startsWith('/') || raw.includes('*')) {
+                continue;
+            }
+            const path = raw !== '/' && raw.endsWith('/') ? raw.slice(0, -1) : raw;
+            if (routes.has(path)) {
+                continue;
+            }
+            const parts = path.split('/').filter(Boolean);
+            routes.set(path, {
+                id: path === '/' ? 'home' : parts.map((part) => part.replace(/^:/, '')).join('-'),
+                path,
+                label: discoveredRouteLabel(path),
+            });
+        }
+    }
+    return [...routes.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+/** Registry-routed (frameworkRouteFiles): registry route ids → the SPA
+ *  component files that render them, via <Route element>/object-form route
+ *  declarations and import resolution (lazy() included). */
+export function resolveSpaRouteFiles(cwd, routes) {
+    const srcDir = join(cwd, 'src');
+    const files = [];
+    walkFiles(srcDir, (name) => ROUTE_SOURCE.test(name), files);
+    const byPath = new Map();
+    for (const [routeId, route] of Object.entries(routes)) {
+        if (typeof route?.path === 'string') {
+            byPath.set(route.path, routeId);
+        }
+    }
+    const resolutions = new Map();
+    for (const file of files) {
+        let code;
+        try {
+            code = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (!/from\s+['"]react-router(?:-dom)?['"]/.test(code)) {
+            continue;
+        }
+        const imports = componentImports(code);
+        const pairs = [];
+        // JSX shape: one <Route …> tag carries both path and element, in either
+        // attribute order.
+        for (const tag of code.matchAll(/<Route\b((?:"[^"]*"|'[^']*'|\{[^{}]*\}|[^>"'{}])*)\/?>/g)) {
+            const attrs = tag[1];
+            const routePath = attrs.match(/\bpath\s*=\s*(?:"([^"]+)"|'([^']+)')/);
+            const element = attrs.match(/\belement\s*=\s*\{\s*<(\w+)[\s/>]/) ?? attrs.match(/\bComponent\s*=\s*\{(\w+)\}/);
+            if (routePath && element) {
+                pairs.push({ path: routePath[1] ?? routePath[2], component: element[1] });
+            }
+        }
+        // Object shape: { path: '/x', element: <X …/> } or { path: '/x', Component: X }.
+        for (const entry of code.matchAll(/path\s*:\s*(?:"([^"]+)"|'([^']+)')\s*,\s*(?:element\s*:\s*<(\w+)[\s/>]|Component\s*:\s*(\w+))/g)) {
+            pairs.push({ path: entry[1] ?? entry[2], component: entry[3] ?? entry[4] });
+        }
+        for (const pair of pairs) {
+            const normalized = pair.path !== '/' && pair.path.endsWith('/') ? pair.path.slice(0, -1) : pair.path;
+            const routeId = byPath.get(normalized);
+            if (!routeId || resolutions.has(routeId)) {
+                continue;
+            }
+            const spec = imports.get(pair.component);
+            const componentFile = spec ? resolveModuleFile(cwd, file, spec) : null;
+            if (componentFile) {
+                resolutions.set(routeId, componentFile);
+            }
+        }
+    }
+    return [...resolutions.entries()].map(([routeId, file]) => ({ routeId, file }));
+}

package/dist/scripts/frameworks/vite/wiring.d.ts

@@ -0,0 +1,22 @@
+import type { RootWiringResult } from '../next/wiring.js';
+/**
+ * Vite React SPA root wiring: wrap the root render argument with
+ * `FimoSpaProviders` (client-side label fetch; inline fallbacks until it
+ * resolves) and import the project's fimo-config.json. Only the mainstream
+ * entry shape is touched — a `createRoot(…).render(<JSX/>)` (or legacy
+ * `ReactDOM.render(<JSX/>, …)`) call whose first argument is a JSX element.
+ * Anything else bails with the reason and stays agent work via the recipe.
+ */
+export declare function ensureSpaEntryWiring(cwd: string): RootWiringResult;
+/**
+ * The `fimo()` Vite plugin serves the virtual modules the generated content
+ * clients import (`virtual:fimo-config`, …). Without it, the first
+ * dependency re-optimization 500s every page the moment an agent uses a
+ * generated client — both run-5 agents had to discover and add it by hand.
+ * Insert `fimo()` into the config's plugins array; unusual configs bail
+ * with the recipe.
+ */
+export declare function ensureViteFimoPlugin(cwd: string): {
+    changes: string[];
+    warnings: string[];
+};

package/dist/scripts/frameworks/vite/wiring.js

@@ -0,0 +1,144 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseSync } from 'oxc-parser';
+/**
+ * Vite React SPA root wiring: wrap the root render argument with
+ * `FimoSpaProviders` (client-side label fetch; inline fallbacks until it
+ * resolves) and import the project's fimo-config.json. Only the mainstream
+ * entry shape is touched — a `createRoot(…).render(<JSX/>)` (or legacy
+ * `ReactDOM.render(<JSX/>, …)`) call whose first argument is a JSX element.
+ * Anything else bails with the reason and stays agent work via the recipe.
+ */
+export function ensureSpaEntryWiring(cwd) {
+    const entryFile = ['src/main.tsx', 'src/main.jsx', 'src/index.tsx', 'src/index.jsx']
+        .map((candidate) => path.join(cwd, candidate))
+        .find((candidate) => fs.existsSync(candidate));
+    const bail = (reason, rel = 'src/main.tsx') => ({
+        changes: [],
+        warnings: [`Root wiring not applied: ${reason} — follow the SPA recipe in the agent prompt (${rel}).`],
+        wired: false,
+    });
+    if (!entryFile) {
+        return bail('no src/main or src/index entry file found');
+    }
+    const rel = path.relative(cwd, entryFile);
+    const code = fs.readFileSync(entryFile, 'utf8');
+    if (code.includes('FimoSpaProviders')) {
+        return { changes: [], warnings: [], wired: true };
+    }
+    let program;
+    try {
+        program = parseSync(entryFile, code).program;
+    }
+    catch {
+        return bail('entry file could not be parsed', rel);
+    }
+    // EVERY root-mount JSX argument, found structurally: `render(<X/>)` calls
+    // (createRoot/ReactDOM) AND `hydrateRoot(container, <X/>)` — a prerendered
+    // SPA mounts through BOTH branches, and wiring only the createRoot one
+    // left the production hydrate path without providers (run-5 finding).
+    const renderArgs = [];
+    (function find(node) {
+        if (!node || typeof node !== 'object') {
+            return;
+        }
+        const candidate = node;
+        if (candidate.type === 'CallExpression') {
+            const isRender = candidate.callee?.type === 'MemberExpression' && candidate.callee?.property?.name === 'render';
+            const isHydrate = candidate.callee?.name === 'hydrateRoot' ||
+                (candidate.callee?.type === 'MemberExpression' && candidate.callee?.property?.name === 'hydrateRoot');
+            const arg = isRender ? candidate.arguments?.[0] : isHydrate ? candidate.arguments?.[1] : undefined;
+            if (arg && (arg.type === 'JSXElement' || arg.type === 'JSXFragment')) {
+                renderArgs.push(arg);
+            }
+        }
+        for (const value of Object.values(candidate)) {
+            if (Array.isArray(value)) {
+                for (const entry of value) {
+                    find(entry);
+                }
+            }
+            else if (value && typeof value === 'object') {
+                find(value);
+            }
+        }
+    })(program);
+    if (renderArgs.length === 0) {
+        return bail('no root render call with a JSX argument found', rel);
+    }
+    const configImportPath = path
+        .relative(path.dirname(entryFile), path.join(cwd, 'fimo-config.json'))
+        .split(path.sep)
+        .join('/');
+    const open = '<FimoSpaProviders\n' +
+        '    config={fimoConfig}\n' +
+        '    apiUrl={import.meta.env.VITE_API_URL}\n' +
+        '    previewScriptUrl={import.meta.env.DEV ? import.meta.env.VITE_FIMO_PREVIEW_SCRIPT_URL : undefined}\n' +
+        '  >';
+    let next = code;
+    for (const renderArg of [...renderArgs].sort((a, b) => b.start - a.start)) {
+        const jsx = next.slice(renderArg.start, renderArg.end);
+        next = next.slice(0, renderArg.start) + `${open}\n    ${jsx}\n  </FimoSpaProviders>` + next.slice(renderArg.end);
+    }
+    // AST-positioned like ensureFimoImport: a multiline import's first line is
+    // not the end of the imports.
+    const importBlock = `import { FimoSpaProviders } from 'fimo/react';\nimport fimoConfig from '${configImportPath.startsWith('.') ? configImportPath : `./${configImportPath}`}';`;
+    let lastImportEnd = -1;
+    for (const node of program.body ?? []) {
+        if (node.type === 'ImportDeclaration') {
+            lastImportEnd = node.end;
+        }
+    }
+    // The wrap edit above only touched positions at/after renderArg.start,
+    // which is always beyond the import block, so import spans still hold.
+    next =
+        lastImportEnd >= 0
+            ? `${next.slice(0, lastImportEnd)}\n${importBlock}${next.slice(lastImportEnd)}`
+            : `${importBlock}\n${next}`;
+    fs.writeFileSync(entryFile, next);
+    const changes = [`wired FimoSpaProviders into ${rel} (${renderArgs.length} mount point(s))`];
+    const pluginResult = ensureViteFimoPlugin(cwd);
+    return {
+        changes: [...changes, ...pluginResult.changes],
+        warnings: pluginResult.warnings,
+        wired: true,
+    };
+}
+/**
+ * The `fimo()` Vite plugin serves the virtual modules the generated content
+ * clients import (`virtual:fimo-config`, …). Without it, the first
+ * dependency re-optimization 500s every page the moment an agent uses a
+ * generated client — both run-5 agents had to discover and add it by hand.
+ * Insert `fimo()` into the config's plugins array; unusual configs bail
+ * with the recipe.
+ */
+export function ensureViteFimoPlugin(cwd) {
+    const configFile = ['vite.config.ts', 'vite.config.js', 'vite.config.mts', 'vite.config.mjs']
+        .map((candidate) => path.join(cwd, candidate))
+        .find((candidate) => fs.existsSync(candidate));
+    if (!configFile) {
+        return { changes: [], warnings: ['No vite.config found — add the fimo() plugin per the agent-prompt recipe.'] };
+    }
+    const rel = path.relative(cwd, configFile);
+    const code = fs.readFileSync(configFile, 'utf8');
+    if (/\bfimo\s*\(/.test(code) && code.includes('fimo/vite')) {
+        return { changes: [], warnings: [] };
+    }
+    const pluginsMatch = code.match(/\bplugins\s*:\s*\[/);
+    if (!pluginsMatch || pluginsMatch.index === undefined) {
+        return {
+            changes: [],
+            warnings: [`No plugins array found in ${rel} — add the fimo() plugin per the agent-prompt recipe.`],
+        };
+    }
+    const insertAt = pluginsMatch.index + pluginsMatch[0].length;
+    let next = `${code.slice(0, insertAt)}fimo(), ${code.slice(insertAt)}`;
+    const importLine = `import { fimo } from 'fimo/vite';`;
+    const lastImport = [...next.matchAll(/^import .*$/gm)].pop();
+    next =
+        lastImport && lastImport.index !== undefined
+            ? `${next.slice(0, lastImport.index + lastImport[0].length)}\n${importLine}${next.slice(lastImport.index + lastImport[0].length)}`
+            : `${importLine}\n${next}`;
+    fs.writeFileSync(configFile, next);
+    return { changes: [`added the fimo() plugin to ${rel}`], warnings: [] };
+}

package/dist/scripts/i18n-namespace.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared next-intl namespace resolution for the two independent label-key
+ * scanners (`extract-translations` for `fimo validate`, `scan-wrappable` for
+ * `migrate wrap --check`). Both must record the SAME key form the i18n
+ * ingestion stores, or the seeding gate can never go green.
+ *
+ * `const t = useTranslations("plans.checkout")` scopes every `t("buyNow")` in
+ * that component to `plans.checkout.buyNow`. Root-scoped `useTranslations()`
+ * (namespace `""`) and server `getTranslations` are handled; a bare `t(...)`
+ * with no binding (Fimo's own label call) keeps its key unchanged.
+ */
+export declare const isFunctionLike: (node: any) => boolean;
+export declare function collectScopedBindings(fnNode: any): Map<string, string | null>;
+/**
+ * Resolve a `<name>("leaf")` call to its full key given the scope stack
+ * (innermost first).
+ * - `scoped`: the callee is a resolved `useTranslations` binding — namespace
+ *   prepended (unless root `""`).
+ * - `unresolvable`: the callee is a passed-in parameter — its namespace lives in
+ *   the caller and cannot be known here, so the caller should count the call as
+ *   covered but NOT demand the (bare) key.
+ */
+export declare function resolveScopedKey(calleeName: string, leafKey: string, scopes: Array<Map<string, string | null>>): {
+    key: string;
+    scoped: boolean;
+    unresolvable: boolean;
+};

package/dist/scripts/i18n-namespace.js

@@ -0,0 +1,155 @@
+/**
+ * Shared next-intl namespace resolution for the two independent label-key
+ * scanners (`extract-translations` for `fimo validate`, `scan-wrappable` for
+ * `migrate wrap --check`). Both must record the SAME key form the i18n
+ * ingestion stores, or the seeding gate can never go green.
+ *
+ * `const t = useTranslations("plans.checkout")` scopes every `t("buyNow")` in
+ * that component to `plans.checkout.buyNow`. Root-scoped `useTranslations()`
+ * (namespace `""`) and server `getTranslations` are handled; a bare `t(...)`
+ * with no binding (Fimo's own label call) keeps its key unchanged.
+ */
+export const isFunctionLike = (node) => node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression';
+/** Collect `useTranslations`/`getTranslations` bindings declared in a function's
+ *  direct body: variable name → namespace (`""` for root scope). */
+const unwrapAwait = (node) => (node?.type === 'AwaitExpression' ? node.argument : node);
+/**
+ * The namespace of a `useTranslations`/`getTranslations` call, or null if the
+ * node is not such a call. Handles the string arg (`getTranslations("seo")`),
+ * the object arg (`getTranslations({ locale, namespace: "seo" })`), and no arg
+ * (root scope → `""`). A dynamic namespace resolves to `""` (best effort).
+ */
+function translationCallNamespace(node) {
+    if (node?.type !== 'CallExpression' || node.callee?.type !== 'Identifier') {
+        return null;
+    }
+    if (node.callee.name !== 'useTranslations' && node.callee.name !== 'getTranslations') {
+        return null;
+    }
+    const arg = node.arguments?.[0];
+    if (!arg) {
+        return '';
+    }
+    if (arg.type === 'Literal' && typeof arg.value === 'string') {
+        return arg.value;
+    }
+    if (arg.type === 'ObjectExpression') {
+        for (const prop of arg.properties ?? []) {
+            const keyName = prop?.key?.name ?? prop?.key?.value;
+            if (keyName === 'namespace' && prop.value?.type === 'Literal' && typeof prop.value.value === 'string') {
+                return prop.value.value;
+            }
+        }
+    }
+    return '';
+}
+/** Mark every identifier bound by a parameter pattern (plain, defaulted, or
+ *  destructured — `t`, `t = x`, `{ t }`, `[t]`) as unresolvable (null). */
+function markParamBindings(node, bindings) {
+    if (!node) {
+        return;
+    }
+    switch (node.type) {
+        case 'Identifier':
+            if (!bindings.has(node.name)) {
+                bindings.set(node.name, null);
+            }
+            break;
+        case 'AssignmentPattern':
+            markParamBindings(node.left, bindings);
+            break;
+        case 'RestElement':
+            markParamBindings(node.argument, bindings);
+            break;
+        case 'ArrayPattern':
+            for (const element of node.elements ?? []) {
+                markParamBindings(element, bindings);
+            }
+            break;
+        case 'ObjectPattern':
+            for (const prop of node.properties ?? []) {
+                markParamBindings(prop.type === 'RestElement' ? prop.argument : prop.value, bindings);
+            }
+            break;
+        default:
+            break;
+    }
+}
+export function collectScopedBindings(fnNode) {
+    const bindings = new Map();
+    const body = fnNode.body;
+    const statements = body && Array.isArray(body.body) ? body.body : [];
+    for (const stmt of statements) {
+        if (stmt?.type !== 'VariableDeclaration') {
+            continue;
+        }
+        for (const decl of stmt.declarations ?? []) {
+            const init = unwrapAwait(decl?.init);
+            // `const t = [await] useTranslations/getTranslations(...)`
+            if (decl?.id?.type === 'Identifier') {
+                const namespace = translationCallNamespace(init);
+                if (namespace !== null) {
+                    bindings.set(decl.id.name, namespace);
+                }
+                continue;
+            }
+            // `const [a, t] = await Promise.all([...])` or `= use(Promise.all([...]))`
+            if (decl?.id?.type === 'ArrayPattern') {
+                // Unwrap React's `use()` wrapper around the promise.
+                const source = init?.type === 'CallExpression' && init.callee?.type === 'Identifier' && init.callee.name === 'use'
+                    ? unwrapAwait(init.arguments?.[0])
+                    : init;
+                const promiseAll = source?.type === 'CallExpression' &&
+                    source.callee?.type === 'MemberExpression' &&
+                    source.callee.object?.name === 'Promise' &&
+                    source.callee.property?.name === 'all';
+                const elements = promiseAll
+                    ? source.arguments?.[0]?.type === 'ArrayExpression'
+                        ? source.arguments[0].elements
+                        : null
+                    : source?.type === 'ArrayExpression'
+                        ? source.elements
+                        : null;
+                if (elements) {
+                    decl.id.elements?.forEach((el, index) => {
+                        if (el?.type !== 'Identifier') {
+                            return;
+                        }
+                        const namespace = translationCallNamespace(unwrapAwait(elements[index]));
+                        if (namespace !== null) {
+                            bindings.set(el.name, namespace);
+                        }
+                    });
+                }
+            }
+        }
+    }
+    // Function parameters are bound by the CALLER: a `t` passed in carries the
+    // caller's namespace, unknowable here. Mark them null so their t() calls are
+    // counted as covered but never demanded by the seeding gate as a bare leaf.
+    for (const param of fnNode.params ?? []) {
+        markParamBindings(param, bindings);
+    }
+    return bindings;
+}
+/**
+ * Resolve a `<name>("leaf")` call to its full key given the scope stack
+ * (innermost first).
+ * - `scoped`: the callee is a resolved `useTranslations` binding — namespace
+ *   prepended (unless root `""`).
+ * - `unresolvable`: the callee is a passed-in parameter — its namespace lives in
+ *   the caller and cannot be known here, so the caller should count the call as
+ *   covered but NOT demand the (bare) key.
+ */
+export function resolveScopedKey(calleeName, leafKey, scopes) {
+    for (let i = scopes.length - 1; i >= 0; i -= 1) {
+        if (scopes[i].has(calleeName)) {
+            const namespace = scopes[i].get(calleeName);
+            if (namespace === null || namespace === undefined) {
+                return { key: leafKey, scoped: false, unresolvable: true };
+            }
+            return { key: namespace ? `${namespace}.${leafKey}` : leafKey, scoped: true, unresolvable: false };
+        }
+    }
+    return { key: leafKey, scoped: false, unresolvable: false };
+}

package/dist/scripts/lib/humanize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Human-facing names derived from slugs and identifiers — route labels, page
+ * names, field titles. One rule set so "ai-stack" reads "AI Stack" and
+ * "agentic-cms" reads "Agentic CMS" everywhere the machine writes a name.
+ */
+/** "ai-stack" → "AI Stack"; "agenticCms" → "Agentic CMS"; "blog" → "Blog". */
+export declare function humanizeSegment(segment: string): string;
+/**
+ * The discovery-time label for a route path. Dynamic templates never share
+ * the parent index page's name (the run-4 tree showed "Blog" twice): the
+ * param joins the label ("/blog/:slug" → "Blog Slug") until a schema
+ * binding upgrades it to the schema's name ("Blog Post").
+ */
+export declare function discoveredRouteLabel(path: string): string;

package/dist/scripts/lib/humanize.js

@@ -0,0 +1,54 @@
+/**
+ * Human-facing names derived from slugs and identifiers — route labels, page
+ * names, field titles. One rule set so "ai-stack" reads "AI Stack" and
+ * "agentic-cms" reads "Agentic CMS" everywhere the machine writes a name.
+ */
+const ACRONYMS = new Set([
+    'ai',
+    'api',
+    'cd',
+    'ci',
+    'cli',
+    'cms',
+    'cta',
+    'faq',
+    'geo',
+    'llm',
+    'sdk',
+    'seo',
+    'spa',
+    'ssg',
+    'ssr',
+    'ui',
+    'url',
+    'ux',
+]);
+/** "ai-stack" → "AI Stack"; "agenticCms" → "Agentic CMS"; "blog" → "Blog". */
+export function humanizeSegment(segment) {
+    return segment
+        .replace(/[_\-]+/g, ' ')
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((word) => ACRONYMS.has(word.toLowerCase()) ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join(' ');
+}
+/**
+ * The discovery-time label for a route path. Dynamic templates never share
+ * the parent index page's name (the run-4 tree showed "Blog" twice): the
+ * param joins the label ("/blog/:slug" → "Blog Slug") until a schema
+ * binding upgrades it to the schema's name ("Blog Post").
+ */
+export function discoveredRouteLabel(path) {
+    if (path === '/') {
+        return 'Home';
+    }
+    const parts = path.split('/').filter(Boolean);
+    const lastStatic = [...parts].reverse().find((part) => !part.startsWith(':'));
+    const base = humanizeSegment(lastStatic ?? parts[parts.length - 1]?.replace(/^:/, '') ?? path);
+    const lastPart = parts[parts.length - 1];
+    if (lastPart?.startsWith(':') && lastStatic) {
+        return `${base} ${humanizeSegment(lastPart.replace(/^:|\*$/g, ''))}`;
+    }
+    return base;
+}

package/dist/scripts/lib/validation-report.d.ts

@@ -23,6 +23,7 @@ export interface PhaseResult {
     skipped?: {
         reason: string;
     };
+    warnings?: string[];
 }
 export interface ValidationReport {
     ok: boolean;
@@ -33,12 +34,9 @@ export interface ValidationReport {
         sync: PhaseResult;
     };
 }
-export declare function emptyPhase(name: string): PhaseResult;
 export declare function skippedPhase(name: string, reason: string): PhaseResult;
 export declare function computeExitCode(report: ValidationReport): 0 | 1 | 2;
 export declare function finalizeReport(report: Omit<ValidationReport, 'ok' | 'exitCode'>): ValidationReport;
 export declare function authorError(opts: Omit<ValidationError, 'kind'>): ValidationError;
-export declare function infraError(opts: Omit<ValidationError, 'kind'>): ValidationError;
 export declare function infraErrorFromException(rule: string, error: unknown): ValidationError;
-export declare function formatReportJson(report: ValidationReport): string;
 export declare function formatReportHuman(report: ValidationReport): string;

package/dist/scripts/lib/validation-report.js

@@ -6,9 +6,6 @@
  * (the Fimo backend is unreachable or returned a server error — agent should
  * surface to the human and stop). Exit codes follow the same split.
  */
-export function emptyPhase(name) {
-    return { name, ok: true, errors: [] };
-}
 export function skippedPhase(name, reason) {
     return { name, ok: false, errors: [], skipped: { reason } };
 }
@@ -32,9 +29,6 @@ export function finalizeReport(report) {
 export function authorError(opts) {
     return { kind: 'author', ...opts };
 }
-export function infraError(opts) {
-    return { kind: 'infra', ...opts };
-}
 export function infraErrorFromException(rule, error) {
     return {
         kind: 'infra',
@@ -42,9 +36,6 @@ export function infraErrorFromException(rule, error) {
         message: error instanceof Error ? error.message : String(error),
     };
 }
-export function formatReportJson(report) {
-    return JSON.stringify(report, null, 2);
-}
 export function formatReportHuman(report) {
     const lines = [];
     for (const phase of [report.phases.checks, report.phases.codegen, report.phases.sync]) {
@@ -76,6 +67,9 @@ function formatPhaseHuman(phase) {
             out.push(`    ${parts.join(', ')}`);
         }
     }
+    for (const warning of phase.warnings ?? []) {
+        out.push(`    ⚠ ${warning}`);
+    }
     for (const err of phase.errors) {
         const loc = err.file ? ` (${err.file}${err.line ? `:${err.line}` : ''}${err.column ? `:${err.column}` : ''})` : '';
         out.push(`    [${err.kind}] ${err.rule}: ${err.message}${loc}`);