@dcl-regenesislabs/artifacts 1.0.0

package/cli/artifacts.mjs

@@ -0,0 +1,706 @@
+#!/usr/bin/env node
+/**
+ * dcl-artifacts — publish a folder (or a single file) to the artifact host.
+ *
+ *   node cli/artifacts.mjs push ./dist --name "my demo"          # new artifact
+ *   node cli/artifacts.mjs push ./dist --id <id or URL>          # new version of it
+ *   node cli/artifacts.mjs info <id or URL>
+ *   node cli/artifacts.mjs ls
+ *   node cli/artifacts.mjs rm   <id or URL>
+ *
+ * Zero dependencies: Node's built-in fetch, node:crypto and node:fs only.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { homedir, hostname, userInfo } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  MAX_PATH_LEN,
+  newId,
+  parseId,
+  randomB64url,
+  sha256B64url,
+  userCode,
+  validateManifest,
+} from "../shared/artifact-id.js";
+
+const DEFAULT_BASE = "https://artifacts.dclregenesislabs.xyz";
+const TEMPLATE_DIR = fileURLToPath(new URL("../templates/artifact/", import.meta.url));
+const TEMPLATE_TITLE = "Artifact template";
+const MAX_FILE_BYTES = 25 * 1024 * 1024;
+const UPLOAD_CONCURRENCY = 6;
+const SKIP = new Set([".git", "node_modules", ".wrangler", ".DS_Store", "Thumbs.db", ".env", ".dev.vars", "credentials.json"]);
+
+const MIME = {
+  html: "text/html; charset=utf-8", htm: "text/html; charset=utf-8",
+  js: "text/javascript; charset=utf-8", mjs: "text/javascript; charset=utf-8",
+  css: "text/css; charset=utf-8", json: "application/json; charset=utf-8",
+  txt: "text/plain; charset=utf-8", md: "text/markdown; charset=utf-8",
+  csv: "text/csv; 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",
+  mp3: "audio/mpeg", wav: "audio/wav", ogg: "audio/ogg", mp4: "video/mp4", webm: "video/webm",
+  woff: "font/woff", woff2: "font/woff2", ttf: "font/ttf", otf: "font/otf",
+  pdf: "application/pdf", wasm: "application/wasm", zip: "application/zip",
+  glb: "model/gltf-binary", gltf: "model/gltf+json",
+};
+
+const USAGE = `dcl-artifacts — publish static artifacts to ${DEFAULT_BASE}
+
+Usage
+  dcl-artifacts login                            Sign in with your work email, in a browser
+  dcl-artifacts logout [--all]                   Revoke this machine's token (--all: every machine)
+  dcl-artifacts whoami                           Who the current token belongs to
+  dcl-artifacts new  <dir> [--name <title>]      Scaffold a single-file page from the house template
+  dcl-artifacts push <dir|file> [...] [options]  Publish a new artifact, or a new version with --id
+  dcl-artifacts info <id|url>                    Name, versions, visibility
+  dcl-artifacts ls                               Every artifact on the host, newest first
+  dcl-artifacts rm   <id|url>                    Delete it, every version, and its public link
+
+Options
+  --id <id|url>       Push as a new version of this artifact instead of creating one.
+                      The artifact's URL works as well as the bare id.
+  --name <name>       Label shown in the bar. Default: the folder/file name for a
+                      new artifact; unchanged for a new version. For 'new' it is
+                      also the page title.
+  --base <url>        Host to talk to (default: $DCL_ARTIFACTS_BASE or ${DEFAULT_BASE})
+  --token <tok>       Upload token. Normally unnecessary: login stores one.
+                      Precedence is --token, then $DCL_ARTIFACTS_TOKEN, then the
+                      saved credentials.
+  --all               push:   include normally-skipped entries (.git, node_modules, ...)
+                      logout: revoke every token issued to your email, not just this one
+  --json              Emit machine-readable JSON on stdout
+  -h, --help          Show this help
+
+URLs
+  ${DEFAULT_BASE}/<id>        latest version — needs a work-email login
+  ${DEFAULT_BASE}/<id>@2      one specific version, pinned
+  ${DEFAULT_BASE}/p/<alias>   public link, no login — switched on and off from
+                                                          the bar at the top of the page, by anyone
+                                                          who can open it. Not from here.
+
+Signing in
+  'login' opens a browser, you sign in with a @dclregenesislabs.xyz or
+  @decentraland.org email, and the token it gives back is written to
+  ~/.config/dcl-artifacts/credentials.json (mode 600). Tokens last 90 days;
+  run 'login' again to renew, 'logout' to revoke. Nothing needs to be pasted
+  anywhere, and no token is ever printed.
+
+An artifact keeps its id for life; each push with --id adds a version. Pushing
+bytes identical to the latest version records nothing. Blobs are stored by
+digest, so a new version uploads only what changed.`;
+
+function parseArgs(argv) {
+  const opts = { positional: [], name: null, id: null, base: null, token: null, all: false, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--name": opts.name = argv[++i]; break;
+      case "--id": opts.id = argv[++i]; break;
+      case "--base": opts.base = argv[++i]; break;
+      case "--token": opts.token = argv[++i]; break;
+      case "--all": opts.all = true; break;
+      case "--json": opts.json = true; break;
+      case "-h": case "--help": opts.help = true; break;
+      default:
+        if (arg.startsWith("--")) throw new Error(`unknown option: ${arg}`);
+        opts.positional.push(arg);
+    }
+  }
+  return opts;
+}
+
+/** Accepts an id or any URL on the host; fails loudly on anything else. */
+function requireId(input, what) {
+  if (!input) throw new Error(`${what} needs an artifact id or URL`);
+  const id = parseId(input);
+  if (!id) throw new Error(`not an artifact id or URL: ${input}`);
+  return id;
+}
+
+function contentTypeFor(path) {
+  const ext = path.includes(".") ? path.slice(path.lastIndexOf(".") + 1).toLowerCase() : "";
+  return MIME[ext] ?? "application/octet-stream";
+}
+
+const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+
+/** Best effort "who pushed this" — informational, the token is what authorizes. */
+function author() {
+  if (process.env.DCL_ARTIFACTS_AUTHOR) return process.env.DCL_ARTIFACTS_AUTHOR;
+  try {
+    const email = execFileSync("git", ["config", "user.email"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+    if (email) return email;
+  } catch { /* no git, or no email configured */ }
+  try { return userInfo().username; } catch { return null; }
+}
+
+async function walk(root, includeAll) {
+  const out = [];
+  async function visit(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      if (!includeAll && SKIP.has(entry.name)) continue;
+      const abs = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await visit(abs);
+      } else if (entry.isFile()) {
+        out.push({ abs, path: relative(root, abs).split(sep).join("/") });
+      }
+      // symlinks are skipped: they can escape the root or loop
+    }
+  }
+  await visit(root);
+  return out;
+}
+
+async function buildFileList(target, opts) {
+  const abs = resolve(target);
+  const info = await stat(abs).catch(() => null);
+  if (!info) throw new Error(`no such file or directory: ${target}`);
+
+  const entries = info.isDirectory()
+    ? await walk(abs, opts.all)
+    : [{ abs, path: basename(abs) }];
+  if (entries.length === 0) throw new Error(`${target} contains no files`);
+
+  const files = [];
+  for (const entry of entries) {
+    const body = await readFile(entry.abs);
+    if (body.byteLength > MAX_FILE_BYTES) {
+      throw new Error(`${entry.path} is ${(body.byteLength / 1e6).toFixed(1)} MB — the limit is 25 MB`);
+    }
+    if (entry.path.length > MAX_PATH_LEN) throw new Error(`path too long: ${entry.path}`);
+    files.push({
+      path: entry.path,
+      size: body.byteLength,
+      sha256: sha256(body),
+      contentType: contentTypeFor(entry.path),
+      _abs: entry.abs,
+    });
+  }
+
+  const list = { files: files.map(({ _abs, ...f }) => f) };
+  const problem = validateManifest(list);
+  if (problem) throw new Error(problem);
+  const bySha = new Map();
+  for (const f of files) if (!bySha.has(f.sha256)) bySha.set(f.sha256, f);
+  return { files: list.files, bySha, defaultName: basename(abs) };
+}
+
+class Client {
+  constructor(base, token) {
+    this.base = base.replace(/\/+$/, "");
+    this.token = token || null;
+  }
+  async call(method, path, { body, headers = {} } = {}) {
+    const res = await fetch(`${this.base}${path}`, {
+      method,
+      headers: {
+        ...(this.token ? { authorization: `Bearer ${this.token}` } : {}),
+        ...headers,
+      },
+      body,
+    });
+    const text = await res.text();
+    let parsed = null;
+    try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON error page */ }
+    if (!res.ok) {
+      const detail = parsed?.error ?? text.slice(0, 300) ?? res.statusText;
+      const hint = res.status === 401 ? " — run: dcl-artifacts login" : "";
+      const err = new Error(`${method} ${path} → ${res.status}: ${detail}${hint}`);
+      err.status = res.status;
+      err.body = parsed;
+      throw err;
+    }
+    return parsed;
+  }
+  json(method, path, body) {
+    return this.call(method, path, { body: JSON.stringify(body), headers: { "content-type": "application/json" } });
+  }
+}
+
+/**
+ * The template is kept as index.html + assets/ so the CSS and JS stay editable
+ * as plain files, but what we hand out is ONE self-contained index.html with
+ * both inlined — the same shape as a Claude artifact, so it works anywhere.
+ */
+async function renderTemplate(name) {
+  const read = (...parts) => readFile(join(TEMPLATE_DIR, ...parts), "utf8");
+  const [html, css, js] = await Promise.all([read("index.html"), read("assets", "dcl.css"), read("assets", "dcl.js")]);
+  const markers = [
+    ['<link rel="stylesheet" href="./assets/dcl.css">', `<style>\n${css.trim()}\n</style>`],
+    ['<script src="./assets/dcl.js"></script>', `<script>\n${js.trim()}\n</script>`],
+  ];
+  let out = html;
+  for (const [marker, replacement] of markers) {
+    if (!out.includes(marker)) throw new Error(`template is missing ${marker}`);
+    out = out.replace(marker, () => replacement); // function form: no $-pattern expansion
+  }
+  return name ? out.replaceAll(TEMPLATE_TITLE, name) : out;
+}
+
+/** Write a fresh single-file page from the house template. */
+async function scaffold(target, name, log) {
+  const dest = resolve(target);
+  const existing = await readdir(dest).catch((err) => (err.code === "ENOENT" ? [] : Promise.reject(err)));
+  if (existing.length > 0) throw new Error(`${target} is not empty — scaffold into a fresh directory`);
+  await mkdir(dest, { recursive: true });
+  await writeFile(join(dest, "index.html"), await renderTemplate(name));
+  const shown = relative(process.cwd(), dest);
+  log(`scaffolded ${!shown || shown.startsWith("..") ? dest : shown}/index.html — one self-contained file`);
+  return dest;
+}
+
+/** Run `worker` over `items` with a bounded number of in-flight promises. */
+async function pooled(items, limit, worker) {
+  const queue = [...items];
+  const runners = Array.from({ length: Math.min(limit, queue.length) }, async () => {
+    while (queue.length > 0) await worker(queue.shift());
+  });
+  await Promise.all(runners);
+}
+
+async function push(target, client, opts, log) {
+  const { files, bySha, defaultName } = await buildFileList(target, opts);
+  const creating = opts.id === null;
+  const id = creating ? newId() : requireId(opts.id, "--id");
+  const name = opts.name ?? (creating ? defaultName : undefined);
+  const total = files.reduce((sum, f) => sum + f.size, 0);
+  log(`${name ?? id}: ${files.length} file(s), ${(total / 1024).toFixed(1)} KiB`);
+
+  const state = await client.json("POST", `/_api/artifacts/${id}/status`, { files });
+  if (!creating && !state.exists) {
+    throw new Error(`no artifact ${id} on ${client.base} — drop --id to create a new one`);
+  }
+
+  if (state.missing.length === 0) {
+    log(`  every blob is already on the host`);
+  } else {
+    log(`  uploading ${state.missing.length} blob(s) (${state.present} already there)`);
+    let done = 0;
+    await pooled(state.missing, UPLOAD_CONCURRENCY, async (sha) => {
+      const file = bySha.get(sha);
+      const body = await readFile(file._abs);
+      await client.call("PUT", `/_api/artifacts/${id}/blobs/${sha}`, {
+        body,
+        headers: {
+          "x-content-type": file.contentType,
+          "content-type": "application/octet-stream",
+          "content-length": String(body.byteLength),
+        },
+      });
+      log(`  [${++done}/${state.missing.length}] ${file.path}`);
+    });
+  }
+
+  const result = await client.json("POST", `/_api/artifacts/${id}/commit`, {
+    files, base: state.current, name, author: author(),
+  });
+  if (!result.hasIndex) {
+    log(`  warning: no index.html — the artifact root will 404, link a specific file instead`);
+  }
+  log(result.unchanged
+    ? `  identical to v${result.version} — nothing recorded`
+    : `  v${result.version} of "${result.name}"${creating ? " (new artifact)" : ""}`);
+  return result;
+}
+
+function fmtWhen(iso) {
+  return new Date(iso).toLocaleString(undefined, { year: "numeric", month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" });
+}
+
+// ---------------------------------------------------------------- credentials
+
+/**
+ * Where the upload token lives once you have signed in.
+ *
+ * Deliberately NOT under ~/.dcl-artifacts: the installer treats that directory
+ * as replaceable downloaded code and `rm -rf`s it on every update, which would
+ * take the credential with it. And deliberately not inside SKILL.md, where it
+ * used to sit — that file is read into a model's prompt every time an artifact
+ * is published.
+ */
+function credentialsPath() {
+  if (process.env.DCL_ARTIFACTS_CREDENTIALS) return resolve(process.env.DCL_ARTIFACTS_CREDENTIALS);
+  const base =
+    process.platform === "win32"
+      ? (process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"))
+      : (process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"));
+  return join(base, "dcl-artifacts", "credentials.json");
+}
+
+/** Keyed by host so a dev server and production never share a token. */
+const hostKey = (base) => base.replace(/\/+$/, "");
+
+async function readCredentialsFile(log) {
+  const path = credentialsPath();
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  if (process.platform !== "win32") {
+    try {
+      const { mode } = await stat(path);
+      // Same complaint ssh makes, for the same reason.
+      if (mode & 0o077) log?.(`warning: ${path} is readable by other users — chmod 600 it`);
+    } catch { /* if it cannot be stat'd, the read below will fail anyway */ }
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function readCredentials(base, log) {
+  const file = await readCredentialsFile(log);
+  return file?.hosts?.[hostKey(base)] ?? null;
+}
+
+/**
+ * Writes through a fresh file and renames it into place. `writeFile` would
+ * follow a symlink somebody else planted and would not re-apply the mode to an
+ * existing file; `wx` refuses to open anything that already exists.
+ */
+async function writeSecret(path, body) {
+  const tmp = `${path}.${process.pid}.${randomB64url(6).replace(/[^A-Za-z0-9]/g, "")}.tmp`;
+  const handle = await open(tmp, "wx", 0o600);
+  try {
+    await handle.writeFile(body);
+  } finally {
+    await handle.close();
+  }
+  await rename(tmp, path);
+}
+
+async function saveCredentials(base, entry, log) {
+  const path = credentialsPath();
+  // The directory matters as much as the file: a 0600 file inside a world-
+  // writable directory can be unlinked and replaced with someone else's token.
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const file = (await readCredentialsFile(log)) ?? { version: 1, hosts: {} };
+  file.version = 1;
+  file.hosts = { ...file.hosts, [hostKey(base)]: entry };
+  await writeSecret(path, `${JSON.stringify(file, null, 2)}\n`);
+  return path;
+}
+
+async function forgetCredentials(base, log) {
+  const path = credentialsPath();
+  const file = await readCredentialsFile(log);
+  if (!file?.hosts?.[hostKey(base)]) return;
+  delete file.hosts[hostKey(base)];
+  if (Object.keys(file.hosts).length === 0) {
+    await rm(path, { force: true });
+    return;
+  }
+  await rm(path, { force: true });
+  await writeSecret(path, `${JSON.stringify(file, null, 2)}\n`);
+}
+
+// ---------------------------------------------------------------- login
+
+const LOGIN_TIMEOUT_MS = 120_000;
+/** Matches what the Worker will accept; anything else is rejected, not scrubbed. */
+const LABEL_RE = /[^A-Za-z0-9 ._@-]/g;
+
+const DONE_HTML = `<!doctype html>
+<meta charset="utf-8">
+<title>Signed in</title>
+<style>
+  body { margin:0; min-height:100vh; display:grid; place-items:center; background:#0f1115; color:#e6e8ee;
+         font:15px/1.6 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif; }
+  @media (prefers-color-scheme: light) { body { background:#fbfbfd; color:#1a1d24; } }
+</style>
+<p>Signed in. You can close this tab.</p>
+`;
+
+function machineLabel() {
+  let name = "";
+  try {
+    name = `${userInfo().username}@${hostname()}`;
+  } catch { /* fall through to the default below */ }
+  return name.replace(LABEL_RE, "-").slice(0, 40) || "a machine";
+}
+
+function sameSecret(a, b) {
+  const left = Buffer.from(String(a), "utf8");
+  const right = Buffer.from(String(b), "utf8");
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+function openBrowser(url) {
+  const [command, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["rundll32", ["url.dll,FileProtocolHandler", url]] // `cmd /c start` mangles &
+        : ["xdg-open", [url]];
+  try {
+    // An argv array, never a shell: the URL contains & and would otherwise
+    // break, or worse, be interpreted.
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {}); // no browser here; the URL is already printed
+    child.unref();
+  } catch { /* same */ }
+}
+
+/**
+ * Listens on a loopback port for the redirect that carries the login code.
+ *
+ * The port is bound *before* the URL is handed out, so there is no window in
+ * which another local process could claim the port we are about to advertise.
+ */
+function awaitCallback(state, onReady) {
+  return new Promise((settle, fail) => {
+    let code = null;
+    const server = createServer((req, res) => {
+      const send = (status, body = "", headers = {}) => {
+        res.writeHead(status, {
+          "content-type": "text/html; charset=utf-8",
+          "cache-control": "no-store",
+          connection: "close",
+          ...headers,
+        });
+        res.end(body);
+      };
+
+      const port = server.address()?.port;
+      // Only a genuine top-level navigation reaches this. A page doing fetch()
+      // sends an Origin; DNS rebinding needs a hostname rather than the literal.
+      if (req.method !== "GET") return send(405);
+      if (req.headers.origin) return send(403);
+      if (req.headers.host !== `127.0.0.1:${port}`) return send(403);
+
+      const url = new URL(req.url, `http://127.0.0.1:${port}`);
+      if (url.pathname === "/done") {
+        send(200, DONE_HTML);
+        return shutdown();
+      }
+      if (url.pathname !== "/cb") return send(404);
+
+      // A callback for a login we did not start: either a stray one or an
+      // attempt to hand us somebody else's token. Refuse it and keep waiting —
+      // giving up here would let any local process break every login.
+      if (!sameSecret(url.searchParams.get("state") ?? "", state)) return send(400);
+
+      code = url.searchParams.get("code") ?? "";
+      // Bounce to /done so the code is not left sitting in the address bar.
+      send(302, "", { location: "/done" });
+      clearTimeout(timer);
+      settle(code);
+      // If the browser never asks for /done, stop listening anyway.
+      grace = setTimeout(shutdown, 3000);
+    });
+
+    let grace = null;
+    const shutdown = () => {
+      clearTimeout(timer);
+      clearTimeout(grace);
+      // close() alone waits out keep-alive sockets and the process would hang.
+      server.closeAllConnections();
+      server.close();
+      if (code === null) fail(new Error("login timed out — nothing came back from the browser"));
+    };
+    const timer = setTimeout(shutdown, LOGIN_TIMEOUT_MS);
+
+    server.on("error", fail);
+    server.listen(0, "127.0.0.1", () => onReady(server.address().port));
+  });
+}
+
+async function login(base, log) {
+  // PKCE. The verifier never leaves this process — not the command line, not
+  // the URL, not the browser, not the loopback hop — so a local process that
+  // manages to see the code still cannot spend it.
+  const verifier = randomB64url(32);
+  const challenge = await sha256B64url(verifier);
+  const state = randomB64url(16);
+  const machine = machineLabel();
+  const match = await userCode(challenge);
+
+  const code = await awaitCallback(state, (port) => {
+    const query = new URLSearchParams({ port: String(port), state, challenge, label: machine });
+    const url = `${base}/cli/login?${query}`;
+    // Printed before the browser is opened, so a machine without one — over
+    // SSH, in a container — needs no special case at all.
+    log(`opening ${url}`);
+    log("");
+    log(`  the page should show this code:  ${match}`);
+    log("");
+    if (process.env.SSH_CONNECTION || process.env.SSH_TTY) {
+      log("(over SSH: open that URL on the machine you are sitting at, with the port forwarded)");
+    }
+    openBrowser(url);
+  });
+
+  const res = await new Client(base, null).json("POST", "/_api/cli/exchange", { code, verifier, machine });
+  const path = await saveCredentials(
+    base,
+    { token: res.token, email: res.email, tokenId: res.tokenId, expiresAt: res.expiresAt, machine },
+    log,
+  );
+  // Never the token itself: this lands in scrollback, tmux logs and CI output.
+  log(`saved to ${path}`);
+  return res;
+}
+
+async function logout(base, opts, log) {
+  const entry = await readCredentials(base, log);
+  if (!entry) return { revoked: 0, email: null };
+  let revoked = 0;
+  try {
+    const res = await new Client(base, entry.token).json(
+      "POST",
+      `/_api/cli/logout${opts.all ? "?all=1" : ""}`,
+      {},
+    );
+    revoked = res?.revoked ?? 0;
+  } catch (err) {
+    // Offline, or the token already expired. Forget it locally regardless —
+    // leaving it on disk would be the worse outcome.
+    log(`could not reach ${base} (${err.message}) — forgetting the token locally anyway`);
+  }
+  await forgetCredentials(base, log);
+  return { revoked, email: entry.email ?? null };
+}
+
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+  if (!command || command === "-h" || command === "--help" || command === "help") {
+    console.log(USAGE);
+    return;
+  }
+
+  const opts = parseArgs(argv.slice(1));
+  if (opts.help) { console.log(USAGE); return; }
+
+  const log = opts.json ? () => {} : (msg) => process.stderr.write(`${msg}\n`);
+
+  if (command === "new") {
+    const target = opts.positional[0];
+    if (!target) throw new Error("new needs a directory to create");
+    const dest = await scaffold(target, opts.name, log);
+    console.log(opts.json ? JSON.stringify({ dir: dest, name: opts.name ?? TEMPLATE_TITLE }) : dest);
+    return;
+  }
+
+  const base = opts.base ?? process.env.DCL_ARTIFACTS_BASE ?? DEFAULT_BASE;
+
+  if (command === "login") {
+    const res = await login(base, log);
+    console.log(
+      opts.json
+        ? JSON.stringify({ email: res.email, tokenId: res.tokenId, expiresAt: res.expiresAt }, null, 2)
+        : `signed in as ${res.email} — expires ${res.expiresAt.slice(0, 10)}`,
+    );
+    return;
+  }
+
+  if (command === "logout") {
+    const res = await logout(base, opts, log);
+    console.log(
+      opts.json
+        ? JSON.stringify(res, null, 2)
+        : res.email
+          ? `signed out ${res.email} (${res.revoked} token(s) revoked)`
+          : "not signed in",
+    );
+    return;
+  }
+
+  // Flag, then environment, then the file `login` wrote. The environment still
+  // wins so CI and scripts/smoke.sh keep working exactly as they did.
+  const token = opts.token ?? process.env.DCL_ARTIFACTS_TOKEN ?? (await readCredentials(base, log))?.token ?? "";
+  if (!token) {
+    throw new Error("not signed in — run: dcl-artifacts login");
+  }
+  const client = new Client(base, token);
+
+  switch (command) {
+    case "push": {
+      if (opts.positional.length === 0) throw new Error("push needs at least one directory or file");
+      if (opts.positional.length > 1 && (opts.name || opts.id)) {
+        throw new Error("--name and --id apply to a single artifact; drop them when pushing several");
+      }
+      const results = [];
+      for (const target of opts.positional) {
+        results.push(await push(target, client, opts, log));
+      }
+      if (opts.json) {
+        console.log(JSON.stringify(results.length === 1 ? results[0] : results, null, 2));
+      } else {
+        for (const r of results) console.log(r.url);
+      }
+      return;
+    }
+    case "info": {
+      const id = requireId(opts.positional[0], "info");
+      const info = await client.call("GET", `/_api/artifacts/${id}`);
+      if (opts.json) { console.log(JSON.stringify(info, null, 2)); return; }
+      console.log(`${info.name}\n  ${info.url}`);
+      console.log(`  ${info.visibility}${info.public ? ` — ${info.public.url} (on since ${fmtWhen(info.public.at)} by ${info.public.by})` : " — work-email login"}`);
+      for (const v of [...info.versions].reverse()) {
+        console.log(`  v${v.n}${v.n === info.current ? " (latest)" : "        "}  ${fmtWhen(v.at)}  ${v.files} file(s), ${(v.bytes / 1024).toFixed(1)} KiB${v.by ? `  by ${v.by}` : ""}`);
+      }
+      return;
+    }
+    case "whoami": {
+      const me = await client.call("GET", "/_api/whoami");
+      if (opts.json) { console.log(JSON.stringify(me, null, 2)); return; }
+      console.log(
+        me.kind === "user"
+          ? `${me.email} — token ${me.tokenId}, expires ${me.expiresAt.slice(0, 10)}`
+          : "the shared upload token — no identity attached",
+      );
+      return;
+    }
+    case "ls":
+    case "list": {
+      const res = await client.call("GET", "/_api/artifacts");
+      if (opts.json) { console.log(JSON.stringify(res, null, 2)); return; }
+      if (res.artifacts.length === 0) console.log("no artifacts");
+      for (const a of res.artifacts) {
+        console.log(`${a.id}  v${String(a.current).padEnd(3)} ${a.visibility.padEnd(7)} ${fmtWhen(a.updatedAt)}  ${a.name}`);
+      }
+      for (const id of res.legacy) console.log(`${id.padEnd(36)}  legacy — rm it and push again`);
+      return;
+    }
+    case "rm":
+    case "delete": {
+      const id = requireId(opts.positional[0], "rm");
+      const res = await client.call("DELETE", `/_api/artifacts/${id}`);
+      console.log(`deleted ${res.deleted} object(s) from ${res.id}${res.revokedAlias ? ` and its public link` : ""}`);
+      return;
+    }
+    default:
+      throw new Error(`unknown command: ${command}\n\n${USAGE}`);
+  }
+}
+
+// Run only when invoked as a program, so the module stays importable. Through
+// resolved paths: npm exposes the bin as a symlink in node_modules/.bin, and
+// argv[1] is the symlink while import.meta.url is the file it points at.
+function invokedDirectly() {
+  try {
+    return realpathSync(process.argv[1] ?? "") === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  main().catch((err) => {
+    process.stderr.write(`error: ${err.message}\n`);
+    process.exit(1);
+  });
+}