lemonade-host 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# lemonade-host
+
+Publish a folder to [Lemonade Host](https://lemonadehost.com) from your terminal.
+
+> The package is **`lemonade-host`**. The plain `lemonade` name on npm
+> belongs to somebody else, so `npx lemonade …` would download and run their
+> package, not this one. Installed globally the command is still `lemonade`.
+
+```bash
+npx lemonade-host deploy
+```
+
+That's the whole thing. It zips the current folder, uploads it, and prints
+the live URL.
+
+## Setup, once
+
+Mint a deploy token in your dashboard — **Deploy tools → Deploy token** —
+and save it:
+
+```bash
+npx lemonade-host login
+```
+
+It asks for the token and the site, and writes them to `~/.lemonade`
+with permissions only you can read. Or set `LEMONADE_TOKEN` and
+`LEMONADE_SITE` in the environment instead, which is what CI wants.
+
+## Commands
+
+| | |
+|---|---|
+| `lemonade deploy [dir]` | Zip a folder and publish it. Defaults to `.`, and prefers `dist/`, `build/`, `out/` or `public/` if one exists |
+| `lemonade status` | The last few deploys for this site |
+| `lemonade login` | Save a token and site id to `~/.lemonade` |
+| `lemonade whoami` | Which site the current token points at |
+
+Useful flags: `--token`, `--site`, `--origin` (for staging), `--yes` (skip
+the confirmation), `--json` (machine-readable output).
+
+## A token reaches exactly one site
+
+A `lm_` token is minted for a single site and can do two things: publish a
+release to that site, and read that site's deploy history. It cannot spend
+money, cancel anything, change an address, or see another site — so leaving
+one in a CI secret is a bounded risk rather than an open door.
+
+Revoke one any time from the same screen you minted it on.
+
+## In CI
+
+```yaml
+- run: npx lemonade-host deploy ./dist --yes
+  env:
+    LEMONADE_TOKEN: ${{ secrets.LEMONADE_TOKEN }}
+    LEMONADE_SITE:  ${{ secrets.LEMONADE_SITE }}
+```
+
+Exit code is 0 on a successful publish and non-zero on anything else, so a
+failed deploy fails the job.
+
+## Limits
+
+256 MB per upload, 25 MB per file, 20,000 files, 1 GB extracted. Dotfiles,
+`node_modules`, `.git` and friends are skipped unless you pass
+`--include-hidden`.
+
+Static files only — Lemonade Host serves what you give it and never runs a
+build. Build locally or in CI, then point this at the output folder.

package/bin/lemonade.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * `npx lemonade …` — the whole entry point.
+ *
+ * Argument parsing is by hand and stays that way: a flag parser is a
+ * dependency, and this package's promise is that `npx lemonade deploy`
+ * downloads one thing and runs.
+ *
+ * EVERY ERROR PATH PRINTS SOMETHING A PERSON CAN ACT ON. An unexpected
+ * exception still prints its stack, because hiding one from whoever has to
+ * report it helps nobody — but everything we anticipated is a sentence and
+ * a fix, never a stack trace at somebody publishing their first website.
+ */
+
+import { deploy, login, Refused, status, whoami } from "../src/commands.mjs";
+
+const USAGE = `lemonade — publish a folder to Lemonade Host
+
+  lemonade deploy [folder]   zip it and publish it (defaults to the built output)
+  lemonade status            the last few deploys for this site
+  lemonade login             save a deploy token and site id to ~/.lemonade
+  lemonade whoami            check the token, and which site it reaches
+
+Options
+  --token lm_…       a deploy token (or set LEMONADE_TOKEN)
+  --site st_…        which site (or set LEMONADE_SITE)
+  --origin URL       point at another instance, e.g. staging
+  --yes, -y          do not ask before publishing
+  --json             machine-readable output
+  --include-hidden   publish dotfiles and node_modules too
+  --version, -v      print the version
+  --help, -h         this
+
+A token reaches exactly one site and can only publish to it and read its
+deploy history. It cannot spend money, cancel anything, or see another site.
+`;
+
+const BOOLEAN = new Set(["yes", "y", "json", "include-hidden", "help", "h", "version", "v"]);
+const VALUED = new Set(["token", "site", "origin"]);
+
+function parse(argv) {
+  const args = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("-")) {
+      args.push(arg);
+      continue;
+    }
+    const [rawName, inline] = arg.replace(/^-+/, "").split("=");
+    const name = rawName;
+    if (VALUED.has(name)) {
+      const value = inline ?? argv[++i];
+      if (value === undefined) throw new Refused(`--${name} needs a value.`);
+      flags[name] = value;
+      continue;
+    }
+    if (BOOLEAN.has(name)) {
+      flags[name] = true;
+      continue;
+    }
+    throw new Refused(`Unknown option: ${arg}\n\n${USAGE}`);
+  }
+  return { args, flags };
+}
+
+const COMMANDS = { deploy, status, login, whoami };
+
+async function main() {
+  const { args, flags } = parse(process.argv.slice(2));
+
+  if (flags.version || flags.v) {
+    const { default: pkg } = await import("../package.json", { with: { type: "json" } });
+    console.log(pkg.version);
+    return 0;
+  }
+  const command = args.shift();
+  // Asking for help is not an error: `lemonade --help` exits 0 so a script
+  // that pipes it does not fail. Running `lemonade` with nothing at all IS
+  // a usage error, and exits 1.
+  if (flags.help || flags.h) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (!command) {
+    console.log(USAGE);
+    return 1;
+  }
+  const run = COMMANDS[command];
+  if (!run) {
+    console.error(`Unknown command: ${command}\n`);
+    console.error(USAGE);
+    return 1;
+  }
+  // The two spellings of the same intent, normalised once.
+  flags.yes = flags.yes || flags.y || false;
+  flags.includeHidden = flags["include-hidden"] || false;
+  return (await run(args, flags)) ?? 0;
+}
+
+main()
+  .then((code) => process.exit(code ?? 0))
+  .catch((err) => {
+    if (err instanceof Refused || err?.expected) {
+      console.error(`\n${err.message}`);
+      process.exit(1);
+    }
+    console.error(err);
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "lemonade-host",
+  "version": "0.1.0",
+  "description": "Publish a folder to Lemonade Host from your terminal.",
+  "keywords": [
+    "lemonade",
+    "lemonade-host",
+    "static",
+    "hosting",
+    "deploy"
+  ],
+  "homepage": "https://lemonadehost.com/deploy/cli/",
+  "bugs": {
+    "url": "mailto:support@lemonadehost.com"
+  },
+  "license": "MIT",
+  "author": "Analytix Media LLC",
+  "type": "module",
+  "bin": {
+    "lemonade": "bin/lemonade.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/src/commands.mjs

@@ -0,0 +1,302 @@
+/**
+ * The four commands, and the one HTTP call underneath them.
+ *
+ * Everything here talks to the deploy API a browser session also uses — the
+ * CLI is an adapter onto it, not a second way in, so the gate order it meets
+ * (401 → concealed 404 → 409 → 429 → 413 → the gauntlet) is the same one the
+ * portal meets and is pinned by the app's own specs.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { CONFIG_PATH, looksLikeToken, normalizeSite, resolve, save } from "./config.mjs";
+import { explain } from "./messages.mjs";
+import { collect, zipFiles } from "./zip.mjs";
+
+const MAX_UPLOAD = 256 * 1024 * 1024;
+
+/** Folders that hold BUILT output, in the order we would guess. */
+const BUILD_DIRS = ["dist", "build", "out", "public", "_site"];
+
+const bold = (s) => (stdout.isTTY ? `\u001b[1m${s}\u001b[0m` : s);
+const dim = (s) => (stdout.isTTY ? `\u001b[2m${s}\u001b[0m` : s);
+const green = (s) => (stdout.isTTY ? `\u001b[32m${s}\u001b[0m` : s);
+
+function human(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** A CLI error that is the user's situation, not a stack trace. */
+export class Refused extends Error {
+  constructor(message, { code = null } = {}) {
+    super(message);
+    this.code = code;
+    this.expected = true;
+  }
+}
+
+function requireAuth(flags) {
+  const cfg = resolve(flags);
+  if (!cfg.token) {
+    throw new Refused(
+      "No deploy token.\n" +
+        "  Mint one in your dashboard under Deploy tools, then run: lemonade login\n" +
+        "  Or set LEMONADE_TOKEN in the environment (which is what CI wants).",
+    );
+  }
+  if (!looksLikeToken(cfg.token)) {
+    throw new Refused(
+      `That does not look like a deploy token (they start with lm_).\n` +
+        `  It came from ${cfg.from.token}.`,
+    );
+  }
+  if (!cfg.site) {
+    throw new Refused(
+      "No site id.\n" +
+        "  Pass --site st_… , set LEMONADE_SITE, or run: lemonade login\n" +
+        "  The id is in the address bar of the site's page in your dashboard.",
+    );
+  }
+  const site = normalizeSite(cfg.site);
+  if (!site) {
+    throw new Refused(`"${cfg.site}" is not a site id — they look like st_….`);
+  }
+  return { ...cfg, site };
+}
+
+/**
+ * Which folder to publish.
+ *
+ * An explicit argument always wins. With none, a build folder is preferred
+ * over the project root — publishing a repository root uploads the source,
+ * the README and often a stray .env, and the thing a customer meant is
+ * nearly always the built output. It says which one it chose, every time.
+ */
+export function chooseDir(arg, cwd = process.cwd()) {
+  if (arg) {
+    const abs = path.resolve(cwd, arg);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
+      throw new Refused(`${abs} is not a folder.`);
+    }
+    return { dir: abs, guessed: false };
+  }
+  for (const name of BUILD_DIRS) {
+    const abs = path.join(cwd, name);
+    if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+      const hasIndex = fs.existsSync(path.join(abs, "index.html"));
+      if (hasIndex) return { dir: abs, guessed: true };
+    }
+  }
+  return { dir: cwd, guessed: false };
+}
+
+async function confirm(question) {
+  if (!stdin.isTTY) return true;
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
+  rl.close();
+  return answer === "" || answer === "y" || answer === "yes";
+}
+
+async function call(cfg, url, init = {}) {
+  let res;
+  try {
+    res = await fetch(url, {
+      ...init,
+      headers: { authorization: `Bearer ${cfg.token}`, ...(init.headers ?? {}) },
+    });
+  } catch (err) {
+    throw new Refused(
+      `Could not reach ${cfg.origin}.\n  ${err.message}\n` +
+        `  Nothing was published. Check the address, or your connection.`,
+    );
+  }
+  const text = await res.text();
+  let body = null;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    /* a proxy or an error page — handled below */
+  }
+  if (!res.ok || (body && body.ok === false)) {
+    const code = body?.error ?? body?.errorCode ?? null;
+    throw new Refused(explain(code, body?.message ?? null), { code });
+  }
+  if (!body) {
+    throw new Refused(
+      `${cfg.origin} answered with something that was not JSON (HTTP ${res.status}).`,
+    );
+  }
+  return body;
+}
+
+/* ── deploy ──────────────────────────────────────────────────────────────── */
+
+export async function deploy(args, flags) {
+  const cfg = requireAuth(flags);
+  const { dir, guessed } = chooseDir(args[0]);
+
+  const { files, skipped } = collect(dir, { includeHidden: flags.includeHidden });
+  if (files.length === 0) {
+    throw new Refused(
+      `${dir} has no files to publish.\n` +
+        `  If everything in it is hidden, pass --include-hidden.`,
+    );
+  }
+
+  const bytes = files.reduce((sum, f) => sum + f.size, 0);
+  const hasIndex = files.some((f) => f.rel === "index.html");
+
+  if (!flags.json) {
+    console.log(`${bold("Publishing")} ${dir}`);
+    if (guessed) console.log(dim(`  chose the built output — pass a folder to override`));
+    console.log(
+      dim(
+        `  ${files.length} file${files.length === 1 ? "" : "s"}, ${human(bytes)}` +
+          (skipped.hidden || skipped.symlink || skipped.secret
+            ? ` · skipped ${skipped.hidden} hidden, ${skipped.symlink} link${skipped.symlink === 1 ? "" : "s"}, ${skipped.secret} secret${skipped.secret === 1 ? "" : "s"}`
+            : ""),
+      ),
+    );
+    // Said BEFORE the upload, not after. A site with no index.html serves a
+    // 404 at its own address, and finding that out from the live URL is a
+    // worse minute than finding it out here.
+    if (!hasIndex) {
+      console.log(
+        `  ${bold("No index.html at the top level")} — visitors will get a 404 at the site's address.`,
+      );
+    }
+  }
+
+  if (bytes > MAX_UPLOAD) {
+    throw new Refused(
+      `That folder is ${human(bytes)}, over the 256 MB upload limit.\n` +
+        `  Publish the built output rather than the whole project.`,
+    );
+  }
+
+  if (!flags.yes && !flags.json && !(await confirm(`Publish to ${cfg.site}?`))) {
+    console.log("Nothing was published.");
+    return 1;
+  }
+
+  const zip = zipFiles(files);
+  const body = await call(cfg, `${cfg.origin}/api/deploy/${cfg.site}`, {
+    method: "POST",
+    headers: { "content-type": "application/zip" },
+    body: zip,
+  });
+
+  if (flags.json) {
+    console.log(JSON.stringify(body, null, 2));
+    return body.blocked ? 1 : 0;
+  }
+
+  // Truthful about the two states a "successful" upload can land in. The
+  // app's own route learned this the hard way: a publish that the safety
+  // scan blocked used to come back as a plain success, and every door
+  // printed the live URL of a site that was now offline.
+  if (body.blocked) {
+    console.log("");
+    console.log(bold("Uploaded, but this version is offline."));
+    console.log(`  ${body.message ?? "Our safety check flagged it and it is under review."}`);
+    console.log(dim("  Nothing was deleted. Check your email."));
+    return 1;
+  }
+
+  console.log("");
+  console.log(green(bold("Live.")));
+  if (body.url) console.log(`  ${body.url}`);
+  console.log(
+    dim(`  ${body.fileCount} file${body.fileCount === 1 ? "" : "s"} · ${body.deploymentId}`),
+  );
+  if (body.serving === false) {
+    console.log("");
+    console.log(
+      `  ${bold("Not serving yet")} — this site has not been published from your dashboard.`,
+    );
+    console.log(dim(`  Your files are here and will go live the moment it is.`));
+  }
+  return 0;
+}
+
+/* ── status ──────────────────────────────────────────────────────────────── */
+
+export async function status(_args, flags) {
+  const cfg = requireAuth(flags);
+  const body = await call(cfg, `${cfg.origin}/api/deploy/${cfg.site}/deployments`);
+  const rows = body.deployments ?? [];
+
+  if (flags.json) {
+    console.log(JSON.stringify(body, null, 2));
+    return 0;
+  }
+  if (rows.length === 0) {
+    console.log("No deploys yet.");
+    return 0;
+  }
+  for (const row of rows.slice(0, 10)) {
+    const when = row.createdAt ? new Date(row.createdAt).toISOString().replace("T", " ").slice(0, 16) : "";
+    const mark = row.status === "active" ? green("●") : row.status === "failed" ? "✗" : dim("○");
+    console.log(
+      `${mark} ${when}  ${String(row.status).padEnd(10)} ${dim(`${row.source ?? ""} ${row.fileCount ?? ""} files`)}`,
+    );
+  }
+  return 0;
+}
+
+/* ── whoami ──────────────────────────────────────────────────────────────── */
+
+export async function whoami(_args, flags) {
+  const cfg = requireAuth(flags);
+  // Asking the SERVER rather than reading the config back: the question is
+  // "does this token still work, and what does it reach", and only one of
+  // those two can be answered locally.
+  await call(cfg, `${cfg.origin}/api/deploy/${cfg.site}/deployments`);
+  if (flags.json) {
+    console.log(JSON.stringify({ ok: true, site: cfg.site, origin: cfg.origin }, null, 2));
+    return 0;
+  }
+  console.log(`Token is valid and reaches ${bold(cfg.site)}`);
+  console.log(dim(`  ${cfg.origin} · token from ${cfg.from.token}, site from ${cfg.from.site}`));
+  return 0;
+}
+
+/* ── login ───────────────────────────────────────────────────────────────── */
+
+export async function login(_args, flags) {
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    console.log("Mint a deploy token in your dashboard, under Deploy tools.");
+    console.log(dim("It is shown once — there is no copy on our side to read back.\n"));
+
+    const token = (flags.token ?? (await rl.question("Deploy token (lm_…): "))).trim();
+    if (!looksLikeToken(token)) {
+      throw new Refused("That does not look like a deploy token — they start with lm_.");
+    }
+    const siteRaw = flags.site ?? (await rl.question("Site id (st_…, or paste the URL): "));
+    const site = normalizeSite(siteRaw);
+    if (!site) throw new Refused("That is not a site id — they look like st_….");
+
+    const origin = (flags.origin ?? process.env.LEMONADE_ORIGIN ?? "https://app.lemonadehost.com").replace(/\/+$/, "");
+
+    // Proved before it is saved. Writing an unverified token means the
+    // first real deploy is where you learn it was wrong, and by then the
+    // one place the raw token existed has usually been closed.
+    const probe = { token, site, origin, from: { token: "prompt", site: "prompt" } };
+    await call(probe, `${origin}/api/deploy/${site}/deployments`);
+
+    const where = save({ token, site, origin });
+    console.log(`\n${green("Saved.")} ${dim(where)} (readable only by you)`);
+    console.log(dim("Now: lemonade deploy"));
+    return 0;
+  } finally {
+    rl.close();
+  }
+}
+
+export const CONFIG_FILE = CONFIG_PATH;

