@scalar/cli 2.12.3 → 2.13.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 (89) hide show
  1. package/README.md +221 -2
  2. package/chunks/{action-JXCU2JKC.js → action-27BJMHFD.js} +38 -6
  3. package/chunks/{action-5BJL72JE.js → action-2BZ3AFBR.js} +10 -7
  4. package/chunks/{action-RPTLQBMK.js → action-3DBOUHKS.js} +8 -6
  5. package/chunks/{action-6I2PWENU.js → action-3R3MVTP3.js} +67 -88
  6. package/chunks/{action-T4MM4OUS.js → action-5HWPNWVU.js} +52 -29
  7. package/chunks/{action-EWZLVN45.js → action-5JTBIUPZ.js} +47 -27
  8. package/chunks/{action-4ESHWOAM.js → action-5QDBZTBF.js} +9 -8
  9. package/chunks/{action-D7L757PX.js → action-7HHTD65O.js} +13 -12
  10. package/chunks/{action-Y7EBKCUU.js → action-ASBFLTOA.js} +1 -1
  11. package/chunks/{action-H4GW3KAI.js → action-CXQ3HLVC.js} +15 -15
  12. package/chunks/{action-EPGS3U3T.js → action-EGF7LXVA.js} +63 -48
  13. package/chunks/{action-7CUPRYNA.js → action-F5LSDVJA.js} +36 -23
  14. package/chunks/{action-6A4NM5WS.js → action-FR6UPGZP.js} +9 -8
  15. package/chunks/{action-KIOYSVKX.js → action-FZZ2VLNA.js} +23 -6
  16. package/chunks/{action-ZOYQBWGD.js → action-GIKW67JB.js} +13 -13
  17. package/chunks/{action-ED4TSPRZ.js → action-GLC54N3F.js} +11 -11
  18. package/chunks/{action-FBOTIFVC.js → action-GRAMP3QD.js} +12 -10
  19. package/chunks/{action-BYYKW4S6.js → action-IUG6MPST.js} +25 -10
  20. package/chunks/{action-ZBEOLJJR.js → action-JCBTINNL.js} +9 -6
  21. package/chunks/{action-VVKMUOKR.js → action-JEI24ZNE.js} +13 -5
  22. package/chunks/{action-EWDQOX5B.js → action-JFNK5UCV.js} +6 -4
  23. package/chunks/action-JRPGHJGA.js +48 -0
  24. package/chunks/{action-Q3DI54OW.js → action-KRXJWRCE.js} +15 -15
  25. package/chunks/{action-B74PPGKB.js → action-PBJFNJMY.js} +34 -16
  26. package/chunks/{action-O7ROX6NF.js → action-PDOW5JS2.js} +12 -11
  27. package/chunks/{action-GMJJMZXY.js → action-RYLO75IN.js} +11 -11
  28. package/chunks/{action-HAKFAXTQ.js → action-VEXFHEQR.js} +6 -6
  29. package/chunks/{action-YXRCGKCK.js → action-W3AGGZ42.js} +6 -4
  30. package/chunks/action-W5VD63XO.js +55 -0
  31. package/chunks/{action-M5OUEDV2.js → action-WEDLKGDY.js} +4 -4
  32. package/chunks/{action-FBQAU5LV.js → action-WI6UW2AL.js} +12 -12
  33. package/chunks/{action-AYKKHH7A.js → action-WQPMJZXL.js} +51 -24
  34. package/chunks/{action-GJHOZ6Q5.js → action-WY4GOD2Y.js} +10 -8
  35. package/chunks/{action-I2IV4VLL.js → action-XXIRB2F6.js} +32 -16
  36. package/chunks/{actions-EXQNVV4T.js → actions-I4HS6ASR.js} +20 -18
  37. package/chunks/{agent-XAHNA4MB.js → agent-E6PYTXAU.js} +3 -3
  38. package/chunks/{asyncapi-FNOWXSKB.js → asyncapi-VQ7CCUCY.js} +9 -7
  39. package/chunks/{build.action-TIKRZPQ5.js → build.action-LIAREWUF.js} +36 -19
  40. package/chunks/chunk-2XWUFFEZ.js +133 -0
  41. package/chunks/{chunk-2GKXAGSH.js → chunk-6VAEDMCP.js} +7 -7
  42. package/chunks/{chunk-EUFK4MVX.js → chunk-6YDIOXF7.js} +2 -2
  43. package/chunks/{chunk-EBNFCIKS.js → chunk-APX65SRT.js} +2 -1
  44. package/chunks/{chunk-WKW5W2ZP.js → chunk-DWN6JOF2.js} +1 -1
  45. package/chunks/{chunk-EXJUFF6G.js → chunk-FXELV3AW.js} +8 -3
  46. package/chunks/{chunk-IOW726L2.js → chunk-GARUDDWI.js} +1 -1
  47. package/chunks/{chunk-JWNWOK2M.js → chunk-HZ4UKLOE.js} +12 -5
  48. package/chunks/{chunk-2AK5O3NQ.js → chunk-IDWF5L45.js} +28 -28
  49. package/chunks/chunk-IRQJDPZE.js +34 -0
  50. package/chunks/{chunk-TYNF7ROW.js → chunk-JHJDLZSM.js} +1 -1
  51. package/chunks/{chunk-TI4NDKQC.js → chunk-KTI65ZVY.js} +5 -5
  52. package/chunks/chunk-LK2ZIDHH.js +32 -0
  53. package/chunks/{chunk-I7ZVWF57.js → chunk-LUR7BA3W.js} +15 -9
  54. package/chunks/{chunk-AOZQPCWI.js → chunk-M4QTWCJ7.js} +2 -0
  55. package/chunks/{chunk-7S34K2P3.js → chunk-NOD4CBF7.js} +1 -1
  56. package/chunks/{chunk-KPLWZIOV.js → chunk-P4EPNS46.js} +3 -3
  57. package/chunks/{chunk-CUHVXHIV.js → chunk-PWFA23M2.js} +1 -1
  58. package/chunks/{chunk-KWIY2QZY.js → chunk-QRYMQPFT.js} +2 -2
  59. package/chunks/{chunk-FI7UKPRF.js → chunk-QS2T7JAK.js} +1 -1
  60. package/chunks/{chunk-OZQPMMTA.js → chunk-QUUBUPAW.js} +5 -5
  61. package/chunks/{chunk-FYMDIB7J.js → chunk-R3NDJICA.js} +1 -1
  62. package/chunks/{chunk-V7RTDFHK.js → chunk-RAJM56L7.js} +5 -1
  63. package/chunks/{chunk-Y2OQOAY7.js → chunk-RQNLEGMQ.js} +1 -1
  64. package/chunks/chunk-RZDLPTXV.js +167 -0
  65. package/chunks/chunk-SIPBGEVT.js +16 -0
  66. package/chunks/chunk-SNQFFEYH.js +11 -0
  67. package/chunks/{chunk-62OOT7FY.js → chunk-SNSJW2JT.js} +2 -2
  68. package/chunks/{chunk-LEECPQZN.js → chunk-UNV7BZD3.js} +2 -2
  69. package/chunks/{chunk-IRA5BW2J.js → chunk-X62ZTOQF.js} +31 -4
  70. package/chunks/{chunk-UN2AAVO5.js → chunk-XFBCZL7J.js} +2 -2
  71. package/chunks/chunk-XUX6JXU5.js +58 -0
  72. package/chunks/{create.action-K7GTWYST.js → create.action-PZMCTYGS.js} +31 -22
  73. package/chunks/{delete.action-JKLXBYRD.js → delete.action-J57JIFG3.js} +35 -21
  74. package/chunks/{delete.action-E4XRGKQW.js → delete.action-VDSTPSWG.js} +37 -21
  75. package/chunks/{get.action-IY7WSJMX.js → get.action-KUP32QJT.js} +13 -13
  76. package/chunks/{get.action-2AKMD4W3.js → get.action-ZOSML6XG.js} +12 -10
  77. package/chunks/{list.action-NRL2DDL5.js → list.action-Q5MPDR42.js} +15 -15
  78. package/chunks/{list.action-44YVCWKN.js → list.action-VYENIC5L.js} +13 -13
  79. package/chunks/{publish.action-E76MHLCN.js → publish.action-MBAZHQ2J.js} +48 -28
  80. package/chunks/{update.action-LZCAHAWW.js → update.action-BWMCXWQ5.js} +35 -21
  81. package/chunks/{update.action-FTTVWVAB.js → update.action-IEXVMUKG.js} +46 -26
  82. package/index.js +212 -127
  83. package/package.json +1 -1
  84. package/skills/scalar-cli/SKILL.md +4 -2
  85. package/template.md +220 -1
  86. package/chunks/action-BDDXF4YV.js +0 -38
  87. package/chunks/chunk-BOPEAS7H.js +0 -38
  88. package/chunks/chunk-EGOXR5FB.js +0 -15
  89. package/chunks/{action-UHXBY3RD.js → action-3P66ZSL3.js} +1 -1
