@mosetta/cli 0.0.0-stage → 0.0.9

package/src/host/nodeFileSystem.mjs

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import { FileSystem } from '@mosetta/build/fileSystem';
+
+/**
+ * Node implementation of the file port: the real FS, read-only.
+ *
+ * Resolution no longer lives here: `createRequire` contexts died together with the `resolve`
+ * method — packages are resolved by `PackagesResolver` from the scanner catalog, identically in
+ * all environments.
+ */
+export class NodeFileSystem extends FileSystem {
+  readFile(file, encoding = null) {
+    return encoding ? fs.readFileSync(file, encoding) : fs.readFileSync(file);
+  }
+
+  exists(file) {
+    return fs.existsSync(file);
+  }
+
+  readDir(dir) {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .map((e) => ({ name: e.name, isDirectory: e.isDirectory() }));
+  }
+
+  isDirectory(dir) {
+    try {
+      return fs.statSync(dir).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  realPath(file) {
+    return fs.realpathSync(file);
+  }
+
+  mtimeMs(file) {
+    try {
+      return fs.statSync(file).mtimeMs;
+    } catch {
+      return null;
+    }
+  }
+
+}

package/src/log.mjs

@@ -0,0 +1,114 @@
+import { formatBytes } from '@mosetta/build';
+
+export { formatBytes };
+
+// Sectioned CLI log — the single tool for all output sources.
+// Every source ([cli], [typescript], [esbuild], [tiles], [workerd], [assets], ...) has a
+// stable color; the HEADER prints once per run of lines from one source (source change → blank
+// separator line + new header), the body starts on a new line with no prefixes — copying from
+// the console does not drag `[typescript]` on every line. Body and header share the section
+// color (header is bold); outside a TTY — plain text.
+const PALETTE = {
+  cli: 36, // cyan — orchestration: build summaries, dev addresses
+  typescript: 34, // blue — tsc gate and the dev companion
+  esbuild: 31, // red — compile errors (syntax and other hard failures, not types)
+  tiles: 32, // green — the tiles being built: rebuilds, watcher, environment warnings
+  workerd: 35, // magenta — render process output
+  assets: 33, // yellow — build asset table
+};
+const FALLBACK = [96, 94, 92, 95, 93, 90];
+
+let lastSection = null;
+
+function colorOf(name) {
+  if (PALETTE[name] != null) return PALETTE[name];
+  let h = 0;
+  for (const ch of name) h = ((h * 31) + ch.charCodeAt(0)) >>> 0;
+  return FALLBACK[h % FALLBACK.length];
+}
+
+/**
+ * No-op log sink for embedders (e.g. tests) that opt out of CLI summary chatter.
+ * Errors keep their own loud channels ([esbuild], [workerd]) and are never routed here.
+ */
+export function silentLog() {}
+
+/** Source logger: `const log = sectionLog('typescript'); log('line or a block\nof lines')` */
+export function sectionLog(name) {
+  const color = colorOf(name);
+  return (text) => {
+    const tty = Boolean(process.stdout.isTTY);
+    const paint = (s, bold) => (tty ? `\x1b[${bold ? '1;' : ''}${color}m${s}\x1b[0m` : s);
+    let out = '';
+    if (lastSection !== name) {
+      out += `${lastSection === null ? '' : '\n'}${paint(`[${name}]`, true)}\n`;
+      lastSection = name;
+    }
+    for (const line of String(text).replace(/\n+$/, '').split('\n')) {
+      // lines already styled (tables paint their own separators) are not repainted
+      out += line.includes('\x1b[') ? `${line}\n` : `${paint(line, false)}\n`;
+    }
+    process.stdout.write(out);
+  };
+}
+
+// table separator colors (deliberately different): vertical │ — gray, horizontal ─┼ — blue
+const SEP_V_COLOR = 90;
+const SEP_H_COLOR = 34;
+
+/**
+ * Aligned table with no dependencies: formatTable(['module', 'size'], [['a', '1.2 KB']]).
+ * A cell may be multi-line ('component\nscript') — a logical row expands into several physical
+ * ones (missing cells pad with emptiness), horizontal separators go BETWEEN logical rows,
+ * vertical ones between columns on every line.
+ */
+export function formatTable(headers, rows) {
+  const tty = Boolean(process.stdout.isTTY);
+  const paint = (s, color) => (tty ? `\x1b[${color}m${s}\x1b[0m` : s);
+  const expand = (row) => {
+    const split = row.map((c) => String(c).split('\n'));
+    const height = Math.max(...split.map((c) => c.length));
+    return Array.from({ length: height }, (_, i) => split.map((c) => c[i] ?? ''));
+  };
+  const logical = [headers, ...rows].map(expand);
+  const physical = logical.flat();
+  const widths = headers.map((_, i) => Math.max(...physical.map((r) => r[i].length)));
+  const sepV = paint(' │ ', SEP_V_COLOR);
+  const line = (r) => r.map((c, i) => (i === r.length - 1 ? c : c.padEnd(widths[i]))).join(sepV).trimEnd();
+  const rule = paint(widths.map((w) => '─'.repeat(w)).join('─┼─'), SEP_H_COLOR);
+  const out = [];
+  logical.forEach((block, i) => {
+    if (i > 0) out.push(rule); // after the header and between logical rows
+    out.push(...block.map(line));
+  });
+  return out.join('\n');
+}
+
+/**
+ * Report over the LOGICAL build artifacts (report from build()): a table per distribution —
+ * a row per module, facets/sizes stacked inside the row — plus a table of dependency artifacts.
+ */
+export function renderBuildReport(report) {
+  if (!report) return null;
+  const blocks = [];
+  for (const d of report.distributions) {
+    const total = d.modules.reduce((s, m) => s + m.facets.reduce((x, f) => x + f.bytes, 0), 0);
+    const rows = d.modules.map((m) => [
+      m.name,
+      m.facets.map((f) => f.facet).join('\n'),
+      m.facets.map((f) => formatBytes(f.bytes)).join('\n'),
+      m.facets.map((f) => f.info).join('\n'),
+    ]);
+    blocks.push(`tile palette ${d.namespace}@${d.version} — ${d.modules.length} tile(s), total ${formatBytes(total)}\n`
+      + formatTable(['tile', 'side', 'size', 'info'], rows));
+  }
+  if (report.dependencies.length) {
+    const total = report.dependencies.reduce((s, r) => s + r.bytes, 0);
+    const rows = [...report.dependencies]
+      .sort((a, b) => b.bytes - a.bytes)
+      .map((r) => [r.specifier, r.version, formatBytes(r.bytes)]);
+    blocks.push(`package tiles — ${report.dependencies.length}, total ${formatBytes(total)}\n`
+      + formatTable(['package', 'version', 'size'], rows));
+  }
+  return blocks.length ? blocks.join('\n\n') : null;
+}

package/src/login.mjs

@@ -0,0 +1,136 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+// `mosetta login`: the CLI signs in to a platform installation the way `gh auth login` does — by a
+// code the person approves in the browser (a device flow). The CLI asks the cabinet for a sign-in,
+// shows the code and opens the cabinet's page for it; the person, signed in there, allows it; the
+// CLI, polling with a secret only it holds, gets a token of the platform. The token is kept in the
+// person's config folder (readable by them only), one per installation — `MOSETTA_TOKEN` (CI, an
+// assistant) wins over it.
+
+/**
+ * Where an app is published: the `publish` entry of its mosetta.json, by target (`default`, `stage`)
+ * — `{ "cabinet": "https://mosetta.org", "api": "https://api.mosetta.org", "target": "platform" }`.
+ * Not a secret: it is committed with the app. An explicit `cabinet` (a flag) wins over it.
+ */
+export function publishTargetOf(root, name = 'default', { cabinet } = {}) {
+  let entry = null;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(root, 'mosetta.json'), 'utf8'));
+    entry = manifest?.publish?.[name] ?? null;
+  } catch { /* no manifest — the flags must say it */ }
+  const chosen = { ...(entry ?? {}), ...(cabinet ? { cabinet } : {}) };
+  if (!chosen.cabinet) {
+    throw new Error(`no installation to sign in to: ${path.join(root, 'mosetta.json')} has no publish.${name}.cabinet — or name one with --cabinet <origin>`);
+  }
+  return chosen;
+}
+
+/** where the CLI keeps what is the person's: `$MOSETTA_CONFIG_DIR`, or `~/.config/mosetta` */
+export function configDir(env = process.env) {
+  if (env.MOSETTA_CONFIG_DIR) return env.MOSETTA_CONFIG_DIR;
+  return path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'mosetta');
+}
+
+const credentialsFile = (dir) => path.join(dir, 'credentials.json');
+
+function readCredentials(dir) {
+  try {
+    const value = JSON.parse(fs.readFileSync(credentialsFile(dir), 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+/** the credentials file rewritten whole: the folder and the file the person's only */
+function writeCredentials(dir, all) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = credentialsFile(dir);
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, file);
+}
+
+/** an installation by its cabinet's origin — `https://mosetta.org` */
+export const installationOf = (cabinet) => new URL(cabinet).origin;
+
+/** the token this CLI acts with on an installation: `MOSETTA_TOKEN`, else the one `login` kept, else null */
+export function tokenFor(cabinet, { env = process.env, dir = configDir(env), now = new Date() } = {}) {
+  if (env.MOSETTA_TOKEN) return { token: env.MOSETTA_TOKEN, from: 'MOSETTA_TOKEN' };
+  const kept = readCredentials(dir)[installationOf(cabinet)];
+  if (!kept?.token) return null;
+  if (kept.expiresAt && Date.parse(kept.expiresAt) <= now.getTime()) return null;
+  return { token: kept.token, from: credentialsFile(dir), login: kept.login, expiresAt: kept.expiresAt };
+}
+
+export function forget(cabinet, { dir = configDir() } = {}) {
+  const all = readCredentials(dir);
+  const key = installationOf(cabinet);
+  if (!(key in all)) return false;
+  delete all[key];
+  writeCredentials(dir, all);
+  return true;
+}
+
+/** the person's browser on the page — best effort: the address is printed either way */
+export function openInBrowser(url) {
+  const [command, args] = process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => undefined);
+    child.unref();
+  } catch { /* no browser here — the printed address is enough */ }
+}
+
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Sign in to the installation whose cabinet is `cabinet`; keeps the token and answers who signed in.
+ * @param fetchImpl the network (tests answer from the cabinet's own handler)
+ */
+export async function login(cabinet, {
+  label = `CLI on ${os.hostname()}`,
+  fetchImpl = fetch,
+  sleep = pause,
+  open = openInBrowser,
+  log = (line) => console.log(line),
+  dir = configDir(),
+  now = () => new Date(),
+} = {}) {
+  const origin = installationOf(cabinet);
+  const asked = await fetchImpl(`${origin}/__mosetta__/sign-in`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ label }),
+  });
+  if (!asked.ok) throw new Error(`login: ${origin} did not start a sign-in (${asked.status} ${(await asked.text()).slice(0, 200)})`);
+  const { userCode, pollSecret, verifyUrl, interval, expiresAt } = await asked.json();
+  log(`Open ${verifyUrl} and allow the sign-in — the page shows the code ${userCode}.`);
+  open(verifyUrl);
+  const every = Math.max(1, Number(interval) || 3) * 1000;
+  while (now().getTime() < Date.parse(expiresAt)) {
+    await sleep(every);
+    const polled = await fetchImpl(`${origin}/__mosetta__/sign-in/poll`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ pollSecret }),
+    });
+    if (polled.status === 202) {
+      await polled.arrayBuffer();
+      continue;
+    }
+    if (!polled.ok) throw new Error(`login: the sign-in was not allowed in time, or was used already — run mosetta login again (${polled.status})`);
+    const got = await polled.json();
+    const all = readCredentials(dir);
+    all[origin] = { token: got.token, via: got.user.via, login: got.user.login, label: got.label, expiresAt: got.expiresAt };
+    writeCredentials(dir, all);
+    log(`Signed in to ${origin} as ${got.user.login}; the token lives until ${got.expiresAt.slice(0, 10)} (revoke it in the cabinet's access tokens).`);
+    return { login: got.user.login, expiresAt: got.expiresAt };
+  }
+  throw new Error('login: the sign-in was not allowed in time — run mosetta login again');
+}

