@tokenoftrust/cli 3.1.0 → 3.3.0

package/README.md

@@ -34,6 +34,7 @@ published npm SDK.
 | `tot clone [<tenant>] [<dir>]` | **built** | Clone a store you're entitled to build on (mirrors `git clone`), with an authenticated remote configured. Dir defaults to `<tenant>`. No arg → list your stores. |
 | `tot validate` | next | Lint your store before you preview. |
 | `tot dev` | **built** | Run your store locally with save→reload — natively. |
+| `tot image add <file...>` | **built** | Upload images into your store's content-addressed image pool and print each one's `/_a/<sha256><ext>` URL to reference in content. Image files never go in the store repo. |
 | `tot preview` | **built** | Bundle your edits into a compliance-reviewed preview (validates, auto-commits the known content trees, pushes the preview ref, opens/updates a candidate PR, reports the reconcile/compliance verdict + preview URL). `tot submit` / `tot deploy` still work as teaching aliases for this same flow. |
 | `tot ship` | **built** | Promote a reconciled preview live: always shows a diff-vs-live and asks for one `[y/N]` confirm (no `--yes`, refuses outside a terminal); records an approval request if you're not authorised to ship yourself. |
 | `tot pr [list\|view\|close]` | **built** | See and manage the candidate PRs `tot preview` opens (`gh pr`-shaped). |

package/bin/tot.mjs

@@ -62,6 +62,7 @@ const COMMANDS = [
   { invocation: "capabilities", blurb: "what the platform supports, refuses, and has not built yet" },
   { invocation: "report go-live --pages <dir>", blurb: "your store's go-live readiness report, from its page-check results" },
   { invocation: "dev", blurb: "run your store locally with save→reload" },
+  { invocation: "image add <file...>", blurb: "upload images to your store's image pool; prints the /_a/ URL to use in content" },
   { invocation: "preview", blurb: "push your store to a reviewable preview" },
   { invocation: "status", blurb: "the pipeline verdict for your active tenant — progressing / stuck / idle, and why" },
   { invocation: "ship", blurb: "publish the store live — its green aggregate and approved mounted spaces as one release (plan → confirm → ship)" },
@@ -218,6 +219,11 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "image") {
+    const { run } = await import("../src/commands/image.mjs");
+    return run(rest, ctx);
+  }
+
   // dev → preview → ship. `preview` is the first-class verb; `submit`/`deploy`
   // reach the SAME preview flow as teaching aliases (preview.mjs prints a one-line
   // hint nudging the developer onto `tot preview` / `tot ship`).
@@ -358,6 +364,10 @@ function safeSubcommand(cmd, rest) {
     const sub = rest.find((t) => t && !t.startsWith("-"));
     if (sub === "scaffold" || sub === "dev") return sub;
   }
+  if (cmd === "image") {
+    const sub = rest.find((t) => t && !t.startsWith("-"));
+    if (sub === "add") return sub;
+  }
   return undefined;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/commands/image.mjs

