@blinkhost/cli 2.4.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,172 @@
2
2
 
3
3
  This file records customer-visible CLI changes. BlinkHost uses semantic versioning for the CLI, while security and migration impact are classified separately. A patch may therefore require prompt action, and a major release may coexist with an earlier supported line during its documented migration window.
4
4
 
5
+ ## 2.5.0 — Idam limited preview
6
+
7
+ This release adds Idam commands for eligible accounts on an enabled control plane.
8
+ Idam remains a limited preview. Workspace permissions, feature availability and
9
+ spending limits are checked by the server. Installing the CLI does not enable
10
+ Idam or change a subscription. Node.js 22.12 or newer is required; no project
11
+ migration is needed from 2.4.0.
12
+
13
+ - Connected-review plans default to GPT-6 Luna and accept GPT-6 Luna and Sol
14
+ alongside GPT-5.6 Terra. Existing GPT-5.6 plan selections remain readable and
15
+ editable. Plan confirmation, approval and credit limits are unchanged.
16
+
17
+ - Windows sign-in allows up to 15 seconds for the read-only credential-tool
18
+ startup check. A timeout still stops sign-in safely; credential operations
19
+ retain their 30-second limit, with no automatic retry or plaintext fallback.
20
+
21
+ - Added named code review: list eligible reviewers, explicitly share
22
+ selected changes, inspect the shared review, approve or request changes, and
23
+ withdraw sharing. Decisions are bound to the reviewed version and current
24
+ access; they never save, build or publish. Conversations stay private.
25
+ Sharing is optional, but withdrawing a review does not bypass independent
26
+ approval required by a workspace for Idam source saves. This policy does not
27
+ cover starter creation, builds or deployments.
28
+ Reviewer options validate the server's explicit review-required flag; a missing
29
+ or malformed flag is not treated as permission to skip review.
30
+
31
+ - Windows sign-in no longer removes a saved credential before writing its
32
+ replacement. Vault failures stop the operation without retrying or displaying
33
+ private diagnostics; refresh credentials remain confined to an input pipe.
34
+
35
+ - macOS credential writes now send refresh tokens through a private input pipe,
36
+ not process arguments. A bounded single-command input rejects control
37
+ characters and preserves write failures; no temporary credential file or
38
+ automatic write retry is used.
39
+
40
+ - Added sign-in recovery guidance for globally revoked sessions and server-side
41
+ security updates. When a fresh sign-in is required, use the same profile and
42
+ explicitly request the permissions you need; an old approval link cannot
43
+ reconnect your device. This does not migrate project files or change billing.
44
+
45
+ - Bounded operating-system credential helpers and removed raw helper diagnostics
46
+ from errors. Linux keyring failures are no longer treated as missing credentials;
47
+ Windows missing-item handling distinguishes other vault errors. Sign-in guidance
48
+ explains recovery after browser approval without retrying an uncertain write.
49
+ Added a separate hosted-CI native-vault check for Linux, macOS and Windows
50
+ using only temporary synthetic credentials; ordinary local tests do not
51
+ modify the user's keyring. Linux and macOS checks also exercise a locked
52
+ synthetic keyring, bounded errors and recovery without losing saved credentials.
53
+ Windows checks cover normal vault operations, not a simulated desktop lock.
54
+ Linux also checks for retained locked credentials before reporting a missing
55
+ credential or successful removal when the keyring silently refuses to unlock.
56
+
57
+ - Added `projects export PROJECT_UUID --source-only --output ./source.zip` for
58
+ backend-only projects and unchanged source downloads. No build configuration,
59
+ README, schema or lockfile is generated or validated. The server must confirm
60
+ the requested mode. Access checks, credential screening and download limits
61
+ remain in effect; default portable exports are unchanged.
62
+
63
+ - Added safe, actionable source-export guidance for unsupported frontend
64
+ configurations, HTML package/lockfile issues and credential-screening blocks.
65
+ Error bodies are bounded and never printed; unknown failures retain their HTTP
66
+ status and request ID. Offline help explains portable and source-only exports.
67
+
68
+ - Fixed source exports returning HTTP 406 during API content negotiation.
69
+ Successful downloads still require a complete ZIP archive; JSON responses
70
+ cannot be saved as source exports.
71
+
72
+ - Fixed upload requests combining the default JSON content type with an explicit
73
+ multipart or binary content type, which could cause HTTP 415 errors. Custom
74
+ headers now replace defaults regardless of capitalization. Failed uploads are
75
+ still not retried automatically.
76
+
77
+ - Sign-in now explains expired codes and how to request a new one. Authorization
78
+ polling backs off when requested by the server and stops at expiry; uncertain
79
+ token-delivery or network failures are not retried automatically. Sign-in
80
+ addresses are validated before display or browser launch, and malformed token
81
+ responses cannot overwrite a saved credential.
82
+
83
+ - Corrected offline workflow help: approving a plan requires `ai:approve`,
84
+ separate from `ai:execute` for drafting, revising and stopping it.
85
+
86
+ - Added `projects export PROJECT_UUID --output ./project.zip` for source ZIPs,
87
+ distinct from Idam task exports. Existing authorization and secret screening
88
+ apply. Bounded downloads refuse redirects and overwrites; nothing is extracted
89
+ or executed. Database rows, runtime secrets and running deployments are excluded.
90
+
91
+ - Added backend starter choices, file review, explicit save approval and read-only
92
+ receipt recovery. Normal permissions, source revisions and module limits apply.
93
+ No builds, publication or AI charges; uncertain saves are never auto-retried.
94
+
95
+ - Added saved-module build choices, review, explicit approval and read-only status.
96
+ Normal compiler rollout, plan capacity and build metering remain authoritative;
97
+ no AI credits are used. Approval never publishes. CLI scope, exact digest and
98
+ review confirmation are required; uncertain responses are never auto-retried.
99
+
100
+ - Added explicitly confirmed `ai resume` for eligible multi-step checkpoints.
101
+ It preserves active work, retry delays, original spending limits and receipts;
102
+ it cannot restart stopped tasks or approve changes. Requires `ai:execute`.
103
+ Ambiguous responses are not retried automatically; inspect task status.
104
+
105
+ - Added `ai sources --project PROJECT_UUID` and bounded `research_source_ids`
106
+ selection for research requests. Reviewed excerpts are inspectable in task
107
+ details and exports, with attribution and citation status. This is not live
108
+ web search; sources are checked before admission and dispatch and count toward
109
+ the existing credit estimate. The separate source gate remains off by default.
110
+
111
+ - Extended declaration review to bounded `requirements.txt` files. Python server
112
+ frameworks and selected native packages receive qualified guidance, not a
113
+ promise of runtime support. Includes, URLs and pip options are not followed;
114
+ environment markers and extras are not evaluated. No code runs or changes.
115
+
116
+ - Extended the same bounded review to static `pyproject.toml` dependencies,
117
+ optional dependencies and build-system requirements, with separate fixed
118
+ labels. Dynamic/tool-specific declarations stay unknown. No build hooks run,
119
+ optional-group names are not disclosed, and older rule responses remain valid.
120
+
121
+ - Task exports identify the reviewed file selection separately from the full
122
+ proposal. An applied timestamp records a save, not a successful build or the
123
+ current contents of files. Review contents and approval tokens stay excluded.
124
+
125
+ - Made invisible direction and terminal controls visible in source review diffs.
126
+ Approval hashes still bind the original source. Structured CLI output uses
127
+ JSON escapes that preserve decoded values, including filenames and source.
128
+
129
+ - Added `ai compatibility --project PROJECT_UUID`: a read-only, revision-bound
130
+ declaration review with explicit inspection limits and no runtime certification.
131
+ Requires `ai:read`; no uploads, model calls, credit reservations or source edits.
132
+
133
+ - Added optional personal project guidance with `ai memory-show`, `memory-save`
134
+ and `memory-clear`. Saving uses an explicitly selected, bounded UTF-8 file,
135
+ reviewed version and project confirmation. Changes stop queued work using
136
+ older guidance; clearing does not erase existing task records or backups.
137
+ - Workload identities are refused across the personal Idam preview, so automated
138
+ jobs cannot inherit the creator's guidance, history or source approvals.
139
+
140
+ - Added `ai workflow-plan`, `workflow-revise`, `workflow-approve`, `workflow-status`
141
+ and `workflow-cancel` for bounded investigation-and-review drafts. Saving and
142
+ editing do not start follow-ups. Approval binds the inspected revision and
143
+ digest with exact workflow confirmation. `workflow-start` is a draft-only
144
+ compatibility alias. Saved version history remains available on each task.
145
+ Separately gated; plan approval does not authorize tools, tests, source writes
146
+ or deployments.
147
+
148
+ - Added `ai rollback-review` and `ai rollback-approve` for an explicitly reviewed,
149
+ source-only undo. Later file edits are protected; unchanged new files are removed
150
+ only when no active co-editing session references them. Original history and
151
+ charges remain unchanged. This is not deployment rollback or project recovery.
152
+
153
+ - `ai export` now retrieves a versioned, private task snapshot with credit totals,
154
+ removal status and explicit history limits. Proposed source is opt-in with
155
+ `--include-source`; internal context, approval tokens and input files are excluded.
156
+
157
+ - Optional, explicitly selected workspace source files for a task, with credential
158
+ screening and byte limits before funding. No implicit local-file upload.
159
+
160
+ - Added `ai start`, `list`, `status`, `events`, `export`, `review`, `approve` and `cancel`.
161
+ - Start requests use a bounded JSON file with a stable request ID and explicit budget.
162
+ - Source approval requires the reviewed action digest and exact task confirmation;
163
+ saving does not build, test, publish, purchase resources or create a Git commit.
164
+ - Added repeated `auth login --scope` for explicit AI permissions. Existing sessions,
165
+ default sign-ins and workload identities do not receive AI permissions automatically.
166
+ - Included offline `docs ai` with scope, privacy, retry and verification limits.
167
+
168
+ These commands require the matching control-plane integration and current project
169
+ access. They were not included in 2.4.0. No automatic update is performed.
170
+
5
171
  ## 2.4.0 — 2026-09-02
