@skyramp/mcp 0.2.6 → 0.2.150-rc.mntnc

package/build/types/TestAnalysis.d.ts

@@ -0,0 +1,97 @@
+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;
+    };
+    executionBefore?: TestExecutionResult;
+    executionAfter?: TestExecutionResult;
+}

package/build/types/TestExecution.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Types for Test Execution
+ *
+ * These types define the structure for test execution results
+ */
+/** Execution outcome for a test run recorded in the maintenance report. */
+export declare enum TestExecutionStatus {
+    Pass = "Pass",
+    Fail = "Fail",
+    Error = "Error",
+    /** Deliberately not executed — VERIFY/IGNORE actions or DELETE (file removed). */
+    Skipped = "Skipped",
+    /** Execution was expected (UPDATE/REGENERATE) but no result was recorded. */
+    Unknown = "Unknown"
+}
+export interface TestExecutionData {
+    status: TestExecutionStatus;
+    executedAt: string;
+    duration: number;
+    errors: string[];
+    warnings: string[];
+    output?: string;
+    exitCode?: number;
+}
+export interface TestExecutionResult extends TestExecutionData {
+    testFile: string;
+    videoPath?: 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/TestExecution.js

@@ -3,4 +3,14 @@
  *
  * These types define the structure for test execution results
  */
-export {};
+/** Execution outcome for a test run recorded in the maintenance report. */
+export var TestExecutionStatus;
+(function (TestExecutionStatus) {
+    TestExecutionStatus["Pass"] = "Pass";
+    TestExecutionStatus["Fail"] = "Fail";
+    TestExecutionStatus["Error"] = "Error";
+    /** Deliberately not executed — VERIFY/IGNORE actions or DELETE (file removed). */
+    TestExecutionStatus["Skipped"] = "Skipped";
+    /** Execution was expected (UPDATE/REGENERATE) but no result was recorded. */
+    TestExecutionStatus["Unknown"] = "Unknown";
+})(TestExecutionStatus || (TestExecutionStatus = {}));

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/types/TestbotReport.d.ts

@@ -0,0 +1,68 @@
+import type { DriftAction } from "./TestAnalysis.js";
+import type { TestExecutionStatus } from "./TestExecution.js";
+import type { HttpMethod, TestType } from "./TestTypes.js";
+/**
+ * Shape of the JSON report written by skyramp_submit_report and read by testbot
+ * for rendering as Markdown. All fields mirror the corresponding Zod schemas in
+ * submitReportTool.ts — keep the two in sync.
+ */
+export interface TestbotReport {
+    businessCaseAnalysis: string;
+    newTestsCreated: {
+        testId: string;
+        testType: TestType;
+        endpoint: string;
+        fileName: string;
+        reasoning: string;
+        description?: string;
+        scenarioFile?: string;
+        traceFile?: string;
+        frontendTrace?: string;
+    }[];
+    /** Omitted when no existing tests were found (agent omits the field). */
+    testMaintenance?: {
+        testType: TestType;
+        endpoint: string;
+        fileName: string;
+        description: string;
+        action: DriftAction;
+        beforeStatus: TestExecutionStatus;
+        beforeDetails: string;
+        afterStatus: TestExecutionStatus;
+        afterDetails: string;
+    }[];
+    testResults: {
+        testType: TestType;
+        endpoint: string;
+        status: "Pass" | "Fail" | "Skipped";
+        details: string;
+        videoPath?: string;
+    }[];
+    additionalRecommendations?: {
+        testId: string;
+        testType: TestType;
+        category?: string;
+        primaryEndpoint?: string;
+        scenarioName?: string;
+        steps: {
+            method?: HttpMethod;
+            path?: string;
+            description: string;
+            expectedStatusCode?: number;
+            requestBody?: Record<string, unknown>;
+            responseBody?: Record<string, unknown>;
+        }[];
+        description: string;
+        priority: "high" | "medium" | "low";
+        reasoning: string;
+        openApiSpec?: string;
+        backendTrace?: string;
+        frontendTrace?: string;
+    }[];
+    issuesFound: {
+        description: string;
+        severity?: "critical" | "high" | "medium" | "low";
+    }[];
+    nextSteps: string[];
+    commitMessage: string;
+}

package/build/types/TestbotReport.js

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

package/build/types/index.d.ts

@@ -0,0 +1,4 @@
+export { TestExecutionStatus } from "./TestExecution.js";
+export { DriftAction } from "./TestAnalysis.js";
+export { TestType, HttpMethod } from "./TestTypes.js";
+export type { TestbotReport } from "./TestbotReport.js";

package/build/types/index.js

@@ -0,0 +1,3 @@
+export { TestExecutionStatus } from "./TestExecution.js";
+export { DriftAction } from "./TestAnalysis.js";
+export { TestType, HttpMethod } from "./TestTypes.js";

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