@walkeros/cli 4.7.0-next-1790245733116 → 4.7.0

package/dist/examples/shared/README.md

@@ -0,0 +1,22 @@
+# shared
+
+Files the server flow of `flow-complete.json` serves first party.
+
+- Root `include: ["./shared"]` ships this folder next to the server artifact.
+- The `assets` store (`@walkeros/server-store-fs`,
+  `basePath: "$env.ASSETS_DIR:./shared"`) reads from it, and the `file`
+  transformer answers `GET /walker.js` with it.
+- `walker.js` is generated, not committed. Build the web flow straight into this
+  folder (web builds ignore root `include`):
+
+```bash
+walkeros bundle packages/cli/examples/flow-complete.json -f web -o packages/cli/examples/shared/walker.js
+```
+
+- Then build and start the server flow; the artifact carries its own copy of
+  this folder:
+
+```bash
+walkeros bundle packages/cli/examples/flow-complete.json -f server -o dist/server.mjs
+runneros start dist/server.mjs -p 8080 --env-file .env
+```

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { Flow, PreviewKey, Elb, Ingest, WalkerOS, Simulation, ObserveWeb } from '@walkeros/core';
+import { Flow, PreviewKey, Elb, Simulation, Ingest, WalkerOS, ObserveWeb } from '@walkeros/core';
 export { Flow } from '@walkeros/core';
 import { BuildOptions as BuildOptions$1 } from 'esbuild';
-import { z, ValidationType, ValidateResult } from '@walkeros/core/dev';
-export { ValidateResult, ValidationError, ValidationType, ValidationWarning, validateFlowStructure } from '@walkeros/core/dev';
+import { z, ValidateResult as ValidateResult$1, ValidationError as ValidationError$1, ValidationWarning as ValidationWarning$1, ValidationType } from '@walkeros/core/dev';
+export { ValidationType, validateFlowStructure } from '@walkeros/core/dev';
 import * as openapi_fetch from 'openapi-fetch';
 
 /**
@@ -102,8 +102,9 @@ interface BuildOptions extends CLIBuildOptions {
      */
     minifyOptions?: MinifyOptions;
     /**
-     * Window property name for collector (web platform only).
-     * @default "collector"
+     * Window property name for collector (web platform only). Set from the
+     * flow's `config.settings.windowCollector`.
+     * @default "walkerOS"
      */
     windowCollector?: string;
     /**
@@ -267,7 +268,7 @@ interface BundleCommandOptions {
     cache?: boolean;
     verbose?: boolean;
     silent?: boolean;
-    /** Config release id baked into config.collector.release (set-if-absent). */
+    /** Release id baked into config.collector.release. Beats an authored one. */
     release?: string;
 }
 declare function bundleCommand(options: BundleCommandOptions): Promise<void>;
@@ -313,8 +314,9 @@ declare function bundle(configOrPath: unknown, options?: {
     cache?: boolean;
     flowName?: string;
     /**
-     * Config release id baked into `config.collector.release` (set-if-absent),
-     * stamping this flow's entry in `event.source.release` at runtime.
+     * Release id baked into `config.collector.release`, stamping this flow's
+     * entry in `event.source.release` at runtime. Beats an authored release;
+     * omitted, the release is a content id of config, packages and CLI.
      */
     release?: string;
     /**
@@ -432,6 +434,29 @@ interface PushCommandOptions {
      * request decoder reads `ingest.url`). Forwarded to `simulateTransformer`.
      */
     ingest?: Omit<Ingest, '_meta'>;
+    /**
+     * Raw `--ingest` flag value (JSON string, file path or URL). Loaded as a
+     * JSON object and used as `ingest` for transformer, collector and
+     * destination simulation.
+     */
+    ingestSource?: string;
+    /**
+     * The collector's starting consent for a simulated transformer, collector
+     * or destination. Forwarded as `consent` (collector: `state.consent`).
+     */
+    consent?: WalkerOS.Consent;
+    /**
+     * Raw `--consent` flag value (JSON string, file path or URL). Loaded as an
+     * object of booleans and used as `consent`.
+     */
+    consentSource?: string;
+    /**
+     * `--command`: a simulated destination runs `collector.command(command,
+     * event)` instead of pushing the event (step examples with `command`).
+     */
+    command?: Flow.StepCommand;
+    /** `--page-url`: the page URL of a simulated web source. */
+    pageUrl?: string;
 }
 /**
  * Push execution result
@@ -443,6 +468,11 @@ interface PushResult {
     networkCalls?: NetworkCall[];
     duration: number;
     error?: string;
+    /**
+     * One result per simulated step, in order (`--simulate`). A multi
+     * destination run stops at the first failure, which is the last entry.
+     */
+    simulations?: Simulation.Result[];
 }
 
 /**
@@ -472,6 +502,15 @@ type PushOptions = z.infer<typeof PushOptionsSchema>;
  * `runPushCommand` directly to avoid `process.exit` killing Jest workers.
  */
 declare function pushCommand(options: PushCommandOptions): Promise<void>;
