@nac3/forge-cli 0.2.0-alpha.1

package/dist/migrate/ai-apply.d.ts

@@ -0,0 +1,198 @@
+import { type ValidationFinding } from './manifest-validator.js';
+export interface AiApplyFileResult {
+    /** Relative file path. */
+    relpath: string;
+    /** Decorated JSX source. */
+    decorated_jsx: string;
+    /** Manifest elements contributed by this file. */
+    elements: Array<{
+        id: string;
+        role: string;
+        actions?: Array<{
+            verb: string;
+            label_i18n?: Record<string, string>;
+        }>;
+        label_i18n?: Record<string, string>;
+        /** H2: for reusable components decorated with dynamic qualifiers,
+           the template the runtime will fill at dispatch time
+           (e.g. "conduit.action.favorite_article__${article.slug}"). */
+        instance_pattern?: string;
+        /** H2: the source of the qualifier (props.label, article.slug, etc).
+           Informational + lets the runtime know which payload key to expect. */
+        qualifier_source?: string;
+        /** H2: present when the model decorated a reusable component without
+           finding a stable qualifier. The aggregator surfaces these as
+           warnings during apply -- N DOM instances will collide on this id. */
+        warning?: string;
+        /** H1: URL paths where this element is reachable. Empty / missing
+           means "unknown" -- the aggregator will try to infer from the
+           file's containing route, then default to "*" (always-present). */
+        mounted_at?: string[];
+        /** H1: true if this element only mounts under an auth-gated route. */
+        requires_auth?: boolean;
+    }>;
+    /** H1: if this file declares routes, the map { component_path -> URL
+       pattern[] } the aggregator uses to fill mounted_at for elements in
+       other files. */
+    route_map?: Record<string, string[] | {
+        paths: string[];
+        requires_auth?: boolean;
+    }>;
+    /** H1.v3: per-:param fixture seeding spec emitted by the Router-root
+       file. Key is the URL-param token (':slug', ':username'). The
+       emitter uses CREATE in beforeEach + DELETE in afterEach so each
+       test starts clean. When DELETE is null, the emitter falls back
+       to a {rand} per-test suffix on unique_suffix_field. */
+    fixtures?: Record<string, {
+        create_endpoint: string;
+        create_payload: any;
+        response_path: string;
+        delete_endpoint?: string | null;
+        requires_auth?: boolean;
+        unique_suffix_field?: string | null;
+    }>;
+    /** H1.v4: Router kind detected when this file is the Router root.
+       "hash" -> emitter prefixes URLs with "#" so cy.visit hits the
+       SPA route. */
+    router_kind?: 'browser' | 'hash' | 'memory';
+    /** Plugin slug as guessed by the model per-file (top-level
+       aggregator picks the most-common slug as canonical). */
+    plugin_slug_guess: string;
+    /** Round-trip metadata. */
+    tokens_in: number;
+    tokens_out: number;
+    cost_usd: number;
+    latency_ms: number;
+    /** Whether the model emitted any decoration. */
+    decorated: boolean;
+    /** i18n: per-file catalog of {data-i18n key -> English source text}.
+       Emitted only when withI18nTags is set on aiApplyProject(). */
+    i18n_catalog?: Record<string, string>;
+    /** G2: number of LLM attempts the file went through. 1 on a clean
+       first response; up to 3 when the validator caught contract
+       violations and the retry loop fired. */
+    attempts: number;
+    /** G2: the validator's findings on the FINAL attempt. Empty
+       array means the file passed validation. Non-empty + attempts=3
+       means the loop gave up; the decorated_jsx + elements still
+       reflect the last attempt and the caller can surface the
+       findings as warnings or block, at its discretion. */
+    validation_findings: ValidationFinding[];
+}
+export interface AiApplyResult {
+    files: AiApplyFileResult[];
+    manifest: {
+        plugin_slug: string;
+        version: string;
+        nac_version: string;
+        label_i18n: Record<string, string>;
+        elements: any[];
+        /** H1.v3: per-:param fixture-seeding spec for dynamic routes. */
+        fixtures?: Record<string, {
+            create_endpoint: string;
+            create_payload: any;
+            response_path: string;
+            delete_endpoint?: string | null;
+            requires_auth?: boolean;
+            unique_suffix_field?: string | null;
+        }>;
+        /** H1.v4: Router kind, aggregated across files. */
+        router_kind?: 'browser' | 'hash' | 'memory';
+    };
+    /** H2: warnings collected when a reusable component was decorated
+       without an inferable qualifier. Empty list when all components
+       either had a qualifier or were unique. */
+    warnings: Array<{
+        file: string;
+        id: string;
+        warning: string;
+    }>;
+    /** i18n: project-level merged catalog (only present when
+       withI18n was set). */
+    i18n_catalog?: Record<string, string>;
+    /** i18n: key-collision warnings -- same key in two files with
+       different EN values. Last-write-wins; this surfaces the drift. */
+    i18n_warnings?: Array<{
+        file: string;
+        key: string;
+        old_value: string;
+        new_value: string;
+    }>;
+    total_tokens_in: number;
+    total_tokens_out: number;
+    total_cost_usd: number;
+    total_latency_ms: number;
+    /** G2: number of files whose first attempt passed validation. */
+    files_clean_first_attempt: number;
+    /** G2: number of files that needed a retry (attempts > 1). */
+    files_retried: number;
+    /** G2: number of files where the retry loop gave up (validation
+       findings still present after max attempts). */
+    files_gave_up: number;
+}
+export declare const AI_APPLY_MAX_ATTEMPTS = 3;
+/**
+ * Shape of a single AI turn used by the retry loop.
+ * Exposed for unit testing -- aiApplyOneWithCaller wires this to the
+ * real Anthropic SDK; tests can pass a stub instead.
+ */
+export interface AiCallerArgs {
+    /** Full system prompt for the turn. */
+    system: string;
+    /** Multi-turn messages (user / assistant), in order. */
+    messages: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    /** Resolved Anthropic model id. */
+    model: string;
+    /** When set, omit temperature (reasoning models). */
+    skipTemperature: boolean;
+}
+export interface AiCallerResult {
+    /** Raw text content from the assistant turn. */
+    text: string;
+    /** Input + output token counts for cost accounting. */
+    usage: {
+        input: number;
+        output: number;
+    };
+}
+export type AiCaller = (args: AiCallerArgs) => Promise<AiCallerResult>;
+export declare function aiApplyOne(opts: {
+    jsxSource: string;
+    relpath: string;
+    pluginSlugHint?: string;
+    model?: string;
+    /** When true, the system prompt is extended to also emit
+        data-i18n="<key>" on user-facing text nodes and return an
+        i18n_catalog map { key -> English source text } in the response. */
+    withI18n?: boolean;
+    /** G2 injectable AI caller (tests pass a stub; production uses
+        the default Anthropic SDK wrapper). */
+    aiCaller?: AiCaller;
+}): Promise<AiApplyFileResult>;
+/**
+ * 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 declare function aiApplyProject(opts: {
+    projectRoot: string;
+    subdir?: string;
+    outDir?: string;
+    pluginSlugHint?: string;
+    model?: string;
+    dryRun?: boolean;
+    concurrency?: number;
+    /** When true, ALSO emit data-i18n="<key>" on text nodes + write
+        i18n/<lang>.json catalogs under outDir (or projectRoot when no
+        outDir). Locale list defaults to the canonical 10 Yujin langs;
+        pass i18nLangs to override. */
+    withI18n?: boolean;
+    i18nLangs?: string[];
+    onProgress?: (i: number, total: number, file: string, result: AiApplyFileResult) => void;
+}): Promise<AiApplyResult>;
+//# sourceMappingURL=ai-apply.d.ts.map

package/dist/migrate/ai-apply.d.ts.map

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