@nac3/forge-cli 0.2.0-alpha.1

package/dist/commands/gen-tests.js

@@ -0,0 +1,118 @@
+/*
+ * yf gen-tests <dir> [--framework <name>] [--all] [--base-url <url>] [--overwrite]
+ *
+ * Reads <dir>/manifest.json, builds a TestPlan covering every
+ * manifest element, then emits the test suite in the requested
+ * framework's syntax.
+ *
+ * Multi-framework support reflects the reality that target teams
+ * already have a test framework. Forge does NOT mandate one.
+ *
+ * Auto-detection: if --framework is omitted, inspect <dir> for
+ * existing config files (playwright.config.ts, cypress.config.ts,
+ * vitest.config.ts, wdio.conf.ts) and pick that. If multiple are
+ * present and none is selected explicitly, list them and require
+ * the user to pick.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { c, header } from '../ui/colors.js';
+import { planFromManifest, detectFramework, generateTests, ALL_FRAMEWORKS, } from '../codegen/e2e.js';
+export function registerGenTestsCommand(program) {
+    program
+        .command('gen-tests <dir>')
+        .description('Generate an e2e test corpus from a NAC-3 decorated app\'s manifest.')
+        .option('--framework <name>', 'playwright | cypress | vitest | wdio | all | csv (default: auto-detect)')
+        .option('--base-url <url>', 'URL the tests should navigate to (default: http://localhost:3000)')
+        .option('--overwrite', 'overwrite existing test files instead of skipping')
+        .action(async (dir, opts) => {
+        await runGenTests(dir, opts);
+    });
+}
+function parseFrameworkArg(raw) {
+    if (!raw)
+        return null;
+    if (raw === 'all')
+        return 'all';
+    const items = raw.split(',').map((s) => s.trim()).filter(Boolean);
+    const valid = [];
+    for (const item of items) {
+        if (ALL_FRAMEWORKS.includes(item))
+            valid.push(item);
+        else
+            return null;
+    }
+    return valid.length > 0 ? valid : null;
+}
+export async function runGenTests(dir, opts) {
+    header('Yujin Forge -- e2e test corpus generator');
+    console.log('');
+    const targetDir = path.resolve(process.cwd(), dir);
+    const manifestPath = path.join(targetDir, 'manifest.json');
+    const ok = await fs.stat(manifestPath).then(() => true, () => false);
+    if (!ok) {
+        console.error(c.error('No manifest.json found in: ' + targetDir));
+        console.error(c.dim('Run `yf migrate <repo> --ai-silent` first to produce one.'));
+        process.exitCode = 1;
+        return;
+    }
+    /* Resolve framework. */
+    let frameworks;
+    const arg = parseFrameworkArg(opts.framework);
+    if (arg === 'all') {
+        frameworks = [...ALL_FRAMEWORKS];
+    }
+    else if (arg && arg.length > 0) {
+        frameworks = arg;
+    }
+    else if (opts.framework) {
+        console.error(c.error('Unknown --framework value: ' + opts.framework));
+        console.error(c.dim('Supported: ' + ALL_FRAMEWORKS.join(', ') + ', all, or csv.'));
+        process.exitCode = 1;
+        return;
+    }
+    else {
+        /* Auto-detect from target dir. */
+        const detected = await detectFramework(targetDir);
+        if (!detected) {
+            console.error(c.error('Could not auto-detect a test framework in: ' + targetDir));
+            console.error(c.dim('Pass --framework <name> explicitly. Supported: ' + ALL_FRAMEWORKS.join(', ') + '.'));
+            process.exitCode = 1;
+            return;
+        }
+        frameworks = [detected];
+        console.log(c.dim('Auto-detected framework: ') + c.brand(detected));
+    }
+    /* Build plan. */
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
+    const plan = planFromManifest(manifest, { pageUrlToken: opts.baseUrl || 'http://localhost:3000' });
+    console.log(c.dim('Manifest:           ') + manifestPath);
+    console.log(c.dim('Plugin slug:        ') + plan.plugin);
+    console.log(c.dim('Manifest elements:  ') + plan.total_elements);
+    console.log(c.dim('Surface exercised:  ') + plan.exercised_elements + ' / ' + plan.total_elements);
+    console.log(c.dim('Test cases:         ') + plan.cases.length);
+    console.log(c.dim('Frameworks:         ') + frameworks.join(', '));
+    console.log('');
+    const framework = frameworks.length === 1
+        ? frameworks[0]
+        : frameworks;
+    const genOpts = {
+        outDir: targetDir,
+        framework,
+        baseUrl: opts.baseUrl,
+        overwrite: !!opts.overwrite,
+    };
+    const results = await generateTests(plan, genOpts);
+    for (const r of results) {
+        console.log(c.success(r.framework) + c.dim(': ') + r.filesWritten.length + ' file(s) written, ' + r.filesSkipped.length + ' skipped.');
+        for (const f of r.filesWritten)
+            console.log('  ' + c.success('+') + ' ' + f);
+        for (const f of r.filesSkipped)
+            console.log('  ' + c.dim('. ') + f + c.dim(' (exists, pass --overwrite to replace)'));
+    }
+    console.log('');
+    console.log(c.success('Coverage: ') + plan.exercised_elements + ' / ' + plan.total_elements + ' manifest elements exercised.');
+    console.log(c.dim('Coverage metric: "agent-relevant surface" -- one test per (nac_id, role, verb) tuple.'));
+    console.log(c.dim('This is the honest claim; do NOT report this as line-coverage.'));
+}
+//# sourceMappingURL=gen-tests.js.map

