@tokenoftrust/cli 2.4.2 → 2.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "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/publication-spaces.mjs

@@ -0,0 +1,223 @@
+/**
+ * A tenant's publication topology as a developer's workspace sees it: one ROOT repository serving
+ * `/`, plus any MOUNTED spaces — each its own repository serving one mount (`/blog`, `/docs`).
+ *
+ * The platform declares the topology; the workspace only records what it was told, in
+ * `.tot/publication-spaces.json` (written by `tot clone`, never committed — the root repo's git
+ * excludes it, and the `spaces/` folder each mounted space is cloned into). Every command that needs
+ * to know which repository owns a URL or a file reads it through this module, so `tot validate`,
+ * `tot dev`, `tot clone` and the change router answer the same way.
+ *
+ * Mount matching mirrors packages/public-runtime/src/publication-space.ts
+ * (`publicationMountMatchesPath`): a mount owns itself and everything below it, segment-wise and
+ * case-sensitively; the longest matching mount wins and `/` owns what nothing else claims.
+ * apps/storefront/src/config/publicationSpaceOwnership.test.ts pins the two together.
+ *
+ * Dependency-free: the published CLI ships it as-is.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Where `tot clone` puts each mounted space, relative to the root checkout: `spaces/<spaceId>/`. */
+export const SPACES_DIR = "spaces";
+/** The workspace's record of the declared topology, relative to the root checkout. */
+export const TOPOLOGY_FILE = ".tot/publication-spaces.json";
+export const TOPOLOGY_VERSION = 1;
+
+const SPACE_ID = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/;
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * @typedef {{ forge: string, repo: string, defaultBranch: string }} SpaceSource
+ * @typedef {{ id: string, mount: string, visibility: "public"|"internal", source: SpaceSource,
+ *   aliases?: string[], collections?: Record<string, string> }} TopologySpace
+ * @typedef {{ version: 1, tenant: string, spaces: TopologySpace[] }} Topology
+ */
+
+/** A mount in canonical form: leading `/`, no trailing `/` except the root itself. Null when not a mount. */
+export function normalizeMount(value) {
+  if (typeof value !== "string" || !value.startsWith("/") || /[?#\\]/.test(value)) return null;
+  const trimmed = value.replace(/\/+$/, "");
+  if (!trimmed) return "/";
+  if (trimmed.split("/").slice(1).some((seg) => !seg || seg === "." || seg === "..")) return null;
+  return trimmed;
+}
+
+/** A request path reduced to what routing reads: no origin, query or fragment; NFC; single slashes. */
+export function normalizeRequestPath(value) {
+  let path = String(value ?? "").trim();
+  try {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path)) path = new URL(path).pathname;
+  } catch {
+    return null;
+  }
+  path = path.replace(/[?#].*$/, "");
+  if (!path.startsWith("/")) path = `/${path}`;
+  try {
+    path = decodeURIComponent(path);
+  } catch {
+    return null;
+  }
+  path = path.normalize("NFC").replace(/\/{2,}/g, "/");
+  return path;
+}
+
+/** Does `mount` own `path` (both normalized)? A mount owns itself and every path below it. */
+export function mountMatchesPath(mount, path) {
+  if (mount === "/") return true;
+  return path === mount || path === `${mount}/` || path.startsWith(`${mount}/`);
+}
+
+/**
+ * Parse a recorded topology. Throws with the reason on anything malformed — a half-read topology
+ * would route a change to the wrong repository.
+ * @param {unknown} input
+ * @returns {Topology}
+ */
+export function parseTopology(input) {
+  const raw = /** @type {any} */ (input);
+  if (!isObject(raw) || raw.version !== TOPOLOGY_VERSION || typeof raw.tenant !== "string" || !raw.tenant ||
+    !Array.isArray(raw.spaces)) {
+    throw new Error(`${TOPOLOGY_FILE} is not a version-${TOPOLOGY_VERSION} topology`);
+  }
+  const ids = new Set();
+  const mounts = new Set();
+  const spaces = raw.spaces.map((space, index) => {
+    const at = `${TOPOLOGY_FILE} spaces[${index}]`;
+    if (!isObject(space) || typeof space.id !== "string" || !SPACE_ID.test(space.id)) throw new Error(`${at}: invalid id`);
+    const mount = normalizeMount(space.mount);
+    if (!mount) throw new Error(`${at}: invalid mount`);
+    if (space.visibility !== "public" && space.visibility !== "internal") throw new Error(`${at}: invalid visibility`);
+    const source = space.source;
+    if (!isObject(source) || typeof source.forge !== "string" || typeof source.repo !== "string" || !source.repo ||
+      typeof source.defaultBranch !== "string" || !source.defaultBranch) throw new Error(`${at}: invalid source`);
+    if (ids.has(space.id)) throw new Error(`${at}: duplicate id ${space.id}`);
+    if (mounts.has(mount)) throw new Error(`${at}: duplicate mount ${mount}`);
+    ids.add(space.id);
+    mounts.add(mount);
+    const aliases = Array.isArray(space.aliases) ? space.aliases.map(normalizeMount).filter(Boolean) : [];
+    return {
+      id: space.id,
+      mount,
+      visibility: space.visibility,
+      source: { forge: source.forge, repo: source.repo, defaultBranch: source.defaultBranch },
+      ...(aliases.length ? { aliases } : {}),
+      ...(isObject(space.collections) ? { collections: { ...space.collections } } : {}),
+    };
+  });
+  if (spaces.filter((space) => space.mount === "/").length !== 1) {
+    throw new Error(`${TOPOLOGY_FILE}: exactly one space must own "/"`);
+  }
+  return { version: TOPOLOGY_VERSION, tenant: raw.tenant, spaces };
+}
+
+/**
+ * Build a topology from the platform's declared-space list (`GET /api/publication-spaces`, whose
+ * rows carry `id`, `visibility`, `canonicalMount`, `source` and `routes`).
+ * @param {string} tenant
+ * @param {unknown} rows
+ * @returns {Topology}
+ */
+export function topologyFromDeclaredSpaces(tenant, rows) {
+  if (!Array.isArray(rows)) throw new Error("the platform returned no publication-space list");
+  return parseTopology({
+    version: TOPOLOGY_VERSION,
+    tenant,
+    spaces: rows.map((row) => ({
+      id: row?.id,
+      mount: row?.routes?.canonicalMount ?? row?.canonicalMount,
+      visibility: row?.visibility,
+      source: row?.source,
+      aliases: Array.isArray(row?.routes?.aliases) ? row.routes.aliases.map((alias) => alias?.from) : undefined,
+      collections: row?.routes?.collections,
+    })),
+  });
+}
+
+/** The root space (owns `/`; `parseTopology` guarantees exactly one). @param {Topology} topology */
+export function rootSpace(topology) {
+  return /** @type {TopologySpace} */ (topology.spaces.find((space) => space.mount === "/"));
+}
+
+/** The mounted spaces, longest mount first. @param {Topology} topology */
+export function mountedSpaces(topology) {
+  return topology.spaces.filter((space) => space.mount !== "/").sort((a, b) => b.mount.length - a.mount.length);
+}
+
+/**
+ * Which space owns a URL path: the longest canonical mount (or alias) that owns it, else the root.
+ * Returns null for a path that cannot be read as a URL path.
+ * @param {Topology} topology
+ * @param {string} urlPath
+ * @returns {{ space: TopologySpace, via: "mount"|"alias"|"root" } | null}
+ */
+export function owningSpace(topology, urlPath) {
+  const path = normalizeRequestPath(urlPath);
+  if (path === null) return null;
+  /** @type {{ space: TopologySpace, via: "mount"|"alias", mount: string } | null} */
+  let best = null;
+  for (const space of topology.spaces) {
+    if (space.mount === "/") continue;
+    /** @type {Array<[string, "mount"|"alias"]>} */
+    const claims = [[space.mount, "mount"], ...(space.aliases ?? []).map((alias) => /** @type {[string, "alias"]} */ ([alias, "alias"]))];
+    for (const [mount, via] of claims) {
+      if (mountMatchesPath(mount, path) && (!best || mount.length > best.mount.length)) best = { space, via, mount };
+    }
+  }
+  if (best) return { space: best.space, via: best.via };
+  return { space: rootSpace(topology), via: "root" };
+}
+
+/** A mounted space's working tree, relative to the root checkout. @param {TopologySpace} space */
+export function spaceDir(space) {
+  return space.mount === "/" ? "" : `${SPACES_DIR}/${space.id}`;
+}
+
+/**
+ * Which space a workspace file belongs to, from its path relative to the root checkout:
+ * `spaces/<id>/...` is that space's, everything else is the root's. A file under `spaces/` naming
+ * no declared space belongs to none (null) — it must not be routed anywhere.
+ * @param {Topology} topology
+ * @param {string} relPath
+ * @returns {{ space: TopologySpace, path: string } | null}
+ */
+export function spaceForWorkspaceFile(topology, relPath) {
+  const rel = String(relPath).replace(/\\/g, "/").replace(/^\.\//, "");
+  if (rel === SPACES_DIR || rel.startsWith(`${SPACES_DIR}/`)) {
+    const [, id, ...rest] = rel.split("/");
+    const space = topology.spaces.find((candidate) => candidate.mount !== "/" && candidate.id === id);
+    return space ? { space, path: rest.join("/") } : null;
+  }
+  return { space: rootSpace(topology), path: rel };
+}
+
+/** Read a workspace's recorded topology, or null when the workspace records none. Throws when malformed. */
+export function readWorkspaceTopology(workspace) {
+  const file = join(workspace, TOPOLOGY_FILE);
+  if (!existsSync(file)) return null;
+  return parseTopology(JSON.parse(readFileSync(file, "utf8")));
+}
+
+/**
+ * Record a topology in a root checkout, and keep it — and the cloned spaces — out of the root
+ * repository: both are listed in the checkout's own `.git/info/exclude`, never in a committed file.
+ */
+export function writeWorkspaceTopology(workspace, topology) {
+  const file = join(workspace, TOPOLOGY_FILE);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(parseTopology(topology), null, 2)}\n`);
+  excludeFromRootRepo(workspace, [`/${TOPOLOGY_FILE}`, `/${SPACES_DIR}/`]);
+}
+
+/** Append patterns to `<workspace>/.git/info/exclude`, once each. No-op outside a git checkout. */
+export function excludeFromRootRepo(workspace, patterns) {
+  const gitDir = join(workspace, ".git");
+  if (!existsSync(gitDir)) return;
+  const file = join(gitDir, "info", "exclude");
+  mkdirSync(dirname(file), { recursive: true });
+  const current = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const lines = new Set(current.split("\n").map((line) => line.trim()));
+  const missing = patterns.filter((pattern) => !lines.has(pattern));
+  if (!missing.length) return;
+  appendFileSync(file, `${current && !current.endsWith("\n") ? "\n" : ""}${missing.join("\n")}\n`);
+}