aloic 0.1.7

package/github-action.yml

@@ -0,0 +1,62 @@
+# Publish to Aloic on every push.
+#
+# Copy this to .github/workflows/deploy.yml in your repository, then add your
+# terminal key as a repository secret called ALOIC_KEY. Make one in Settings on
+# aloic.ai, or run `aloic login` and copy the key it saves.
+#
+# THE BUILD RUNS ON GITHUB'S MACHINE, not on Aloic's. That is the whole design:
+# your Actions minutes do the npm install and the build, and only the finished
+# folder is sent. It costs Aloic no compute, which is why this exists instead
+# of a "connect your repository" button that would need one.
+
+name: Deploy to Aloic
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci
+      - run: npm run build
+
+      # THE SAME INSTALLER A LAPTOP USES, rather than `npx aloic`. There is no
+      # `aloic` package on npm and there may never be: the releases are hosted
+      # at get.aloic.ai, which is the address the tool itself checks for
+      # updates. A workflow that reached for the registry would fail on its
+      # first run with a package-not-found nobody could act on.
+      - name: Install the Aloic CLI
+        run: |
+          curl -fsSL https://get.aloic.ai | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      # THE COMMIT MESSAGE ARRIVES AS AN ENVIRONMENT VARIABLE, NOT AS TEXT
+      # PASTED INTO THE SCRIPT.
+      #
+      # It used to be written straight into the command as ${{ ... }}, which
+      # GitHub substitutes before bash ever sees the line: a commit message
+      # containing a quote and a semicolon becomes a second command, running on
+      # the runner, in a step that has the deploy key in its environment.
+      # Anyone who can land a commit could have read the secret. Through `env`
+      # the message is only ever data.
+      - name: Publish
+        env:
+          ALOIC_KEY: ${{ secrets.ALOIC_KEY }}
+          COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
+        run: |
+          # The first line only: a title is a heading, and the body of a commit
+          # message belongs in the deploy's description if anywhere.
+          TITLE=$(printf '%s' "$COMMIT_MESSAGE" | head -1)
+          # Started by hand from the Actions tab, there is no commit to read.
+          [ -n "$TITLE" ] || TITLE="Deploy ${GITHUB_SHA:0:7}"
+          aloic deploy ./dist --title "$TITLE"

package/lib/api.mjs