package/src/config.mjs

@@ -0,0 +1,87 @@
+/**
+ * Where the token comes from, and where it is allowed to be written.
+ *
+ * PRECEDENCE, highest first: a flag, then the environment, then `~/.lemonade`.
+ * CI sets the environment and must beat a stale file left on a shared
+ * runner; a human typing `--site` means this run and must beat both.
+ *
+ * THE FILE IS 0600 AND IS CHECKED. A deploy token in a world-readable file
+ * in a home directory is the failure this whole shape exists to avoid, so
+ * `load()` REFUSES a file anyone else can read rather than quietly using
+ * it — the same posture the app takes with its own credentials file. It
+ * says how to fix it in one line the reader can paste.
+ *
+ * AND IT IS NEVER PRINTED. Nothing in this package writes a raw token to
+ * stdout, stderr or an error message. A token echoed once is a token in a
+ * terminal's scrollback, a CI log and whatever screenshot follows.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const CONFIG_PATH = path.join(os.homedir(), ".lemonade");
+export const DEFAULT_ORIGIN = "https://app.lemonadehost.com";
+
+/** Everything the commands need, resolved. Never contains a printed token. */
+export function resolve(flags = {}) {
+  const file = load();
+  const origin =
+    flags.origin ?? process.env.LEMONADE_ORIGIN ?? file.origin ?? DEFAULT_ORIGIN;
+  return {
+    token: flags.token ?? process.env.LEMONADE_TOKEN ?? file.token ?? null,
+    site: flags.site ?? process.env.LEMONADE_SITE ?? file.site ?? null,
+    origin: origin.replace(/\/+$/, ""),
+    // Where each one came from, for the error messages. Saying "no token"
+    // to somebody who has one in ~/.lemonade and a typo in the env is not
+    // an answer.
+    from: {
+      token: flags.token ? "--token" : process.env.LEMONADE_TOKEN ? "LEMONADE_TOKEN" : file.token ? CONFIG_PATH : null,
+      site: flags.site ? "--site" : process.env.LEMONADE_SITE ? "LEMONADE_SITE" : file.site ? CONFIG_PATH : null,
+    },
+  };
+}
+
+export function load() {
+  if (!fs.existsSync(CONFIG_PATH)) return {};
+  const stat = fs.statSync(CONFIG_PATH);
+  // Group or other can read it. On Windows the mode bits are not meaningful,
+  // so this only bites where it means something.
+  if (process.platform !== "win32" && (stat.mode & 0o077) !== 0) {
+    throw new Error(
+      `${CONFIG_PATH} is readable by other users, and it holds a deploy token.\n` +
+        `  Fix it with:  chmod 600 ${CONFIG_PATH}\n` +
+        `  Or revoke the token in your dashboard and mint a new one.`,
+    );
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    throw new Error(`${CONFIG_PATH} is not valid JSON. Delete it and run: lemonade login`);
+  }
+}
+
+export function save(next) {
+  const body = JSON.stringify({ ...load(), ...next }, null, 2) + "\n";
+  // Written 0600 from the first byte — creating it 0644 and chmod-ing after
+  // leaves a window in which it is readable, and that window is exactly
+  // when a backup or a file watcher would see it.
+  fs.writeFileSync(CONFIG_PATH, body, { mode: 0o600 });
+  if (process.platform !== "win32") fs.chmodSync(CONFIG_PATH, 0o600);
+  return CONFIG_PATH;
+}
+
+/** `lm_` + 40 base64url chars, as minted by the dashboard. */
+export function looksLikeToken(raw) {
+  return typeof raw === "string" && /^lm_[A-Za-z0-9_-]{20,120}$/.test(raw.trim());
+}
+
+/** `st_` + an opaque id. Accepts a pasted URL and pulls the id out of it. */
+export function normalizeSite(raw) {
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  const fromUrl = trimmed.match(/\/sites\/(st_[A-Za-z0-9_-]+)/);
+  const id = fromUrl ? fromUrl[1] : trimmed;
+  return /^st_[A-Za-z0-9_-]+$/.test(id) ? id : null;
+}

