hostedge 0.1.1 → 0.1.3

package/README.md

@@ -1,48 +1,106 @@
-# hostedge CLI
+# hostedge
 
-Deploy a folder to HostEdge from your terminal.
+**Hosting your AI agent can use.** The HostEdge command line deploys websites and apps to a global edge network, reads logs, and manages environment variables. It works the same for people at a terminal, in CI, and for AI agents such as Claude Code, Cursor and Codex.
 
-Install once with `npm install --global hostedge` (or `curl -fsSL https://hostedge.app/install.sh | sh`), or run it with `npx`:
+- Site: https://hostedge.app
+- Docs: https://hostedge.app/docs/cli
+- Free plan: 3 projects, no card
+
+## Quick start
+
+```sh
+npx hostedge login     # opens your browser and signs you in
+npx hostedge deploy    # uploads your project, shows the build, prints the live URL
+```
+
+That is all. Run it in the folder that holds your site (a built `dist` or `out` folder, or the project itself). The first deploy creates the project and links it; later deploys only upload what changed.
+
+Install it once if you prefer a short command:
+
+```sh
+npm install --global hostedge     # then: hostedge deploy
+```
+
+Requires Node 20.11 or newer.
+
+## Let your AI agent do it
+
+There are two ways. Use either or both.
+
+**1. Teach the agent HostEdge (no setup in the dashboard):**
+
+```sh
+npx hostedge init --ai
+```
+
+This writes `AGENTS.md`, `CLAUDE.md`, a Cursor rule and a Claude Code skill into your project. Your agent then knows how to build for HostEdge, deploy, read logs and roll back.
+
+**2. Connect it over MCP** and just ask ("deploy this and check the logs"):
 
 ```sh
-npx hostedge login      # opens your browser; or: hostedge login --token hostedge_…
-npx hostedge deploy     # uploads changed files, streams the build log, prints the URL
+claude mcp add --transport http hostedge https://hostedge.app/api/mcp
 ```
 
+For Cursor, Windsurf and other clients, add `https://hostedge.app/api/mcp` as a remote MCP server. Details: https://hostedge.app/docs/ai-assistants
+
+### For agents: what to know
+
+- Every command takes `--json` (machine output on stdout, human text on stderr), `--yes` (never prompt) and `--quiet`. With `CI=1` or no TTY it never prompts.
+- Authenticate with the `HOSTEDGE_TOKEN` environment variable (create one in Settings, API tokens, scope `deployments:write`) or `hostedge login --token <token>`.
+- `hostedge deploy --wait --json` prints `{ "deploymentId", "status", "url", "failureReason", ... }` and exits `5` if the build fails.
+- `hostedge logs --json` prints one JSON object per line.
+- Exit codes are stable, see the table below.
+
+## Commands
+
 | Command | What it does |
 | --- | --- |