@@ -0,0 +1,308 @@
+/* Everything this tool knows about the outside world.
+ *
+ * NO DEPENDENCIES, ANYWHERE IN THIS PACKAGE. A deploy tool is the one thing in
+ * a pipeline that has to work on a machine nobody has looked at, on whatever
+ * Node happens to be installed, months after it was written. Every dependency
+ * is a chance for that to stop being true, and everything here is one fetch
+ * and one hash, both of which Node has had built in since 18. */
+
+import { createHash } from "node:crypto";
+
+/* The same public configuration the web app ships. None of it is secret: it
+   names the project and nothing more, and every path below is still gated by
+   the database rules on whoever is signed in. */
+export const API = process.env.ALOIC_API || "https://api.aloic.ai";
+export const PROJECT = "aloicai";
+export const WEB_KEY = "AIzaSyC0yD5S7ggmIOvaWQMCr5FxJ47aeWY4BrU";
+export const RTDB = "https://aloicai-default-rtdb.firebaseio.com";
+/* A document's RESOURCE NAME, which is what the commit API wants, not a URL.
+   Passing the full https:// address is rejected with "lacks projects at index
+   0", which is a confusing way of saying the same thing. */
+const DOC = `projects/${PROJECT}/databases/(default)/documents`;
+
+async function jsonOrThrow(r, what) {
+  const text = await r.text();
+  let body = null;
+  try { body = text ? JSON.parse(text) : null; } catch { /* not json */ }
+  if (!r.ok) {
+    const why = body?.error?.message || body?.error || text.slice(0, 200) || r.statusText;
+    throw new Error(`${what}: ${why}`);
+  }
+  return body;
+}
+
+/* A deploy key, exchanged for a session that can publish to one project and
+   nothing else. See api/signin/token.js. */
+export async function signIn(key) {
+  const r = await fetch(`${API}/api/signin/token`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ deploy: key })
+  });
+  const got = await jsonOrThrow(r, "Could not use that deploy key");
+
+  const s = await fetch(
+    `https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=${WEB_KEY}`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ token: got.customToken, returnSecureToken: true })
+    }
+  );
+  const session = await jsonOrThrow(s, "Could not start a session");
+  return { ...got, idToken: session.idToken };
+}
+
+/* ---------- the file store ---------- */
+
+/* Which blobs this project already holds. Shallow, so the answer is a list of
+   names rather than every byte under them: this is the request that makes a
+   second deploy send only what changed, and asking for it the ordinary way
+   would download the entire site to find out its filenames.
+
+   Failing here means uploading everything, which is correct and merely slower.
+   It must never mean failing the deploy. */
+export async function have(uid, siteId, idToken) {
+  try {
+    const r = await fetch(
+      `${RTDB}/blobs/${uid}/${siteId}.json?shallow=true&auth=${encodeURIComponent(idToken)}`
+    );
+    if (!r.ok) return new Set();
+    const body = await r.json();
+    return new Set(body && typeof body === "object" ? Object.keys(body) : []);
+  } catch {
+    return new Set();
+  }
+}
+
+export async function putBlob(uid, siteId, idToken, hash, type, bytes) {
+  const r = await fetch(
+    `${RTDB}/blobs/${uid}/${siteId}/${hash}.json?auth=${encodeURIComponent(idToken)}`,
+    {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ t: type, b: bytes.toString("base64") })
+    }
+  );
+  await jsonOrThrow(r, `Could not store a file`);
+}
+
+/* The map goes down LAST, so a deploy id never resolves to a half written
+   site: until this lands there is nothing pointing at any of it. */
+export async function putMap(uid, siteId, idToken, deployId, map) {
+  const r = await fetch(
+    `${RTDB}/files/${uid}/${siteId}/${deployId}/__map.json?auth=${encodeURIComponent(idToken)}`,
+    {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(map)
+    }
+  );
+  await jsonOrThrow(r, "Could not finish the deploy");
+}
+
+/* ---------- the record ---------- */
+
+/* Firestore's REST shape wants every value tagged with its type. */
+function val(v) {
+  if (v === null || v === undefined) return { nullValue: null };
+  if (typeof v === "boolean") return { booleanValue: v };
+  if (typeof v === "number") {
+    return Number.isInteger(v) ? { integerValue: String(v) } : { doubleValue: v };
+  }
+  if (Array.isArray(v)) return { arrayValue: { values: v.map(val) } };
+  if (typeof v === "object") return { mapValue: { fields: fields(v) } };
+  return { stringValue: String(v) };
+}
+const fields = o => Object.fromEntries(Object.entries(o).map(([k, v]) => [k, val(v)]));
+
+/* ONE COMMIT, so a site can never point at a deploy that has no record and a
+   record can never be written without the site being pointed at it. The same
+   guarantee the browser gets from a batched write. */
+export async function publish(idToken, siteId, deployId, record, live) {
+  const writes = [
+    {
+      update: {
+        name: `${DOC}/sites/${siteId}/deployments/${deployId}`,
+        fields: fields(record)
+      }
+    }
+  ];
+  if (live) {
+    writes.push({
+      update: {
+        name: `${DOC}/sites/${siteId}`,
+        fields: fields({ liveDeployId: deployId, status: "live", updatedAt: Date.now() })
+      },
+      updateMask: { fieldPaths: ["liveDeployId", "status", "updatedAt"] }
+    });
+  }
+  const r = await fetch(
+    `https://firestore.googleapis.com/v1/projects/${PROJECT}/databases/(default)/documents:commit`,
+    {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${idToken}`
+      },
+      body: JSON.stringify({ writes })
+    }
+  );
+  await jsonOrThrow(r, "Could not record the deploy");
+}
+
+/* REVOKING A KEY FROM THE MACHINE THAT HOLDS IT.
+ *
+ * The document is named by the hash of the key, and this machine has the key,
+ * so it can work out the name without ever having been told it. Signing out
+ * without this leaves a working credential on the account for a machine that
+ * has forgotten it, which is the kind of thing nobody goes back and tidies.
+ *
+ * Best effort: a key that cannot be reached is still forgotten locally, and
+ * the account page can always revoke it by hand. */
+/* ---------- drafts ----------
+ *
+ * A draft is a build that was uploaded and deliberately not published, which
+ * makes it the one deploy the terminal has to be able to find again later: you
+ * made it in one command and you finish with it in another, possibly the next
+ * morning. Everything here works on "the newest draft of this project",
+ * because that is what somebody means when they say "the draft".
+ *
+ * Deployment records are world readable by rule, so this is an ordinary query
+ * carrying the session for consistency rather than for permission. */
+export async function newestDraft(idToken, siteId) {
+  /* NO orderBy, AND THAT IS THE POINT.
+   *
+   * The obvious query is "where draft is true, newest first, limit one", and
+   * Firestore refuses it: a filter on one field ordered by another needs a
+   * composite index, which did not exist, so this failed with a 400 every
+   * time. The caller caught it and said the project had no draft, which is the
+   * worst kind of bug, a lie told confidently about somebody's data.
+   *
+   * An equality filter on its own needs only the automatic single-field index
+   * and always works. A project has a handful of drafts at most, so twenty are
+   * fetched and the newest is chosen here, which costs nothing and removes an
+   * index from the list of things that have to be deployed for a command to
+   * work at all. */
+  const r = await fetch(
+    `https://firestore.googleapis.com/v1/${DOC}/sites/${siteId}:runQuery`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${idToken}` },
+      body: JSON.stringify({
+        structuredQuery: {
+          from: [{ collectionId: "deployments" }],
+          where: {
+            fieldFilter: {
+              field: { fieldPath: "draft" },
+              op: "EQUAL",
+              value: { booleanValue: true }
+            }
+          },
+          limit: 20
+        }
+      })
+    }
+  );
+  const rows = await jsonOrThrow(r, "Could not look for a draft");
+
+  const one = doc => {
+    const f = doc.fields || {};
+    const str = k => f[k]?.stringValue || "";
+    const num = k => Number(f[k]?.integerValue ?? f[k]?.doubleValue ?? 0);
+    return {
+      id: doc.name.split("/").pop(),
+      title: str("title"),
+      note: str("note"),
+      files: num("files"),
+      bytes: num("bytes"),
+      createdAt: num("createdAt"),
+      expiresAt: f.expiresAt?.integerValue ? num("expiresAt") : 0,
+      previewKey: str("previewKey"),
+      previewUntil: num("previewUntil")
+    };
+  };
+
+  const all = (rows || [])
+    .map(x => x.document)
+    .filter(Boolean)
+    .map(one)
+    /* A test build is not a draft. It carries an expiry and throws itself away;
+       a draft is a thing somebody is keeping. */
+    .filter(d => !d.expiresAt)
+    .sort((a, b) => b.createdAt - a.createdAt);
+
+  return all[0] || null;
+}
+
+/* Point the project at a deploy it already holds, and stop calling that deploy
+   a draft. Both in one commit, because a project pointed at a build still
+   marked "never published" is a record that argues with itself. */
+export async function publishDraft(idToken, siteId, deployId) {
+  const r = await fetch(
+    `https://firestore.googleapis.com/v1/projects/${PROJECT}/databases/(default)/documents:commit`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${idToken}` },
+      body: JSON.stringify({
+        writes: [
+          {
+            update: {
+              name: `${DOC}/sites/${siteId}/deployments/${deployId}`,
+              fields: fields({ draft: false })
+            },
+            updateMask: { fieldPaths: ["draft"] }
+          },
+          {
+            update: {
+              name: `${DOC}/sites/${siteId}`,
+              fields: fields({ liveDeployId: deployId, status: "live", updatedAt: Date.now() })
+            },
+            updateMask: { fieldPaths: ["liveDeployId", "status", "updatedAt"] }
+          }
+        ]
+      })
+    }
+  );
+  await jsonOrThrow(r, "Could not publish that draft");
+}
+
+/* A temporary address for a build that has none. The same two fields the
+   dashboard writes, and the same half hour: see previewUrl in
+   src/lib/creators.ts for why a preview is its own host. */
+export const PREVIEW_FOR = 30 * 60 * 1000;
+
+export async function setPreview(idToken, siteId, deployId, key, until) {
+  const r = await fetch(
+    `https://firestore.googleapis.com/v1/${DOC}/sites/${siteId}/deployments/${deployId}`
+      + `?updateMask.fieldPaths=previewKey&updateMask.fieldPaths=previewUntil`,
+    {
+      method: "PATCH",
+      headers: { "content-type": "application/json", authorization: `Bearer ${idToken}` },
+      body: JSON.stringify({ fields: fields({ previewKey: key, previewUntil: until }) })
+    }
+  );
+  await jsonOrThrow(r, "Could not make that preview");
+}
+
+export async function revoke(key, idToken) {
+  const hash = createHash("sha256").update(key).digest("hex");
+  const r = await fetch(
+    `https://firestore.googleapis.com/v1/projects/${PROJECT}`
+    + `/databases/(default)/documents/deployKeys/${hash}`,
+    { method: "DELETE", headers: { authorization: `Bearer ${idToken}` } }
+  );
+  return r.ok;
+}
+
+/* ---------- naming ---------- */
+
+/* The first sixteen bytes of the file's SHA-256, which is what names a blob.
+   Has to match the web app exactly or the two would never share a byte. */
+export const hashOf = buf =>
+  createHash("sha256").update(buf).digest("hex").slice(0, 32);
+
+/* A web path as one database key. The database forbids `.`, `#`, `$`, `[`, `]`
+   and `/`, and a web path is made almost entirely of the first and the last;
+   base64url survives all of them and is reversible. */
+export const keyOf = path => Buffer.from(path, "utf8").toString("base64url");

