@glash/cli 0.2.17 → 0.2.20

package/README.md

@@ -2,12 +2,64 @@
 
 The official command-line interface for [glashDB](https://glashdb.com).
 
+## Install
+
+Pick whichever install style you prefer — all four produce the same `glash` command:
+
+```bash
+# Short-name (recommended)
+npm install -g glashdb
+
+# Scoped package
+npm install -g @glash/cli@latest
+
+# pnpm / yarn / bun
+pnpm add -g glashdb
+yarn global add glashdb
+bun add -g glashdb
+
+# No install — run on demand
+npx -y glashdb deploy
 ```
-npm install -g @glash/cli
+
+Then:
+
+```bash
 glash login
 glash deploy
 ```
 
+### `glash: command not found`
+
+If npm says the install completed but your shell can't find `glash`, your npm
+global `bin` folder isn't on `PATH`. Fix it once:
+
+```bash
+npm list -g glashdb --depth=0          # confirm install
+ls -la "$(npm prefix -g)/bin/glash"  # confirm bin exists
+echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+hash -r
+glash --version
+```
+
+On macOS with Homebrew Node, the global prefix is usually
+`/opt/homebrew/bin` (Apple Silicon) or `/usr/local/bin` (Intel) — both are
+typically already on `PATH`. With `nvm`, re-run `nvm use` in new shells or
+add `nvm use --default` to your shell init.
+
+### EACCES / permission errors
+
+Don't `sudo npm install -g`. Instead, point npm at a user-owned prefix:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+npm install -g glashdb
+```
+
 ## Commands
 
 | Command | Purpose |

package/commands/deploy.mjs

@@ -224,10 +224,17 @@ export async function deploy({ flags }) {
       ok(`Live${url ? ` → ${color.cyan(`https://${url.replace(/^https?:\/\//, '')}`)}` : ''}`);
       return;
     }
+    if (status === 'placeholder') {
+      indicator.stop();
+      const lastPlaceholder = [...(pipe.events ?? [])].reverse().find((ev) => ev.status === 'placeholder' || ev.step === 'deploy');
+      const detail = lastPlaceholder?.message ? `: ${lastPlaceholder.message}` : '';
+      return fail(`Deployment reached the glashDB parked page, not your app${detail}. Run \`glash logs ${dep.id}\` for details.`);
+    }
     if (['error', 'failed'].includes(status)) {
       indicator.stop();
       const lastError = [...(pipe.events ?? [])].reverse().find((ev) => ev.status === 'error' || ev.status === 'failed');
-      const detail = lastError?.message ? `: ${lastError.message}` : '';
+      const rawDetail = lastError?.message ? `: ${lastError.message}` : '';
+      const detail = `${rawDetail}${deploymentFailureHint(lastError?.message)}`;
       return fail(`Deployment failed (${status})${detail}. Run \`glash logs ${dep.id}\` for details.`);
     }
     currentPhase = phaseFromPipeline(pipe, currentPhase);
@@ -351,6 +358,16 @@ function phaseFromPipeline(pipe, fallback) {
   return last ? phaseFromEvent(last) : fallback;
 }
 
+function deploymentFailureHint(message = '') {
+  if (/agent .*timeout|agent .*ECONN|host-agent|No healthy host-agent|Waiting for a healthy build host/i.test(message)) {
+    return `\n${color.yellow('glashDB build host issue:')} your source uploaded, but the platform host agent was unavailable. Re-run \`glash deploy\`; glashDB will skip unhealthy hosts or use the SSH build worker when configured.`;
+  }
+  if (/GLASH_BUILD_SSH_KEY|Permission denied|invalid format|libcrypto/i.test(message)) {
+    return `\n${color.yellow('glashDB build worker issue:')} the platform SSH build worker rejected its key. This is not an app-code error.`;
+  }
+  return '';
+}
+
 function createDeployIndicator({ start, getPhase }) {
   const interactive = Boolean(stdout.isTTY);
   let frame = 0;

package/lib/api.mjs

@@ -19,7 +19,25 @@ function retryAfterMs(headers) {
   return undefined;
 }
 
-export async function api(method, path, { body, token, query } = {}) {
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Transient HTTP statuses worth retrying. These mean the request almost
+// certainly never reached app logic (gateway/edge hiccup, cold start,
+// rate-limit), so retrying is safe even for non-idempotent POSTs and is the
+// main reason `glash deploy` survives flaky networks, VPNs and corporate
+// proxies across machines.
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504, 522, 524]);
+const DEFAULT_RETRIES = 4;
+
+function backoffMs(attempt, retryAfter) {
+  if (retryAfter && Number.isFinite(retryAfter)) return Math.min(Math.max(retryAfter, 1000), 60000);
+  // Exponential backoff with jitter: ~1s, 2s, 4s, 8s (+/- 30%), capped at 30s.
+  const base = Math.min(1000 * 2 ** attempt, 30000);
+  const jitter = base * (0.7 + Math.random() * 0.6);
+  return Math.round(jitter);
+}
+
+export async function api(method, path, { body, token, query, retries = DEFAULT_RETRIES, signal } = {}) {
   const headers = {
     Accept: 'application/json',
     'User-Agent': `glash-cli/${VERSION}`,
@@ -27,7 +45,8 @@ export async function api(method, path, { body, token, query } = {}) {
   };
   const t = token ?? (await getToken());
   if (t) headers.Authorization = `Bearer ${t}`;
-  if (body !== undefined && !(body instanceof FormData)) {
+  const isForm = body instanceof FormData;
+  if (body !== undefined && !isForm) {
     headers['Content-Type'] = 'application/json';
   }
 
@@ -39,35 +58,55 @@ export async function api(method, path, { body, token, query } = {}) {
     if (qs) url += (url.includes('?') ? '&' : '?') + qs;
   }
 
-  let res;
-  try {
-    res = await fetch(url, {
-      method,
-      headers,
-      body: body instanceof FormData ? body : (body === undefined ? undefined : JSON.stringify(body)),
-    });
-  } catch (e) {
-    const detail = e?.cause?.message || e?.message || String(e);
-    throw new GlashApiError(0, `Network request failed while calling ${method} ${path}: ${detail}`);
-  }
+  // FormData bodies carry file Blobs backed by the on-disk zip, so they are
+  // re-streamable — fetch reads them fresh on each attempt, which lets us
+  // retry uploads without re-zipping.
+  const requestBody = isForm ? body : (body === undefined ? undefined : JSON.stringify(body));
 
-  if (!res.ok) {
-    let message = `HTTP ${res.status}`;
+  let attempt = 0;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    let res;
     try {
-      const data = await res.json();
-      if (typeof data?.message === 'string') message = data.message;
-      else if (Array.isArray(data?.message)) message = data.message.join(', ');
-    } catch {}
-    if (res.status === 401 && !path.includes('/auth/login') && !path.includes('/auth/cli/login')) {
-      message = `${message}. Run \`glash login\` again, then retry the command.`;
+      res = await fetch(url, { method, headers, body: requestBody, signal });
+    } catch (e) {
+      if (signal?.aborted) throw e;
+      const detail = e?.cause?.message || e?.message || String(e);
+      // Network-level failure: the request did not complete, so retrying is
+      // always safe. This covers DNS, TLS, connection-reset and timeout errors.
+      if (attempt < retries) {
+        await sleep(backoffMs(attempt));
+        attempt += 1;
+        continue;
+      }
+      throw new GlashApiError(0, `Network request failed while calling ${method} ${path}: ${detail}`);
+    }
+
+    if (!res.ok) {
+      const retryAfter = retryAfterMs(res.headers);
+      if (RETRYABLE_STATUS.has(res.status) && attempt < retries) {
+        await res.body?.cancel?.().catch(() => {});
+        await sleep(backoffMs(attempt, retryAfter));
+        attempt += 1;
+        continue;
+      }
+      let message = `HTTP ${res.status}`;
+      try {
+        const data = await res.json();
+        if (typeof data?.message === 'string') message = data.message;
+        else if (Array.isArray(data?.message)) message = data.message.join(', ');
+      } catch {}
+      if (res.status === 401 && !path.includes('/auth/login') && !path.includes('/auth/cli/login')) {
+        message = `${message}. Run \`glash login\` again, then retry the command.`;
+      }
+      throw new GlashApiError(res.status, message, { retryAfterMs: retryAfter });
     }
-    throw new GlashApiError(res.status, message, { retryAfterMs: retryAfterMs(res.headers) });
-  }
 
-  if (res.status === 204) return undefined;
-  const text = await res.text();
-  if (!text) return undefined;
-  try { return JSON.parse(text); } catch { return text; }
+    if (res.status === 204) return undefined;
+    const text = await res.text();
+    if (!text) return undefined;
+    try { return JSON.parse(text); } catch { return text; }
+  }
 }
 
 export const apiGet = (p, opts) => api('GET', p, opts);

package/lib/version.mjs

@@ -1 +1 @@
-export const VERSION = '0.2.17';
+export const VERSION = '0.2.20';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glash/cli",
-  "version": "0.2.17",
+  "version": "0.2.20",
   "description": "glashDB command-line interface — deploy projects, pull source + env, manage env vars.",
   "license": "Apache-2.0",
   "homepage": "https://glashdb.com",