@walkeros/cli 4.0.0-next-1777882869103 → 4.0.1-next-1778068549946

package/CHANGELOG.md

@@ -1,6 +1,56 @@
 # @walkeros/cli
 
-## 4.0.0-next-1777882869103
+## 4.0.1-next-1778068549946
+
+### Patch Changes
+
+- e4b6cf4: Fix `walkeros bundle` failing on Windows when stage 2 import paths
+  contained backslashes that JS parsed as escape sequences.
+- 381dfe7: Add an optional `setup` lifecycle to destinations, sources, and
+  stores.
+
+  Each package may now implement `setup?: SetupFn` to provision external
+  resources (BigQuery datasets and tables, Pub/Sub topics and subscriptions,
+  SQLite tables, webhook registrations, etc.). Setup is triggered only by the
+  new `walkeros setup <kind>.<name>` CLI command, never automatically by the
+  runtime, push, or deploy. Idempotency, ordering, and error semantics are the
+  package's responsibility; the framework provides the type slot, the CLI
+  invocation, and a `resolveSetup(value, defaults)` helper.
+
+  `LifecycleContext<C, E>` is the new shared context type used by both `setup`
+  and `destroy`. `DestroyContext` remains as a deprecated type alias for one
+  minor cycle. The `Types` bundle on `Destination`, `Source`, and `Store` gains
+  a 5th/6th/4th positional slot for setup options; existing aliases compile
+  unchanged because the slot defaults to `unknown`.
+  `Config<T>.setup?: boolean | SetupOptions<T>` is added across all three kinds
+  and validated by the corresponding Zod `ConfigSchema` plus the flow component
+  schemas in `@walkeros/core/schemas/flow.ts`.
+
+  CLI:
+  - `walkeros setup <kind>.<name>` runs a single component's `setup()` function.
+  - `<kind>` is `source`, `destination`, or `store` (transformers have no
+    provisioning).
+  - `--config <path>` (default `./flow.json`), `--flow <name>` for multi-flow
+    configs, plus standard `--json` / `--verbose` / `--silent`.
+  - Exit 0 on success or skip; non-zero on failure. Skip narration covers three
+    cases: no `setup()` on the package, `config.setup === false`, or
+    `config.setup` unset.
+  - When the package's `setup()` returns a non-undefined value, the CLI emits it
+    as JSON on stdout for `jq` piping.
+
+- 03d7055: Merge `definitions` into `variables`. Single concept, single syntax
+  `$var.name(.deep.path)?`. Whole-string references preserve native type; inline
+  interpolation requires scalars. Deep paths and recursive resolution with cycle
+  detection now supported. `Flow.Definitions`, `Flow.Primitive`, and the `$def.`
+  reference syntax are removed.
+- Updated dependencies [381dfe7]
+- Updated dependencies [03d7055]
+  - @walkeros/core@4.0.1-next-1778068549946
+  - @walkeros/collector@4.0.1-next-1778068549946
+  - @walkeros/server-core@4.0.1-next-1778068549946
+  - @walkeros/server-destination-api@4.0.1-next-1778068549946
+
+## 4.0.0
 
 ### Major Changes
 
@@ -232,6 +282,31 @@
 
 ### Patch Changes
 
+- ca237ef: Fix `walkeros push` deadlock for web flows whose destinations await
+  real timers during init.
+
+  Previously, async-drain timer interception captured every `setTimeout` into a
+  pending map and only fired them via a post-`fn` flush. If a destination's init
+  awaited one of those captured timers (e.g.,
+  `@walkeros/web-destination-amplitude`'s engagement plugin awaits a 10s
+  setTimeout to give up on a CDN script load), `init` never resolved,
+  `await collector.push` deadlocked, and Node exited with
+  `Detected unsettled top-level await` (exit 13).
+
+  A drain pump now runs alongside `fn(flowModule)` for non-`--simulate` runs:
+  each tick fires every captured non-cleared timer using a real `setImmediate`
+  reference. Timers fire in delay-ascending order, intervals re-register,
+  callback errors are reported via `console.warn`. Bounded by max-iterations
+  (1000) and wall-clock (30s) caps.
+
+  `--simulate <step>` continues to use the post-`fn` flush path so snapshot
+  ordering remains stable.
+
+  Behavior change (edge case): a destination using `setTimeout` for retry
+  backoff under `walkeros push` (real, non-simulate) now sees its timer fire
+  instantly. This was already the documented contract for `--simulate <step>`
+  snapshots; it now extends to real `push` for consistency.
+
 - 6422b9b: Validate device-code and token responses from the auth server with
   Zod schemas at the trust boundary in `login/index.ts`. Malformed responses now
   surface as structured errors instead of being trusted into config writes or