package/src/push.mjs

@@ -0,0 +1,99 @@
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { manifestOf } from '@mosetta/build/release';
+import { writeTar } from '@mosetta/build/archive';
+import { builtDistribution } from './deploy.mjs';
+import { publishTargetOf, tokenFor } from './login.mjs';
+import { sectionLog } from './log.mjs';
+
+// `mosetta push`: the built distribution released THROUGH a platform — no store key on this machine.
+// The CLI describes the build (both catalogs, every file with its SHA-256, the commit it comes
+// from), asks the platform's API for a plan, and sends the files the plan asks for; the platform
+// checks every byte and runs the release rules on its side, writing with keys only it holds. Where
+// to push is the app's `publish` target in mosetta.json; who pushes is the token `mosetta login`
+// kept (or MOSETTA_TOKEN).
+
+/** where the build comes from, as git says — the platform keeps it with the release */
+export function provenanceOf(root) {
+  const git = (...args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  try {
+    return { commit: git('rev-parse', 'HEAD'), branch: git('rev-parse', '--abbrev-ref', 'HEAD'), dirty: git('status', '--porcelain') !== '' };
+  } catch {
+    // not a repository: the platform hears of no commit, and a target that takes commits only refuses
+    return { commit: null, branch: null, dirty: null };
+  }
+}
+
+async function answerOf(res) {
+  const text = await res.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { error: { message: text.slice(0, 300) } };
+  }
+}
+
+/** a refusal or failure of the API, said as it said it */
+function failureOf(res, body, doing) {
+  if (body?.refused) return new Error(body.refused);
+  const message = body?.error?.message ?? body?.error?.code ?? `${res.status}`;
+  if (res.status === 401) return new Error(`push: the platform did not take the token (${message}) — mosetta login`);
+  return new Error(`push: ${doing} failed — ${message}`);
+}
+
+/**
+ * @param root app root (holds dist/ after `mosetta build`, and mosetta.json with its publish targets)
+ * @param target the publish target's name in mosetta.json (`default`, `stage`)
+ */
+export async function push(root, {
+  target = 'default',
+  dryRun = false,
+  fetchImpl = fetch,
+  env = process.env,
+  dir,
+  provenance = provenanceOf(root),
+  log = sectionLog('push'),
+} = {}) {
+  const where = publishTargetOf(root, target);
+  if (!where.api || !where.target) throw new Error(`push: publish.${target} in ${path.join(root, 'mosetta.json')} names no "api" and "target"`);
+  const held = tokenFor(where.cabinet, { env, ...(dir ? { dir } : {}) });
+  if (!held) throw new Error(`push: not signed in to ${where.cabinet} — mosetta login${target === 'default' ? '' : ` --target ${target}`}`);
+  const build = builtDistribution(path.join(root, 'dist'));
+  const manifest = await manifestOf(build, provenance);
+  // a palette's target has a slash of its own (`palettes/<brand>`): each part encoded, the slash kept
+  const base = `${new URL(where.api).origin}/v1/code/${where.target.split('/').map(encodeURIComponent).join('/')}`;
+  const authorization = `Bearer ${held.token}`;
+
+  const planned = await fetchImpl(`${base}/plan`, {
+    method: 'POST',
+    headers: { authorization, 'content-type': 'application/json' },
+    body: JSON.stringify(manifest),
+  });
+  const plan = await answerOf(planned);
+  if (!planned.ok) throw failureOf(planned, plan, 'planning');
+  const asked = [...plan.need.public.map((key) => ['public', key]), ...plan.need.private.map((key) => ['private', key])];
+  log(`release into "${where.target}" at ${where.api}: new ${plan.fresh.join(', ') || 'nothing'}; ${plan.same} tile(s) as deployed, `
+    + `${plan.rebuilt} rebuilt only for a new framework, ${plan.kept} published package(s) kept; ${asked.length} file(s) to send`);
+  if (plan.conflicts.length) {
+    log(`${plan.conflicts.length} tile(s) differ from their released copies — refused unless only the framework's versions changed: `
+      + `${[...new Set(plan.conflicts.map((c) => c.release))].join(', ')}`);
+  }
+  if (dryRun) return { dryRun: true, ...plan };
+
+  const entries = [{ name: 'release.json', data: new TextEncoder().encode(JSON.stringify(manifest)) }];
+  for (const [side, key] of asked) {
+    const data = await build.read(side, key);
+    if (data === null) throw new Error(`push: ${side} ${key} was asked for but is not in the build`);
+    entries.push({ name: `${side}/${key}`, data });
+  }
+  const pushed = await fetchImpl(`${base}/push`, {
+    method: 'POST',
+    headers: { authorization, 'content-type': 'application/x-tar' },
+    body: writeTar(entries),
+  });
+  const answer = await answerOf(pushed);
+  if (!pushed.ok || !answer.ok) throw failureOf(pushed, answer, 'pushing');
+  const { release } = answer;
+  log(`released ${release.fresh.join(', ') || 'nothing new'} into "${where.target}" (${release.uploaded.public} public, ${release.uploaded.private} private file(s)); trace ${release.id}`);
+  return release;
+}