package/dist/commands/gen-tests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gen-tests.js","sourceRoot":"","sources":["../../src/commands/gen-tests.ts"],"names":[],"mappings":"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"}

package/dist/commands/license.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `yf license <action>` -- license-lifecycle subcommands. Action
+ * is one of: activate, status, revoke.
+ *
+ * `status` is implemented today (reads the local cache).
+ * `activate` + `revoke` ship with the License client milestone.
+ */
+import type { Command } from 'commander';
+export interface LicenseOptions {
+    key?: string;
+    json?: boolean;
+}
+export declare function registerLicenseCommand(program: Command): void;
+//# sourceMappingURL=license.d.ts.map

package/dist/commands/license.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"license.d.ts","sourceRoot":"","sources":["../../src/commands/license.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAazC,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+J7D"}

package/dist/commands/license.js

@@ -0,0 +1,182 @@
+import { c, header } from '../ui/colors.js';
+import { loadLicense, isPaidSeat, isTrialActive } from '../license/index.js';
+import { activate, revoke, InvalidLicenseKeyError } from '../license/activate.js';
+import { readLicense as readPolarLicense, writeLicense as writePolarLicense, buildCheckoutUrl as buildPolarCheckoutUrl, describeLicense as describePolarLicense, isActive as isPolarActive, } from '../core/polar.js';
+export function registerLicenseCommand(program) {
+    const cmd = program
+        .command('license')
+        .description('Activate, inspect, or revoke a Yujin Forge license.');
+    cmd
+        .command('status')
+        .description('Print the current license state (JWT seat + Polar subscription).')
+        .option('--json', 'emit JSON instead of human-readable output')
+        .action(async (opts) => {
+        const lic = await loadLicense();
+        const polar = await readPolarLicense();
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ jwt_seat: lic, polar }, null, 2) + '\n');
+            return;
+        }
+        header('Yujin Forge -- license status');
+        console.log('');
+        console.log('  JWT seat:    ' + colorStatus(lic.status) + c.dim('  (' + lic.source + ')'));
+        if (isPaidSeat(lic)) {
+            console.log('    Seat email:  ' + (lic.seat?.email ?? c.dim('(unknown)')));
+            console.log('    Expires:     ' + (lic.seat?.expiresAt ?? c.dim('(no expiry)')));
+        }
+        else if (isTrialActive(lic)) {
+            console.log('    Trial ends:  ' + (lic.trial?.endsAt ?? c.dim('(unknown)')));
+            console.log('    Days left:   ' + (lic.trial?.daysLeft ?? 0));
+        }
+        console.log('');
+        console.log('  Polar plan:  ' + colorPolarPlan(polar.plan));
+        console.log('    ' + describePolarLicense(polar));
+        if (!isPolarActive(polar) && !isPaidSeat(lic)) {
+            console.log('');
+            console.log('  ' + c.warn('No active subscription.'));
+            console.log('  Run ' + c.code('yf license activate') + ' to open the Polar checkout.');
+        }
+    });
+    cmd
+        .command('activate')
+        .description('Install a JWT seat key OR open the Polar checkout (no key supplied).')
+        .option('-k, --key <key>', 'paid seat key issued by the parent server')
+        .option('--user-handle <handle>', 'email or username to bind the Polar subscription to')
+        .action(async (opts) => {
+        const key = (opts.key ?? '').trim();
+        if (key === '') {
+            /* No JWT supplied -- redirect to Polar checkout. */
+            const url = buildPolarCheckoutUrl(opts.userHandle);
+            header('Yujin Forge -- attach payment method');
+            console.log('');
+            console.log('  Open this URL to attach a card + start the 7-day free window:');
+            console.log('  ' + c.code(url));
+            console.log('');
+            console.log(c.dim('  - Day 1-7: free, cancel any time with ') + c.code('yf license cancel'));
+            console.log(c.dim('  - Day 8:   first USD 10 charge (auto)'));
+            console.log(c.dim('  Once the Polar webhook fires, ~/.yujin-forge/license.json'));
+            console.log(c.dim('  is updated automatically. Run `yf license status` to confirm.'));
+            return;
+        }
+        try {
+            const res = await activate(key);
+            header('Yujin Forge -- license activated');
+            console.log('');
+            console.log('  Seat email:    ' + (res.seat.email ?? c.dim('(not bound to email)')));
+            console.log('  Expires:       ' + (res.seat.expiresAt ?? c.dim('(no expiry)')));
+            console.log('  Fingerprint:   ' + c.dim(res.seat.machineFingerprint));
+            console.log('  Stored at:     ' + c.dim(res.path));
+            console.log('');
+            console.log(c.success('License installed. Commercial features unlocked.'));
+            console.log(c.dim('Server-side validation runs every 24h once the license server is live.'));
+        }
+        catch (err) {
+            if (err instanceof InvalidLicenseKeyError) {
+                console.error(c.error('Invalid license key: ') + err.message);
+            }
+            else {
+                console.error(c.error(err instanceof Error ? err.message : String(err)));
+            }
+            process.exitCode = 1;
+        }
+    });
+    cmd
+        .command('revoke')
+        .description('Remove the local license cache (return to trial mode).')
+        .action(async (_opts) => {
+        const removed = await revoke();
+        header('Yujin Forge -- license revoked');
+        console.log('');
+        if (removed) {
+            console.log(c.success('License removed. Falling back to trial semantics.'));
+        }
+        else {
+            console.log(c.dim('No license was installed -- nothing to do.'));
+        }
+    });
+    cmd
+        .command('cancel')
+        .description('Cancel the Polar subscription. Access continues until the current billing date.')
+        .action(async () => {
+        const polar = await readPolarLicense();
+        header('Yujin Forge -- cancel subscription');
+        console.log('');
+        if (polar.plan === 'none') {
+            console.log(c.dim('No subscription on file. Nothing to cancel.'));
+            return;
+        }
+        if (polar.plan === 'institutional' || polar.plan === 'gifted' || polar.plan === 'free-public') {
+            console.log(c.warn('Free seats are not Polar-billed. Nothing to cancel.'));
+            return;
+        }
+        if (polar.plan === 'cancelled') {
+            console.log(c.dim('Subscription already cancelled.'));
+            console.log('  ' + describePolarLicense(polar));
+            return;
+        }
+        /* Mark cancelled. Access continues until cancel_grace_until
+         * (trial path) or expires_at (paid path). */
+        const next = {
+            ...polar,
+            plan: 'cancelled',
+            expires_at: polar.plan === 'trial'
+                ? (polar.cancel_grace_until ?? polar.bills_first_on ?? null)
+                : (polar.expires_at ?? null),
+        };
+        await writePolarLicense(next);
+        console.log(c.success('Subscription cancelled.'));
+        console.log('  ' + describePolarLicense(next));
+        console.log('');
+        console.log(c.dim('Run ') + c.code('yf license resubscribe') + c.dim(' to reactivate while access is still live.'));
+    });
+    cmd
+        .command('resubscribe')
+        .description('Re-activate a cancelled Polar subscription (or open checkout if expired).')
+        .action(async () => {
+        const polar = await readPolarLicense();
+        header('Yujin Forge -- resubscribe');
+        console.log('');
+        if (polar.plan !== 'cancelled') {
+            console.log(c.dim('Current plan is "' + polar.plan + '". Resubscribe is only for cancelled plans.'));
+            if (polar.plan === 'none') {
+                console.log('  Run ' + c.code('yf license activate') + ' to start a new subscription.');
+            }
+            return;
+        }
+        const stillActive = isPolarActive(polar);
+        if (stillActive) {
+            /* Inside the original billing period -- flip back to paid
+             * without re-running checkout. */
+            const next = { ...polar, plan: 'paid' };
+            await writePolarLicense(next);
+            console.log(c.success('Reactivated as paid. Next bill keeps the original date.'));
+            console.log('  ' + describePolarLicense(next));
+            return;
+        }
+        /* Past the grace period -- the user needs a fresh Polar
+         * checkout (the subscription on Polar is dead). */
+        const url = buildPolarCheckoutUrl(polar.user_handle);
+        console.log(c.warn('Your previous billing period has expired.'));
+        console.log('  Open this URL to start a fresh subscription:');
+        console.log('  ' + c.code(url));
+    });
+}
+function colorStatus(s) {
+    if (s === 'paid')
+        return c.success(s);
+    if (s === 'trial')
+        return c.info(s);
+    if (s === 'expired')
+        return c.warn(s);
+    return c.error(s);
+}
+function colorPolarPlan(p) {
+    if (p === 'paid' || p === 'institutional' || p === 'gifted' || p === 'free-public')
+        return c.success(p);
+    if (p === 'trial')
+        return c.info(p);
+    if (p === 'cancelled')
+        return c.warn(p);
+    return c.error(p);
+}
+//# sourceMappingURL=license.js.map

