@sylphx/cli 0.19.3 → 0.20.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/README.md CHANGED
@@ -1,466 +1,62 @@
1
- # @sylphx/cli
1
+ # `@sylphx/cli`
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/@sylphx/cli.svg?style=flat)](https://www.npmjs.com/package/@sylphx/cli)
4
- [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
5
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript)](https://www.typescriptlang.org/)
3
+ **npm install channel for the Rust operator CLI** (`sylphx`).
6
4
 
7
- The official CLI for the [Sylphx Platform](https://sylphx.com). Deploy and operate your applications across deployment, logs, env vars, domains, managed databases, object storage, monitoring, webhooks, feature flags, and more directly from your terminal.
5
+ This package does **not** reimplement the CLI in TypeScript. It installs and
6
+ executes the same native binary published as **`sylphx-cli`** on crates.io
7
+ (ADR-3820 sole-wire dual-language product path).
8
8
 
9
- Full documentation: [sylphx.com/docs](https://sylphx.com/docs)
9
+ | Channel | Command | Product |
10
+ | --- | --- | --- |
11
+ | **npm** | `npm install -g @sylphx/cli` | Rust `sylphx` binary |
12
+ | **crates.io** | `cargo install sylphx-cli` | same Rust `sylphx` binary |
10
13
 
11
- ## Installation
14
+ ## Install
12
15
 
13
16
  ```bash
14
- bun add -g @sylphx/cli
15
- # or
16
17
  npm install -g @sylphx/cli
17
- # or
18
- pnpm add -g @sylphx/cli
18
+ # equivalent:
19
+ cargo install sylphx-cli
19
20
  ```
20
21
 
21
- Requires **Node.js ≥ 20** (or Bun ≥ 1.3). The CLI binary is `sylphx`; the published package is a single self-contained ESM bundle (`@sylphx/management` and `@sylphx/contract` are bundled via tsup `noExternal`, so there are no workspace peers to resolve on global install).
22
+ Requires a matching platform optional package (`@sylphx/cli-linux-x64`,
23
+ `@sylphx/cli-darwin-arm64`, …). If the optional native package is missing for
24
+ your OS/arch, install falls back messaging to `cargo install sylphx-cli`.
22
25
 
23
- ## Quick start
26
+ Override path (advanced):
24
27
 
25
28
  ```bash
26
- # Authenticate (opens the browser for OAuth device flow)
27
- sylphx login
28
-
29
- # Link the current project to a Sylphx app
30
- cd my-project
31
- sylphx link
32
-
33
- # Ship it
34
- sylphx deploy
35
- ```
36
-
37
- ## Authentication
38
-
39
- The CLI supports four auth paths (ADR-059 + ADR-074):
40
-
41
- | Mode | Use case | How |
42
- |---|---|---|
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
- | **`SYLPHX_TOKEN` env var** | CI / CD / agents | `export SYLPHX_TOKEN=svc_...` — no login step, no disk write, stateless service-token auth |
45
- | **Injected OAuth pair** | Managed local agent fleets | `SYLPHX_ACCESS_TOKEN=eyJ...` + `SYLPHX_REFRESH_TOKEN=...` — imports the pair into the normal refresh chain and uses the cross-process refresh lock |
46
- | **`SYLPHX_TOKEN_FILE` secret file** | Local agent fleets / mounted secrets | `export SYLPHX_TOKEN_FILE=~/.sylphx/agent-token.env` — reads a raw service token, `SYLPHX_TOKEN=...`, or an access+refresh OAuth pair; fails closed when the file is invalid |
47
-
48
- Legacy `slx_*` personal access tokens were eliminated 2026-04-21 (ADR-059 §1.4) and are no longer accepted by the API.
49
-
50
- 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. Reuse/expiry clears only the rejected refresh-token chain; refresh transport failures are reported as outages and never silently erase the stored login.
51
-
52
- ```bash
53
- # Interactive (developers)
54
- sylphx login
55
- sylphx whoami # → "Auth: stored OAuth session (~/.sylphx/config.json)"
56
- sylphx logout
57
-
58
- # Non-interactive (CI / agents)
59
- export SYLPHX_TOKEN=svc_…
60
- sylphx whoami # → "Auth: SYLPHX_TOKEN env var"
61
-
62
- export SYLPHX_ACCESS_TOKEN=eyJ…
63
- export SYLPHX_REFRESH_TOKEN=...
64
- sylphx whoami # → "Auth: SYLPHX_ACCESS_TOKEN/SYLPHX_REFRESH_TOKEN env vars"
65
-
66
- printf '%s\n' 'SYLPHX_TOKEN=svc_…' > ~/.sylphx/agent-token.env
67
- chmod 600 ~/.sylphx/agent-token.env
68
- export SYLPHX_TOKEN_FILE=~/.sylphx/agent-token.env
69
- sylphx whoami # → "Auth: SYLPHX_TOKEN_FILE (...)"
70
-
71
- sylphx deploy --env=production
72
- sylphx status --project=proj_abc123 --org=my-org
73
- sylphx logs --project=proj_abc123 --org=my-org --tail=100
74
- sylphx logs --project=proj_abc123 --org=my-org --type=build --tail=100
75
- sylphx env set DATABASE_URL=postgres://... --project=proj_abc123 --org=my-org --secret
76
- sylphx env set LOKI_URL=http://loki.monitoring.svc.cluster.local:3100 --project=proj_abc123 --org=my-org --env=production --service-id=esvc_abc123
77
- sylphx config set PUBLIC_URL=https://app.example.com --project=proj_abc123 --org=my-org
78
- sylphx secrets set --project=proj_abc123 --org=my-org --key STRIPE_SECRET --value sk_live_...
79
- sylphx storage list --project=proj_abc123 --org=my-org
80
- sylphx volumes list --project=proj_abc123 --org=my-org
81
- sylphx resources bind res_abc123 --project=proj_abc123 --org=my-org --env=production
82
- sylphx run-cmd --project=proj_abc123 --org=my-org --env=production -- bun test
83
- sylphx promote --project=proj_abc123 --org=my-org --from=staging --to=production --yes
84
- sylphx releases list --project=proj_abc123 --org=my-org
29
+ export SYLPHX_CLI_BINARY=/path/to/sylphx
85
30
  ```
86
31
 
87
- ### Non-interactive use (CI / agents)
88
-
89
- Set `SYLPHX_TOKEN` to a `svc_*` service token for stateless CI, or inject
90
- `SYLPHX_ACCESS_TOKEN` + `SYLPHX_REFRESH_TOKEN` when a managed credential
91
- broker owns an OAuth session. Every CLI command honours the active source:
92
-
93
- - `SYLPHX_ACCESS_TOKEN` + `SYLPHX_REFRESH_TOKEN` wins first. The CLI
94
- writes the pair into `~/.sylphx/config.json`, then uses the same
95
- proactive/reactive refresh path and cross-process refresh lock as
96
- `sylphx login`. `SYLPHX_TOKEN` may supply the access token only when
97
- `SYLPHX_REFRESH_TOKEN` is present and the token is not `svc_*`.
98
- - `SYLPHX_TOKEN=svc_...` is next and stays stateless: no login step, no
99
- browser, no config write.
100
- - `SYLPHX_TOKEN_FILE` is next in precedence and supports a raw token,
101
- `SYLPHX_TOKEN=svc_...`, `export SYLPHX_TOKEN="svc_..."`, or
102
- `SYLPHX_ACCESS_TOKEN=...` + `SYLPHX_REFRESH_TOKEN=...`.
103
- - If `SYLPHX_TOKEN_FILE` is set but unreadable or empty, the CLI fails
104
- closed instead of silently using a stored human OAuth session.
105
- - The OAuth refresh interceptor is skipped only for stateless service
106
- token sources. Access-token-only OAuth JWTs are short-lived and should
107
- be paired with `SYLPHX_REFRESH_TOKEN` or replaced by a service token.
108
- - Empty string (`SYLPHX_TOKEN=`) is treated as unset and falls back to
109
- the stored session — defends against misconfigured CI shell exports.
110
- - The same `SYLPHX_TOKEN` GitHub Actions output minted by `sylphx ci
111
- github-actions` is the variable the CLI itself consumes. One contract,
112
- no shell glue.
113
-
114
- GitHub Actions example:
115
-
116
- ```yaml
117
- - run: sylphx deploy --env=production
118
- env:
119
- SYLPHX_TOKEN: ${{ secrets.SYLPHX_TOKEN }}
120
- ```
32
+ ## Day-1 shipped commands
121
33
 
122
- Local agent example:
34
+ | Command | Notes |
35
+ | --- | --- |
36
+ | `sylphx health` | Control-plane health |
37
+ | `sylphx whoami` | Current principal |
38
+ | `sylphx orgs list` | Organizations |
39
+ | `sylphx projects list` | Projects |
40
+ | `sylphx projects get <id>` | Project detail |
41
+ | `sylphx environments list <project_id>` | Environments |
42
+ | `sylphx environments get <project_id> <env_id>` | Environment detail |
43
+ | `sylphx deployments list <project_id>` | Deployments |
44
+ | `sylphx api <METHOD> <path>` | Escape hatch |
45
+ | `sylphx version-info` | Contract identity |
123
46
 
124
47
  ```bash
125
- install -m 700 -d ~/.sylphx
126
- printf '%s\n' 'SYLPHX_TOKEN=svc_...' > ~/.sylphx/agent-token.env
127
- chmod 600 ~/.sylphx/agent-token.env
128
- export SYLPHX_TOKEN_FILE=~/.sylphx/agent-token.env
129
- sylphx doctor
130
- ```
131
-
132
- Agents should prefer a scope-limited `svc_*` service token for long-running
133
- automation. If a broker injects OAuth, inject both access and refresh tokens
134
- so the CLI can rotate the chain. Do not copy `~/.sylphx/config.json` between
135
- machines: the OAuth refresh token is single-use rotation state.
136
-
137
- ## Configuration
138
-
139
- Stored at `~/.sylphx/config.json`:
140
-
141
- ```json
142
- {
143
- "oauth": {
144
- "accessToken": "eyJ...",
145
- "refreshToken": "ref_...",
146
- "expiresAt": "2026-04-23T15:00:00.000Z",
147
- "refreshExpiresAt": "2026-05-23T15:00:00.000Z"
148
- },
149
- "defaultOrg": "org_xyz789"
150
- }
48
+ export SYLPHX_TOKEN=svc_...
49
+ export SYLPHX_API_URL=https://api.sylphx.com/v1 # optional
50
+ sylphx health --json
51
+ sylphx projects list --json
52
+ sylphx environments list prj_demo --json
151
53
  ```
152
54
 
153
- Repo project binding and deployment intent live in `./sylphx.toml` (git-committable):
154
-
155
- ```toml
156
- version = "1"
157
-
158
- [project]
159
- id = "proj_abc123"
160
- name = "My Project"
161
- slug = "my-project"
162
- org_id = "org_xyz789"
163
- org = "my-org"
164
- default_env = "production"
165
- default_env_id = "env_prod123"
166
- ```
167
-
168
- The home config is private operator state only. It does not store per-directory project links.
169
-
170
- ## Environment variables
171
-
172
- | Variable | Description |
173
- |---|---|
174
- | `SYLPHX_TOKEN` | Stateless bearer token for non-interactive auth (CI / agents). Use `svc_*` service tokens. Empty string is treated as unset. |
175
- | `SYLPHX_ACCESS_TOKEN` | OAuth access token for managed agents. Must be paired with `SYLPHX_REFRESH_TOKEN`; wins over stateless `SYLPHX_TOKEN` and participates in CLI refresh. |
176
- | `SYLPHX_REFRESH_TOKEN` | OAuth refresh token for managed agents. Used only with `SYLPHX_ACCESS_TOKEN` or a non-service-token `SYLPHX_TOKEN`. |
177
- | `SYLPHX_TOKEN_FILE` | Path to a non-interactive auth secret file. Accepts a raw service token, `SYLPHX_TOKEN=...`, `export SYLPHX_TOKEN="..."`, or `SYLPHX_ACCESS_TOKEN=...` + `SYLPHX_REFRESH_TOKEN=...`. Fails closed when set but invalid. |
178
- | `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. |
179
- | `SYLPHX_API_URL` | Override API base URL (default: `https://sylphx.com`) |
180
-
181
- ## Commands
182
-
183
- ### Authentication & identity
184
-
185
- | Command | Purpose |
186
- |---|---|
187
- | `sylphx login` | OAuth device flow — browser-based, stores access + refresh tokens |
188
- | `sylphx logout` | Clear stored credentials |
189
- | `sylphx whoami` | Show current user + org + linked project |
190
-
191
- ### Diagnostics & raw API
192
-
193
- | Command | Purpose |
194
- |---|---|
195
- | `sylphx doctor` | Diagnose CLI install + auth + linked-project state, including read-only live auth validation |
196
- | `sylphx api` | Generic authenticated Management API caller (`sylphx api GET /projects`) — like `gh api`; inherits OAuth refresh, idempotency keys, RFC 7807 errors |
197
-
198
- ### Project lifecycle
199
-
200
- | Command | Purpose |
201
- |---|---|
202
- | `sylphx init` | Scaffold a new project |
203
- | `sylphx link` | Link current directory to a Sylphx app |
204
- | `sylphx unlink` | Remove the project link |
205
- | `sylphx open` | Open the linked project, or an explicit project with `--project/--org` |
206
- | `sylphx projects` | List / manage projects |
207
- | `sylphx orgs` | Manage organizations (members, invites, roles); `sylphx org` is an alias |
208
- | `sylphx migrate` | ADR-driven codemods for the linked repo (health-checks wiring, fleet migration status) |
209
-
210
- ### Deployment
211
-
212
- | Command | Purpose |
213
- |---|---|
214
- | `sylphx deploy` | Deploy the linked project, or an explicit project with `--project/--org`; verifies final state from the deployment record if the build-log stream drops |
215
- | `sylphx deployments` | List / inspect deployments |
216
- | `sylphx releases` | Browse release history for a linked or explicit project |
217
- | `sylphx inspect` | Inspect a deployment's build + run metadata |
218
- | `sylphx bisect` | Git-bisect-style regression hunt across deployments for a linked or explicit project |
219
- | `sylphx promote` | Promote one environment into another for a linked or explicit project |
220
- | `sylphx rollback` | Roll back a linked or explicit project deployment |
221
- | `sylphx status` | Deployment + health status for a linked or explicit project |
222
- | `sylphx logs` | Inspect bounded runtime logs for a linked or explicit project; add `--follow` for SSE or `--type=build` for deploy logs |
223
- | `sylphx tail` | Follow runtime logs with structured formatting; accepts the same filters as `logs` |
224
- | `sylphx run-cmd` | Run a local command with remote env from a linked or explicit project |
225
- | `sylphx run` | Submit a direct batch run, or a distributed run with `--parallelism`; uses the app server connection URL (`--url` or `SYLPHX_SECRET_URL`) |
226
- | `sylphx runs` | List, inspect, fetch shard logs for, or cancel submitted direct/distributed runs |
227
-
228
- `sylphx run-cmd` resolves the target environment through the Management API and
229
- injects the same customer-authored runtime env vars that a deployed service
230
- receives. Remote values override same-named local process values so local
231
- agent/CI smoke tests use production, staging, or preview configuration exactly
232
- as stored in Platform. Secret values are passed only to the child process; CLI
233
- status output reports counts, never values.
234
-
235
- When `sylphx.toml` exists in the working directory, `sylphx deploy` validates
236
- and publishes that manifest before triggering the deployment. This is the path
237
- that makes config-as-code fields such as `[database.migrations]` visible to the
238
- management deploy pipeline. For explicit deploys, pass both project and org
239
- scope, for example `sylphx deploy --project=proj_abc123 --org=my-org`; the CLI
240
- uses the same resolved org scope for the manifest publish, deployment trigger,
241
- log stream, and final deployment-state verification.
242
-
243
- `--skip-manifest` is an operator recovery escape hatch only. It bypasses local
244
- manifest publication, so any local `sylphx.toml` changes that have not already
245
- been persisted, including migration command changes, are not part of that
246
- deployment.
247
-
248
- ### Direct and distributed runs
249
-
250
- `sylphx run` submits language-agnostic container batch work to the public BaaS
251
- Run plane. Pass exactly one image source:
252
-
253
- - `--image <oci-ref>` for an explicit image from a connected registry.
254
- - `--image-from-service <name>` to resolve the image from the named service's
255
- current successful deployment in the same project environment.
256
-
257
- For distributed work, set `--parallelism N`. The platform injects
258
- `SYLPHX_SHARD_INDEX` and `SYLPHX_SHARD_COUNT` into every shard. Use
259
- `--opportunistic` to run on low-priority spare fleet capacity
260
- (`gangScheduling=false`), and `--backoff-limit-per-index N` to give each shard a
261
- bounded retry budget after preemption.
262
-
263
- ```bash
264
- export SYLPHX_SECRET_URL='sylphx://sk_...@pale-tore-0lgrqz.api.sylphx.com'
265
-
266
- sylphx run \
267
- --image-from-service trainer \
268
- --command python --command -m --command trainer.shard \
269
- --parallelism 8 \
270
- --opportunistic \
271
- --backoff-limit-per-index 12 \
272
- --env TRAINER_UNIVERSE_SIZE=800 \
273
- --follow
274
-
275
- sylphx runs list
276
- sylphx runs get worker_abc123 --parallelism 8
277
- sylphx runs logs worker_abc123 --parallelism 8 --shard 3
278
- sylphx runs cancel worker_abc123 --yes
279
- ```
280
-
281
- ### Preview capacity and service build context
282
-
283
- Project preview capacity is a public project-level override. It controls how
284
- many PR preview environments may be active for that project before platform
285
- backpressure leaves new preview webhooks queued under `sylphx/preview`. Leave
286
- the value unset to follow the organization plan.
287
-
288
- ```bash
289
- sylphx projects preview-capacity get proj_abc123 --output json
290
- sylphx projects preview-capacity set proj_abc123 10
291
- sylphx projects preview-capacity clear proj_abc123
292
- ```
293
-
294
- Service build source layout remains service-scoped. Use
295
- `sylphx services update` when a service needs a Dockerfile path, build context,
296
- or command override without changing the project-level manifest contract.
297
-
298
- ```bash
299
- sylphx services update web \
300
- --project=proj_abc123 \
301
- --org=my-org \
302
- --dockerfile=apps/web/Dockerfile \
303
- --build-context=. \
304
- --build-command="bun run build"
305
- ```
306
-
307
- ### Managed primitives
308
-
309
- | Command | Purpose |
310
- |---|---|
311
- | `sylphx db` | Manage PostgreSQL databases (CNPG-backed) |
312
- | `sylphx preview` | Preview environment management (branch DB, keep-alive, …) |
313
- | `sylphx previews` | Per-PR preview cost browser (ADR-137) |
314
- | `sylphx storage` | Manage object storage buckets for a linked or explicit project (Ceph S3) |
315
- | `sylphx volumes` | Manage persistent volumes for a linked or explicit project (Rook-Ceph RWO/RWX) |
316
- | `sylphx workspaces` | Manage Platform workspace handles for a linked or explicit project |
317
- | `sylphx agent-resources` | Inspect the project Agent Resource Graph across Platform-owned resources |
318
- | `sylphx mobile-device-tests` | Create, list, poll, and cancel managed Android/iOS device-runtime test requests |
319
- | `sylphx device-sessions` | Drive an interactive Android device session — boot, install, tap/swipe/key/text, screenshot, launch, logcat, terminate |
320
- | `sylphx resources` | Bind / unbind shared resources for a linked or explicit project |
321
- | `sylphx services` | List + deploy service blueprints |
322
- | `sylphx config` | Per-environment app config for a linked or explicit project |
323
- | `sylphx env` | Environment variables and environments for a linked or explicit project |
324
- | `sylphx secrets` | Encrypted project secrets for a linked or explicit project |
325
- | `sylphx tasks` | Task definitions (job / cron / service) for a linked or explicit project |
326
- | `sylphx domains` | Custom domains + TLS for a linked or explicit project |
327
- | `sylphx sandbox` | Interactive sandbox environments for a linked or explicit project |
328
- | `sylphx runners` | Self-hosted runner admin |
329
-
330
- Mobile device tests run on the managed device-runtime plane, not inside the
331
- default sandbox workspace. Build APK/AAB/IPA artifacts in CI, store them behind
332
- artifact handles, then submit the handles and device matrix:
333
-
334
- ```bash
335
- sylphx mobile-device-tests create \
336
- --project=proj_abc123 \
337
- --framework=maestro \
338
- --app-kind=apk \
339
- --app-uri=resource://artifacts/app-debug.apk \
340
- --test-kind=zip \
341
- --test-uri=resource://artifacts/mobile-tests.zip \
342
- --device=android:emulator:35:Pixel-8
343
-
344
- sylphx mobile-device-tests list --project=proj_abc123 --status=waiting-for-capacity
345
- sylphx mobile-device-tests get mdt_abc123
346
- sylphx mobile-device-tests cancel mdt_abc123
347
- ```
348
-
349
- A **device session** is the interactive counterpart: a long-lived Android device
350
- you drive in real time — boot once, then install, screenshot, and send input
351
- until you tear it down. The agent perceives the device through `screenshot` and
352
- acts through `input`, exactly like computer-use. See
353
- [docs/how-to/drive-android-device-session.md](../../docs/how-to/drive-android-device-session.md)
354
- for the full loop with CLI and curl examples.
355
-
356
- ```bash
357
- # Boot a device and block until it is ready (prints the dvs_ id).
358
- sylphx device-sessions create --project=proj_abc123 --wait
359
-
360
- # Install, launch, see the screen, then act on it.
361
- sylphx device-sessions install dvs_abc123 https://example.com/app-debug.apk
362
- sylphx device-sessions launch dvs_abc123
363
- sylphx device-sessions screenshot dvs_abc123 -o screen.png --open
364
- sylphx device-sessions input dvs_abc123 tap 540 1200
365
- sylphx device-sessions input dvs_abc123 text "hello world"
366
-
367
- sylphx device-sessions list --project=proj_abc123
368
- sylphx device-sessions rm dvs_abc123 --yes
369
- ```
370
-
371
- ### Integration primitives
372
-
373
- | Command | Purpose |
374
- |---|---|
375
- | `sylphx backup` | Managed data backup + restore |
376
- | `sylphx webhooks` | Outbound webhook endpoint CRUD |
377
- | `sylphx flags` | Feature flag admin |
378
- | `sylphx realtime` | Realtime channel admin |
379
- | `sylphx saml` | SAML SSO configuration |
380
- | `sylphx ai` | AI model / completion admin |
381
- | `sylphx session-replay` | Session replay admin |
382
- | `sylphx search` | Search index admin |
383
- | `sylphx engagement` | Engagement campaign admin |
384
- | `sylphx consent` | GDPR / CCPA consent admin |
385
- | `sylphx privacy` | Privacy / data-subject-request admin |
386
- | `sylphx referrals` | Referral program admin |
387
- | `sylphx newsletter` | Newsletter admin |
388
-
389
- ### Billing & scale
390
-
391
- | Command | Purpose |
392
- |---|---|
393
- | `sylphx plan` | View / upgrade plan for a linked or explicit project |
394
- | `sylphx billing` | Invoices, payment methods |
395
- | `sylphx experiments` | A/B experiment admin |
396
- | `sylphx analytics` | Analytics admin queries |
397
-
398
- ### Observability & integrations
399
-
400
- | Command | Purpose |
401
- |---|---|
402
- | `sylphx monitoring` | Metric + alert admin |
403
- | `sylphx insights` | Customer-facing latency dashboards — rolling 7-day merge-to-live rollups (ADR-136) |
404
- | `sylphx health` | Audit + verification subcommands for service health, e.g. `health verify --file` for exported audit hash chains (ADR-144) |
405
- | `sylphx certs` | TLS certificate inspection |
406
- | `sylphx email` | Transactional email admin |
407
- | `sylphx notifications` | Push / in-app notification admin |
408
-
409
- ### Machine identity & policy
410
-
411
- | Command | Purpose |
412
- |---|---|
413
- | `sylphx tokens` | Service token issuance + revocation |
414
- | `sylphx oidc` | OIDC federation (GitHub Actions, GitLab CI, …) |
415
- | `sylphx ci` | CI integration helpers (generates workflow snippets) |
416
-
417
- ### Account & administration
418
-
419
- | Command | Purpose |
420
- |---|---|
421
- | `sylphx account` | Account-level operations (verified email change, …) |
422
- | `sylphx user` | Current-user self-service: profile, sessions, security posture, data export |
423
- | `sylphx users` | Platform-admin user directory (list / get / role / verify-email / delete / revoke-sessions) |
424
- | `sylphx admin` | Platform-admin operations (quotas, tenants, builds, reconcile, …) — requires platform-operator scopes |
425
- | `sylphx rate-limits` | Inspect + tune BaaS rate-limit strategy overrides (ADR-089) |
426
-
427
- ## Architecture
428
-
429
- - Built on `@effect/cli` (ADR-073 Strategy A) — every command is an Effect value, tests can swap the Layer and assert on the Exit channel without subprocessing.
430
- - `BunRuntime.runMain` is the single `runPromise`-like call site (ADR-058 Rule 21).
431
- - Management plane only (ADR-083) — runtime BaaS verbs (`kv.*`, `email.send`, `flags.evaluate`, …) live inside the deployed application via [`@sylphx/sdk`](https://www.npmjs.com/package/@sylphx/sdk).
432
- - Types derive from [`@sylphx/contract`](https://www.npmjs.com/package/@sylphx/contract) (Effect Schema SSOT, ADR-084). Hand-written wire types are a bug.
433
- - HTTP client is `@sylphx/management` bundled in via `tsup noExternal` — global install has zero workspace peers to resolve.
434
-
435
- ## Version compatibility
436
-
437
- | CLI | Management API | Contract |
438
- |---|---|---|
439
- | `@sylphx/cli@0.x` (beta) | `api.sylphx.com/v1` | `@sylphx/contract` (workspace / beta) |
440
-
441
- The Management API `/v1` surface is the stable HTTP target per ADR-077; the CLI and SDK packages themselves are still in pre-1.0 beta. The CLI auto-detects API version and degrades gracefully on newer fields.
442
-
443
- ## Development
444
-
445
- ```bash
446
- bun install
447
- bun run dev -- --help # Run CLI against workspace
448
- bun run build # Build production bundle via tsup
449
- bun test # Run test suite (bun test)
450
- ```
451
-
452
- Shared table-formatting helpers under `packages/cli/src/utils/` are internal
453
- presentation utilities. Moving identical helpers out of command modules must
454
- preserve command names, flags, JSON fields, and human-readable output strings;
455
- otherwise update this README, the public docs, and command tests in the same
456
- change.
457
-
458
- ## Related packages
459
-
460
- - [`@sylphx/management`](https://www.npmjs.com/package/@sylphx/management) — Promise SDK the CLI is built on (bundled).
461
- - [`@sylphx/contract`](https://www.npmjs.com/package/@sylphx/contract) — Effect Schema SSOT (bundled).
462
- - [`@sylphx/sdk`](https://www.npmjs.com/package/@sylphx/sdk) — runtime BaaS SDK for deployed apps.
55
+ ## Versioning
463
56
 
464
- ## License
57
+ - **npm package** `@sylphx/cli` version (this package) follows the npm channel.
58
+ - **Binary** `--version` reports the Rust crate `sylphx-cli` version (see
59
+ `package.json#sylphx.crateVersion`).
465
60
 
466
- MIT — see [LICENSE](./LICENSE).
61
+ Wire SSOT: Protobuf under `api/proto` (`sylphx.platform.v1`). App library:
62
+ `@sylphx/sdk` (TypeScript) / `sylphx-sdk` (Rust).
package/bin/run.js ADDED
@@ -0,0 +1,41 @@
1
+ #!/usr/bin/env node
2
+ 'use strict'
3
+
4
+ /**
5
+ * Thin npm bin shim for the Rust `sylphx` binary.
6
+ * Does not reimplement CLI logic — only resolves and execs the native binary.
7
+ */
8
+
9
+ const { spawn } = require('node:child_process')
10
+ const { getBinaryPath } = require('../lib/get-binary')
11
+
12
+ function main() {
13
+ let binary
14
+ try {
15
+ binary = getBinaryPath()
16
+ } catch (err) {
17
+ console.error(err && err.message ? err.message : String(err))
18
+ process.exit(1)
19
+ }
20
+
21
+ const args = process.argv.slice(2)
22
+ const child = spawn(binary, args, {
23
+ stdio: 'inherit',
24
+ windowsHide: true,
25
+ })
26
+
27
+ child.on('error', (err) => {
28
+ console.error(`Failed to execute ${binary}: ${err.message}`)
29
+ process.exit(1)
30
+ })
31
+
32
+ child.on('exit', (code, signal) => {
33
+ if (signal) {
34
+ process.kill(process.pid, signal)
35
+ return
36
+ }
37
+ process.exit(code == null ? 1 : code)
38
+ })
39
+ }
40
+
41
+ main()
package/install.js ADDED
@@ -0,0 +1,37 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * postinstall: soft-check that the platform optionalDependency landed.
5
+ * Never hard-fails install on optional-missing (npm already soft-fails optionals);
6
+ * prints a clear warning so operators see cargo fallback immediately.
7
+ */
8
+
9
+ const { platformPackageName, platformKey } = require('./lib/platform')
10
+ const { getBinaryPath } = require('./lib/get-binary')
11
+
12
+ function main() {
13
+ // Skip in CI pack / offline contexts that set this intentionally
14
+ if (process.env.SYLPHX_CLI_SKIP_POSTINSTALL === '1') {
15
+ return
16
+ }
17
+
18
+ try {
19
+ const bin = getBinaryPath()
20
+ if (process.env.SYLPHX_CLI_INSTALL_VERBOSE === '1') {
21
+ console.log(`@sylphx/cli: native binary ready at ${bin}`)
22
+ }
23
+ } catch {
24
+ const pkg = platformPackageName() || '(unsupported platform)'
25
+ console.warn(
26
+ [
27
+ '',
28
+ `[@sylphx/cli] Native binary for ${platformKey()} not found after install.`,
29
+ ` Expected optional package: ${pkg}`,
30
+ ' Fallbacks: cargo install sylphx-cli | export SYLPHX_CLI_BINARY=/path/to/sylphx',
31
+ '',
32
+ ].join('\n'),
33
+ )
34
+ }
35
+ }
36
+
37
+ main()
@@ -0,0 +1,98 @@
1
+ 'use strict'
2
+
3
+ const fs = require('node:fs')
4
+ const path = require('node:path')
5
+ const { platformPackageName, knownPlatforms, platformKey } = require('./platform')
6
+
7
+ /**
8
+ * Resolve the absolute path to the native `sylphx` binary.
9
+ * Fail closed with actionable install paths when missing.
10
+ *
11
+ * Resolution order:
12
+ * 1. SYLPHX_CLI_BINARY env override (absolute path)
13
+ * 2. optionalDependency platform package bin/sylphx(.exe)
14
+ * 3. sibling packages/cli-<platform>/bin (workspace / local pack layout)
15
+ */
16
+
17
+ function binaryFileName() {
18
+ return process.platform === 'win32' ? 'sylphx.exe' : 'sylphx'
19
+ }
20
+
21
+ function tryRequireResolve(pkgName) {
22
+ try {
23
+ // package.json is always resolvable even if exports hide other files
24
+ return require.resolve(`${pkgName}/package.json`)
25
+ } catch {
26
+ return null
27
+ }
28
+ }
29
+
30
+ function pathFromPackageRoot(pkgRoot) {
31
+ const candidate = path.join(pkgRoot, 'bin', binaryFileName())
32
+ if (fs.existsSync(candidate)) return candidate
33
+ return null
34
+ }
35
+
36
+ function getBinaryPath() {
37
+ if (process.env.SYLPHX_CLI_BINARY) {
38
+ const override = path.resolve(process.env.SYLPHX_CLI_BINARY)
39
+ if (!fs.existsSync(override)) {
40
+ throw missingBinaryError(
41
+ `SYLPHX_CLI_BINARY is set to ${override} but that file does not exist.`,
42
+ )
43
+ }
44
+ return override
45
+ }
46
+
47
+ const pkgName = platformPackageName()
48
+ if (!pkgName) {
49
+ throw missingBinaryError(
50
+ `Unsupported platform: ${platformKey()}. Supported: ${knownPlatforms().join(', ')}.`,
51
+ )
52
+ }
53
+
54
+ const pkgJson = tryRequireResolve(pkgName)
55
+ if (pkgJson) {
56
+ const fromOptional = pathFromPackageRoot(path.dirname(pkgJson))
57
+ if (fromOptional) return fromOptional
58
+ }
59
+
60
+ // Workspace / monorepo layout: packages/cli-linux-x64 next to packages/cli
61
+ const localSibling = pathFromPackageRoot(
62
+ path.resolve(__dirname, '..', '..', pkgName.replace('@sylphx/', '')),
63
+ )
64
+ if (localSibling) return localSibling
65
+
66
+ // Nested node_modules of this package (some installers place optionals here)
67
+ const nested = pathFromPackageRoot(
68
+ path.resolve(__dirname, '..', 'node_modules', ...pkgName.split('/')),
69
+ )
70
+ if (nested) return nested
71
+
72
+ throw missingBinaryError(
73
+ `Native binary package ${pkgName} is not installed or does not contain bin/${binaryFileName()}.`,
74
+ )
75
+ }
76
+
77
+ function missingBinaryError(detail) {
78
+ const msg = [
79
+ 'Sylphx CLI: native Rust binary not available via npm channel.',
80
+ detail,
81
+ '',
82
+ 'Fix options:',
83
+ ' 1) npm install -g @sylphx/cli@0.20.0 # reinstall (pulls platform optionalDependency)',
84
+ ' 2) cargo install sylphx-cli # crates.io SSOT (same binary product)',
85
+ ' 3) export SYLPHX_CLI_BINARY=/path/to/sylphx',
86
+ '',
87
+ 'This package is an install channel for the Rust `sylphx` binary, not a TypeScript reimplementation.',
88
+ ].join('\n')
89
+ const err = new Error(msg)
90
+ err.code = 'SYLPHX_CLI_BINARY_MISSING'
91
+ return err
92
+ }
93
+
94
+ module.exports = {
95
+ getBinaryPath,
96
+ binaryFileName,
97
+ missingBinaryError,
98
+ }