@sylphx/cli 0.9.2 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,77 @@
1
1
  # @sylphx/cli
2
2
 
3
+ ## 0.12.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#1126](https://github.com/SylphxAI/platform/pull/1126) [`b5c6c14`](https://github.com/SylphxAI/platform/commit/b5c6c142ba89078edf460807282337dc315b77df) Thanks [@shtse8](https://github.com/shtse8)! - ADR-141..146 — health observability stack lands across the SDK, CLI, contract, and management surfaces.
8
+
9
+ ## `@sylphx/sdk` (`@sylphx/sdk/health`) — new public surface
10
+
11
+ - **`withHealth.{hono,express,fastify,fetch}`** — framework-agnostic Zero-Config `/healthz` middleware. Drop one line into your Hono / Express / Fastify / Next.js / Bun.serve app and you get a multi-signal continuous-score health endpoint, OTel emission, causality propagation, and audit-grade history out of the box.
12
+ - **Seven built-in signals**: `eventLoopLagSignal`, `queueDepthSignal`, `errorRateSignal`, `memoryPressureSignal`, `pingSignal`, `databaseSignal`, `redisSignal`. Compose them via `sylphxHealth({ signals: [...] })`; the default scoring strategy is weighted geometric mean per ADR-111 §4.5.
13
+ - **ADR-142 OTel-native emission** — `health.score`, `health.signal.factor`, `health.signal.value`, `health.signal.value_state`, `health.downstream_cause` metrics + `service.health.*` span attributes + `health.evaluated` event. Default-on; graceful no-op when `@opentelemetry/api` is not installed.
14
+ - **ADR-143 causality propagation** — read/write OTel Baggage entries `sylphx.health.cause` + `sylphx.health.cause_chain`. A Postgres outage produces one paged alert at the root plus N silent downstream-impact rows, not 12 red dots. Default-on with a 0.5 score threshold.
15
+ - **ADR-144 audit-grade history** — every `evaluate()` produces a SHA-256 prev-hash chained `HistoryEntry` (CloudTrail-style integrity), retrievable via `getHistory(query?)` / verifiable via `verifyHistory(query?)`. Pluggable `HistoryStore` interface; in-memory ring buffer is the reference implementation.
16
+
17
+ ## `@sylphx/cli`
18
+
19
+ - **`sylphx migrate health-checks`** — idempotent codemod that wires `withHealth.*` into your app's entry file (Hono / Express / Fastify / Next.js auto-detected) and removes hand-rolled `/health` + `/ready` routes. Supports `--dry-run` and `--check` (CI-grade exit-1-on-pending).
20
+ - **`sylphx migrate status`** — per-service fleet visibility. Queries the Management API for every visible project and reports which services have `frameworkSignals.sdkHealthDetected = true`. The answer to "which of my services still need ADR-141?".
21
+ - **`sylphx health verify --file <path>`** — offline verifier for an exported ADR-144 history chain. Walks the SHA-256 chain and reports the first break with a clear reason. Mirrors AWS CloudTrail `validate-logs`.
22
+
23
+ ## `@sylphx/management` + `@sylphx/contract`
24
+
25
+ - **`TriggerDeploymentInput.frameworkSignals`** — optional map of `service slug → { sdkHealthDetected?: boolean }`. The CLI now scans `package.json` at deploy time and forwards these signals; the Management API merges them into `project_services.machine_config.frameworkSignals` before the reconciler picks up the deploy. Used by the reconciler smart-default (HTTP `/healthz` probe when the SDK is detected) and by the new ADR-111 Phase B sidecar SDK-detection gate.
26
+ - **`Service.frameworkSignals`** — new read-only field on the Service response so `sylphx migrate status` can render the fleet scorecard.
27
+
28
+ ## Why upgrade
29
+
30
+ Every Sylphx service gets the SOTA dataplane for free — continuous score in `[0, 1]`, multi-signal composition, OTel-native observability, causality-aware alert routing, audit-grade evidence, and (post-ADR-111 Phase B sidecar) automatic drain/kill enforcement. The legacy `/live` + `/ready` split-probe pattern is retired in a single migration.
31
+
32
+ See `docs/how-to/health-checks.md`, `docs/explanation/health-check-ownership.md`, and the runbook `docs/runbooks/health-alert-routing-adr143.md` for the operator surface.
33
+
34
+ ### Patch Changes
35
+
36
+ - Updated dependencies [[`b5c6c14`](https://github.com/SylphxAI/platform/commit/b5c6c142ba89078edf460807282337dc315b77df)]:
37
+ - @sylphx/sdk@0.13.0
38
+
39
+ ## 0.11.0
40
+
41
+ ### Minor Changes
42
+
43
+ - [#1105](https://github.com/SylphxAI/platform/pull/1105) [`ab0491b`](https://github.com/SylphxAI/platform/commit/ab0491b892ecb9e96eb2843d2b6519f8eb52e3c9) Thanks [@shtse8](https://github.com/shtse8)! - ADR-137 §2.3 / §2.4 — per-PR cost browser, step 2 (API + SDK + CLI).
44
+
45
+ - **API**: `GET /projects/:id/previews/:prNumber/cost` returns a per-PR cost envelope (build / preview env / BaaS breakdown + 30-day project monthly-average comparison). `GET /projects/:id/previews/cost` lists the most recent 50 PRs (cursor paginated by `(prNumber, windowOpenedAt)`). Both require `project:read`.
46
+ - **SDK** (`@sylphx/management`): new `previews.cost(client, projectId, prNumber, opts?)` and `previews.listCosts(client, projectId, opts?)` capability namespace.
47
+ - **CLI** (`@sylphx/cli`): new `sylphx previews cost <pr-number>` and `sylphx previews list-costs [--project <slug>]` subcommands. Headline cost is coloured by comparison ratio (green < 1×, yellow 1–2×, red ≥ 2×) per ADR-137 §2.5.
48
+
49
+ No DB migration. Cost math reuses the aggregator landed in ADR-137 Step 1 (#1092).
50
+
51
+ - [#1090](https://github.com/SylphxAI/platform/pull/1090) [`7493f41`](https://github.com/SylphxAI/platform/commit/7493f41af30f565428f0335c6c6c3a491065c89d) Thanks [@shtse8](https://github.com/shtse8)! - Fail loudly on SSE log-stream transport failures instead of silently switching `sylphx deploy` to deployment polling. Deployment state remains available through explicit `sylphx deployments get` and `sylphx deployments wait` commands.
52
+
53
+ ### Patch Changes
54
+
55
+ - [#1097](https://github.com/SylphxAI/platform/pull/1097) [`7065be6`](https://github.com/SylphxAI/platform/commit/7065be6ccf978f76e8e2e518bf57f7e144e3954e) Thanks [@shtse8](https://github.com/shtse8)! - Validate configured CLI credentials in `sylphx doctor` with a read-only Management API principal check so revoked or expired agent tokens fail loudly instead of appearing logged in.
56
+
57
+ - Updated dependencies []:
58
+ - @sylphx/sdk@0.12.3
59
+
60
+ ## 0.10.0
61
+
62
+ ### Minor Changes
63
+
64
+ - [#1063](https://github.com/SylphxAI/platform/pull/1063) [`f7bce5d`](https://github.com/SylphxAI/platform/commit/f7bce5d4869cc3904fc21edb1c0e6cfcbcab0d9a) Thanks [@shtse8](https://github.com/shtse8)! - Add an agent-safe `SYLPHX_TOKEN_FILE` auth source for the CLI, preserve OAuth refresh-token expiry through the token endpoint contract, and surface refresh-expiry diagnostics in `sylphx doctor`.
65
+
66
+ Agents and CI can now mount a raw token or `SYLPHX_TOKEN=...` secret file instead of sharing a human `sylphx login` OAuth refresh chain. The CLI resolves auth as `SYLPHX_TOKEN` → `SYLPHX_TOKEN_FILE` → stored OAuth, skips OAuth refresh for machine credentials, and fails closed when a configured token file is invalid.
67
+
68
+ ### Patch Changes
69
+
70
+ - [#1078](https://github.com/SylphxAI/platform/pull/1078) [`b1d0edf`](https://github.com/SylphxAI/platform/commit/b1d0edfbd8386ea2421d8f0ae769d21e86c0db3a) Thanks [@shtse8](https://github.com/shtse8)! - Increase deploy fallback wait budget for production rollouts and rely on corrected Management API deployment status projection after log-stream disconnects.
71
+
72
+ - Updated dependencies [[`f7bce5d`](https://github.com/SylphxAI/platform/commit/f7bce5d4869cc3904fc21edb1c0e6cfcbcab0d9a)]:
73
+ - @sylphx/sdk@0.12.2
74
+
3
75
  ## 0.9.2
4
76
 
5
77
  ### Patch Changes
package/README.md CHANGED
@@ -42,11 +42,11 @@ The CLI supports three auth paths (ADR-059 + ADR-074):
42
42
  |---|---|---|
43
43
  | **OAuth device flow** (default) | Interactive dev | `sylphx login` — browser-backed device flow, 15-min access + 30-day refresh token stored at `~/.sylphx/config.json` (`0600`), auto-refresh built in |
44
44
  | **`SYLPHX_TOKEN` env var** | CI / CD / agents | `export SYLPHX_TOKEN=svc_...` — no login step, no disk write, stateless. Service tokens (`svc_*`, ADR-089 §2.10) or short-lived OAuth access JWTs (`eyJ…`) both work |
45
- | **`SYLPHX_TOKEN_FILE` env var** | Local agent fleets | `export SYLPHX_TOKEN_FILE=~/.config/sylphx/agent.token` — reads a raw token or dotenv-style `SYLPHX_TOKEN=...` from a local file, with the same stateless refresh behavior as `SYLPHX_TOKEN` |
45
+ | **`SYLPHX_TOKEN_FILE` secret file** | Local agent fleets / mounted secrets | `export SYLPHX_TOKEN_FILE=~/.sylphx/agent-token.env` — reads a raw token or `SYLPHX_TOKEN=...` file, skips OAuth refresh, and never falls back to a human OAuth session when the file is invalid |
46
46
 
47
47
  Legacy `slx_*` personal access tokens were eliminated 2026-04-21 (ADR-059 §1.4) and are no longer accepted by the API.
48
48
 
49
- Under ADR-059, OAuth tokens are stored as an atomic `{ accessToken, refreshToken, expiresAt, refreshExpiresAt }` credential with mode `0600` on disk. The refresh interceptor (`utils/oauth-refresh.ts`) transparently rotates the access token when it's within the refresh window; a failed refresh prompts re-login.
49
+ Under ADR-059, OAuth tokens are stored as an atomic `{ accessToken, refreshToken, expiresAt, refreshExpiresAt }` record with mode `0600` on disk. The refresh interceptor (`utils/oauth-refresh.ts`) transparently rotates the access token when it's within the refresh window; a failed refresh prompts re-login.
50
50
 
51
51
  ```bash
52
52
  # Interactive (developers)
@@ -57,13 +57,13 @@ sylphx logout
57
57
  # Non-interactive (CI / agents)
58
58
  export SYLPHX_TOKEN=svc_…
59
59
  sylphx whoami # → "Auth: SYLPHX_TOKEN env var"
60
- sylphx deploy --env=production
61
60
 
62
- # Local agent fleet, shared shell, or secret-file handoff
63
- printf '%s\n' 'SYLPHX_TOKEN=svc_…' > ~/.config/sylphx/agent.token
64
- chmod 600 ~/.config/sylphx/agent.token
65
- export SYLPHX_TOKEN_FILE=~/.config/sylphx/agent.token
61
+ printf '%s\n' 'SYLPHX_TOKEN=svc_…' > ~/.sylphx/agent-token.env
62
+ chmod 600 ~/.sylphx/agent-token.env
63
+ export SYLPHX_TOKEN_FILE=~/.sylphx/agent-token.env
66
64
  sylphx whoami # → "Auth: SYLPHX_TOKEN_FILE (...)"
65
+
66
+ sylphx deploy --env=production
67
67
  sylphx status --project=proj_abc123 --org=my-org
68
68
  sylphx logs --project=proj_abc123 --org=my-org --tail=100
69
69
  sylphx env set DATABASE_URL=postgres://... --project=proj_abc123 --org=my-org --secret
@@ -79,22 +79,22 @@ sylphx releases list --project=proj_abc123 --org=my-org
79
79
 
80
80
  ### Non-interactive use (CI / agents)
81
81
 
82
- Set `SYLPHX_TOKEN` or `SYLPHX_TOKEN_FILE` and every CLI command honours
83
- it as a Bearer token — no `sylphx login`, no browser, no
82
+ Set `SYLPHX_TOKEN` or `SYLPHX_TOKEN_FILE` and every CLI command honours it
83
+ as a Bearer token — no `sylphx login`, no browser, no
84
84
  `~/.sylphx/config.json` write:
85
85
 
86
- - `SYLPHX_TOKEN` **wins** over `SYLPHX_TOKEN_FILE`, and both win over any
87
- stored OAuth session — useful when a developer's machine doubles as a
88
- CI runner.
89
- - The OAuth refresh interceptor is **skipped** when external auth is
90
- active. Service tokens have no refresh token (rotate via `sylphx
91
- tokens rotate` instead); JWTs supplied here are operator-rotated.
86
+ - The env var **wins** over any stored OAuth session — useful when a
87
+ developer's machine doubles as a CI runner.
88
+ - `SYLPHX_TOKEN_FILE` is next in precedence and supports a raw token,
89
+ `SYLPHX_TOKEN=svc_...`, or `export SYLPHX_TOKEN="svc_..."`.
90
+ - If `SYLPHX_TOKEN_FILE` is set but unreadable or empty, the CLI fails
91
+ closed instead of silently using a stored human OAuth session.
92
+ - The OAuth refresh interceptor is **skipped** when the env var is
93
+ active or a token file is configured. Service tokens have no refresh
94
+ token (rotate via `sylphx tokens rotate` instead); JWTs supplied here
95
+ are operator-rotated.
92
96
  - Empty string (`SYLPHX_TOKEN=`) is treated as unset and falls back to
93
97
  the stored session — defends against misconfigured CI shell exports.
94
- - If `SYLPHX_TOKEN_FILE` is set but unreadable or empty, auth fails
95
- loudly and does not fall back to a stored interactive session. This
96
- prevents local agents from accidentally operating as the human logged
97
- into the same machine.
98
98
  - The same `SYLPHX_TOKEN` GitHub Actions output minted by `sylphx ci
99
99
  github-actions` is the variable the CLI itself consumes. One contract,
100
100
  no shell glue.
@@ -107,6 +107,21 @@ GitHub Actions example:
107
107
  SYLPHX_TOKEN: ${{ secrets.SYLPHX_TOKEN }}
108
108
  ```
109
109
 
110
+ Local agent example:
111
+
112
+ ```bash
113
+ install -m 700 -d ~/.sylphx
114
+ printf '%s\n' 'SYLPHX_TOKEN=svc_...' > ~/.sylphx/agent-token.env
115
+ chmod 600 ~/.sylphx/agent-token.env
116
+ export SYLPHX_TOKEN_FILE=~/.sylphx/agent-token.env
117
+ sylphx doctor
118
+ ```
119
+
120
+ Agents should prefer a scope-limited `svc_*` service token or OIDC-issued
121
+ short-lived token. Do not copy `~/.sylphx/config.json` between agents:
122
+ the OAuth refresh token is single-use rotation state for one interactive
123
+ user session, and sharing it can revoke the chain.
124
+
110
125
  ## Configuration
111
126
 
112
127
  Stored at `~/.sylphx/config.json`:
@@ -137,7 +152,7 @@ Per-project deployment intent lives in `./sylphx.toml` (git-committable); the ho
137
152
  | Variable | Description |
138
153
  |---|---|
139
154
  | `SYLPHX_TOKEN` | Bearer token for non-interactive auth (CI / agents). Accepts `svc_*` service tokens or `eyJ…` OAuth access JWTs. Wins over any stored OAuth session; refresh interceptor is skipped (stateless). Empty string is treated as unset. |
140
- | `SYLPHX_TOKEN_FILE` | Path to a local file containing a raw token or `SYLPHX_TOKEN=...`. Used for local agent fleets and secret-file handoff. Used after `SYLPHX_TOKEN`, before stored OAuth; unreadable/empty files fail loudly instead of falling back. |
155
+ | `SYLPHX_TOKEN_FILE` | Path to a non-interactive auth secret file. Accepts a raw token, `SYLPHX_TOKEN=...`, or `export SYLPHX_TOKEN="..."`. Used after `SYLPHX_TOKEN` and before stored OAuth; fails closed when set but invalid. |
141
156
  | `SYLPHX_CONFIG_DIR` | Advanced automation override for the CLI config directory. Use in CI, tests, and hermetic agent sandboxes to avoid reading or writing the operator's real `~/.sylphx` credentials. |
142
157
  | `SYLPHX_API_URL` | Override API base URL (default: `https://sylphx.com`) |
143
158