package/src/crc32.mjs

@@ -0,0 +1,32 @@
+/**
+ * CRC-32, the one the zip format wants (IEEE 802.3 polynomial, reflected).
+ *
+ * Here rather than from a package for the reason in zip.mjs: this file is
+ * twenty lines and a dependency is a supply chain. The table is built once
+ * on first use rather than shipped as a literal, because a 256-entry array
+ * of magic numbers is unreviewable and this is not.
+ */
+
+let TABLE = null;
+
+function table() {
+  if (TABLE) return TABLE;
+  TABLE = new Int32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    TABLE[i] = c;
+  }
+  return TABLE;
+}
+
+export function crc32(buf) {
+  const t = table();
+  let c = 0 ^ -1;
+  for (let i = 0; i < buf.length; i++) {
+    c = (c >>> 8) ^ t[(c ^ buf[i]) & 0xff];
+  }
+  return (c ^ -1) >>> 0;
+}

package/src/messages.mjs

@@ -0,0 +1,60 @@
+/**
+ * The server's error codes, in words somebody can act on.
+ *
+ * WHY THIS FILE. The deploy API's gauntlet is precise and its codes are
+ * short — `zip_slip`, `absolute_path`, `too_many_entries`. Printing those
+ * verbatim to somebody publishing their first website tells them nothing
+ * except that they have done something wrong. Every line here names the
+ * cause and the fix, in that order, and never blames the customer for a
+ * limit they were never shown.
+ *
+ * Anything unmapped falls through to the raw code, which is still better
+ * than a spinner that stops. New codes on the server should appear here,
+ * but a missing one degrades to legible rather than to silence.
+ */
+
+export const MESSAGES = {
+  /* auth and scope */
+  unauthorized:
+    "That token was refused. Mint a fresh one in your dashboard under Deploy tools, then run: lemonade login",
+  not_found:
+    "No site with that id, or this token was minted for a different one. A token reaches exactly one site — check the id with: lemonade whoami",
+
+  /* traffic */
+  deploy_in_progress:
+    "A deploy for this site is already running. Wait for it to finish — it will not be long.",
+  rate_limited:
+    "Too many deploys in a row for this site. Wait a minute and try again.",
+  too_large:
+    "That folder is over the 256 MB upload limit. Publish the built output rather than the whole project — dist/ or build/ — or drop the largest files.",
+  empty_body: "There was nothing to upload.",
+  upload_interrupted:
+    "The upload stopped part-way. Nothing was published; run it again.",
+
+  /* the gauntlet — a valid request with content we will not extract */
+  zip_slip:
+    "One of the paths in that folder points outside itself. Re-export it from your editor or build tool rather than zipping it by hand.",
+  absolute_path:
+    "One of the paths is absolute. Deploy from inside the folder you want published, not from its parent.",
+  symlink:
+    "That folder contains a symbolic link. Links are not published — replace it with the real file.",
+  too_many_entries:
+    "Over 20,000 files. Publish the built output rather than the whole project.",
+  file_too_large:
+    "One file is over 25 MB. A video or a raw photo usually — host it elsewhere and link to it.",
+  quota_exceeded:
+    "That release would take the site over its 1 GB of storage.",
+  not_a_zip: "The upload did not arrive as a readable archive. Try again.",
+
+  /* the box */
+  site_not_found: "That site no longer exists.",
+  failed:
+    "The deploy failed on our side. Nothing changed — your previous version is still live. If it happens twice, email support@lemonadehost.com.",
+};
+
+export function explain(code, fallbackMessage) {
+  if (code && MESSAGES[code]) return MESSAGES[code];
+  if (fallbackMessage) return fallbackMessage;
+  if (code) return `The server refused it: ${code}`;
+  return "The server refused it.";
+}

