@appilots/cli 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,891 @@
+/**
+ * Core types for the MCP Generator.
+ */
+interface AnalyzerConfig {
+    /** Root directory of the React Native project */
+    rootDir: string;
+    /** Glob patterns for source files */
+    include?: string[];
+    /** Glob patterns to exclude */
+    exclude?: string[];
+    /** TypeScript/JavaScript parser options */
+    parserPlugins?: string[];
+}
+interface ScreenDescriptor {
+    name: string;
+    filePath: string;
+    title?: string;
+    description?: string;
+    components: ComponentDescriptor[];
+    forms: FormDescriptor[];
+    actions: ActionDescriptor[];
+    navigationTargets: string[];
+    /**
+     * Compact operational hints derived from the structured map. These are
+     * designed for the agent prompt, not as the canonical source of truth.
+     */
+    agentHints?: ScreenAgentHints;
+    /** Stable, addressable UI targets the agent can interact with. */
+    targets?: TargetDescriptor[];
+    /** Common multi-step tasks inferred from forms, lists, actions and navigation. */
+    flows?: FlowDescriptor[];
+    collections?: CollectionDescriptor[];
+    /**
+     * Dev-defined prompts to surface as chips in the chat when the user lands
+     * on this screen. Extracted from `registerScreen({ suggestedPrompts: [...] })`.
+     * Persists into the MCP doc so the dashboard can render them and the SDK
+     * can fall back to them on first run before any popular history exists.
+     */
+    suggestedPrompts?: string[];
+    /**
+     * Permission/safety metadata extracted from a `@appilots-permissions`
+     * JSDoc tag on the screen component. Layered under the dashboard
+     * configuration at runtime — see `apps/api/src/common/services/permissions.ts`.
+     */
+    permissions?: ScreenPermissionDescriptor;
+    /**
+     * Convenience flag for screens marked PII via JSDoc (e.g.
+     * `@appilots-pii` or `permissions.isPii: true`). Lifted up so the
+     * runtime can apply project-wide PII guards without re-parsing
+     * the permissions object.
+     */
+    isPii?: boolean;
+}
+interface ScreenPermissionDescriptor {
+    agentAccess?: 'read' | 'write' | 'none';
+    requiresConfirmation?: boolean;
+    blockedActions?: string[];
+    isPii?: boolean;
+}
+interface NavigationGraph {
+    screens: Record<string, NavigationNode>;
+    initialScreen: string;
+    navigators: NavigatorDescriptor[];
+}
+interface NavigationNode {
+    screenName: string;
+    navigatorType: 'stack' | 'tab' | 'drawer';
+    parentNavigator?: string;
+    reachableFrom: string[];
+    reachableTo: string[];
+    params?: ParamDescriptor[];
+}
+interface NavigatorDescriptor {
+    name: string;
+    type: 'stack' | 'tab' | 'drawer';
+    screens: string[];
+    parentNavigator?: string;
+}
+interface ParamDescriptor {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue?: unknown;
+}
+interface ComponentDescriptor {
+    name: string;
+    type: 'view' | 'input' | 'button' | 'list' | 'modal' | 'custom';
+    props?: Record<string, string>;
+    children?: ComponentDescriptor[];
+    testID?: string;
+    accessibilityLabel?: string;
+}
+interface FormDescriptor {
+    id: string;
+    fields: FormFieldDescriptor[];
+    submitAction?: string;
+    validationRules?: Record<string, string>;
+}
+interface FormFieldDescriptor {
+    name: string;
+    label?: string;
+    type: 'text' | 'number' | 'email' | 'phone' | 'select' | 'toggle' | 'date' | 'custom';
+    required: boolean;
+    placeholder?: string;
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    defaultValue?: unknown;
+    locator?: LocatorDescriptor;
+    sourceComponent?: string;
+    valueBinding?: string;
+    errorBinding?: string;
+}
+interface CollectionDescriptor {
+    id: string;
+    component: 'FlatList' | 'SectionList' | 'VirtualizedList' | 'FlashList' | 'ScrollView' | string;
+    itemType?: string;
+    dataSource?: string;
+    keyField?: string;
+    renderItem?: string;
+    displayFields?: string[];
+    rowAction?: RowActionDescriptor;
+    rowActions?: RowActionDescriptor[];
+    identityFields?: string[];
+    searchField?: string;
+}
+interface RowActionDescriptor {
+    type: 'navigation' | 'custom';
+    targetScreen?: string;
+    params?: Record<string, string>;
+    handler?: string;
+    description?: string;
+}
+interface ActionDescriptor {
+    id: string;
+    type: 'navigation' | 'submit' | 'api_call' | 'state_change' | 'custom';
+    label?: string;
+    description?: string;
+    targetScreen?: string;
+    handler?: string;
+    locator?: LocatorDescriptor;
+    sourceComponent?: string;
+    opensModal?: string;
+    opensBottomSheet?: string;
+    successSignal?: SignalDescriptor;
+    failureSignal?: SignalDescriptor;
+    nativeConfirmationExpected?: boolean;
+    /**
+     * BACKLOG 2.2 — Destructive flag.
+     * Set to `true` when:
+     *   - the dev annotated the call site with `@appilots-destructive`,
+     *   - the handler name matches a destructive verb (delete/destroy/
+     *     remove/discard/wipe/revoke/etc.),
+     *   - or a sibling JSX `destructive` prop / `aria-destructive`
+     *     attribute is true.
+     * The runtime auto-injects a `confirm` action before executing
+     * any action carrying `destructive: true` (unless the project
+     * has whitelisted the action id in `neverConfirmActions`).
+     */
+    destructive?: boolean;
+    /**
+     * Structured action semantics for runtimes that need to enforce
+     * policy in multilingual apps without parsing labels. Prefer these
+     * fields when the app/developer can declare them explicitly.
+     */
+    effect?: 'read' | 'write' | 'destructive' | string;
+    riskLevel?: 'low' | 'medium' | 'high' | string;
+    requiresConfirmation?: boolean;
+    /**
+     * Static-analysis hints derived by the MCP generator from the
+     * action's handler body. Used by the SDK to refine waiting and
+     * loading heuristics. None of these fields are guessed by the LLM
+     * — the generator either has enough evidence to populate the
+     * field or leaves it undefined. When all three are undefined, the
+     * SDK falls back to the agnostic runtime signals (ActivityIndicator,
+     * pressed-button-still-disabled, fingerprint quiescence).
+     *
+     * See packages/mcp-generator/docs/INFERRED_ACTION_FIELDS.md for the
+     * detection rules.
+     */
+    appilotsInferred?: AppilotsInferredAction;
+}
+interface LocatorDescriptor {
+    id?: string;
+    appilotsId?: string;
+    testID?: string;
+    accessibilityLabel?: string;
+    label?: string;
+    source?: 'appilotsId' | 'testID' | 'accessibilityLabel' | 'label' | 'inferred' | string;
+}
+interface SignalDescriptor {
+    type: 'navigation' | 'goBack' | 'toast' | 'modal' | 'inline-error' | 'data-arrival' | 'loading' | 'none' | string;
+    target?: string;
+    description?: string;
+}
+interface TargetDescriptor {
+    id: string;
+    role: 'button' | 'submit' | 'input' | 'toggle' | 'select' | 'date' | 'list' | 'row' | 'menuItem' | 'modal' | 'custom' | string;
+    label?: string;
+    locator?: LocatorDescriptor;
+    handler?: string;
+    actionId?: string;
+    fieldName?: string;
+    targetScreen?: string;
+    destructive?: boolean;
+    requiresConfirmation?: boolean;
+    opensModal?: string;
+    opensBottomSheet?: string;
+    sourceComponent?: string;
+}
+interface FlowDescriptor {
+    id: string;
+    title: string;
+    intent: 'navigate' | 'form_submit' | 'list_action' | 'destructive_action' | 'inline_action' | string;
+    steps: FlowStepDescriptor[];
+    waitPolicy?: WaitPolicyDescriptor;
+    safetyNotes?: string[];
+}
+interface FlowStepDescriptor {
+    type: 'navigate' | 'fill' | 'press' | 'select' | 'toggle' | 'wait' | 'confirm' | 'choose-list-item' | string;
+    target?: string;
+    label?: string;
+    description?: string;
+    required?: boolean;
+}
+interface WaitPolicyDescriptor {
+    expectedOutcome?: AppilotsInferredAction['expectedOutcome'] | 'goBack' | 'toast' | 'modal' | string;
+    signals?: SignalDescriptor[];
+    maxMs?: number;
+}
+interface ScreenAgentHints {
+    primaryGoal?: string;
+    commonTasks?: string[];
+    preferredTargets?: string[];
+    waitPolicy?: WaitPolicyDescriptor;
+    safetyNotes?: string[];
+}
+/**
+ * Inferred metadata about an action's expected async behavior.
+ *
+ * Emitted by the MCP generator when it can statically prove (from
+ * the handler source) one of the following — never from heuristic
+ * guessing on labels or props alone.
+ */
+interface AppilotsInferredAction {
+    /**
+     * True when the handler awaits a Promise (await fetch, axios,
+     * useMutation.mutateAsync, etc.) or contains `.then(`/`.catch(`
+     * on a returned Promise. Tells the SDK that pressing this button
+     * is expected to trigger async work, and the runtime wait window
+     * should be more generous (10s instead of 6s).
+     */
+    isAsyncTrigger?: boolean;
+    /**
+     * The most-likely observable outcome of the action, when the
+     * generator can detect one:
+     *   - 'navigation'      : handler calls navigation.navigate /
+     *                         push / replace AFTER the await. SDK
+     *                         expects a route change.
+     *   - 'inline-feedback' : handler updates local state (toast,
+     *                         validation, list re-render) without
+     *                         navigating. SDK waits for fingerprint
+     *                         quiescence only.
+     *   - 'data-arrival'    : handler triggers a data load whose
+     *                         result is rendered into the current
+     *                         screen (e.g. fetching list items into
+     *                         a FlatList). SDK waits for the
+     *                         fingerprint to change AND then settle.
+     *   - 'mixed'           : generator detected more than one of
+     *                         the above. SDK uses the most generous
+     *                         (data-arrival) waiting policy.
+     *   - 'none'            : handler is synchronous local state
+     *                         update only. SDK waits minimally.
+     */
+    expectedOutcome?: 'navigation' | 'inline-feedback' | 'data-arrival' | 'mixed' | 'none';
+    /**
+     * Names of boolean state variables the generator found being set
+     * to `true` immediately before the await and `false` immediately
+     * after. Names only — not runtime values; the SDK can't observe
+     * React state directly, so this field is currently informational
+     * (surfaced in dashboards and used by future tooling). Common
+     * shapes: `['isSubmitting']`, `['isLoading', 'isFetching']`.
+     */
+    loadingStateBindings?: string[];
+}
+
+/**
+ * Analyzes React Native source files to extract screen definitions,
+ * their components, forms, and available actions.
+ *
+ * The analyzer uses Babel AST to:
+ * 1. Extract optional registerScreen() calls (developer-provided metadata)
+ * 2. Detect exported component names
+ * 3. Find navigation patterns (navigation.navigate calls)
+ * 4. Identify form inputs (TextInput, Input components)
+ * 5. Extract button/action handlers
+ *
+ * §1 Strict mode: when `strictScreens` is enabled in config, only files
+ * containing a `registerScreen()` call or matching `screenPatterns` globs
+ * are included in the output. This avoids components/hooks/utils being
+ * listed as screens.
+ */
+declare class ScreenAnalyzer {
+    private config;
+    private verbose;
+    /** When true, only files with registerScreen or matching screen patterns are included */
+    private strictScreens;
+    /** Glob patterns that identify screen files in strict mode */
+    private screenPatterns;
+    /** §D: Count of screens filtered out in strict mode (available after analyze()) */
+    screensFilteredOut: number;
+    constructor(config: AnalyzerConfig, options?: {
+        strictScreens?: boolean;
+        screenPatterns?: string[];
+    });
+    /** Analyze all screens in the project */
+    analyze(): Promise<ScreenDescriptor[]>;
+    /** Analyze a single file. Returns descriptor + whether registerScreen was found. */
+    analyzeFile(filePath: string): Promise<ScreenDescriptor | null>;
+    /**
+     * §B: Detect actual presence of registerScreen() call in the AST.
+     * This is more reliable than checking for title/description which are optional.
+     */
+    private detectRegisterScreenCall;
+    /**
+     * Extract metadata from registerScreen() call
+     */
+    private extractRegisterScreenMetadata;
+    /**
+     * Parse the object passed to registerScreen()
+     */
+    private parseRegisterScreenObject;
+    /**
+     * Parse actions array from registerScreen
+     */
+    private parseActionsArray;
+    /**
+     * Parse a single action object
+     */
+    private parseActionObject;
+    private parseAppilotsInferredObject;
+    /**
+     * Parse fields array from registerScreen
+     */
+    private parseFieldsArray;
+    /**
+     * Parse a single field object
+     */
+    private parseFieldObject;
+    /**
+     * Parse options array for select fields
+     */
+    private parseOptionsArray;
+    private mergeForms;
+    private findEquivalentField;
+    private namedSubmitAction;
+    private mergeFieldMetadata;
+    private findFormWithSharedFields;
+    /**
+     * Extract the name of the default exported component
+     */
+    private extractDefaultComponentName;
+    /**
+     * Extract navigation targets from navigation.navigate() calls
+     */
+    private extractNavigationTargets;
+    /**
+     * Extract form information from JSX
+     */
+    private extractForms;
+    /**
+     * Extract field metadata from a TextInput/Input element
+     */
+    private extractFieldFromInputElement;
+    private isWeakInferredFieldName;
+    /**
+     * Extract component structure from JSX
+     */
+    private extractComponents;
+    /**
+     * Infer component type from component name
+     */
+    private inferComponentType;
+    /**
+     * Extract actions from button/touchable elements
+     */
+    private extractActions;
+    private normalizeLabel;
+    private mergeActionMetadata;
+    private enrichActionsFromHandlers;
+    private collectButtonHandlersByLabel;
+    private collectHandlerInfo;
+    private analyzeHandlerFunction;
+    /**
+     * BACKLOG 2.2 — heuristic destructive detection.
+     *
+     * Combines several signals:
+     *  - JSX `destructive` boolean prop (`<Pressable destructive />`)
+     *  - JSX `aria-destructive` attribute
+     *  - Handler name contains a generic destructive verb
+     *    (delete/destroy/remove/discard/wipe/revoke/etc.). `cancel` is intentionally excluded —
+     *    too many "Cancelar" buttons that just dismiss modals.
+     *  - testID / id contains a destructive verb
+     *
+     * Default-allow with explicit opt-out via `@appilots-non-destructive`
+     * is more dangerous than the inverse, so we default-deny: the
+     * heuristic must hit OR the JSDoc tag must be present.
+     */
+    private isElementDestructive;
+    /**
+     * Extract action metadata from a button element
+     */
+    private extractActionFromButton;
+    private extractInlineOnPressMetadata;
+    private extractFirstHandlerName;
+    private mergeLocator;
+    private expressionToBinding;
+    private slugifyActionId;
+    private extractCollections;
+    private collectRenderItemFunctions;
+    private jsxExpressionIdentifier;
+    private extractKeyField;
+    private extractRowAction;
+    private extractNavigationParams;
+    private extractItemFields;
+    private inferItemType;
+    private inferIdentityFields;
+    private inferSearchField;
+    /**
+     * Extract literal values from AST nodes
+     */
+    private extractLiteralValue;
+    /**
+     * Extract screen name from file path
+     * E.g., /src/screens/ItemListScreen.tsx -> ItemListScreen
+     */
+    private extractScreenName;
+}
+
+/**
+ * Analyzes React Navigation configuration to build a navigation graph.
+ */
+declare class NavigationAnalyzer {
+    private config;
+    /** Extra glob patterns for navigation file discovery (added to defaults) */
+    private navigationInclude;
+    /** Extra glob patterns to exclude from navigation analysis */
+    private navigationExclude;
+    constructor(config: AnalyzerConfig, options?: {
+        navigationInclude?: string[];
+        navigationExclude?: string[];
+    });
+    /** Build the full navigation graph */
+    analyze(): Promise<NavigationGraph>;
+    /** Find all navigation-related files */
+    private findNavigationFiles;
+    /** Parse navigator definitions from a file */
+    private parseNavigators;
+    /** Extract screens from a navigator JSX element */
+    private extractScreensFromNavigator;
+    /** Extract string attribute value from JSX attributes */
+    private extractAttributeValue;
+    /** Parse TypeScript type exports (ParamList types) */
+    private parseParamTypes;
+    /** Extract param entries from a TypeScript type literal */
+    private extractParamListEntries;
+    /** Extract param descriptors from a TypeScript type */
+    private extractParamsFromType;
+    /** Convert TypeScript type annotation to string */
+    private typeToString;
+    /** Infer navigator type from type name */
+    private inferTypeFromName;
+    /** Attach parsed type params to navigator screens */
+    private attachParamsToNavigators;
+    /** Build the complete navigation graph */
+    private buildNavigationGraph;
+}
+
+/**
+ * Analyzes React Native components to extract their semantic meaning,
+ * props, and interaction points.
+ */
+declare class ComponentAnalyzer {
+    private config;
+    constructor(config: AnalyzerConfig);
+    /** Analyze components in a file */
+    analyzeFile(filePath: string): Promise<ComponentDescriptor[]>;
+    private extractComponentFromJSXElement;
+    private getElementName;
+    private determineComponentType;
+    private extractProps;
+    private extractAccessibilityProps;
+    private extractChildren;
+}
+
+/**
+ * Analyzes form structures in React Native screens, extracting
+ * field definitions, validation rules, and submit actions.
+ */
+declare class FormAnalyzer {
+    private config;
+    private stateVariables;
+    private inputElements;
+    private submitButtons;
+    constructor(config: AnalyzerConfig);
+    /** Analyze forms in a file */
+    analyzeFile(filePath: string): Promise<FormDescriptor[]>;
+    private extractStateVariables;
+    private extractFormElements;
+    private extractInputInfo;
+    private extractButtonInfo;
+    private extractAttributeValue;
+    private getElementName;
+    private extractValidationRules;
+    private extractRuleFromCondition;
+    private buildForms;
+    private inferFieldType;
+    private isFieldRequired;
+}
+
+interface MCPGeneratorOptions {
+    /** Output format (only 'json' supported currently) */
+    format: 'json';
+    /** Output directory */
+    outputDir: string;
+    /** Whether to include source file paths */
+    includeSourcePaths?: boolean;
+    /** Whether to generate a single file or per-screen files */
+    splitOutput?: boolean;
+    /** MCP document version */
+    version?: string;
+}
+interface MCPDocument {
+    version: string;
+    generatedAt: string;
+    projectName: string;
+    screens: ScreenDescriptor[];
+    navigation: NavigationGraph;
+    metadata: MCPMetadata;
+}
+interface MCPMetadata {
+    generatorVersion: string;
+    /**
+     * Host app version read from the project's package.json. Lets the
+     * backend match the MCP document to the app build that generated it
+     * (B.4 — OTA fleets run several app versions at once).
+     */
+    appVersion?: string;
+    totalScreens: number;
+    totalForms: number;
+    totalActions: number;
+    /** Number of source files matched by glob (before screen filtering) */
+    analyzedFiles: number;
+    /** Number of files excluded by strict screen filtering (only set when strictScreens is on) */
+    screensFilteredOut?: number;
+}
+interface MCPOutput {
+    document: MCPDocument;
+    filePath: string;
+    format: 'json';
+    checksum: string;
+}
+
+/**
+ * Main generator that orchestrates analyzers and produces MCP documents.
+ *
+ * @example
+ * ```ts
+ * const generator = new MCPGenerator({
+ *   rootDir: './my-rn-app',
+ *   outputDir: '.appilots',
+ *   format: 'json',
+ * });
+ *
+ * const output = await generator.generate();
+ * console.log(`Generated MCP at: ${output.filePath}`);
+ * ```
+ */
+interface MCPGeneratorConfig {
+    rootDir: string;
+    outputDir?: string;
+    format?: 'json';
+    version?: string;
+    includeSourcePaths?: boolean;
+    splitOutput?: boolean;
+    /** §1: Only include files with registerScreen() or matching screen patterns */
+    strictScreens?: boolean;
+    /** §1: Custom glob patterns for screen file detection */
+    screenPatterns?: string[];
+    /** §5: Additional navigation file patterns (added to defaults) */
+    navigationInclude?: string[];
+    /** §5: Exclude patterns for navigation analysis */
+    navigationExclude?: string[];
+    /** Source include patterns */
+    include?: string[];
+    /** Source exclude patterns */
+    exclude?: string[];
+}
+declare class MCPGenerator {
+    private analyzerConfig;
+    private options;
+    private generatorConfig;
+    constructor(config: MCPGeneratorConfig);
+    /** Generate MCP documents from the project */
+    generate(): Promise<MCPOutput>;
+    /**
+     * Read the previously stored checksum from disk.
+     * Returns null if no checksum file exists (first run).
+     *
+     * §4: This replaces the incomplete `hasChanged` static method.
+     * To detect actual changes, compare this value with `output.checksum`
+     * after calling `generate()`.
+     */
+    static readPreviousChecksum(outputDir: string): Promise<string | null>;
+    /**
+     * Calculate SHA-256 checksum of content
+     */
+    private calculateChecksum;
+    private mergeForm;
+    private findEquivalentField;
+    private mergeField;
+    private namedSubmitAction;
+    private isWeakInferredFieldName;
+    private findFormWithSharedFields;
+    /**
+     * Get project name and version from package.json in rootDir
+     */
+    private getProjectInfo;
+}
+
+/**
+ * Appilots configuration interface
+ */
+interface AppilotsConfig {
+    /** API key for authenticating with Appilots backend */
+    apiKey: string;
+    /**
+     * Project ID on Appilots dashboard. Optional at load time — the API key
+     * already identifies the project server-side (env-only CI workflows run
+     * without a .appilotsrc), so commands must not assume it is present.
+     */
+    projectId?: string;
+    /** Server URL for Appilots API */
+    serverUrl: string;
+    /** Output directory for generated files */
+    outputDir?: string;
+    /** Glob patterns to include in analysis */
+    include?: string[];
+    /** Glob patterns to exclude from analysis */
+    exclude?: string[];
+    /** Automatically activate generated MCP on sync */
+    autoActivate?: boolean;
+    /**
+     * Strict screen filtering (§1).
+     * When true, only files with registerScreen() calls or matching
+     * screenPatterns are included as screens in the MCP document.
+     * Default: true (exclude components/hooks/config files from the MCP screen map)
+     */
+    strictScreens?: boolean;
+    /**
+     * Glob patterns that identify screen files (used with strictScreens).
+     * Default: ['**\/*Screen.{ts,tsx}', '**\/screens/**\/*.{ts,tsx}']
+     */
+    screenPatterns?: string[];
+    /**
+     * Additional glob patterns for navigation file discovery (§5).
+     * These are ADDED to the default patterns, not replacing them.
+     */
+    navigationInclude?: string[];
+    /**
+     * Glob patterns to exclude from navigation analysis (§5).
+     */
+    navigationExclude?: string[];
+    /** `appilots eval` settings — see docs: Testing your agent between releases. */
+    eval?: EvalConfig;
+}
+interface EvalConfig {
+    /** Directory of `*.json` scenario files. Default: `<outputDir>/scenarios`. */
+    scenariosDir?: string;
+    /** Committed baseline file. Default: `<outputDir>/eval-baseline.json`. */
+    baselinePath?: string;
+    /** Minimum fraction of scenarios that must pass (0-1). Default: 0.95. */
+    minPassRate?: number;
+    /** Max fractional token increase vs baseline before it's flagged as a
+     * regression on an otherwise-passing scenario. Default: 0.25 (+25%). */
+    maxTokenRegression?: number;
+}
+/**
+ * Validation result type
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Environment overrides recognized by the CLI. Precedence when loading:
+ * command-line flags (applied by each command) > env vars > .appilotsrc.
+ */
+interface EnvOverrides {
+    apiKey?: string;
+    projectId?: string;
+    serverUrl?: string;
+}
+/**
+ * Reads APPILOTS_* environment variables, treating blank values as unset.
+ */
+declare function getEnvOverrides(env?: NodeJS.ProcessEnv): EnvOverrides;
+/**
+ * Loads configuration from the nearest .appilotsrc merged with APPILOTS_*
+ * environment variables (env wins). Works without a .appilotsrc when
+ * APPILOTS_API_KEY is set, so CI can run `appilots sync` with env vars only.
+ *
+ * @returns AppilotsConfig if a file or APPILOTS_API_KEY exists, null otherwise
+ * @throws when the file is unparseable or the merged config fails validation
+ */
+declare function loadConfig(): AppilotsConfig | null;
+/**
+ * Saves configuration to .appilotsrc in the given directory
+ *
+ * @param dir Directory to write .appilotsrc to
+ * @param config Partial config to merge with defaults
+ */
+declare function saveConfig(dir: string, config: Partial<AppilotsConfig>): void;
+/**
+ * Finds and returns the path to the nearest .appilotsrc file by walking up
+ * the directory tree from cwd. Follows the same logic as .npmrc lookup.
+ *
+ * @returns Path to .appilotsrc if found, null otherwise
+ */
+declare function getConfigPath(): string | null;
+/**
+ * Validates an Appilots configuration object for required fields and types
+ *
+ * @param config Configuration object to validate
+ * @returns ValidationResult with valid flag and array of error messages
+ */
+declare function validateConfig(config: any): ValidationResult;
+
+/**
+ * Metadata lint (OKR-005 KR4) — every mutating action registered in the
+ * MCP document should declare `effect` and `riskLevel` so the runtime can
+ * enforce safety policy without parsing labels. The generator extracts
+ * these fields when declared in registerScreen(); this lint surfaces the
+ * ones that were not, instead of letting them pass silently.
+ */
+interface MetadataLintWarning {
+    screen: string;
+    actionId: string;
+    actionType: ActionDescriptor['type'];
+    missing: ('effect' | 'riskLevel')[];
+    reason: string;
+}
+/**
+ * Scans every screen action and returns one warning per mutating action
+ * that is missing `effect` and/or `riskLevel`.
+ */
+declare function lintActionMetadata(document: MCPDocument): MetadataLintWarning[];
+/**
+ * Formats lint warnings for terminal output: one line per action plus an
+ * aggregate line, e.g.
+ *   VehicleDetails.deleteVehicle (submit): missing effect, riskLevel
+ */
+declare function formatMetadataWarnings(warnings: MetadataLintWarning[]): string[];
+
+/**
+ * HTTP client for communicating with the Appilots API backend
+ */
+/**
+ * Result from a sync operation
+ */
+interface SyncResult {
+    success: boolean;
+    unchanged: boolean;
+    id?: string;
+    checksum?: string;
+    screensCount?: number;
+    formsCount?: number;
+    actionsCount?: number;
+    error?: string;
+}
+/**
+ * One eval scenario as sent to `POST /cli/eval/run`. Shape mirrors the
+ * server's `evalScenarioRequestSchema` — kept as a plain interface here
+ * (no @appilots/shared import) since this package publishes standalone.
+ */
+interface EvalScenarioRequest {
+    id: string;
+    screen?: string;
+    observation?: unknown;
+    prompt: string;
+    modelOverride?: string;
+}
+interface EvalScenarioResult {
+    id: string;
+    content: string;
+    actions: Array<{
+        id: string;
+        type: string;
+        payload: Record<string, unknown>;
+    }>;
+    totalTokens: number;
+    totalCostUsd: number;
+    totalLatencyMs: number;
+    modelUsed: string;
+}
+/**
+ * Result from an eval run
+ */
+interface EvalRunResult {
+    results?: EvalScenarioResult[];
+    error?: string;
+}
+/**
+ * Result from a status query
+ */
+interface StatusResult {
+    project?: {
+        id: string;
+        name: string;
+    };
+    activeMcp?: {
+        id: string;
+        version: string;
+        screensCount: number;
+        formsCount: number;
+        actionsCount: number;
+    };
+    error?: string;
+}
+/**
+ * Appilots API client configuration
+ */
+interface APIClientConfig {
+    serverUrl: string;
+    apiKey: string;
+    /** Per-request timeout in ms (default 30s) */
+    timeoutMs?: number;
+    /** Retries on network errors / 5xx (default 2) */
+    maxRetries?: number;
+}
+/**
+ * HTTP client for communicating with Appilots API
+ */
+declare class AppilotsAPIClient {
+    private serverUrl;
+    private apiKey;
+    private timeoutMs;
+    private maxRetries;
+    constructor(config: APIClientConfig);
+    /**
+     * fetch with a hard timeout and exponential-backoff retries. Retries
+     * only on network failures and 5xx responses — 4xx are the caller's
+     * problem and retrying them would just spam the server.
+     */
+    private request;
+    /**
+     * Syncs content with the Appilots backend
+     *
+     * @param content The MCP content object to sync
+     * @param version Version string for the content
+     * @param appVersion Host app version (package.json) — sent as
+     *                   X-App-Version so the backend can associate the MCP
+     *                   document with the app build that produced it
+     * @returns SyncResult with success status and metadata
+     */
+    sync(content: object, version: string, appVersion?: string): Promise<SyncResult>;
+    /**
+     * Gets the status of the Appilots project and active MCP
+     *
+     * @returns StatusResult with project and active MCP information
+     */
+    status(): Promise<StatusResult>;
+    /**
+     * Runs a batch of eval scenarios against the project's MCP document in
+     * decision/dry-run mode — no side effects, same relay path as the
+     * dashboard's sandbox, authenticated with this client's API key.
+     *
+     * @param scenarios Scenarios to run, capped server-side at
+     *   EVAL_MAX_SCENARIOS_PER_RUN (currently 20) as a cost guard.
+     */
+    evalRun(scenarios: EvalScenarioRequest[]): Promise<EvalRunResult>;
+    /**
+     * Checks if the Appilots API server is healthy
+     *
+     * @returns true if server is healthy, false otherwise
+     */
+    health(): Promise<boolean>;
+}
+
+export { type ActionDescriptor, type AnalyzerConfig, AppilotsAPIClient, type AppilotsConfig, ComponentAnalyzer, type ComponentDescriptor, type EnvOverrides, type FlowDescriptor, type FlowStepDescriptor, FormAnalyzer, type FormDescriptor, type FormFieldDescriptor, type LocatorDescriptor, type MCPDocument, MCPGenerator, type MCPGeneratorConfig, type MCPGeneratorOptions, type MCPOutput, type MetadataLintWarning, NavigationAnalyzer, type NavigationGraph, type NavigationNode, type NavigatorDescriptor, type ParamDescriptor, type ScreenAgentHints, ScreenAnalyzer, type ScreenDescriptor, type SignalDescriptor, type StatusResult, type SyncResult, type TargetDescriptor, type WaitPolicyDescriptor, formatMetadataWarnings, getConfigPath, getEnvOverrides, lintActionMetadata, loadConfig, saveConfig, validateConfig };