@skyramp/mcp 0.2.6 → 0.2.7

package/build/types/TestAnalysis.d.ts

@@ -0,0 +1,96 @@
+import { TestExecutionResult } from "./TestExecution.js";
+export declare enum RecommendationPriority {
+    High = "high",
+    Medium = "medium",
+    Low = "low"
+}
+export declare enum IssueSeverity {
+    Low = "low",
+    Medium = "medium",
+    High = "high",
+    Critical = "critical"
+}
+export declare enum DriftChangeType {
+    EndpointAdded = "endpoint_added",
+    EndpointRemoved = "endpoint_removed",
+    EndpointRenamed = "endpoint_renamed",
+    EndpointModified = "endpoint_modified",
+    AuthenticationChanged = "authentication_changed",
+    SchemaChanges = "schema_changes",
+    RouteChanged = "route_changed",
+    RouteAdded = "route_added",
+    RouteRemoved = "route_removed",
+    UiComponentAdded = "ui_component_added",
+    UiComponentRemoved = "ui_component_removed",
+    UiComponentModified = "ui_component_modified",
+    UiComponentRestructured = "ui_component_restructured",
+    DependencyChanged = "dependency_changed",
+    FunctionChanged = "function_changed",
+    ClassChanged = "class_changed",
+    BreakingChange = "breaking_change",
+    CodeChange = "code_change"
+}
+export interface DriftChange {
+    type: DriftChangeType;
+    file: string;
+    description: string;
+    severity: IssueSeverity;
+    details?: string;
+}
+export interface AffectedFiles {
+    files: string[];
+}
+/** Origin of a test file — whether it was generated by Skyramp or is user/third-party maintained. */
+export declare enum TestSource {
+    Skyramp = "skyramp",
+    External = "external"
+}
+/** Drift action assigned by the LLM health assessment for an existing test. */
+export declare enum DriftAction {
+    Update = "UPDATE",
+    Regenerate = "REGENERATE",
+    Delete = "DELETE",
+    Verify = "VERIFY",
+    Ignore = "IGNORE"
+}
+/** Estimated effort to apply a drift UPDATE action. */
+export declare enum EstimatedWork {
+    Small = "Small",
+    Medium = "Medium",
+    Large = "Large"
+}
+/** Normalized internal recommendation built from LLM-supplied args.recommendations. */
+export interface DriftRecommendation {
+    testFile: string;
+    action: DriftAction;
+    priority: RecommendationPriority;
+    rationale: string;
+    estimatedWork: EstimatedWork;
+    updateInstructions: string;
+    renamedEndpoints: Array<{
+        oldPath: string;
+        newPath: string;
+        method: string;
+    }>;
+    /** Computed during instruction building — suggested renamed file path if applicable. */
+    _suggestedNewFile?: string;
+}
+/**
+ * Complete test analysis result that combines discovery, drift, execution, and health data
+ */
+export interface TestAnalysisResult {
+    testFile: string;
+    testType: string;
+    language: string;
+    framework: string;
+    apiSchema?: string;
+    apiEndpoint?: string;
+    /** Origin of this test. Defaults to TestSource.Skyramp for backwards compatibility
+     *  with existing state files. */
+    source?: TestSource;
+    drift?: {
+        changes: DriftChange[];
+        affectedFiles: AffectedFiles;
+    };
+    execution?: TestExecutionResult;
+}