package/src/zip.mjs

@@ -0,0 +1,212 @@
+/**
+ * A zip file, built with nothing installed.
+ *
+ * WHY NOT A LIBRARY. This package's whole promise is `npx lemonade deploy`
+ * — one command, nothing to install, on a machine that may be a laptop or a
+ * CI runner with a cold cache. Every dependency is a download before the
+ * first byte of the customer's site moves, a version to keep patched, and
+ * one more thing that can be yanked or compromised between them and their
+ * website going live. The zip format's stored (uncompressed) mode is about
+ * a hundred lines, so this package has ZERO dependencies and always will.
+ *
+ * STORED, NOT DEFLATED, and that is a deliberate trade. Deflate would need
+ * zlib streaming plumbed through the central directory; Node has zlib, so
+ * it is possible, but the win is bandwidth on an upload that is already
+ * capped at 256 MB and usually a few hundred KB of HTML. Correctness that
+ * anyone can read beats a smaller upload nobody can audit.
+ *
+ * THE ONE THING THAT MUST NOT BE WRONG: paths. The server's gauntlet
+ * rejects `..`, absolute paths, backslashes, NUL bytes and every symlink —
+ * so a bug here surfaces as a rejected deploy rather than a traversal. It
+ * is still written to emit only forward-slashed relative paths, because
+ * "the other side would catch it" is not a reason to send something wrong.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { crc32 } from "./crc32.mjs";
+
+/** Directories nobody means to publish. Skipped unless --include-hidden. */
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  ".svn",
+  ".hg",
+  ".next",
+  ".nuxt",
+  ".cache",
+  ".turbo",
+  ".vercel",
+  ".netlify",
+  ".DS_Store",
+  "__pycache__",
+]);
+
+/** Files that are somebody's secret, not their website. */
+const SKIP_FILES = new Set([
+  ".env",
+  ".env.local",
+  ".env.production",
+  ".env.development",
+  ".npmrc",
+  ".netrc",
+  "id_rsa",
+  "id_ed25519",
+  ".DS_Store",
+  "Thumbs.db",
+]);
+
+/**
+ * Every file under `root`, as { rel, abs, size }.
+ *
+ * Symlinks are SKIPPED, not followed. Following one would either escape the
+ * folder (which the server refuses anyway) or silently duplicate a file;
+ * skipping is the only behaviour that is the same on both machines.
+ */
+export function collect(root, { includeHidden = false } = {}) {
+  const out = [];
+  const skipped = { hidden: 0, symlink: 0, secret: 0 };
+
+  const walk = (dir, prefix) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (err) {
+      throw new Error(`cannot read ${dir}: ${err.message}`);
+    }
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      const name = entry.name;
+      const abs = path.join(dir, name);
+      const rel = prefix ? `${prefix}/${name}` : name;
+
+      if (entry.isSymbolicLink()) {
+        skipped.symlink++;
+        continue;
+      }
+      if (!includeHidden && SKIP_FILES.has(name)) {
+        skipped.secret++;
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (!includeHidden && (SKIP_DIRS.has(name) || name.startsWith("."))) {
+          skipped.hidden++;
+          continue;
+        }
+        walk(abs, rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!includeHidden && name.startsWith(".") && name !== ".well-known") {
+        skipped.hidden++;
+        continue;
+      }
+      const stat = fs.statSync(abs);
+      out.push({ rel, abs, size: stat.size });
+    }
+  };
+
+  walk(root, "");
+  return { files: out, skipped };
+}
+
+/* ── the zip itself ──────────────────────────────────────────────────────── */
+
+/**
+ * General-purpose bit 11: "the filename in this entry is UTF-8".
+ *
+ * Without it a reader is entitled to decode names as CP437, and Info-ZIP
+ * does — `café.html` came out of the system unzip as `caf+?.html` and then
+ * failed to create at all with "Illegal byte sequence". Every name here is
+ * written as UTF-8, so every entry says so.
+ *
+ * Found by round-tripping through a real unzip rather than through this
+ * file's own reader, which is the entire reason that test shells out.
+ */
+const UTF8_NAMES = 0x0800;
+
+const LOCAL_SIG = 0x04034b50;
+const CENTRAL_SIG = 0x02014b50;
+const END_SIG = 0x06054b50;
+
+/** DOS date/time. Zip predates Unix timestamps and still wants 1980-based. */
+function dosTime(date) {
+  const year = Math.max(1980, date.getFullYear());
+  return {
+    time: (date.getHours() << 11) | (date.getMinutes() << 5) | (date.getSeconds() >> 1),
+    date: ((year - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate(),
+  };
+}
+
+/**
+ * Build the archive in memory.
+ *
+ * In memory on purpose: the upload cap is 256 MB and the practical size of
+ * a static site is orders of magnitude under it, so a temp file would buy
+ * nothing and would leave a copy of the customer's site on disk if the
+ * process died mid-upload.
+ */
+export function zipFiles(files, { now = new Date() } = {}) {
+  const chunks = [];
+  const central = [];
+  let offset = 0;
+
+  for (const file of files) {
+    const nameBuf = Buffer.from(file.rel, "utf8");
+    const data = fs.readFileSync(file.abs);
+    const crc = crc32(data);
+    const { time, date } = dosTime(now);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(LOCAL_SIG, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(UTF8_NAMES, 6); // no encryption, no data descriptor, UTF-8 names
+    local.writeUInt16LE(0, 8); // method 0 = stored
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(date, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(data.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28); // no extra field
+
+    chunks.push(local, nameBuf, data);
+
+    const entry = Buffer.alloc(46);
+    entry.writeUInt32LE(CENTRAL_SIG, 0);
+    entry.writeUInt16LE(20, 4); // version made by
+    entry.writeUInt16LE(20, 6); // version needed
+    entry.writeUInt16LE(UTF8_NAMES, 8);
+    entry.writeUInt16LE(0, 10); // method 0 = stored
+    entry.writeUInt16LE(time, 12);
+    entry.writeUInt16LE(date, 14);
+    entry.writeUInt32LE(crc, 16);
+    entry.writeUInt32LE(data.length, 20);
+    entry.writeUInt32LE(data.length, 24);
+    entry.writeUInt16LE(nameBuf.length, 28);
+    entry.writeUInt16LE(0, 30); // extra
+    entry.writeUInt16LE(0, 32); // comment
+    entry.writeUInt16LE(0, 34); // disk
+    entry.writeUInt16LE(0, 36); // internal attrs
+    // 0644 in the high 16 bits, the way every unix zip writer does it. The
+    // server does not read this, but a customer who downloads their own
+    // archive should not find every file marked executable.
+    entry.writeUInt32LE((0o100644 << 16) >>> 0, 38);
+    entry.writeUInt32LE(offset, 42);
+    central.push(entry, nameBuf);
+
+    offset += local.length + nameBuf.length + data.length;
+  }
+
+  const centralBuf = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(END_SIG, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(files.length, 8);
+  end.writeUInt16LE(files.length, 10);
+  end.writeUInt32LE(centralBuf.length, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...chunks, centralBuf, end]);
+}