+/**
+ * Text output of `walkeros push`: the outcome, the push result or one block
+ * per simulated step (its mapping, why nothing was sent, recorded calls), the
+ * error, the duration. Call arguments are scrubbed here (before their cut),
+ * masking `knownSecrets`; `pushCommand` scrubs the whole text at egress.
+ */
+declare function formatPushResult(result: PushResult, options?: {
+    knownSecrets?: readonly string[];
+}): string;
 /**
  * High-level push function for programmatic usage.
  *
@@ -499,6 +538,16 @@ declare function push(configOrPath: string | unknown, event: unknown, options?:
     platform?: Platform;
     mock?: string[];
     snapshot?: string;
+    /**
+     * The config at `configOrPath`, already read by the caller: used as is,
+     * the path is not read again (it still anchors relative paths).
+     */
+    raw?: unknown;
+    /**
+     * Values masked in the flow's logs. Defaults to the values of the
+     * secrets the config references (see `collectKnownSecrets`).
+     */
+    knownSecrets?: readonly string[];
 }): Promise<PushResult>;
 /**
  * Shared data-injection seam for all simulate functions.
@@ -522,12 +571,26 @@ interface SimulateDataOptions {
     data?: Record<string, unknown>;
 }
 interface SimulateSourceOptions extends SimulateDataOptions {
+    /** Log to stderr so stdout carries only the result (`push --json`). */
+    json?: boolean;
     sourceId: string;
     bundlePath?: string;
     flow?: string;
     silent?: boolean;
     verbose?: boolean;
     snapshot?: string;
