@appilots/cli 0.4.0 → 0.11.0

package/dist/index.d.mts

@@ -425,6 +425,14 @@ declare class ScreenAnalyzer {
     private extractNavigationParams;
     private extractItemFields;
     private inferItemType;
+    /**
+     * Identity comes from how a field is NAMED, not from what the app
+     * sells: `id`/`uuid`/`key`/`slug` are conventions any codebase uses,
+     * `name`/`title`/`email` are how any row introduces itself. `plate`
+     * used to sit in this list and read like one of them — but it is the
+     * example app's schema, and no other tenant ever got its equivalent
+     * (`mrn`, `trackingNumber`, `sku`) added here.
+     */
     private inferIdentityFields;
     private inferSearchField;
     /**
@@ -457,6 +465,26 @@ declare class NavigationAnalyzer {
     private findNavigationFiles;
     /** Parse navigator definitions from a file */
     private parseNavigators;
+    /**
+     * Is this JSX element `<navigatorVarName.MEMBER …>`?
+     */
+    private isNavigatorMember;
+    /**
+     * Flatten a navigator's JSX children into the `<X.Screen>` elements they
+     * contain, unwrapping every container a real app puts in between.
+     *
+     * The old version compared `t.isJSXElement(child)` against the direct
+     * children only. A ternary is a `JSXExpressionContainer`, so an
+     * auth-gated root — the modal shape of a commercial app, and the shape
+     * of this repo's own `apps/example-app` — contributed ZERO screens to
+     * the graph while `appilots sync` reported success (#396).
+     *
+     * Both branches of a conditional are collected on purpose. The graph is
+     * a design-time map of what routes EXIST, not a prediction of which one
+     * a given session will render; the agent needs the destination name to
+     * be there whether or not the user happens to be logged in right now.
+     */
+    private collectScreenElements;
     /** Extract screens from a navigator JSX element */
     private extractScreensFromNavigator;
     /** Extract string attribute value from JSX attributes */
@@ -827,9 +855,8 @@ interface LoadManifestResult {
 declare function loadManifest(rootDir: string, manifestPath?: string): Promise<LoadManifestResult>;
 /**
  * Merge a declared manifest's screens on top of analyzer-derived screens.
- * The manifest wins on a screen-name conflict (it's the developer's
- * explicit, authoritative statement); screens only one side knows about
- * pass through unchanged.
+ * A screen only one side knows about passes through unchanged; a screen
+ * both sides know is merged key by key (see `mergeScreen`).
  */
 declare function mergeManifestScreens(analyzerScreens: ScreenDescriptor[], manifestScreens: ScreenDescriptor[] | undefined): ScreenDescriptor[];
 /**
@@ -1060,6 +1087,12 @@ interface EvalConfig {
 interface ValidationResult {
     valid: boolean;
     errors: string[];
+    /**
+     * Non-fatal problems — today, keys the CLI does not understand. A typo
+     * here is silently ignored at load time and only surfaces much later as
+     * a confusing failure, so it is worth saying out loud.
+     */
+    warnings: string[];
 }
 /**
  * Environment overrides recognized by the CLI. Precedence when loading:
@@ -1079,10 +1112,12 @@ declare function getEnvOverrides(env?: NodeJS.ProcessEnv): EnvOverrides;
  * environment variables (env wins). Works without a .appilotsrc when
  * APPILOTS_API_KEY is set, so CI can run `appilots sync` with env vars only.
  *
+ * @param onWarn Called once per non-fatal problem (unrecognized keys).
+ *   Commands pass the logger's `warn`; omitting it keeps loading silent.
  * @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;
+declare function loadConfig(onWarn?: (message: string) => void): AppilotsConfig | null;
 /**
  * Saves configuration to .appilotsrc in the given directory
  *
@@ -1140,12 +1175,26 @@ declare function formatMetadataWarnings(warnings: MetadataLintWarning[]): string
 interface SyncResult {
     success: boolean;
     unchanged: boolean;
+    /**
+     * Set by the server when an unchanged upload had to re-activate a
+     * document that was stored but not active — i.e. something else (an
+     * older version, a hand-activated document) was in front of the agent.
+     */
+    activated?: boolean;
     id?: string;
     checksum?: string;
     screensCount?: number;
     formsCount?: number;
     actionsCount?: number;
     error?: string;
+    /**
+     * The server's `error.code`, kept structured alongside the rendered
+     * `error` text so callers can branch on the failure instead of
+     * matching substrings. Absent when the failure produced no envelope.
+     */
+    errorCode?: string;
+    /** HTTP status of the failed response; 0 for network/timeout failures. */
+    errorStatus?: number;
 }
 /**
  * One eval scenario as sent to `POST /cli/eval/run`. Shape mirrors the
@@ -1207,11 +1256,21 @@ interface APIClientConfig {
     /** Retries on network errors / 5xx (default 2) */
     maxRetries?: number;
 }