@@ -271,10 +346,10 @@
 - Updated dependencies [8e06b1f]
 - Updated dependencies [3d50dd6]
 - Updated dependencies [1ef33d9]
-  - @walkeros/core@4.0.0-next-1777882869103
-  - @walkeros/collector@4.0.0-next-1777882869103
-  - @walkeros/server-destination-api@4.0.0-next-1777882869103
-  - @walkeros/server-core@4.0.0-next-1777882869103
+  - @walkeros/core@4.0.0
+  - @walkeros/collector@4.0.0
+  - @walkeros/server-destination-api@4.0.0
+  - @walkeros/server-core@4.0.0
 
 ## 3.4.2
 

package/README.md

@@ -170,15 +170,77 @@ walkeros push dist/bundle.js --platform server --event '{"name":"order complete"
 
 **Push modes:**
 
-| Mode | Flag | API Calls | Use Case |
-| ---- | ---- | --------- | -------- |
-| Real | (none) | Real HTTP requests | Integration testing |
-| Simulate | `--simulate` | Mocked (captured) | Safe local testing |
-| Mock | `--mock` | Returns mock value | Controlled testing |
+| Mode     | Flag         | API Calls          | Use Case            |
+| -------- | ------------ | ------------------ | ------------------- |
+| Real     | (none)       | Real HTTP requests | Integration testing |
+| Simulate | `--simulate` | Mocked (captured)  | Safe local testing  |
+| Mock     | `--mock`     | Returns mock value | Controlled testing  |
 
 Use `--simulate` first to validate safely, then push without flags for real
 integrations.
 
+### setup
+
+Run the optional `setup()` lifecycle on a single component to provision external
+resources (BigQuery datasets, Pub/Sub topics, SQLite tables, webhook
+registrations).
+
+```bash
+walkeros setup <target> [options]
+```
+
+**Target format:** `<kind>.<name>` matching `walkeros push --simulate`. Valid
+kinds: `source`, `destination`, `store`. Transformers are pure functions and
+have no setup.
+
+**Options:**
+
+- `-c, --config <path>` - Flow config file (default: `./flow.json`)
+- `-f, --flow <name>` - Flow name for multi-flow configs
+- `--json` - Output as JSON
+- `-v, --verbose` - Verbose output
+- `-s, --silent` - Suppress output
+
+**Behavior:**
+
+- Loads the flow config, resolves the named component, imports its package, and
+  calls `setup({ id, config, env, logger })`. No collector boot, no event
+  pipeline, no destinations are pushed to.
+- Skips with an explanatory message in three cases: the package has no `setup`
+  function, `config.setup === false`, or `config.setup` is unset.
+- When `setup()` returns a non-undefined value, the CLI emits it as JSON on
+  stdout for `jq`-style scripting.
+- Exit code `0` on success or skip, non-zero on failure.
+
+**Operator-time, never automatic.** Setup is explicit only. It is never
+triggered by `push`, `simulate`, `deploy`, or the long-running runtime.
+Operators run it once when provisioning, and again only when external resources
+need to be re-provisioned.
+
+**IAM note:** Setup typically needs higher permissions than runtime push (for
+example, "create dataset" vs "write rows"). Operators commonly run setup with a
+separate service account or different credentials than the runtime uses.
+
+**Examples:**
+
+```bash
+# Provision the BigQuery dataset and table for the destination named "bigquery"
+# in the default flow file.
+walkeros setup destination.bigquery
+
+# Same but pointing to a specific flow in a multi-flow config.
+walkeros setup destination.bigquery --flow analytics
+
+# Custom config path.
+walkeros setup destination.bigquery --config ./flows/prod.json
+
+# Pipe the structured result to jq.
+walkeros setup destination.bigquery --json | jq .datasetCreated
+
+# Provision a Pub/Sub source's subscription.
+walkeros setup source.events-in
+```
+
 ### run
 
 Run flows locally (no Docker daemon required).
@@ -509,10 +571,7 @@ const result = await push(
 // result.usage = API call tracking data
 
 // Push for real
-await push(
-  './flow.json',
-  { name: 'page view', data: { title: 'Test' } },
-);
+await push('./flow.json', { name: 'page view', data: { title: 'Test' } });
 
 // Run
 await runCommand({