@nac3/forge-cli 0.2.0-alpha.1

package/dist/codegen/e2e.js

@@ -0,0 +1,931 @@
+/*
+ * src/codegen/e2e.ts
+ *
+ * E2E test corpus generator. Reads a NAC-3 manifest, builds an
+ * abstract TestPlan (framework-agnostic), then emits the actual
+ * test files in the requested framework's syntax.
+ *
+ * Supported frameworks (v1):
+ *   - playwright    (TypeScript, .spec.ts under tests/)
+ *   - cypress       (JavaScript, .cy.js under cypress/e2e/)
+ *   - vitest        (TypeScript, .test.ts with jsdom under tests/)
+ *   - wdio          (TypeScript, .test.ts under test/specs/)
+ *
+ * Coverage metric reported: "agent-relevant surface" -- one test
+ * per (nac_id, role, verb) tuple in the manifest. This is the
+ * honest number to publish (NOT line-coverage, which the manifest
+ * cannot guarantee).
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+export const ALL_FRAMEWORKS = ['playwright', 'cypress', 'vitest', 'wdio'];
+/* ----------------------------------------------------------
+ * Plan synthesis -- manifest -> TestPlan
+ * ---------------------------------------------------------- */
+export function planFromManifest(manifest, options) {
+    const plugin = manifest.plugin_slug || 'unknown';
+    const els = manifest.elements || [];
+    const cases = [];
+    let exercised = 0;
+    const fixtures = (manifest && manifest.fixtures) || {};
+    const haveFixtureFor = (param) => !!fixtures[param];
+    /* H1.v3: pick the test's visit route from el.mounted_at.
+       - empty / undefined -> default '/'
+       - ['*']             -> '/' (always-mounted top-level chrome)
+       - first entry with :params -> KEEP the params verbatim if every
+         :param has a fixture spec; the emitter will interpolate them
+         from the per-test aliases. If a :param lacks a fixture, fall
+         back to the v2 behaviour (strip the param).
+  
+       H1.v5: when mounted_at is missing, use keyword heuristics on the
+       element id to infer the most likely route. Reusable components
+       (ArticleEditorForm, FormFieldset, etc) get a sensible route
+       instead of defaulting to '/'. The heuristic checks routes
+       declared in the manifest's route_map (when present) and matches
+       by id substring; falls through to '/' only when nothing matches. */
+    function inferRouteFromId(id) {
+        const lower = id.toLowerCase();
+        /* Keyword -> candidate route patterns. Order matters: most
+           specific first.
+           Note: word boundaries (\b) only match between word and
+           non-word chars; for substrings flanked by underscores we
+           allow either \b or _ at either side. */
+        const rules = [
+            { keys: /(article_editor|publish_article|editor_form|\.field\.title|\.field\.description|\.field\.body|\.field\.tags)/, route: '/editor' },
+            { keys: /(delete_article|edit_article|favorite_article|article_meta|article_buttons|article_preview|edit_article_link|comment_author|delete_comment|follow_author|comment_body|post_comment|follow_button)/, route: '/article/:slug' },
+            { keys: /(signup|sign_up_form|auth_page_container__sign_up)/, route: '/register' },
+            { keys: /(login_form|login_page)/, route: '/login' },
+            { keys: /(edit_profile_settings|profile_articles|profile_fav|follow_user|fav_articles_preview|fav_articles_pagination)/, route: '/@:username' },
+            { keys: /\.settings\b|region\.settings\b/, route: '/settings' },
+            { keys: /(paginate|tag_button|feed_nav_link|feed_)/, route: '/' },
+            { keys: /(auth_link|dropdown_item|nav_item|form_fieldset)/, route: '/' },
+        ];
+        for (const r of rules) {
+            if (r.keys.test(lower))
+                return r.route;
+        }
+        return null;
+    }
+    function pickVisitRoute(el) {
+        let ma = el.mounted_at;
+        let raw;
+        if (!ma || ma.length === 0) {
+            const inferred = inferRouteFromId(el.id || '');
+            if (!inferred)
+                return { route: '/', params: [] };
+            raw = inferred;
+        }
+        else {
+            if (ma[0] === '*')
+                return { route: '/', params: [] };
+            /* H1.v6: when multiple mounted_at routes exist, prefer a
+               conventional `/segment/:param` over unusual prefixes like
+               `/@:param`. Most React Router apps don't use `@` as a path
+               segment; when both forms appear in mounted_at, the
+               conventional one is more likely to be the real route. When
+               only the `/@:x` form is present, rewrite it to `/profile/:x`
+               since that's the canonical RealWorld convention. */
+            const conventional = ma.find((r) => r !== '*' && !r.includes('@'));
+            raw = (conventional || ma[0]);
+            if (raw.startsWith('/@'))
+                raw = raw.replace(/^\/@/, '/profile/');
+        }
+        const paramTokens = Array.from(raw.matchAll(/:([a-zA-Z_][a-zA-Z0-9_]*)/g)).map(m => ':' + m[1]);
+        if (paramTokens.length === 0)
+            return { route: raw, params: [] };
+        const allHaveFixture = paramTokens.every(haveFixtureFor);
+        if (allHaveFixture) {
+            return { route: raw, params: paramTokens };
+        }
+        /* At least one :param has no fixture spec -- strip them all and
+           fall back to the param-less prefix. */
+        return { route: raw.replace(/:[a-zA-Z_][a-zA-Z0-9_]*/g, ''), params: [] };
+    }
+    for (const el of els) {
+        if (!el || !el.id)
+            continue;
+        /* H1.v5: skip region_present tests for elements that --ai-apply
+           flagged as marker-only ("covers the outer container region",
+           "marks the mount point"). The region id never reaches the
+           DOM; testing presence is a guaranteed false-positive failure.
+           Field / action / tab tests on warned elements ARE kept --
+           they may now resolve after operator-level FormFieldset-style
+           prop-forwarding fixes. The warning list shipped at apply-time
+           remains the canonical audit trail. */
+        const isMarkerRegion = (el.role === 'region') && !!el.warning;
+        if (isMarkerRegion)
+            continue;
+        /* H1.v6: skip presence-checking tests for elements whose
+           manifest entry is a TEMPLATE (carries instance_pattern). Such
+           entries are never in DOM unsuffixed -- DOM has the qualified
+           instances only (`conduit.field.form_fieldset__title` etc).
+           region_present + field_read + tab_switch on the bare id are
+           guaranteed false negatives. Action/field_write tests with
+           qualifier wiring (H1.v6 below) can still resolve. */
+        const isTemplate = !!el.instance_pattern;
+        const role = el.role;
+        const id = el.id;
+        const picked = pickVisitRoute(el);
+        const visit_route = picked.route;
+        const fixture_params = picked.params.length ? picked.params : undefined;
+        const requires_auth = !!el.requires_auth;
+        if (role === 'action') {
+            const verbs = (el.actions || []).map((a) => a && a.verb).filter(Boolean);
+            /* H1.v6: when this element is a template, derive a qualifier
+               alias from the first fixture param. The emitter wraps the
+               test in a cy.get('@alias').then() and forwards the value
+               as opts.qualifier to NAC.click_by_verb. */
+            const qualifier_alias = (isTemplate && fixture_params && fixture_params.length > 0)
+                ? fixture_params[0].replace(/^:/, '')
+                : undefined;
+            for (const verb of verbs) {
+                /* H1.v5: skip verbs that mutate global session state (logout
+                   drops the JWT, signup creates a new user, save on a
+                   settings-shaped page rewrites the current user's password
+                   with the value of empty/inputted fields). Without a
+                   per-test user reset, these tests poison every test that
+                   follows. Operator can opt back in via --include-session
+                   when test isolation is in place. */
+                const sessionMutating = /^(logout|signup|save)$/i.test(verb);
+                if (sessionMutating)
+                    continue;
+                /* H1.v6 item 4: verbs that require viewer != author. The
+                   target object (e.g. an article) must be authored by
+                   someone OTHER than the test user; otherwise the affected
+                   UI element doesn't render. The emitter wires a secondary
+                   user into the fixture create path. */
+                const viewer_role = /^(follow|unfollow|favorite|unfavorite)$/i.test(verb) && qualifier_alias
+                    ? 'secondary_author'
+                    : 'primary';
+                cases.push({
+                    id: 'action__' + id.replace(/\./g, '_') + '__' + verb,
+                    kind: 'action_dispatch',
+                    name: 'dispatches ' + plugin + '.' + verb,
+                    plugin, nac_id: id, verb,
+                    visit_route, requires_auth, fixture_params, qualifier_alias,
+                    viewer_role,
+                });
+            }
+            exercised++;
+        }
+        else if (role === 'field') {
+            /* H1.v6: skip field_read for templates -- bare id never in DOM. */
+            if (!isTemplate)
+                cases.push({
+                    id: 'field_read__' + id.replace(/\./g, '_'),
+                    kind: 'field_read',
+                    name: 'reads ' + id,
+                    plugin, nac_id: id,
+                    visit_route, requires_auth, fixture_params,
+                });
+            /* H1.v5: skip field_write for credential / identity fields.
+               Their values mutate the test user's session and break every
+               subsequent test that relies on the same login. Sample
+               inputs cannot be made round-trip-safe without app-specific
+               knowledge of the save endpoint. Operator can opt back in
+               via --include-credentials when they accept the side effect. */
+            const isCredential = /password|email|username|api[-_]?key|token/i.test(id);
+            if (!isCredential && /input|edit|name|title|search|comment|body/i.test(id)) {
+                cases.push({
+                    id: 'field_write__' + id.replace(/\./g, '_'),
+                    kind: 'field_write',
+                    name: 'writes to ' + id,
+                    plugin, nac_id: id,
+                    /* Deterministic per-id seed instead of Math.random so the
+                       suite is byte-reproducible across runs. */
+                    sample_input: 'forge-e2e-' + id.length.toString(36) + 'v' + (id.split('.').length),
+                    visit_route, requires_auth, fixture_params,
+                });
+            }
+            exercised++;
+        }
+        else if (role === 'tab') {
+            /* H1.v6: skip tab_switch for templates -- DOM has only qualified
+               instances. NAC.tab() runtime fallback handles base→qualified
+               when the QUALIFIED siblings carry a known prefix, but for
+               pure templates (like conduit.tab.feed_nav_link) there is no
+               agent-meaningful target without picking an instance. */
+            if (!isTemplate)
+                cases.push({
+                    id: 'tab__' + id.replace(/\./g, '_'),
+                    kind: 'tab_switch',
+                    name: 'switches to tab ' + id,
+                    plugin, nac_id: id,
+                    visit_route, requires_auth, fixture_params,
+                });
+            exercised++;
+        }
+        else if (role === 'region') {
+            /* H1.v6: skip region_present for templates -- bare id never in DOM. */
+            if (!isTemplate)
+                cases.push({
+                    id: 'region__' + id.replace(/\./g, '_'),
+                    kind: 'region_present',
+                    name: 'region ' + id + ' is present',
+                    plugin, nac_id: id,
+                    visit_route, requires_auth, fixture_params,
+                });
+            exercised++;
+        }
+        else if (role === 'navigation') {
+            const verbs = (el.actions || []).map((a) => a && a.verb).filter(Boolean);
+            if (verbs.length === 0) {
+                cases.push({
+                    id: 'nav__' + id.replace(/\./g, '_'),
+                    kind: 'action_dispatch',
+                    name: 'nav ' + id + ' present',
+                    plugin, nac_id: id, verb: 'navigate',
+                    visit_route, requires_auth, fixture_params,
+                });
+            }
+            else {
+                for (const verb of verbs) {
+                    cases.push({
+                        id: 'nav__' + id.replace(/\./g, '_') + '__' + verb,
+                        kind: 'action_dispatch',
+                        name: 'navigates ' + plugin + '.' + verb,
+                        plugin, nac_id: id, verb,
+                        visit_route, requires_auth, fixture_params,
+                    });
+                }
+            }
+            exercised++;
+        }
+    }
+    const rk = manifest && manifest.router_kind;
+    const router_kind = (rk === 'hash' || rk === 'memory' || rk === 'browser') ? rk : undefined;
+    return {
+        plugin,
+        manifest_path: 'manifest.json',
+        page_url_token: options?.pageUrlToken || 'http://localhost:3000',
+        cases,
+        total_elements: els.length,
+        exercised_elements: exercised,
+        fixtures: Object.keys(fixtures).length > 0 ? fixtures : undefined,
+        router_kind,
+    };
+}
+/* ----------------------------------------------------------
+ * Auto-detect a framework from the target dir
+ * ---------------------------------------------------------- */
+export async function detectFramework(targetDir) {
+    const checks = [
+        { file: 'playwright.config.ts', framework: 'playwright' },
+        { file: 'playwright.config.js', framework: 'playwright' },
+        { file: 'cypress.config.ts', framework: 'cypress' },
+        { file: 'cypress.config.js', framework: 'cypress' },
+        { file: 'cypress.json', framework: 'cypress' }, // legacy cypress
+        { file: 'vitest.config.ts', framework: 'vitest' },
+        { file: 'vitest.config.js', framework: 'vitest' },
+        { file: 'wdio.conf.ts', framework: 'wdio' },
+        { file: 'wdio.conf.js', framework: 'wdio' },
+    ];
+    for (const ch of checks) {
+        const ok = await fs.stat(path.join(targetDir, ch.file)).then(() => true, () => false);
+        if (ok)
+            return ch.framework;
+    }
+    /* Also look in subdirs cypress/, e2e/. */
+    const cypress = await fs.stat(path.join(targetDir, 'cypress')).then(() => true, () => false);
+    if (cypress)
+        return 'cypress';
+    return null;
+}
+export function emitPlaywright(plan, opts) {
+    const baseUrl = opts?.baseUrl || plan.page_url_token;
+    const body = [
+        '/* Auto-generated by Yujin Forge -- e2e test corpus.',
+        ' * Plugin: ' + plan.plugin,
+        ' * Surface coverage: ' + plan.exercised_elements + ' / ' + plan.total_elements + ' manifest elements.',
+        ' * Framework: Playwright. Re-generate with: yf gen-tests <dir> --framework playwright',
+        ' */',
+        "import { test, expect } from '@playwright/test';",
+        "",
+        "const BASE_URL = process.env.FORGE_E2E_BASE_URL || '" + baseUrl + "';",
+        "",
+        "async function gotoAndWait(page) {",
+        "  await page.goto(BASE_URL, { waitUntil: 'networkidle' });",
+        "  await page.waitForFunction(",
+        "    (slug) => !!(window.NAC && window.NAC.list_registered_plugins().includes(slug)),",
+        "    '" + plan.plugin + "',",
+        "    { timeout: 10000 }",
+        "  );",
+        "}",
+        "",
+    ];
+    for (const tc of plan.cases) {
+        if (tc.kind === 'action_dispatch') {
+            body.push("test('" + tc.name + "', async ({ page }) => {");
+            body.push("  await gotoAndWait(page);");
+            body.push("  const result = await page.evaluate(async (v) => {");
+            body.push("    try { await window.NAC.click_by_verb('" + tc.plugin + "', v); return { ok: true }; }");
+            body.push("    catch (e) { return { ok: false, error: String(e.message || e) }; }");
+            body.push("  }, '" + tc.verb + "');");
+            body.push("  expect(result.ok, JSON.stringify(result)).toBe(true);");
+            body.push("});");
+            body.push("");
+        }
+        else if (tc.kind === 'field_read') {
+            body.push("test('" + tc.name + "', async ({ page }) => {");
+            body.push("  await gotoAndWait(page);");
+            body.push("  const el = await page.$('[data-nac-id=\"" + tc.nac_id + "\"]');");
+            body.push("  expect(el, 'Element " + tc.nac_id + " not found').not.toBeNull();");
+            body.push("});");
+            body.push("");
+        }
+        else if (tc.kind === 'field_write') {
+            body.push("test('" + tc.name + "', async ({ page }) => {");
+            body.push("  await gotoAndWait(page);");
+            body.push("  const result = await page.evaluate(async (id, val) => {");
+            body.push("    try { await window.NAC.fill(id, val); return { ok: true }; }");
+            body.push("    catch (e) { return { ok: false, error: String(e.message || e) }; }");
+            body.push("  }, '" + tc.nac_id + "', '" + tc.sample_input + "');");
+            body.push("  expect(result.ok, JSON.stringify(result)).toBe(true);");
+            body.push("});");
+            body.push("");
+        }
+        else if (tc.kind === 'tab_switch') {
+            body.push("test('" + tc.name + "', async ({ page }) => {");
+            body.push("  await gotoAndWait(page);");
+            body.push("  const result = await page.evaluate(async (id) => {");
+            body.push("    try { await window.NAC.tab(id); return { ok: true }; }");
+            body.push("    catch (e) { return { ok: false, error: String(e.message || e) }; }");
+            body.push("  }, '" + tc.nac_id + "');");
+            body.push("  expect(result.ok, JSON.stringify(result)).toBe(true);");
+            body.push("});");
+            body.push("");
+        }
+        else if (tc.kind === 'region_present') {
+            body.push("test('" + tc.name + "', async ({ page }) => {");
+            body.push("  await gotoAndWait(page);");
+            body.push("  const el = await page.$('[data-nac-id=\"" + tc.nac_id + "\"]');");
+            body.push("  expect(el, 'Region " + tc.nac_id + " not found').not.toBeNull();");
+            body.push("});");
+            body.push("");
+        }
+    }
+    return [{ relpath: 'tests/forge-e2e/' + plan.plugin + '.spec.ts', content: body.join('\n') }];
+}
+export function emitCypress(plan, opts) {
+    const baseUrl = (opts?.baseUrl || plan.page_url_token).replace(/\/$/, '');
+    const fixtures = plan.fixtures || {};
+    const body = [
+        '/* Auto-generated by Yujin Forge -- e2e test corpus.',
+        ' * Plugin: ' + plan.plugin,
+        ' * Surface coverage: ' + plan.exercised_elements + ' / ' + plan.total_elements + ' manifest elements.',
+        ' * Framework: Cypress. Re-generate with: yf gen-tests <dir> --framework cypress',
+        ' * H1.v3: each test that needs dynamic-route data CREATEs the',
+        ' * resource via API in beforeEach + DELETEs in afterEach so the',
+        ' * suite is reproducible from a clean DB. Seed is deterministic',
+        ' * (test index), never random.',
+        ' */',
+        "const BASE_URL = Cypress.env('FORGE_E2E_BASE_URL') || '" + baseUrl + "';",
+        "/* H1.v4: Router kind from manifest. 'hash' -> cy.visit prefixes",
+        "   the route with '#' so SPA hash router engages. */",
+        "const ROUTER_KIND = '" + (plan.router_kind || 'browser') + "';",
+        "const FORGE_TEST_USER = Cypress.env('FORGE_TEST_USER') || {",
+        "  email: 'forge-e2e@yujin.app',",
+        "  password: 'forge-e2e-2026',",
+        "  username: 'forge_e2e'",
+        "};",
+        "/* H1.v6 item 4 -- secondary user for multi-user fixtures.",
+        "   Verbs like follow_author / favorite_article require the viewer",
+        "   to differ from the author. This second user authors fixtures",
+        "   that the primary test user then interacts with. Deterministic",
+        "   credentials, idempotent registration. */",
+        "const FORGE_TEST_USER2 = Cypress.env('FORGE_TEST_USER2') || {",
+        "  email: 'forge-e2e-other@yujin.app',",
+        "  password: 'forge-e2e-2026',",
+        "  username: 'forge_e2e_other'",
+        "};",
+        "",
+        "function ensureTestUser(user) {",
+        "  /* Idempotent: register if absent, ignore conflict. */",
+        "  cy.request({",
+        "    method: 'POST',",
+        "    url: BASE_URL + '/api/users',",
+        "    body: { user: user || FORGE_TEST_USER },",
+        "    failOnStatusCode: false,",
+        "  });",
+        "}",
+        "function loginAs(user) {",
+        "  /* Login as the supplied user and snapshot the resulting token",
+        "     into Cypress.env. Used by secondary-author fixtures to create",
+        "     fixtures as user2, then swap back to user1 before the it() body.",
+        "     H1.v6 stabilizer: tokens are cached per-user in",
+        "     Cypress.env('FORGE_AUTH_TOKEN_' + email). The cache survives",
+        "     for the entire spec run since JWT lifetimes far exceed it.",
+        "     This eliminates the multi-user login race: switching users",
+        "     becomes a synchronous env swap, not a fresh HTTP round-trip.",
+        "     Cy.env writes outside cy.then() execute IMMEDIATELY in queue",
+        "     order, so the env is always swapped before the next command. */",
+        "  const cacheKey = 'FORGE_AUTH_TOKEN_' + user.email;",
+        "  const cached = Cypress.env(cacheKey);",
+        "  if (cached) {",
+        "    Cypress.env('FORGE_AUTH_TOKEN', cached);",
+        "    return cy.wrap(cached, { log: false });",
+        "  }",
+        "  return cy.request({",
+        "    method: 'POST',",
+        "    url: BASE_URL + '/api/users/login',",
+        "    body: { user: { email: user.email, password: user.password } },",
+        "    failOnStatusCode: false,",
+        "  }).then((resp) => {",
+        "    if (resp.status !== 200 || !resp.body || !resp.body.user) return null;",
+        "    const tok = resp.body.user.token;",
+        "    Cypress.env(cacheKey, tok);",
+        "    Cypress.env('FORGE_AUTH_TOKEN', tok);",
+        "    return tok;",
+        "  });",
+        "}",
+        "",
+        "/* loginViaApi caches the token under Cypress.env so subsequent",
+        "   cy.request calls (fixture CREATE / DELETE) can include the",
+        "   Authorization header. Also drops the SPA-shaped wrapper into",
+        "   localStorage so cy.visit boots already logged-in. */",
+        "function loginViaApi() {",
+        "  /* H1.v6 stabilizer: same caching strategy as loginAs(). When the",
+        "     primary user token is already cached, swap env synchronously. */",
+        "  const cacheKey = 'FORGE_AUTH_TOKEN_' + FORGE_TEST_USER.email;",
+        "  const cached = Cypress.env(cacheKey);",
+        "  if (cached) {",
+        "    Cypress.env('FORGE_AUTH_TOKEN', cached);",
+        "    return cy.wrap(cached, { log: false });",
+        "  }",
+        "  return cy.request({",
+        "    method: 'POST',",
+        "    url: BASE_URL + '/api/users/login',",
+        "    body: { user: { email: FORGE_TEST_USER.email, password: FORGE_TEST_USER.password } },",
+        "    failOnStatusCode: false,",
+        "  }).then((resp) => {",
+        "    if (resp.status !== 200 || !resp.body || !resp.body.user) return null;",
+        "    const user = resp.body.user;",
+        "    Cypress.env(cacheKey, user.token);",
+        "    Cypress.env('FORGE_AUTH_TOKEN', user.token);",
+        "    return user.token;",
+        "  });",
+        "}",
+        "function authHeaders() {",
+        "  const t = Cypress.env('FORGE_AUTH_TOKEN');",
+        "  return t ? { Authorization: 'Token ' + t } : {};",
+        "}",
+        "",
+        "function gotoAndWait(route) {",
+        "  const r = route || '/';",
+        "  /* HashRouter: cy.visit must hit BASE_URL/#/<route>. */",
+        "  const url = ROUTER_KIND === 'hash' ? (BASE_URL + '/#' + r) : (BASE_URL + r);",
+        "  /* Auth-screen routes must always render as unauth. Skip seeding. */",
+        "  const isAuthScreen = /^\\/(login|register|signup|sign-up|sign_up)\\b/.test(r);",
+        "  const tok = isAuthScreen ? null : Cypress.env('FORGE_AUTH_TOKEN');",
+        "  if (tok) {",
+        "    cy.visit(url, {",
+        "      onBeforeLoad(win) {",
+        "        const u = " + JSON.stringify({ email: 'forge-e2e@yujin.app', username: 'forge_e2e' }) + ";",
+        "        const wrapper = { headers: { Authorization: 'Token ' + tok }, isAuth: true, loggedUser: Object.assign({}, u, { token: tok }) };",
+        "        win.localStorage.setItem('loggedUser', JSON.stringify(wrapper));",
+        "      },",
+        "    });",
+        "  } else {",
+        "    cy.visit(url);",
+        "  }",
+        "  cy.window({ timeout: 10000 }).should((win) => {",
+        "    expect(win.NAC).to.exist;",
+        "    expect(win.NAC.list_registered_plugins()).to.include('" + plan.plugin + "');",
+        "  });",
+        "  /* H1.v6: NAC manifest registration fires when nac.browser.js",
+        "     evaluates -- BEFORE React renders the route's content. For",
+        "     parametric routes (article/:slug, @:username) the route's",
+        "     component fetches data asynchronously; the action buttons",
+        "     mount only after that resolves. Wait until the DOM has at",
+        "     least one decorated INTERACTIVE element (data-nac-action),",
+        "     not just any data-nac-id (some top-level nav exists at all",
+        "     routes and would satisfy the looser check). */",
+        "  if (/:[a-zA-Z]/.test(r)) {",
+        "    cy.document({ timeout: 8000 }).should((doc) => {",
+        "      const n = doc.querySelectorAll('[data-nac-action]').length;",
+        "      expect(n, 'data-nac-action element count').to.be.greaterThan(5);",
+        "    });",
+        "  }",
+        "}",
+        "",
+        "/* H1.v3 helpers: deterministic seed + dotted-path get/set. */",
+        "function getByPath(obj, path) {",
+        "  if (!obj || !path) return undefined;",
+        "  return path.split('.').reduce((a, k) => (a == null ? a : a[k]), obj);",
+        "}",
+        "function setByPath(obj, path, value) {",
+        "  const parts = path.split('.'); let o = obj;",
+        "  for (let i = 0; i < parts.length - 1; i++) { if (o[parts[i]] == null) o[parts[i]] = {}; o = o[parts[i]]; }",
+        "  o[parts[parts.length - 1]] = value;",
+        "}",
+        "function applySeedToPayload(payload, uniqueCsv, seed) {",
+        "  const cloned = JSON.parse(JSON.stringify(payload));",
+        "  if (!uniqueCsv) return cloned;",
+        "  uniqueCsv.split(',').map(s => s.trim()).filter(Boolean).forEach(p => {",
+        "    const v = getByPath(cloned, p);",
+        "    if (typeof v === 'string') setByPath(cloned, p, v.replace(/\\{seed\\}/g, String(seed)));",
+        "  });",
+        "  /* Also any string value in the cloned payload that still contains {seed} gets substituted. */",
+        "  (function walk(node) {",
+        "    if (node == null) return;",
+        "    if (Array.isArray(node)) { node.forEach((v, i) => { if (typeof v === 'string' && v.indexOf('{seed}') >= 0) node[i] = v.replace(/\\{seed\\}/g, String(seed)); else walk(v); }); return; }",
+        "    if (typeof node === 'object') Object.keys(node).forEach(k => { if (typeof node[k] === 'string' && node[k].indexOf('{seed}') >= 0) node[k] = node[k].replace(/\\{seed\\}/g, String(seed)); else walk(node[k]); });",
+        "  })(cloned);",
+        "  return cloned;",
+        "}",
+        "function splitMethodPath(endpoint) {",
+        "  const m = String(endpoint || '').match(/^(\\S+)\\s+(.+)$/);",
+        "  return m ? { method: m[1].toUpperCase(), path: m[2] } : null;",
+        "}",
+        "",
+        "/* Fixtures spec emitted by Forge --ai-apply. Static literal so the",
+        "   suite is reproducible byte-by-byte. */",
+        "const FIXTURES = " + JSON.stringify(fixtures, null, 2) + ";",
+        "",
+        "/* H1.v6: purge stale fixture articles from BOTH test users before",
+        "   the suite runs. A test that crashed mid-it() leaves an article",
+        "   behind; the next run hits 'slug already taken' and the fixture",
+        "   captures undefined as the slug -> downstream tests fail with",
+        "   qualifier=undefined. The purge is a one-time sweep over both",
+        "   users' authored articles via cy.request to /api/articles. */",
+        "function purgeFixtureArticles(user) {",
+        "  return cy.request({",
+        "    method: 'POST',",
+        "    url: BASE_URL + '/api/users/login',",
+        "    body: { user: { email: user.email, password: user.password } },",
+        "    failOnStatusCode: false,",
+        "  }).then((loginResp) => {",
+        "    if (loginResp.status !== 200) return;",
+        "    const tok = loginResp.body.user.token;",
+        "    return cy.request({",
+        "      method: 'GET',",
+        "      url: BASE_URL + '/api/articles?author=' + encodeURIComponent(user.username) + '&limit=100',",
+        "      headers: { Authorization: 'Token ' + tok },",
+        "      failOnStatusCode: false,",
+        "    }).then((listResp) => {",
+        "      const arts = (listResp.body && listResp.body.articles) || [];",
+        "      arts.forEach((a) => {",
+        "        cy.request({",
+        "          method: 'DELETE',",
+        "          url: BASE_URL + '/api/articles/' + a.slug,",
+        "          headers: { Authorization: 'Token ' + tok },",
+        "          failOnStatusCode: false,",
+        "        });",
+        "      });",
+        "    });",
+        "  });",
+        "}",
+        "/* H1.v6 item 5 -- minimal seed data for pagination/filter tests.",
+        "   Creates a small set of articles under FORGE_TEST_USER so the",
+        "   home feed has > 1 page and tags exist. Without this seed,",
+        "   ArticlesPagination doesn't mount (no second page) and the tag",
+        "   list is empty. Deterministic titles -> deterministic slugs. */",
+        "function seedHomeFeed() {",
+        "  return cy.request({",
+        "    method: 'POST',",
+        "    url: BASE_URL + '/api/users/login',",
+        "    body: { user: { email: FORGE_TEST_USER.email, password: FORGE_TEST_USER.password } },",
+        "    failOnStatusCode: false,",
+        "  }).then((loginResp) => {",
+        "    if (loginResp.status !== 200) return;",
+        "    const tok = loginResp.body.user.token;",
+        "    /* 12 articles to guarantee pagination (default 10/page). */",
+        "    for (let i = 1; i <= 12; i++) {",
+        "      cy.request({",
+        "        method: 'POST',",
+        "        url: BASE_URL + '/api/articles',",
+        "        headers: { Authorization: 'Token ' + tok },",
+        "        body: { article: { title: 'Forge seed ' + i, description: 'seed-' + i,",
+        "          body: 'Seed article body ' + i, tagList: i % 2 === 0 ? ['forge', 'seed'] : ['forge'] } },",
+        "        failOnStatusCode: false,",
+        "      });",
+        "    }",
+        "  });",
+        "}",
+        "/* H1.v6 stabilizer: warm the token cache for both users up-front.",
+        "   Subsequent loginAs / loginViaApi calls are instant env swaps,",
+        "   eliminating the per-test login race that drove ±2-test variance",
+        "   between runs. */",
+        "function warmTokenCache(user) {",
+        "  return cy.request({",
+        "    method: 'POST',",
+        "    url: BASE_URL + '/api/users/login',",
+        "    body: { user: { email: user.email, password: user.password } },",
+        "    failOnStatusCode: false,",
+        "  }).then((resp) => {",
+        "    if (resp.status === 200 && resp.body && resp.body.user) {",
+        "      Cypress.env('FORGE_AUTH_TOKEN_' + user.email, resp.body.user.token);",
+        "    }",
+        "  });",
+        "}",
+        "before(() => {",
+        "  ensureTestUser(FORGE_TEST_USER);",
+        "  ensureTestUser(FORGE_TEST_USER2);",
+        "  warmTokenCache(FORGE_TEST_USER);",
+        "  warmTokenCache(FORGE_TEST_USER2);",
+        "  purgeFixtureArticles(FORGE_TEST_USER);",
+        "  purgeFixtureArticles(FORGE_TEST_USER2);",
+        "  seedHomeFeed();",
+        "});",
+        "/* H1.v6: Cypress.env persists across tests. Tests that visit auth",
+        "   screens (/login, /register) should NOT inherit a prior test's",
+        "   token, since the page would render the logged-in redirect. The",
+        "   gotoAndWait function skips localStorage seeding for these routes",
+        "   even when Cypress.env still has a token. */",
+        "",
+        "describe('" + plan.plugin + " -- Forge e2e corpus', () => {",
+    ];
+    /* Emit each test. Tests with fixture_params get a per-test
+       beforeEach (create) + afterEach (delete). Tests without
+       fixture_params keep the simple shape from H1.v2. */
+    let testIndex = 0;
+    for (const tc of plan.cases) {
+        testIndex++;
+        const route = tc.visit_route || '/';
+        const params = tc.fixture_params || [];
+        const hasFixtures = params.length > 0;
+        if (hasFixtures) {
+            /* Open a context() to scope beforeEach / afterEach. */
+            body.push("  context('" + tc.name + " (with fixtures)', () => {");
+            /* Per-test deterministic seed: stable hash of test index. */
+            body.push("    const SEED = " + testIndex + ";");
+            /* beforeEach: create one resource per :param.
+               H1.v6 item 4: for viewer_role='secondary_author', the fixture
+               is created by FORGE_TEST_USER2 so the primary test user can
+               interact with it (follow/favorite/unfollow logic requires
+               viewer != author). After the fixture is created, swap back
+               to the primary user. */
+            const secondaryAuthor = tc.viewer_role === 'secondary_author';
+            body.push("    beforeEach(() => {");
+            if (secondaryAuthor) {
+                body.push("      loginAs(FORGE_TEST_USER2);");
+            }
+            else if (tc.requires_auth || params.some(p => fixtures[p] && fixtures[p].requires_auth)) {
+                body.push("      loginViaApi();");
+            }
+            for (const p of params) {
+                const spec = fixtures[p];
+                if (!spec)
+                    continue;
+                const alias = p.replace(/^:/, '');
+                const useAuth = !!spec.requires_auth;
+                /* H1.v3: wrap inside cy.then() so authHeaders() is evaluated
+                   AFTER loginViaApi() has populated Cypress.env -- not at
+                   the synchronous emit-time of the test body. */
+                body.push("      cy.then(() => {");
+                body.push("        const spec = FIXTURES['" + p + "'];");
+                body.push("        const mp = splitMethodPath(spec.create_endpoint);");
+                body.push("        const payload = applySeedToPayload(spec.create_payload, spec.unique_suffix_field, SEED);");
+                body.push("        return cy.request({ method: mp.method, url: BASE_URL + mp.path, body: payload, headers: " + (useAuth ? "authHeaders()" : "{}") + ", failOnStatusCode: false })");
+                body.push("          .then((resp) => { const v = getByPath(resp.body, spec.response_path); cy.wrap(v).as('" + alias + "'); });");
+                body.push("      });");
+            }
+            if (secondaryAuthor) {
+                /* Swap back to primary so the it() body runs as the viewer. */
+                body.push("      loginViaApi();");
+            }
+            body.push("    });");
+            /* afterEach: delete each resource (idempotent). */
+            const anyDeletable = params.some(p => fixtures[p] && fixtures[p].delete_endpoint);
+            if (anyDeletable) {
+                body.push("    afterEach(() => {");
+                for (const p of params) {
+                    const spec = fixtures[p];
+                    if (!spec || !spec.delete_endpoint)
+                        continue;
+                    const alias = p.replace(/^:/, '');
+                    const useAuth = !!spec.requires_auth;
+                    /* afterEach: also defer authHeaders() into the cy.then closure. */
+                    body.push("      cy.get('@" + alias + "').then((val) => {");
+                    body.push("        const spec = FIXTURES['" + p + "'];");
+                    body.push("        const mp = splitMethodPath(spec.delete_endpoint.replace(/\\{value\\}/g, String(val)));");
+                    body.push("        const hdrs = " + (useAuth ? "authHeaders()" : "{}") + ";");
+                    body.push("        cy.request({ method: mp.method, url: BASE_URL + mp.path, headers: hdrs, failOnStatusCode: false });");
+                    body.push("      });");
+                }
+                body.push("    });");
+            }
+            /* The it() body: visit interpolated route + dispatch. */
+            body.push("    it('" + tc.name + "', () => {");
+            /* Build a sequence that resolves each alias into a local var
+               then visits the route with placeholders substituted. */
+            const aliases = params.map(p => p.replace(/^:/, ''));
+            if (aliases.length === 1) {
+                const a = aliases[0];
+                const pName = params[0];
+                body.push("      cy.get('@" + a + "').then((" + a + ") => {");
+                body.push("        const route = '" + route + "'.replace('" + pName + "', String(" + a + "));");
+                body.push("        gotoAndWait(route);");
+                emitBodyDispatch(body, tc, '        ');
+                body.push("      });");
+            }
+            else {
+                body.push("      cy.then(function () {");
+                body.push("        const route = " + JSON.stringify(route) + "");
+                for (const p of params) {
+                    const a = p.replace(/^:/, '');
+                    body.push("          .replace('" + p + "', String(this." + a + "))");
+                }
+                body.push("        ; gotoAndWait(route);");
+                emitBodyDispatch(body, tc, '        ');
+                body.push("      });");
+            }
+            body.push("    });");
+            body.push("  });");
+        }
+        else {
+            /* No fixtures needed. Single it(). */
+            body.push("  it('" + tc.name + "', () => {");
+            if (tc.requires_auth)
+                body.push("    loginViaApi();");
+            body.push("    gotoAndWait('" + route + "');");
+            emitBodyDispatch(body, tc, '    ');
+            body.push("  });");
+        }
+    }
+    body.push("});");
+    return [{ relpath: 'cypress/e2e/forge/' + plan.plugin + '.cy.js', content: body.join('\n') }];
+}
+/* Helper -- emit the dispatch portion of a test's it() body. */
+function emitBodyDispatch(body, tc, indent) {
+    /* H1.v6: when this test carries a qualifier_alias (template-id action
+       with a per-test fixture value), forward that value to NAC as
+       opts.qualifier so click_by_verb resolves to the right
+       dynamically-qualified DOM instance (e.g. distinguishing
+       delete_article from delete_comment, follow_author from follow_user). */
+    const q = tc.qualifier_alias;
+    /* H1.v6 item 4: for secondary-author fixtures the qualifier alias
+       is the article slug, but the actual DOM qualifier on follow_author
+       / favorite_article is author.username -- the alias doesn't match
+       the runtime suffix. Skip the qualifier; click_by_verb picks the
+       first DOM match, which is the only follow button on the page
+       (the secondary author's). */
+    const useQualifier = q && tc.viewer_role !== 'secondary_author';
+    if (tc.kind === 'action_dispatch') {
+        if (q || tc.viewer_role === 'secondary_author') {
+            /* Wait for the action target to render before clicking. */
+            body.push(indent + "cy.get('[data-nac-action=\"" + tc.verb + "\"]', { timeout: 8000 }).should('exist');");
+        }
+        body.push(indent + "cy.window().then(async (win) => {");
+        if (useQualifier) {
+            body.push(indent + "  const qval = String(" + q + ");");
+            body.push(indent + "  await win.NAC.click_by_verb('" + tc.plugin + "', '" + tc.verb + "', { qualifier: qval });");
+        }
+        else {
+            body.push(indent + "  await win.NAC.click_by_verb('" + tc.plugin + "', '" + tc.verb + "');");
+        }
+        body.push(indent + "});");
+    }
+    else if (tc.kind === 'field_read' || tc.kind === 'region_present') {
+        body.push(indent + "cy.get('[data-nac-id=\"" + tc.nac_id + "\"]').should('exist');");
+    }
+    else if (tc.kind === 'field_write') {
+        body.push(indent + "cy.window().then(async (win) => {");
+        body.push(indent + "  await win.NAC.fill('" + tc.nac_id + "', '" + tc.sample_input + "');");
+        body.push(indent + "});");
+    }
+    else if (tc.kind === 'tab_switch') {
+        body.push(indent + "cy.window().then(async (win) => {");
+        body.push(indent + "  await win.NAC.tab('" + tc.nac_id + "');");
+        body.push(indent + "});");
+    }
+}
+export function emitVitest(plan, opts) {
+    const baseUrl = opts?.baseUrl || plan.page_url_token;
+    const body = [
+        '/* Auto-generated by Yujin Forge -- e2e test corpus.',
+        ' * Plugin: ' + plan.plugin,
+        ' * Surface coverage: ' + plan.exercised_elements + ' / ' + plan.total_elements + ' manifest elements.',
+        ' * Framework: Vitest + jsdom. Re-generate with: yf gen-tests <dir> --framework vitest',
+        ' *',
+        ' * Vitest tests run in jsdom -- they validate the manifest + DOM',
+        ' * structure but do not exercise a real browser. For browser-level',
+        ' * dispatch tests, use the Playwright corpus.',
+        ' */',
+        "import { describe, it, expect, beforeAll } from 'vitest';",
+        "import fs from 'node:fs';",
+        "import path from 'node:path';",
+        "import { JSDOM } from 'jsdom';",
+        "",
+        "const BASE_HTML = path.resolve(__dirname, '..', 'index.html');",
+        "const MANIFEST  = path.resolve(__dirname, '..', 'manifest.json');",
+        "",
+        "let dom;",
+        "let manifest;",
+        "",
+        "beforeAll(() => {",
+        "  const html = fs.readFileSync(BASE_HTML, 'utf-8');",
+        "  manifest   = JSON.parse(fs.readFileSync(MANIFEST, 'utf-8'));",
+        "  dom = new JSDOM(html);",
+        "});",
+        "",
+        "describe('" + plan.plugin + " -- Forge e2e corpus (structural)', () => {",
+        "  it('manifest plugin_slug matches', () => {",
+        "    expect(manifest.plugin_slug).toBe('" + plan.plugin + "');",
+        "  });",
+    ];
+    for (const tc of plan.cases) {
+        body.push("  it('" + tc.name + "', () => {");
+        if (tc.kind === 'action_dispatch') {
+            body.push("    const els = manifest.elements.filter((e) => e.id === '" + tc.nac_id + "');");
+            body.push("    expect(els.length, 'manifest element ' + '" + tc.nac_id + "' + ' missing').toBe(1);");
+            body.push("    const verbs = (els[0].actions || []).map((a) => a.verb);");
+            body.push("    expect(verbs).toContain('" + tc.verb + "');");
+        }
+        else {
+            body.push("    const els = manifest.elements.filter((e) => e.id === '" + tc.nac_id + "');");
+            body.push("    expect(els.length, 'manifest element ' + '" + tc.nac_id + "' + ' missing').toBe(1);");
+            body.push("    const el = dom.window.document.querySelector('[data-nac-id=\"" + tc.nac_id + "\"]');");
+            body.push("    expect(el, 'DOM element ' + '" + tc.nac_id + "' + ' missing').not.toBeNull();");
+        }
+        body.push("  });");
+    }
+    body.push("});");
+    return [{ relpath: 'tests/forge-e2e/' + plan.plugin + '.test.ts', content: body.join('\n') }];
+}
+export function emitWdio(plan, opts) {
+    const baseUrl = opts?.baseUrl || plan.page_url_token;
+    const body = [
+        '/* Auto-generated by Yujin Forge -- e2e test corpus.',
+        ' * Plugin: ' + plan.plugin,
+        ' * Surface coverage: ' + plan.exercised_elements + ' / ' + plan.total_elements + ' manifest elements.',
+        ' * Framework: WebdriverIO. Re-generate with: yf gen-tests <dir> --framework wdio',
+        ' */',
+        "const BASE_URL = process.env.FORGE_E2E_BASE_URL || '" + baseUrl + "';",
+        "",
+        "async function gotoAndWait() {",
+        "  await browser.url(BASE_URL);",
+        "  await browser.waitUntil(async () => {",
+        "    return await browser.execute((slug) => {",
+        "      return !!(window.NAC && window.NAC.list_registered_plugins().includes(slug));",
+        "    }, '" + plan.plugin + "');",
+        "  }, { timeout: 10000, timeoutMsg: 'NAC manifest never registered' });",
+        "}",
+        "",
+        "describe('" + plan.plugin + " -- Forge e2e corpus', () => {",
+    ];
+    for (const tc of plan.cases) {
+        body.push("  it('" + tc.name + "', async () => {");
+        body.push("    await gotoAndWait();");
+        if (tc.kind === 'action_dispatch') {
+            body.push("    await browser.executeAsync(async (plugin, verb, done) => {");
+            body.push("      try { await window.NAC.click_by_verb(plugin, verb); done({ ok: true }); }");
+            body.push("      catch (e) { done({ ok: false, error: String(e.message || e) }); }");
+            body.push("    }, '" + tc.plugin + "', '" + tc.verb + "');");
+        }
+        else if (tc.kind === 'field_read' || tc.kind === 'region_present') {
+            body.push("    const el = await $('[data-nac-id=\"" + tc.nac_id + "\"]');");
+            body.push("    await expect(el).toBeExisting();");
+        }
+        else if (tc.kind === 'field_write') {
+            body.push("    await browser.executeAsync(async (id, val, done) => {");
+            body.push("      try { await window.NAC.fill(id, val); done({ ok: true }); }");
+            body.push("      catch (e) { done({ ok: false, error: String(e.message || e) }); }");
+            body.push("    }, '" + tc.nac_id + "', '" + tc.sample_input + "');");
+        }
+        else if (tc.kind === 'tab_switch') {
+            body.push("    await browser.executeAsync(async (id, done) => {");
+            body.push("      try { await window.NAC.tab(id); done({ ok: true }); }");
+            body.push("      catch (e) { done({ ok: false, error: String(e.message || e) }); }");
+            body.push("    }, '" + tc.nac_id + "');");
+        }
+        body.push("  });");
+    }
+    body.push("});");
+    return [{ relpath: 'test/specs/forge-e2e/' + plan.plugin + '.test.ts', content: body.join('\n') }];
+}
+export async function generateTests(plan, opts) {
+    const frameworks = Array.isArray(opts.framework) ? opts.framework : [opts.framework];
+    const results = [];
+    for (const fw of frameworks) {
+        const emit = (fw === 'playwright') ? emitPlaywright
+            : (fw === 'cypress') ? emitCypress
+                : (fw === 'vitest') ? emitVitest
+                    : (fw === 'wdio') ? emitWdio
+                        : null;
+        if (!emit)
+            throw new Error('Unknown framework: ' + fw);
+        const files = emit(plan, { baseUrl: opts.baseUrl });
+        const written = [];
+        const skipped = [];
+        for (const f of files) {
+            const abs = path.join(opts.outDir, f.relpath);
+            await fs.mkdir(path.dirname(abs), { recursive: true });
+            const exists = await fs.stat(abs).then(() => true, () => false);
+            if (exists && !opts.overwrite) {
+                skipped.push(f.relpath);
+                continue;
+            }
+            await fs.writeFile(abs, f.content, 'utf-8');
+            written.push(f.relpath);
+        }
+        results.push({
+            framework: fw, filesWritten: written, filesSkipped: skipped,
+            cases: plan.cases.length, exercised_elements: plan.exercised_elements, total_elements: plan.total_elements,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=e2e.js.map