package/lib/config.mjs

@@ -0,0 +1,97 @@
+/* What this machine remembers between runs.
+ *
+ * TWO FILES, AND THE SPLIT MATTERS.
+ *
+ *   ~/.aloic/config.json    the key, which belongs to the person
+ *   ./.aloic                the project, which belongs to the directory
+ *
+ * A key is per machine: signing in once should mean every project on this
+ * computer can be deployed. Which project a folder publishes to is a fact
+ * about the folder, so it lives beside it and can be committed, which is what
+ * lets a whole team deploy the same repository without each of them choosing
+ * from a list every time.
+ *
+ * THE KEY FILE IS 0600. It is the only secret this tool holds, and a
+ * world-readable secret in a home directory is how shared machines leak.
+ * Everything here also yields to environment variables, because a build
+ * machine has no home directory worth writing to and no browser to sign in
+ * with. */
+
+import { chmod, mkdir, readFile, writeFile, unlink } from "node:fs/promises";
+import { homedir, hostname } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+const DIR = process.env.ALOIC_HOME || join(homedir(), ".aloic");
+const FILE = join(DIR, "config.json");
+const PROJECT_FILE = ".aloic";
+
+async function readJson(path) {
+  try { return JSON.parse(await readFile(path, "utf8")); }
+  catch { return null; }
+}
+
+export async function loadConfig() {
+  return (await readJson(FILE)) || {};
+}
+
+export async function saveConfig(patch) {
+  const now = { ...(await loadConfig()), ...patch };
+  await mkdir(DIR, { recursive: true });
+  await writeFile(FILE, JSON.stringify(now, null, 2) + "\n", { mode: 0o600 });
+  /* Set explicitly as well as on create, because a file that already existed
+     keeps whatever mode it had. */
+  await chmod(FILE, 0o600).catch(() => {});
+  return now;
+}
+
+export async function clearConfig() {
+  await unlink(FILE).catch(() => {});
+}
+
+export const configPath = () => FILE;
+
+/* The key, from wherever it is. The environment wins over the file so a build
+   machine and a laptop can run the same command and mean different things.
+
+   ALOIC_DEPLOY_KEY still answers, because it was the name first and a rename
+   that breaks somebody's pipeline is not a rename, it is an outage. */
+export async function findKey() {
+  for (const name of ["ALOIC_KEY", "ALOIC_DEPLOY_KEY"]) {
+    const env = process.env[name];
+    if (env && env.trim()) return { key: env.trim(), from: name };
+  }
+  const cfg = await loadConfig();
+  if (cfg.key) return { key: cfg.key, from: configPath() };
+  return null;
+}
+
+/* ---------- the project a folder publishes to ---------- */
+
+/* Walked upward from the working directory, the way every tool that keeps a
+   dotfile does, so running the command from a subfolder still finds it. */
+export async function findProject(from = process.cwd()) {
+  let at = resolve(from);
+  for (;;) {
+    const got = await readJson(join(at, PROJECT_FILE));
+    if (got?.project) return { ...got, file: join(at, PROJECT_FILE) };
+    const up = dirname(at);
+    if (up === at) return null;
+    at = up;
+  }
+}
+
+export async function saveProject(dir, project, slug) {
+  const file = join(resolve(dir), PROJECT_FILE);
+  await writeFile(
+    file,
+    JSON.stringify({ project, slug }, null, 2) + "\n"
+  );
+  return file;
+}
+
+/* What to call the key this machine makes, so a list of them in a browser is
+   a list of places rather than a list of "Untitled". */
+export function deviceName() {
+  const host = (hostname() || "").split(".")[0];
+  return (host || "Terminal").slice(0, 60);
+}

