@blinkhost/cli 2.5.0 → 2.5.2

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,32 @@
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.2 — Deployment request recovery
6
+
7
+ Activate, promote, retry and rollback now require a saved `--idempotency-key`.
8
+ After a timeout, `deployments publication-lookup --idempotency-key KEY` reads
9
+ the original request using the same account and profile. Known operations can
10
+ be inspected with `deployments publication-status OPERATION_ID`. Neither
11
+ recovery command resubmits work. Preserve the original key when a response is
12
+ lost; a new key represents a new request.
13
+
14
+ These commands require a control plane with deployment publication support.
15
+ Update deployment scripts to supply the key before upgrading. Publication
16
+ success confirms the control-plane commit; `result_status` and
17
+ `result_is_current` describe propagation and current routing separately.
18
+ Workspace permissions, approvals and Idam limited-preview policy still apply.
19
+
20
+ ## 2.5.1 — Saved-session concurrency
21
+
22
+ Commands sharing a saved profile now serialize credential refresh and sign-out.
23
+ This prevents concurrent CLI processes from reusing a rotated refresh credential
24
+ and revoking the session. Sign-in verifies the new session using its original
25
+ access token, and temporary refresh errors preserve the saved credential.
26
+
27
+ If a command exits unexpectedly while holding the sign-in lock, the CLI reports
28
+ the lock path. Confirm that no command for that profile is running before
29
+ removing that file. Idam remains limited preview; workspace policy is unchanged.
30
+
5
31
  ## 2.5.0 — Idam limited preview
6
32
 
7
33
  This release adds Idam commands for eligible accounts on an enabled control plane.
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.5.0
10
+ npm install --global @blinkhost/cli@2.5.2
11
11
  blinkhost --version
12
12
  ```
13
13
 
@@ -15,6 +15,25 @@ Signed release archives, checksums, the CycloneDX SBOM, and Sigstore verificatio
15
15
 
16
16
  ## Current release
17
17
 
18
+ ### 2.5.2 — deployment request recovery
19
+
20
+ Activate, promote, retry and rollback require a saved `--idempotency-key`.
21
+ Update scripts to supply a key before upgrading. These commands require a
22
+ control plane with deployment publication support; recovery reads the original
23
+ request after a timeout without submitting another deployment. Keep the same
24
+ account, profile and key while recovering. Workspace permissions and approvals
25
+ still apply.
26
+
27
+ ### 2.5.1 — saved-session concurrency
28
+
29
+ Commands sharing a saved profile serialize credential refresh and sign-out so
30
+ concurrent processes do not reuse a rotated credential. Temporary refresh
31
+ failures preserve the saved credential; rejected sessions still require a fresh
32
+ sign-in. Explicit environment credentials remain the caller's responsibility.
33
+ If a command reports `credential_busy`, let the other command finish. After a
34
+ crash, confirm that no command for that profile is running before removing the
35
+ reported lock file. The file contains process metadata, never credentials.
36
+
18
37
  ### 2.5.0 — Idam limited preview
19
38
 
20
39
  - Added Idam task, source-review, starter, build, export and connected-review commands.
@@ -337,9 +356,24 @@ Create and update operations accept a JSON object or `@path` to a JSON file:
337
356
 
338
357
  ```bash
339
358
  blinkhost projects create --data @project.json
340
- blinkhost deployments action DEPLOYMENT_ID rollback --data @rollback.json
359
+ blinkhost deployments action DEPLOYMENT_ID rollback --data @rollback.json --idempotency-key SAVED_REQUEST_KEY
341
360
  ```
342
361
 
362
+ For activate, promote, retry and rollback, save a unique request key before the
363
+ first command. Keys accept 8–128 letters, digits, dots, underscores, colons or
364
+ hyphens. If the response is lost, use the same account and profile to inspect
365
+ the original request:
366
+
367
+ ```bash
368
+ blinkhost deployments publication-lookup --idempotency-key SAVED_REQUEST_KEY
369
+ blinkhost deployments publication-status OPERATION_ID
370
+ ```
371
+
372
+ These recovery commands only read status. A new key starts a separate request;
373
+ do not replace a key because of a timeout. Publication success confirms the
374
+ control-plane commit. Inspect `result_status` and `result_is_current` to check
375
+ release propagation and current routing.
376
+
343
377
  Destructive operations require the exact resource ID twice:
344
378
 
345
379
  ```bash