package/README.md CHANGED
@@ -38,7 +38,19 @@ scalar document bundle openapi.yaml --output - > openapi.bundled.yaml
38
38
 
39
39
  Pulls every external `$ref` into a single file. `--treeShake` drops components nothing uses. The input can be a URL.
40
40
 
41
- Use `--output -` (or `-o -`) to write YAML to stdout for piping. Timings, diagnostics, and upgrade notices go to stderr. Without `--output`, local input requires an interactive overwrite confirmation; URL and non-interactive input require an explicit output destination.
41
+ Use `--output -` (or `-o -`) to write to stdout for piping, preserving the root document’s JSON or YAML format. The format is detected from the document contents, including for URLs. Timings, diagnostics, and upgrade notices go to stderr. Without `--output`, local input requires an interactive overwrite confirmation; URL and non-interactive input require an explicit output destination.
42
+
43
+ ### Format files or piped input
44
+
45
+ ```bash
46
+ scalar document format openapi.yaml
47
+ scalar document format openapi.json --output -
48
+ cat openapi.yaml | scalar document format - --output openapi.json
49
+ cat openapi.json | scalar document format -
50
+ cat openapi.json | scalar document format - --output -
51
+ ```
52
+
53
+ Use `-` to read JSON or YAML from stdin and `--output -` to write only document content to stdout in the input’s JSON or YAML format, with diagnostics and timings on stderr. Without `--output`, stdin is formatted to stdout in its original JSON or YAML format. JSON input produces two-space JSON; YAML input produces YAML. URL inputs require an explicit output destination. Named output files use YAML for `.yaml` or `.yml` extensions (case-insensitive), and two-space JSON otherwise. Without `--output`, a local input file is overwritten in place. Use `./-` to refer to a file literally named `-`.
42
54
 
43
55
  ### Preview the API reference
44
56
 
@@ -115,6 +127,22 @@ mkdir -p .claude/skills
115
127
  cp -r "$(npm root -g)/@scalar/cli/skills/scalar-cli" .claude/skills/
