@kelviq/cli 0.1.1

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 (99) hide show
  1. package/README.md +313 -0
  2. package/dist/cli-ui/auth-hint.d.ts +6 -0
  3. package/dist/cli-ui/auth-hint.js +34 -0
  4. package/dist/cli-ui/auth-hint.js.map +1 -0
  5. package/dist/cli-ui/hints.d.ts +5 -0
  6. package/dist/cli-ui/hints.js +19 -0
  7. package/dist/cli-ui/hints.js.map +1 -0
  8. package/dist/cli-ui/spinner.d.ts +7 -0
  9. package/dist/cli-ui/spinner.js +61 -0
  10. package/dist/cli-ui/spinner.js.map +1 -0
  11. package/dist/cli-ui/style.d.ts +47 -0
  12. package/dist/cli-ui/style.js +71 -0
  13. package/dist/cli-ui/style.js.map +1 -0
  14. package/dist/cli-ui/tty.d.ts +1 -0
  15. package/dist/cli-ui/tty.js +13 -0
  16. package/dist/cli-ui/tty.js.map +1 -0
  17. package/dist/cli.d.ts +2 -0
  18. package/dist/cli.js +51 -0
  19. package/dist/cli.js.map +1 -0
  20. package/dist/commands/env.d.ts +34 -0
  21. package/dist/commands/env.js +52 -0
  22. package/dist/commands/env.js.map +1 -0
  23. package/dist/commands/init.d.ts +15 -0
  24. package/dist/commands/init.js +70 -0
  25. package/dist/commands/init.js.map +1 -0
  26. package/dist/commands/login.d.ts +22 -0
  27. package/dist/commands/login.js +205 -0
  28. package/dist/commands/login.js.map +1 -0
  29. package/dist/commands/logout.d.ts +13 -0
  30. package/dist/commands/logout.js +39 -0
  31. package/dist/commands/logout.js.map +1 -0
  32. package/dist/commands/promote.d.ts +42 -0
  33. package/dist/commands/promote.js +243 -0
  34. package/dist/commands/promote.js.map +1 -0
  35. package/dist/commands/pull.d.ts +31 -0
  36. package/dist/commands/pull.js +108 -0
  37. package/dist/commands/pull.js.map +1 -0
  38. package/dist/commands/push-shared.d.ts +97 -0
  39. package/dist/commands/push-shared.js +283 -0
  40. package/dist/commands/push-shared.js.map +1 -0
  41. package/dist/commands/push.d.ts +42 -0
  42. package/dist/commands/push.js +268 -0
  43. package/dist/commands/push.js.map +1 -0
  44. package/dist/config-format/builders.d.ts +10 -0
  45. package/dist/config-format/builders.js +46 -0
  46. package/dist/config-format/builders.js.map +1 -0
  47. package/dist/config-format/index.d.ts +4 -0
  48. package/dist/config-format/index.js +9 -0
  49. package/dist/config-format/index.js.map +1 -0
  50. package/dist/config-format/load.d.ts +23 -0
  51. package/dist/config-format/load.js +82 -0
  52. package/dist/config-format/load.js.map +1 -0
  53. package/dist/config-format/schema.d.ts +423 -0
  54. package/dist/config-format/schema.js +105 -0
  55. package/dist/config-format/schema.js.map +1 -0
  56. package/dist/core/config.d.ts +48 -0
  57. package/dist/core/config.js +128 -0
  58. package/dist/core/config.js.map +1 -0
  59. package/dist/core/errors.d.ts +20 -0
  60. package/dist/core/errors.js +58 -0
  61. package/dist/core/errors.js.map +1 -0
  62. package/dist/core/http.d.ts +39 -0
  63. package/dist/core/http.js +104 -0
  64. package/dist/core/http.js.map +1 -0
  65. package/dist/core/version.d.ts +1 -0
  66. package/dist/core/version.js +14 -0
  67. package/dist/core/version.js.map +1 -0
  68. package/dist/generated/openapi.json +6635 -0
  69. package/dist/sync/apply.d.ts +38 -0
  70. package/dist/sync/apply.js +234 -0
  71. package/dist/sync/apply.js.map +1 -0
  72. package/dist/sync/diff.d.ts +186 -0
  73. package/dist/sync/diff.js +402 -0
  74. package/dist/sync/diff.js.map +1 -0
  75. package/dist/sync/fetch-catalog.d.ts +105 -0
  76. package/dist/sync/fetch-catalog.js +100 -0
  77. package/dist/sync/fetch-catalog.js.map +1 -0
  78. package/dist/sync/price-filter.d.ts +37 -0
  79. package/dist/sync/price-filter.js +195 -0
  80. package/dist/sync/price-filter.js.map +1 -0
  81. package/dist/sync/prune.d.ts +77 -0
  82. package/dist/sync/prune.js +112 -0
  83. package/dist/sync/prune.js.map +1 -0
  84. package/dist/sync/publish.d.ts +75 -0
  85. package/dist/sync/publish.js +126 -0
  86. package/dist/sync/publish.js.map +1 -0
  87. package/dist/sync/push-plan-json.d.ts +79 -0
  88. package/dist/sync/push-plan-json.js +70 -0
  89. package/dist/sync/push-plan-json.js.map +1 -0
  90. package/dist/sync/render-plan.d.ts +83 -0
  91. package/dist/sync/render-plan.js +358 -0
  92. package/dist/sync/render-plan.js.map +1 -0
  93. package/dist/sync/serialize.d.ts +18 -0
  94. package/dist/sync/serialize.js +108 -0
  95. package/dist/sync/serialize.js.map +1 -0
  96. package/dist/sync/to-config.d.ts +9 -0
  97. package/dist/sync/to-config.js +191 -0
  98. package/dist/sync/to-config.js.map +1 -0
  99. package/package.json +68 -0