@@ -426,7 +460,7 @@ Pin or roll back explicitly with `npm install --global @blinkhost/cli@VERSION`.
426
460
  ```bash
427
461
  cosign verify-blob \
428
462
  --bundle SHA256SUMS.sigstore.json \
429
- --certificate-identity "https://github.com/blinkhost-ltd/blinkhost-cli/.github/workflows/release.yml@refs/tags/v2.5.0" \
463
+ --certificate-identity "https://github.com/blinkhost-ltd/blinkhost-cli/.github/workflows/release.yml@refs/tags/v2.5.2" \
430
464
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
431
465
  SHA256SUMS
432
466
  ```
package/dist/api.d.ts CHANGED
@@ -10,6 +10,10 @@ export declare class ApiClient {
10
10
  private accessToken;
11
11
  private constructor();
12
12
  static create(profileName?: string): Promise<ApiClient>;
13
+ private static refresh;
14
+ static logout(profileName?: string): Promise<{
15
+ profile: string;
16
+ }>;
13
17
  static fromAccessToken(profileName: string, profile: Profile, accessToken: string): ApiClient;
14
18
  projectArchive(projectId: string, mode?: 'portable' | 'source'): Promise<Buffer>;
15
19
  request(path: string, init?: RequestInit): Promise<unknown>;
package/dist/api.js CHANGED
@@ -1,6 +1,8 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
  import { activeProfile, writeConfig } from './config.js';
3
3
  import { deleteRefreshCredential, getRefreshCredential, setRefreshCredential } from './credentials.js';
4
+ import { withCredentialLock } from './credential-lock.js';
5
+ import { validateDeviceTokens } from './device-flow.js';
4
6
  import { CliError, EXIT } from './errors.js';
5
7
  import { VERSION } from './version.js';
6
8
  const REQUEST_TIMEOUT_MS = 30_000;
@@ -140,20 +142,51 @@ export class ApiClient {
140
142
  throw new CliError(payload.detail || 'BlinkHost rejected this workload identity.', EXIT.auth, 'ci_exchange_failed');
141
143
  return new ApiClient(selected.name, selected.profile, payload.access_token, true);
142
144
  }
145
+ if (process.env.BLINKHOST_REFRESH_TOKEN)
146
+ return ApiClient.refresh(selected);
147
+ return withCredentialLock(selected.name, () => ApiClient.refresh(selected));
148
+ }
149
+ // Caller holds the profile lock for saved credentials. Explicit environment
150
+ // credentials remain caller-managed and are never persisted or removed.
151
+ static async refresh(selected) {
143
152
  const refresh = process.env.BLINKHOST_REFRESH_TOKEN || await getRefreshCredential(selected.name);
144
153
  if (!refresh)
145
154
  throw new CliError('Sign in with `blinkhost auth login` or provide BLINKHOST_ACCESS_TOKEN for CI.', EXIT.auth, 'not_authenticated');
146
155
  const result = await publicRequest(selected.profile.apiOrigin, '/api/cli/v2/token/refresh/', { method: 'POST', body: JSON.stringify({ refresh_token: refresh, client_version: VERSION }) });
147
156
  if (!result.response.ok) {
148
- if (!process.env.BLINKHOST_REFRESH_TOKEN)
149
- await deleteRefreshCredential(selected.name);
150
- throw new CliError(messageFrom(result.data, 'Your CLI session has expired. Sign in again.'), EXIT.auth, 'session_expired');
157
+ if (result.response.status === 401) {
158
+ if (!process.env.BLINKHOST_REFRESH_TOKEN)
159
+ await deleteRefreshCredential(selected.name);
160
+ throw new CliError(messageFrom(result.data, 'Your CLI session has expired. Sign in again.'), EXIT.auth, 'session_expired');
161
+ }
162
+ throw new CliError('BlinkHost could not refresh this session. The saved credential was preserved.', EXIT.network, 'session_refresh_failed');
151
163
  }
152
- const tokens = result.data;
164
+ const tokens = validateDeviceTokens(result.data);
153
165
  if (!process.env.BLINKHOST_REFRESH_TOKEN)
154
166
  await setRefreshCredential(selected.name, tokens.refresh_token);
155
167
  return new ApiClient(selected.name, selected.profile, tokens.access_token, Boolean(process.env.BLINKHOST_REFRESH_TOKEN));
156
168
  }