package/src/scanner.mjs

@@ -0,0 +1,26 @@
+import { createRequire } from 'node:module';
+import { FRAMEWORK_RESOLUTIONS } from '@mosetta/build/packagesResolver';
+
+/**
+ * The node side of the scanner: ONLY framework resolutions — files from the CLI's own
+ * installation (systemjs etc. — its dependencies) that the build mixes in by itself.
+ *
+ * The package-catalog scanner itself is portable and lives in `@mosetta/build/scanner`: it
+ * takes the file port and uses only sources and pnpm-lock.yaml from it — exactly what the
+ * scanner isolate will have. Only `createRequire` remains here, because resolving the tool's
+ * installation is an environment capability; in the isolate a pre-seeded map in the plan
+ * replaces it.
+ */
+const cliRequire = createRequire(import.meta.url);
+
+/** File for a framework specifier from the CLI installation (for frameworkDir in harnesses). */
+export function frameworkFileOf(specifier) {
+  return cliRequire.resolve(specifier);
+}
+
+/** `catalog.framework`: ready answers for the FRAMEWORK_RESOLUTIONS list. */
+export function frameworkResolutions() {
+  const framework = {};
+  for (const spec of FRAMEWORK_RESOLUTIONS) framework[spec] = cliRequire.resolve(spec);
+  return framework;
+}

