@aiaiai-pt/frankctl 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to `@aiaiai-pt/frankctl` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.5.0
+
+- Make `Source.spec.streams` declarative desired state: create or patch named
+  streams without resetting runtime state, report omitted streams as unmanaged,
+  export configuration-only stream declarations, and scope `apply --wait` to
+  explicitly declared enabled streams.
+- Add Source-level execution and chunk-budget fields to declarative apply,
+  create/update validation, server preflight, and export.
+- Extend server preflight with opt-in, GET-only live ontology validation through
+  `pipelines apply --dry-run-server --live-ontology`.
+- Correlate `pipelines apply --wait` to the exact Source, Transform, and ontology
+  runs it starts; emit precision-safe snapshot IDs and durable REST bulk-job
+  evidence through `--json`.
+- Validate relationship prerequisites through `BackingDataset.metadata.dependsOn`
+  and execute manual BackingDatasets in topological order.
+- Treat raw pipeline exports as private review material when Sources contain
+  literal credentials; `frankctl` does not interpolate environment variables in
+  Source configuration.
+
 ## 0.4.4
 
 - Add `backing-datasets sync --force` and poll the exact ontology sync run,

package/README.md

@@ -57,15 +57,47 @@ when force replay is unsupported or unadvertised.
 
 ### Declarative apply (`pipelines apply -f`)
 
-`frankctl pipelines apply -f vertical.yaml` provisions a complete Source +
-Pipeline + BackingDataset triple from a single multi-doc YAML file.
+`frankctl pipelines apply -f vertical.yaml` can provision a complete Source +
+Pipeline + BackingDataset triple from a single multi-doc YAML file when the
+Source contains no credential value.
 Docs use the kubectl-style envelope (`apiVersion: frank.platform/v1`,
 `kind:`, `metadata.name:`, `spec:`). The CLI sorts by kind (Source →
 Pipeline → BackingDataset), resolves cross-doc name references to UUIDs,
 and POSTs each doc with `?if-not-exists=true`. `frankctl pipelines export
 <id> -o yaml` round-trips an existing pipeline back to a multi-doc YAML
-file ready for adoption into git. See `../docs/guides/cli.md` for the
-full reference.
+file for private review. Current Source config uses literal credentials,
+`frankctl` performs no environment interpolation, and export preserves that
+config. Split secret-bearing Sources into an untracked mode-0600 file before
+committing the non-secret Pipeline/BackingDataset declarations. See
+`../docs/guides/cli.md` for the full reference and Frank issue #602 for the
+future Vault-backed reference contract.
+
+Relationship-bearing BackingDatasets declare their prerequisites in
+`metadata.dependsOn` and explicitly use `spec.sync_mode: manual`. The graph is
+currently invocation-local rather than persisted server policy, so missing mode
+and `on_materialization` are rejected. `--wait` directly triggers those manual
+BackingDatasets in topological order and requires external targets to be already
+`synced`; missing dependencies, cycles, and self-referential relationships fail
+before execution.
+
+`Source.spec.streams` is desired state on create and reapply: declared streams
+are created/patched by name without resetting cursor, chunk, counter, or run
+state. Omitted streams are preserved and reported as unmanaged; explicitly set
+`is_enabled: false` to disable one. Client dry-run shows the declaration,
+server dry-run shows per-stream actions, and export emits config-only stream
+declarations without runtime state. With `--wait`, an explicit declaration
+syncs only its enabled stream names, so preserved unmanaged streams do not run.
+For a migration, explicitly declare known obsolete enabled streams with
+`is_enabled: false` as well, so scheduled/direct Source syncs converge safely.
+
+Use `--dry-run-server --live-ontology` for an opt-in, GET-only check of
+BackingDataset mappings against the server's configured ontology. Use
+`--wait --json` to execute with exact Source, Transform, and BackingDataset
+run correlation and emit one evidence object. `--wait` does not replace a
+separate ontology entity readback; an ontology run reported as `skipped`
+means the snapshot was already converged and no rows were replayed. REST bulk
+runs include durable job IDs and submitted/completed counts from the exact
+ontology SyncRun; credentials and row payloads are never included.
 
 ## Environment