package/lib/files.mjs

@@ -0,0 +1,92 @@
+/* Which files go up, and what they are called.
+ *
+ * The same rules the browser applies to a dropped folder, because a project
+ * deployed from a terminal and the same project dropped into the dashboard
+ * have to produce the same site. */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+
+/* Sized for where the files actually go, which today is a database rather
+   than a bucket. A file is held as one base64 string, so the real ceiling is
+   a third higher than these and the whole thing has to fit in a free tier. */
+export const MAX_FILES = 400;
+export const MAX_BYTES = 25 * 1024 * 1024;
+export const MAX_ONE = 4 * 1024 * 1024;
+
+const TYPES = {
+  html: "text/html; charset=utf-8", htm: "text/html; charset=utf-8",
+  css: "text/css; charset=utf-8",
+  js: "text/javascript; charset=utf-8", mjs: "text/javascript; charset=utf-8",
+  json: "application/json; charset=utf-8", map: "application/json; charset=utf-8",
+  txt: "text/plain; charset=utf-8", xml: "application/xml; charset=utf-8",
+  svg: "image/svg+xml", png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg",
+  gif: "image/gif", webp: "image/webp", avif: "image/avif", ico: "image/x-icon",
+  mp4: "video/mp4", webm: "video/webm", mp3: "audio/mpeg", wav: "audio/wav",
+  woff: "font/woff", woff2: "font/woff2", ttf: "font/ttf", otf: "font/otf",
+  wasm: "application/wasm", pdf: "application/pdf",
+  webmanifest: "application/manifest+json"
+};
+export const typeOf = path =>
+  TYPES[path.split(".").pop()?.toLowerCase() || ""] || "application/octet-stream";
+
+/* NOT PART OF A BUILT SITE, and left behind without being counted as a
+   problem. Dependencies and version control are the two that would otherwise
+   blow past every limit above on the first attempt, and reporting them as
+   "skipped" rather than refusing the deploy is the difference between a tool
+   that works when pointed at a project root and one that lectures you. */
+const SKIP_DIR = new Set([
+  "node_modules", ".git", ".svn", ".hg", ".cache", ".next", ".nuxt",
+  ".output", ".turbo", ".parcel-cache", ".vercel", ".netlify", ".firebase",
+  "__pycache__", ".venv", "venv", ".idea", ".vscode", "coverage"
+]);
+const SKIP_FILE = /^(\.DS_Store|Thumbs\.db|npm-debug\.log.*|\.env(\..+)?)$/;
+
+export async function walk(root) {
+  const files = [];
+  const skipped = [];
+
+  async function into(dir) {
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (SKIP_DIR.has(e.name)) { skipped.push(rel(full) + "/"); continue; }
+        await into(full);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      if (SKIP_FILE.test(e.name)) { skipped.push(rel(full)); continue; }
+      const info = await stat(full);
+      if (info.size > MAX_ONE) { skipped.push(`${rel(full)} (too large)`); continue; }
+      files.push({ path: rel(full), size: info.size, full });
+    }
+  }
+  const rel = full => relative(root, full).split(sep).join("/");
+
+  const info = await stat(root).catch(() => null);
+  if (!info) throw new Error(`There is no folder at ${root}`);
+  if (info.isFile()) {
+    /* A single file is a site too: index.html on its own is a page. */
+    return { files: [{ path: root.split(sep).pop(), size: info.size, full: root }], skipped };
+  }
+  await into(root);
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  return { files, skipped };
+}
+
+export const read = f => readFile(f.full);
+
+export function tooMuch(files) {
+  const bytes = files.reduce((n, f) => n + f.size, 0);
+  if (!files.length) return "There are no files to publish in that folder.";
+  if (files.length > MAX_FILES) {
+    return `That is ${files.length} files and the limit is ${MAX_FILES}. Publish a built folder rather than a project root.`;
+  }
+  if (bytes > MAX_BYTES) {
+    return `That is ${(bytes / 1048576).toFixed(1)}MB and the limit is ${MAX_BYTES / 1048576}MB.`;
+  }
+  return null;
+}