116
128
  ```
117
129
 
130
+ ## Noninteractive execution
131
+
132
+ Pass `--no-input` in scripts and agent commands, including when a pseudo-terminal (PTY) is attached:
133
+
134
+ ```sh
135
+ scalar --no-input project create --name "My docs"
136
+ scalar project rollback --slug my-docs --yes --no-input
137
+ scalar document bundle openapi.yaml --output - --no-input
138
+ ```
139
+
140
+ The flag works before or after subcommands. It disables prompts and browser launches. Supply required arguments or options; missing input exits with code 1 and explains what to provide. Optional values retain their defaults, including the generated project slug. Piped data is never read as confirmation.
141
+
142
+ `--no-input` does not imply `--yes` (confirm an action) or `--force` (override a specific protection). Neither flag chooses an unspecified target. Prompt cancellation, Ctrl-C during a prompt, and EOF exit with code 1 and “Operation cancelled.”
143
+
144
+ For `auth login`, supply a personal token using the existing `SCALAR_API_KEY` source or `--token`; without one, noninteractive login fails before starting a browser or callback server. `project preview` still runs the requested preview server but never opens its browser under `--no-input`, even with an opening option. `readme` prints the documentation URL without launching a browser.
145
+
118
146
  ## Use in CI
119
147
 
120
148
  ```yml