169
+ static async logout(profileName) {
170
+ const selected = await activeProfile(profileName);
171
+ if (process.env.BLINKHOST_ACCESS_TOKEN || process.env.BLINKHOST_REFRESH_TOKEN
172
+ || (process.env.ACTIONS_ID_TOKEN_REQUEST_URL && process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN)) {
173
+ const client = await ApiClient.create(selected.name);
174
+ await client.request('/api/cli/v2/sessions/current/', { method: 'DELETE' });
175
+ return { profile: selected.name };
176
+ }
177
+ return withCredentialLock(selected.name, async () => {
178
+ try {
179
+ const client = await ApiClient.refresh(selected);
180
+ await client.request('/api/cli/v2/sessions/current/', { method: 'DELETE' });
181
+ }
182
+ catch (error) {
183
+ if (!(error instanceof CliError) || error.code !== 'session_expired')
184
+ throw error;
185
+ }
186
+ await deleteRefreshCredential(selected.name);
187
+ return { profile: selected.name };
188
+ });
189
+ }
157
190
  static fromAccessToken(profileName, profile, accessToken) {
158
191
  return new ApiClient(profileName, profile, accessToken, true);
159
192
  }
package/dist/auth.js CHANGED
@@ -2,7 +2,8 @@ import { createHash, randomBytes } from 'node:crypto';
2
2
  import { hostname } from 'node:os';
3
3
  import { spawn } from 'node:child_process';
4
4
  import { activeProfile, validateApiOrigin, validateProfileName, writeConfig } from './config.js';
5
- import { credentialStoreStatus, deleteRefreshCredential, setRefreshCredential } from './credentials.js';
5
+ import { credentialStoreStatus, setRefreshCredential } from './credentials.js';
6
+ import { withCredentialLock } from './credential-lock.js';
6
7
  import { ApiClient, publicRequest } from './api.js';
7
8
  import { CliError, EXIT } from './errors.js';
8
9
  import { VERSION } from './version.js';
@@ -43,26 +44,21 @@ export async function login(options) {
43
44
  if (options.openBrowser !== false)
44
45
  openBrowser(device.verification_uri_complete);
45
46
  const tokens = validateDeviceTokens(await pollDeviceAuthorization(apiOrigin, device, verifier));
46
- await setRefreshCredential(profileName, tokens.refresh_token);
47
- selected.config.profiles[profileName] = { apiOrigin };
48
- selected.config.activeProfile = profileName;
49
- await writeConfig(selected.config);
50
- const client = await ApiClient.create(profileName);
51
- const capabilities = await client.request('/api/cli/v2/capabilities/');
52
- await client.rememberIdentity(capabilities.actor || {});
53
- return { profile: profileName, api_origin: apiOrigin, account: capabilities.actor, permissions: capabilities.features };
47
+ return withCredentialLock(profileName, async () => {
48
+ await setRefreshCredential(profileName, tokens.refresh_token);
49
+ selected.config.profiles[profileName] = { apiOrigin };
50
+ selected.config.activeProfile = profileName;
51
+ await writeConfig(selected.config);
52
+ const client = ApiClient.fromAccessToken(profileName, { apiOrigin }, tokens.access_token);
53
+ const capabilities = await client.request('/api/cli/v2/capabilities/');
54
+ selected.config.profiles[profileName] = { apiOrigin,
55
+ ...(capabilities.actor?.id ? { userId: capabilities.actor.id } : {}),
56
+ ...(capabilities.actor?.username ? { username: capabilities.actor.username } : {}) };
57
+ await writeConfig(selected.config);
58
+ return { profile: profileName, api_origin: apiOrigin, account: capabilities.actor, permissions: capabilities.features };
59
+ });
54
60
  }
