@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 +72 -0
- package/README.md +35 -20
- package/dist/main.js +7407 -6541
- package/dist/main.js.map +1 -1
- package/package.json +2 -2
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`
|
|
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 }`
|
|
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
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
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
|
|
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
|
|