package/src/serverPackage.mjs

@@ -0,0 +1,75 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createWasmEngine } from './wasmEngine.mjs';
+
+const require = createRequire(import.meta.url);
+
+// @mosetta/server holds the render runtime (TS, OOP). The CLI consumes it as SOURCE via esbuild (same
+// convention as the @mosetta/* libraries) — bundled for workerd (the worker) or imported in node
+// (SSG renderer / tests). No compiled dist is ever emitted: `.ts` is the canonical form.
+//
+// Resolution prefers node module resolution via the package's `exports` map (`./worker`, `./render`), so
+// it keeps working once @mosetta/server is a real dependency / published to npm (installed under
+// node_modules by package NAME, not sibling-dir layout). It falls back to the monorepo sibling path for
+// now, because the package isn't yet symlinked into node_modules (nothing declares it as a dependency).
+const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SIBLING_SERVER_DIR = path.resolve(CLI_ROOT, '..', 'server');
+
+function resolveServerEntry(subpath, siblingFile) {
+  try {
+    return require.resolve(`@mosetta/server/${subpath}`);
+  } catch {
+    return path.join(SIBLING_SERVER_DIR, 'src', siblingFile);
+  }
+}
+
+export const SERVER_WORKER_ENTRY = resolveServerEntry('worker', 'worker.ts');
+// dev entry: render + static serving from a Durable Object on a single port
+export const SERVER_DEV_WORKER_ENTRY = resolveServerEntry('devWorker', 'devWorker.ts');
+export const SERVER_RENDER_ENTRY = resolveServerEntry('render', 'renderNode.ts');
+
+// Bundle a server entry to a single ESM string. platform 'neutral' = Web API (workerd); 'node' = in-process.
+// In-process (node) execution of a server entry — tests, the static render: workerd's own
+// `cloudflare:workers` does not exist there. The host entrypoint only needs the base class to
+// exist; node has no ctx.exports, so the runner falls back to in-process capabilities.
+const WORKERS_SHIM = {
+  name: 'mosetta-cloudflare-workers-shim',
+  setup(build) {
+    build.onResolve({ filter: /^cloudflare:workers$/ }, () => ({ path: 'cloudflare:workers', namespace: 'mosetta-cf-shim' }));
+    build.onLoad({ filter: /.*/, namespace: 'mosetta-cf-shim' }, () => ({
+      contents: 'export class WorkerEntrypoint { constructor(ctx, env) { this.ctx = ctx; this.env = env; } }',
+      loader: 'js',
+    }));
+  },
+};
+
+export async function bundleServer(entry, { platform = 'neutral', mode = 'development' } = {}) {
+  // with the same wasm engine as the distributive: the CLI has no native binaries
+  const { bundle } = await createWasmEngine();
+  const result = await bundle({
+    entryPoints: [entry],
+    bundle: true,
+    format: 'esm',
+    platform,
+    target: 'es2022',
+    write: false,
+    minify: mode === 'production',
+    // the Workers runtime's own modules (WorkerEntrypoint for the store capability) — workerd
+    // provides them at run time; in node a shim stands in
+    ...(platform === 'node' ? { plugins: [WORKERS_SHIM] } : { external: ['cloudflare:*'] }),
+  });
+  return result.outputFiles[0].text;
+}
+
+// Bundle + import a server entry for in-process (node) use; returns { module, cleanup }.
+export async function importServer(entry, { platform = 'node' } = {}) {
+  const code = await bundleServer(entry, { platform });
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mosetta-server-'));
+  const file = path.join(dir, 'entry.mjs');
+  fs.writeFileSync(file, code);
+  const module = await import(pathToFileURL(file).href);
+  return { module, cleanup: () => fs.rmSync(dir, { recursive: true, force: true }) };
+}