@@ -0,0 +1,200 @@
+/**
+ * `tot image add <file...>` — put local images into your store's image pool and print the URL to
+ * reference in content.
+ *
+ * A store's repo never holds image bytes: the platform's content-addressed pool does, and content
+ * references an image as `/_a/<sha256><ext>`. This command is the on-ramp for an image you hold
+ * locally (a blog photo, a new product shot): it uploads the bytes and prints that URL. The URL is
+ * the image's own content hash, so the same bytes always print the same URL and are uploaded once —
+ * the command asks the store first and skips the upload when the pool already has them.
+ *
+ * AUTH — your own `tot login`, exchanged for a storefront viewer session (`resolveViewerTransport`).
+ * The store's admission rule decides who may upload (the people who may change what its preview
+ * serves); the CLI decides nothing.
+ *
+ * OUTPUT — one URL per file on stdout, in argument order, so `url="$(tot image add hero.jpg)"`
+ * works; progress and refusals go to stderr. `--json` prints `[{ file, url, outcome }]` instead.
+ */
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { resolveViewerTransport } from "../viewer-session.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
+
+/** The server's upload limit (`MAX_UPLOAD_BYTES`): refused here before any bytes are sent. */
+export const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+
+/** Parse `tot image` argv. Pure — unit-tested. */
+export function parseImageArgs(argv) {
+  /** @type {{ sub: string|null, files: string[], tenant: string|null, url: string|null, json: boolean, help: boolean }} */
+  const a = { sub: null, files: [], tenant: null, url: null, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--json") a.json = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+    else if (a.sub === null) a.sub = t;
+    else a.files.push(t);
+  }
+  return a;
+}
+
+export function renderUsage() {
+  return `tot image add — put images into your store's image pool
+
+Usage:
+  tot image add <file...> [--tenant <appDomain>] [--json]
+
+Uploads each image and prints the URL to reference in your content, one per line:
+
+  /_a/<sha256>.<ext>
+
+Use it anywhere content names an image (an <img src>, a page block, a product image).
+Never commit image files to your store repo — the pool holds them, your repo holds
+these URLs. The same file always prints the same URL; uploading it again is a no-op.
+
+Accepted: PNG, JPEG, GIF, WebP, AVIF, up to 8 MiB. SVG is not accepted yet.
+
+Options:
+  --tenant <appDomain>   Store to upload to. Defaults to the current checkout's store.
+  --url <origin>         Storefront origin. Defaults to $TOT_STOREFRONT_URL or the
+                         hosted storefront.
+  --json                 Print [{ file, url, outcome }] instead of bare URLs.
+  --help, -h             Show this help.`;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx — detected CLI context (ctx.tenant when in a checkout)
+ * @param {{ resolveViewerTransport?: typeof resolveViewerTransport, fetchImpl?: typeof fetch,
+ *   env?: NodeJS.ProcessEnv, out?: (s: string) => void, err?: (s: string) => void,
+ *   readFileImpl?: (path: string) => Promise<Uint8Array>, statImpl?: (path: string) => Promise<{ size: number, isFile(): boolean }> }} [deps]
+ */
+export async function run(argv, ctx, deps = {}) {
+  const out = deps.out || ((s) => process.stdout.write(`${s}\n`));
+  const err = deps.err || ((s) => process.stderr.write(`${s}\n`));
+  const env = deps.env || process.env;
+  const fetchImpl = deps.fetchImpl || fetch;
+  const resolveViewer = deps.resolveViewerTransport || resolveViewerTransport;
+  const read = deps.readFileImpl || readFile;
+  const statFile = deps.statImpl || stat;
+
+  const args = parseImageArgs(argv);
+  if (args.help || args.sub === null) {
+    (args.help ? out : err)(renderUsage());
+    return args.help ? 0 : 2;
+  }
+  if (args.sub !== "add") {
+    err(`✗ unknown \`tot image\` command: ${args.sub}\n\n  → next: tot image add <file...>`);
+    return 2;
+  }
+  if (args.files.length === 0) {
+    err("✗ no image to add.\n\n  → next: tot image add <file...>");
+    return 2;
+  }
+  const tenant = String(args.tenant || ctx?.tenant || "").trim().toLowerCase();
+  if (!tenant) {
+    err("✗ no store to upload to.\n\n  → next: pass --tenant <appDomain>, or run inside a store checkout.");
+    return 2;
+  }
+
+  // Read and hash every file first: a typo in the last path fails before anything is uploaded.
+  /** @type {{ file: string, bytes: Uint8Array, address: string }[]} */
+  const images = [];
+  for (const file of args.files) {
+    let info;
+    try {
+      info = await statFile(file);
+    } catch {
+      err(`✗ ${file}: no such file.`);
+      return 2;
+    }
+    if (!info.isFile()) {
+      err(`✗ ${file}: not a file.`);
+      return 2;
+    }
+    if (info.size > MAX_IMAGE_BYTES) {
+      err(`✗ ${file}: larger than the 8 MiB upload limit.\n\n  → next: compress or resize it, then re-run.`);
+      return 2;
+    }
+    const bytes = await read(file);
+    images.push({ file, bytes, address: createHash("sha256").update(bytes).digest("hex") });
+  }
+
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || null;
+  const transport = await resolveViewer({ tenant, env, fetchImpl, storefrontUrl });
+  if (!transport.ok) {
+    err(`✗ ${transport.message}\n\n  → next: ${transport.hint}`);
+    return 1;
+  }
+  const endpoint = `${transport.base}/api/changes/images`;
+
+  /** @type {Map<string, { url: string, outcome: string }>} */
+  const done = new Map();
+  /** @type {{ file: string, url: string|null, outcome: string, error?: string }[]} */
+  const results = [];
+  let failed = false;
+  for (const image of images) {
+    let result = done.get(image.address) ?? null;
+    if (!result) {
+      const answer = await addOne(image, { endpoint, headers: transport.authHeaders, fetchImpl });
+      if (!answer.ok) {
+        err(`✗ ${image.file}: ${answer.error}${answer.hint ? `\n\n  → next: ${answer.hint}.` : ""}`);
+        results.push({ file: image.file, url: null, outcome: "refused", error: answer.error });
+        failed = true;
+        if (answer.fatal) break;
+        continue;
+      }
+      result = { url: answer.url, outcome: answer.outcome };
+      done.set(image.address, result);
+    }
+    results.push({ file: image.file, ...result });
+    if (!args.json) {
+      out(result.url);
+      err(`  ✓ ${image.file} → ${result.url}${result.outcome === "created" ? "" : " (already in the pool)"}`);
+    }
+  }
+  if (args.json) out(JSON.stringify(results));
+  return failed ? 1 : 0;
+}
+
+/**
+ * Ask whether the pool already holds the bytes; upload them only when it does not.
+ * @returns {Promise<{ ok: true, url: string, outcome: string } | { ok: false, error: string, hint?: string, fatal?: boolean }>}
+ */
+async function addOne(image, { endpoint, headers, fetchImpl }) {
+  let res;
+  try {
+    res = await fetchImpl(`${endpoint}?address=${image.address}`, { method: "GET", headers });
+  } catch (e) {
+    return { ok: false, error: `could not reach the store: ${e?.message || e}`, hint: "check --url / your network", fatal: true };
+  }
+  let data = await res.json().catch(() => null);
+  if (res.status === 401 || res.status === 403) {
+    return { ok: false, error: "your account can't upload images to this store.", hint: refusalHint(res.status, missingGrantsOf(data)), fatal: true };
+  }
+  if (res.ok && data?.outcome === "present" && typeof data.url === "string") return { ok: true, url: data.url, outcome: "present" };
+
+  try {
+    res = await fetchImpl(endpoint, {
+      method: "POST",
+      // `application/octet-stream` keeps this out of the form-POST class the origin check guards.
+      headers: { ...headers, "content-type": "application/octet-stream", "x-tot-content-sha256": image.address },
+      body: image.bytes,
+    });
+  } catch (e) {
+    return { ok: false, error: `could not reach the store: ${e?.message || e}`, hint: "check --url / your network", fatal: true };
+  }
+  data = await res.json().catch(() => null);
+  if (res.status === 401 || res.status === 403) {
+    return { ok: false, error: "your account can't upload images to this store.", hint: refusalHint(res.status, missingGrantsOf(data)), fatal: true };
+  }
+  if (res.ok && typeof data?.url === "string") return { ok: true, url: data.url, outcome: data.outcome === "present" ? "present" : "created" };
+  const error = typeof data?.error === "string" ? data.error : `the store refused the upload (HTTP ${res.status}).`;
+  return {
+    ok: false, error,
+    hint: res.status === 429 ? "upload the rest tomorrow (UTC)"
+      : res.status >= 500 ? "retry shortly; if it persists, report it with `tot feedback`" : undefined,
+    fatal: res.status === 429,
+  };
+}

package/src/public-binaries.mjs

@@ -9,11 +9,11 @@
  *
  *   - one per entry of {@link FORBIDDEN_PUBLIC_DIRS}: any file under a directory a media download
  *     writes (`public/catalog-images/` is `catalog-images-in-repo`, `public/blog/wp-content/uploads/`
- *     is `blog-media-in-repo`). Decided from paths alone, so a caller without sizes still refuses
- *     it. This list is the one source the validators and the reconcile read; the Gitea
- *     pre-receive size guard names the same directories.
+ *     is `blog-media-in-repo`), each with its own remedy. Decided from paths alone, so a caller
+ *     without sizes still refuses it. This list is the one source the validators and the reconcile
+ *     read; the Gitea pre-receive size guard names the same directories.
  *   - `public-binary-oversized` — one raster or media file over {@link PUBLIC_BINARY_LIMITS}
