@aiaiai-pt/frankctl 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 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,
+  exposing safe replay reason, snapshot, row count, and attempted/applied
+  effective-SyncSpec fingerprint evidence.
+- Preserve ordinary-sync compatibility with an older API through legacy status
+  polling and safe no-wait output. Capability-check `--force` before mutation,
+  so an unsupported server receives zero sync POSTs.
+- Prefer the precision-safe `snapshot_id_exact` in human sync output while JSON
+  retains numeric `snapshot_id` and exposes the additive exact decimal string.
+
 ## 0.4.3
 
 - Rewrite the bundled agent skill (`SKILL.md`) to be outward-facing and declarative-first: leads with the repeatable `pipelines scaffold → edit → apply` loop (multi-doc `frank.platform/v1` YAML, `--dry-run-server`, `--wait`, idempotency/`--allow-recreate`), with the imperative subcommands as a reference. Drops internal-only content (ticket refs, dev-mode/E2E-harness notes, roadmap).

package/README.md

@@ -37,7 +37,7 @@ frankctl --help
 - `frankctl config set|get|list`
 - `frankctl pipelines list|get|validate|apply|export`
 - `frankctl sources list|get|create|update|delete|discover|sync|logs|history`
-- `frankctl backing-datasets list|get|create|update|delete` (alias: `frankctl bd`)
+- `frankctl backing-datasets list|get|create|update|delete|sync|entities` (alias: `frankctl bd`; `sync --force` replays unchanged data/spec)
 - `frankctl sources streams list|set|refresh-schema`
 - `frankctl transforms list|get|runs|logs|trigger`
 - `frankctl runs get|wait|cancel`
@@ -48,17 +48,56 @@ frankctl --help
 
 Config files for `sources create|update`, `backing-datasets create|update`, and `sources streams set` accept YAML or JSON (use `-` to read stdin).
 
+`frankctl backing-datasets sync <id>` polls exact run evidence when the API
+advertises sync contract v2. For an ordinary sync against an older API, it
+falls back to BackingDataset status polling and explicitly reports that replay
+evidence is unavailable. `--force` is stricter: the CLI verifies the
+capabilities endpoint before the mutating request and sends zero sync POSTs
+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