-/**
- * HTTP client for communicating with Appilots API
- */
 declare class AppilotsAPIClient {
-    private serverUrl;
+    /**
+     * `serverUrl` with the API's mount prefix resolved — every path below
+     * is relative to THIS, not to the configured origin.
+     *
+     * It used to be the raw `serverUrl` with `/api/v1` hardcoded into each
+     * path, which made the field mean something different here than in the
+     * SDK. Both read the same `.appilotsrc`: the SDK completes the prefix
+     * when it is missing, so `https://api.appilots.com/api/v1` is correct
+     * there — and here that same value produced
+     * `/api/v1/api/v1/cli/sync`, a 404 whose body reads `Route not found`.
+     * Sharing `normalizeApiBaseUrl` is what makes one file mean one thing:
+     * with or without the prefix now works in both.
+     */
+    private baseUrl;
     private apiKey;
     private timeoutMs;
     private maxRetries;
@@ -1256,4 +1315,13 @@ declare class AppilotsAPIClient {
     health(): Promise<boolean>;
 }
 
-export { type ActionDescriptor, type AnalyzerConfig, AppilotsAPIClient, type AppilotsConfig, type AppilotsManifest, ComponentAnalyzer, type ComponentDescriptor, DEFAULT_MANIFEST_FILENAME, DEFAULT_WEB_SCREEN_PATTERNS, type EnvOverrides, type FlowDescriptor, type FlowStepDescriptor, FormAnalyzer, type FormDescriptor, type FormFieldDescriptor, GenericPlatformAnalyzer, type LoadManifestResult, type LocatorDescriptor, type MCPDocument, MCPGenerator, type MCPGeneratorConfig, type MCPGeneratorOptions, type MCPOutput, type MetadataLintWarning, NavigationAnalyzer, type NavigationGraph, type NavigationNode, type NavigatorDescriptor, type ParamDescriptor, type PlatformAnalyzer, type PlatformAnalyzerOptions, type PlatformAnalyzerResult, ReactNativePlatformAnalyzer, ReactWebPlatformAnalyzer, type ScreenAgentHints, ScreenAnalyzer, type ScreenDescriptor, type SignalDescriptor, type StatusResult, type SyncResult, type TargetDescriptor, type WaitPolicyDescriptor, WebNavigationAnalyzer, type WebNavigationResult, type WebRoute, WebScreenAnalyzer, formatMetadataWarnings, getConfigPath, getEnvOverrides, lintActionMetadata, loadConfig, loadManifest, mergeManifestNavigation, mergeManifestScreens, resolvePathToScreen, saveConfig, screenNameFromPath, validateConfig };
+/**
+ * GENERATED by scripts/release/sync-sdk-versions.mjs — do not edit.
+ *
+ * The version `@appilots/cli` prints for `appilots --version` and in its
+ * banner. Kept identical to package.json by the release flow;
+ * `version.test.ts` fails if the two ever disagree.
+ */
+declare const CLI_VERSION = "0.11.0";
+
+export { type ActionDescriptor, type AnalyzerConfig, AppilotsAPIClient, type AppilotsConfig, type AppilotsManifest, CLI_VERSION, ComponentAnalyzer, type ComponentDescriptor, DEFAULT_MANIFEST_FILENAME, DEFAULT_WEB_SCREEN_PATTERNS, type EnvOverrides, type FlowDescriptor, type FlowStepDescriptor, FormAnalyzer, type FormDescriptor, type FormFieldDescriptor, GenericPlatformAnalyzer, type LoadManifestResult, type LocatorDescriptor, type MCPDocument, MCPGenerator, type MCPGeneratorConfig, type MCPGeneratorOptions, type MCPOutput, type MetadataLintWarning, NavigationAnalyzer, type NavigationGraph, type NavigationNode, type NavigatorDescriptor, type ParamDescriptor, type PlatformAnalyzer, type PlatformAnalyzerOptions, type PlatformAnalyzerResult, ReactNativePlatformAnalyzer, ReactWebPlatformAnalyzer, type ScreenAgentHints, ScreenAnalyzer, type ScreenDescriptor, type SignalDescriptor, type StatusResult, type SyncResult, type TargetDescriptor, type WaitPolicyDescriptor, WebNavigationAnalyzer, type WebNavigationResult, type WebRoute, WebScreenAnalyzer, formatMetadataWarnings, getConfigPath, getEnvOverrides, lintActionMetadata, loadConfig, loadManifest, mergeManifestNavigation, mergeManifestScreens, resolvePathToScreen, saveConfig, screenNameFromPath, validateConfig };

package/dist/index.d.ts

@@ -425,6 +425,14 @@ declare class ScreenAnalyzer {
     private extractNavigationParams;
     private extractItemFields;
     private inferItemType;
+    /**
+     * Identity comes from how a field is NAMED, not from what the app
+     * sells: `id`/`uuid`/`key`/`slug` are conventions any codebase uses,
+     * `name`/`title`/`email` are how any row introduces itself. `plate`
+     * used to sit in this list and read like one of them — but it is the
+     * example app's schema, and no other tenant ever got its equivalent
+     * (`mrn`, `trackingNumber`, `sku`) added here.
+     */
     private inferIdentityFields;
     private inferSearchField;
     /**
@@ -457,6 +465,26 @@ declare class NavigationAnalyzer {
     private findNavigationFiles;
     /** Parse navigator definitions from a file */
     private parseNavigators;
+    /**
+     * Is this JSX element `<navigatorVarName.MEMBER …>`?
+     */
+    private isNavigatorMember;
+    /**
+     * Flatten a navigator's JSX children into the `<X.Screen>` elements they
+     * contain, unwrapping every container a real app puts in between.
+     *
+     * The old version compared `t.isJSXElement(child)` against the direct
+     * children only. A ternary is a `JSXExpressionContainer`, so an
+     * auth-gated root — the modal shape of a commercial app, and the shape
+     * of this repo's own `apps/example-app` — contributed ZERO screens to
+     * the graph while `appilots sync` reported success (#396).
+     *
+     * Both branches of a conditional are collected on purpose. The graph is
+     * a design-time map of what routes EXIST, not a prediction of which one
+     * a given session will render; the agent needs the destination name to
+     * be there whether or not the user happens to be logged in right now.
+     */
+    private collectScreenElements;
     /** Extract screens from a navigator JSX element */
     private extractScreensFromNavigator;
     /** Extract string attribute value from JSX attributes */
@@ -827,9 +855,8 @@ interface LoadManifestResult {
 declare function loadManifest(rootDir: string, manifestPath?: string): Promise<LoadManifestResult>;
 /**
  * Merge a declared manifest's screens on top of analyzer-derived screens.
- * The manifest wins on a screen-name conflict (it's the developer's
- * explicit, authoritative statement); screens only one side knows about
- * pass through unchanged.
+ * A screen only one side knows about passes through unchanged; a screen
+ * both sides know is merged key by key (see `mergeScreen`).
  */
 declare function mergeManifestScreens(analyzerScreens: ScreenDescriptor[], manifestScreens: ScreenDescriptor[] | undefined): ScreenDescriptor[];
 /**
@@ -1060,6 +1087,12 @@ interface EvalConfig {
 interface ValidationResult {
     valid: boolean;
     errors: string[];
+    /**
+     * Non-fatal problems — today, keys the CLI does not understand. A typo
+     * here is silently ignored at load time and only surfaces much later as
+     * a confusing failure, so it is worth saying out loud.
+     */
+    warnings: string[];
 }
 /**
  * Environment overrides recognized by the CLI. Precedence when loading:
@@ -1079,10 +1112,12 @@ declare function getEnvOverrides(env?: NodeJS.ProcessEnv): EnvOverrides;
  * environment variables (env wins). Works without a .appilotsrc when
  * APPILOTS_API_KEY is set, so CI can run `appilots sync` with env vars only.
  *
+ * @param onWarn Called once per non-fatal problem (unrecognized keys).
+ *   Commands pass the logger's `warn`; omitting it keeps loading silent.
  * @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;
+declare function loadConfig(onWarn?: (message: string) => void): AppilotsConfig | null;
 /**
  * Saves configuration to .appilotsrc in the given directory
  *
@@ -1140,12 +1175,26 @@ declare function formatMetadataWarnings(warnings: MetadataLintWarning[]): string
 interface SyncResult {
     success: boolean;
     unchanged: boolean;
+    /**
+     * Set by the server when an unchanged upload had to re-activate a
+     * document that was stored but not active — i.e. something else (an
+     * older version, a hand-activated document) was in front of the agent.
+     */
+    activated?: boolean;
     id?: string;
     checksum?: string;
     screensCount?: number;
     formsCount?: number;
     actionsCount?: number;
     error?: string;
+    /**
+     * The server's `error.code`, kept structured alongside the rendered
+     * `error` text so callers can branch on the failure instead of
+     * matching substrings. Absent when the failure produced no envelope.
+     */
+    errorCode?: string;
+    /** HTTP status of the failed response; 0 for network/timeout failures. */
+    errorStatus?: number;
 }
 /**
  * One eval scenario as sent to `POST /cli/eval/run`. Shape mirrors the
@@ -1207,11 +1256,21 @@ interface APIClientConfig {
     /** Retries on network errors / 5xx (default 2) */
     maxRetries?: number;
 }