55
61
  export async function logout(profile) {
56
- const selected = await activeProfile(profile);
57
- try {
58
- const client = await ApiClient.create(selected.name);
59
- await client.request('/api/cli/v2/sessions/current/', { method: 'DELETE' });
60
- }
61
- catch (error) {
62
- if (!(error instanceof CliError) || error.code !== 'session_expired')
63
- throw error;
64
- }
65
- await deleteRefreshCredential(selected.name);
66
- return { profile: selected.name };
62
+ return ApiClient.logout(profile);
67
63
  }
68
64
  //# sourceMappingURL=auth.js.map
@@ -0,0 +1,3 @@
1
+ export declare function credentialLockPath(profile: string): string;
2
+ /** Serialize the complete read/rotate/save operation across CLI processes. */
3
+ export declare function withCredentialLock<T>(profile: string, operation: () => Promise<T>, timeoutMs?: number): Promise<T>;
@@ -0,0 +1,52 @@
1
+ import { mkdir, open, unlink } from 'node:fs/promises';
2
+ import { homedir } from 'node:os';
3
+ import { join } from 'node:path';
4
+ import { setTimeout as delay } from 'node:timers/promises';
5
+ import { validateProfileName } from './config.js';
6
+ import { CliError, EXIT } from './errors.js';
7
+ // The OS credential store keys by profile, independently of CONFIG_HOME and
8
+ // API origin. Commands using different config files must therefore share locks.
9
+ export function credentialLockPath(profile) {
10
+ return join(homedir(), '.blinkhost', 'credential-locks', `${validateProfileName(profile)}.lock`);
11
+ }
12
+ /** Serialize the complete read/rotate/save operation across CLI processes. */
13
+ export async function withCredentialLock(profile, operation, timeoutMs = 45_000) {
14
+ const path = credentialLockPath(profile);
15
+ const directory = join(homedir(), '.blinkhost', 'credential-locks');
16
+ if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 45_000) {
17
+ throw new CliError('The CLI credential lock timeout is invalid.', EXIT.internal, 'credential_lock_invalid');
18
+ }
19
+ try {
20
+ await mkdir(directory, { recursive: true, mode: 0o700 });
21
+ }
22
+ catch {
23
+ throw new CliError('The CLI credential lock directory is unavailable.', EXIT.filesystem, 'credential_lock_failed');
24
+ }
25
+ const deadline = performance.now() + timeoutMs;
26
+ let handle;
27
+ while (!handle) {
28
+ try {
29
+ handle = await open(path, 'wx', 0o600);
30
+ }
31
+ catch (error) {
32
+ if (error.code !== 'EEXIST') {
33
+ throw new CliError('The CLI credential lock is unavailable.', EXIT.filesystem, 'credential_lock_failed');
34
+ }
35
+ if (performance.now() >= deadline) {
36
+ // Never steal an old lock based on time alone: a suspended process may
37
+ // still rotate the credential when it resumes. This file has no secrets.
38
+ throw new CliError('Another CLI command holds this profile’s sign-in lock. Let it finish and retry. If it exited unexpectedly, confirm no CLI command is running before removing the lock file.', EXIT.conflict, 'credential_busy', [path]);
39
+ }
40
+ await delay(Math.min(50, Math.max(1, deadline - performance.now())));
41
+ }
42
+ }
43
+ try {
44
+ await handle.writeFile(JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }) + '\n');
45
+ return await operation();
46
+ }
47
+ finally {
48
+ await handle.close();
49
+ await unlink(path);
50
+ }
51
+ }
52
+ //# sourceMappingURL=credential-lock.js.map
package/dist/guidance.js CHANGED
@@ -141,7 +141,11 @@ const TOPICS = {
141
141
  connections: resource('connections', 'Manage project-to-repository source connections.'),
142
142
  previews: resource('previews', 'Manage temporary preview environments.', ['`previews wait ID [--timeout 10..3600]` waits for a terminal state. `previews open ID` accepts only trusted BlinkHost HTTPS preview hosts. Preview operations can consume plan resources.']),
143
143
  builds: resource('builds', 'Create, inspect and wait for verified builds.', ['`builds wait ID [--timeout 10..3600]` stops on success, failure, cancellation, expiry or timeout. Builds can consume plan resources.']),
144
- deployments: resource('deployments', 'Manage production deployments and protected release actions.', ['Rollback uses `deployments action DEPLOYMENT_ID rollback --data @rollback.json`. Protected environments can require approval and a verified artifact. Deployment operations can consume plan resources.']),
144
+ deployments: resource('deployments', 'Manage production deployments and protected release actions.', [
145
+ 'Activate, promote, retry and rollback require a saved request key: `deployments action DEPLOYMENT_ID rollback --idempotency-key KEY`. Use 8–128 letters, digits, dots, underscores, colons or hyphens. A new key means a new request.',
146
+ 'After a timeout, use `deployments publication-lookup --idempotency-key KEY` with the same account and profile. Inspect a known operation with `deployments publication-status OPERATION_ID`. Keep the original key when recovering a request; these commands never resubmit it.',
147
+ 'Publication success confirms the control-plane commit. Check result_status and result_is_current to establish release propagation and current routing. Protected environments can require approval and a verified artifact. Deployment operations can consume plan resources.',
148
+ ]),
145
149
  modules: resource('modules', 'Manage Rust, Go, Python, JavaScript and TypeScript Functions.'),
146
150
  functions: {
147
151
  name: 'functions', title: 'Function triggers and runs', summary: 'Manage beta event, schedule and background triggers with explicit retry and idempotency controls.',
package/dist/remote.js CHANGED
@@ -63,6 +63,12 @@ function validIdempotencyKey(value) {
63
63
  throw new CliError('Idempotency keys must be from 1 to 256 bytes and cannot contain control characters.', EXIT.usage, 'invalid_idempotency_key');
64
64
  return value;
65
65
  }
66
+ function publicationKey(value) {
67
+ if (!value || !/^[A-Za-z0-9._:-]{8,128}$/.test(value)) {
68
+ throw new CliError('Publication requires --idempotency-key KEY: 8–128 letters, digits, dots, underscores, colons or hyphens. Save this key to recover the same request after a timeout.', EXIT.usage, 'publication_key_required');
69
+ }
70
+ return value;
71
+ }
66
72
  async function readPayload(value) {
67
73
  if (!value)
68
74
  return {};
@@ -109,9 +115,27 @@ export async function runRemote(group, input, profile) {
109
115
  const project = takeOption(args, '--project');
110
116
  const query = takeRepeated(args, '--query');
111
117
  const dataOption = takeOption(args, '--data');
118
+ const publicationKeyOption = group === 'deployments' && ['action', 'publication-lookup'].includes(action)
119
+ ? takeOption(args, '--idempotency-key') : undefined;
120
+ const isPublication = group === 'deployments' && action === 'action'
121
+ && ['activate', 'promote', 'retry', 'rollback'].includes(args[1] || '');
122
+ const key = isPublication || (group === 'deployments' && action === 'publication-lookup')
123
+ ? publicationKey(publicationKeyOption) : undefined;
124
+ if (publicationKeyOption !== undefined && key === undefined) {
125
+ throw new CliError('--idempotency-key is supported here only for activate, promote, retry and rollback.', EXIT.usage, 'unexpected_argument');
126
+ }
112
127
  const client = await ApiClient.create(profile);
113
128
  const base = collectionPath(group, project);
114
129
  const data = await readPayload(dataOption);
130
+ if (group === 'deployments' && ['publication-status', 'publication-lookup'].includes(action)) {
131
+ if (query.length || dataOption || project)
132
+ throw new CliError('Publication recovery accepts only its operation ID or original idempotency key.', EXIT.usage, 'unexpected_argument');
133
+ const path = action === 'publication-status'
134
+ ? `/api/deployment-publications/${safeIdentifier(args.shift(), 'Operation ID')}/`
135
+ : '/api/deployment-publications/lookup/';
136
+ noExtra(args);
137
+ return client.request(path, key ? { headers: { 'Idempotency-Key': key } } : {});
138
+ }
115
139
  if (action === 'list') {
116
140
  noExtra(args);
117
141
  return client.request(`${base}${queryString(query)}`);
@@ -143,6 +167,24 @@ export async function runRemote(group, input, profile) {
143
167
  const id = safeIdentifier(args.shift());
144
168
  const operation = safeIdentifier(args.shift(), 'Action');
145
169
  noExtra(args);
170
+ if (isPublication && key) {
171
+ try {
172
+ const result = await client.request(`${base}${id}/${operation}/`, {
173
+ method: 'POST', body: JSON.stringify(data), headers: { 'Idempotency-Key': key },
174
+ });
175
+ return { ...result, idempotency_key: key };
176
+ }
177
+ catch (error) {
178
+ if (error instanceof CliError) {
179
+ throw new CliError(error.message, error.exitCode, error.code, [...error.details,
180
+ `Publication key: ${key}`,
181
+ `Check with the same account and profile: blinkhost deployments publication-lookup --idempotency-key ${key}`,
182
+ 'A timeout or server error may follow a committed request. Keep the original key; do not submit a replacement request.',
183
+ ]);
184
+ }
185
+ throw error;
186
+ }
187
+ }
146
188
  return client.request(`${base}${id}/${operation}/`, { method: 'POST', body: JSON.stringify(data) });
147
189
  }
148
190
  throw new CliError(`Unknown ${group} action: ${action}.`, EXIT.usage, 'unknown_action');
package/dist/version.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- export declare const VERSION = "2.5.0";
1
+ export declare const VERSION = "2.5.2";
2
2
  export declare const DOCUMENTATION_URL = "https://app.blinkhost.me/docs/source-control/cli";
3
3
  export declare const RELEASES_URL = "https://github.com/blinkhost-ltd/blinkhost-cli/releases";
4
4
  export declare function supportedNodeVersion(version?: string): boolean;
package/dist/version.js CHANGED
@@ -1,4 +1,4 @@
1
- export const VERSION = '2.5.0';
1
+ export const VERSION = '2.5.2';
2
2
  export const DOCUMENTATION_URL = 'https://app.blinkhost.me/docs/source-control/cli';
3
3
  export const RELEASES_URL = 'https://github.com/blinkhost-ltd/blinkhost-cli/releases';
4
4
  export function supportedNodeVersion(version = process.versions.node) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blinkhost/cli",
3
- "version": "2.5.0",
3
+ "version": "2.5.2",
4
4
  "description": "Secure local and remote developer workflows for BlinkHost",
5
5
  "keywords": ["blinkhost", "deployment", "hosting", "cloud", "cli", "developer-tools"],
6
6
  "homepage": "https://app.blinkhost.me/docs/source-control/cli",