- *     `maxFileBytes`.
+ *     `maxFileBytes`. An image's remedy is {@link IMAGE_ADD_COMMAND}.
  *   - `public-tree-over-budget` — the whole `public/` tree over `maxTotalBytes`.
  *
  * The size findings need `bytes`; an entry without it is judged by path only.
@@ -31,14 +31,24 @@ export const PUBLIC_BINARY_LIMITS = Object.freeze({
   maxTotalBytes: 32 * 1024 * 1024,
 });
 
+/** The kit command that moves downloaded catalog images and blog media back to their source URLs. */
+export const UNHOST_IMAGES_COMMAND = "node agency-kit/tools/import-catalog.mjs --store <checkout> --unhost-images --write";
+
+/** The command that puts an image the author holds into the platform pool and prints its `/_a/` URL. */
+export const IMAGE_ADD_COMMAND = "tot image add <file>";
+
 /**
  * The directories under `public/` a media download writes. No file under one may be committed.
+ * `remedy` is the fix for files of that kind.
  *
- * @type {ReadonlyArray<Readonly<{ dir: string, code: string, noun: string }>>}
+ * @type {ReadonlyArray<Readonly<{ dir: string, code: string, noun: string, remedy: string }>>}
  */
 export const FORBIDDEN_PUBLIC_DIRS = Object.freeze([
-  Object.freeze({ dir: "catalog-images/", code: "catalog-images-in-repo", noun: "catalog image" }),
-  Object.freeze({ dir: "blog/wp-content/uploads/", code: "blog-media-in-repo", noun: "blog media" }),
+  Object.freeze({ dir: "catalog-images/", code: "catalog-images-in-repo", noun: "catalog image", remedy: UNHOST_IMAGES_COMMAND }),
+  Object.freeze({
+    dir: "blog/wp-content/uploads/", code: "blog-media-in-repo", noun: "blog media",
+    remedy: `a new post image: ${IMAGE_ADD_COMMAND}, then reference the /_a/ URL it prints; media a migration downloaded: ${UNHOST_IMAGES_COMMAND}`,
+  }),
 ]);
 
 /** The finding codes decided from paths alone. */