package/build/types/TestExecution.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Types for Test Execution
+ *
+ * These types define the structure for test execution results
+ */
+export interface TestExecutionData {
+    passed: boolean;
+    executedAt: string;
+    duration: number;
+    errors: string[];
+    warnings: string[];
+    crashed: boolean;
+    output?: string;
+    exitCode?: number;
+}
+export interface TestExecutionResult extends TestExecutionData {
+    testFile: string;
+}
+export interface BatchExecutionResult {
+    totalTests: number;
+    passed: number;
+    failed: number;
+    crashed: number;
+    totalDuration: number;
+    results: TestExecutionResult[];
+}
+export interface TestExecutionOptions {
+    testFile: string;
+    workspacePath: string;
+    language: string;
+    testType: string;
+    token?: string;
+    timeout?: number;
+    playwrightSaveStoragePath?: string;
+    useHostNetwork?: boolean;
+}
+/**
+ * Progress callback for reporting execution status
+ */
+export interface ExecutionProgress {
+    phase: "docker-check" | "docker-pull" | "preparing" | "executing" | "processing";
+    message: string;
+    percent: number;
+    details?: {
+        cached?: boolean;
+        pullProgress?: {
+            current?: number;
+            total?: number;
+            layer?: string;
+        };
+    };
+}
+export type ProgressCallback = (progress: ExecutionProgress) => Promise<void>;

package/build/types/TestRecommendation.d.ts

@@ -0,0 +1,12 @@
+/** Internal scenario-scoring tier — UPPERCASE, includes CRITICAL. */
+export type PriorityTier = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+/** All categories including internal ones. */
+export declare const SCENARIO_CATEGORIES: readonly ["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"];
+export type ScenarioCategory = typeof SCENARIO_CATEGORIES[number];
+/** Categories valid for tool submissions (excludes internal-only categories). */
+export declare const TEST_CATEGORIES: readonly ["business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"];
+export type TestCategory = typeof TEST_CATEGORIES[number];
+/** Priority assignment for each category. */
+export declare const CATEGORY_PRIORITY: Record<ScenarioCategory, PriorityTier>;
+/** Map internal-only categories to their external equivalent for tool submission. */
+export declare function externalCategory(cat: ScenarioCategory): TestCategory;

package/build/types/TestTypes.d.ts