6
172
 
7
173
  ### Added
package/README.md CHANGED
@@ -7,7 +7,7 @@ The BlinkHost CLI brings project setup, local development, source control, previ
7
7
  Node.js 22.12 or newer is required.
8
8
 
9
9
  ```bash
10
- npm install --global @blinkhost/cli@2.4.0
10
+ npm install --global @blinkhost/cli@2.5.0
11
11
  blinkhost --version
12
12
  ```
13
13
 
@@ -15,16 +15,194 @@ Signed release archives, checksums, the CycloneDX SBOM, and Sigstore verificatio
15
15
 
16
16
  ## Current release
17
17
 
18
- ### 2.4.0 — release intelligence and compatibility guidance
18
+ ### 2.5.0 — Idam limited preview
19
19
 
20
- - Added `blinkhost update notes [VERSION]` for terminal-accessible, verified release history.
21
- - Added cached, time-bounded update awareness that stays silent in CI, structured output, and non-interactive sessions.
22
- - CLI token refresh now records the installed client version so project compatibility guidance does not rely on a stale login record.
20
+ - Added Idam task, source-review, starter, build, export and connected-review commands.
21
+ - Connected-review plans default to GPT-6 Luna and support GPT-6 Sol and GPT-5.6 Terra; older GPT-5.6 plans remain readable.
22
+ - Improved scoped sign-in and operating-system credential handling on Linux, macOS and Windows.
23
+
24
+ Idam remains a limited preview. Access depends on the server rollout, current
25
+ project permissions and available credits. Installing this CLI does not enable
26
+ Idam or change a subscription. No project migration is required from 2.4.0.
23
27
 
