@skyramp/mcp 0.2.6 → 0.2.8-rc.1

package/build/utils/AnalysisStateManager.d.ts

@@ -0,0 +1,242 @@
+import { TestAnalysisResult } from "../types/TestAnalysis.js";
+import { RepositoryAnalysis, AnalysisScope } from "../types/RepositoryAnalysis.js";
+import { PRTestContext } from "./pr-comment-parser.js";
+import { ParsedDiffEndpoint } from "./routeParsers.js";
+import type { CandidateUiPage } from "./uiPageEnumerator.js";
+export type { CandidateUiPage } from "./uiPageEnumerator.js";
+export declare function setTestsRepoDir(dir: string | undefined): void;
+export declare function getTestsRepoDir(): string | undefined;
+export declare function setActiveRunStatePath(stateFilePath: string): void;
+export declare function getActiveRunStatePath(): string | undefined;
+/** Reset the run anchor — for tests, and as a safety hook between runs. */
+export declare function clearActiveRunStatePath(): void;
+export declare function registerSession(sessionId: string, stateFilePath: string): void;
+export declare function getSessionFilePath(sessionId: string): string | undefined;
+export declare function getRegisteredSessions(): ReadonlyMap<string, string>;
+export declare function storeSessionData(sessionId: string, data: any): void;
+export declare function getSessionData(sessionId: string): any | undefined;
+export declare function hasSessionData(sessionId: string): boolean;
+/**
+ * Normalize a loaded RecommendationState: if the LLM saved a raw
+ * RepositoryAnalysis at the root (without the wrapper), detect it
+ * and wrap it properly.
+ */
+export declare function normalizeRecommendationState(data: RecommendationState): RecommendationState;
+/**
+ * State types supported by the manager
+ */
+export type StateType = "analysis" | "recommendation";
+/**
+ * State data for test maintenance workflow (discovery, drift, execution, health)
+ */
+export interface TestAnalysisState {
+    tests: TestAnalysisResult[];
+}
+/**
+ * State data for test recommendation workflow (analyze repo, recommend tests)
+ */
+export interface RecommendationState {
+    repositoryPath: string;
+    analysisScope?: AnalysisScope;
+    analysis: RepositoryAnalysis;
+    prContext?: PRTestContext;
+}
+/**
+ * Map of test type → numeric score (e.g., priority, relevance, confidence).
+ */
+type TestTypeScores = Record<string, number>;
+/**
+ * Map of test type → grouping/label information used by downstream tools.
+ */
+type TestTypeMapping = Record<string, string | string[]>;
+/**
+ * UI-specific analysis context populated when the diff contains frontend files.
+ *
+ * Computed deterministically by `skyramp_analyze_changes` (via `isFrontendFile`
+ * in scopeAssessment.ts). Persisted so downstream consumers —
+ * `skyramp_analyze_test_health`'s UI drift detection, recommendation prompt
+ * rendering, etc. — don't have to re-derive the classification.
+ *
+ * Absent on backend-only PRs (no frontend files in the diff).
+ */
+export interface UiAnalysisContext {
+    /**
+     * Subset of `repositoryAnalysis.diff.changedFiles` that classified as
+     * frontend by `isFrontendFile()`. Empty when no frontend files changed —
+     * callers can derive `hasFrontendChanges` from `changedFrontendFiles.length > 0`.
+     */
+    changedFrontendFiles: string[];
+    /**
+     * Candidate pages the testbot agent should capture blueprints for, enumerated
+     * by the strategy ladder in `uiPageEnumerator.ts` (framework route grep,
+     * source-grounded routes, root fallback). Each entry carries the candidate
+     * URL plus the strategy + source files that surfaced it. May be empty when
+     * the workspace has no resolvable frontend baseUrl — caller should fall back
+     * to the agent's prose-driven enumeration.
+     */
+    candidateUiPages: CandidateUiPage[];
+}
+/**
+ * Unified state data combining test discovery + endpoint scanning
+ * Used by the unified test-management workflow
+ */
+export interface UnifiedAnalysisState {
+    existingTests: TestAnalysisResult[];
+    repositoryAnalysis?: any;
+    testTypeScores?: TestTypeScores;
+    testTypeMapping?: TestTypeMapping;
+    analysisScope: AnalysisScope;
+    newEndpoints: ParsedDiffEndpoint[];
+    /**
+     * UI-specific state populated when the diff contains frontend files.
+     * Absent on backend-only PRs.
+     */
+    uiContext?: UiAnalysisContext;
+}
+/**
+ * State file metadata
+ */
+interface StateMetadata {
+    sessionId: string;
+    stateType: StateType;
+    repositoryPath?: string;
+    /** owner/repo of the PRIMARY repo, recorded on the root so related-repo writes
+     *  can be distinguished from the primary. Absent only for legacy single-repo
+     *  state files written before explicit tagging. */
+    repository?: string;
+    createdAt: string;
+    updatedAt: string;
+    step?: string;
+}
+/**
+ * One related repo's analysis section in a run-scoped (multi-repo) state file.
+ * The primary repo's analysis stays at the root for backward compatibility; each
+ * related repo's analysis is stored here keyed by its `owner/repo`.
+ */
+interface RepoStateSection<T> {
+    /** Analysis payload — same shape as the root (e.g. UnifiedAnalysisState). */
+    data: T;
+    /** Absolute checkout path of this repo (used to re-absolutize test paths). */
+    repositoryPath?: string;
+}
+/**
+ * State file format - data fields at root level with metadata.
+ * Example: { tests: [...], metadata: {...} }
+ * Example: { repositoryPath: "...", analysis: {...}, mapping: {...}, metadata: {...} }
+ *
+ * Multi-repo (run-scoped) files additionally carry `relatedRepos`: a map of
+ * `owner/repo` → that repo's analysis section. State is per-RUN, not per-repo —
+ * one file holds the primary (at root) plus every related repo's section, so
+ * there is exactly one stateFile per Testbot run. A file with no `relatedRepos`
+ * key is a single-repo file and behaves exactly as before.
+ */
+type StateFile<T> = T & {
+    metadata: StateMetadata;
+    relatedRepos?: Record<string, RepoStateSection<T>>;
+};
+/**
+ * Generic State Manager for persisting workflow data
+ * Reduces token usage by storing intermediate results in filesystem
+ *
+ * Supports two state types:
+ * - analysis: Test maintenance workflow (discovery, drift, execution, health)
+ * - recommendation: Test recommendation workflow (analyze repo, map tests, recommendations)
+ */
+export declare class StateManager<T = any> {
+    private stateFile;
+    private sessionId;
+    private stateType;
+    /**
+     * Create a new state manager
+     * @param stateType Type of state (analysis, recommendation)
+     * @param sessionId Unique session identifier (defaults to UUID)
+     * @param stateDir Directory to store state files (defaults to /tmp)
+     */
+    constructor(stateType?: StateType, sessionId?: string, stateDir?: string, stateFilePath?: string);
+    /**
+     * Create state manager from a sessionId (resolves the state file path internally)
+     */
+    static fromSessionId<T = any>(sessionId: string, stateType?: StateType, stateDir?: string): StateManager<T>;
+    /**
+     * Create state manager from existing state file path
+     */
+    static fromStatePath<T = any>(stateFilePath: string): StateManager<T>;
+    /**
+     * Read data from state file (excludes metadata)
+     */
+    readData(): Promise<T | null>;
+    /**
+     * Read full state including metadata
+     */
+    readFullState(): Promise<StateFile<T> | null>;
+    /**
+     * Write data to state file
+     * Data fields are spread at root level alongside metadata
+     */
+    writeData(data: T, options?: {
+        repositoryPath?: string;
+        step?: string;
+        /** owner/repo recorded on the root metadata — identifies the PRIMARY repo
+         *  so later section routing (isPrimaryRepo) can compare against it.
+         *  Preserved when omitted. */
+        repository?: string;
+    }): Promise<void>;
+    /** Is `repo` the primary section? Primary when `repo` is falsy (single-repo /
+     *  legacy callers), when no state file exists yet (the FIRST write of a run is
+     *  the primary — the testbot prompt mandates the primary is analyzed first), or
+     *  when `repo` matches the `repo` recorded on the root metadata. A non-empty
+     *  `repo` that doesn't match an already-recorded root is a RELATED repo. */
+    private isPrimaryRepo;
+    /**
+     * Write one repo's analysis into the run-scoped state file. The primary repo
+     * (repo absent, or matching the root's recorded repo, or the first write of the
+     * run) is written to the root via writeData(); a related repo is upserted into
+     * `relatedRepos[repo]`, preserving the primary + other sections. Used by
+     * skyramp_analyze_changes — every repo in the run writes the SAME stateFile path.
+     */
+    writeRepoData(data: T, options: {
+        repo?: string;
+        repositoryPath?: string;
+        step?: string;
+    }): Promise<void>;
+    /**
+     * Read one repo's analysis payload from the run-scoped state file. `repo`
+     * undefined → the primary (root) section (identical to readData()).
+     */
+    readRepoData(repo?: string): Promise<T | null>;
+    /**
+     * Resolve the checkout path for a repo's section — used to re-absolutize test
+     * paths. `repo` undefined → the primary's metadata.repositoryPath.
+     */
+    getRepoRepositoryPath(repo?: string): Promise<string | undefined>;
+    /** List the related repo keys present in the run-scoped file (empty if single-repo). */
+    listRelatedRepos(): Promise<string[]>;
+    getStatePath(): string;
+    getSessionId(): string;
+    getStateType(): StateType;
+    exists(): boolean;
+    delete(): Promise<void>;
+    getSize(): Promise<number>;
+    getSizeFormatted(): Promise<string>;
+    /**
+     * Cleanup old state files
+     * @param maxAgeHours Maximum age in hours
+     * @param stateDir Directory to clean (defaults to /tmp)
+     * @param stateTypes Which state types to clean (defaults to all)
+     * @returns Number of files deleted
+     */
+    static cleanupOldFiles(maxAgeHours?: number, stateDir?: string, stateTypes?: StateType[]): Promise<number>;
+    /**
+     * List all state files in directory
+     * @param stateDir Directory to search (defaults to /tmp)
+     * @param stateTypes Which state types to list (defaults to all)
+     */
+    static listStateFiles(stateDir?: string, stateTypes?: StateType[]): Promise<Array<{
+        sessionId: string;
+        stateType: StateType;
+        path: string;
+        size: number;
+        createdAt: Date;
+        modifiedAt: Date;
+    }>>;
+}

