@walkeros/cli 4.0.0 → 4.0.1-next-1778068549946

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @walkeros/cli
 
+## 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

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({