24
28
  Run `blinkhost update notes` to read published notes in the terminal. The complete version history and compatibility policy are maintained in [CHANGELOG.md](./CHANGELOG.md) and the [developer release notes](https://app.blinkhost.me/docs/releases).
25
29
 
26
30
  ## Start safely
27
31
 
32
+ ### Idam limited preview
33
+
34
+ Request a review of selected code with
35
+ `ai peer-options TASK_UUID --project PROJECT_UUID`, then
36
+ `ai peer-invite TASK_UUID --project PROJECT_UUID --reviewer USER_ID --digest ACTION_DIGEST --confirm TASK_UUID`.
37
+ Prepare and inspect `ai review` first. Only the selected before-and-after code
38
+ is shared with the named owner or administrator; conversations and other
39
+ proposed files remain private. The reviewer uses `ai peer-inbox --project PROJECT_UUID`,
40
+ `ai peer-review PEER_UUID --project PROJECT_UUID`, then
41
+ `ai peer-approve PEER_UUID --project PROJECT_UUID --digest REVIEW_DIGEST --confirm PEER_UUID`
42
+ or `peer-decline` with the same options. Read commands need `ai:read`; sharing
43
+ and decisions need `ai:approve`. Decisions never save, build or publish.
44
+ The requester saves separately after approval, or explicitly withdraws with
45
+ `ai peer-withdraw TASK_UUID --project PROJECT_UUID --peer PEER_UUID --confirm TASK_UUID`.
46
+ Sharing is optional, but your workspace may require independent approval before
47
+ Idam source saves. Withdrawal ends sharing and preserves history; it does not
48
+ bypass workspace-required review.
49
+ Reviews expire after at most 15 minutes and changes to source or permissions
50
+ require fresh review. Inspect current status after a timeout; do not retry
51
+ automatically. This policy covers Idam source saves only, not starter creation,
52
+ builds or deployments; those retain their separate permissions and approvals.
53
+ These commands require current Idam access. See `blinkhost docs ai`.
54
+
55
+ Create a supported backend starter with `ai starters --project PROJECT_UUID` and
56
+ `ai starter-review --project PROJECT_UUID --name api --language LANGUAGE_ID --revision SOURCE_REVISION --request-id REQUEST_UUID`.
57
+ Inspect the returned files and retain the review UUID before approving with
58
+ `ai starter-approve REVIEW_UUID --project PROJECT_UUID --digest ACTION_DIGEST --confirm REVIEW_UUID`.
59
+ This saves new source through normal module limits; it does not build or publish.
60
+ No AI credits are used. After an uncertain response, use
61
+ `ai starter-status REVIEW_UUID --project PROJECT_UUID` to reconcile the original
62
+ save, never another create. Read, preparation and approval require `ai:read`,
63
+ `ai:execute` and `ai:approve` respectively.
64
+
65
+ Saved WASM modules can be reviewed for a normal, metered build using
66
+ `ai build-modules --project PROJECT_UUID`, followed by
67
+ `ai build-review --project PROJECT_UUID --module MODULE_UUID --revision SOURCE_REVISION --request-id REQUEST_UUID`.
68
+ Retain the request UUID. Review the source in the IDE and the returned digest,
69
+ usage policy and expiry. Then explicitly approve with
70
+ `ai build-approve REVIEW_UUID --project PROJECT_UUID --digest ACTION_DIGEST --confirm REVIEW_UUID`.
71
+ Read/list needs `ai:read`, preparation needs `ai:execute`, and approval needs
72
+ `ai:approve`. This uses normal build allowance, configured overages and duration
73
+ usage—not AI credits. It does not publish, promote an artifact or commit files.
74
+ Unsaved edits are excluded. After a timeout, use
75
+ `ai build-status REVIEW_UUID --project PROJECT_UUID` before any further action;
76
+ do not create a new review to repeat an uncertain build. See `blinkhost docs ai`.
77
+ These commands require current Idam access and an available module compiler.
78
+
79
+ For an eligible multi-step task, use
80
+ `blinkhost ai resume TASK_UUID --confirm TASK_UUID` with `ai:execute` to request
81
+ continuation from its saved checkpoint. This keeps the same task, original
82
+ credit limit and confirmed usage. Active work and retry delays are preserved;
83
+ it does not restart stopped or completed tasks, increase spending, approve
84
+ changes or repeat confirmed execution. Project access, revision and guidance
85
+ are checked again. After a timeout, inspect `ai status` before taking another
86
+ action.
87
+
88
+ Reviewed public sources have a separate feature gate that is off by default. Use
89
+ `blinkhost ai sources --project PROJECT_UUID` with `ai:read` to inspect the
90
+ available excerpts, attribution and capture/review dates. To use them, set
91
+ `"mode": "research"` and `"research_source_ids": ["SOURCE_SHA256"]` in the
92
+ request JSON (up to four unique IDs). This does not browse or fetch websites.
93
+ Source text counts toward the credit estimate. Expired or withdrawn sources
94
+ cannot start new work; already dispatched work can finish. Task status/export
95
+ retains the excerpts provided, not later versions of the source website. A model
96
+ citation is not proof that a conclusion is correct.
97
+
98
+ Source-review diffs use `[U+…]` markers for invisible control characters and
99
+ annotations for line endings. They are review displays, not patches to copy.
100
+ Approvals bind the original source, which these annotations do not modify.
101
+ Structured terminal output escapes controls while preserving the exact decoded
102
+ JSON values. Ordinary Unicode is retained; this is not a confusable-character
103
+ detector or a guarantee that proposed code is safe.
104
+
105
+ Version 2.5.0 includes `blinkhost ai` task and reviewed-change commands, with
106
+ offline help at `blinkhost docs ai`. They require an enabled Idam preview.
107
+ AI task execution (`ai:execute`) and source
108
+ approval (`ai:approve`) are separate, explicitly requested permissions; existing
109
+ sessions do not gain these permissions automatically. See the [changelog](./CHANGELOG.md).
110
+
111
+ Saving an approved proposal changes workspace source only. Build, test and preview
112
+ before publishing. To share source with Azure OpenAI for a task, include optional
113
+ `source_paths` in its request JSON (up to eight project-relative paths of saved
114
+ workspace files, 16 KiB each / 24 KiB total). No local files are uploaded. Review
115
+ selected files for credentials; automated screening is not exhaustive. Omit the
116
+ field to share structural metadata only.
117
+
118
+ Unknown model usage is never automatically retried or refunded.
119
+
120
+ To review only part of a proposal, use `blinkhost ai review TASK_UUID --path
121
+ src/example.ts` (repeat `--path` for more files). With no paths, all proposed files
122
+ are included. Inspect every returned diff before approval. Changing the selection
123
+ requires a fresh review; saving finishes the task and omitted files may still be
124
+ needed for the application to work. Task exports distinguish the full proposal
125
+ from `review.paths`; only a populated review `applied_at` records that selection's
126
+ save. This is file selection, not automatic dependency analysis or project copying.
127
+
128
+ Use `blinkhost ai compatibility --project PROJECT_UUID` for a read-only review of
129
+ the saved project's declared dependencies. It requires `ai:read` and the enabled
130
+ Idam preview. Results identify the workspace
131
+ revision, manifest paths, declaration sections and inspection limits. Only a fixed
132
+ set of npm and Python package names is checked in `package.json` and single-line
133
+ `requirements.txt` and static `pyproject.toml` declarations. Runtime, optional and
134
+ build-system requirements keep distinct labels; build-only use is not runtime
135
+ use. Python markers and extras are not evaluated. Dynamic dependencies, tool
136
+ overrides, includes, pip options, URLs and other manifest formats need manual
137
+ review. No lockfile or transitive dependency graph is resolved.
138
+ No findings is **not a compatibility pass**. This command uploads no local
139
+ files, makes no model calls, reserves no credits and does not install, build, test,
140
+ adapt or deploy code. Customer backend execution remains WASM-only. Review project
141
+ metadata before sharing command output, and rerun after workspace changes.
142
+
143
+ You can save optional project guidance for your own future tasks using the
144
+ `ai memory-show`, `memory-save` and `memory-clear` commands. First run
145
+ `blinkhost ai memory-show --project PROJECT_UUID` and inspect the saved version.
146
+ Then use `blinkhost ai memory-save --project PROJECT_UUID --file @guidance.txt
147
+ --expected-version VERSION --confirm PROJECT_UUID` to upload a regular UTF-8 file
148
+ of at most 4 KiB. Saving authorizes sending this guidance with future model tasks;
149
+ it does not change permissions, runtime support or billing. Keep credentials out.
150
+ `memory-show` prints private text: take care with logs and shared terminals.
151
+
152
+ To clear it, run `blinkhost ai memory-clear --project PROJECT_UUID
153
+ --expected-version VERSION --confirm PROJECT_UUID`. Editing or clearing prevents
154
+ queued tasks and later workflow steps from using an older version. Work already
155
+ sent may finish. Existing task copies and backups are not erased. After a timeout
156
+ or conflict, reload and compare with `memory-show` before another write; the CLI
157
+ never retries it automatically. Reading requires `ai:read`; saving and clearing
158
+ require `ai:execute`. CI workload identities cannot use the personal Idam preview,
159
+ including indirectly through task creation or history, regardless of token scopes.
160
+
161
+ Connected investigation-and-review sequences require a separate feature gate.
162
+ Inspect `ai status TASK_UUID` first. Then
163
+ `ai workflow-plan TASK_UUID --maximum-units TOTAL_LIMIT --confirm TASK_UUID`
164
+ saves a draft with two follow-ups of 80 credits each. `TOTAL_LIMIT` must
165
+ cover the original task's approved limit plus 160 credits, up to 2,000 total.
166
+ Saving does not approve follow-ups; the original task continues independently.
167
+ `workflow-start` remains a draft-only compatibility alias. Use
168
+ `ai workflow-status WORKFLOW_UUID` to inspect the saved plan and version history.
169
+ To change a draft, use `ai workflow-revise WORKFLOW_UUID --request @plan.json
170
+ --expected-revision VERSION --digest PLAN_DIGEST --confirm WORKFLOW_UUID`.
171
+ The regular UTF-8 JSON file (16 KiB maximum) contains exactly `steps`,
172
+ `maximum_units` and `maximum_context_units`; see `blinkhost docs ai` for the schema.
173
+ Then approve the version you inspected with `ai workflow-approve WORKFLOW_UUID
174
+ --expected-revision VERSION --digest PLAN_DIGEST --confirm WORKFLOW_UUID`.
175
+ Changed drafts require fresh review; approved or stopped plans cannot be edited.
176
+ Reading requires `ai:read`, preparing or revising a plan requires `ai:execute`,
177
+ and approving it requires the separate `ai:approve` permission. Approval permission
178
+ does not grant access to another user's plan or bypass current project access.
179
+ These operations grant no funding and reserve no additional credits. Each later
180
+ step checks available balance and current project access. Use
181
+ `ai workflow-cancel WORKFLOW_UUID --confirm WORKFLOW_UUID` to stop later steps.
182
+ After a timeout, task status exposes `analysis_workflow.id`; inspect it before
183
+ making another write. Never automatically retry approval or reuse stale versions.
184
+ These are drafts, not executed tests or deployments.
185
+ Follow-ups retain the original request and previous draft under their own task
186
+ retention periods. Removing one task does not remove copies in another.
187
+
188
+ `blinkhost ai export TASK_UUID --json` prints a versioned private task record.
189
+ Add `--include-source` only when you want proposed source-file copies included.
190
+ Requests and narrative may still contain private information: review before
191
+ sharing. This is not a project backup or deployment certificate. Removed content
192
+ is not reconstructed; long histories are marked partial, and existing downloads
193
+ are outside task-history retention. See `blinkhost docs ai` for limits.
194
+
195
+ To undo an Idam source save in the limited preview, run
196
+ `blinkhost ai rollback-review TASK_UUID --json`, inspect its file restorations and
197
+ removals, then run `blinkhost ai rollback-approve TASK_UUID --digest UNDO_ACTION_DIGEST --confirm TASK_UUID`.
198
+ This is a separate, expiring approval, not the original source-save digest.
199
+ Preparing requires `ai:execute`; confirming requires `ai:approve`. Later edits to
200
+ affected files block undo. Other files and folders are preserved. Removed task
201
+ content cannot be recovered. Undo does not reverse deployments, charges or Git
202
+ commits. Check the task after a timeout; these commands do not automatically retry.
203
+
204
+ ### Local readiness
205
+
28
206
  ```bash
29
207
  blinkhost quickstart
30
208
  blinkhost docs
@@ -51,8 +229,28 @@ blinkhost profile use work
51
229
 
52
230
  Revoke a device with `blinkhost auth revoke SESSION_ID` or disconnect all CLI sessions for the active profile with `blinkhost auth logout`.
53
231
 
232
+ If your CLI session is rejected after signing out of all devices, an account
233
+ security change or a BlinkHost security update, run `blinkhost auth login` again
234
+ with the same `--profile` and any explicit `--scope` options you need. Sign in to
235
+ the correct account in your browser and review the new request before approving.
236
+ Reopening an old approval link does not reconnect the CLI. Reauthentication does
237
+ not change your project files, deployments or billing plan. If the new sign-in is
238
+ blocked, check email verification and any required legal acceptance in the
239
+ dashboard; do not copy credentials from another device to work around it.
240
+
54
241
  Interactive credential storage uses macOS Keychain, Windows Password Vault, or Linux Secret Service (`secret-tool` with an available, unlocked session keyring). The CLI intentionally does not fall back to a plaintext refresh-token file. Headless systems should use a registered GitHub OIDC workload or a short-lived runtime access token.
55
242
 
243
+ Before opening browser authorization, the CLI checks that the credential tooling can run. This does not prove that your keyring is unlocked; on Linux, start an unlocked Secret Service session first. Missing tooling is reported before a device authorization is requested.
244
+
245
+ Credential-tool checks stop after five seconds on macOS and Linux, or 15 seconds
246
+ on Windows to allow PowerShell to start. Credential reads and writes stop after
247
+ 30 seconds. These checks do not retry. Keyring errors use safe messages without displaying helper
248
+ output. On Linux, an unavailable session keyring is reported as a credential-service
249
+ failure rather than a missing sign-in. Unlock or restart your Secret Service session.
250
+ If browser approval succeeded but saving the session failed or timed out, review
251
+ your CLI sessions in BlinkHost settings before starting another sign-in. The CLI
252
+ does not automatically retry credential writes or fall back to plaintext storage.
253
+
56
254
  ## Create or adopt a project
57
255
 
58
256
  ```bash
@@ -84,6 +282,44 @@ blinkhost test .
84
282
 
85
283
  ## Remote workflows
86
284
 
285
+ ### Download project source
286
+
287
+ ```bash
288
+ blinkhost projects export PROJECT_UUID --output ./project-source.zip --json
289
+ ```
290
+
291
+ This downloads source and portable configuration through BlinkHost's existing
292
+ export service. It requires `projects:read` and an owner, admin or developer role;
293
+ connecting GitHub is optional. Choose a new `.zip` filename in an existing
294
+ directory without symbolic links. Downloads are limited to 32 MiB and 30 seconds.
295
+ The CLI does not follow redirects, replace existing files, extract the ZIP or run
296
+ its contents. It returns a SHA-256 checksum and saves with private permissions
297
+ where POSIX permissions apply.
298
+
299
+ The default portable export requires a supported frontend configuration. For
300
+ backend-only projects, or to download source without generating build files, use:
301
+
302
+ ```bash
303
+ blinkhost projects export PROJECT_UUID --source-only --output ./source.zip --json
304
+ ```
305
+
306
+ Source-only mode preserves workspace files and validated project assets, including
307
+ any existing configuration. It does not generate or validate build configuration,
308
+ README files, database schemas or lockfiles. A connected repository's saved base
309
+ is overlaid with the workspace; files outside the application root are preserved.
310
+ It is not a fresh fetch of the remote branch. The server must explicitly confirm
311
+ source-only mode, so an older server cannot silently return generated files.
312
+ The same authorization, credential screening and size limits apply in both modes.
313
+ Known configuration and credential-screening errors include next steps and a
314
+ request ID; raw server details are not printed. Export never repairs your stored
315
+ configuration, installs dependencies or changes source on your behalf.
316
+
317
+ The archive is **not a database backup or a running deployment**. Database rows,
318
+ runtime secrets, deployed artifacts and complete Git history are not included.
319
+ Source is screened for possible credentials, but review it before sharing.
320
+ Configure resources and secrets separately, and check compatibility before running
321
+ the exported application elsewhere. `ai export` instead exports a task record.
322
+
87
323
  Resource commands use the same pattern:
88
324
 
89
325
  ```bash
@@ -190,7 +426,7 @@ Pin or roll back explicitly with `npm install --global @blinkhost/cli@VERSION`.
190
426
  ```bash
191
427
  cosign verify-blob \
192
428
  --bundle SHA256SUMS.sigstore.json \
193
- --certificate-identity "https://github.com/blinkhost-ltd/blinkhost-cli/.github/workflows/release.yml@refs/tags/v2.4.0" \
429
+ --certificate-identity "https://github.com/blinkhost-ltd/blinkhost-cli/.github/workflows/release.yml@refs/tags/v2.5.0" \
194
430
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
195
431
  SHA256SUMS
196
432
  ```
package/dist/api.d.ts CHANGED
@@ -11,6 +11,7 @@ export declare class ApiClient {
11
11
  private constructor();
12
12
  static create(profileName?: string): Promise<ApiClient>;
13
13
  static fromAccessToken(profileName: string, profile: Profile, accessToken: string): ApiClient;
14
+ projectArchive(projectId: string, mode?: 'portable' | 'source'): Promise<Buffer>;
14
15
  request(path: string, init?: RequestInit): Promise<unknown>;
15
16
  rememberIdentity(identity: {
16
17
  id?: number;
package/dist/api.js CHANGED
@@ -4,6 +4,56 @@ import { deleteRefreshCredential, getRefreshCredential, setRefreshCredential } f
4
4
  import { CliError, EXIT } from './errors.js';
5
5
  import { VERSION } from './version.js';
6
6
  const REQUEST_TIMEOUT_MS = 30_000;
7
+ // Only locally written guidance may reach terminal output. Never echo server
8
+ // details, filenames or arbitrary codes from a source-export error response.
9
+ const EXPORT_GUIDANCE = {
10
+ project_template_unsupported: { status: 400, message: 'Portable export needs a supported frontend configuration. Backend-only projects can use projects export PROJECT_UUID --source-only --output ./source.zip to download source without generating or validating build configuration. This command has not changed your source.' },
11
+ committed_secret_detected: { status: 409, message: 'Source export was blocked by credential screening. Review possible credentials in your project before sharing it, and rotate any exposed values. Do not paste credentials into a support request.' },
12
+ html_package_invalid: { status: 409, message: 'Source export could not read the HTML project package configuration. Check that package.json is valid JSON and its scripts field is an object.' },
13
+ dependency_lockfile_missing: { status: 409, message: 'Source export needs package-lock.json for this HTML project. Review the project dependencies, then use its normal dependency-install workflow to create the lockfile. This command has not installed or run anything.' },
14
+ };
15
+ async function exportErrorGuidance(response) {
16
+ const limit = 8192;
17
+ if (![400, 409].includes(response.status)
18
+ || response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'application/json'
19
+ || !response.body)
20
+ return;
21
+ const length = response.headers.get('content-length');
22
+ if (length !== null && (!/^\d+$/.test(length) || Number(length) > limit))
23
+ return;
24
+ const reader = response.body.getReader();
25
+ try {
26
+ let size = 0;
27
+ const chunks = [];
28
+ while (true) {
29
+ const chunk = await reader.read();
30
+ if (chunk.done)
31
+ break;
32
+ size += chunk.value.byteLength;
33
+ if (size > limit)
34
+ return;
35
+ chunks.push(Buffer.from(chunk.value));
36
+ }
37
+ if (length !== null && Number(length) !== size)
38
+ return;
39
+ const payload = JSON.parse(Buffer.concat(chunks, size).toString('utf8'));
40
+ if (!payload || typeof payload !== 'object' || Array.isArray(payload))
41
+ return;
42
+ const code = payload.code;
43
+ if (typeof code !== 'string' || !Object.hasOwn(EXPORT_GUIDANCE, code))
44
+ return;
45
+ const guidance = EXPORT_GUIDANCE[code];
46
+ if (guidance.status === response.status)
47
+ return { code, message: guidance.message };
48
+ }
49
+ catch {
50
+ // Malformed, incomplete and failed error bodies retain the generic HTTP error.
51
+ }
52
+ finally {
53
+ await reader.cancel().catch(() => undefined);
54
+ reader.releaseLock();
55
+ }
56
+ }
7
57
  function messageFrom(payload, fallback) {
8
58
  if (payload && typeof payload === 'object') {
9
59
  const candidate = payload;
@@ -29,11 +79,15 @@ export async function publicRequest(apiOrigin, path, init = {}) {
29
79
  const controller = new AbortController();
30
80
  const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
31
81
  try {
82
+ // Headers are case-insensitive. Object-spreading normalized caller headers
83
+ // into mixed-case defaults makes fetch combine Content-Type values.
84
+ const headers = new Headers({ Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': `BlinkHost-CLI/${VERSION}` });
85
+ new Headers(init.headers).forEach((value, name) => headers.set(name, value));
32
86
  const response = await fetch(new URL(path, `${apiOrigin}/`), {
33
87
  ...init,
34
88
  redirect: 'error',
35
89
  signal: controller.signal,
36
- headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': `BlinkHost-CLI/${VERSION}`, ...Object.fromEntries(new Headers(init.headers).entries()) },
90
+ headers,
37
91
  });
38
92
  return { response, data: await parseResponse(response) };
39
93
  }
@@ -103,6 +157,79 @@ export class ApiClient {
103
157
  static fromAccessToken(profileName, profile, accessToken) {
104
158
  return new ApiClient(profileName, profile, accessToken, true);
105
159
  }
160
+ async projectArchive(projectId, mode = 'portable') {
161
+ if (!/^[a-f0-9]{8}-(?:[a-f0-9]{4}-){3}[a-f0-9]{12}$/i.test(projectId)) {
162
+ throw new CliError('A valid project UUID is required.', EXIT.usage, 'invalid_project_id');
163
+ }
164
+ if (mode !== 'portable' && mode !== 'source')
165
+ throw new CliError('Choose portable or source export mode.', EXIT.usage, 'export_mode_invalid');
166
+ const controller = new AbortController();
167
+ const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
168
+ const requestId = randomUUID();
169
+ const limit = 32 * 1024 * 1024;
170
+ let reader;
171
+ try {
172
+ const response = await fetch(new URL(`/api/source-control/connections/project-export/?project=${projectId}${mode === 'source' ? '&mode=source' : ''}`, this.profile.apiOrigin), {
173
+ method: 'GET', redirect: 'error', signal: controller.signal,
174
+ // Allow the API's JSON error renderer during content negotiation.
175
+ // Successful responses must still pass ZIP-only validation below.
176
+ headers: { Accept: 'application/zip, application/json', Authorization: `Bearer ${this.accessToken}`,
177
+ 'X-Request-ID': requestId, 'User-Agent': `BlinkHost-CLI/${VERSION}` },
178
+ });
179
+ if (!response.ok) {
180
+ const guidance = await exportErrorGuidance(response);
181
+ throw new CliError(guidance?.message || `Project export returned HTTP ${response.status}. Check your access and the project's export status in BlinkHost.`, [401, 403].includes(response.status) ? EXIT.auth : response.status === 409 ? EXIT.conflict : EXIT.remote, `api_${response.status}`, [`Request ID: ${requestId}`, ...(guidance ? [`Export reason: ${guidance.code}`] : [])]);
182
+ }
183
+ // An older API may ignore an unknown query parameter. Never silently
184
+ // save generated configuration when an exact source export was requested.
185
+ if (mode === 'source' && response.headers.get('x-blinkhost-export-mode') !== 'source') {
186
+ await response.body?.cancel().catch(() => undefined);
187
+ throw new CliError('The server did not confirm a source-only export. No archive was saved. Check server support before trying again.', EXIT.validation, 'export_mode_unconfirmed');
188
+ }
189
+ const length = response.headers.get('content-length');
190
+ if (response.status !== 200 || response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'application/zip'
191
+ || (length !== null && (!/^\d+$/.test(length) || Number(length) > limit)) || !response.body) {
192
+ throw new CliError('The export did not return a supported ZIP archive (maximum 32 MiB).', EXIT.validation, 'invalid_project_archive');
193
+ }
194
+ reader = response.body.getReader();
195
+ const chunks = [];
196
+ let size = 0;
197
+ while (true) {
198
+ const chunk = await reader.read();
199
+ if (chunk.done)
200
+ break;
201
+ size += chunk.value.byteLength;
202
+ if (size > limit)
203
+ throw new CliError('The project ZIP exceeds the CLI download limit of 32 MiB.', EXIT.validation, 'archive_too_large');
204
+ chunks.push(Buffer.from(chunk.value));
205
+ }
206
+ const body = Buffer.concat(chunks, size);
207
+ // The canonical exporter writes a single-disk ZIP without an archive
208
+ // comment. Check its closing directory record too, not just the prefix.
209
+ const end = size - 22;
210
+ if ((length !== null && Number(length) !== size) || size < 22 || !['504b0304', '504b0506'].includes(body.subarray(0, 4).toString('hex'))
211
+ || body.subarray(end, end + 4).toString('hex') !== '504b0506'
212
+ || body.readUInt16LE(end + 4) !== 0 || body.readUInt16LE(end + 6) !== 0
213
+ || body.readUInt16LE(end + 8) !== body.readUInt16LE(end + 10)
214
+ || body.readUInt16LE(end + 20) !== 0
215
+ || body.readUInt32LE(end + 12) + body.readUInt32LE(end + 16) !== end) {
216
+ throw new CliError('The export response is not a ZIP archive.', EXIT.validation, 'invalid_project_archive');
217
+ }
218
+ return body;
219
+ }
220
+ catch (error) {
221
+ if (error instanceof CliError)
222
+ throw error;
223
+ const timedOut = controller.signal.aborted;
224
+ throw new CliError(timedOut ? 'The project export timed out. No archive was saved.' : 'The project export could not be downloaded. No archive was saved.', EXIT.network, timedOut ? 'request_timeout' : 'network_error');
225
+ }
226
+ finally {
227
+ controller.abort();
228
+ if (reader)
229
+ await reader.cancel().catch(() => undefined);
230
+ clearTimeout(timeout);
231
+ }
232
+ }
106
233
  async request(path, init = {}) {
107
234
  const headers = new Headers(init.headers);
108
235
  headers.set('Authorization', `Bearer ${this.accessToken}`);
@@ -0,0 +1,7 @@
1
+ export declare function readAssistantRequest(path: string | undefined): Promise<Record<string, unknown>>;
2
+ export declare function readWorkflowPlan(path: string | undefined): Promise<Record<string, unknown>>;
3
+ export declare function readProjectGuidance(path: string | undefined): Promise<string>;
4
+ export declare function runAssistant(input: string[], profile?: string): Promise<{
5
+ message: string;
6
+ data: unknown;
7
+ }>;