@walkeros/cli 2.0.0 → 2.1.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Flow, Elb } from '@walkeros/core';
+import { Flow, Elb, WalkerOS } from '@walkeros/core';
 export { Flow } from '@walkeros/core';
 import { BuildOptions as BuildOptions$1 } from 'esbuild';
 import { z } from '@walkeros/core/dev';
@@ -143,40 +143,6 @@ interface MinifyOptions {
     legalComments?: 'none' | 'inline' | 'eof' | 'linked' | 'external';
 }
 
-/**
- * Global CLI Options
- *
- * Options that apply to all commands.
- */
-/**
- * Global options available across all CLI commands
- */
-interface GlobalOptions {
-    /**
-     * Show detailed execution logs
-     * @default false
-     */
-    verbose?: boolean;
-    /**
-     * Suppress all output except errors
-     * @default false
-     */
-    silent?: boolean;
-}
-
-/**
- * Input Detector
- *
- * Detects whether CLI input is a config JSON or pre-built bundle.
- * Supports both local files and URLs.
- */
-type Platform$1 = 'web' | 'server';
-
-declare function getToken(): string | undefined;
-declare function getAuthHeaders(): Record<string, string>;
-declare function resolveBaseUrl(): string;
-declare function requireProjectId(): string;
-
 interface BundleStats {
     totalSize: number;
     packages: {
@@ -252,19 +218,13 @@ declare function bundleRemote(options: {
     stats: any;
 }>;
 
-/**
- * Call Tracker for Simulation
- *
- * Wraps mock environment functions to track API calls.
- * Used with destination-provided examples/env.ts mocks.
- */
+/** Tracked API call from destination simulation */
 interface ApiCall {
     type: 'call';
     path: string;
     args: unknown[];
     timestamp: number;
 }
-
 interface SimulateCommandOptions {
     config?: string;
     output?: string;
@@ -274,6 +234,16 @@ interface SimulateCommandOptions {
     verbose?: boolean;
     silent?: boolean;
     platform?: 'web' | 'server';
+    example?: string;
+    step?: string;
+}
+interface ExampleMatch {
+    name: string;
+    step: string;
+    expected: unknown;
+    actual: unknown;
+    match: boolean;
+    diff?: string;
 }
 interface SimulationResult {
     success: boolean;
@@ -283,6 +253,9 @@ interface SimulationResult {
     logs?: unknown[];
     usage?: Record<string, ApiCall[]>;
     duration?: number;
+    exampleMatch?: ExampleMatch;
+    /** Events captured by source simulation */
+    capturedEvents?: WalkerOS.DeepPartialEvent[];
 }
 
 /**
@@ -301,7 +274,7 @@ declare const PlatformSchema: z.ZodEnum<{
     web: "web";
     server: "server";
 }>;
-type Platform = z.infer<typeof PlatformSchema>;
+type Platform$1 = z.infer<typeof PlatformSchema>;
 /**
  * Simulate options schema.
  *
@@ -315,6 +288,69 @@ declare const SimulateOptionsSchema: z.ZodObject<{
 }, z.core.$strip>;
 type SimulateOptions = z.infer<typeof SimulateOptionsSchema>;
 
+/**
+ * Input Detector
+ *
+ * Detects whether CLI input is a config JSON or pre-built bundle.
+ * Supports both local files and URLs.
+ */
+type Platform = 'web' | 'server';
+
+declare function getToken(): string | undefined;
+declare function getAuthHeaders(): Record<string, string>;
+/**
+ * Fetch with deploy token priority for heartbeat calls.
+ * Priority: WALKEROS_DEPLOY_TOKEN > WALKEROS_TOKEN > config file
+ */
+declare function deployAuthenticatedFetch(url: string, init?: RequestInit): Promise<Response>;
+declare function resolveBaseUrl(): string;
+declare function requireProjectId(): string;
+
+interface SSEEvent {
+    type: string;
+    data: string;
+}
+interface SSEParseResult {
+    parsed: SSEEvent[];
+    remainder: string;
+}
+declare function parseSSEEvents(buffer: string): SSEParseResult;
+
+type StepType = 'source' | 'transformer' | 'destination';
+interface ExampleLookupResult {
+    stepType: StepType;
+    stepName: string;
+    exampleName: string;
+    example: {
+        in?: unknown;
+        mapping?: unknown;
+        out?: unknown;
+    };
+}
+/**
+ * Find a named example in a flow config.
+ *
+ * Searches sources, transformers, and destinations for a matching example.
+ * If --step is provided (e.g. "destination.gtag"), looks only in that step.
+ * If not, searches all steps and errors if ambiguous.
+ *
+ * @param config - Raw (unresolved) flow config with examples intact
+ * @param exampleName - Name of the example to find
+ * @param stepTarget - Optional step target in "type.name" format
+ * @returns The found example with its location
+ */
+declare function findExample(config: Flow.Config, exampleName: string, stepTarget?: string): ExampleLookupResult;
+
+/**
+ * Compare simulation output against expected example output.
+ */
+declare function compareOutput(expected: unknown, actual: unknown): {
+    expected: unknown;
+    actual: unknown;
+    match: boolean;
+    diff?: string;
+};
+
 /**
  * CLI command handler for simulate command
  */
@@ -355,7 +391,9 @@ declare function simulateCommand(options: SimulateCommandOptions): Promise<void>
  */
 declare function simulate(configOrPath: string | unknown, event: unknown, options?: SimulateOptions & {
     flow?: string;
-    platform?: Platform;
+    platform?: Platform$1;
+    example?: string;
+    step?: string;
 }): Promise<SimulationResult>;
 
 /**
@@ -428,7 +466,7 @@ declare function pushCommand(options: PushCommandOptions): Promise<void>;
  */
 declare function push(configOrPath: string | unknown, event: unknown, options?: PushOptions & {
     flow?: string;
-    platform?: Platform$1;
+    platform?: Platform;
 }): Promise<PushResult>;
 
 /**
@@ -436,10 +474,6 @@ declare function push(configOrPath: string | unknown, event: unknown, options?:
  *
  * Types for running walkerOS flows via CLI using local runtime
  */
-/**
- * Run mode - determines which execution mode to use
- */
-type RunMode = 'collect' | 'serve';
 /**
  * CLI command options for `walkeros run`
  */
@@ -450,16 +484,22 @@ interface RunCommandOptions {
     port?: number;
     /** Server host (default: 0.0.0.0) */
     host?: string;
-    /** Serve path (URL directory path, e.g., 'libs/v1') */
-    servePath?: string;
-    /** Serve name (filename in URL, default: walker.js) */
-    serveName?: string;
     /** Enable JSON output */
     json?: boolean;
     /** Verbose logging */
     verbose?: boolean;
     /** Suppress output */
     silent?: boolean;
+    /** Deployment slug (enables heartbeat to walkerOS app) */
+    deployment?: string;
+    /** Project ID (used with --deploy) */
+    project?: string;
+    /** Public URL of this server (used with --deploy) */
+    url?: string;
+    /** Health check endpoint path (used with --deploy, default: /health) */
+    healthEndpoint?: string;
+    /** Heartbeat interval in seconds (used with --deploy, default: 60) */
+    heartbeatInterval?: number;
 }
 /**
  * Programmatic run options (subset of CLI options)
@@ -471,10 +511,6 @@ interface RunOptions {
     port?: number;
     /** Server host */
     host?: string;
-    /** Serve path (URL directory path, e.g., 'libs/v1') */
-    servePath?: string;
-    /** Serve name (filename in URL, default: walker.js) */
-    serveName?: string;
     /** Suppress output */
     silent?: boolean;
     /** Verbose logging */
@@ -503,40 +539,40 @@ interface RunResult {
 /**
  * CLI command function for `walkeros run`
  *
- * @param mode - Run mode (collect | serve)
  * @param options - Command options
  */
-declare function runCommand(mode: string, options: RunCommandOptions): Promise<void>;
+declare function runCommand(options: RunCommandOptions): Promise<void>;
 /**
  * Programmatic run function
  *
- * @param mode - Run mode (collect | serve)
  * @param options - Run options
  * @returns Run result
  *
  * @example
  * ```typescript
  * // Run with JSON config (bundles automatically)
- * await run('collect', {
+ * await run({
  *   config: './flow.json',
  *   port: 8080
  * });
  *
  * // Run with pre-built bundle
- * await run('collect', {
+ * await run({
  *   config: './flow.mjs',
  *   port: 8080
  * });
  * ```
  */
-declare function run(mode: RunMode, options: RunOptions): Promise<RunResult>;
+declare function run(options: RunOptions): Promise<RunResult>;
 
-type ValidationType = 'event' | 'flow' | 'mapping' | 'entry';
+type ValidationType = 'contract' | 'event' | 'flow' | 'mapping';
+type ValidateResultType = ValidationType | 'entry';
 interface ValidateCommandOptions {
     type: ValidationType;
     input?: string;
     output?: string;
     flow?: string;
+    path?: string;
     json?: boolean;
     verbose?: boolean;
     strict?: boolean;
@@ -555,7 +591,7 @@ interface ValidationWarning {
 }
 interface ValidateResult {
     valid: boolean;
-    type: ValidationType;
+    type: ValidateResultType;
     errors: ValidationError[];
     warnings: ValidationWarning[];
     details: Record<string, unknown>;
@@ -565,14 +601,36 @@ interface ValidateResult {
  * Programmatic API for validation.
  * Can be called directly from code or MCP server.
  */
-declare function validate(type: ValidationType | string, input: unknown, options?: {
+declare function validate(type: ValidationType, input: unknown, options?: {
     flow?: string;
+    path?: string;
 }): Promise<ValidateResult>;
 /**
  * CLI command handler for validate command.
  */
 declare function validateCommand(options: ValidateCommandOptions): Promise<void>;
 
+/**
+ * Global CLI Options
+ *
+ * Options that apply to all commands.
+ */
+/**
+ * Global options available across all CLI commands
+ */
+interface GlobalOptions {
+    /**
+     * Show detailed execution logs
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Suppress all output except errors
+     * @default false
+     */
+    silent?: boolean;
+}
+
 interface LoginCommandOptions extends GlobalOptions {
     url?: string;
     json?: boolean;
@@ -800,6 +858,9 @@ interface DeployOptions {
     projectId?: string;
     wait?: boolean;
     flowName?: string;
+    timeout?: number;
+    signal?: AbortSignal;
+    onStatus?: (status: string, substatus: string | null) => void;
 }
 declare function deploy(options: DeployOptions): Promise<any>;
 declare function getDeployment(options: {
@@ -811,12 +872,48 @@ interface DeployCommandOptions extends GlobalOptions {
     project?: string;
     flow?: string;
     wait?: boolean;
+    timeout?: string;
     output?: string;
     json?: boolean;
 }
 declare function deployCommand(flowId: string, options: DeployCommandOptions): Promise<void>;
 declare function getDeploymentCommand(flowId: string, options: DeployCommandOptions): Promise<void>;
 
+interface ListDeploymentsOptions {
+    projectId?: string;
+    type?: 'web' | 'server';
+    status?: string;
+}
+declare function listDeployments(options?: ListDeploymentsOptions): Promise<any>;
+declare function getDeploymentBySlug(options: {
+    slug: string;
+    projectId?: string;
+}): Promise<any>;
+declare function createDeployment(options: {
+    type: 'web' | 'server';
+    label?: string;
+    projectId?: string;
+}): Promise<any>;
+declare function deleteDeployment(options: {
+    slug: string;
+    projectId?: string;
+}): Promise<any>;
+interface DeploymentsCommandOptions extends GlobalOptions {
+    json?: boolean;
+    output?: string;
+    project?: string;
+    type?: string;
+    status?: string;
+    label?: string;
+}
+declare function listDeploymentsCommand(options: DeploymentsCommandOptions): Promise<void>;
+declare function getDeploymentBySlugCommand(slug: string, options: DeploymentsCommandOptions): Promise<void>;
+declare function createDeploymentCommand(options: DeploymentsCommandOptions): Promise<void>;
+declare function deleteDeploymentCommand(slug: string, options: DeploymentsCommandOptions): Promise<void>;
+declare function createDeployCommand(config: string | undefined, options: DeploymentsCommandOptions & {
+    flow?: string;
+}): Promise<void>;
+
 /**
  * This file was auto-generated by openapi-typescript.
  * Do not make direct changes to the file.
@@ -3198,4 +3295,22 @@ interface components {
 
 declare function createApiClient(): openapi_fetch.Client<paths, `${string}/${string}`>;
 
-export { type BuildOptions, type BundleStats, type CLIBuildOptions, type DeployOptions, type GlobalOptions, type ListFlowsOptions, type MinifyOptions, type PushResult, type RunCommandOptions, type RunMode, type RunOptions, type RunResult, type SimulationResult, type ValidateResult, type ValidationError, type ValidationType, type ValidationWarning, bundle, bundleCommand, bundleRemote, createApiClient, createFlow, createFlowCommand, createProject, createProjectCommand, deleteFlow, deleteFlowCommand, deleteProject, deleteProjectCommand, deploy, deployCommand, duplicateFlow, duplicateFlowCommand, getAuthHeaders, getDeployment, getDeploymentCommand, getFlow, getFlowCommand, getProject, getProjectCommand, getToken, listFlows, listFlowsCommand, listProjects, listProjectsCommand, loginCommand, logoutCommand, push, pushCommand, requireProjectId, resolveBaseUrl, run, runCommand, simulate, simulateCommand, updateFlow, updateFlowCommand, updateProject, updateProjectCommand, validate, validateCommand, whoami, whoamiCommand };
+/**
+ * Load and parse JSON configuration file from local path or URL.
+ *
+ * @param configPath - Path to JSON file or HTTP/HTTPS URL
+ * @returns Parsed configuration object and cleanup function
+ * @throws Error if file not found, download fails, or invalid JSON
+ *
+ * @example
+ * ```typescript
+ * // Local file
+ * const config = await loadJsonConfig('./config.json')
+ *
+ * // Remote URL
+ * const config = await loadJsonConfig('https://example.com/config.json')
+ * ```
+ */
+declare function loadJsonConfig<T>(configPath: string): Promise<T>;
+
+export { type BuildOptions, type BundleStats, type CLIBuildOptions, type DeployOptions, type ExampleLookupResult, type ExampleMatch, type GlobalOptions, type ListDeploymentsOptions, type ListFlowsOptions, type MinifyOptions, type PushResult, type RunCommandOptions, type RunOptions, type RunResult, type SSEEvent, type SSEParseResult, type SimulationResult, type ValidateResult, type ValidationError, type ValidationType, type ValidationWarning, bundle, bundleCommand, bundleRemote, compareOutput, createApiClient, createDeployCommand, createDeployment, createDeploymentCommand, createFlow, createFlowCommand, createProject, createProjectCommand, deleteDeployment, deleteDeploymentCommand, deleteFlow, deleteFlowCommand, deleteProject, deleteProjectCommand, deploy, deployAuthenticatedFetch, deployCommand, duplicateFlow, duplicateFlowCommand, findExample, getAuthHeaders, getDeployment, getDeploymentBySlug, getDeploymentBySlugCommand, getDeploymentCommand, getFlow, getFlowCommand, getProject, getProjectCommand, getToken, listDeployments, listDeploymentsCommand, listFlows, listFlowsCommand, listProjects, listProjectsCommand, loadJsonConfig, loginCommand, logoutCommand, parseSSEEvents, push, pushCommand, requireProjectId, resolveBaseUrl, run, runCommand, simulate, simulateCommand, updateFlow, updateFlowCommand, updateProject, updateProjectCommand, validate, validateCommand, whoami, whoamiCommand };