package/build/utils/AnalysisStateManager.js

@@ -22,6 +22,29 @@ export function setTestsRepoDir(dir) {
 export function getTestsRepoDir() {
     return _testsRepoDir;
 }
+/**
+ * Multi-repo run anchor: the path of the run-scoped analysis state file for the
+ * current Testbot run. One Testbot run = one MCP server process, so a single
+ * module-level value is naturally run-scoped (same pattern as _testsRepoDir and
+ * processSessionRegistry above).
+ *
+ * skyramp_analyze_changes sets this on the FIRST call of a multi-repo run (the one
+ * carrying a `repository`) and REUSES it on subsequent related-repo calls, so every
+ * repo's analysis lands in ONE state file with per-repo sections — without the agent
+ * ever passing a file path (which previously caused filename hallucinations).
+ * Single-repo / standalone calls (no `repository`) never set or read this.
+ */
+let _activeRunStatePath;
+export function setActiveRunStatePath(stateFilePath) {
+    _activeRunStatePath = stateFilePath;
+}
+export function getActiveRunStatePath() {
+    return _activeRunStatePath;
+}
+/** Reset the run anchor — for tests, and as a safety hook between runs. */
+export function clearActiveRunStatePath() {
+    _activeRunStatePath = undefined;
+}
 /**
  * In-memory session store: sessionId → { data, storedAt }.
  * Eliminates the need for the LLM to read/write state files on disk.
@@ -119,6 +142,15 @@ export class StateManager {
         if (stateFilePath) {
             this.stateFile = stateFilePath;
         }
+        else if (stateType === "analysis" && process.env.RUNNER_TEMP) {
+            // In CI (testbot action), RUNNER_TEMP is a job-isolated dir that both the
+            // action and this tool can independently derive — no LLM input needed.
+            // TODO: interim step — remove this branch when stateFile and summaryOutputFile are merged
+            // (see getTestbotPrompt TODO). RUNNER_TEMP is GitHub Actions-specific; other CI systems
+            // (Jenkins, GitLab, Buildkite) must set it explicitly. Once merged, path flows through
+            // summaryOutputFile which is already testbot-controlled and CI-agnostic.
+            this.stateFile = path.join(process.env.RUNNER_TEMP, "skyramp", "analyze-changes-state.json");
+        }
         else {
             const baseDir = stateDir || os.tmpdir();
             const prefix = STATE_FILE_PREFIXES[stateType];
@@ -161,7 +193,11 @@ export class StateManager {
         }
         try {
             const content = await fs.promises.readFile(this.stateFile, "utf-8");
-            const { metadata, ...data } = JSON.parse(content);
+            // Strip both metadata and the multi-repo relatedRepos section so callers
+            // get only the PRIMARY repo's analysis payload (unchanged single-repo shape).
+            const { metadata, relatedRepos, ...data } = JSON.parse(content);
+            void metadata;
+            void relatedRepos;
             logger.debug(`Read data from state file: ${this.stateFile}`);
             return data;
         }
@@ -192,11 +228,14 @@ export class StateManager {
      */
     async writeData(data, options) {
         try {
-            // Read existing metadata if file exists
+            // Read existing metadata + any related-repo sections if file exists, so
+            // rewriting the primary (root) payload preserves the multi-repo sections.
             let existingMetadata;
+            let existingRelated;
             if (this.exists()) {
                 const existing = await this.readFullState();
                 existingMetadata = existing?.metadata;
+                existingRelated = existing?.relatedRepos;
             }
             const state = {
                 ...data,
@@ -204,10 +243,12 @@ export class StateManager {
                     sessionId: this.sessionId,
                     stateType: this.stateType,
                     repositoryPath: options?.repositoryPath || existingMetadata?.repositoryPath,
+                    repository: options?.repository ?? existingMetadata?.repository,
                     createdAt: existingMetadata?.createdAt || new Date().toISOString(),
                     updatedAt: new Date().toISOString(),
                     step: options?.step,
                 },
+                ...(existingRelated ? { relatedRepos: existingRelated } : {}),
             };
             await fs.promises.mkdir(path.dirname(this.stateFile), { recursive: true });
             await fs.promises.writeFile(this.stateFile, JSON.stringify(state, null, 2), "utf-8");
@@ -218,6 +259,106 @@ export class StateManager {
             throw new Error(`Failed to write state file: ${error.message}`);
         }
     }
+    // -----------------------------------------------------------------------
+    // Multi-repo (run-scoped) section access
+    //
+    // State is per-RUN: one file holds the primary repo at the root plus each
+    // related repo under `relatedRepos[<owner/repo>]`. `repo` undefined (or
+    // matching the root's metadata.repo) targets the PRIMARY section, so all
+    // single-repo behavior is unchanged.
+    // -----------------------------------------------------------------------
+    /** Is `repo` the primary section? Primary when `repo` is falsy (single-repo /
+     *  legacy callers), when no state file exists yet (the FIRST write of a run is
+     *  the primary — the testbot prompt mandates the primary is analyzed first), or
+     *  when `repo` matches the `repo` recorded on the root metadata. A non-empty
+     *  `repo` that doesn't match an already-recorded root is a RELATED repo. */
+    async isPrimaryRepo(repo) {
+        if (!repo)
+            return true;
+        // First write of the run is the primary (the prompt mandates the primary is
+        // analyzed first), even when it carries an explicit owner/repo.
+        if (!this.exists())
+            return true;
+        const full = await this.readFullState();
+        // File already exists: primary only if `repo` matches the repo recorded on
+        // the root. An untagged root means the primary was written without a repo
+        // (legacy/single-repo), so any non-empty `repo` here is a RELATED repo.
+        return full?.metadata.repository === repo;
+    }
+    /**
+     * Write one repo's analysis into the run-scoped state file. The primary repo
+     * (repo absent, or matching the root's recorded repo, or the first write of the
+     * run) is written to the root via writeData(); a related repo is upserted into
+     * `relatedRepos[repo]`, preserving the primary + other sections. Used by
+     * skyramp_analyze_changes — every repo in the run writes the SAME stateFile path.
+     */
+    async writeRepoData(data, options) {
+        if (await this.isPrimaryRepo(options.repo)) {
+            await this.writeData(data, {
+                repositoryPath: options.repositoryPath,
+                step: options.step,
+                // Record the primary's owner/repo on the root so later related-repo
+                // writes can distinguish it from a section by matching this value.
+                repository: options.repo,
+            });
+            return;
+        }
+        // Related repo: read the current file (must already exist — primary is
+        // analyzed first), upsert this repo's section, write back.
+        const existing = (await this.readFullState());
+        const base = existing ??
+            {
+                metadata: {
+                    sessionId: this.sessionId,
+                    stateType: this.stateType,
+                    createdAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                },
+            };
+        const relatedRepos = { ...(base.relatedRepos ?? {}) };
+        // Preserve a previously-stored repositoryPath when this write omits it.
+        // Callers that update a section without re-supplying the checkout path (e.g.
+        // skyramp_execute_test writing execution results) must not clobber the path
+        // that skyramp_analyze_changes recorded — getRepoRepositoryPath() relies on
+        // it to re-absolutize that repo's test paths.
+        const priorRepositoryPath = relatedRepos[options.repo]?.repositoryPath;
+        relatedRepos[options.repo] = {
+            data,
+            repositoryPath: options.repositoryPath ?? priorRepositoryPath,
+        };
+        base.relatedRepos = relatedRepos;
+        base.metadata = { ...base.metadata, updatedAt: new Date().toISOString() };
+        await fs.promises.mkdir(path.dirname(this.stateFile), { recursive: true });
+        await fs.promises.writeFile(this.stateFile, JSON.stringify(base, null, 2), "utf-8");
+        logger.debug(`Wrote ${options.repo} section to state file: ${this.stateFile}`);
+    }
+    /**
+     * Read one repo's analysis payload from the run-scoped state file. `repo`
+     * undefined → the primary (root) section (identical to readData()).
+     */
+    async readRepoData(repo) {
+        if (await this.isPrimaryRepo(repo)) {
+            return this.readData();
+        }
+        const full = await this.readFullState();
+        return full?.relatedRepos?.[repo]?.data ?? null;
+    }
+    /**
+     * Resolve the checkout path for a repo's section — used to re-absolutize test
+     * paths. `repo` undefined → the primary's metadata.repositoryPath.
+     */
+    async getRepoRepositoryPath(repo) {
+        const full = await this.readFullState();
+        if (await this.isPrimaryRepo(repo)) {
+            return full?.metadata.repositoryPath;
+        }
+        return full?.relatedRepos?.[repo]?.repositoryPath;
+    }
+    /** List the related repo keys present in the run-scoped file (empty if single-repo). */
+    async listRelatedRepos() {
+        const full = await this.readFullState();
+        return Object.keys(full?.relatedRepos ?? {});
+    }
     getStatePath() {
         return this.stateFile;
     }
@@ -260,7 +401,7 @@ export class StateManager {
      * @returns Number of files deleted
      */
     static async cleanupOldFiles(maxAgeHours = 24, stateDir, stateTypes) {
-        const baseDir = stateDir || os.tmpdir();
+        const baseDir = stateDir || (process.env.RUNNER_TEMP ? path.join(process.env.RUNNER_TEMP, "skyramp") : os.tmpdir());
         const files = await fs.promises.readdir(baseDir).catch(() => []);
         const statePrefixes = stateTypes
             ? stateTypes.map((t) => STATE_FILE_PREFIXES[t])

package/build/utils/AnalysisStateManager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/utils/AnalysisStateManager.test.js

@@ -34,3 +34,101 @@ describe("StateManager.writeData", () => {
         await fs.promises.rm(nestedDir, { recursive: true, force: true });
     });
 });
+describe("StateManager — run-scoped per-repo sections (SKYR-3796)", () => {
+    let stateFile;
+    const mkState = (tag) => ({
+        existingTests: [{ testFile: `${tag}.spec.ts` }],
+        analysisScope: AnalysisScope.CurrentBranchDiff,
+        newEndpoints: [],
+    });
+    beforeEach(() => {
+        stateFile = path.join(os.tmpdir(), `skyramp-analysis-sections-${Date.now()}.json`);
+    });
+    afterEach(async () => {
+        await fs.promises.rm(stateFile, { force: true });
+    });
+    it("keeps the primary at root and additional repos in relatedRepos, all in ONE file", async () => {
+        const mgr = StateManager.fromStatePath(stateFile);
+        // Primary (repo omitted) → root; additional repo → section.
+        await mgr.writeRepoData(mkState("primary"), { repositoryPath: "/work/primary" });
+        await mgr.writeRepoData(mkState("api"), {
+            repo: "letsramp/api-insight",
+            repositoryPath: "/work/api-insight",
+        });
+        // Exactly one file on disk.
+        expect(fs.existsSync(stateFile)).toBe(true);
+        expect(fs.existsSync(`${stateFile}.1.json`)).toBe(false);
+        const raw = JSON.parse(await fs.promises.readFile(stateFile, "utf-8"));
+        // Primary analysis lives at root (backward-compatible single-repo shape).
+        expect(raw.existingTests[0].testFile).toBe("primary.spec.ts");
+        expect(raw.metadata.repositoryPath).toBe("/work/primary");
+        // Additional repo under relatedRepos, keyed by owner/repo.
+        expect(raw.relatedRepos["letsramp/api-insight"].data.existingTests[0].testFile).toBe("api.spec.ts");
+        expect(raw.relatedRepos["letsramp/api-insight"].repositoryPath).toBe("/work/api-insight");
+    });
+    it("reads back the correct section by repo (primary when omitted)", async () => {
+        const mgr = StateManager.fromStatePath(stateFile);
+        await mgr.writeRepoData(mkState("primary"), { repositoryPath: "/work/primary" });
+        await mgr.writeRepoData(mkState("api"), { repo: "letsramp/api-insight", repositoryPath: "/work/api-insight" });
+        expect((await mgr.readRepoData()).existingTests[0].testFile).toBe("primary.spec.ts");
+        expect((await mgr.readRepoData("letsramp/api-insight")).existingTests[0].testFile).toBe("api.spec.ts");
+        expect(await mgr.getRepoRepositoryPath()).toBe("/work/primary");
+        expect(await mgr.getRepoRepositoryPath("letsramp/api-insight")).toBe("/work/api-insight");
+        expect(await mgr.listRelatedRepos()).toEqual(["letsramp/api-insight"]);
+    });
+    it("preserves additional sections when the primary root is rewritten (writeData)", async () => {
+        const mgr = StateManager.fromStatePath(stateFile);
+        await mgr.writeRepoData(mkState("primary"), { repositoryPath: "/work/primary" });
+        await mgr.writeRepoData(mkState("api"), { repo: "letsramp/api-insight", repositoryPath: "/work/api-insight" });
+        // execute_test-style root rewrite must not drop the additional section.
+        const primary = (await mgr.readRepoData());
+        primary.existingTests[0].execution = { marker: "ran" };
+        await mgr.writeData(primary);
+        expect((await mgr.readRepoData("letsramp/api-insight")).existingTests[0].testFile).toBe("api.spec.ts");
+        expect((await mgr.readRepoData()).existingTests[0].execution.marker).toBe("ran");
+    });
+    it("preserves an additional repo's repositoryPath when a later write omits it", async () => {
+        const mgr = StateManager.fromStatePath(stateFile);
+        await mgr.writeRepoData(mkState("primary"), { repositoryPath: "/work/primary" });
+        // analyze_changes records the section WITH its checkout path.
+        await mgr.writeRepoData(mkState("api"), {
+            repo: "letsramp/api-insight",
+            repositoryPath: "/work/api-insight",
+        });
+        // A later write to the same section (e.g. execute_test) omits repositoryPath.
+        await mgr.writeRepoData(mkState("api-ran"), { repo: "letsramp/api-insight" });
+        // The path must survive so getRepoRepositoryPath can still re-absolutize.
+        expect(await mgr.getRepoRepositoryPath("letsramp/api-insight")).toBe("/work/api-insight");
+        expect((await mgr.readRepoData("letsramp/api-insight")).existingTests[0].testFile).toBe("api-ran.spec.ts");
+    });
+    it("routes the primary to root and a related repo to a section when BOTH pass an explicit repo", async () => {
+        const mgr = StateManager.fromStatePath(stateFile);
+        // The agent now always passes an explicit owner/repo, including for the
+        // primary. The FIRST write is the primary → root (tagged on metadata).
+        await mgr.writeRepoData(mkState("primary"), {
+            repo: "letsramp/primary-app",
+            repositoryPath: "/work/primary",
+        });
+        await mgr.writeRepoData(mkState("api"), {
+            repo: "letsramp/api-insight",
+            repositoryPath: "/work/api-insight",
+        });
+        const raw = JSON.parse(await fs.promises.readFile(stateFile, "utf-8"));
+        expect(raw.metadata.repository).toBe("letsramp/primary-app");
+        expect(raw.existingTests[0].testFile).toBe("primary.spec.ts");
+        expect(raw.relatedRepos["letsramp/api-insight"].data.existingTests[0].testFile).toBe("api.spec.ts");
+        // The primary is reachable BOTH by its explicit repo and by omitting it.
+        expect((await mgr.readRepoData("letsramp/primary-app")).existingTests[0].testFile).toBe("primary.spec.ts");
+        expect((await mgr.readRepoData()).existingTests[0].testFile).toBe("primary.spec.ts");
+        expect(await mgr.getRepoRepositoryPath("letsramp/primary-app")).toBe("/work/primary");
+        expect(await mgr.listRelatedRepos()).toEqual(["letsramp/api-insight"]);
+    });
+    it("reads a legacy single-section file (no relatedRepos) as the primary", async () => {
+        const mgr = StateManager.fromStatePath(stateFile);
+        // Legacy write path — no repo, no sections.
+        await mgr.writeData(mkState("legacy"), { repositoryPath: "/work/legacy" });
+        expect((await mgr.readRepoData()).existingTests[0].testFile).toBe("legacy.spec.ts");
+        expect(await mgr.getRepoRepositoryPath()).toBe("/work/legacy");
+        expect(await mgr.listRelatedRepos()).toEqual([]);
+    });
+});

package/build/utils/analyze-openapi.d.ts

@@ -0,0 +1 @@
+export declare function analyzeOpenAPIWithGivenEndpoint(apiSchemaInput: string, uriInput: string, pathParamsInput: string): Promise<string | null>;

package/build/utils/branchDiff.d.ts

@@ -0,0 +1,18 @@
+export interface BranchDiffData {
+    currentBranch: string;
+    baseBranch: string;
+    changedFiles: string[];
+    /** Full unified diff content. */
+    diffContent: string;
+    diffStat: string;
+    /** Files newly created in this branch (--- /dev/null in diff header). Relative paths. */
+    newFiles: string[];
+    /** Files deleted in this branch (+++ /dev/null in diff header). Relative paths. */
+    deletedFiles: string[];
+}
+/**
+ * Extract every file path mentioned in a unified-diff `diff --git` header.
+ * Always uses the `b/` form so renames return the new path.
+ */
+export declare function parseChangedFilesFromDiff(rawDiff: string): string[];
+export declare function computeBranchDiff(repositoryPath: string, providedBaseBranch?: string): Promise<BranchDiffData>;

package/build/utils/dartRouteExtractor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Dart route extraction for Flutter apps using the `go_router` package.
+ *
+ * Walks the repo's Dart sources looking for GoRoute declarations with
+ * string-literal `path:` arguments:
+ *
+ *   GoRoute(path: '/login', builder: (ctx, st) => LoginScreen())
+ *   GoRoute(path: "/profile/:id", builder: ...)
+ *
+ * Why regex (not a Dart compiler): Dart parsers (analyzer, dart-analyzer
+ * package) require a Dart SDK install. Regex on the GoRoute string-literal-path
+ * subset gives ~95% coverage of real customer apps with zero install cost.
+ * Constants like `path: _kHome` are deliberately skipped — emitting them
+ * as a URL `_kHome` would mislead the agent worse than dropping them.
+ *
+ * Each route also carries metadata to support diff-matching in the caller
+ * (findCandidatePagesByDartRoute):
+ *
+ *   - `screenWidgets`: identifiers referenced as builder/pageBuilder targets,
+ *     e.g. `AuthorsScreen`. Resolved through the file's imports to absolute
+ *     paths in `screenFiles`.
+ *   - `screenFiles`: the imported source files those identifiers come from.
+ *   - `isRedirectOnly`: true if the GoRoute has `redirect:` but no
+ *     `builder:` or `pageBuilder:` — these don't render UI, just redirect.
+ *
+ * Scope choices for slice 1:
+ *   - GoRouter only (`MaterialApp.routes` and `auto_route` deferred)
+ *   - String-literal `path:` only (no constant resolution)
+ *   - Nested GoRoutes emit each declaration verbatim — the absolute parent
+ *     plus relative children. Caller may compose them later.
+ */
+/** A route declaration discovered in Dart source. */
+export interface DartRoute {
+    /** URL path string from the GoRoute(path: ...) declaration (verbatim). */
+    path: string;
+    /** Dart file the declaration was found in (absolute path). */
+    declaredIn: string;
+    /** Widget identifiers referenced from builder:/pageBuilder: (e.g. `AuthorsScreen`). */
+    screenWidgets: string[];
+    /** Resolved absolute paths for screenWidgets via the file's imports. */
+    screenFiles: string[];
+    /** True when GoRoute has `redirect:` but no `builder:`/`pageBuilder:` — no UI. */
+    isRedirectOnly: boolean;
+}
+export declare function extractDartRoutes(repositoryPath: string): DartRoute[];

package/build/utils/dartRouteExtractor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/utils/docker.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pull a Docker image by name.
+ *
+ * When `dockerPlatform` is provided, pulls with that exact platform — no
+ * fallback logic runs.  Use this for images whose platform is known ahead
+ * of time (e.g. executor is amd64-only).
+ *
+ * When `dockerPlatform` is omitted, uses the host architecture and falls
+ * back to linux/amd64 if the arm64 pull fails or the image doesn't land
+ * locally (Docker Desktop quirk on Apple Silicon).
+ */
+export declare function pullDockerImage(imageName: string, dockerPlatform?: string): Promise<void>;
+/**
+ * Check if a Docker image exists locally for the given reference (repo:tag or digest).
+ * Uses image inspect (daemon name resolution), not listImages tag scanning.
+ * Returns true if found, false if the image is not present (404).
+ * Throws for any other error (e.g. Docker daemon unreachable) so callers can skip pulling.
+ */
+export declare function dockerImageExistsLocally(imageName: string): Promise<boolean>;

package/build/utils/docker.test.d.ts

@@ -0,0 +1 @@
+export {};