-| `hostedge login [--token <t> \| --with-token] [--api-url <url>]` | Signs in. The browser flow creates a 90-day token scoped to the CLI; `--with-token` reads the token from stdin. |
-| `hostedge logout` | Forgets the saved token (revoke it in Settings → API tokens). |
-| `hostedge whoami` | Shows the account, workspace and scopes in use. |
-| `hostedge ai-kit [dir] [--force]` | Writes `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/hostedge.mdc` and `.claude/skills/hostedge/SKILL.md` (never overwrites without `--force`). |
-| `hostedge init [dir] [--name] [--project <id\|slug>] [--ai]` | Links a folder to a new or existing project (`.hostedge/project.json`); `--ai` also writes the agent kit. |
-| `hostedge deploy [dir] [--preview] [-m <message>] [--no-wait]` | Deploys; links the folder on first deploy. Exits 5 if the build fails. |
-| `hostedge logs [-f] [--level <l>] [--search <text>] [--since 30m\|1h\|24h\|7d]` | Runtime logs, oldest first; `-f` follows. |
-| `hostedge env pull [-e <environment>] [--file <path>]` | Writes variables to `.env.local` (0600, added to `.gitignore`). |
-
-For scripts and AI agents every command accepts `--json` (JSON on stdout, human text on
-stderr), `--yes` (never prompt; `CI=1` or no TTY also disables prompts), `--quiet`,
-`--api-url <url>` and `--no-color` (`NO_COLOR` is respected). `hostedge deploy --wait --json`
-prints `{deploymentId,status,url,failureReason,…}` and exits 5 if the build fails;
-`hostedge logs --json` prints one JSON object per line.
-
-| Exit code | Meaning |
+| `hostedge login [--token <t> \| --with-token] [--api-url <url>]` | Sign in. The browser flow creates a 90-day token limited to the CLI. `--with-token` reads the token from stdin. |
+| `hostedge logout` | Forget the saved token (revoke it in Settings, API tokens). |
+| `hostedge whoami` | Show the account, workspace and scopes in use. |
+| `hostedge init [dir] [--name] [--project <id\|slug>] [--ai]` | Link a folder to a new or existing project. `--ai` also writes the agent kit. |
+| `hostedge deploy [dir] [--preview] [-m <message>] [--no-wait]` | Deploy. Links the folder on first use. Exits `5` if the build fails. |
+| `hostedge logs [-f] [--level <l>] [--search <text>] [--since 30m\|1h\|24h\|7d]` | Runtime logs, oldest first. `-f` follows. |
+| `hostedge env pull [-e <environment>] [--file <path>]` | Write variables to `.env.local` (private file, added to `.gitignore`). |
+| `hostedge ai-kit [dir] [--force]` | Write the agent files only. Never overwrites without `--force`. |
+
+Global flags: `--json`, `--yes`, `--quiet`, `--api-url <url>`, `--no-color` (`NO_COLOR` is respected).
+
+## Exit codes
+
+| Code | Meaning |
 | --- | --- |
-| 0 | ok |
-| 1 | generic failure |
-| 2 | usage error |
-| 3 | auth error (not signed in, token invalid or missing a scope) |
-| 4 | not found (project, deployment, folder not linked) |
-| 5 | deployment failed or was canceled |
-| 6 | plan limit reached |
-
-In CI, set `HOSTEDGE_TOKEN` (create one in Settings → API tokens with the `deployments:write`
-scope) and run `npx hostedge deploy`. `HOSTEDGE_API_URL` points the CLI at another HostEdge
-(e.g. `http://localhost:3000` in development).
-
-The CLI follows the dashboard's upload rules: `.git`, `node_modules` and similar folders are
-skipped, secret-looking files (`.env*`, keys) are left behind, and symbolic links are refused.
-Only files HostEdge doesn't already have are uploaded.
-
-Development: `pnpm --filter hostedge build` bundles `dist/hostedge.js` (no runtime
-dependencies); `pnpm --filter hostedge test` runs the commands against a fake API.
+| 0 | OK |
+| 1 | Generic failure |
+| 2 | Usage error (bad flag or argument) |
+| 3 | Auth error: not signed in, token invalid, or missing a scope |
+| 4 | Not found: project, deployment, or folder not linked |
+| 5 | Deployment failed or was canceled |
+| 6 | Plan limit reached |
+
+## CI
+
+```yaml
+- run: npx hostedge deploy --yes
+  env:
+    HOSTEDGE_TOKEN: ${{ secrets.HOSTEDGE_TOKEN }}
+```
+
+`HOSTEDGE_API_URL` points the CLI at another HostEdge, for example `http://localhost:3000` in development.
+
+## What gets uploaded
+
+The CLI follows the same rules as the dashboard. `.git`, `node_modules` and similar folders are skipped. Files that look like secrets (`.env*`, private keys) are left behind. Symbolic links are refused. Only files HostEdge does not already have are uploaded, in batches, with progress and automatic retries.
+
+## Troubleshooting
+
+- **"Not signed in" (exit 3):** run `npx hostedge login`, or set `HOSTEDGE_TOKEN`.
+- **"Not linked" (exit 4):** run `npx hostedge init` in the project folder, or pass `--project <slug>`.
+- **Too many requests:** the CLI waits and retries by itself; if it keeps failing, run it again in a minute.
+- **Plan limit (exit 6):** upgrade at https://hostedge.app/pricing or remove an unused project.
+
+## Development
+
+`pnpm --filter hostedge build` bundles `dist/hostedge.js` (no runtime dependencies). `pnpm --filter hostedge test` runs the commands against a fake API.
+
+Source: https://github.com/ybenjaa-dev/appdock/tree/main/apps/cli