package/dist/commands/license.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"license.js","sourceRoot":"","sources":["../../src/commands/license.ts"],"names":[],"mappings":"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"}

package/dist/commands/log.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `yf log` -- runtime knobs for the SQ.K logger.
+ *
+ * Subcommands (MVP):
+ *   yf log level                       Print the active default + scope overrides.
+ *   yf log level <scope> <level>       Override a scope (current process only).
+ *   yf log level --reset <scope>       Clear the override.
+ *   yf log scopes                      List well-known scopes.
+ *
+ * Bigger items deferred (see docs/PENDING_AND_SQ_LESSONS.md SQ.K):
+ *   - `yf log capture --since 10m`     Bundle a time-windowed dump.
+ *   - `yf log tail <scope>`            Stream the persistent file.
+ *   - `--persist` flag to write the override to disk.
+ *
+ * ASCII-only.
+ */
+import type { Command } from 'commander';
+export declare function registerLogCommand(program: Command): void;
+//# sourceMappingURL=log.d.ts.map

package/dist/commands/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/commands/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBzC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoFzD"}

package/dist/commands/log.js

@@ -0,0 +1,101 @@
+import { c, header } from '../ui/colors.js';
+import { setScopeLevel, levelForScope, currentDefaultLevel, LEVELS, } from '../core/logger.js';
+const KNOWN_SCOPES = [
+    { scope: 'state_channel', purpose: 'Cross-device PubSub long-poll loop' },
+    { scope: 'cascade_router', purpose: 'laptop -> CF tunnel -> GHA fallback' },
+    { scope: 'voice_loop', purpose: 'idle / listening / speaking FSM' },
+    { scope: 'polar_webhook', purpose: 'Polar webhook receiver (server-side)' },
+    { scope: 'brain_client', purpose: 'HITO 4 callFlow / fetchServerLicense' },
+    { scope: 'hito4.flow_router', purpose: 'Server-side flow dispatch' },
+    { scope: 'pairing', purpose: 'Mobile pair / unpair / encrypt' },
+    { scope: 'lan_browse', purpose: 'mDNS / polling discovery' },
+];
+function isValidLevel(v) {
+    return LEVELS.includes(v);
+}
+export function registerLogCommand(program) {
+    const root = program
+        .command('log')
+        .description('Runtime knobs for the logging subsystem (SQ.K MVP).');
+    root
+        .command('level [scope] [level]')
+        .description('Print or set log level (current process). Without args, prints the active config.')
+        .option('--reset', 'clear the override for the given scope')
+        .option('--json', 'machine-readable output')
+        .action((scope, level, opts) => {
+        if (opts.reset) {
+            if (!scope) {
+                console.error(c.error('--reset requires a scope'));
+                process.exitCode = 1;
+                return;
+            }
+            setScopeLevel(scope, null);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ ok: true, scope, reset: true }) + '\n');
+            }
+            else {
+                console.log(c.success('+') + ' override cleared on scope ' + c.dim(scope));
+            }
+            return;
+        }
+        if (scope && level) {
+            if (!isValidLevel(level)) {
+                console.error(c.error('invalid level "' + level + '" (must be one of: ' + LEVELS.join(', ') + ')'));
+                process.exitCode = 1;
+                return;
+            }
+            setScopeLevel(scope, level);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ ok: true, scope, level }) + '\n');
+            }
+            else {
+                console.log(c.success('+') + ' scope ' + c.brand(scope) + ' -> ' + c.info(level));
+            }
+            return;
+        }
+        /* No mutation -- just print state. */
+        const def = currentDefaultLevel();
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({
+                ok: true,
+                default_level: def,
+                known_scopes: KNOWN_SCOPES.map((k) => ({
+                    scope: k.scope, level: levelForScope(k.scope),
+                })),
+            }, null, 2) + '\n');
+            return;
+        }
+        header('Yujin Forge -- log levels');
+        console.log('');
+        console.log('  Default level: ' + c.brand(def));
+        console.log('');
+        console.log('  Scope                            Level');
+        console.log('  ' + '-'.repeat(50));
+        for (const k of KNOWN_SCOPES) {
+            const lvl = levelForScope(k.scope);
+            const overridden = lvl !== def;
+            const lvlStr = overridden ? c.info(lvl) : c.dim(lvl);
+            console.log('  ' + k.scope.padEnd(32) + ' ' + lvlStr);
+        }
+        console.log('');
+        console.log(c.dim('  Override:  yf log level <scope> <level>'));
+        console.log(c.dim('  Reset:     yf log level --reset <scope>'));
+        console.log(c.dim('  N.B. overrides apply to the current process only -- restart resets.'));
+    });
+    root
+        .command('scopes')
+        .description('List the well-known scopes + their purpose.')
+        .option('--json', 'machine-readable output')
+        .action((opts) => {
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(KNOWN_SCOPES, null, 2) + '\n');
+            return;
+        }
+        header('Yujin Forge -- log scopes');
+        console.log('');
+        for (const k of KNOWN_SCOPES) {
+            console.log('  ' + c.brand(k.scope.padEnd(32)) + c.dim(' ' + k.purpose));
+        }
+    });
+}
+//# sourceMappingURL=log.js.map

