@superblocksteam/vite-plugin-file-sync 2.0.119-next.1 → 2.0.120-next.0

package/dist/migration/migration-verification.d.ts

@@ -0,0 +1,206 @@
+import { type ApiComparisonDiff, type ApiComparisonDiffEntry } from "../ai-service/agent/tools/apis/api-comparator.js";
+import { type ApiExecutionResult } from "../ai-service/agent/tools/apis/api-executor.js";
+import { PermissionLevel } from "../ai-service/agent/tools2/types.js";
+import type { Clark, ClarkStateHandlerParams } from "../ai-service/state-machine/clark-fsm.js";
+/**
+ * Hard cap on verification attempts per API per migration. The agent does NOT
+ * decide when to stop iterating — this counter is computed from on-disk
+ * history and enforced inside `runMigrationVerification`. An LLM agent asked
+ * to self-assess "am I converging?" reliably picks the socially acceptable
+ * answer ("yes"); the cap removes that judgment from the loop.
+ */
+export declare const MAX_VERIFICATION_ATTEMPTS = 10;
+export type VerificationOutcome = {
+    kind: "passed";
+} | {
+    kind: "both_failed";
+    v2Error: string;
+    v3Error: string;
+} | {
+    kind: "skipped_mutation";
+    mutationDetails: string[];
+    /** "ask" = user set policy to ask-before-running; "deny" = permanently blocked. */
+    skipPolicy: "ask" | "deny";
+} | {
+    kind: "v2_unrunnable";
+    reason: string;
+} | {
+    kind: "diverged";
+    diff: ApiComparisonDiff;
+    /** 1-indexed attempt number for this verification run. */
+    attempt: number;
+    /**
+     * Programmatic convergence signal computed from on-disk history. Agents
+     * cannot fudge this — it's derived by hashing the (path, kind) tuples of
+     * the current diff and comparing to the prior attempt's hash.
+     *
+     * - `first_attempt`: no prior diverged result for this API.
+     * - `converging`: the set of (path, kind) pairs differs from the prior
+     *   diverged attempt — Clark's last edit changed *which* paths diverge.
+     *   Note: the hash deliberately excludes value hashes, so changing the
+     *   *value* on the same path/kind is NOT counted as progress.
+     * - `stalled`: the set of (path, kind) pairs is identical to the prior
+     *   diverged attempt. Whatever Clark did had no structural effect.
+     */
+    progress: "first_attempt" | "converging" | "stalled";
+} | {
+    kind: "error";
+    reason: string;
+} | {
+    kind: "exhausted";
+    attempts: number;
+    lastDivergence?: ApiComparisonDiff;
+};
+export interface RunMigrationVerificationParams {
+    apiName: string;
+    appRootDir: string;
+    /**
+     * Test inputs to inject into both the v2 YAML pipeline and the v3 SDK
+     * execution. Structurally identical to the `inputs` accepted by the
+     * `testApi` tool — Clark synthesizes mock values for the API's bindings
+     * (e.g. `Input1.value`, `Table1.selectedRow`) the same way it does for
+     * standalone testing. Defaults to `{}` so callers that don't care about
+     * parametrized verification can omit it.
+     */
+    inputs?: Record<string, unknown>;
+    /** Injected to allow unit testing without Clark infrastructure. */
+    runV2Pipeline: (sourcePath: string, inputs: Record<string, unknown>) => Promise<{
+        success: boolean;
+        executionResult?: ApiExecutionResult;
+    }>;
+    runV3Sdk: (integrationIds: string[] | undefined, inputs: Record<string, unknown>) => Promise<Pick<ApiExecutionResult, "success" | "outputs"> & Partial<Pick<ApiExecutionResult, "errors" | "systemError">>>;
+    /**
+     * If true, "ask" mutation policy does not auto-skip and verification proceeds.
+     * Callers must ensure permission prompting has already been handled.
+     */
+    allowAskPolicy?: boolean;
+}
+/**
+ * Verify a single API by running both the v2 YAML and v3 TS versions with the
+ * supplied inputs and comparing their outputs.
+ *
+ * Wraps `computeVerificationOutcome` with on-disk history bookkeeping:
+ * - Reads `scratch/migration-verification/<apiName>.history.json` and refuses
+ *   to run beyond `MAX_VERIFICATION_ATTEMPTS`, returning `kind: "exhausted"`.
+ * - For `diverged` outcomes, computes `progress` (`first_attempt` |
+ *   `converging` | `stalled`) by hashing (path, kind) tuples and comparing to
+ *   the prior diverged attempt's hash.
+ * - Appends a history entry on every run so the next call has accurate state.
+ *
+ * History persistence is best-effort: bookkeeping I/O failures are logged but
+ * do not surface as verification errors.
+ */
+export declare function runMigrationVerification(params: RunMigrationVerificationParams): Promise<VerificationOutcome>;
+/** Relative path (from appRootDir) for a diff JSON file. */
+export declare function diffRelativePath(apiName: string): string;
+export declare const migrationVerificationToolFactory: import("../ai-service/agent/tools2/types.js").ToolFactory<{
+    clark: Clark;
+    services: ClarkStateHandlerParams;
+}, import("../ai-service/agent/tools2/types.js").Tool<{
+    apiName: string;
+    inputs?: Record<string, any> | undefined;
+}, {
+    kind: string;
+    summaryForAgent: ApiComparisonDiffEntry[];
+    diffPath: string;
+    attempt: number;
+    maxAttempts: number;
+    progress: "first_attempt" | "converging" | "stalled";
+    guidance: string;
+    attempts?: undefined;
+    summary?: undefined;
+    mutationDetails?: undefined;
+    reason?: undefined;
+} | {
+    kind: string;
+    attempts: number;
+    summary: string;
+    summaryForAgent?: undefined;
+    diffPath?: undefined;
+    attempt?: undefined;
+    maxAttempts?: undefined;
+    progress?: undefined;
+    guidance?: undefined;
+    mutationDetails?: undefined;
+    reason?: undefined;
+} | {
+    kind: string;
+    mutationDetails: string[];
+    summary: string;
+    summaryForAgent?: undefined;
+    diffPath?: undefined;
+    attempt?: undefined;
+    maxAttempts?: undefined;
+    progress?: undefined;
+    guidance?: undefined;
+    attempts?: undefined;
+    reason?: undefined;
+} | {
+    kind: string;
+    summary: string;
+    summaryForAgent?: undefined;
+    diffPath?: undefined;
+    attempt?: undefined;
+    maxAttempts?: undefined;
+    progress?: undefined;
+    guidance?: undefined;
+    attempts?: undefined;
+    mutationDetails?: undefined;
+    reason?: undefined;
+} | {
+    kind: string;
+    reason: string;
+    summaryForAgent?: undefined;
+    diffPath?: undefined;
+    attempt?: undefined;
+    maxAttempts?: undefined;
+    progress?: undefined;
+    guidance?: undefined;
+    attempts?: undefined;
+    summary?: undefined;
+    mutationDetails?: undefined;
+}>>;
+/**
+ * Inspect a v2 backup YAML for mutating steps and the integrations they touch.
+ *
+ * Returns empty results when the backup is missing or unparseable — the
+ * verification flow handles that downstream as `v2_unrunnable`. The goal here
+ * is only to feed the policy gate so v2-only writes don't bypass it.
+ *
+ * Walks the whole tree via `forEachYamlStep` so writes nested inside
+ * control-flow blocks (`tryCatch`, `conditional`, `foreach`, `parallel`) are
+ * caught — a flat scan over `parsed.blocks` would let nested v2 writes bypass
+ * the policy gate, especially now that the language-plugin filter has removed
+ * the accidental safety net where javascript's missing policy used to block
+ * all verification.
+ *
+ * Treats `unknown` step classifications (dynamic SQL bodies, plugins we don't
+ * recognize) as mutations: better to ask the user than silently run a write.
+ */
+export declare function analyzeV2BackupMutations(v2BackupPath: string): Promise<{
+    mutationDetails: string[];
+    integrationIds: string[];
+}>;
+export declare const checkRunMigrationVerificationPermissions: (services: ClarkStateHandlerParams, input?: {
+    apiName?: string;
+}) => Promise<PermissionLevel>;
+/**
+ * Delete the per-API verification history (and stale diff snapshot) so the
+ * next `runMigrationVerification` call starts from a clean slate. Called by
+ * the "Fix with Clark" retry endpoints — without this, an item that hit the
+ * `MAX_VERIFICATION_ATTEMPTS` cap on the first run would immediately return
+ * `kind: "exhausted"` on retry, making the retry a no-op.
+ *
+ * Routed through the same per-API `verificationHistoryQueues` queue used by
+ * `runMigrationVerification`. Without this, a clear could race with an
+ * in-flight verification: the verification reads history, runs the pipeline,
+ * the clear `rm()`s the file, then the verification's append re-creates the
+ * file with a stale attempt count — defeating the clear and immediately
+ * returning `exhausted` on the user's next retry.
+ *
+ * Best-effort: missing files are not an error. The safety check on
+ * `apiName` (via `historyPath`/`diffPath`) runs *before* enqueueing so a
+ * poisoned name throws synchronously, never holding the queue.
+ */
+export declare function clearVerificationHistory(appRootDir: string, apiName: string): Promise<void>;
+//# sourceMappingURL=migration-verification.d.ts.map

package/dist/migration/migration-verification.d.ts.map

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