-/**
- * HTTP client for communicating with Appilots API
- */
 declare class AppilotsAPIClient {
-    private serverUrl;
+    /**
+     * `serverUrl` with the API's mount prefix resolved — every path below
+     * is relative to THIS, not to the configured origin.
+     *
+     * It used to be the raw `serverUrl` with `/api/v1` hardcoded into each
+     * path, which made the field mean something different here than in the
+     * SDK. Both read the same `.appilotsrc`: the SDK completes the prefix
+     * when it is missing, so `https://api.appilots.com/api/v1` is correct
+     * there — and here that same value produced
+     * `/api/v1/api/v1/cli/sync`, a 404 whose body reads `Route not found`.
+     * Sharing `normalizeApiBaseUrl` is what makes one file mean one thing:
+     * with or without the prefix now works in both.
+     */
+    private baseUrl;
     private apiKey;
     private timeoutMs;
     private maxRetries;
@@ -1256,4 +1315,13 @@ declare class AppilotsAPIClient {
     health(): Promise<boolean>;
 }
 
-export { type ActionDescriptor, type AnalyzerConfig, AppilotsAPIClient, type AppilotsConfig, type AppilotsManifest, ComponentAnalyzer, type ComponentDescriptor, DEFAULT_MANIFEST_FILENAME, DEFAULT_WEB_SCREEN_PATTERNS, type EnvOverrides, type FlowDescriptor, type FlowStepDescriptor, FormAnalyzer, type FormDescriptor, type FormFieldDescriptor, GenericPlatformAnalyzer, type LoadManifestResult, type LocatorDescriptor, type MCPDocument, MCPGenerator, type MCPGeneratorConfig, type MCPGeneratorOptions, type MCPOutput, type MetadataLintWarning, NavigationAnalyzer, type NavigationGraph, type NavigationNode, type NavigatorDescriptor, type ParamDescriptor, type PlatformAnalyzer, type PlatformAnalyzerOptions, type PlatformAnalyzerResult, ReactNativePlatformAnalyzer, ReactWebPlatformAnalyzer, type ScreenAgentHints, ScreenAnalyzer, type ScreenDescriptor, type SignalDescriptor, type StatusResult, type SyncResult, type TargetDescriptor, type WaitPolicyDescriptor, WebNavigationAnalyzer, type WebNavigationResult, type WebRoute, WebScreenAnalyzer, formatMetadataWarnings, getConfigPath, getEnvOverrides, lintActionMetadata, loadConfig, loadManifest, mergeManifestNavigation, mergeManifestScreens, resolvePathToScreen, saveConfig, screenNameFromPath, validateConfig };
+/**
+ * GENERATED by scripts/release/sync-sdk-versions.mjs — do not edit.
+ *
+ * The version `@appilots/cli` prints for `appilots --version` and in its
+ * banner. Kept identical to package.json by the release flow;
+ * `version.test.ts` fails if the two ever disagree.
+ */
+declare const CLI_VERSION = "0.11.0";
+
+export { type ActionDescriptor, type AnalyzerConfig, AppilotsAPIClient, type AppilotsConfig, type AppilotsManifest, CLI_VERSION, ComponentAnalyzer, type ComponentDescriptor, DEFAULT_MANIFEST_FILENAME, DEFAULT_WEB_SCREEN_PATTERNS, type EnvOverrides, type FlowDescriptor, type FlowStepDescriptor, FormAnalyzer, type FormDescriptor, type FormFieldDescriptor, GenericPlatformAnalyzer, type LoadManifestResult, type LocatorDescriptor, type MCPDocument, MCPGenerator, type MCPGeneratorConfig, type MCPGeneratorOptions, type MCPOutput, type MetadataLintWarning, NavigationAnalyzer, type NavigationGraph, type NavigationNode, type NavigatorDescriptor, type ParamDescriptor, type PlatformAnalyzer, type PlatformAnalyzerOptions, type PlatformAnalyzerResult, ReactNativePlatformAnalyzer, ReactWebPlatformAnalyzer, type ScreenAgentHints, ScreenAnalyzer, type ScreenDescriptor, type SignalDescriptor, type StatusResult, type SyncResult, type TargetDescriptor, type WaitPolicyDescriptor, WebNavigationAnalyzer, type WebNavigationResult, type WebRoute, WebScreenAnalyzer, formatMetadataWarnings, getConfigPath, getEnvOverrides, lintActionMetadata, loadConfig, loadManifest, mergeManifestNavigation, mergeManifestScreens, resolvePathToScreen, saveConfig, screenNameFromPath, validateConfig };