@@ -142,7 +170,7 @@ jobs:
142
170
  | [`scalar auth`](https://scalar.com/tools/cli/commands/auth) | Log in to Scalar and manage your session | `login`, `whoami`, `logout` |
143
171
  | [`scalar access-group`](https://scalar.com/tools/cli/commands/access-group) | Manage access groups and allowed email domains for the current team | `list`, `create`, `get`, `update`, `delete`, `domain add`, `domain remove` |
144
172
  | [`scalar document`](https://scalar.com/tools/cli/commands/document) | Work with OpenAPI and AsyncAPI descriptions | `bundle`, `split`, `join`, `format`, `convert`, `markdown`, `mock`, `serve`, `share`, `validate`, `void`, `lint`, `upgrade` |
145
- | [`scalar project`](https://scalar.com/tools/cli/commands/project) | Manage Scalar Docs projects | `list`, `get`, `init`, `check-config`, `create`, `preview`, `publish`, `rollback`, `deployments list`, `upgrade` |
173
+ | [`scalar project`](https://scalar.com/tools/cli/commands/project) | Manage Scalar Docs projects | `list`, `get`, `init`, `check-config`, `create`, `preview`, `publish`, `rollback`, `deployments list`, `deployments get`, `upgrade` |
146
174
  | [`scalar registry`](https://scalar.com/tools/cli/commands/registry) | Manage API descriptions in the Scalar Registry | `publish`, `update`, `delete`, `list`, `get` |
147
175
  | [`scalar team`](https://scalar.com/tools/cli/commands/team) | List and switch between your Scalar teams | `list`, `get`, `set` |
148
176
  | [`scalar sdk`](https://scalar.com/tools/cli/commands/sdk) | Manage Scalar SDKs (Enterprise only) | `list`, `get`, `create`, `update`, `delete`, `build` |
@@ -163,3 +191,194 @@ authentication method (browser session or personal token). Use
163
191
  `personal_token`). If the team name cannot be loaded, the team ID remains
164
192
  available and JSON returns `null` for the name. Missing email or role values
165
193
  also return `null`. Credentials are never included.
194
+
195
+ ### Recover a project publish
196
+
197
+ `scalar project publish --slug my-docs` prints the accepted Build ID before waiting up to 600 seconds for deployment. Use `--timeout <seconds>` to change the wait (positive seconds, at most 2147483), or `--no-wait` to return immediately after acceptance. Do not combine `--no-wait` with `--timeout`.
198
+
199
+ Inspect the same production or preview build with the original team selected, without publishing again:
200
+
201
+ ```sh
202
+ scalar project deployments get BUILD_ID
203
+ scalar project deployments get BUILD_ID --wait --timeout 600
204
+ ```
205
+
206
+ A one-shot inspection waits at most 30 seconds for its request unless overridden. It exits zero when the record was read, even if that record reports a failed build. With `--wait`, zero means deployed; a failed build, unavailable status, or expired deadline exits nonzero. `publish --no-wait` exits zero for acceptance, not completed deployment.
207
+
208
+ A status-query error or timeout means the outcome is unknown. Stopping local waiting, including Ctrl-C, does not cancel the remote build. Use the printed Build ID to inspect it later instead of resubmitting.
209
+
210
+ With `publish --json`, successful waiting returns one deployment result. With `--json --no-wait`, acceptance returns `{uid: string, status: "accepted"}`. JSON mode writes no progress to stdout; failures and recovery instructions go to stderr.
211
+
212
+ ### Structured command results
213
+
214
+ Pass `--json` explicitly for machine output. Human output remains the default,
215
+ including when redirected. Success writes one newline-terminated JSON value to
216
+ stdout with exit code 0. Empty lists write `[]`. Failures write human-readable
217
+ diagnostics to stderr, exit nonzero, and do not write a success result to stdout.
218
+ JSON output contains no progress, colors, links, or upgrade notices. In JSON
219
+ mutation mode, missing inputs fail with the required flag instead of prompting,
220
+ even in a terminal.
221
+
222
+ #### List contracts
223
+
224
+ | Command | JSON value |
225
+ | ------------------------------ | -------------------------------------------------------------------------------------------------------- |
226
+ | `team list --json` | Array of `{uid: string, name: string, current: boolean}` |
227
+ | `registry list --json` | Array of `{namespace: string, slug: string, title: string, version: string, isPrivate: boolean}` |
228
+ | `schema list --json` | Array of `{namespace: string, slug: string, title: string, version: string \| null, isPrivate: boolean}` |
229
+ | `sdk list --json` | Array of SDK metadata objects described below |
230
+ | `sdk get --slug <slug> --json` | One SDK metadata object |
231
+
232
+ Schema `version` is the greatest version by semantic-version comparison, or
233
+ `null` when no version exists. Registry `version` is the current version.
234
+ List order is unspecified. These list commands have no pagination flags,
235
+ continuation tokens, or incremental output: each invocation returns a single
236
+ array from the selected team or namespace. Do not interpret an empty array as
237
+ an authentication failure; authentication failures exit nonzero.
238
+
239
+ SDK metadata fields:
240
+
241
+ | Field | Type |
242
+ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
243
+ | `uid`, `namespace`, `slug`, `title`, `description`, `currentVersion` | string |
244
+ | `isPrivate` | boolean |
245
+ | `createdAt`, `updatedAt` | number, Unix seconds |
246
+ | `api` | `null` or `{uid: string, trackedVersion: string \| null, namespace: string \| null, slug: string \| null}` |
247
+ | `targets` | Array of `{language: string, slug?: string}` |
248
+ | `versions` | Array of version objects below |
249
+ | `latestBuild` | Latest build by creation time, or `null` when no build exists |
250
+
251
+ Each version has `version: string`, `apiVersion: string`, `status: string`,
252
+ `languages: string[]`, `createdAt: number | null`,
253
+ `publishedAt: number | null`, and `targets`, an array of
254
+ `{language: string, activeBuild: string | null, builtAt: number | null}`.
255
+ Each latest build has `uid: string`, `version: string`, `createdAt: number`,
256
+ `api: {uid: string, namespace: string, slug: string, version: string}`, and
257
+ `targets`, an array of
258
+ `{language: string, slug?: string, buildStatus: string, gitStatus: string | null}`.
259
+ All timestamps are Unix seconds. Optional target slugs are omitted when absent;
260
+ nullable fields are emitted as `null`. Source API coordinates are `null` when
261
+ the linked API no longer exists. SDK JSON fails if required build or source
262
+ metadata cannot be loaded. It excludes configuration, credentials, repository
263
+ authentication bindings, and build log messages.
264
+
265
+ #### Mutation contracts
266
+
267
+ | Command with `--json` | Success object |
268
+ | ------------------------------------ | ---------------------------------------------------- |
269
+ | `registry publish`, `schema publish` | `{uid, namespace, slug, version}` |
270
+ | `registry update` | `{namespace, slug, status: "updated"}` |
271
+ | `registry delete` | `{namespace, slug, deleted: true}` |
272
+ | `schema update`, `sdk update` | `{uid, namespace, slug, status: "updated"}` |
273
+ | `schema delete`, `sdk delete` | `{uid, namespace, slug, deleted: true}` |
274
+ | `sdk create` | `{uid}` |
275
+ | `sdk build` | `{uid, namespace, slug, version, status: "started"}` |
276
+
277
+ All identifiers, coordinates, versions and status values are strings, except
278
+ SDK build `version`, which can be `null` if the server does not return its
279
+ resolved version. `deleted` is a boolean. Fields shown in each success object
280
+ are always present. A build receipt means the server accepted the build request,
281
+ not that generation finished; no build ID is returned by that endpoint.
282
+ SDK create returns the new SDK UID without an additional metadata request.
283
+ Updates and deletes acknowledge the resolved target; they are not resource
284
+ snapshots. A transport failure can leave a mutation's outcome unknown, so inspect
285
+ the resource before retrying a write.
286
+
287
+ Supply the existing targeting flags and arguments, for example:
288
+
289
+ ```sh
290
+ scalar registry list --namespace acme --json
291
+ scalar registry update acme widgets --title "Widgets API" --json
292
+ scalar schema publish schema.json --namespace acme --slug widget --title Widget --version 1.0.0 --json
293
+ scalar sdk create --namespace acme --api widgets --language typescript --json
294
+ scalar sdk build --namespace acme --slug widgets --json
295
+ ```
296
+
297
+ Team list UIDs can be passed directly to `scalar team set --team <uid>` when
298
+ using browser-session authentication. Personal tokens belong to one team and
299
+ cannot switch teams. Registry/schema list coordinates and SDK list slugs can
300
+ likewise be passed to their mutation commands.
301
+
302
+ #### Team and project results
303
+
304
+ The same explicit JSON mode, stdout/stderr separation, and noninteractive input
305
+ rules apply to the following commands. Existing team and project list/get output
306
+ is preserved.
307
+
308
+ | Command with `--json` | Result |
309
+ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
310
+ | `team set --team <uid>` | `{uid: string, name: string, current: true}` after switching the session |
311
+ | `project create --name <name>` | `{uid: string, slug: string, name: string}`; an omitted slug is generated by the server |
312
+ | `project init --subdomain <name>` | `{configPath: string, subdomain: string, files: string[], availabilityChecked: boolean}` |
313
+ | `project upgrade [config]` | `{configPath: string, changed: boolean, files: string[], dropped: string[]}` |
314
+ | `project publish --slug <slug>` | `{uid: string, status: "deployed", url: string \| null, preview: boolean, hasWarnings: boolean}` |
315
+ | `project rollback --slug <slug> --yes` | `{uid: string, projectUid: string, slug: string, status: "redeployed" \| "already-live"}` |
316
+ | `project deployments list --slug <slug>` | Array of `{uid: string, status: string, current: boolean, createdAt: number, deployedAt: number \| null, commitSha: string \| null}` |
317
+
318
+ Project init and upgrade return absolute paths. `files` lists the files written.
319
+ Initialization's `availabilityChecked: false` means no authenticated subdomain
320
+ availability check was performed, not that the subdomain was reserved.
321
+ Initialization still requires `--force` to overwrite an existing configuration.
322
+ An already-current config upgrade returns `changed: false`, `files: []`, and
323
+ `dropped: []`. A completed upgrade reports settings without a v2 equivalent in
324
+ `dropped`.
325
+
326
+ By default, project publish waits for the deployment to finish in both output modes.
327
+ With `--no-wait`, it returns after acceptance; JSON output is `{uid: string, status: "accepted"}`.
328
+ Its `uid` is the build ID. `url` is null when no public URL can be resolved.
329
+ Warnings about local configuration are sent to stderr; build warnings are
330
+ reported by `hasWarnings`. Failed or cancelled builds exit nonzero without a
331
+ success object. The behavior also applies to `--github` and `--preview`.
332
+
333
+ Rollback requires `--yes` before changing the live deployment. JSON does not
334
+ supply confirmation. `already-live` is a successful no-op and performs no
335
+ redeploy request; `redeployed` acknowledges a successful redeploy request.
336
+ Deployment history includes production builds only, newest creation time first,
337
+ with no pagination flags or continuation tokens. Empty history is `[]`.
338
+ Timestamps are Unix seconds; older records without a deployment timestamp use
339
+ `deployedAt: null`. The full `uid` can be passed to rollback's `--to`:
340
+
341
+ ```sh
342
+ scalar project deployments list --slug docs --json
343
+ scalar project rollback --slug docs --to <build-id> --yes --json
344
+ ```
345
+
346
+ Existing `project list --json` returns an array sorted by slug, while
347
+ `project get <slug> --json` returns one object. Each object contains
348
+ `uid`, `name`, and `slug` (strings), `isPrivate` (boolean), `provider`
349
+ (`github`, `forgejo`, `bitbucket`, or `unlinked`), `repository` (null or
350
+ `{name: string, branch: string, configPath: string}`), and `activeDeployment`
351
+ (null or `{uid: string, domain: string, publishedAt: number}`, with Unix seconds).
352
+ Project listing follows service continuation cursors internally and prints no
353
+ partial list if a cursor or fetch fails. It merges legacy projects, preferring
354
+ unified projects with the same UID or slug.
355
+
356
+ #### Existing access-group contracts
357
+
358
+ Access-group JSON formats remain unchanged:
359
+
360
+ | Command with `--json` | Result |
361
+ | -------------------------------------------- | ----------------------------------------------------------------------- |
362
+ | `access-group list` | Array of group metadata objects; empty `[]` |
363
+ | `access-group get <slug>` | One group metadata object |
364
+ | `access-group create <slug>` | Group metadata plus `createdAt` and `updatedAt` (numbers, Unix seconds) |
365
+ | `access-group update <slug>` | `null` after success |
366
+ | `access-group delete <slug> --yes` | `null` after success |
367
+ | `access-group domain add <slug> <domain>` | `null` after success |
368
+ | `access-group domain remove <slug> <domain>` | `null` after success |
369
+
370
+ Group metadata is `{uid: string, name: string, slug: string,
371
+ allowedDomains: string[], allowedEmails: string[]}`. Ordering is unspecified;
372
+ no pagination flags or continuation tokens are exposed. Deletion requires
373
+ `--yes` in JSON mode even in a terminal. A successful `null` response is an
374
+ acknowledgement, not an empty list or a failed lookup; failures use stderr and a
375
+ nonzero exit status.
376
+
377
+ Long-running project preview, configuration validation, and raw file downloads
378
+ are not mutation-result streams and do not gain `--json` from this feature.
379
+
380
+ ## File and download failures
381
+
382
+ URL input for `document format`, `upgrade`, `markdown`, `mock`, `serve`, `postman`, and `share`, plus Registry and schema publish input, has a 10-second download deadline. `registry get` and `schema get` use the same deadline. It includes reading the response body, but is not a total command runtime limit. Downloads are not automatically retried.
383
+
384
+ File and download failures report the input, a known cause when available, and a recovery step on stderr, with exit code 1. Diagnostic URLs omit credentials, query strings, and fragments. Remote error bodies are not echoed because they may contain credentials; HTTP status remains available. Successful document output is unchanged.
@@ -13,13 +13,21 @@ import {
13
13
  findConfig,
14
14
  legacyTo2_0_0
15
15
  } from "./chunk-MQ65WBVF.js";
16
- import "./chunk-5ENKYZA4.js";
16
+ import {
17
+ writeJson
18
+ } from "./chunk-SNQFFEYH.js";
17
19
  import {
18
20
  ConfigVersion
19
21
  } from "./chunk-VRZSDUZK.js";
22
+ import {
23
+ requireInteractive,
24
+ text
25
+ } from "./chunk-XUX6JXU5.js";
26
+ import "./chunk-IRQJDPZE.js";
20
27
  import {
21
28
  output
22
29
  } from "./chunk-T5HJUAWB.js";
30
+ import "./chunk-5ENKYZA4.js";
23
31
  import "./chunk-I57ID5K7.js";
24
32
  import "./chunk-3MZYUBJ6.js";
25
33
 
@@ -28,11 +36,14 @@ import { spawnSync } from "node:child_process";
28
36
  import { existsSync } from "node:fs";
29
37
  import fs from "node:fs/promises";
30
38
  import path from "node:path";
31
- import { text } from "@clack/prompts";
32
39
  import as from "ansis";
33
40
  import { n } from "neverpanic";
34
- async function upgradeAction(__configPath) {
35
- const configPath = __configPath || findConfig() || await text({
41
+ async function upgradeAction(providedConfigPath, args = {}) {
42
+ const foundConfigPath = providedConfigPath || findConfig();
43
+ if (!foundConfigPath) {
44
+ requireInteractive("Provide the configuration file path.", args.json);
45
+ }
46
+ const configPath = foundConfigPath || await text({
36
47
  message: "Where is your configuration file located?",
37
48
  defaultValue: CONFIG_FILE_DEFAULT,
38
49
  placeholder: CONFIG_FILE_DEFAULT
@@ -41,13 +52,22 @@ async function upgradeAction(__configPath) {
41
52
  if (!parseConfigResult.success) {
42
53
  renderConfigError(parseConfigResult.error);
43
54
  }
44
- if (parseConfigResult.success) {
55
+ if (parseConfigResult.success && !args.json) {
45
56
  output.info().line(
46
57
  `${as.green("[SUCCESS]")} ${as.green("Configuration is valid:")} ${as.green(parseConfigResult.filePath)}`
47
58
  ).print();
48
59
  }
49
60
  const { config } = parseConfigResult;
50
61
  if (config.version === ConfigVersion.V2) {
62
+ if (args.json) {
63
+ writeJson({
64
+ configPath: path.resolve(parseConfigResult.filePath),
65
+ changed: false,
66
+ files: [],
67
+ dropped: []
68
+ });
69
+ return;
70
+ }
51
71
  return output.info().title("Your Scalar configuration is already upgraded").message(
52
72
  "You are already on the latest Scalar docs version. No further action required."
53
73
  ).exit("success");
@@ -101,7 +121,7 @@ async function upgradeAction(__configPath) {
101
121
  return output.error().title(`Could not save ${sideFile.path}`).message(writeSideFileResult.error.code).message(displayError(writeSideFileResult.error.detail)).exit("error");
102
122
  }
103
123
  }
104
- if (dropped.length) {
124
+ if (dropped.length && !args.json) {
105
125
  output.warn().title("Some settings have no V2 equivalent and were not carried over:").message(dropped.join(", ")).print();
106
126
  }
107
127
  const writeUpgradedConfigResult = await n.fromUnsafe(
@@ -114,6 +134,18 @@ async function upgradeAction(__configPath) {
114
134
  if (!writeUpgradedConfigResult.success) {
115
135
  return output.error().title("Could not save the upgraded configuration").message(writeUpgradedConfigResult.error.code).message(displayError(writeUpgradedConfigResult.error.detail)).exit("error");
116
136
  }
137
+ if (args.json) {
138
+ writeJson({
139
+ configPath: path.resolve(parseConfigResult.filePath),
140
+ changed: true,
141
+ files: [
142
+ path.resolve(parseConfigResult.filePath),
143
+ ...sideFiles.map((file) => path.resolve(projectRootDir, file.path))
144
+ ],
145
+ dropped
146
+ });
147
+ return;
148
+ }
117
149
  return output.info().title("Scalar Docs configuration upgraded").message("Run `scalar project preview` to preview your project.").exit("success");
118
150
  }
119
151
  function listGitFiles(projectRootDir) {
@@ -4,21 +4,25 @@ import {
4
4
  } from "./chunk-KHDYYVYF.js";
5
5
  import {
6
6
  isDocument
7
- } from "./chunk-I7ZVWF57.js";
7
+ } from "./chunk-LUR7BA3W.js";
8
8
  import {
9
9
  isAsyncApiDocument
10
- } from "./chunk-WKW5W2ZP.js";
10
+ } from "./chunk-DWN6JOF2.js";
11
+ import "./chunk-2XWUFFEZ.js";
11
12
  import {
12
- requireInteractive
13
- } from "./chunk-EGOXR5FB.js";
13
+ requireInteractive,
14
+ text
15
+ } from "./chunk-XUX6JXU5.js";
16
+ import "./chunk-IRQJDPZE.js";
14
17
  import {
15
18
  isUrl
16
19
  } from "./chunk-4ORL4MST.js";
17
- import "./chunk-TYNF7ROW.js";
20
+ import "./chunk-JHJDLZSM.js";
18
21
  import {
19
22
  output
20
23
  } from "./chunk-T5HJUAWB.js";
21
- import "./chunk-AOZQPCWI.js";
24
+ import "./chunk-5ENKYZA4.js";
25
+ import "./chunk-M4QTWCJ7.js";
22
26
  import "./chunk-Q26DFKTY.js";
23
27
  import "./chunk-I57ID5K7.js";
24
28
  import "./chunk-3MZYUBJ6.js";
@@ -26,7 +30,6 @@ import "./chunk-3MZYUBJ6.js";
26
30
  // src/domains/document/split/action.ts
27
31
  import fs2 from "node:fs/promises";
28
32
  import path2 from "node:path";
29
- import { text } from "@clack/prompts";
30
33
  import as from "ansis";
31
34
  import { bundle } from "@scalar/json-magic/bundle";
32
35
  import { fetchUrls, readFiles } from "@scalar/json-magic/bundle/plugins/node";
@@ -1,20 +1,22 @@
1
1
  import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
2
  import {
3
3
  getFileOrUrl
4
- } from "./chunk-I7ZVWF57.js";
4
+ } from "./chunk-LUR7BA3W.js";
5
5
  import {
6
6
  isAsyncApiContent
7
- } from "./chunk-WKW5W2ZP.js";
7
+ } from "./chunk-DWN6JOF2.js";
8
+ import "./chunk-2XWUFFEZ.js";
8
9
  import {
9
10
  config
10
- } from "./chunk-FYMDIB7J.js";
11
- import "./chunk-IOW726L2.js";
11
+ } from "./chunk-R3NDJICA.js";
12
+ import "./chunk-GARUDDWI.js";
12
13
  import "./chunk-4ORL4MST.js";
13
- import "./chunk-TYNF7ROW.js";
14
+ import "./chunk-JHJDLZSM.js";
14
15
  import {
15
16
  output
16
17
  } from "./chunk-T5HJUAWB.js";
17
- import "./chunk-AOZQPCWI.js";
18
+ import "./chunk-5ENKYZA4.js";
19
+ import "./chunk-M4QTWCJ7.js";
18
20
  import "./chunk-Q26DFKTY.js";
19
21
  import "./chunk-I57ID5K7.js";
20
22
  import "./chunk-3MZYUBJ6.js";
@@ -1,50 +1,51 @@
1
1
  import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
2
- import {
3
- getPublishDeploymentUrl
4
- } from "./chunk-7S34K2P3.js";
5
2
  import {
6
3
  readAndParseConfig,
7
4
  renderConfigError
8
5
  } from "./chunk-4YQVGOHX.js";
9
- import {
10
- resolveProject
11
- } from "./chunk-TSURUX4A.js";
12
6
  import {
13
7
  DEFAULT_ASSETS_DIR
14
8
  } from "./chunk-MQ65WBVF.js";
15
- import "./chunk-62OOT7FY.js";
16
9
  import {
17
- getDatabaseClient
18
- } from "./chunk-JWNWOK2M.js";
10
+ defaultWaitSeconds,
11
+ finishPublish,
12
+ timeoutSchema
13
+ } from "./chunk-RZDLPTXV.js";
14
+ import "./chunk-NOD4CBF7.js";
15
+ import {
16
+ resolveProject
17
+ } from "./chunk-TSURUX4A.js";
18
+ import "./chunk-SNSJW2JT.js";
19
+ import "./chunk-SNQFFEYH.js";
20
+ import "./chunk-HZ4UKLOE.js";
19
21
  import {
20
22
  apiService
21
- } from "./chunk-2GKXAGSH.js";
22
- import "./chunk-2AK5O3NQ.js";
23
- import "./chunk-KPLWZIOV.js";
23
+ } from "./chunk-6VAEDMCP.js";
24
+ import "./chunk-IDWF5L45.js";
25
+ import "./chunk-P4EPNS46.js";
24
26
  import "./chunk-YTTDYTVB.js";
25
- import "./chunk-Y2OQOAY7.js";
26
- import "./chunk-5ENKYZA4.js";
27
- import "./chunk-IRA5BW2J.js";
28
- import "./chunk-EXJUFF6G.js";
27
+ import "./chunk-RQNLEGMQ.js";
28
+ import "./chunk-X62ZTOQF.js";
29
+ import "./chunk-FXELV3AW.js";
29
30
  import "./chunk-RE5Z56QD.js";
30
31
  import "./chunk-VUXPDHTQ.js";
31
32
  import {
32
33
  getAuthData
33
- } from "./chunk-FI7UKPRF.js";
34
- import "./chunk-FYMDIB7J.js";
35
- import "./chunk-IOW726L2.js";
34
+ } from "./chunk-QS2T7JAK.js";
35
+ import "./chunk-R3NDJICA.js";
36
+ import "./chunk-GARUDDWI.js";
36
37
  import "./chunk-F3TQHNSQ.js";
37
38
  import {
38
39
  ConfigVersion,
39
- isGithubBackedDocsProject,
40
- publishRecordSchema
40
+ isGithubBackedDocsProject
41
41
  } from "./chunk-VRZSDUZK.js";
42
42
  import "./chunk-4ORL4MST.js";
43
- import "./chunk-TYNF7ROW.js";
43
+ import "./chunk-JHJDLZSM.js";
44
44
  import {
45
45
  output
46
46
  } from "./chunk-T5HJUAWB.js";
47
- import "./chunk-AOZQPCWI.js";
47
+ import "./chunk-5ENKYZA4.js";
48
+ import "./chunk-M4QTWCJ7.js";
48
49
  import "./chunk-Q26DFKTY.js";
49
50
  import {
50
51
  slugSchema,
@@ -332,12 +333,19 @@ async function publishProject({
332
333
  configPath,
333
334
  config,
334
335
  slug,
335
- mode
336
+ mode,
337
+ json = false
336
338
  }) {
337
339
  try {
338
340
  const root = path.join(configDir, config.root ?? "./");
339
341
  const missingReferences = findMissingReferences(root, config);
340
- if (missingReferences.length > 0) {
342
+ if (missingReferences.length > 0 && json) {
343
+ console.error(
344
+ "[WARN] Config references missing files:",
345
+ missingReferences.join(", ")
346
+ );
347
+ }
348
+ if (missingReferences.length > 0 && !json) {
341
349
  output.warn().title("Some files referenced by your config were not found").message(
342
350
  `The build may fail because these paths do not exist:
343
351
  ${missingReferences.map((reference) => ` - ${reference}`).join("\n")}`
@@ -383,20 +391,17 @@ async function publishUnifiedDocsProjectFromGithub({
383
391
  };
384
392
  }
385
393
 
386
- // src/helpers/utils.ts
387
- var sleep = (ms) => {
388
- return new Promise((resolve) => {
389
- setTimeout(resolve, ms);
390
- });
391
- };
392
-
393
394
  // src/domains/project/publish/action.ts
394
395
  async function publishAction(args) {
395
396
  const argsParseResult = zod_default.object({
396
397
  slug: slugSchema,
397
398
  config: zod_default.string().optional(),
398
399
  preview: zod_default.coerce.boolean().default(false),
399
- github: zod_default.coerce.boolean().default(false)
400
+ github: zod_default.coerce.boolean().default(false),
401
+ wait: zod_default.boolean().default(true),
402
+ timeout: timeoutSchema.optional()
403
+ }).refine((value) => value.wait || value.timeout === void 0, {
404
+ message: "--timeout cannot be combined with --no-wait."
400
405
  }).safeParse(args);
401
406
  if (argsParseResult.error)
402
407
  return output.error().title("Invalid arguments").message(argsParseResult.error.issues[0].message).exit("error");
@@ -404,7 +409,9 @@ async function publishAction(args) {
404
409
  config: configPathOption,
405
410
  slug,
406
411
  preview,
407
- github
412
+ github,
413
+ wait,
414
+ timeout = defaultWaitSeconds
408
415
  } = argsParseResult.data;
409
416
  const apiClient = await apiService();
410
417
  const auth = await getAuthData();
@@ -434,9 +441,13 @@ async function publishAction(args) {
434
441
  if (!publishResult3.success) {
435
442
  return output.error().title("Could not publish from GitHub").message(publishResult3.error).exit("error");
436
443
  }
437
- return await waitForPublish({
444
+ return await finishPublish({
445
+ wait,
446
+ timeout,
438
447
  teamUid: auth.teamUid,
439
- publishUid: publishResult3.publishUid
448
+ accessToken: auth.accessToken,
449
+ publishUid: publishResult3.publishUid,
450
+ json: args.json
440
451
  });
441
452
  }
442
453
  if (!isGithubBackedDocsProject(resolved.project)) {
@@ -457,9 +468,13 @@ async function publishAction(args) {
457
468
  if (!publishResult2.success) {
458
469
  return output.error().title("Could not publish from GitHub").message(publishResult2.error).exit("error");
459
470
  }
460
- return await waitForPublish({
471
+ return await finishPublish({
472
+ wait,
473
+ timeout,
461
474
  teamUid: auth.teamUid,
462
- publishUid: publishResult2.publishUid
475
+ accessToken: auth.accessToken,
476
+ publishUid: publishResult2.publishUid,
477
+ json: args.json
463
478
  });
464
479
  }
465
480
  const configResult = readAndParseConfig(configPathOption ?? "");
@@ -467,9 +482,16 @@ async function publishAction(args) {
467
482
  renderConfigError(configResult.error);
468
483
  }
469
484
  const { config, filePath: configPath } = configResult;
470
- warnIfLegacyConfig(config);
485
+ if (args.json && config.version === ConfigVersion.V1) {
486
+ console.error(
487
+ "[WARN] The v1 configuration will be upgraded for this build only."
488
+ );
489
+ } else {
490
+ warnIfLegacyConfig(config);
491
+ }
471
492
  const publishResult = await publishProject({
472
493
  config,
494
+ json: args.json,
473
495
  slug,
474
496
  configDir: dirname(configPath),
475
497
  configPath,
@@ -480,9 +502,13 @@ async function publishAction(args) {
480
502
  publishResult.error instanceof Error ? publishResult.error.message : publishResult.error
481
503
  ).exit("error");
482
504
  }
483
- return await waitForPublish({
505
+ return await finishPublish({
506
+ wait,
507
+ timeout,
484
508
  teamUid: auth.teamUid,
485
- publishUid: publishResult.publishUid
509
+ accessToken: auth.accessToken,
510
+ publishUid: publishResult.publishUid,
511
+ json: args.json
486
512
  });
487
513
  }
488
514
  function warnIfLegacyConfig(config) {
@@ -491,54 +517,7 @@ function warnIfLegacyConfig(config) {
491
517
  "It will be upgraded to v2 for this build only. Run `scalar project upgrade` to upgrade the config file."
492
518
  ).print();
493
519
  }
494
- async function waitForPublish({
495
- teamUid,
496
- publishUid
497
- }) {
498
- const dbClient = await getDatabaseClient();
499
- const logger = output.info({ animate: true }).loader("Deploying project\u2026");
500
- while (true) {
501
- const deployStatus = await getDeployStatus({
502
- client: dbClient,
503
- publishUid,
504
- teamUid
505
- });
506
- if (deployStatus.error === true) {
507
- return output.error().title("Could not load deployment status").exit("error");
508
- }
509
- logger.update("loader", 0, { content: deployStatus.data.message });
510
- if (deployStatus.data.status === "deployed") {
511
- const deploymentUrl = getPublishDeploymentUrl(deployStatus.data);
512
- if (deploymentUrl) {
513
- output.info().line(
514
- `${deployStatus.data.preview ? "Preview URL" : "Deployment URL"}: ${deploymentUrl}`
515
- ).print();
516
- }
517
- if (deployStatus.data.hasWarnings) {
518
- output.warn().title("The build finished with warnings").line("Check the build log in the Scalar Dashboard for details.").print();
519
- }
520
- logger.exit("success");
521
- return;
522
- }
523
- if (deployStatus.data.status === "error" || deployStatus.data.status === "cancelled") {
524
- return logger.exit("error");
525
- }
526
- await sleep(3e3);
527
- }
528
- }
529
- async function getDeployStatus({
530
- client,
531
- publishUid,
532
- teamUid
533
- }) {
534
- return client.getOne({
535
- collectionPath: `team/${teamUid}/publish`,
536
- schema: publishRecordSchema,
537
- query: { uid: publishUid }
538
- });
539
- }
540
520
  export {
541
521
  publishAction,
542
- waitForPublish,
543
522
  warnIfLegacyConfig
544
523
  };