@@ -49,11 +59,11 @@ export function isForbiddenPublicPath(rel) {
   return FORBIDDEN_PUBLIC_DIRS.some((d) => rel.startsWith(d.dir));
 }
 
-/** The kit command that moves downloaded catalog images and blog media back to their source URLs. */
-export const UNHOST_IMAGES_COMMAND = "node agency-kit/tools/import-catalog.mjs --store <checkout> --unhost-images --write";
-
 const RASTER_OR_MEDIA = /\.(?:jpe?g|png|gif|webp|avif|bmp|tiff?|heic|heif|ico|jxl|mp4|m4v|mov|webm|mkv|avi|mpe?g|mp3|wav|ogg|oga|m4a|aac|flac|opus)$/i;
 
+/** The formats {@link IMAGE_ADD_COMMAND} accepts. */
+const UPLOADABLE_IMAGE = /\.(?:jpe?g|png|gif|webp|avif)$/i;
+
 const mb = (bytes) => `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 
 /**
@@ -66,7 +76,7 @@ export function publicBinaryFindings(entries, limits = {}) {
   const maxFileBytes = limits.maxFileBytes ?? PUBLIC_BINARY_LIMITS.maxFileBytes;
   const maxTotalBytes = limits.maxTotalBytes ?? PUBLIC_BINARY_LIMITS.maxTotalBytes;
   const findings = [];
-  for (const { dir, code, noun } of FORBIDDEN_PUBLIC_DIRS) {
+  for (const { dir, code, noun, remedy } of FORBIDDEN_PUBLIC_DIRS) {
     const files = entries.filter((e) => e.rel.startsWith(dir));
     if (files.length === 0) continue;
     const bytes = files.reduce((n, e) => n + (e.bytes ?? 0), 0);
@@ -74,8 +84,8 @@ export function publicBinaryFindings(entries, limits = {}) {
       code,
       path: `public/${dir}`,
       message: `${files.length} ${noun} file(s)${bytes ? ` (${mb(bytes)})` : ""} are committed to the store repo; ` +
-        "images belong in the platform pool, not the repo; until platform capture owns them, keep each image at its source URL",
-      remedy: UNHOST_IMAGES_COMMAND,
+        "images belong in the platform pool, not the repo",
+      remedy,
     });
   }
   for (const e of entries) {
@@ -86,7 +96,9 @@ export function publicBinaryFindings(entries, limits = {}) {
         path: `public/${e.rel}`,
         message: `${mb(e.bytes)} raster/media file exceeds the ${mb(maxFileBytes)} per-file limit for the store repo; ` +
           "images and media belong in the platform pool",
-        remedy: "reference the file by its source URL, or compress it under the limit",
+        remedy: UPLOADABLE_IMAGE.test(e.rel)
+          ? `${IMAGE_ADD_COMMAND}, then reference the /_a/ URL it prints instead of the file`
+          : "reference the file by its source URL, or compress it under the limit",
       });
     }
   }
@@ -98,7 +110,8 @@ export function publicBinaryFindings(entries, limits = {}) {
         path: "public/",
         message: `public/ holds ${mb(total)} across ${entries.length} file(s), over the ${mb(maxTotalBytes)} store-repo budget; ` +
           "images and media belong in the platform pool",
-        remedy: "reference large or bulk assets by their source URL instead of committing them",
+        remedy: `upload images with ${IMAGE_ADD_COMMAND} and reference the /_a/ URLs it prints; ` +
+          "reference other large assets by their source URL",
       });
     }
   }