@canner-ca/cli 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @canner-ca/cli
+
+Deploy to [Canner](https://canner.ca) from any terminal. Works in macOS, Linux, Windows, and Cursor's integrated terminal. No git required.
+
+## Install
+
+```bash
+npm install -g @canner-ca/cli
+```
+
+Or run without installing:
+
+```bash
+npx @canner-ca/cli@latest deploy --follow
+```
+
+Requires Node.js 20 or later.
+
+## Quick start
+
+```bash
+# Sign in once (paste an API token from canner.ca/dashboard/account)
+canner login
+
+# In your project directory, create a Canner project
+canner init
+
+# Ship it
+canner deploy --follow
+```
+
+`--follow` streams the build log live and exits with the build's success code, so it works as the last step of a CI pipeline.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `canner login` | Prompt for an API token, store it at `~/.canner/credentials` (mode 0600). |
+| `canner whoami` | Show the email + plan this CLI is signed in as. |
+| `canner init [--slug X]` | Create a new Canner project and write `canner.json` in the current directory. |
+| `canner deploy [path] [--slug X] [--follow]` | Tar the directory and upload it. `--follow` streams the build log and exits with the build's success code. |
+
+## What gets uploaded
+
+The CLI tars the current directory into a `.tar.gz`, excludes the "build noise" defaults, and streams it to the same upload endpoint the dashboard's drag-drop uses. The server-side build pipeline detects the framework and runs install / build / deploy just like a `git push`.
+
+**Always excluded** (no opt-out): `node_modules/`, `.git/`, `.next/`, `.nuxt/`, `.turbo/`, `.vercel/`, `.svelte-kit/`, `.DS_Store`, `Thumbs.db`. The server-side pipeline rebuilds these from your `package.json` anyway.
+
+**Additionally excluded if present**: anything in `.cannerignore`. Format is similar to `.gitignore` but simpler:
+
+```
+# comment lines start with #
+build
+coverage/
+*.log
+/dist        # leading slash anchors to project root
+```
+
+Supported: basename matches anywhere in the tree, trailing-slash for directory-only, leading-slash for root-anchored, single-segment `*` glob. No negation.
+
+## Per-project config: `canner.json`
+
+`canner init` writes this in your project root. Commit it alongside your source so `canner deploy` knows the target slug:
+
+```json
+{
+  "slug": "my-app"
+}
+```
+
+Override the slug per-run with `--slug=other-app` if you maintain multiple environments.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `CANNER_TOKEN` | Use this token instead of the one in `~/.canner/credentials`. Handy for CI. |
+| `CANNER_API_BASE` | Override the API endpoint. Default `https://api.canner.ca`. |
+
+## CI / GitHub Actions
+
+```yaml
+- uses: actions/setup-node@v4
+  with: { node-version: 22 }
+- run: npx @canner-ca/cli@latest deploy --follow
+  env:
+    CANNER_TOKEN: ${{ secrets.CANNER_TOKEN }}
+```
+
+`--follow` exits with the build's success code, so a failed build fails the workflow.
+
+## Cursor / AI agents
+
+Works in any terminal, including Cursor's integrated terminal. Agents can invoke it as a shell tool — no extension or MCP server required:
+
+```
+canner deploy --follow
+```
+
+## Plan size caps
+
+The CLI uploads under the same per-tier compressed-archive cap as the dashboard:
+
+- **Starter** — 50 MB
+- **Basic** — 200 MB
+- **Pro** — 500 MB
+
+If your project is bigger than that compressed, drop heavier directories into `.cannerignore` or upgrade your plan. `node_modules` is already excluded; the typical thing that pushes a project over the cap is a `public/` folder full of media.
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@canner-ca/cli",
+  "version": "0.1.0",
+  "description": "Canner deploy CLI — git push from any terminal, no GitHub required",
+  "type": "module",
+  "bin": {
+    "canner": "./src/cli.mjs"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/cli.mjs",
+    "prepublishOnly": "node -e \"require('fs').accessSync('src/cli.mjs')\""
+  },
+  "dependencies": {
+    "tar": "^7.4.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "canner",
+    "deploy",
+    "cli",
+    "canadian",
+    "hosting"
+  ],
+  "author": "Canner",
+  "license": "MIT",
+  "homepage": "https://canner.ca/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tzshand/canner.git",
+    "directory": "tools/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/tzshand/canner/issues"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,616 @@
+#!/usr/bin/env node
+// @canner-ca/cli — canner deploy CLI.
+//
+// Single-file ESM. Zero transitive deps beyond `tar` (one MIT package).
+// Works in any terminal (macOS / Linux / Windows / Cursor). Authenticates
+// with a `cnr_*` API token from the dashboard; deploys by tarring the
+// current directory and POSTing to the same /projects/:slug/upload
+// endpoint the dashboard's drag-drop uses.
+//
+// Commands:
+//   canner login                        store an API token
+//   canner whoami                       show the account this CLI is signed in as
+//   canner init [--slug X]              create a project, write canner.json
+//   canner deploy [path] [--slug X] [--follow]
+//                                       tar + upload + optionally stream the build log
+//
+// Exit codes: 0 on success, 1 on user/network/auth error, 2 on bad CLI
+// invocation. `canner deploy --follow` exits with the build's success
+// (0 = live, 1 = failed) so it composes with CI pipelines.
+
+import { existsSync, openAsBlob } from 'node:fs';
+import { mkdir, readFile, writeFile, stat, chmod, unlink } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve, basename } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { randomUUID } from 'node:crypto';
+import { stdin as input, stdout as output } from 'node:process';
+import { create as tarCreate } from 'tar';
+
+const VERSION = '0.1.0';
+const DEFAULT_API_BASE = 'https://api.canner.ca';
+const CONFIG_DIR = join(homedir(), '.canner');
+const CREDENTIALS_PATH = join(CONFIG_DIR, 'credentials');
+const PROJECT_CONFIG_FILE = 'canner.json';
+
+// Stuff we never ship even if the user doesn't have a .cannerignore. These
+// are "build noise" — heavy directories that the server-side build pipeline
+// rebuilds, plus OS / IDE droppings.
+const HARD_EXCLUDES = new Set([
+  'node_modules',
+  '.git',
+  '.next',
+  '.nuxt',
+  '.turbo',
+  '.vercel',
+  '.svelte-kit',
+  '.DS_Store',
+  'Thumbs.db',
+]);
+
+// ---------------------------------------------------------------------------
+// Tiny ANSI styling. No chalk dep — eight inlined escape codes cover us.
+// Disabled when stdout isn't a TTY (CI, redirected to file).
+// ---------------------------------------------------------------------------
+const isTTY = output.isTTY === true;
+const c = (code) => (s) => isTTY ? `\x1b[${code}m${s}\x1b[0m` : String(s);
+const bold = c('1');
+const dim = c('2');
+const red = c('31');
+const green = c('32');
+const yellow = c('33');
+const cyan = c('36');
+
+function die(msg, code = 1) {
+  process.stderr.write(`${red('error:')} ${msg}\n`);
+  process.exit(code);
+}
+
+function info(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+
+function muted(msg) {
+  process.stdout.write(`${dim(msg)}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Credential storage (~/.canner/credentials)
+//
+// JSON with shape: { api_base: string, token: string }. Mode 0600 on
+// platforms that respect it. We default api_base to https://api.canner.ca
+// but allow override via CANNER_API_BASE env var (handy for self-host
+// later, and for local dev pointing at localhost:4001 via tunnel).
+// ---------------------------------------------------------------------------
+async function loadCredentials() {
+  try {
+    const raw = await readFile(CREDENTIALS_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return {
+      apiBase: process.env.CANNER_API_BASE || parsed.api_base || DEFAULT_API_BASE,
+      token: parsed.token,
+    };
+  } catch {
+    return {
+      apiBase: process.env.CANNER_API_BASE || DEFAULT_API_BASE,
+      token: process.env.CANNER_TOKEN || null,
+    };
+  }
+}
+
+async function saveCredentials({ apiBase, token }) {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(
+    CREDENTIALS_PATH,
+    JSON.stringify({ api_base: apiBase, token }, null, 2),
+    { mode: 0o600 }
+  );
+  try {
+    await chmod(CREDENTIALS_PATH, 0o600);
+  } catch {
+    // Windows doesn't honor Unix mode; fine.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers. fetch is built-in on Node 20+.
+// ---------------------------------------------------------------------------
+async function apiRequest(creds, method, path, options = {}) {
+  if (!creds.token) {
+    die("not signed in. Run `canner login` first.");
+  }
+  const url = `${creds.apiBase}${path}`;
+  const headers = {
+    Authorization: `Bearer ${creds.token}`,
+    Accept: 'application/json',
+    ...(options.headers ?? {}),
+  };
+  const init = {
+    method,
+    headers,
+    body: options.body,
+    // Long-lived ops (deploy upload, SSE) shouldn't time out at the
+    // fetch level. Per-call options.signal can still abort.
+  };
+  if (options.signal) init.signal = options.signal;
+  const res = await fetch(url, init).catch((err) => {
+    die(`network: ${err.message}`);
+  });
+  if (!res.ok) {
+    let body = null;
+    try { body = await res.json(); } catch { /* not JSON */ }
+    if (res.status === 401) {
+      die("authentication failed. Your token may be revoked. Run `canner login` again.");
+    }
+    if (res.status === 403) {
+      die("forbidden. The API token doesn't have access to this resource.");
+    }
+    const msg = body?.message || body?.error || `${res.status} ${res.statusText}`;
+    die(`${method} ${path}: ${msg}`);
+  }
+  return res;
+}
+
+async function apiJSON(creds, method, path, body) {
+  const init = {};
+  if (body !== undefined) {
+    init.headers = { 'Content-Type': 'application/json' };
+    init.body = JSON.stringify(body);
+  }
+  const res = await apiRequest(creds, method, path, init);
+  if (res.status === 204) return null;
+  return res.json();
+}
+
+// ---------------------------------------------------------------------------
+// .cannerignore parsing — simple line-based excludes.
+// One pattern per line. '#' comments, blank lines ignored. Supports:
+//   - exact-basename match anywhere ('build', 'coverage')
+//   - trailing-slash directory match ('logs/' matches only directories)
+//   - leading '/' anchors to project root ('/dist' = only the root dist/)
+//   - basic glob: '*' inside a single path segment
+// No negation ('!') support — keep the surface tight.
+// ---------------------------------------------------------------------------
+function parseIgnoreFile(text) {
+  const patterns = [];
+  for (const lineRaw of text.split('\n')) {
+    const line = lineRaw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const dirOnly = line.endsWith('/');
+    const anchored = line.startsWith('/');
+    const body = line.replace(/^\/+/, '').replace(/\/+$/, '');
+    const glob = body.includes('*');
+    patterns.push({ pattern: body, dirOnly, anchored, glob });
+  }
+  return patterns;
+}
+
+function matchesIgnore(relPath, isDir, patterns) {
+  // relPath is POSIX-normalized, no leading slash, no './'.
+  const parts = relPath.split('/');
+  for (const p of patterns) {
+    if (p.dirOnly && !isDir) continue;
+    if (p.anchored) {
+      if (matchSegment(p, parts.join('/'))) return true;
+    } else {
+      // Unanchored: match the pattern against any segment (basename match)
+      // OR against any suffix of the path.
+      for (let i = 0; i < parts.length; i++) {
+        if (matchSegment(p, parts.slice(i).join('/'))) return true;
+      }
+    }
+  }
+  return false;
+}
+
+function matchSegment(p, candidate) {
+  if (!p.glob) return p.pattern === candidate;
+  // Compile glob to regex on first use. Cache on the pattern object.
+  if (!p._re) {
+    const escaped = p.pattern
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*/g, '[^/]*');
+    p._re = new RegExp(`^${escaped}$`);
+  }
+  return p._re.test(candidate);
+}
+
+async function loadIgnorePatterns(cwd) {
+  const path = join(cwd, '.cannerignore');
+  if (!existsSync(path)) return [];
+  const text = await readFile(path, 'utf8');
+  return parseIgnoreFile(text);
+}
+
+// ---------------------------------------------------------------------------
+// Project config (canner.json) — what `canner init` writes and `canner
+// deploy` reads. Currently just {slug}. Future fields: a `path` override
+// for monorepos pointing at a subdir, an optional `before_upload` hook.
+// ---------------------------------------------------------------------------
+async function loadProjectConfig(cwd) {
+  const path = join(cwd, PROJECT_CONFIG_FILE);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch (err) {
+    die(`could not parse ${PROJECT_CONFIG_FILE}: ${err.message}`);
+  }
+}
+
+async function writeProjectConfig(cwd, cfg) {
+  await writeFile(join(cwd, PROJECT_CONFIG_FILE), JSON.stringify(cfg, null, 2) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+async function cmdLogin(_args) {
+  const rl = createInterface({ input, output });
+  const existing = await loadCredentials();
+  const apiBase = process.env.CANNER_API_BASE || existing.apiBase || DEFAULT_API_BASE;
+  info(bold('Sign in to Canner'));
+  info(`Create an API token at ${cyan(apiBase.replace('api.', '') + '/dashboard/account')}`);
+  info(`Then paste it below. It starts with ${dim('cnr_')}`);
+  const token = (await rl.question('token: ')).trim();
+  rl.close();
+  if (!token.startsWith('cnr_')) {
+    die("that doesn't look like a Canner API token (expected prefix 'cnr_').");
+  }
+  await saveCredentials({ apiBase, token });
+  // Verify by hitting /auth/me.
+  const me = await apiJSON({ apiBase, token }, 'GET', '/auth/me');
+  if (!me?.account) {
+    die("token didn't authenticate. Check it was copied correctly.");
+  }
+  info(`${green('Signed in as')} ${bold(me.account.email)}`);
+}
+
+async function cmdWhoami() {
+  const creds = await loadCredentials();
+  if (!creds.token) {
+    die("not signed in. Run `canner login`.");
+  }
+  const me = await apiJSON(creds, 'GET', '/auth/me');
+  if (!me?.account) {
+    die('authenticated but /auth/me returned no account.');
+  }
+  info(`${bold(me.account.email)}`);
+  muted(`api: ${creds.apiBase}`);
+  // Projects count from /me/plan (cheap call we already have).
+  try {
+    const plan = await apiJSON(creds, 'GET', '/me/plan');
+    if (plan?.plan) {
+      muted(
+        `plan: ${plan.plan.display_name} (${plan.project_count}/${plan.project_count_limit} projects)`
+      );
+    }
+  } catch {
+    // /me/plan is optional context; not fatal if it fails.
+  }
+}
+
+async function cmdInit(args) {
+  const cwd = process.cwd();
+  const existing = await loadProjectConfig(cwd);
+  if (existing?.slug) {
+    die(`already initialized — ${PROJECT_CONFIG_FILE} has slug=${existing.slug}`);
+  }
+
+  const creds = await loadCredentials();
+  if (!creds.token) {
+    die("not signed in. Run `canner login` first.");
+  }
+
+  const rl = createInterface({ input, output });
+  const defaultName = basename(cwd);
+  const name = (await rl.question(`Project name [${defaultName}]: `)).trim() || defaultName;
+  const defaultSlug = sluggify(name);
+  const slug =
+    args.slug ||
+    (await rl.question(`Slug [${defaultSlug}]: `)).trim() ||
+    defaultSlug;
+  rl.close();
+
+  if (!/^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$/.test(slug)) {
+    die(`invalid slug "${slug}" — must be 3–50 lowercase letters/digits/hyphens, no leading or trailing hyphen.`);
+  }
+
+  // Server validates uniqueness + reserved-slug rules; we just surface them.
+  const body = await apiJSON(creds, 'POST', '/projects', { name, slug });
+  if (!body) die('project creation returned no body.');
+  await writeProjectConfig(cwd, { slug });
+  info(`${green('Created')} ${bold(slug)}`);
+  muted(`Will be served at https://${slug}.app.canner.ca after the first deploy.`);
+  muted(`Wrote ${PROJECT_CONFIG_FILE}. Run \`canner deploy\` to ship.`);
+}
+
+async function cmdDeploy(args) {
+  const projectPath = resolve(args._[0] || '.');
+  if (!existsSync(projectPath)) {
+    die(`path not found: ${projectPath}`);
+  }
+  const cwdStat = await stat(projectPath);
+  if (!cwdStat.isDirectory()) {
+    die(`path is not a directory: ${projectPath}`);
+  }
+
+  const cfg = await loadProjectConfig(projectPath);
+  const slug = args.slug || cfg?.slug;
+  if (!slug) {
+    die(`no project slug. Pass --slug=X or run \`canner init\` to create ${PROJECT_CONFIG_FILE}.`);
+  }
+
+  const creds = await loadCredentials();
+  if (!creds.token) {
+    die("not signed in. Run `canner login`.");
+  }
+
+  // Build the ignore patterns: hard excludes + user .cannerignore.
+  const userPatterns = await loadIgnorePatterns(projectPath);
+
+  // Build the tarball as a temp file. We use a temp file (not piping directly
+  // into the upload) so we know the final size before POST + so a tar error
+  // surfaces cleanly before we touch the network.
+  const tarPath = join(tmpdir(), `canner-${randomUUID()}.tar.gz`);
+  let fileCount = 0;
+  info(`${dim('packaging')} ${projectPath}`);
+  try {
+    await tarCreate(
+      {
+        gzip: true,
+        file: tarPath,
+        cwd: projectPath,
+        // Strict portable-file-only — refuse symlinks pointing outside the
+        // project, etc. Matches what the server-side safe-extractor enforces.
+        portable: true,
+        filter: (path) => {
+          // path is relative to cwd, POSIX-normalized by tar.
+          const rel = path.replace(/^\.\//, '').replace(/^\/+/, '');
+          if (!rel) return true; // root
+          const parts = rel.split('/');
+          // Hard excludes match by basename anywhere in the tree.
+          for (const part of parts) {
+            if (HARD_EXCLUDES.has(part)) return false;
+          }
+          // User .cannerignore.
+          const isDir = path.endsWith('/');
+          if (matchesIgnore(rel, isDir, userPatterns)) return false;
+          fileCount++;
+          return true;
+        },
+      },
+      ['./']
+    );
+  } catch (err) {
+    await unlink(tarPath).catch(() => undefined);
+    die(`tar failed: ${err.message}`);
+  }
+
+  const tarStat = await stat(tarPath);
+  const sizeMb = (tarStat.size / 1024 / 1024).toFixed(2);
+  info(`${dim('packaged')} ${fileCount} files (${sizeMb} MB compressed)`);
+
+  // Upload. fs.openAsBlob() backs the Blob by the on-disk file lazily —
+  // bytes only flow when fetch consumes them, so a 500 MB Pro upload
+  // doesn't buffer into RAM on the user's machine. Node fetch has no
+  // upload-progress hook as of 2026, so we just print the size we're
+  // sending; the dashboard shows real-time progress for browser uploads.
+  info(`${dim('uploading')} to ${slug}…`);
+  const form = new FormData();
+  const blob = await openAsBlob(tarPath, { type: 'application/gzip' });
+  form.append('archive', blob, `${slug}.tar.gz`);
+
+  let response;
+  try {
+    response = await apiRequest(creds, 'POST', `/projects/${slug}/upload`, { body: form });
+  } finally {
+    await unlink(tarPath).catch(() => undefined);
+  }
+
+  const body = await response.json();
+  const deploymentId = body.deployment_id;
+  if (!deploymentId) {
+    die('upload succeeded but the response had no deployment_id.');
+  }
+  info(`${green('queued')} deployment ${dim(deploymentId.slice(0, 8))}`);
+
+  if (!args.follow) {
+    muted(`Tail with: canner deploy --follow --slug=${slug}  (or visit the dashboard)`);
+    return;
+  }
+
+  // SSE tail until terminal.
+  const exitCode = await tailDeploymentLogs(creds, slug, deploymentId);
+  process.exit(exitCode);
+}
+
+// ---------------------------------------------------------------------------
+// SSE consumer for /projects/:slug/deployments/:id/logs.
+// Parses the wire format manually (no eventsource dep). Returns exit code:
+// 0 if status ended at 'live', 1 if 'failed', 2 if connection died early.
+// ---------------------------------------------------------------------------
+async function tailDeploymentLogs(creds, slug, deploymentId) {
+  info(dim(`streaming build log…`));
+  const url = `${creds.apiBase}/projects/${slug}/deployments/${deploymentId}/logs`;
+  const res = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${creds.token}`,
+      Accept: 'text/event-stream',
+    },
+  }).catch((err) => {
+    die(`could not open log stream: ${err.message}`);
+  });
+  if (!res.ok || !res.body) {
+    die(`log stream returned ${res.status} ${res.statusText}`);
+  }
+
+  const decoder = new TextDecoder('utf-8');
+  let buffer = '';
+  let lastStatus = 'queued';
+  let printedHistory = false;
+
+  for await (const chunk of res.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let idx;
+    while ((idx = buffer.indexOf('\n\n')) !== -1) {
+      const raw = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 2);
+      // Skip heartbeat comments (": ping").
+      if (raw.startsWith(':')) continue;
+      let event = 'message';
+      let data = '';
+      for (const line of raw.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim();
+        else if (line.startsWith('data:')) data += line.slice(5).trim();
+      }
+      if (!data) continue;
+      let parsed;
+      try { parsed = JSON.parse(data); } catch { continue; }
+      if (event === 'history') {
+        if (!printedHistory && parsed.log) {
+          process.stdout.write(parsed.log);
+        }
+        printedHistory = true;
+      } else if (event === 'log') {
+        if (parsed.log) process.stdout.write(parsed.log);
+      } else if (event === 'status') {
+        lastStatus = parsed.status ?? lastStatus;
+      } else if (event === 'done') {
+        lastStatus = parsed.status ?? lastStatus;
+        break;
+      }
+    }
+  }
+
+  if (lastStatus === 'live') {
+    info(`\n${green('live')} at https://${slug}.app.canner.ca`);
+    return 0;
+  }
+  if (lastStatus === 'failed') {
+    info(`\n${red('failed')} (status=${lastStatus})`);
+    return 1;
+  }
+  info(`\n${yellow('stream ended')} (status=${lastStatus})`);
+  return 2;
+}
+
+// ---------------------------------------------------------------------------
+// Slug derivation mirrors the server's regex: ^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$
+// ---------------------------------------------------------------------------
+function sluggify(s) {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-+/g, '-')
+    .slice(0, 50);
+}
+
+// ---------------------------------------------------------------------------
+// Argv parser. Tiny, no dep. Supports:
+//   canner cmd                    → { _: [], cmd }
+//   canner cmd value              → { _: ['value'] }
+//   canner cmd --flag             → { flag: true }
+//   canner cmd --key value        → { key: 'value' }
+//   canner cmd --key=value        → { key: 'value' }
+//   canner cmd -v                 → { v: true }
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq !== -1) {
+        out[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next && !next.startsWith('-')) {
+          out[key] = next;
+          i++;
+        } else {
+          out[key] = true;
+        }
+      }
+    } else if (a.startsWith('-') && a.length === 2) {
+      out[a.slice(1)] = true;
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+function printHelp() {
+  process.stdout.write(`${bold('canner')} ${dim('— deploy to Canner from any terminal')}
+
+${bold('Usage:')}
+  canner <command> [options]
+
+${bold('Commands:')}
+  ${bold('login')}                Store your Canner API token (one-time).
+  ${bold('whoami')}               Show the account this CLI is signed in as.
+  ${bold('init')} [--slug X]      Create a project and write ${cyan(PROJECT_CONFIG_FILE)}.
+  ${bold('deploy')} [path] [--slug X] [--follow]
+                       Tar the current directory and ship it.
+
+${bold('Examples:')}
+  canner login
+  cd my-site && canner init
+  canner deploy --follow             ${dim('# build to live, streaming logs')}
+  canner deploy ./web --slug my-app  ${dim('# deploy a sibling directory')}
+
+${bold('Environment:')}
+  CANNER_TOKEN         Override stored token (handy for CI).
+  CANNER_API_BASE      Override API endpoint (default ${DEFAULT_API_BASE}).
+
+${bold('Files:')}
+  ~/.canner/credentials   Stored token (mode 0600).
+  canner.json             Per-project slug (committed alongside source).
+  .cannerignore           Optional excludes (in addition to node_modules,
+                          .git, .next, .nuxt, .turbo, .vercel, .svelte-kit,
+                          .DS_Store, Thumbs.db which are always excluded).
+
+Docs: https://canner.ca/cli
+Version: ${VERSION}
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+const args = parseArgs(process.argv.slice(2));
+const command = args._.shift();
+
+if (args.version || args.v || command === 'version') {
+  process.stdout.write(`canner ${VERSION}\n`);
+  process.exit(0);
+}
+if (!command || args.help || args.h || command === 'help') {
+  printHelp();
+  process.exit(0);
+}
+
+const dispatch = {
+  login: cmdLogin,
+  whoami: cmdWhoami,
+  init: cmdInit,
+  deploy: cmdDeploy,
+};
+const handler = dispatch[command];
+if (!handler) {
+  process.stderr.write(`${red('error:')} unknown command "${command}"\n\n`);
+  printHelp();
+  process.exit(2);
+}
+
+try {
+  await handler(args);
+} catch (err) {
+  if (err && err.code === 'ERR_UNHANDLED_ERROR') {
+    die(err.message);
+  }
+  die(err?.message ?? String(err));
+}