@nac3/forge-cli 0.2.0-alpha.1

package/dist/migrate/ai-apply.js

@@ -0,0 +1,833 @@
+/*
+ * src/migrate/ai-apply.ts
+ *
+ * Claude-powered JSX decoration. Per-file LLM call that adds
+ * data-nac-id / data-nac-role / data-nac-action attributes to JSX
+ * interactive elements, and returns a manifest fragment listing
+ * what it decorated. Forge aggregates all fragments into a single
+ * top-level manifest.json.
+ *
+ * The JSX-side counterpart to ai-decorator.ts (which works on
+ * static HTML). For React apps the source-level decoration is what
+ * persists across builds; static-HTML decoration would be lost on
+ * the next Vite build.
+ *
+ * Single-call per file. Sonnet 4.6 by default. temperature=0 for
+ * determinism (verified on calc baseline).
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import Anthropic from '@anthropic-ai/sdk';
+import { validateAiApplyFragment, formatFindingsForRetry, } from './manifest-validator.js';
+const DEFAULT_MODEL = 'claude-sonnet-4-6';
+const PRICING = {
+    'claude-sonnet-4-6': { in: 3.00, out: 15.00 },
+    'claude-haiku-4-5': { in: 0.80, out: 4.00 },
+    'claude-haiku-4-5-20251001': { in: 0.80, out: 4.00 },
+    'claude-opus-4-7': { in: 15.00, out: 75.00 },
+};
+function resolveAnthropicModelId(id) {
+    if (id === 'claude-haiku-4-5')
+        return 'claude-haiku-4-5-20251001';
+    return id;
+}
+function computeCost(model, usage) {
+    const p = PRICING[model] ?? PRICING['claude-sonnet-4-6'];
+    return (usage.input * p.in + usage.output * p.out) / 1_000_000;
+}
+const SYSTEM_PROMPT = `You are a NAC-3 (Native Agent Contract) JSX decorator. You receive one React JSX file and return:
+  (a) the SAME file with data-nac-id / data-nac-role / data-nac-action attributes added to every interactive element (buttons, inputs, selects, links that DO something, tabs, navigation items, form fields).
+  (b) the manifest fragment listing what you decorated.
+
+ROLE TAXONOMY (critical):
+- action: anything the user CLICKS to make something happen.
+- field: an element that HOLDS a VALUE the user can read or write (inputs, textareas, output panels). NEVER classify a value-holding element as region.
+- region: a CONTAINER that groups other elements.
+- option: a single choice inside a select / radio group.
+- tab: a tab-bar entry.
+- navigation: nav link that changes route.
+
+ID PATTERN: "<plugin_slug>.<role>.<thing>", snake_case, lowercase. Example: "conduit.action.submit", "conduit.field.email", "conduit.region.feed".
+
+VERB NAMING: short imperative (submit, login, follow, favorite, publish, delete, save). Avoid prefixes like "do_" or "btn_".
+
+PLUGIN SLUG: choose ONE for the whole app. Use the same slug across every file. Default: derive from the project name or a clear semantic guess (e.g. "conduit" for a Medium clone, "todo" for a todo app).
+
+PARENT-CHILD ID-PREFIX CONTINUITY (H5, critical when both files in scope):
+
+When a PARENT file declares per-instance ids for a CHILD component it
+renders (e.g. <FeedToggler> emits manifest entries
+"conduit.tab.feed__your_feed", "conduit.tab.feed__global_feed" for
+its rendered <FeedNavLink> children), the CHILD component's own
+template-literal decoration MUST use the SAME prefix the parent
+declared. Do NOT derive the child's prefix from the child's component
+name.
+
+In the FeedToggler/FeedNavLink example:
+  - PARENT FeedToggler.jsx declares per-instance ids using prefix
+    "conduit.tab.feed__" (NOT "conduit.tab.feed_nav_link__").
+  - CHILD FeedNavLink.jsx must therefore decorate as:
+       data-nac-id={\`conduit.tab.feed__\${slugify(name)}\`}
+       data-nac-role="tab"
+       data-nac-action="activate"
+    NOT as conduit.tab.feed_nav_link__\${name}.
+  - In the child's manifest "elements" array, the entry's
+    "instance_pattern" field carries the SAME parent-prefixed pattern:
+       "instance_pattern": "conduit.tab.feed__\${qualifier}"
+
+This rule applies to ANY role that supports per-instance qualifiers
+(tab, navigation, action, field, region). The parent's naming wins
+because the parent is the file that knows the user-meaningful names
+of the instances; the child is generic and reused across contexts.
+
+To detect parent-declared prefixes from a child's file alone:
+  - If the child is imported by exactly one parent in the input set
+    AND that parent emits per-instance entries with a common prefix
+    "<plugin>.<role>.<X>__" (where X is shorter than the child's
+    own component name), use prefix "<plugin>.<role>.<X>__" for the
+    child's template, NOT "<plugin>.<role>.<child_component>__".
+  - If the parent is NOT in the input set or the prefix can't be
+    inferred, fall back to the child-component-name prefix BUT emit
+    a warning: "Child component decorated without parent-prefix
+    context; ids may not match parent's per-instance declarations."
+
+This closes a structural gap previously assumed only at runtime
+(NAC.click_by_verb base→qualified fallback). The fix belongs in
+decoration, not runtime: runtime can't reconcile two prefix schemes
+that don't share a root.
+
+REUSABLE COMPONENTS -- PER-INSTANCE QUALIFIER (critical for SPAs):
+
+Many React components are written once but rendered N times. If you decorate
+<NavItem> as data-nac-id="conduit.navigation.nav_item", the DOM ends up with
+N copies of the SAME id (Home, Sign in, Sign up, Settings -- all collide).
+An agent cannot disambiguate "click Sign in" from "click Home" in that
+collision.
+
+The fix is per-instance qualifier suffixing on data-nac-id. Decide one of
+three strategies BASED ON THE COMPONENT, not the parent:
+
+  1. STATIC: the component's identity is determined by a JSX prop / child
+     known at AUTHORING time (label="Home", to="/login", icon="trash"). Use
+     a JSX template literal that bakes the qualifier in:
+       data-nac-id={\`conduit.navigation.nav_item__\${slugify(label)}\`}
+     For this case, in your "elements" array, emit ONE entry per known
+     instance (look at how the parent uses the component to enumerate them
+     -- if the parent file is being decorated and uses <NavItem label="Home"/>,
+     <NavItem label="Sign in"/>, emit two entries:
+        conduit.navigation.nav_item__home
+        conduit.navigation.nav_item__sign_in
+     If you cannot see all the parents (the component is exported and the
+     parent file is not in this prompt), emit ONE element with the
+     "qualifier_source" pointing to the JSX expression you used:
+        { "id": "conduit.navigation.nav_item",
+          "role": "navigation",
+          "actions": [{ "verb": "navigate" }],
+          "instance_pattern": "conduit.navigation.nav_item__\${qualifier}",
+          "qualifier_source": "props.label",
+          "warning": "static qualifier inferred from props.label; see parents for enumerated instances" }
+
+  2. DYNAMIC: the component's identity is from data that arrives at runtime
+     (an article slug, a comment id, a row's primary key). Use the JSX
+     expression that reads the data:
+       data-nac-id={\`conduit.action.favorite_article__\${article.slug}\`}
+     In your "elements" array, emit ONE template entry:
+       { "id": "conduit.action.favorite_article",
+         "role": "action",
+         "actions": [{ "verb": "favorite" }],
+         "instance_pattern": "conduit.action.favorite_article__\${article.slug}",
+         "qualifier_source": "article.slug" }
+
+  3. UNINFERRABLE: you tried 1 and 2 and there is no obvious qualifier
+     (the component is reused but takes no identifying prop). Decorate with
+     the base id and emit a WARNING in the entry:
+       { "id": "conduit.action.unknown_action",
+         "role": "action",
+         "actions": [{ "verb": "click" }],
+         "warning": "component is reusable but no qualifier could be inferred; N DOM instances will share this id; consider adding a label/id prop or use yf migrate --ai-override to disambiguate manually" }
+     NEVER silently collapse. The warning is what keeps the case study honest.
+
+QUALIFIER SOURCES, in preference order:
+  1. props that identify content: \`label\`, \`name\`, \`id\`, \`slug\`, \`key\`, \`title\`
+  2. routing props: \`to\`, \`href\` (slugify the path)
+  3. primitive children: <Comp>Sign in</Comp> -> slugify the child text
+  4. semantic icon hints: icon="trash" -> qualifier "trash"
+
+SLUGIFY: lowercase, replace whitespace + non-alphanum with "_", trim leading/trailing "_".
+E.g. "Sign in" -> "sign_in", "/login" -> "login", "How to train your dragon" -> "how_to_train_your_dragon".
+
+VERB NAMING when adding qualifier: keep the verb generic across instances
+(verb="navigate" for all NavItems, not verb="navigate_to_home"). The
+qualifier is what disambiguates instance; the verb is what disambiguates intent.
+
+WHAT TO SKIP:
+- Pure layout components (header / footer / div wrappers with no event handlers).
+- Components that ONLY render children (no own interactive elements).
+- Static text / images that have no onClick / onChange / form handlers.
+
+WHAT TO PRESERVE:
+- Every existing attribute, prop, JSX expression. You ONLY add.
+- File structure, imports, exports.
+- All formatting outside the touched elements.
+
+ROUTE AWARENESS (H1 -- critical for SPA test generation):
+
+If this file declares routes (matches React Router patterns
+<Route path="/something" element={<Component />} />, or
+<Routes>...children...</Routes>, or a route config object), capture
+the URL path the element corresponds to.
+
+For each element you decorate, if you can determine the route(s)
+under which the component MOUNTS, emit a "mounted_at" array on the
+element:
+
+  - For elements declared in routes/Home.jsx that mount under "/":
+    "mounted_at": ["/"]
+  - For elements declared in routes/Login.jsx that mount under "/login":
+    "mounted_at": ["/login"]
+  - For nav elements that live in a top-level Navbar always visible:
+    "mounted_at": ["*"]    (the "always available" sentinel)
+
+If you cannot determine the route (the component is a leaf rendered
+by a parent you can't see), omit mounted_at. The aggregator will
+attempt to infer it later from the import graph.
+
+If this file IS a Router root (Routes container or a config that
+declares <Route> children), also emit a top-level "route_map" field
+mapping component import path -> URL pattern, e.g.:
+  "route_map": {
+    "./routes/Home": ["/"],
+    "./routes/Login": ["/login"],
+    "./routes/ArticleEditor": ["/editor", "/editor/:slug"]
+  }
+The Router root file is also the natural place to emit "fixtures"
+(see FIXTURE SEEDING below).
+
+ROUTER KIND (H1.v4 -- critical for test URL emission):
+Detect which Router the SPA uses and emit a top-level "router_kind"
+field on the response:
+  - <BrowserRouter> -> "router_kind": "browser"  (URLs like "/login")
+  - <HashRouter>    -> "router_kind": "hash"     (URLs like "/#/login")
+  - <MemoryRouter>  -> "router_kind": "memory"
+  - default / unsure -> "router_kind": "browser"
+The emitter prefixes test URLs with "#" when router_kind is "hash"
+so cy.visit hits the right SPA route.
+
+AUTH GATING (H1 -- critical for test pre-steps):
+
+If a route is wrapped in <RequireAuth> or any obvious auth-guard
+component, mark the route as auth-gated in "route_map":
+  "/editor": { "paths": ["/editor"], "requires_auth": true }
+And for elements that mount only under auth-gated routes, set on
+the element:
+  "requires_auth": true
+
+FIXTURE SEEDING (H1.v3 -- critical for dynamic-route tests):
+
+If this file is a Router root AND any route contains a path
+parameter (\`:slug\`, \`:username\`, \`:id\`, etc), an e2e test on that
+route cannot simply visit it -- the resource must exist first.
+
+For each path parameter, infer the API endpoint that CREATES a
+resource matching that parameter, by inspecting:
+  - the file you are decorating right now (Router roots often
+    import service modules)
+  - other src/services/*.js modules referenced in the imports
+  - the JSX of the route component (does it call useParams() with
+    a name that maps to this param?)
+
+Emit "fixtures" inside route_map for each :param you can resolve.
+Each fixture has a CREATE endpoint and (when possible) a DELETE
+endpoint so each test starts from a clean state and tears down
+after itself. Schema:
+
+  "fixtures": {
+    ":slug": {
+      "create_endpoint": "POST /api/articles",
+      "create_payload": { "article": { "title": "Forge fixture",
+        "body": "Forge fixture body", "tagList": [] } },
+      "response_path": "article.slug",
+      "delete_endpoint": "DELETE /api/articles/{value}",
+      "requires_auth": true,
+      "unique_suffix_field": null
+    },
+    ":username": {
+      "create_endpoint": "POST /api/users",
+      "create_payload": { "user": { "username": "forge_fixture_{seed}",
+        "email": "forge-fixture-{seed}@yujin.app",
+        "password": "forge-fixture-2026" } },
+      "response_path": "user.username",
+      "delete_endpoint": null,
+      "requires_auth": false,
+      "unique_suffix_field": "user.username,user.email"
+    }
+  }
+
+Conventions:
+- "create_endpoint" is "<METHOD> <PATH>" the SPA's service module
+  hits to CREATE the resource.
+- "create_payload" is the minimal body for a 200/201. Use literal
+  values. When "unique_suffix_field" is set, the emitter replaces
+  {seed} with a DETERMINISTIC per-test suffix derived from the
+  test\'s position (NOT Math.random -- the suite must be
+  reproducible byte-for-byte across runs).
+- "response_path" is the dotted path from response body to the
+  value that fills the URL param (e.g. "article.slug").
+- "delete_endpoint" is "<METHOD> <PATH>" where "{value}" is
+  substituted with the captured response value. Set to null only
+  when truly no delete exists (e.g. user registration). When set,
+  the emitter calls it in afterEach with failOnStatusCode=false
+  so a failed test cleans up defensively.
+- "unique_suffix_field" is a CSV list of dotted paths inside
+  create_payload where {seed} is substituted with the deterministic
+  per-test suffix (e.g. "user.username,user.email"). Required when
+  delete_endpoint is null AND the resource persists across tests.
+- "requires_auth" is true when CREATE needs an auth header.
+
+DETERMINISM (non-negotiable): never use random data. The emitter
+will pass a deterministic SEED integer per test (the test index
+within the suite) so the same suite produces the same payloads
+across runs. Tests for the same element get the same fixture.
+ISOLATION (non-negotiable): every test creates its own fixture in
+beforeEach and tears it down in afterEach. No state leaks across
+tests; the suite is repeatable from a fresh DB.
+
+If you cannot determine a fixture for a given :param, omit it.
+The emitter will skip the corresponding tests with a TODO.
+
+OUTPUT FORMAT: a single JSON object, no prose, no markdown fences:
+{
+  "decorated_jsx": "<the FULL decorated file content as a single string>",
+  "plugin_slug": "<slug>",
+  "route_map": "<optional: only when this file is a Router root>",
+  "fixtures": "<optional: only when this file is a Router root AND any route uses :params>",
+  "elements": [
+    {
+      "id": "<dotted id, possibly with __qualifier suffix>",
+      "role": "action|field|option|tab|region|navigation",
+      "actions": [{ "verb": "<verb>" }],
+      "instance_pattern": "<optional: present for DYNAMIC qualifiers>",
+      "qualifier_source": "<optional: JSX expression backing the qualifier>",
+      "warning": "<optional: present for UNINFERRABLE reusable components>",
+      "mounted_at": "<optional: array of URL paths where this element appears>",
+      "requires_auth": "<optional: true if any of its mount routes is auth-gated>"
+    }
+  ],
+  "decorated": <true | false -- false if the file has no interactive elements>
+}
+
+If the file has zero interactive elements to decorate, return:
+{ "decorated_jsx": "<original file unchanged>", "plugin_slug": "<slug>", "elements": [], "decorated": false }
+`;
+/* I18N_PROMPT_EXTENSION -- appended to SYSTEM_PROMPT when the
+   --with-i18n-tags flag is set. Adds data-i18n="<key>" decoration
+   on user-facing text nodes IN PARALLEL with the existing NAC-3
+   decoration. The two attribute systems are independent: NAC ids
+   are for AGENTS (semantic, language-invariant); i18n keys are for
+   HUMAN VIEWERS (translated per locale at runtime via the host's
+   i18n shim).
+
+   Do NOT decorate the SAME element with conflicting keys. Do not
+   collide i18n keys across files (use the file's component context
+   as a namespace, e.g. "navbar.home", "login.sign_in_button"). */
+const I18N_PROMPT_EXTENSION = `
+I18N DECORATION (ADDITIONAL, runs in parallel with NAC-3 decoration):
+
+For every JSX text node that is user-facing (button text, link text,
+heading text, paragraph text, label text, placeholder, title attribute,
+aria-label) AND that is a LITERAL STRING (not derived from a prop /
+variable / expression), add:
+
+- "data-i18n" attribute on the text-containing element, holding a
+  stable snake_case key. Format: "<surface>.<element>" where surface
+  is the namespace (nav, feed, profile, form, action, msg) and element
+  describes the specific text (sign_in, home, password, etc).
+- "data-i18n-placeholder" attribute for placeholder= attributes.
+- "data-i18n-title" attribute for title= attributes.
+- "data-i18n-aria-label" for aria-label= attributes.
+
+Example transformations:
+  Before: <button>Sign in</button>
+  After:  <button data-nac-id="conduit.action.sign_in"
+                  data-nac-role="action" data-nac-action="login"
+                  data-i18n="action.sign_in">Sign in</button>
+
+  Before: <input placeholder="Email" />
+  After:  <input data-nac-id="conduit.field.email"
+                 data-nac-role="field"
+                 data-i18n-placeholder="form.email"
+                 placeholder="Email" />
+
+DO NOT decorate:
+- Text that is a prop / variable / expression / template (\`\${...}\`).
+  Those are dynamic and live in the rendered data, not the catalog.
+- Text inside <code> / <pre> blocks (technical content, language-agnostic).
+- Single-character symbols (×, ✓, +, etc).
+- Numerals that are computed (counts, prices). Static numerals in
+  copy ARE decorated.
+
+Return an ADDITIONAL field in the JSON response:
+
+  "i18n_catalog": {
+    "action.sign_in": "Sign in",
+    "form.email": "Email",
+    "msg.tagline": "A place to share your knowledge.",
+    ...
+  }
+
+Keys MUST match what you placed in data-i18n / data-i18n-placeholder /
+data-i18n-title / data-i18n-aria-label attributes. Values are the
+ENGLISH source text (the original verbatim string from the JSX). The
+catalog is per-file; the project-level aggregator merges them.
+
+If the file has no user-facing literal text to decorate, return
+"i18n_catalog": {} (an empty object).
+`;
+const _client = {};
+function client() {
+    if (!_client.c)
+        _client.c = new Anthropic();
+    return _client.c;
+}
+function extractJsonObject(text) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    if (fenced && fenced[1])
+        return fenced[1].trim();
+    const trimmed = text.trim();
+    if (trimmed.startsWith('{') && trimmed.endsWith('}'))
+        return trimmed;
+    const i = trimmed.indexOf('{');
+    const j = trimmed.lastIndexOf('}');
+    if (i >= 0 && j > i)
+        return trimmed.slice(i, j + 1);
+    return trimmed;
+}
+/* G2: maximum LLM attempts per file before we accept the last
+   response as-is and surface validation findings to the caller. */
+export const AI_APPLY_MAX_ATTEMPTS = 3;
+const defaultAiCaller = async (args) => {
+    const payload = {
+        model: args.model,
+        max_tokens: 8192,
+        system: args.system,
+        messages: args.messages,
+    };
+    if (!args.skipTemperature)
+        payload.temperature = 0;
+    const resp = await client().messages.create(payload);
+    const block = resp.content.find((b) => b.type === 'text');
+    return {
+        text: block?.text || '',
+        usage: {
+            input: resp.usage.input_tokens || 0,
+            output: resp.usage.output_tokens || 0,
+        },
+    };
+};
+/**
+ * G2: assemble the retry-turn user message. Includes the prior
+ * findings + the last attempt's raw output so Claude can target a
+ * fix instead of guessing what went wrong.
+ *
+ * `attempt` is the zero-based index of the JUST-FAILED attempt;
+ * the next attempt the model is about to make is therefore
+ * `attempt + 2` in human-counted "1 of N" terms.
+ */
+function buildRetryUserMessage(args) {
+    return 'Your previous response failed contract validation. Findings:\n'
+        + formatFindingsForRetry(args.findings)
+        + '\n\nThis is retry attempt ' + (args.attempt + 2) + ' of '
+        + AI_APPLY_MAX_ATTEMPTS + '. Please re-emit the COMPLETE JSON object '
+        + '(decorated_jsx, elements, plugin_slug, etc) with the listed errors fixed. '
+        + 'Do not omit fields that were already correct.';
+}
+export async function aiApplyOne(opts) {
+    const model = opts.model || DEFAULT_MODEL;
+    const skipTemp = /^claude-opus-4-7/.test(model);
+    const system = opts.withI18n ? (SYSTEM_PROMPT + '\n\n' + I18N_PROMPT_EXTENSION) : SYSTEM_PROMPT;
+    const initialUserPrompt = '<FILE path="' + opts.relpath + '">\n' + opts.jsxSource + '\n</FILE>' +
+        (opts.pluginSlugHint ? '\n\nPlugin slug for this project: ' + opts.pluginSlugHint : '') +
+        (opts.withI18n ? '\n\nALSO emit i18n decoration per the i18n section of the system prompt.' : '');
+    const caller = opts.aiCaller || defaultAiCaller;
+    const t0 = Date.now();
+    let tokens_in = 0;
+    let tokens_out = 0;
+    const messages = [
+        { role: 'user', content: initialUserPrompt },
+    ];
+    let lastParsed = null;
+    let lastRaw = '';
+    let lastFindings = [];
+    let attempts = 0;
+    for (let attempt = 0; attempt < AI_APPLY_MAX_ATTEMPTS; attempt++) {
+        attempts = attempt + 1;
+        const result = await caller({
+            system,
+            messages,
+            model: resolveAnthropicModelId(model),
+            skipTemperature: skipTemp,
+        });
+        lastRaw = result.text;
+        tokens_in += result.usage.input;
+        tokens_out += result.usage.output;
+        const jsonText = extractJsonObject(lastRaw);
+        let parsed;
+        let parseFailed = false;
+        try {
+            parsed = JSON.parse(jsonText);
+        }
+        catch (_e) {
+            parseFailed = true;
+        }
+        if (parseFailed) {
+            lastParsed = null;
+            lastFindings = [{
+                    severity: 'error',
+                    code: 'response_not_json',
+                    message: 'Response did not contain a parseable JSON object. ' +
+                        'Wrap the result in a single { ... } object (or a single ```json fenced block).',
+                }];
+        }
+        else {
+            lastParsed = parsed;
+            const validation = validateAiApplyFragment(parsed);
+            lastFindings = validation.findings;
+            if (validation.ok) {
+                // Success: break the loop, return below.
+                break;
+            }
+        }
+        // Failed attempt: prepare retry messages if there is a next round.
+        if (attempt + 1 < AI_APPLY_MAX_ATTEMPTS) {
+            messages.push({ role: 'assistant', content: lastRaw });
+            messages.push({
+                role: 'user',
+                content: buildRetryUserMessage({ findings: lastFindings, attempt }),
+            });
+        }
+    }
+    const latency_ms = Date.now() - t0;
+    const cost_usd = computeCost(model, { input: tokens_in, output: tokens_out });
+    /* Final fragment: if parsing failed all attempts, fall back to the
+       original source with no decorations. Otherwise reflect whatever
+       the last attempt produced -- the caller decides whether to act
+       on validation_findings (warn vs block) at aggregation time. */
+    if (!lastParsed) {
+        return {
+            relpath: opts.relpath,
+            decorated_jsx: opts.jsxSource,
+            elements: [],
+            plugin_slug_guess: opts.pluginSlugHint || 'unknown',
+            tokens_in,
+            tokens_out,
+            cost_usd,
+            latency_ms,
+            decorated: false,
+            attempts,
+            validation_findings: lastFindings,
+        };
+    }
+    return {
+        relpath: opts.relpath,
+        decorated_jsx: lastParsed.decorated_jsx || opts.jsxSource,
+        elements: Array.isArray(lastParsed.elements) ? lastParsed.elements : [],
+        plugin_slug_guess: lastParsed.plugin_slug || opts.pluginSlugHint || 'unknown',
+        route_map: (lastParsed.route_map && typeof lastParsed.route_map === 'object') ? lastParsed.route_map : undefined,
+        fixtures: (lastParsed.fixtures && typeof lastParsed.fixtures === 'object') ? lastParsed.fixtures : undefined,
+        router_kind: (lastParsed.router_kind === 'hash' || lastParsed.router_kind === 'memory' || lastParsed.router_kind === 'browser')
+            ? lastParsed.router_kind
+            : undefined,
+        i18n_catalog: (lastParsed.i18n_catalog && typeof lastParsed.i18n_catalog === 'object') ? lastParsed.i18n_catalog : undefined,
+        tokens_in,
+        tokens_out,
+        cost_usd,
+        latency_ms,
+        decorated: !!lastParsed.decorated,
+        attempts,
+        validation_findings: lastFindings,
+    };
+}
+/**
+ * Walk a project directory, decorate every JSX/TSX file, aggregate
+ * into a single manifest. Writes decorated files back in place (or
+ * to outDir when set). Sequential by default to keep API budgets
+ * predictable; can run with bounded concurrency via the
+ * `concurrency` option.
+ */
+export async function aiApplyProject(opts) {
+    const root = opts.subdir
+        ? path.join(opts.projectRoot, opts.subdir)
+        : opts.projectRoot;
+    /* Collect .jsx / .tsx files. */
+    const files = [];
+    async function walk(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const e of entries) {
+            const p = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist')
+                    continue;
+                await walk(p);
+            }
+            else if (/\.(jsx|tsx)$/.test(e.name)) {
+                files.push(p);
+            }
+        }
+    }
+    await walk(root);
+    const results = new Array(files.length);
+    const conc = Math.max(1, Math.min(opts.concurrency || 4, 8));
+    let next = 0;
+    async function worker() {
+        while (true) {
+            const i = next++;
+            if (i >= files.length)
+                return;
+            const abs = files[i];
+            const rel = path.relative(opts.projectRoot, abs);
+            const src = await fs.readFile(abs, 'utf-8');
+            const r = await aiApplyOne({
+                jsxSource: src,
+                relpath: rel,
+                pluginSlugHint: opts.pluginSlugHint,
+                model: opts.model,
+                withI18n: opts.withI18n,
+            });
+            results[i] = r;
+            if (opts.onProgress)
+                opts.onProgress(i + 1, files.length, rel, r);
+            if (!opts.dryRun && r.decorated) {
+                const dst = opts.outDir
+                    ? path.join(opts.outDir, rel)
+                    : abs;
+                await fs.mkdir(path.dirname(dst), { recursive: true });
+                await fs.writeFile(dst, r.decorated_jsx, 'utf-8');
+            }
+            else if (opts.outDir && !opts.dryRun) {
+                /* When outputting to a separate dir, copy the file verbatim
+                   even if undecorated so the project is complete. */
+                const outBase = opts.outDir;
+                const dst = path.join(outBase, rel);
+                await fs.mkdir(path.dirname(dst), { recursive: true });
+                await fs.writeFile(dst, src, 'utf-8');
+            }
+        }
+    }
+    const workers = Array.from({ length: conc }, () => worker());
+    await Promise.all(workers);
+    /* Pick canonical plugin slug: most common across non-empty
+       decorated files; tiebreak by first occurrence. */
+    const slugCount = {};
+    for (const r of results) {
+        if (!r || !r.plugin_slug_guess)
+            continue;
+        slugCount[r.plugin_slug_guess] = (slugCount[r.plugin_slug_guess] || 0) + 1;
+    }
+    let canonicalSlug = opts.pluginSlugHint || 'app';
+    let bestCount = -1;
+    for (const slug of Object.keys(slugCount)) {
+        const cnt = slugCount[slug] ?? 0;
+        if (cnt > bestCount) {
+            canonicalSlug = slug;
+            bestCount = cnt;
+        }
+    }
+    const combinedRouteMap = {};
+    for (const r of results) {
+        if (!r || !r.route_map)
+            continue;
+        for (const k of Object.keys(r.route_map)) {
+            const v = r.route_map[k];
+            if (v === undefined)
+                continue;
+            const norm = Array.isArray(v)
+                ? { paths: v, requires_auth: false }
+                : { paths: v.paths || [], requires_auth: !!v.requires_auth };
+            const existing = combinedRouteMap[k];
+            if (existing) {
+                existing.paths = Array.from(new Set([...existing.paths, ...norm.paths]));
+                existing.requires_auth = existing.requires_auth || norm.requires_auth;
+            }
+            else {
+                combinedRouteMap[k] = norm;
+            }
+        }
+    }
+    /* H1: infer mounted_at for elements that didn't declare it. The
+       heuristic: if the element's file path matches one of the
+       route_map keys, propagate the paths + requires_auth. */
+    function inferMountedFor(file) {
+        const candidates = Object.keys(combinedRouteMap);
+        const norm = file.replace(/\\/g, '/').replace(/^src\//, '').replace(/\.(jsx|tsx)$/, '');
+        for (const k of candidates) {
+            const nk = k.replace(/^\.\//, '').replace(/\.(jsx|tsx)$/, '');
+            if (norm === nk || norm.endsWith('/' + nk) || nk.endsWith('/' + norm)) {
+                return combinedRouteMap[k] || null;
+            }
+        }
+        return null;
+    }
+    /* Aggregate elements. Dedupe by id (later file wins, but warn).
+       H2: collect warnings from individual elements (reusable components
+       without qualifier) for surfacing at end-of-apply.
+       H1: fill mounted_at + requires_auth from route_map where the
+       element omitted them. */
+    const seen = {};
+    const elements = [];
+    const warnings = [];
+    for (const r of results) {
+        if (!r || !r.elements)
+            continue;
+        const fileInfer = inferMountedFor(r.relpath);
+        for (const el of r.elements) {
+            if (!el || !el.id)
+                continue;
+            if (el.warning) {
+                warnings.push({ file: r.relpath, id: el.id, warning: el.warning });
+            }
+            /* H1: fill mounted_at + requires_auth if missing. */
+            if ((!el.mounted_at || el.mounted_at.length === 0) && fileInfer) {
+                el.mounted_at = fileInfer.paths;
+                if (fileInfer.requires_auth && el.requires_auth === undefined) {
+                    el.requires_auth = true;
+                }
+            }
+            if (seen[el.id]) {
+                continue;
+            }
+            seen[el.id] = r;
+            elements.push(el);
+        }
+    }
+    /* H1.v3: aggregate fixtures across files. Multiple Router roots
+       could declare fixtures for the same :param; last write wins. */
+    const fixtures = {};
+    for (const r of results) {
+        if (!r || !r.fixtures)
+            continue;
+        for (const k of Object.keys(r.fixtures)) {
+            fixtures[k] = r.fixtures[k];
+        }
+    }
+    /* H1.v4: aggregate router_kind. Take the first non-undefined value
+       across all files. "hash" wins over "browser" if both were detected
+       (the Router root file's value is authoritative; this is just a
+       defensive fallback). */
+    let router_kind = undefined;
+    for (const r of results) {
+        if (!r || !r.router_kind)
+            continue;
+        if (!router_kind)
+            router_kind = r.router_kind;
+        else if (r.router_kind === 'hash')
+            router_kind = 'hash';
+    }
+    /* i18n: aggregate per-file catalogs into a single EN canonical, then
+       write i18n/<lang>.json under outDir (or projectRoot when outDir not
+       set). The EN catalog is the source of truth; other languages start
+       as a CLONE of EN so the keys are present; humans / downstream tools
+       translate the values. Collisions (same key, different value across
+       files) are resolved last-write-wins with a warning. */
+    const i18nCanonical = {};
+    const i18nWarnings = [];
+    if (opts.withI18n) {
+        for (const r of results) {
+            if (!r || !r.i18n_catalog)
+                continue;
+            for (const k of Object.keys(r.i18n_catalog)) {
+                const v = r.i18n_catalog[k];
+                if (v == null)
+                    continue;
+                if (i18nCanonical[k] != null && i18nCanonical[k] !== v) {
+                    i18nWarnings.push({
+                        file: r.relpath,
+                        key: k,
+                        old_value: i18nCanonical[k],
+                        new_value: v,
+                    });
+                }
+                i18nCanonical[k] = v;
+            }
+        }
+        if (!opts.dryRun) {
+            const langs = (opts.i18nLangs && opts.i18nLangs.length > 0)
+                ? opts.i18nLangs
+                : ['en', 'es', 'pt', 'fr', 'it', 'de', 'ja', 'zh', 'hi', 'ar'];
+            const targetRoot = opts.outDir || opts.projectRoot;
+            const i18nDir = path.join(targetRoot, 'i18n');
+            await fs.mkdir(i18nDir, { recursive: true });
+            /* en.json -- authoritative source from the AI extraction. */
+            await fs.writeFile(path.join(i18nDir, 'en.json'), JSON.stringify(i18nCanonical, null, 2), 'utf-8');
+            /* Other locales -- start as a clone of EN. The user fills in
+               translations downstream (manually or by another LLM pass).
+               An empty stub {} is misleading -- it would make the runtime
+               shim fall back to EN silently. Cloning EN makes the
+               missing-translation state visible (the value is still EN,
+               not blank). */
+            for (const lang of langs) {
+                if (lang === 'en')
+                    continue;
+                const langPath = path.join(i18nDir, lang + '.json');
+                /* If the file already exists, DO NOT overwrite -- it may
+                   contain real translations the user already authored. */
+                try {
+                    await fs.access(langPath);
+                    continue;
+                }
+                catch {
+                    /* not found -- fall through and write the EN clone */
+                }
+                await fs.writeFile(langPath, JSON.stringify(i18nCanonical, null, 2), 'utf-8');
+            }
+            /* index.json -- declares the available locale list for the
+               runtime shim. */
+            const indexPath = path.join(i18nDir, 'index.json');
+            try {
+                await fs.access(indexPath);
+                /* leave the existing index alone -- the user may have customised it */
+            }
+            catch {
+                const NATIVE_NAMES = {
+                    en: 'English', es: 'Español', pt: 'Português', fr: 'Français',
+                    it: 'Italiano', de: 'Deutsch', ja: '日本語', zh: '中文',
+                    hi: 'हिन्दी', ar: 'العربية',
+                };
+                const index = {
+                    default: 'en',
+                    available: langs.map(l => ({
+                        code: l,
+                        name: l.toUpperCase(),
+                        native: NATIVE_NAMES[l] || l,
+                    })),
+                };
+                await fs.writeFile(indexPath, JSON.stringify(index, null, 2), 'utf-8');
+            }
+        }
+    }
+    return {
+        files: results,
+        manifest: {
+            plugin_slug: canonicalSlug,
+            version: '1.0.0',
+            nac_version: '1.0',
+            label_i18n: { es: canonicalSlug, en: canonicalSlug },
+            elements,
+            ...(Object.keys(fixtures).length > 0 ? { fixtures } : {}),
+            ...(router_kind ? { router_kind } : {}),
+        },
+        warnings,
+        i18n_catalog: opts.withI18n ? i18nCanonical : undefined,
+        i18n_warnings: opts.withI18n ? i18nWarnings : undefined,
+        total_tokens_in: results.reduce((a, b) => a + (b?.tokens_in || 0), 0),
+        total_tokens_out: results.reduce((a, b) => a + (b?.tokens_out || 0), 0),
+        total_cost_usd: results.reduce((a, b) => a + (b?.cost_usd || 0), 0),
+        total_latency_ms: results.reduce((a, b) => a + (b?.latency_ms || 0), 0),
+        files_clean_first_attempt: results.reduce((a, b) => a + ((b?.attempts === 1 && (b?.validation_findings?.length || 0) === 0) ? 1 : 0), 0),
+        files_retried: results.reduce((a, b) => a + (((b?.attempts || 0) > 1) ? 1 : 0), 0),
+        files_gave_up: results.reduce((a, b) => a + (((b?.attempts || 0) >= AI_APPLY_MAX_ATTEMPTS
+            && (b?.validation_findings?.filter((f) => f.severity === 'error').length || 0) > 0) ? 1 : 0), 0),
+    };
+}
+//# sourceMappingURL=ai-apply.js.map