package/README.md ADDED
@@ -0,0 +1,313 @@
1
+ # Kelviq CLI
2
+
3
+ Pricing-as-code for Kelviq — a CLI that lets you
4
+ define products, features, and plans as typed TypeScript instead of clicking
5
+ through a dashboard, and sync that definition against a real Kelviq
6
+ environment.
7
+
8
+ Author or pull a typed `kelviq.config.ts`, inspect what environment you're
9
+ pointed at, then preview and apply changes with `kelviq push` — a dry-run
10
+ diff, confirmation, ordered writes, and optional `--publish`/`--prune` —
11
+ against a live environment. `kelviq promote` runs that same reconciliation
12
+ sandbox → production in one command.
13
+
14
+ ## Install
15
+
16
+ ```bash
17
+ npm install -g @kelviq/cli
18
+ kelviq --help
19
+ ```
20
+
21
+ ## Commands
22
+
23
+ Everything else (catalog browse commands, browser-handoff login) is not
24
+ built yet — see "What's not here yet" below.
25
+
26
+ | Command | What it does |
27
+ |---|---|
28
+ | `kelviq init` | Writes a starter `kelviq.config.ts` to the current directory. |
29
+ | `kelviq login` | Pastes a Kelviq Server API key from the dashboard and stores it locally. |
30
+ | `kelviq logout` | Removes a stored API key. |
31
+ | `kelviq env` | Shows which environment and keys are configured — no live validation. `--json` for scripting. |
32
+ | `kelviq pull` | Fetches the remote catalog and writes it to `kelviq.config.ts`. |
33
+ | `kelviq push` | Diffs `kelviq.config.ts` against an environment, confirms, and applies drafts-only writes. `--dry-run --json` for scripting. |
34
+ | `kelviq promote` | Diffs the sandbox catalog against production and applies the same way — no local config file involved. |
35
+
36
+ ```bash
37
+ kelviq init # write kelviq.config.ts in the current directory
38
+ kelviq login # paste a sandbox key (default env)
39
+ kelviq login --prod # paste a production key
40
+ kelviq logout --all # remove both stored keys
41
+ kelviq env # show configured environment + key status
42
+ kelviq pull # pull the sandbox catalog into kelviq.config.ts
43
+ kelviq pull --prod --force # pull production, overwriting an existing file
44
+ kelviq push --dry-run # preview what push would change, no writes
45
+ kelviq push --yes # push to sandbox non-interactively
46
+ kelviq promote --dry-run # preview sandbox -> production
47
+ ```
48
+
49
+ Run `kelviq push --help` / `kelviq promote --help` for the full flag set:
50
+ `--publish`, `--migrate-features`, `--migrate-pricing`, `--prune`,
51
+ `--allow-prod-prune`, `--verbose`, `--json`.
52
+
53
+ `kelviq login` prints the dashboard's API-keys URL, deep-linked to the
54
+ environment mode matching the target (sandbox by default, production with
55
+ `--prod`), and tries to open it in your default browser, then prompts for
56
+ the key on stdin (an interactive terminal masks each character as `*` while
57
+ you type or paste, then reports how many characters it received). Kelviq has no
58
+ key-introspection endpoint, so neither `login` nor `env` can confirm a key
59
+ is actually valid or show which org it belongs to — `env` reports only what's
60
+ configured locally.
61
+
62
+ ## `kelviq.config.ts`
63
+
64
+ `kelviq init` writes this starter file:
65
+
66
+ ```ts
67
+ // kelviq.config.ts — pricing-as-code for Kelviq.
68
+ // Defines products, features, and plans as typed, versioned TypeScript.
69
+ // Sync this file with your Kelviq account using `kelviq pull` / `kelviq push`.
70
+ import { product, feature, plan } from '@kelviq/cli/config';
71
+
72
+ export const app = product({
73
+ identifier: 'my-app',
74
+ name: 'My App',
75
+ taxCode: 'saas',
76
+ });
77
+
78
+ export const seats = feature({
79
+ identifier: 'seats',
80
+ name: 'Seats',
81
+ type: 'CUSTOMIZABLE',
82
+ });
83
+
84
+ export const pro = plan({
85
+ identifier: 'pro',
86
+ name: 'Pro',
87
+ product: 'my-app',
88
+ entitlements: [{ feature: 'seats', value: 5 }],
89
+ prices: [
90
+ {
91
+ priceType: 'PAID',
92
+ currency: 'USD',
93
+ // Full charge shape: see Kelviq docs → api-reference/plans/update-plan-prices
94
+ },
95
+ ],
96
+ });
97
+ ```
98
+
99
+ Every cross-reference in the format (`plan.product`, `entitlement.feature`)
100
+ is a stable `identifier` slug, never a UUID — the API sometimes wants UUIDs
101
+ (plan creation takes a product UUID; entitlement attachment takes feature
102
+ UUIDs), but that resolution is sync's job, not something you write by hand.
103
+ The plan lifecycle (draft → publish) is deliberately absent from this
104
+ format: it describes desired state, not deployment state.
105
+
106
+ `kelviq pull` generates this same shape from a live environment's catalog
107
+ instead of you writing it by hand — the two are meant to be interchangeable
108
+ starting points.
109
+
110
+ ## Environments
111
+
112
+ Every Kelviq org has a sandbox environment; the CLI targets it by default.
113
+ Pass `--prod` on `login`/`pull`/`push` to target production instead
114
+ (`promote` always targets production — no flag needed). Keys are stored
115
+ per-environment
116
+ (`~/.config/kelviq/config.json`, mode `0600`, created via `kelviq login`) or
117
+ supplied via `KELVIQ_SANDBOX_SERVER_API_KEY` / `KELVIQ_SERVER_API_KEY`
118
+ (env vars win over the stored file). There is deliberately no environment
119
+ where an unqualified command touches production by accident.
120
+
121
+ Sandbox and production also talk to different API hosts:
122
+
123
+ | Environment | Default host | Override env var |
124
+ |---|---|---|
125
+ | Sandbox | `https://sandboxapi.kelviq.com/api/v1` | `KELVIQ_SANDBOX_BASE_URL` |
126
+ | Production | `https://api.kelviq.com/api/v1` | `KELVIQ_BASE_URL` |
127
+
128
+ The two overrides are independent — setting one doesn't affect the other.
129
+ `kelviq env` prints both resolved URLs.
130
+
131
+ ## Scripting: `--json` output
132
+
133
+ `kelviq env --json` and `kelviq push --dry-run --json` / `kelviq promote
134
+ --dry-run --json` each emit a single JSON document on stdout and nothing
135
+ else — safe to pipe into `jq` or parse in CI. **This is a public, versioned
136
+ contract**: the field names below are exact, and changing them is a breaking
137
+ change.
138
+
139
+ ### `kelviq env --json`
140
+
141
+ ```json
142
+ {
143
+ "environment": "sandbox",
144
+ "sandboxUrl": "https://sandboxapi.kelviq.com/api/v1",
145
+ "prodUrl": "https://api.kelviq.com/api/v1",
146
+ "sandboxKey": "set",
147
+ "prodKey": "missing"
148
+ }
149
+ ```
150
+
151
+ `sandboxKey`/`prodKey` are always the literal string `"set"` or `"missing"`
152
+ — never any part of the actual key value. `environment` is always the
153
+ literal `"sandbox"` — `env` has no `--prod` flag of its own; it always
154
+ reports both keys' status together.
155
+
156
+ ### `kelviq push --dry-run --json` / `kelviq promote --dry-run --json`
157
+
158
+ `--json` is valid **only** together with `--dry-run` — it never mixes with
159
+ the interactive confirmation prompts or an actual write. Passing it without
160
+ `--dry-run` exits 1 with a one-line explanation before any fetch happens.
161
+ Colors and the fetch spinner (see below) are forced off in `--json` mode
162
+ regardless of `FORCE_COLOR`/TTY, and stderr carries nothing but a fatal
163
+ error.
164
+
165
+ ```json
166
+ {
167
+ "environment": "sandbox",
168
+ "direction": "push",
169
+ "changes": true,
170
+ "summary": {
171
+ "creates": 1,
172
+ "updates": 0,
173
+ "priceReplaces": 0,
174
+ "entitlementChanges": 0,
175
+ "archives": 0,
176
+ "skipped": 0,
177
+ "remoteOnly": 0,
178
+ "warnings": 0
179
+ },
180
+ "operations": {
181
+ "products": { "create": [], "patch": [] },
182
+ "features": { "create": [] },
183
+ "plans": { "create": [], "patch": [] },
184
+ "entitlements": { "add": [], "update": [], "delete": [] },
185
+ "prices": { "bulkReplace": [] }
186
+ },
187
+ "prune": null,
188
+ "publish": null,
189
+ "featureDrift": [],
190
+ "errors": [],
191
+ "warnings": []
192
+ }
193
+ ```
194
+
195
+ - `environment`: `"sandbox"` or `"production"` — the write target. `promote`
196
+ always reports `"production"` (its only possible target); `direction` is
197
+ what distinguishes the two commands (`"push"` or `"promote"`).
198
+ - `changes`: whether a REAL run of this same invocation (i.e. without
199
+ `--dry-run`) would write or archive anything. The exit code is always `0`
200
+ on a successful render, whether or not `changes` is true — check this
201
+ field in a script, not the process exit code, e.g.
202
+ `test "$(kelviq push --dry-run --json | jq -r .changes)" = "false"`.
203
+ - `operations`: the exact op groups `push`/`promote` compute internally
204
+ (`products`/`features`/`plans`/`entitlements`/`prices`), serialized as-is
205
+ — a stable, documented contract, never reshaped for display. A same-run
206
+ pending reference (e.g. a plan
207
+ referencing a product this same run also creates, before it has a real
208
+ UUID) serializes as its placeholder object verbatim, e.g.
209
+ `{ "pendingProductIdentifier": "my-app" }` or
210
+ `{ "pendingFeatureIdentifier": "seats" }` — never resolved or dropped.
211
+ - `prune`: `null` unless run with `--prune`; otherwise the full computed
212
+ archive/skip plan: `{ "archive": { "plans": [...], "features": [...] },
213
+ "skipped": { "plans": [...], "features": [...] } }`. `summary.skipped` (the
214
+ count of remote-only resources that matched but carry no `managed-by:
215
+ kelviq-cli` marker) is always populated regardless of `--prune`; `prune`
216
+ itself and `summary.archives` are not.
217
+ - `publish`: `null` unless run with `--publish --dry-run`; otherwise
218
+ `{ "plans": [...identifiers], "updateFeatures": boolean, "updatePricing":
219
+ boolean }` — the plans that WOULD be published this run.
220
+ - `featureDrift` / `errors`: the same hard-abort data the text renderer
221
+ shows before refusing to proceed — empty arrays on a normal run.
222
+ - `warnings`: the **raw, unaggregated** list (every dropped-price-field
223
+ warning individually) — never collapsed the way the text renderer's
224
+ "Warnings (N):" section groups them per plan by default. `--verbose` is a
225
+ text-mode-only concept; JSON output always gives you the raw list.
226
+
227
+ On a load/fetch/feature-drift error, the command exits non-zero and emits a
228
+ smaller, separate document instead of the shape above:
229
+
230
+ ```json
231
+ { "error": "push failed: Missing KELVIQ_SANDBOX_SERVER_API_KEY. ...", "featureDrift": [] }
232
+ ```
233
+
234
+ `featureDrift` is populated only for an actual feature-drift abort (the same
235
+ condition that aborts a normal run before any write); every other error (a
236
+ missing key, a network failure, an unresolved config reference) reports
237
+ `featureDrift: []`.
238
+
239
+ ## Push and promote
240
+
241
+ `push` deploys a `kelviq.config.ts` to an environment; `promote` does the
242
+ same sandbox → production, reusing the exact same diff/apply/publish engine
243
+ with no local config file involved. Both default to a dry-run-first,
244
+ confirm-before-write posture: `--dry-run` previews with zero writes,
245
+ non-interactive sessions require `--yes`, and production pruning
246
+ (`--prune`) has its own dedicated gate (`--allow-prod-prune` or a typed
247
+ confirmation) that `--yes` alone never satisfies. New plans are created as
248
+ drafts and stay unpublished unless you pass `--publish`, price changes
249
+ replace a plan's full price list rather than patching individual entries,
250
+ and `--prune` only ever archives resources carrying the CLI's own
251
+ `managed-by: kelviq-cli` marker — nothing unmanaged is touched.
252
+
253
+ ## What's not here yet
254
+
255
+ - **Catalog browse commands** (list/show products, features, plans without a
256
+ full `pull`) — not built yet.
257
+ - **Browser-handoff login** (`whoami`, org display) — needs pairing-flow and
258
+ key-introspection endpoints that don't exist on the platform yet; `login`
259
+ is paste-key only for now.
260
+
261
+ ## Development
262
+
263
+ The full push/promote reconciliation design is documented in
264
+ [`DESIGN-push.md`](./DESIGN-push.md).
265
+
266
+ Run from a checkout instead of the published package:
267
+
268
+ ```bash
269
+ npm install
270
+ npm run build
271
+ node dist/cli.js --help
272
+ ```
273
+
274
+ Or link it onto your `PATH` for a real `kelviq` command during development:
275
+
276
+ ```bash
277
+ npm link
278
+ kelviq --help
279
+ ```
280
+
281
+ ```bash
282
+ npm run dev # run the CLI from source (tsx), e.g. `npm run dev -- pull`
283
+ npm test # run the test suite (vitest)
284
+ npm run lint # eslint
285
+ npm run typecheck # tsc --noEmit, no output
286
+ npm run snapshot # refresh src/generated/openapi.json from the live docs URL
287
+ npm run build # snapshot + tsc + chmod dist/cli.js
288
+ ```
289
+
290
+ `npm run snapshot` (and therefore `npm run build`, and therefore
291
+ `prepublishOnly`) fetches `https://docs.kelviq.com/api-reference/openapi.json`
292
+ by default and writes it to `src/generated/openapi.json` — no sibling
293
+ checkout required, so `build` works from any machine with network access.
294
+ The response is validated (parses as JSON, has `openapi`/`paths` keys, meets
295
+ a minimum size) before it overwrites the existing snapshot; a degenerate
296
+ response leaves the snapshot untouched and exits non-zero.
297
+
298
+ For offline or pre-deploy work, `npm run snapshot -- --from-local` (or
299
+ `KELVIQ_SPEC_SOURCE=local npm run snapshot`) falls back to copying
300
+ `../docs/api-reference/openapi.json` from a sibling checkout of the `docs`
301
+ repo, failing fast if that checkout is absent. Prefer the default (live)
302
+ source when possible — a local checkout can sit on a stale branch, so a
303
+ "no drift" result against it proves nothing about the deployed spec.
304
+
305
+ Publish via `npm run publish:stable` (or `npm run publish:beta` for a
306
+ `--tag beta` prerelease). `scripts/publish.sh` guards the release: it checks
307
+ you're on a clean `main` working tree and logged in to npm as `kelviq`, runs
308
+ lint and typecheck, prints a summary, and asks for interactive confirmation
309
+ before calling `npm publish`. It does not run tests or build itself —
310
+ `prepublishOnly` (`npm run snapshot && npm test && npm run build`) does that
311
+ automatically at publish time against a freshly fetched live OpenAPI spec. A
312
+ successful stable publish also creates an annotated `v<version>` git tag and
313
+ prints (without running) the follow-up commands to push it.
@@ -0,0 +1,6 @@
1
+ /** True for a 401 or 403 HTTP status. */
2
+ export declare function isAuthStatus(httpStatus: number | undefined): boolean;
3
+ /** True when a composed error message embeds `HTTP 401`/`HTTP 403` the way fetch-catalog.ts's error wrapping does. */
4
+ export declare function messageCarriesAuthStatus(message: string): boolean;
5
+ /** The one dim actionable line appended after a detected 401/403 (never spans multiple lines itself). */
6
+ export declare function authHintLine(): string;
@@ -0,0 +1,34 @@
1
+ // CLI plan 014 Step 5: the actionable 401/403 hint.
2
+ //
3
+ // `src/core/errors.ts`'s `fromHttpResponse` always sets a numeric
4
+ // `httpStatus`, but by the time an error reaches a command's top-level catch
5
+ // block, only a composed message STRING survives — `src/sync/fetch-catalog.ts`
6
+ // throws `Failed to fetch ${label}: ${result.error.message} (${result.error.status})`,
7
+ // and `result.error.status` falls back to the literal `HTTP ${httpStatus}`
8
+ // whenever the server response didn't carry its own `status` string (the
9
+ // common case for a DRF-default `{"detail": "..."}` 401/403 body). So a
10
+ // fetch-catalog failure's final text already carries `HTTP 401`/`HTTP 403`
11
+ // verbatim when applicable — `messageCarriesAuthStatus` below just looks for
12
+ // it, rather than re-plumbing a structured status code through a thrown
13
+ // `Error`'s `.message` (out of scope for this presentation-only plan).
14
+ //
15
+ // `src/sync/apply.ts` (and only apply.ts — see its own module comment) has
16
+ // the structured `KelviqAPIError` in hand at the moment a write fails, before
17
+ // it collapses to a plain string for `OperationRecord.error` — `isAuthStatus`
18
+ // is for that call site, checking the real numeric `httpStatus` directly.
19
+ import { style } from './style.js';
20
+ const HINT_TEXT = 'Hint: this key may belong to the other environment — check "kelviq env", ' +
21
+ 'and re-login via the mode-aware dashboard page (kelviq login [--prod]).';
22
+ /** True for a 401 or 403 HTTP status. */
23
+ export function isAuthStatus(httpStatus) {
24
+ return httpStatus === 401 || httpStatus === 403;
25
+ }
26
+ /** True when a composed error message embeds `HTTP 401`/`HTTP 403` the way fetch-catalog.ts's error wrapping does. */
27
+ export function messageCarriesAuthStatus(message) {
28
+ return /\bHTTP 40[13]\b/.test(message);
29
+ }
30
+ /** The one dim actionable line appended after a detected 401/403 (never spans multiple lines itself). */
31
+ export function authHintLine() {
32
+ return style.dim(HINT_TEXT);
33
+ }
34
+ //# sourceMappingURL=auth-hint.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"auth-hint.js","sourceRoot":"","sources":["../../src/cli-ui/auth-hint.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,kEAAkE;AAClE,6EAA6E;AAC7E,+EAA+E;AAC/E,uFAAuF;AACvF,2EAA2E;AAC3E,yEAAyE;AACzE,wEAAwE;AACxE,2EAA2E;AAC3E,6EAA6E;AAC7E,wEAAwE;AACxE,uEAAuE;AACvE,EAAE;AACF,2EAA2E;AAC3E,8EAA8E;AAC9E,8EAA8E;AAC9E,0EAA0E;AAC1E,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,MAAM,SAAS,GACb,2EAA2E;IAC3E,yEAAyE,CAAC;AAE5E,yCAAyC;AACzC,MAAM,UAAU,YAAY,CAAC,UAA8B;IACzD,OAAO,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,GAAG,CAAC;AAClD,CAAC;AAED,sHAAsH;AACtH,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,OAAO,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACzC,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,YAAY;IAC1B,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC9B,CAAC"}
@@ -0,0 +1,5 @@
1
+ export declare const INIT_HINT = "Next: kelviq login \u00B7 then kelviq push --dry-run";
2
+ export declare const LOGIN_HINT = "Next: kelviq pull";
3
+ export declare const PULL_HINT = "Preview changes anytime: kelviq push --dry-run";
4
+ /** Writes `text` dimmed, once, only when `stdout` is a real terminal. A silent no-op when piped/redirected — never part of a script's parsed output. */
5
+ export declare function printHint(stdout: NodeJS.WritableStream, text: string): void;
@@ -0,0 +1,19 @@
1
+ // CLI plan 015 Step 3: next-step hints — a dim one-liner printed to stdout
2
+ // after `init`/`login`/`pull` succeed, teaching the natural next command.
3
+ // TTY-gated the same way the spinner is (src/cli-ui/tty.ts's `isTTYStream`,
4
+ // read off the stream itself, never a separate IO field) so piped/CI output
5
+ // stays hint-free without any of init.ts/login.ts/pull.ts's IO interfaces
6
+ // needing a new field. No `push`/`promote` hint: DESIGN-push.md's own
7
+ // summary line already ends their story.
8
+ import { style } from './style.js';
9
+ import { isTTYStream } from './tty.js';
10
+ export const INIT_HINT = 'Next: kelviq login · then kelviq push --dry-run';
11
+ export const LOGIN_HINT = 'Next: kelviq pull';
12
+ export const PULL_HINT = 'Preview changes anytime: kelviq push --dry-run';
13
+ /** Writes `text` dimmed, once, only when `stdout` is a real terminal. A silent no-op when piped/redirected — never part of a script's parsed output. */
14
+ export function printHint(stdout, text) {
15
+ if (!isTTYStream(stdout))
16
+ return;
17
+ stdout.write(`${style.dim(text)}\n`);
18
+ }
19
+ //# sourceMappingURL=hints.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hints.js","sourceRoot":"","sources":["../../src/cli-ui/hints.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,sEAAsE;AACtE,yCAAyC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,CAAC,MAAM,SAAS,GAAG,mDAAmD,CAAC;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAC9C,MAAM,CAAC,MAAM,SAAS,GAAG,gDAAgD,CAAC;AAE1E,wJAAwJ;AACxJ,MAAM,UAAU,SAAS,CAAC,MAA6B,EAAE,IAAY;IACnE,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;QAAE,OAAO;IACjC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC"}
@@ -0,0 +1,7 @@
1
+ export interface Spinner {
2
+ start(text: string): void;
3
+ succeed(text?: string): void;
4
+ fail(text?: string): void;
5
+ stop(): void;
6
+ }
7
+ export declare function createSpinner(stream: NodeJS.WritableStream): Spinner;
@@ -0,0 +1,61 @@
1
+ // CLI plan 015 Step 2: hand-rolled stderr spinner for the catalog fetches in
2
+ // pull/push/promote. No `ora`, no new dependency — kept small by design.
3
+ //
4
+ // TTY-gated by `stream.isTTY` (src/cli-ui/tty.ts's `isTTYStream`) alone:
5
+ // `start` renders and re-renders a braille frame in place only on a real
6
+ // terminal; on any other stream (piped, redirected, a test's plain
7
+ // `Writable`) `start` writes nothing at all, and `succeed`/`fail` fall back
8
+ // to one plain completion line — no frame, no cursor movement, so piped/CI
9
+ // output stays clean without special-casing.
10
+ //
11
+ // `--json` mode has no representation here at all: this module doesn't know
12
+ // what JSON mode is. Callers (src/commands/push.ts/promote.ts) simply never
13
+ // construct a spinner when `options.json` is set — see their own comments —
14
+ // which is what "spinner forced off" in plan 015's JSON contract amounts to
15
+ // in practice.
16
+ import { isTTYStream } from './tty.js';
17
+ const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
18
+ const INTERVAL_MS = 80;
19
+ export function createSpinner(stream) {
20
+ const isTTY = isTTYStream(stream);
21
+ let timer;
22
+ let frame = 0;
23
+ let lineLength = 0;
24
+ function clearLine() {
25
+ if (lineLength > 0)
26
+ stream.write(`\r${' '.repeat(lineLength)}\r`);
27
+ lineLength = 0;
28
+ }
29
+ function render(text) {
30
+ const line = `${FRAMES[frame % FRAMES.length]} ${text}`;
31
+ frame += 1;
32
+ stream.write(`\r${line}`);
33
+ lineLength = line.length;
34
+ }
35
+ function stop() {
36
+ if (timer)
37
+ clearInterval(timer);
38
+ timer = undefined;
39
+ clearLine();
40
+ }
41
+ return {
42
+ start(text) {
43
+ if (!isTTY)
44
+ return;
45
+ render(text);
46
+ timer = setInterval(() => render(text), INTERVAL_MS);
47
+ },
48
+ succeed(text) {
49
+ stop();
50
+ if (text)
51
+ stream.write(`✓ ${text}\n`);
52
+ },
53
+ fail(text) {
54
+ stop();
55
+ if (text)
56
+ stream.write(`✗ ${text}\n`);
57
+ },
58
+ stop,
59
+ };
60
+ }
61
+ //# sourceMappingURL=spinner.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"spinner.js","sourceRoot":"","sources":["../../src/cli-ui/spinner.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,yEAAyE;AACzE,EAAE;AACF,yEAAyE;AACzE,yEAAyE;AACzE,mEAAmE;AACnE,4EAA4E;AAC5E,2EAA2E;AAC3E,6CAA6C;AAC7C,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,4EAA4E;AAC5E,4EAA4E;AAC5E,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAClE,MAAM,WAAW,GAAG,EAAE,CAAC;AASvB,MAAM,UAAU,aAAa,CAAC,MAA6B;IACzD,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,KAAiD,CAAC;IACtD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,SAAS,SAAS;QAChB,IAAI,UAAU,GAAG,CAAC;YAAE,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAClE,UAAU,GAAG,CAAC,CAAC;IACjB,CAAC;IAED,SAAS,MAAM,CAAC,IAAY;QAC1B,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACxD,KAAK,IAAI,CAAC,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QAC1B,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,SAAS,IAAI;QACX,IAAI,KAAK;YAAE,aAAa,CAAC,KAAK,CAAC,CAAC;QAChC,KAAK,GAAG,SAAS,CAAC;QAClB,SAAS,EAAE,CAAC;IACd,CAAC;IAED,OAAO;QACL,KAAK,CAAC,IAAY;YAChB,IAAI,CAAC,KAAK;gBAAE,OAAO;YACnB,MAAM,CAAC,IAAI,CAAC,CAAC;YACb,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,CAAC,IAAa;YACnB,IAAI,EAAE,CAAC;YACP,IAAI,IAAI;gBAAE,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;QACxC,CAAC;QACD,IAAI,CAAC,IAAa;YAChB,IAAI,EAAE,CAAC;YACP,IAAI,IAAI;gBAAE,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;QACxC,CAAC;QACD,IAAI;KACL,CAAC;AACJ,CAAC"}
@@ -0,0 +1,47 @@
1
+ import pc from 'picocolors';
2
+ type StyleInstance = ReturnType<typeof pc.createColors>;
3
+ export interface InitStyleOptions {
4
+ /** True iff `--no-color` was passed on the command line. */
5
+ noColorFlag: boolean;
6
+ /** The stream color-support is judged against — defaults to `process.stdout`. Injectable so tests never touch the real stream. */
7
+ stream?: {
8
+ isTTY?: boolean;
9
+ };
10
+ /** Defaults to `process.env`. Injectable for deterministic tests. */
11
+ env?: NodeJS.ProcessEnv;
12
+ }
13
+ /**
14
+ * Sets the module-level color singleton every other module's `style` import
15
+ * reads from, and returns it. Precedence (highest first): `FORCE_COLOR` wins
16
+ * outright; then `NO_COLOR`; then `--no-color`; otherwise color follows
17
+ * whether `stream` is a TTY.
18
+ */
19
+ export declare function initStyle(opts: InitStyleOptions): StyleInstance;
20
+ /** Test-only escape hatch: restores the module to its pre-`initStyle` (disabled) default without depending on import order. */
21
+ export declare function resetStyleForTests(): void;
22
+ /**
23
+ * Semantic helpers, not raw colors — surfaces call these names so the
24
+ * palette is changeable in one place (CLI plan 014 Step 1). Each function
25
+ * reads the module-level `current` singleton at CALL time (not at import
26
+ * time), so a later `initStyle` call is honored by every module that already
27
+ * imported `style` earlier in the same run.
28
+ */
29
+ export declare const style: {
30
+ /** `+ create ...` lines. */
31
+ create: (s: string) => string;
32
+ /** `~ update` / `~ replace` lines. */
33
+ update: (s: string) => string;
34
+ /** `Archive (--prune)` section lines. */
35
+ archive: (s: string) => string;
36
+ dim: (s: string) => string;
37
+ bold: (s: string) => string;
38
+ /** Trailing `ok` on an apply/publish/prune progress line. */
39
+ ok: (s: string) => string;
40
+ /** `FAILED: ...` on an apply/publish/prune progress line. */
41
+ fail: (s: string) => string;
42
+ /** Warning headings/lines. */
43
+ warn: (s: string) => string;
44
+ /** Error blocks (feature drift, `<cmd> failed:`). */
45
+ err: (s: string) => string;
46
+ };
47
+ export {};
@@ -0,0 +1,71 @@
1
+ // CLI plan 014 Step 1: the one place picocolors is imported (enforced by
2
+ // eslint.config.js's `no-restricted-imports` entry — every other module
3
+ // reaches color only through `style` below, never `picocolors` directly).
4
+ //
5
+ // The enable decision lives HERE, once:
6
+ // enabled = FORCE_COLOR ? true : (NO_COLOR ? false : (--no-color ? false : stream.isTTY))
7
+ // `FORCE_COLOR`/`NO_COLOR` follow the informal standards' "any non-empty
8
+ // value counts" rule (https://no-color.org, https://force-color.org) — an
9
+ // explicitly-set empty string does NOT count as "set".
10
+ //
11
+ // `initStyle` is called exactly once, by src/cli.ts, in a `preAction` hook —
12
+ // after commander has parsed `--no-color` but before any command's action
13
+ // runs. Every other module imports the `style` singleton below and calls its
14
+ // semantic helpers; nothing else calls `initStyle`.
15
+ //
16
+ // Default state — before `initStyle` is ever called — is DISABLED. This is
17
+ // deliberate: every existing test invokes `runPush`/`runPromote`/`runPull`/
18
+ // `runEnvReport` directly, never through src/cli.ts, so `initStyle` never
19
+ // runs under vitest and every exact-string assertion written before this
20
+ // plan keeps passing unedited. Tests that want to exercise real color
21
+ // formatting call `initStyle` themselves (see test/cli-ui-style.test.ts).
22
+ import pc from 'picocolors';
23
+ let current = pc.createColors(false);
24
+ function hasNonEmptyValue(value) {
25
+ return typeof value === 'string' && value.length > 0;
26
+ }
27
+ /**
28
+ * Sets the module-level color singleton every other module's `style` import
29
+ * reads from, and returns it. Precedence (highest first): `FORCE_COLOR` wins
30
+ * outright; then `NO_COLOR`; then `--no-color`; otherwise color follows
31
+ * whether `stream` is a TTY.
32
+ */
33
+ export function initStyle(opts) {
34
+ const env = opts.env ?? process.env;
35
+ const forceColor = hasNonEmptyValue(env.FORCE_COLOR);
36
+ const noColorEnv = hasNonEmptyValue(env.NO_COLOR);
37
+ const isTTY = Boolean(opts.stream?.isTTY);
38
+ const enabled = forceColor ? true : noColorEnv ? false : opts.noColorFlag ? false : isTTY;
39
+ current = pc.createColors(enabled);
40
+ return current;
41
+ }
42
+ /** Test-only escape hatch: restores the module to its pre-`initStyle` (disabled) default without depending on import order. */
43
+ export function resetStyleForTests() {
44
+ current = pc.createColors(false);
45
+ }
46
+ /**
47
+ * Semantic helpers, not raw colors — surfaces call these names so the
48
+ * palette is changeable in one place (CLI plan 014 Step 1). Each function
49
+ * reads the module-level `current` singleton at CALL time (not at import
50
+ * time), so a later `initStyle` call is honored by every module that already
51
+ * imported `style` earlier in the same run.
52
+ */
53
+ export const style = {
54
+ /** `+ create ...` lines. */
55
+ create: (s) => current.green(s),
56
+ /** `~ update` / `~ replace` lines. */
57
+ update: (s) => current.yellow(s),
58
+ /** `Archive (--prune)` section lines. */
59
+ archive: (s) => current.red(s),
60
+ dim: (s) => current.dim(s),
61
+ bold: (s) => current.bold(s),
62
+ /** Trailing `ok` on an apply/publish/prune progress line. */
63
+ ok: (s) => current.green(s),
64
+ /** `FAILED: ...` on an apply/publish/prune progress line. */
65
+ fail: (s) => current.red(s),
66
+ /** Warning headings/lines. */
67
+ warn: (s) => current.yellow(s),
68
+ /** Error blocks (feature drift, `<cmd> failed:`). */
69
+ err: (s) => current.red(s),
70
+ };
71
+ //# sourceMappingURL=style.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"style.js","sourceRoot":"","sources":["../../src/cli-ui/style.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,wEAAwE;AACxE,0EAA0E;AAC1E,EAAE;AACF,wCAAwC;AACxC,4FAA4F;AAC5F,yEAAyE;AACzE,0EAA0E;AAC1E,uDAAuD;AACvD,EAAE;AACF,6EAA6E;AAC7E,0EAA0E;AAC1E,6EAA6E;AAC7E,oDAAoD;AACpD,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,0EAA0E;AAC1E,yEAAyE;AACzE,sEAAsE;AACtE,0EAA0E;AAC1E,OAAO,EAAE,MAAM,YAAY,CAAC;AAI5B,IAAI,OAAO,GAAkB,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;AAWpD,SAAS,gBAAgB,CAAC,KAAyB;IACjD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAAsB;IAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,UAAU,GAAG,gBAAgB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE1C,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;IAE1F,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,+HAA+H;AAC/H,MAAM,UAAU,kBAAkB;IAChC,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,4BAA4B;IAC5B,MAAM,EAAE,CAAC,CAAS,EAAU,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/C,sCAAsC;IACtC,MAAM,EAAE,CAAC,CAAS,EAAU,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,yCAAyC;IACzC,OAAO,EAAE,CAAC,CAAS,EAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C,GAAG,EAAE,CAAC,CAAS,EAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAS,EAAU,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5C,6DAA6D;IAC7D,EAAE,EAAE,CAAC,CAAS,EAAU,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3C,6DAA6D;IAC7D,IAAI,EAAE,CAAC,CAAS,EAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,8BAA8B;IAC9B,IAAI,EAAE,CAAC,CAAS,EAAU,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9C,qDAAqD;IACrD,GAAG,EAAE,CAAC,CAAS,EAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;CAC3C,CAAC"}
@@ -0,0 +1 @@
1
+ export declare function isTTYStream(stream: NodeJS.WritableStream | NodeJS.ReadableStream): boolean;
@@ -0,0 +1,13 @@
1
+ // CLI plan 015: the one place every TTY-gated feature (the fetch spinner,
2
+ // next-step hints) reads terminal-ness from. A narrow duck-typed check
3
+ // (`.isTTY === true`, never just truthy) against the stream itself — never a
4
+ // separate boolean threaded through an IO interface — so gating a new
5
+ // surface never requires widening PushIO/PromoteIO/PullIO/LoginIO/InitIO.
6
+ // Real Node streams (`process.stdout`/`process.stderr`) carry `isTTY` only
7
+ // when connected to an actual terminal; a test's plain `Writable`/`PassThrough`
8
+ // never does, so this is `false` under vitest by construction, no stubbing
9
+ // required.
10
+ export function isTTYStream(stream) {
11
+ return stream.isTTY === true;
12
+ }
13
+ //# sourceMappingURL=tty.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tty.js","sourceRoot":"","sources":["../../src/cli-ui/tty.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,uEAAuE;AACvE,6EAA6E;AAC7E,sEAAsE;AACtE,0EAA0E;AAC1E,2EAA2E;AAC3E,gFAAgF;AAChF,2EAA2E;AAC3E,YAAY;AACZ,MAAM,UAAU,WAAW,CAAC,MAAqD;IAC/E,OAAQ,MAA8B,CAAC,KAAK,KAAK,IAAI,CAAC;AACxD,CAAC"}
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};