package/dist/commands/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/commands/log.ts"],"names":[],"mappings":"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"}

package/dist/commands/migrate.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `yf migrate <repo> --audit`    -- produce an audit report.
+ * `yf migrate <repo> --apply`    -- run the AST migration (.tsx/.jsx).
+ * `yf migrate <repo> --html`     -- silent HTML walker (auto-apply).
+ * `yf migrate <repo> --assisted` -- HTML walker with CLI prompts for
+ *                                   low-confidence candidates.
+ *
+ * Audit is read-only + free for everyone (the SPEC carves it out
+ * as a pre-purchase funnel surface). Apply / html / assisted are
+ * gated on a paid seat.
+ */
+import type { Command } from 'commander';
+import { type AiMode, type AiDecorateFn } from '../migrate/ai-decorator.js';
+export interface MigrateOptions {
+    audit?: boolean;
+    apply?: boolean;
+    yes?: boolean;
+    out?: string;
+    subdir?: string;
+    dryRun?: boolean;
+    html?: boolean;
+    assisted?: boolean;
+    threshold?: string;
+    aiSilent?: boolean;
+    aiAssisted?: boolean;
+    aiModel?: string;
+    aiHint?: string;
+    aiOut?: string;
+    withPilot?: boolean;
+    aiSearch?: string;
+    aiOverride?: string;
+    noOverrides?: boolean;
+    aiApply?: boolean;
+    aiPluginSlug?: string;
+    aiConcurrency?: string;
+    withI18nTags?: boolean;
+    i18nLangs?: string;
+    multiPage?: boolean;
+}
+export declare function registerMigrateCommand(program: Command): void;
+export declare function runAudit(repo: string, opts: MigrateOptions): Promise<void>;
+export declare function runApply(repo: string, opts: MigrateOptions): Promise<void>;
+export declare function runSilentHtml(repo: string, opts: MigrateOptions): Promise<void>;
+export declare function runAssistedHtml(repo: string, opts: MigrateOptions): Promise<void>;
+export declare function runAiHtml(repo: string, opts: MigrateOptions, mode: AiMode): Promise<void>;
+export interface MultiPagePlanItem {
+    /** Absolute path of the source .html file. */
+    htmlPath: string;
+    /** Relative basename used for the output file + sidecar manifest. */
+    basename: string;
+    /** Path the decorated HTML will land at. */
+    outHtmlPath: string;
+    /** Path the sidecar manifest will land at. */
+    outManifestPath: string;
+}
+/**
+ * Build the plan of pages a multi-page run would touch. Pure +
+ * testable: no LLM calls, no writes. Exported so the test suite can
+ * exercise the directory-walk logic against a fixture.
+ */
+export declare function planMultiPageHtml(baseDir: string, outDir: string): Promise<MultiPagePlanItem[]>;
+export interface RunMultiPageOptions {
+    baseDir: string;
+    outDir: string;
+    mode: AiMode;
+    pluginHint?: string;
+    model?: string;
+    dryRun: boolean;
+    withPilot: boolean;
+    /** DI seam: lets tests stub the network round-trip. Defaults to the
+        real aiDecorate from ai-decorator.ts. */
+    decorator?: AiDecorateFn;
+}
+export interface RunMultiPageResult {
+    plan: MultiPagePlanItem[];
+    /** Per-page decoration result. */
+    pages: Array<{
+        item: MultiPagePlanItem;
+        plugin_slug: string;
+        manifest_json: string;
+        decorated_html: string;
+        diff: string;
+        ambiguities_count: number;
+        tokens_in: number;
+        tokens_out: number;
+        cost_usd: number;
+        latency_ms: number;
+    }>;
+    /** Canonical plugin slug, taken from the first page (or pluginHint
+        when set). */
+    plugin_slug: string;
+    total_tokens_in: number;
+    total_tokens_out: number;
+    total_cost_usd: number;
+    total_latency_ms: number;
+}
+/**
+ * Decorate every .html file in `baseDir`, share a plugin_slug across
+ * pages, write per-page outputs. Pure + DI-friendly so the call site
+ * (`runAiHtmlMultiPage`) can stay terse and the test suite can drive
+ * it without hitting the network.
+ */
+export declare function decorateMultiPageHtml(opts: RunMultiPageOptions): Promise<RunMultiPageResult>;
+export declare function runAiHtmlMultiPage(repo: string, opts: MigrateOptions, mode: AiMode): Promise<void>;
+/**
+ * `yf migrate <repo> --ai-search "<query>"` -- list manifest
+ * elements matching the free-text query, ranked by relevance.
+ * Useful before running --ai-override to find the right nac_id.
+ */
+export declare function runAiSearch(repo: string, opts: MigrateOptions): Promise<void>;
+/**
+ * `yf migrate <repo> --ai-override <nacId>` -- interactively
+ * re-decorate one element. Writes the override to overrides.json AND
+ * applies it immediately to index.html + manifest.json.
+ */
+export declare function runAiOverride(repo: string, opts: MigrateOptions): Promise<void>;
+export declare function runAiApply(repo: string, opts: MigrateOptions): Promise<void>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/commands/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"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"}