+    /**
+     * Web sources only: the absolute URL of the simulated page. Defaults to the
+     * input trigger's `options.url` when it is a string, else
+     * `http://localhost`.
+     */
+    pageUrl?: string;
+    /**
+     * The collector's starting consent, handed to `startFlow` as its state
+     * (e.g. the consent a gated source such as the session source waits for).
+     * Never recorded as a call: only the source's own commands are.
+     */
+    consent?: WalkerOS.Consent;
 }
 /**
  * Self-contained source simulation.
@@ -541,6 +604,8 @@ interface SimulateSourceOptions extends SimulateDataOptions {
  */
 declare function simulateSource(configOrPath: string | Flow.Json, input: unknown, options: SimulateSourceOptions): Promise<Simulation.Result>;
 interface SimulateTransformerOptions extends SimulateDataOptions {
+    /** Log to stderr so stdout carries only the result (`push --json`). */
+    json?: boolean;
     transformerId: string;
     bundlePath?: string;
     flow?: string;
@@ -554,6 +619,8 @@ interface SimulateTransformerOptions extends SimulateDataOptions {
      * present; provide only the keys the step reads.
      */
     ingest?: Omit<Ingest, '_meta'>;
+    /** The collector's starting consent, handed to `startFlow` as its state. */
+    consent?: WalkerOS.Consent;
 }
 /**
  * Self-contained transformer simulation.
@@ -568,6 +635,8 @@ interface SimulateTransformerOptions extends SimulateDataOptions {
  */
 declare function simulateTransformer(configOrPath: string | Flow.Json, event: WalkerOS.DeepPartialEvent, options: SimulateTransformerOptions): Promise<Simulation.Result>;
 interface SimulateCollectorOptions extends SimulateDataOptions {
+    /** Log to stderr so stdout carries only the result (`push --json`). */
+    json?: boolean;
     collectorName: string;
     bundlePath?: string;
     flow?: string;
@@ -582,6 +651,12 @@ interface SimulateCollectorOptions extends SimulateDataOptions {
         globals?: WalkerOS.Properties;
         timing?: number;
     };
+    /**
+     * Pipeline context the collector's chain (`collector.next`) reads via
+     * `ctx.ingest`. Merged onto a fresh ingest so `_meta` is always the
+     * runtime's.
+     */
+    ingest?: Omit<Ingest, '_meta'>;
 }
 /**
  * Self-contained collector simulation.
@@ -595,6 +670,8 @@ interface SimulateCollectorOptions extends SimulateDataOptions {
  */
 declare function simulateCollector(configOrPath: string | Flow.Json, event: WalkerOS.DeepPartialEvent, options: SimulateCollectorOptions): Promise<Simulation.Result>;
 interface SimulateDestinationOptions extends SimulateDataOptions {
+    /** Log to stderr so stdout carries only the result (`push --json`). */
+    json?: boolean;
     destinationId: string;
     bundlePath?: string;
     flow?: string;
@@ -602,18 +679,120 @@ interface SimulateDestinationOptions extends SimulateDataOptions {
     silent?: boolean;
     verbose?: boolean;
     snapshot?: string;
+    /**
+     * Pipeline context the destination's `before` chain and push read via
+     * `ctx.ingest` (e.g. `userAgent` for a conversion API). Merged onto a
+     * fresh ingest so `_meta` is always the runtime's.
+     */
+    ingest?: Omit<Ingest, '_meta'>;
+    /**
+     * The collector's starting consent: handed to `startFlow` as its initial
+     * state, which applies it pre-run as a consent command that only the target
+     * (the one registered destination) hears. A `require: ["consent"]`
+     * destination starts, the consent gate sees it, and a Consent Mode target
+     * records its consent update. The event's own consent still applies.
+     */
+    consent?: WalkerOS.Consent;
+    /**
+     * Run `collector.command(command, event)` instead of pushing the event: a
+     * step example with `command` (e.g. `consent`), whose `in` is the command's
+     * data. With `consent`, the starting state applies first, then the command.
+     */
+    command?: Flow.StepCommand;
 }
 /**
  * Self-contained destination simulation.
  *
  * Takes a DeepPartialEvent, validates it with Zod, loads the flow config,
- * bundles it, starts the flow, then pushes via collector.push with an include
- * filter so only the target destination receives the event. This gives full
- * pipeline support — consent checks, event mapping, createEvent enrichment,
- * before chains — without manual wiring.
+ * bundles it, then starts the flow with ONLY the target destination (no
+ * other destination initializes against its real env) and `consent` as the
+ * collector's starting state. It pushes the event through the full pipeline
+ * (consent checks, event mapping, createEvent enrichment, before chains), or
+ * runs `command` with the event as its data. When nothing was sent, the
+ * result's `skipped` says why, from the collector's own records.
  */
-declare function simulateDestination(configOrPath: string | Flow.Json, event: WalkerOS.DeepPartialEvent, options: SimulateDestinationOptions): Promise<Simulation.Result>;
+declare function simulateDestination(configOrPath: string | Flow.Json, event: WalkerOS.DeepPartialEvent | Record<string, unknown>, options: SimulateDestinationOptions): Promise<Simulation.Result>;
 
+/**
+ * Validate Command Schemas
+ *
+ * Zod schemas for validate command parameter validation.
+ */
+
+/**
+ * Validate options schema.
+ *
+ * @remarks
+ * Options for the programmatic validate() API.
+ */
+declare const ValidateOptionsSchema: z.ZodObject<{
+    flow: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+    offline: z.ZodOptional<z.ZodBoolean>;
+    configDir: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ValidateOptions = z.infer<typeof ValidateOptionsSchema>;
+
+/**
+ * Every code an error, warning or skip of `validate` can carry. Agents and
+ * tests branch on these, never on message text.
+ */
+declare const VALIDATE_CODES: readonly ["INPUT_ERROR", "SERIALIZATION_ERROR", "OPTION_NOT_APPLICABLE", "FLOW_NOT_FOUND", "ENTRY_NOT_FOUND", "AMBIGUOUS_ENTRY", "UNSUPPORTED_SECTION", "INVALID_PATH", "SCHEMA_VALIDATION", "CONFIG_WARNING", "EMPTY_FLOWS", "UNKNOWN_KEY", "CONFLICT", "MISSING_PACKAGE", "OBSOLETE_CODE_STRING", "INVALID_IMPORT", "INVALID_CODE_SHAPE", "PACKAGE_VERSION_MISSING", "DEPRECATED_PACKAGE", "UNKNOWN_ROUTE_TARGET", "ROUTE_DEAD_CODE", "ROUTE_EMPTY_MANY", "ROUTE_SINGLE_MANY", "ROUTE_FIRST_MATCH", "INCOMPATIBLE_EXAMPLES", "EXAMPLES_INCOMPLETE", "CONTRACT_VIOLATION", "MAPPING_DOT_KEY", "FLOW_REF_WARNING", "FLOW_CYCLE", "VAR_CYCLE", "INVALID_COMPONENT_NAME", "INVALID_REFERENCE", "STORE_REFERENCE_NOT_FOUND", "UNRESOLVED_REFERENCE", "MISSING_ENV", "WEB_SECRET_REF", "UNRESOLVED_CONTRACT", "ENTRY_SCHEMA", "NO_CONTRACT_SECTION", "INVALID_CONTRACT", "FLAT_CONTRACT_SHAPE", "INVALID_CONTRACT_ENTRY", "UNKNOWN_CONTRACT_KEY", "INVALID_TAGGING", "INVALID_SCHEMA", "INVALID_EXTENDS", "INVALID_SECTION", "INVALID_EVENTS", "CIRCULAR_EXTENDS", "INVALID_ENTITY_KEY", "INVALID_ENTITY", "INVALID_ACTION_KEY", "INVALID_SCHEMA_ENTRY", "NOT_AN_OBJECT", "MISSING_EVENT_NAME", "EMPTY_EVENT_NAME", "INVALID_EVENT_NAME", "INVALID_MAPPING_TYPE", "INVALID_EVENT_PATTERN", "INVALID_RULE_TYPE", "CATCH_ALL_NOT_LAST", "GATED_BY_ERRORS", "CONTRACT_NOT_STATIC", "NO_PACKAGE", "NO_SETTINGS_SCHEMA", "SCHEMA_UNAVAILABLE"];
+type ValidateCode = (typeof VALIDATE_CODES)[number];
+/**
+ * Named checks a run includes (`details.scope.checks`). `file:` checks run
+ * on the whole file whatever `--flow` says; `flow:` checks run per flow in
+ * scope; `entry:` checks run per entry `--path` addressed.
+ */
+type ValidateCheck = 'file:schema' | 'file:contract' | 'flow:schema' | 'flow:steps' | 'flow:structure' | 'flow:package-versions' | 'flow:routes' | 'flow:examples' | 'flow:contract-examples' | 'flow:mapping-keys' | 'flow:resolve' | 'flow:package-settings' | 'entry:settings' | 'contract' | 'event' | 'mapping';
+interface ValidateScopeEntry {
+    /** Section of the addressed entry, when the path or the match names one. */
+    section?: string;
+    key: string;
+    /** Flows that have the entry and were checked. */
+    flows: string[];
+    /** Flows searched for the entry. */
+    searchedFlows: string[];
+}
+/** What a run covered (C6). */
+interface ValidateScope {
+    flows: string[];
+    entry?: ValidateScopeEntry;
+    checks: ValidateCheck[];
+    /** Set when `offline` removed the package settings check from `checks`. */
+    offline?: true;
+}
+/** A check the scope includes that did not run (C5). */
+interface ValidateSkip {
+    path: string;
+    check: ValidateCheck;
+    reason: string;
+    code: ValidateCode;
+}
+/** A value known only at runtime, not schema-checked (info, not a skip). */
+interface ValidateDeferred {
+    path: string;
+    reference: string;
+}
+interface ValidateDetails {
+    scope?: ValidateScope;
+    skipped?: ValidateSkip[];
+    deferred?: ValidateDeferred[];
+    [key: string]: unknown;
+}
+interface ValidationError extends ValidationError$1 {
+    /** The JSON Schema keyword of an ENTRY_SCHEMA error. */
+    keyword?: string;
+}
+interface ValidationWarning extends ValidationWarning$1 {
+    keyword?: string;
+}
+interface ValidateResult extends ValidateResult$1 {
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+    details: ValidateDetails;
+}
 interface ValidateCommandOptions {
     type: ValidationType;
     input?: string;
@@ -623,6 +802,8 @@ interface ValidateCommandOptions {
     json?: boolean;
     verbose?: boolean;
     strict?: boolean;
+    /** Skip every package settings check (no network); named in the scope. */
+    offline?: boolean;
     silent?: boolean;
 }
 
@@ -632,11 +813,7 @@ interface ValidateCommandOptions {
  *
  * Accepts parsed objects, JSON strings, file paths, or URLs as input.
  */
-declare function validate(type: ValidationType, input: unknown, options?: {
-    flow?: string;
-    path?: string;
-    strict?: boolean;
-}): Promise<ValidateResult>;
+declare function validate(type: ValidationType, input: unknown, options?: ValidateOptions): Promise<ValidateResult>;
 /**
  * CLI command handler for validate command.
  */
@@ -15239,11 +15416,11 @@ declare const BuildResultSchema: z.ZodObject<{
     }, z.core.$strip>>;
     error: z.ZodOptional<z.ZodObject<{
         code: z.ZodEnum<{
+            WEB_SECRET_REF: "WEB_SECRET_REF";
             INVALID_MANIFEST: "INVALID_MANIFEST";
             TOOLCHAIN_MISMATCH: "TOOLCHAIN_MISMATCH";
             INVALID_CONFIG: "INVALID_CONFIG";
             MISSING_BUILD_ENV: "MISSING_BUILD_ENV";
-            WEB_SECRET_REF: "WEB_SECRET_REF";
             UNSUPPORTED_PACKAGE_SPEC: "UNSUPPORTED_PACKAGE_SPEC";
             LOCAL_PATH_NOT_ALLOWED: "LOCAL_PATH_NOT_ALLOWED";
             BUILD_FAILED: "BUILD_FAILED";
@@ -15255,6 +15432,26 @@ declare const BuildResultSchema: z.ZodObject<{
 }, z.core.$strip>;
 type BuildResult = z.infer<typeof BuildResultSchema>;
 
+/**
+ * One retry policy for every network call of a manifest build: the manifest
+ * download, a skeleton download and each PUT. A transient failure (the fetch
+ * rejects, times out, or answers 5xx or 429) is retried; any other status
+ * fails at once, since an expired or wrong presign never heals.
+ *
+ * Messages never carry the URL, its query or a header value: presigned
+ * credentials live there.
+ */
+interface FetchRetryOptions {
+    /** Names the call in warnings and errors, e.g. `Manifest download`. */
+    label: string;
+    /** Per-attempt timeout; each attempt gets a fresh signal. */
+    timeoutMs: number;
+    /** Called once per retry with a ready-to-print line. */
+    warn?: (message: string) => void;
+    /** Injectable for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+
 /**
  * `walkeros bundle --manifest <source>`: build from a manifest.
  *
@@ -15270,6 +15467,8 @@ type BuildResult = z.infer<typeof BuildResultSchema>;
 
 /** Env var a bare `--manifest` reads its source from. */
 declare const BUILD_MANIFEST_ENV = "BUILD_MANIFEST_URL";
+/** Retry hooks for the build's network calls; see `fetchWithRetry`. */
+type BuildRetryOptions = Pick<FetchRetryOptions, 'warn' | 'sleep'>;
 interface RunBuildManifestResult {
     result: BuildResult;
     /** False when the result could not be PUT (or the manifest was unreadable). */
@@ -15278,8 +15477,10 @@ interface RunBuildManifestResult {
 /**
  * Run a manifest build end to end. Never throws: every failure becomes a
  * result, and `reported` says whether that result reached `resultPutUrl`.
+ * Each download and upload retries transient failures; `retry.warn` hears
+ * about every retry.
  */
-declare function runBuildManifest(source: string): Promise<RunBuildManifestResult>;
+declare function runBuildManifest(source: string, retry?: BuildRetryOptions): Promise<RunBuildManifestResult>;
 /** Resolve the `--manifest` value, falling back to the env for a bare flag. */
 declare function resolveManifestSource(manifest: string | true, env?: Record<string, string | undefined>): string;
 
@@ -15424,9 +15625,9 @@ interface ClientContext {
 /**
  * Set the client context used to identify this process to the walkerOS app.
  *
- * The CLI binary calls this at startup, the MCP server calls it on boot, and
- * the runner Docker image overrides the resolved type via the
- * `WALKEROS_CLIENT_TYPE` env var (env wins over `input.type`).
+ * The CLI binary calls this at startup and the MCP server calls it on boot.
+ * The `WALKEROS_CLIENT_TYPE` env var overrides the resolved type (env wins
+ * over `input.type`).
  */
 declare function setClientContext(input: {
     type?: ClientType;
@@ -15850,6 +16051,74 @@ declare function loadConfig<T = unknown>(input: string, options?: {
  */
 declare function loadJsonConfig<T>(configPath: string): Promise<T>;
 
+/**
+ * The values of every `$secret.NAME` the flow references, read from `env`.
+ * Names that are unset or empty there are ignored. Hand the result to
+ * `scrubSecrets(line, { known })` or the logger's `knownSecrets` so a secret
+ * value is masked whatever its shape.
+ */
+declare function collectKnownSecrets(flow: Flow.Json, env?: NodeJS.ProcessEnv): string[];
+
+/**
+ * Shared resolver for the export name to import from a flow component's
+ * package.
+ *
+ * Both `walkeros bundle` and `walkeros setup` need to know which named export
+ * (or default) to pull off a package referenced by a flow component. The
+ * precedence chain is:
+ *
+ * 1. `flow.<kind>.<id>.import` if set (named export selector at the step).
+ * 2. `flow.config.bundle.packages[<package>].imports[0]` if set.
+ * 3. Otherwise undefined; the caller falls back to the package's `default`
+ *    export.
+ *
+ * This lives in `cli/src/core/` so both `commands/bundle/*` and
+ * `commands/setup/*` import the same function. Duplicating the chain is how
+ * setup ended up out of sync with bundle (Bug F: `setup destination.pubsub`
+ * routed through BigQuery's setup because it ignored the `code` field and
+ * always grabbed `mod.default`).
+ */
+
+type ComponentKind = 'source' | 'transformer' | 'destination' | 'store';
+type ResolveSource = 'import' | 'imports' | 'default';
+interface ResolvedExportName {
+    /**
+     * The named export to pull off the imported module, or `undefined` to
+     * indicate the caller should use the package's `default` export.
+     */
+    exportName: string | undefined;
+    /** Which precedence step produced the result (useful for diagnostics). */
+    source: ResolveSource;
+}
+/**
+ * Resolve the export name to import for a flow component's package.
+ *
+ * See module docs for the precedence chain. Inline code (`code` is an object)
+ * doesn't enter this resolver at all — setup rejects inline code at a higher
+ * layer.
+ */
+declare function resolveExportName(flow: Flow, kind: ComponentKind, id: string): ResolvedExportName;
+
+/**
+ * Selects the dev examples of one export from a package's awaited `/dev`
+ * module.
+ *
+ * A package with several exports (`walkerOS.exports` in its package.json)
+ * ships `exportExamples`, a map from export name to that export's examples,
+ * the default export included. A package with one export ships only
+ * `examples`.
+ *
+ * - Map present, export named: `exportExamples[exportName]`. A name missing
+ *   from the map resolves to `undefined`, never to another export's examples.
+ * - Map present, no export name (the step uses the default export):
+ *   `examples`, which by convention holds the default export's examples.
+ * - No map: `examples`.
+ *
+ * `exportName` comes from `resolveExportName` (step `import`, else
+ * `bundle.packages[pkg].imports[0]`, else default).
+ */
+declare function selectDevExamples(devModule: unknown, exportName: string | undefined): Record<string, unknown> | undefined;
+
 interface EmitterOptions {
     /** Caller supplies the v4 source verbatim (type, platform, etc). */
     source: WalkerOS.Source;
@@ -15975,6 +16244,8 @@ type PrepareInput = {
     mock?: string[];
     silent?: boolean;
     verbose?: boolean;
+    /** Log to stderr so stdout carries only the result. */
+    json?: boolean;
 } | {
     mode: 'prebuilt';
     bundlePath: string;
@@ -15984,6 +16255,8 @@ type PrepareInput = {
     mock?: string[];
     silent?: boolean;
     verbose?: boolean;
+    /** Log to stderr so stdout carries only the result. */
+    json?: boolean;
 };
 interface PreparedFlow {
     bundlePath: string;
@@ -16003,4 +16276,4 @@ declare module '@walkeros/core' {
     }
 }
 
-export { type AddThreadMessageOptions, ApiError, type ApiErrorDetail, BUILD_ERROR_CODES, BUILD_MANIFEST_ENV, BUILD_MANIFEST_VERSION, type BuildArtifact, BuildArtifactSchema, BuildBundleArtifactSchema, type BuildErrorCode, type BuildManifest, BuildManifestSchema, type BuildOptions, type BuildResult, BuildResultSchema, BuildWrapArtifactSchema, type BuildWrapOptions, BuildWrapOptionsSchema, type BundleStats, type CLIBuildOptions, type ClientContext, type ClientType, type CompareContractInput, type CompleteDeviceLoginOptions, type ContractComparison, type ContractVerdict, type CreatePreviewOptions, type CreateSecretOptions, type CreateThreadOptions, type DeletePreviewOptions, type DeleteSecretOptions, type DeployOptions, DeploymentAmbiguityError, type DeploymentSummaryForFlow, type DeviceAuthorization, type DeviceLoginResult, type EndObserveSessionOptions, type FeedbackOptions, type GetFrameOptions, type GetObserveSessionOptions, type GetPreviewOptions, type GetReleaseOptions, type GlobalOptions, type HealthResult, type ListDeploymentsOptions, type ListFlowsOptions, type ListFramesOptions, type ListJourneysOptions, type ListKnowledgeOptions, type ListPageFramesOptions, type ListPreviewsOptions, type ListProjectsOptions, type ListReleasesOptions, type ListSecretsOptions, type ListStepHistoryOptions, type ListThreadsOptions, type LoginOptions, type LoginResult, type MinifyOptions, type PrepareInput, type PreparedFlow, type ProjectFlows, type PushResult, type RegrantPreviewOptions, type ReleaseDetailResponse, type ReleaseDiffResponse, type ReleaseIndexResponse, type ReleaseRationaleSummary, type ReleaseRef, type RunBuildManifestResult, type SSEEvent, type SSEParseResult, type SetReleaseRationaleOptions, type SimulateCollectorOptions, type SimulateDataOptions, type SimulateDestinationOptions, type SimulateSourceOptions, type SimulateTransformerOptions, type StartObserveSessionOptions, type ThreadAnchorType, type ThreadStatus, type UpdateSecretOptions, VERSION, type WalkerOSConfig, type WrapSkeletonOptions, addThreadMessage, annotateErrorWithDrift, apiFetch, bakedContractHash, bakedContractVersion, buildDataPayload, bundle, bundleCommand, canonicalContractHash, classifyStepProperties, clearAuthFields, clientContextHeaders, compareContract, completeDeviceLogin, containsCodeMarkers, createApiClient, createDeployCommand, createDeployment, createDeploymentCommand, createFlow, createFlowCommand, createPreview, createProject, createProjectCommand, createSecret, createThread, credentialSource, deleteConfig, deleteDeployment, deleteDeploymentByFlowId, deleteDeploymentCommand, deleteFlow, deleteFlowCommand, deletePreview, deleteProject, deleteProjectCommand, deleteSecret, deploy, deployCommand, deployFetch, duplicateFlow, duplicateFlowCommand, endObserveSession, feedback, feedbackCommand, fetchHealth, getAuthHeaders, getClientContext, getDefaultProject, getDeployment, getDeploymentBySlug, getDeploymentBySlugCommand, getDeploymentCommand, getFeedbackPreference, getFlow, getFlowCommand, getFrame, getObserveSession, getPreview, getProject, getProjectCommand, getRelease, listAllFlows, listDeployments, listDeploymentsCommand, listFlows, listFlowsCommand, listFrames, listJourneys, listKnowledge, listPageFrames, listPreviews, listProjects, listProjectsCommand, listReleases, listSecrets, listStepHistory, listThreads, loadConfig, loadJsonConfig, login, loginCommand, logout, logoutCommand, mergeAuthHeaders, parseSSEEvents, publicFetch, push, pushCommand, readConfig, regrantPreview, requireProjectId, resetClientContext, resolveAccessToken, resolveAppUrl, resolveManifestSource, resolveToken, runBuildManifest, setClientContext, setDefaultProject, setFeedbackPreference, setReleaseRationale, simulateCollector, simulateDestination, simulateSource, simulateTransformer, startDeviceAuthorization, startObserveSession, index as telemetry, telemetryDisableCommand, telemetryEnableCommand, telemetryStatusCommand, throwApiError, updateFlow, updateFlowCommand, updateProject, updateProjectCommand, updateSecret, validate, validateCommand, whoami, whoamiCommand, wrapSkeleton, writeConfig };
+export { type AddThreadMessageOptions, ApiError, type ApiErrorDetail, BUILD_ERROR_CODES, BUILD_MANIFEST_ENV, BUILD_MANIFEST_VERSION, type BuildArtifact, BuildArtifactSchema, BuildBundleArtifactSchema, type BuildErrorCode, type BuildManifest, BuildManifestSchema, type BuildOptions, type BuildResult, BuildResultSchema, BuildWrapArtifactSchema, type BuildWrapOptions, BuildWrapOptionsSchema, type BundleStats, type CLIBuildOptions, type ClientContext, type ClientType, type CompareContractInput, type CompleteDeviceLoginOptions, type ContractComparison, type ContractVerdict, type CreatePreviewOptions, type CreateSecretOptions, type CreateThreadOptions, type DeletePreviewOptions, type DeleteSecretOptions, type DeployOptions, DeploymentAmbiguityError, type DeploymentSummaryForFlow, type DeviceAuthorization, type DeviceLoginResult, type EndObserveSessionOptions, type FeedbackOptions, type GetFrameOptions, type GetObserveSessionOptions, type GetPreviewOptions, type GetReleaseOptions, type GlobalOptions, type HealthResult, type ListDeploymentsOptions, type ListFlowsOptions, type ListFramesOptions, type ListJourneysOptions, type ListKnowledgeOptions, type ListPageFramesOptions, type ListPreviewsOptions, type ListProjectsOptions, type ListReleasesOptions, type ListSecretsOptions, type ListStepHistoryOptions, type ListThreadsOptions, type LoginOptions, type LoginResult, type MinifyOptions, type PrepareInput, type PreparedFlow, type ProjectFlows, type PushResult, type RegrantPreviewOptions, type ReleaseDetailResponse, type ReleaseDiffResponse, type ReleaseIndexResponse, type ReleaseRationaleSummary, type ReleaseRef, type RunBuildManifestResult, type SSEEvent, type SSEParseResult, type SetReleaseRationaleOptions, type SimulateCollectorOptions, type SimulateDataOptions, type SimulateDestinationOptions, type SimulateSourceOptions, type SimulateTransformerOptions, type StartObserveSessionOptions, type ThreadAnchorType, type ThreadStatus, type UpdateSecretOptions, VALIDATE_CODES, VERSION, type ValidateCheck, type ValidateCode, type ValidateDeferred, type ValidateResult, type ValidateScope, type ValidateSkip, type ValidationError, type ValidationWarning, type WalkerOSConfig, type WrapSkeletonOptions, addThreadMessage, annotateErrorWithDrift, apiFetch, bakedContractHash, bakedContractVersion, buildDataPayload, bundle, bundleCommand, canonicalContractHash, classifyStepProperties, clearAuthFields, clientContextHeaders, collectKnownSecrets, compareContract, completeDeviceLogin, containsCodeMarkers, createApiClient, createDeployCommand, createDeployment, createDeploymentCommand, createFlow, createFlowCommand, createPreview, createProject, createProjectCommand, createSecret, createThread, credentialSource, deleteConfig, deleteDeployment, deleteDeploymentByFlowId, deleteDeploymentCommand, deleteFlow, deleteFlowCommand, deletePreview, deleteProject, deleteProjectCommand, deleteSecret, deploy, deployCommand, deployFetch, duplicateFlow, duplicateFlowCommand, endObserveSession, feedback, feedbackCommand, fetchHealth, formatPushResult, getAuthHeaders, getClientContext, getDefaultProject, getDeployment, getDeploymentBySlug, getDeploymentBySlugCommand, getDeploymentCommand, getFeedbackPreference, getFlow, getFlowCommand, getFrame, getObserveSession, getPreview, getProject, getProjectCommand, getRelease, listAllFlows, listDeployments, listDeploymentsCommand, listFlows, listFlowsCommand, listFrames, listJourneys, listKnowledge, listPageFrames, listPreviews, listProjects, listProjectsCommand, listReleases, listSecrets, listStepHistory, listThreads, loadConfig, loadJsonConfig, login, loginCommand, logout, logoutCommand, mergeAuthHeaders, parseSSEEvents, publicFetch, push, pushCommand, readConfig, regrantPreview, requireProjectId, resetClientContext, resolveAccessToken, resolveAppUrl, resolveExportName, resolveManifestSource, resolveToken, runBuildManifest, selectDevExamples, setClientContext, setDefaultProject, setFeedbackPreference, setReleaseRationale, simulateCollector, simulateDestination, simulateSource, simulateTransformer, startDeviceAuthorization, startObserveSession, index as telemetry, telemetryDisableCommand, telemetryEnableCommand, telemetryStatusCommand, throwApiError, updateFlow, updateFlowCommand, updateProject, updateProjectCommand, updateSecret, validate, validateCommand, whoami, whoamiCommand, wrapSkeleton, writeConfig };