@azx-pbc/helix-cli 0.2.0 → 0.4.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.
Files changed (3) hide show
  1. package/README.md +44 -13
  2. package/dist/helix.js +1734 -550
  3. package/package.json +4 -3
package/README.md CHANGED
@@ -21,19 +21,37 @@ is wherever you're standing.
21
21
  Each setting is resolved **flags → environment → `helix.json` → built-in default**
22
22
  (first match wins):
23
23
 
24
- | Setting | Flag | Env | `helix.json` key | Default |
25
- | ---------- | -------------- | ------------------ | ---------------- | -------------------------- |
26
- | App slug | `--slug` | — | `slug` | _(required)_ |
27
- | Portal URL | `--portal-url` | `HELIX_PORTAL_URL` | `portalUrl` | `http://localhost:3001` |
28
- | Build dir | `--dir` | — | `dir` | `dist` |
29
- | Auth token | `--token` | `HELIX_TOKEN` | — | _(`helix login` if unset)_ |
24
+ | Setting | Flag | Env | `helix.json` key | Default |
25
+ | ----------- | --------------- | ------------------ | ---------------- | -------------------------- |
26
+ | App slug | `--slug` | — | `slug` | _(required)_ |
27
+ | Portal URL | `--portal-url` | `HELIX_PORTAL_URL` | `portalUrl` | `http://localhost:3001` |
28
+ | Build dir | `--dir` | — | `dir` | `dist` |
29
+ | Auth token | `--token` | `HELIX_TOKEN` | — | _(`helix login` if unset)_ |
30
+ | Description | `--description` | — | `description` | — |
30
31
 
31
- A minimal `helix.json` is just:
32
+ A `helix.json` looks like:
32
33
 
33
34
  ```json
34
- { "slug": "my-app" }
35
+ {
36
+ "slug": "my-app",
37
+ "dir": "dist",
38
+ "portalUrl": "https://portal.example.com",
39
+ "description": "Tracks Q3 cloud spend by team."
40
+ }
35
41
  ```
36
42
 
43
+ **`portalUrl` is the one you cannot leave to the default.** `http://localhost:3001`
44
+ is right only for a portal running on your own machine; against a deployed one,
45
+ set `portalUrl` (or `HELIX_PORTAL_URL`, or `--portal-url`) or every command —
46
+ starting with `helix login` — fails to connect to a portal that was never there.
47
+ Your portal prints the exact file to copy under **How to develop → On your
48
+ machine**. The file is the form worth checking in: `login`, `create`, `deploy`
49
+ and `promote` all resolve it the same way, so it is set once.
50
+
51
+ The repo's `examples/*/helix.json` deliberately omit it — a checked-in portal URL
52
+ would be wrong for every deployment but one — so to deploy an example, add
53
+ `portalUrl` to its file or export `HELIX_PORTAL_URL` first.
54
+
37
55
  `--dir` is resolved **relative to the current working directory**, and so is
38
56
  `helix.json` — another reason to run `helix` from the app directory.
39
57
 
@@ -43,17 +61,25 @@ A minimal `helix.json` is just:
43
61
  helix login # browser sign-in (OIDC device flow)
44
62
  helix logout # forget the cached tokens
45
63
  helix whoami # who the portal thinks you are
46
- helix create [--display-name <name>] [--visibility <v>] # register the app
64
+ helix create [--display-name <name>] [--description <text>] [--visibility <v>] # register the app
47
65
  helix deploy [--dir <dir>] [--bundle <zip>] [--promote] # upload a version
48
66
  helix versions # list versions
49
67
  helix promote <number> # make a version live
50
68
  helix rollback [number] # revert the live pointer
69
+ helix skill [--path <file>] # write this deployment's agent skill to disk
51
70
  ```
52
71
 
53
72
  `deploy` uploads the bundle as a **preview**; `--promote` flips it live in the
54
- same step (architecture §5.1). `visibility` is `internal | group:<id> | password
73
+ same step (architecture §5.1). `visibility` is `internal | group:<id>[,<id>…] | password
55
74
  | public`.
56
75
 
76
+ `helix skill` fetches this deployment's rendered agent skill (`GET /api/v1/skill`,
77
+ ADR-0036) — the same document the portal's **How to develop** modal hands out, with
78
+ this deployment's hosts, servable models, and approval baselines already substituted
79
+ in. It needs no app slug or `helix.json`, only a portal URL and a token. Defaults to
80
+ `./SKILL.md`; `--path .claude/skills/helix/SKILL.md` drops it where a Claude Code
81
+ agent reads it off disk.
82
+
57
83
  > **Breaking in 0.2.0:** the `private` visibility mode was renamed to `internal`.
58
84
  > It never checked _which_ user signed in, only that someone had. Passing the old
59
85
  > value now **errors** rather than mapping to the new one, deliberately: the name
@@ -87,12 +113,17 @@ export HELIX_TOKEN="…"
87
113
  helix deploy --promote
88
114
  ```
89
115
 
90
- Needs **Node 24+** — the bundle is emitted at that target, so older runtimes
91
- may not merely warn, they may fail to parse it.
116
+ Needs **Node 22.12+** (or 24+). The engines range and the bundle's esbuild
117
+ target move together (see `scripts/build.mjs`), so the declared floor is real:
118
+ older runtimes may not merely warn, they may fail to parse it.
92
119
 
93
120
  `0.0.0` is a deprecated placeholder that exists only because npm requires a
94
121
  package to exist before a trusted publisher can be attached to it. Every real
95
- version is `0.1.0` or later and carries a provenance attestation.
122
+ version is `0.1.0` or later and carries a provenance attestation. npm filters
123
+ registry versions by `engines` against the running runtime, so before 0.3.0
124
+ declared 22.12+ an install on Node 22 fell all the way back to that
125
+ placeholder — the reason a supported-looking Node could yield a
126
+ non-functional package.
96
127
 
97
128
  ### From this monorepo today
98
129