package/dist/hostedge.js

@@ -1320,19 +1320,21 @@ function exitCodeFor(status, code) {
   return EXIT.failure;
 }
 var ApiError = class extends CliError {
-  constructor(message, status, code) {
+  constructor(message, status, code, retryAfter = null) {
     super(message, exitCodeFor(status, code));
     this.status = status;
     this.code = code;
+    this.retryAfter = retryAfter;
   }
   status;
   code;
+  retryAfter;
 };
 function createApi(io2, apiUrl, token) {
   async function raw(path, init2 = {}) {
     const headers = new Headers(init2.headers);
     headers.set("authorization", `Bearer ${token}`);
-    headers.set("user-agent", "hostedge-cli/0.1.1");
+    headers.set("user-agent", "hostedge-cli/0.1.3");
     let response;
     try {
       response = await io2.fetch(`${apiUrl}${path}`, { ...init2, headers });
@@ -1343,7 +1345,13 @@ function createApi(io2, apiUrl, token) {
       const body2 = await response.json().catch(() => ({}));
       const fields = body2.error?.fields ? ` ${Object.entries(body2.error.fields).map(([k, v]) => `${k}: ${v}`).join("; ")}` : "";
       const message = response.status === 401 ? `${body2.error?.message ?? "Not signed in."} Run \`hostedge login\`.` : `${body2.error?.message ?? `HostEdge answered ${response.status}.`}${fields}`;
-      throw new ApiError(message, response.status, body2.error?.code ?? null);
+      const wait = Number(response.headers.get("retry-after"));
+      throw new ApiError(
+        message,
+        response.status,
+        body2.error?.code ?? null,
+        Number.isFinite(wait) && wait > 0 ? wait : null
+      );
     }
     return response;
   }
@@ -1566,7 +1574,8 @@ async function withRetries(work, retryable, attempts = 4, delayMs = 500) {
       return await work();
     } catch (error) {
       if (attempt >= attempts || !retryable(error)) throw error;
-      await new Promise((resolve6) => setTimeout(resolve6, delayMs * 2 ** (attempt - 1)));
+      const wait = typeof delayMs === "function" ? delayMs(error, attempt) : delayMs * 2 ** (attempt - 1);
+      await new Promise((resolve6) => setTimeout(resolve6, wait));
     }
   }
 }
@@ -1639,8 +1648,31 @@ async function* readSse(body2) {
 
 // src/commands/deploy.ts
 var FINISHED = /* @__PURE__ */ new Set(["ready", "failed", "canceled"]);
-var UPLOAD_CONCURRENCY = 16;
+var UPLOAD_CONCURRENCY = 6;
+var BATCH_BYTES = 3 * 1024 * 1024;
+var BATCH_FILES = 100;
 var UPLOAD_TIMEOUT_MS = 3e4;
+function batchesOf(files) {
+  const batches = [];
+  let current = [];
+  let bytes = 0;
+  for (const file of files) {
+    if (current.length > 0 && (bytes + file.size > BATCH_BYTES || current.length >= BATCH_FILES)) {
+      batches.push(current);
+      current = [];
+      bytes = 0;
+    }
+    current.push(file);
+    bytes += file.size;
+  }
+  if (current.length > 0) batches.push(current);
+  return batches;
+}
+function retryDelay(error, attempt) {
+  if (error instanceof ApiError && error.retryAfter !== null)
+    return Math.min(6e4, (error.retryAfter + 1) * 1e3);
+  return Math.min(6e4, 500 * 2 ** (attempt - 1));
+}
 function temporary(error) {
   if (error instanceof ApiError) return error.status === 429 || error.status >= 500;
   return error instanceof CliError;
@@ -1721,23 +1753,56 @@ async function deploy(r, options) {
   let uploaded = 0;
   let reported = 0;
   const step = Math.max(1, Math.ceil(toUpload.length / 10));
-  await pool(toUpload, UPLOAD_CONCURRENCY, async (file) => {
-    const bytes = await readFile4(file.absolute);
-    await withRetries(
-      () => api.raw(`/api/v1/uploads/${file.hash}`, {
-        method: "PUT",
-        headers: { "content-type": "application/octet-stream" },
-        body: bytes,
-        signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS)
-      }),
-      temporary
-    );
-    uploaded++;
+  const progress = (count2) => {
+    uploaded += count2;
     if (toUpload.length > 20 && uploaded - reported >= step && uploaded < toUpload.length) {
       reported = uploaded;
       r.say(`${s.dim(`  ${uploaded}/${toUpload.length} uploaded`)}
 `);
     }
+  };
+  const send = (path, init2, bytes) => withRetries(
+    () => api.raw(path, {
+      ...init2,
+      // 30 s plus a few more for every MB, so a big file on a slow line can finish.
+      signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS + Math.ceil(bytes / 1048576) * 4e3)
+    }),
+    temporary,
+    6,
+    retryDelay
+  );
+  let batching = true;
+  await pool(batchesOf(toUpload), UPLOAD_CONCURRENCY, async (batch) => {
+    if (batching && (batch.length > 1 || (batch[0]?.size ?? 0) <= BATCH_BYTES)) {
+      const form = new FormData();
+      for (const file of batch)
+        form.append(file.hash, new Blob([await readFile4(file.absolute)]), file.hash);
+      try {
+        await send(
+          "/api/v1/uploads/batch",
+          { method: "POST", body: form },
+          batch.reduce((sum, file) => sum + file.size, 0)
+        );
+        progress(batch.length);
+        return;
+      } catch (error) {
+        if (!(error instanceof ApiError) || error.status !== 404 && error.status !== 405)
+          throw error;
+        batching = false;
+      }
+    }
+    for (const file of batch) {
+      await send(
+        `/api/v1/uploads/${file.hash}`,
+        {
+          method: "PUT",
+          headers: { "content-type": "application/octet-stream" },
+          body: await readFile4(file.absolute)
+        },
+        file.size
+      );
+      progress(1);
+    }
   });
   let project;
   if (!link) {
@@ -2969,8 +3034,8 @@ var Reporter = class {
 };
 
 // src/cli.ts
-var VERSION = "0.1.1";
-var HELP = `hostedge \u2014 deploy to HostEdge from your terminal
+var VERSION = "0.1.3";
+var HELP = `hostedge \u2014 hosting your AI agent can use. Deploy from your terminal, CI or an agent.
 
 Usage
   hostedge login [--token <t> | --with-token] [--api-url <url>]

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "hostedge",
-  "version": "0.1.1",
-  "description": "Deploy to HostEdge from your terminal",
+  "version": "0.1.3",
+  "description": "Hosting your AI agent can use. Deploy websites and apps to the edge, read logs and manage env vars from the terminal, CI or an AI agent (Claude Code, Cursor, Codex). JSON output, stable exit codes, MCP.",
   "keywords": [
     "hostedge",
     "deploy",
     "hosting",
     "cli",
+    "ai-agents",
+    "mcp",
+    "claude-code",
+    "cursor",
+    "edge",
+    "static-site",
     "cloudflare-workers"
   ],
   "homepage": "https://hostedge.app/docs/cli",