package/src/staticBuild.mjs

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { build } from '@mosetta/build';
+import { PackagesResolver } from '@mosetta/build/packagesResolver';
+import { loadBuildConfig } from './buildConfigLoader.mjs';
+import { scanCatalog } from '@mosetta/build/scanner';
+import { frameworkResolutions } from './scanner.mjs';
+import { importServer, SERVER_RENDER_ENTRY } from './serverPackage.mjs';
+import { sectionLog, silentLog, renderBuildReport } from './log.mjs';
+import { evaluateModule } from './evaluate.mjs';
+
+const isAbstractRoute = (pattern) => typeof pattern === 'string' && pattern.includes('{');
+
+/**
+ * Static publish / SSG. Produces a deployable static distributive in <root>/dist, split
+ * into two top-level folders so nothing crosses the trust boundary on deploy:
+ *   dist/public/   — client-facing static (modules + co-located loaders + dependencies + non-devOnly
+ *                    prefabs + per-concrete-route <name>.html + pages.json). Its CONTENTS deploy to the CDN.
+ *   dist/private/  — server-only artifacts (server-action monoliths). Deploy to the private store (S3), not
+ *                    the public CDN. Empty for a pure SPA (server modules are devOnly / excluded here).
+ * devOnly assets and the per-file pages/ collection are NOT shipped. Abstract (param) routes would go into
+ * a catch-all index.html — deferred until the client router + patterns land.
+ */
+/**
+ * The ids a tile host descriptor names — read from a file or an https address — as a build takes
+ * them for `released`: a tile palette built for a platform skips the palettes and published
+ * packages the platform already holds.
+ */
+export async function releasedIdsOf(where) {
+  const text = /^https?:\/\//.test(where)
+    ? await (async () => {
+      const res = await fetch(where);
+      if (!res.ok) throw new Error(`build: --released ${where} answered ${res.status}`);
+      return res.text();
+    })()
+    : fs.readFileSync(where, 'utf8');
+  const entries = JSON.parse(text);
+  if (!Array.isArray(entries)) throw new Error(`build: --released ${where} is not a tile host descriptor (an array)`);
+  return new Set(entries.map((entry) => entry?.id).filter((id) => typeof id === 'string'));
+}
+
+/** `released` — the ids already where the build goes (releasedIdsOf): not built again */
+export async function staticBuild(root, { outDir, log = sectionLog('cli'), quiet = false, fileSystem, engine, frameworkDir, released = null }) {
+  // quiet (tests): summaries stay silent, build errors are still thrown as exceptions
+  const out = quiet ? silentLog : log;
+  const dist = outDir || path.join(root, 'dist');
+  const buildConfig = await loadBuildConfig(root);
+  // the package catalog is fresh per build iteration; the prod closure sees dependencies only:
+  // importing a devDep fails with a "move it to dependencies" explanation
+  const resolver = new PackagesResolver({
+    fileSystem,
+    catalog: { ...scanCatalog({ fileSystem, root, frameworkDir, includeDev: false }), framework: frameworkResolutions() },
+  });
+  const state = await build(root, { mode: 'production', log: out, fileSystem, resolver, engine, frameworkDir, buildConfig, evaluate: evaluateModule, released });
+  const report = renderBuildReport(state.report);
+  if (report && !quiet) sectionLog('assets')(report);
+
+  fs.rmSync(dist, { recursive: true, force: true });
+  const write = (rel, content) => {
+    const p = path.join(dist, rel);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content);
+  };
+
+  // 1) copy build artifacts as-is (FS keys already carry the public/ | private/ split), EXCEPT the
+  // per-file public/pages/ collection and devOnly prefabs. system.js is a public/ artifact → shipped here.
+  const devOnlyPrefabFiles = new Set(
+    state.prefabs.filter((p) => p.json && p.json.devOnly).map((p) => `public/prefabs/${p.namespace}/${p.name}.json`),
+  );
+  for (const [rel, content] of state.fs.files) {
+    if (rel.startsWith('public/pages/')) continue; // pages collection is not shipped (HTML + pages.json instead)
+    if (devOnlyPrefabFiles.has(rel)) continue; // devOnly prefabs excluded from the distributive
+    write(rel, content);
+  }
+
+  // 2) pages → HTML (concrete routes, flat in public/) + pages.json (all non-devOnly pages, for SPA router).
+  // Render via @mosetta/server (the SAME renderer the dev worker uses), with relative refs.
+  const { module: server, cleanup } = await importServer(SERVER_RENDER_ENTRY);
+  const shipped = state.pages.filter((p) => !(p.json && p.json.devOnly));
+  // the unified entity catalog: boot tags + preload + styles + the slice into the envelope
+  const catalog = JSON.parse(state.fs.get('public/modules.json') ?? '[]');
+  let html = 0;
+  let skipped = 0;
+  try {
+    for (const pg of shipped) {
+      if (isAbstractRoute(pg.json.pattern)) { skipped++; continue; } // → index.html later (deferred)
+      write(`public/${pg.name}.html`, server.renderPage(pg.json, { providerOrigin: '', catalog }));
+      html++;
+    }
+  } finally {
+    cleanup();
+  }
+  write('public/pages.json', JSON.stringify(shipped.map((p) => p.json)));
+
+  out(`mosetta build → ${path.relative(root, dist) || dist}: ${html} page HTML, ${shipped.length} page(s) in pages.json`
+    + (skipped ? `, ${skipped} abstract route(s) skipped (need index.html — deferred)` : '')
+    + `, ${state.pages.length - shipped.length} devOnly page(s) excluded`);
+
+  return { dist, htmlCount: html, pages: shipped.length };
+}