@@ -0,0 +1,234 @@
+import { z } from "zod";
+export declare const SESSION_STORAGE_FILENAME = "skyramp_session_storage.json";
+export declare const AUTH_PLACEHOLDER_TOKEN = "SKYRAMP_PLACEHOLDER_TOKEN";
+export declare enum ProgrammingLanguage {
+    PYTHON = "python",
+    TYPESCRIPT = "typescript",
+    JAVASCRIPT = "javascript",
+    JAVA = "java"
+}
+export declare enum TestType {
+    SMOKE = "smoke",
+    FUZZ = "fuzz",
+    CONTRACT = "contract",
+    LOAD = "load",
+    INTEGRATION = "integration",
+    E2E = "e2e",
+    UI = "ui",
+    MOCK = "mock"
+}
+export declare enum HttpMethod {
+    GET = "GET",
+    POST = "POST",
+    PUT = "PUT",
+    DELETE = "DELETE",
+    PATCH = "PATCH",
+    HEAD = "HEAD",
+    OPTIONS = "OPTIONS"
+}
+export declare enum RuntimeEnvironment {
+    LOCAL = "local",
+    DOCKER = "docker",
+    KUBERNETES = "kubernetes"
+}
+export interface TestConfig {
+    testType: TestType;
+    toolName: string;
+    description: string;
+    additionalFields?: Record<string, z.ZodSchema>;
+}
+export declare const languageSchema: z.ZodObject<{
+    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    framework: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    language: ProgrammingLanguage;
+    framework: string;
+}, {
+    language: ProgrammingLanguage;
+    framework: string;
+}>;
+export declare const baseSchema: z.ZodObject<{
+    deployDashboard: z.ZodDefault<z.ZodBoolean>;
+    runtime: z.ZodDefault<z.ZodNativeEnum<typeof RuntimeEnvironment>>;
+    dockerNetwork: z.ZodDefault<z.ZodString>;
+    dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
+    k8sNamespace: z.ZodDefault<z.ZodString>;
+    k8sConfig: z.ZodDefault<z.ZodString>;
+    k8sContext: z.ZodDefault<z.ZodString>;
+    authHeader: z.ZodDefault<z.ZodString>;
+    authScheme: z.ZodDefault<z.ZodString>;
+    insecure: z.ZodDefault<z.ZodBoolean>;
+    output: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    outputDir: z.ZodString;
+    force: z.ZodDefault<z.ZodBoolean>;
+    mockPort: z.ZodDefault<z.ZodNumber>;
+    optionalFields: z.ZodDefault<z.ZodBoolean>;
+    prompt: z.ZodString;
+    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    framework: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    language: ProgrammingLanguage;
+    framework: string;
+    deployDashboard: boolean;
+    runtime: RuntimeEnvironment;
+    dockerNetwork: string;
+    dockerWorkerPort: number;
+    k8sNamespace: string;
+    k8sConfig: string;
+    k8sContext: string;
+    authHeader: string;
+    authScheme: string;
+    insecure: boolean;
+    outputDir: string;
+    force: boolean;
+    mockPort: number;
+    optionalFields: boolean;
+    prompt: string;
+    output?: string | undefined;
+}, {
+    language: ProgrammingLanguage;
+    framework: string;
+    outputDir: string;
+    prompt: string;
+    deployDashboard?: boolean | undefined;
+    runtime?: RuntimeEnvironment | undefined;
+    dockerNetwork?: string | undefined;
+    dockerWorkerPort?: number | undefined;
+    k8sNamespace?: string | undefined;
+    k8sConfig?: string | undefined;
+    k8sContext?: string | undefined;
+    authHeader?: string | undefined;
+    authScheme?: string | undefined;
+    insecure?: boolean | undefined;
+    output?: string | undefined;
+    force?: boolean | undefined;
+    mockPort?: number | undefined;
+    optionalFields?: boolean | undefined;
+}>;
+export declare const basePlaywrightSchema: z.ZodObject<{
+    playwrightInput: z.ZodString;
+    playwrightStoragePath: z.ZodOptional<z.ZodString>;
+    playwrightSaveStoragePath: z.ZodOptional<z.ZodString>;
+    playwrightViewportSize: z.ZodDefault<z.ZodUnion<[z.ZodEnum<["", "hd", "full-hd", "2k"]>, z.ZodString]>>;
+    browser: z.ZodDefault<z.ZodEnum<["chromium", "firefox", "webkit"]>>;
+    device: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    playwrightInput: string;
+    playwrightViewportSize: string;
+    browser: "chromium" | "firefox" | "webkit";
+    device: string;
+    playwrightStoragePath?: string | undefined;
+    playwrightSaveStoragePath?: string | undefined;
+}, {
+    playwrightInput: string;
+    playwrightStoragePath?: string | undefined;
+    playwrightSaveStoragePath?: string | undefined;
+    playwrightViewportSize?: string | undefined;
+    browser?: "chromium" | "firefox" | "webkit" | undefined;
+    device?: string | undefined;
+}>;
+export declare const baseTraceSchema: z.ZodObject<{
+    deployDashboard: z.ZodDefault<z.ZodBoolean>;
+    runtime: z.ZodDefault<z.ZodNativeEnum<typeof RuntimeEnvironment>>;
+    dockerNetwork: z.ZodDefault<z.ZodString>;
+    dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
+    k8sNamespace: z.ZodDefault<z.ZodString>;
+    k8sConfig: z.ZodDefault<z.ZodString>;
+    k8sContext: z.ZodDefault<z.ZodString>;
+    authHeader: z.ZodDefault<z.ZodString>;
+    authScheme: z.ZodDefault<z.ZodString>;
+    insecure: z.ZodDefault<z.ZodBoolean>;
+    output: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    outputDir: z.ZodString;
+    force: z.ZodDefault<z.ZodBoolean>;
+    mockPort: z.ZodDefault<z.ZodNumber>;
+    optionalFields: z.ZodDefault<z.ZodBoolean>;
+    prompt: z.ZodString;
+    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    framework: z.ZodString;
+    trace: z.ZodString;
+    include: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    language: ProgrammingLanguage;
+    framework: string;
+    deployDashboard: boolean;
+    runtime: RuntimeEnvironment;
+    dockerNetwork: string;
+    dockerWorkerPort: number;
+    k8sNamespace: string;
+    k8sConfig: string;
+    k8sContext: string;
+    authHeader: string;
+    authScheme: string;
+    insecure: boolean;
+    outputDir: string;
+    force: boolean;
+    mockPort: number;
+    optionalFields: boolean;
+    prompt: string;
+    trace: string;
+    include: string[];
+    exclude: string[];
+    output?: string | undefined;
+}, {
+    language: ProgrammingLanguage;
+    framework: string;
+    outputDir: string;
+    prompt: string;
+    trace: string;
+    deployDashboard?: boolean | undefined;
+    runtime?: RuntimeEnvironment | undefined;
+    dockerNetwork?: string | undefined;
+    dockerWorkerPort?: number | undefined;
+    k8sNamespace?: string | undefined;
+    k8sConfig?: string | undefined;
+    k8sContext?: string | undefined;
+    authHeader?: string | undefined;
+    authScheme?: string | undefined;
+    insecure?: boolean | undefined;
+    output?: string | undefined;
+    force?: boolean | undefined;
+    mockPort?: number | undefined;
+    optionalFields?: boolean | undefined;
+    include?: string[] | undefined;
+    exclude?: string[] | undefined;
+}>;
+export declare const baseTestSchema: {
+    deployDashboard: z.ZodDefault<z.ZodBoolean>;
+    runtime: z.ZodDefault<z.ZodNativeEnum<typeof RuntimeEnvironment>>;
+    dockerNetwork: z.ZodDefault<z.ZodString>;
+    dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
+    k8sNamespace: z.ZodDefault<z.ZodString>;
+    k8sConfig: z.ZodDefault<z.ZodString>;
+    k8sContext: z.ZodDefault<z.ZodString>;
+    authHeader: z.ZodDefault<z.ZodString>;
+    authScheme: z.ZodDefault<z.ZodString>;
+    insecure: z.ZodDefault<z.ZodBoolean>;
+    output: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    outputDir: z.ZodString;
+    force: z.ZodDefault<z.ZodBoolean>;
+    mockPort: z.ZodDefault<z.ZodNumber>;
+    optionalFields: z.ZodDefault<z.ZodBoolean>;
+    prompt: z.ZodString;
+    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    framework: z.ZodString;
+    endpointURL: z.ZodString;
+    method: z.ZodDefault<z.ZodUnion<[z.ZodNativeEnum<typeof HttpMethod>, z.ZodLiteral<"">]>>;
+    apiSchema: z.ZodDefault<z.ZodString>;
+    pathParams: z.ZodDefault<z.ZodString>;
+    queryParams: z.ZodDefault<z.ZodString>;
+    formParams: z.ZodDefault<z.ZodString>;
+    requestData: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
+    responseStatusCode: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
+};
+export declare const codeRefactoringSchema: z.ZodObject<{
+    codeReuse: z.ZodDefault<z.ZodBoolean>;
+    modularizeCode: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    codeReuse: boolean;
+    modularizeCode: boolean;
+}, {
+    codeReuse?: boolean | undefined;
+    modularizeCode?: boolean | undefined;
+}>;

package/build/utils/AnalysisStateManager.d.ts

@@ -0,0 +1,182 @@
+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 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;
+    createdAt: string;
+    updatedAt: string;
+    step?: string;
+}
+/**
+ * State file format - data fields at root level with metadata
+ * Example: { tests: [...], metadata: {...} }
+ * Example: { repositoryPath: "...", analysis: {...}, mapping: {...}, metadata: {...} }
+ */
+type StateFile<T> = T & {
+    metadata: StateMetadata;
+};
+/**
+ * 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;
+    }): Promise<void>;
+    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.test.d.ts

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

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 {};