naive-framework 0.0.0-stage → 0.2.0

package/interface/boundaries.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// Error boundaries (Next.js translation P-15, E-5, E-6, E-8). Expected errors stay answers, never throws.
+//
+//   global-error  a broken venture.json, or a broken framework file (the data model, a layer or package
+//                 manifest), answers with what is wrong and the recovery steps, instead of a stack trace.
+//                 One broken venture never stops the router from finding the others.
+//   boundary      a failing check in one package is contained there: the other packages proceed, and
+//                 only a venture-level failure (venture.json, the folder structure) reaches the venture.
+//   per record    one bad record (a file that does not parse or does not match its schema) does not fail
+//                 its package's read or check: the others come back, and the bad one is named with its fix.
+//
+//   node interface/boundaries.mjs check <venture dir> [--package <name>] [--json]   the boundaries, exit 1 on a failure
+//   node interface/boundaries.mjs recover <venture dir> --confirm recover           rebuild a broken venture.json
+//
+// The router calls these through interface/writes.mjs; `mentura venture check` and `mentura <package> check`
+// run them. Never calls a model.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+const load = (f) => JSON.parse(readFileSync(f, "utf8"));
+
+// Where a JSON parse failed: line and column from the position in the message, when it gives one.
+function where(text, message) {
+  const m = message.match(/position (\d+)/);
+  if (!m && /end of JSON input/.test(message)) return ` (at the end of the file, line ${text.split("\n").length})`;
+  if (!m || /line \d+/.test(message)) return "";
+  const before = text.slice(0, Number(m[1]));
+  const line = before.split("\n").length, col = before.length - before.lastIndexOf("\n");
+  return ` (line ${line}, column ${col})`;
+}
+
+/** Why a JSON file is broken, or null. */
+export function jsonProblem(file) {
+  if (!existsSync(file)) return "is missing";
+  const text = readFileSync(file, "utf8");
+  try { JSON.parse(text); return null; } catch (e) { return `does not parse: ${String(e.message).split("\n")[0]}${where(text, String(e.message))}`; }
+}
+
+const VENTURE_SCHEMA = () => load(join(repo, "schema/venture.schema.json"));
+
+/** A minimal venture.json for a folder, from the schema's required fields: what recover writes. */
+export function minimalVenture(dir) {
+  const id = basename(dir).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "venture";
+  return { id, name: id, parent: null, phase: "discovery", owner: "self", status: "active", profile: "profile.md",
+    layers: Object.fromEntries(["purpose", "knowledge", "operations", "evidence", "governance", "interface"].map((l) => [l, existsSync(join(dir, l)) ? { location: `${l}/` } : false])) };
+}
+
+/**
+ * The venture's global error (E-8, P-15): null when venture.json is sound, else what is wrong and
+ * how to recover. Checks what the router needs before anything else runs: it parses, its required
+ * fields are there, its id and phase are valid. The full schema check stays in schema/validate.py.
+ */
+export function ventureHealth(dir) {
+  const file = join(dir, "venture.json");
+  let problem = jsonProblem(file);
+  if (!problem) {
+    const v = load(file), s = VENTURE_SCHEMA();
+    const missing = v && typeof v === "object" ? s.required.filter((k) => !(k in v)) : [];
+    if (!v || typeof v !== "object" || Array.isArray(v)) problem = "is not a JSON object";
+    else if (missing.length) problem = `is missing ${missing.join(", ")}`;
+    else if (!new RegExp(s.properties.id.pattern).test(String(v.id))) problem = `has id ${JSON.stringify(v.id)}, which is not lowercase letters, digits and hyphens`;
+    else if (!s.properties.phase.enum.includes(v.phase)) problem = `has phase ${JSON.stringify(v.phase)}, which is not one of ${s.properties.phase.enum.join(", ")}`;
+    else if (typeof v.layers !== "object" || v.layers === null) problem = "has layers that are not an object";
+  }
+  if (!problem) return null;
+  const git = spawnSync("git", ["-C", dir, "ls-files", "--error-unmatch", "venture.json"], { encoding: "utf8" }).status === 0;
+  return {
+    scope: "venture", file, problem: `venture.json ${problem}`,
+    recovery: [
+      ...(git ? [`Restore the last committed version: git -C ${dir} checkout -- venture.json`] : []),
+      `Fix it by hand: it must be a JSON object with ${VENTURE_SCHEMA().required.join(", ")}`,
+      `Or rebuild a minimal one, keeping the broken file in _private/: node interface/boundaries.mjs recover ${dir} --confirm recover`,
+      `Then check it: python3 schema/validate.py --schema venture.schema.json --file ${file}`,
+    ],
+    template: minimalVenture(dir),
+  };
+}
+
+// The framework files every route depends on. A broken one stops every route, so it is checked first.
+function frameworkFiles() {
+  const fixed = ["schema/data-model.json", "schema/need-now.json", "schema/venture.schema.json", "packages/catalog.json", "purpose/frameworks/product-anatomy/phases.json", "purpose/strategic-foundation.json", "operations/departments.json"];
+  let layers = [];
+  try { layers = load(join(repo, "schema/data-model.json")).layers.map((l) => `${l}/layer.json`); } catch {}
+  const pkgs = existsSync(join(repo, "packages")) ? readdirSync(join(repo, "packages")).map((n) => `packages/${n}/package.json`).filter((f) => existsSync(join(repo, f))) : [];
+  return [...fixed, ...layers, "schema/layer.json", ...pkgs];
+}
+
+/** The framework's global error (E-8): null when the data model and manifests parse, else the file, the problem and how to recover. */
+export function frameworkHealth() {
+  for (const f of frameworkFiles()) {
+    const problem = jsonProblem(join(repo, f));
+    if (!problem) continue;
+    return { scope: "framework", file: f, problem: `${f} ${problem}`, recovery: [
+      `Restore it: git -C ${repo} checkout -- ${f}`,
+      "Then check the data model and the manifests: node schema/check-data-model.mjs",
+      "No venture record was touched: every route stops until the framework file parses again.",
+    ] };
+  }
+  return null;
+}
+
+/** The answer a global error gives: an expected error with its recovery steps, never a throw. */
+export function globalError(h, venture) {
+  const head = h.scope === "venture" ? `${venture ?? basename(dirname(h.file))}: ${h.problem}` : `the framework is broken: ${h.problem}`;
+  return { ok: false, outcome: "error", error: [head, "Recovery:", ...h.recovery.map((s, i) => `  ${i + 1}. ${s}`)].join("\n"), global_error: h };
+}
+
+/** Per-record containment (E-6): parses each item on its own; a bad one becomes an error beside the good ones. */
+export function contain(items, parse, idOf = (x) => x.path) {
+  const values = [], errors = {};
+  for (const x of items) {
+    try { values.push([x, parse(x)]); } catch (e) { errors[idOf(x.path)] = { file: x.path, error: `${x.path} does not parse: ${String(e.message ?? e).split("\n")[0]}` }; }
+  }
+  return { values, errors };
+}
+
+function validateFile(file, schema) {
+  const p = spawnSync("python3", [join(repo, "schema/validate.py"), "--schema", schema.replace(/^schema\//, ""), "--file", file], { encoding: "utf8" });
+  return p.status === 0 ? null : (p.stdout + p.stderr).trim();
+}
+
+/**
+ * The boundaries of a venture (E-5): the venture level first (venture.json and its folder structure),
+ * then each package the venture uses, each contained. Inside a package each record is checked on its
+ * own (E-6), then the package's checks run. options.only limits it to some packages.
+ */
+export async function boundaries(dir, { only = null } = {}) {
+  const { structure, checkManifest, manifest } = await import("../schema/structure.mjs");
+  const { routes, glob } = await import("./router.mjs");
+  const { routable } = await import("../schema/structure.mjs");
+  const h = ventureHealth(dir);
+  if (h) return { ok: false, reached: "venture", venture: { ok: false, error: h.problem, recovery: h.recovery }, packages: [], proceeds: [] };
+  const s = structure(dir);
+  const verrors = [...s.errors, ...checkManifest(dir)];
+  const venture = { ok: !verrors.length, ...(verrors.length ? { errors: verrors, fix: "node schema/structure.mjs " + dir } : {}), warnings: s.warnings };
+  const m = await manifest(dir);
+  // Asked for by name, a package is checked whether or not the venture lists it.
+  const names = only ? only.filter((n) => existsSync(join(repo, "packages", n, "package.json"))) : m.packages.list.filter((p) => p.known).map((p) => p.name);
+  const rs = routes().filter((r) => r.kind === "record" && r.collection !== "list");
+  const out = [];
+  for (const name of names) {
+    // A package's failure stays in its result: an exception here is caught and reported as that package's.
+    try {
+      const pkg = load(join(repo, "packages", name, "package.json"));
+      const types = [...new Set([...(pkg.required ?? []), ...(pkg.optional ?? []), ...(pkg.records ?? [])])];
+      const records = [], checks = new Set((pkg.checks ?? []).filter((c) => /^schema\/check-[a-z-]+\.mjs$/.test(c) && c !== "schema/check-data-model.mjs" && existsSync(join(repo, c))));
+      for (const t of types) {
+        const r = rs.find((x) => x.record === t);
+        if (!r) continue;
+        for (const c of r.checks ?? []) checks.add(c);
+        const pats = r.files;
+        const hits = files(dir).filter((f) => pats.some((g) => glob(g).test(f) && routable(f, g)));
+        for (const f of hits) {
+          const problem = f.endsWith(".json") ? jsonProblem(join(dir, f)) ?? (r.schema ? validateFile(join(dir, f), r.schema) : null) : null;
+          records.push({ record: t, route: r.collection === "item" ? r.route.replace("[id]", starOf(f, pats) ?? basename(f)) : r.route, file: f, ok: !problem,
+            ...(problem ? { error: problem, fix: { schema: r.schema, template: r.template, skills: pkg.skill?.path ? [pkg.skill.path] : [] } } : {}) });
+        }
+      }
+      const ran = [...checks].map((c) => { const p = spawnSync("node", [join(repo, c), dir], { encoding: "utf8" }); return { check: c, passed: p.status === 0, output: (p.stdout + p.stderr).trim().split("\n").slice(-5).join("\n") }; });
+      const ok = records.every((x) => x.ok) && ran.every((x) => x.passed);
+      out.push({ package: name, ok, records, checks: ran });
+    } catch (e) {
+      out.push({ package: name, ok: false, error: `uncaught in ${name}: ${String(e.message ?? e).split("\n")[0]}`, records: [], checks: [] });
+    }
+  }
+  const failed = out.filter((p) => !p.ok).map((p) => p.package);
+  return { ok: venture.ok && !failed.length, reached: !venture.ok ? "venture" : failed.length ? "package" : null, venture, packages: out, contained: failed, proceeds: out.filter((p) => p.ok).map((p) => p.package) };
+}
+
+// The id a collection pattern's one star matches in a file (customers/[id].json, accounts/[id]/account.json).
+export function starOf(file, patterns) {
+  for (const g of patterns) {
+    if (!g.includes("*") || g.includes("**")) continue;
+    const m = file.match(new RegExp("^" + g.split("*").map((x) => x.replace(/[.+^${}()|[\]\\]/g, "\\$&")).join("([^/]*)") + "$"));
+    if (m) return m[1];
+  }
+  return null;
+}
+
+// A venture's files, skipping dot folders, nested ventures and the root's private folders (as the router does).
+function files(d, base = d) {
+  return existsSync(d) ? readdirSync(d, { withFileTypes: true }).flatMap((e) => e.name.startsWith(".") ? [] : e.isDirectory()
+    ? (existsSync(join(d, e.name, "venture.json")) || (d === base && e.name.startsWith("_")) ? [] : files(join(d, e.name), base)) : [join(d, e.name).slice(base.length + 1)]) : [];
+}
+
+/** Rebuilds a broken venture.json (E-8): the broken file moves to _private/, and a minimal one takes its place. */
+export function recover(dir) {
+  const h = ventureHealth(dir);
+  if (!h) return { ok: true, result: "venture.json is sound: nothing to recover" };
+  const kept = join("_private", `venture.json.broken-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+  if (existsSync(join(dir, "venture.json"))) { mkdirSync(join(dir, "_private"), { recursive: true }); renameSync(join(dir, "venture.json"), join(dir, kept)); }
+  writeFileSync(join(dir, "venture.json"), JSON.stringify(minimalVenture(dir), null, 2) + "\n");
+  return { ok: true, result: { written: "venture.json", kept: existsSync(join(dir, kept)) ? kept : null, note: "a minimal venture.json: copy back what you need from the kept file, then check it" } };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [cmd, dir] = process.argv.slice(2);
+  const opt = (n) => { const i = process.argv.indexOf(`--${n}`); return i >= 0 ? process.argv[i + 1] : undefined; };
+  if (!["check", "recover"].includes(cmd) || !dir || !existsSync(dir)) { console.error("usage: node interface/boundaries.mjs check <venture dir> [--package <name>] [--json] | recover <venture dir> --confirm recover"); process.exit(2); }
+  if (cmd === "recover") {
+    if (opt("confirm") !== "recover") { console.error("recover rewrites venture.json: pass --confirm recover"); process.exit(1); }
+    const r = recover(dir);
+    console.log(typeof r.result === "string" ? r.result : JSON.stringify(r.result, null, 2));
+    process.exit(0);
+  }
+  const fw = frameworkHealth();
+  if (fw) { console.error(globalError(fw).error); process.exit(1); }
+  const b = await boundaries(dir, { only: opt("package") ? [opt("package")] : null });
+  if (process.argv.includes("--json")) console.log(JSON.stringify(b, null, 2));
+  else {
+    console.log(`venture: ${b.venture.ok ? "ok" : `failed: ${(b.venture.errors ?? [b.venture.error]).join("; ")}`}`);
+    for (const p of b.packages) console.log(`${p.package.padEnd(14)} ${p.ok ? "ok" : `contained: ${[p.error, ...p.records.filter((x) => !x.ok).map((x) => `${x.file} ${x.error.split("\n")[0]}`), ...p.checks.filter((x) => !x.passed).map((x) => `${x.check} failed`)].filter(Boolean).join("; ")}`}`);
+  }
+  process.exit(b.ok ? 0 : 1);
+}

package/interface/brand.mjs

@@ -0,0 +1,214 @@
+// The brand and asset verbs of the CLI (mentura brand ..., mentura assets ...). Every write goes
+// through the router, so it is checked against its schema and logged in provenance; the logic lives
+// in schema/brand.mjs and schema/assets.mjs.
+//
+//   mentura assets add <public/file> --venture <id> --source <who or url> --license <id> --credit <who>
+//                                     [--alt <text>] [--decorative] [--as person]
+//                                     register a file in public/; code fills its facts (J-2, J-4)
+//   mentura assets fill --venture <id>          refill every entry's facts from its file, by code (J-4)
+//   mentura assets alt <public/file> --text <alt> --venture <id> [--as person]
+//                                     write alt text; an agent's waits for a person to confirm it
+//   mentura assets confirm <public/file> --venture <id> --by <name> [--confirm <public/file>]
+//                                     a person confirms the alt text as it stands (J-4)
+//   mentura assets remote <url> --venture <id> --license <id> --credit <who> [--id <raw id>] [--alt <text>] [--note <text>]
+//                                     record a remote image as a link with a note in raw/ (J-3)
+//   mentura assets hosts <host,host> --venture <id>   set the hosts an agent may fetch from (J-3)
+//   mentura assets check|facts --venture <id>
+//   mentura brand tokens|css|head|check|voice --venture <id> [--json]
+//   mentura brand resolve <route> --venture <id>      the brand at a route, nearer context winning (Y-5, T-2)
+//   mentura brand terms <package> --venture <id>      the terms a package sees (Y-2)
+//   mentura brand sitemap --venture <id> --base <url> [--out <file>]   sitemap.xml from the marketing sitemap (P-26)
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { call, ventureDir } from "./router.mjs";
+import { agentFromEnv, record as prov } from "./provenance.mjs";
+import { altStatement, checkAssets, facts as allFacts, factsOf, REGISTER, registerOf } from "../schema/assets.mjs";
+import { brandOf, checkBrand, resolveBrand, sitemapOf, sitemapXml, termsFor, tokens, voice } from "../schema/brand.mjs";
+
+const VERSION = "0.1.0";
+const today = () => new Date().toISOString();
+
+/** The facts code reads, in the register's shape. */
+export const factsFor = (dir, path) => {
+  const f = factsOf(readFileSync(join(dir, path)));
+  return Object.fromEntries(Object.entries({ type: f.type, width: f.width, height: f.height, sizes: f.sizes, bytes: f.bytes, sha256: f.sha256, filled_at: today() }).filter(([, v]) => v !== undefined));
+};
+
+const emptyRegister = () => ({ version: VERSION, assets: [] });
+
+/** Writes the register through the router: schema first, then provenance. */
+export async function writeRegister(venture, workspace, reg, { actor = "agent", note } = {}) {
+  return call({ venture, route: "public/assets", action: "write", input: reg, actor, workspace, via: "cli", provenance: { note } });
+}
+
+/** Registers one file in public/ with its source, license and credit; code fills its facts. */
+export async function addAsset({ venture, workspace, path, source, license, credit, alt, decorative, origin_url, design_system, actor = "agent" }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  if (!path?.startsWith("public/")) return { ok: false, error: `${path} is not in public/` };
+  if (!existsSync(join(dir, path))) return { ok: false, error: `${path} is not in ${venture}` };
+  const reg = registerOf(dir) ?? emptyRegister();
+  const entry = Object.fromEntries(Object.entries({ path, source, license, credit, alt: alt ? { text: alt, by: actor === "person" ? "person" : "agent" } : undefined, decorative: decorative || undefined, origin_url, design_system, facts: factsFor(dir, path) }).filter(([, v]) => v !== undefined));
+  reg.assets = [...reg.assets.filter((a) => a.path !== path), entry].sort((a, b) => a.path.localeCompare(b.path));
+  const w = await writeRegister(venture, workspace, reg, { actor, note: `registered ${path}; facts read by code` });
+  if (w.ok && alt && actor === "person") prov(dir, { entity: REGISTER, route: "public/assets", activity: "confirm", statement: altStatement(path, alt), agent: agentFromEnv("person", "cli"), note: `alt text of ${path} written by a person` });
+  return w.ok ? { ok: true, result: { registered: path, facts: entry.facts, alt: entry.alt ?? null } } : w;
+}
+
+/** Refills every entry's facts from its file. Only code writes facts. */
+export async function fill({ venture, workspace }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  const reg = registerOf(dir);
+  if (!reg) return { ok: false, error: `${venture} has no ${REGISTER}; register a file first: mentura assets add public/<file> ...` };
+  const changed = [], missing = [];
+  for (const a of reg.assets) {
+    if (!existsSync(join(dir, a.path))) { missing.push(a.path); continue; }
+    const f = factsFor(dir, a.path);
+    if (!a.facts || ["type", "width", "height", "bytes", "sha256"].some((k) => (a.facts[k] ?? null) !== (f[k] ?? null))) { a.facts = f; changed.push(a.path); }
+  }
+  const listed = new Set(reg.assets.map((a) => a.path));
+  const unregistered = allFacts(dir).map((x) => x.path).filter((p) => !listed.has(p));
+  if (changed.length) { const w = await writeRegister(venture, workspace, reg, { note: `facts filled by code: ${changed.join(", ")}` }); if (!w.ok) return w; }
+  return { ok: true, result: { filled: changed, missing, unregistered } };
+}
+
+/** Writes alt text. An agent's carries agent provenance until a person confirms it; a person's is confirmed as written. */
+export async function setAlt({ venture, workspace, path, text, actor = "agent" }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  const reg = registerOf(dir);
+  const a = reg?.assets.find((x) => x.path === path);
+  if (!a) return { ok: false, error: `${path} is not registered; mentura assets add ${path} first` };
+  a.alt = { text, by: actor === "person" ? "person" : "agent" };
+  const w = await writeRegister(venture, workspace, reg, { actor, note: `alt text of ${path} by ${a.alt.by}` });
+  if (!w.ok) return w;
+  if (actor === "person") prov(dir, { entity: REGISTER, route: "public/assets", activity: "confirm", statement: altStatement(path, text), agent: agentFromEnv("person", "cli"), note: `alt text of ${path} written by a person` });
+  return { ok: true, result: { path, alt: a.alt, confirmed: actor === "person" } };
+}
+
+/** A person confirms an alt text exactly as it stands. The confirmation is bound to the text: change it and it is pending again. */
+export function confirmAlt({ venture, workspace, path, by }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  if (!by) return { ok: false, error: "say who is confirming: --by <name>" };
+  const a = registerOf(dir)?.assets.find((x) => x.path === path);
+  if (!a?.alt?.text) return { ok: false, error: `${path} has no alt text to confirm` };
+  const e = prov(dir, { entity: REGISTER, route: "public/assets", activity: "confirm", statement: altStatement(path, a.alt.text), agent: agentFromEnv("person", "cli", { id: by }), note: `${by} confirmed the alt text of ${path}: ${a.alt.text}` });
+  return { ok: true, result: { path, alt: a.alt.text, confirmed_by: by, provenance: e.hash } };
+}
+
+const rawId = (url) => {
+  const u = new URL(url);
+  const slug = `${u.host}-${u.pathname.split("/").filter(Boolean).pop() ?? "image"}`.toLowerCase().replace(/\.[a-z0-9]+$/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return slug.slice(0, 60) || "remote-image";
+};
+
+/**
+ * A remote image as a link with a note in raw/ (J-3): raw/sources/<id>/source.json says where it is,
+ * text.md is the note, and the register lists it under remote. Nothing is fetched here. The platform
+ * fetcher passes `fetched` (facts of the private original) and `copy` when it kept a public copy.
+ */
+export async function addRemote({ venture, workspace, url, license, credit, id, alt, note, fetched, copy, actor = "agent" }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  try { new URL(url); } catch { return { ok: false, error: `${url} is not a URL` }; }
+  const rid = id ?? rawId(url);
+  const reg = registerOf(dir) ?? emptyRegister();
+  if (!existsSync(join(dir, "raw/sources", rid, "source.json"))) {
+    const w = await call({ venture, route: `raw/sources/${rid}`, action: "write", input: { id: rid, origin: url, title: `Remote image at ${new URL(url).host}`, fetched: today().slice(0, 10) }, actor, workspace, via: "cli", provenance: { note: "a remote image, kept as a link (J-3)" } });
+    if (!w.ok) return w;
+    const text = [`# Remote image`, "", `- Link: ${url}`, `- Host: ${new URL(url).host}`, `- License: ${license}`, `- Credit: ${credit ?? "(missing)"}`, ...(fetched ? [`- Fetched: ${fetched.type}${fetched.width ? `, ${fetched.width}x${fetched.height}` : ""}, ${fetched.bytes} bytes, sha256 ${fetched.sha256}`] : []), "",
+      copy ? `A copy is kept at ${copy}: the license allows it.` : "The venture links to this image. A full copy stays private (raw/sources/<id>/original.*, out of git) unless the license allows one.", ...(note ? ["", note] : []), ""].join("\n");
+    writeFileSync(join(dir, "raw/sources", rid, "text.md"), text);
+    prov(dir, { entity: `raw/sources/${rid}/text.md`, route: `raw/sources/${rid}`, activity: "write", agent: agentFromEnv(actor === "person" ? "person" : "agent", "cli"), note: "the note beside a remote image (J-3)" });
+  }
+  const entry = Object.fromEntries(Object.entries({ id: rid, url, license, credit, alt: alt ? { text: alt, by: actor === "person" ? "person" : "agent" } : undefined, fetched, copy }).filter(([, v]) => v !== undefined));
+  reg.remote = [...(reg.remote ?? []).filter((r) => r.url !== url), entry];
+  const w = await writeRegister(venture, workspace, reg, { actor, note: `remote image ${url}` });
+  return w.ok ? { ok: true, result: { remote: url, raw: `raw/sources/${rid}/`, copy: copy ?? null } } : w;
+}
+
+/** The hosts an agent may fetch from, a setting the platform fetcher enforces (J-3). */
+export async function setHosts({ venture, workspace, hosts, actor = "agent" }) {
+  const dir = ventureDir(venture, workspace);
+  if (!dir) return { ok: false, error: `no venture ${venture}` };
+  const reg = registerOf(dir) ?? emptyRegister();
+  reg.remote_hosts = hosts;
+  const w = await writeRegister(venture, workspace, reg, { actor, note: `hosts an agent may fetch from: ${hosts.join(", ") || "none"}` });
+  return w.ok ? { ok: true, result: { remote_hosts: hosts } } : w;
+}
+
+/** mentura brand ... and mentura assets ...: returns the exit code. */
+export async function main(argv, { workspace } = {}) {
+  const opt = (n) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] : undefined; };
+  const flag = (n) => argv.includes(`--${n}`);
+  const pos = argv.filter((a, i) => !a.startsWith("--") && !(i > 0 && argv[i - 1].startsWith("--") && !["json", "decorative"].includes(argv[i - 1].slice(2))));
+  const [group, verb, arg] = pos;
+  const venture = opt("venture");
+  const actor = opt("as") === "person" ? "person" : "agent";
+  const show = (r, text) => {
+    if (!r.ok) { console.error(r.error ?? JSON.stringify(r, null, 2)); return 1; }
+    console.log(flag("json") || text === undefined ? JSON.stringify(r.result, null, 2) : text);
+    return 0;
+  };
+  if (!venture) { console.error(`mentura ${group} ${verb ?? ""}: --venture <id> is required`); return 2; }
+  const dir = ventureDir(venture, workspace);
+  if (!dir) { console.error(`no venture ${venture}`); return 1; }
+
+  if (group === "assets") {
+    if (verb === "add") return show(await addAsset({ venture, workspace, path: arg, source: opt("source"), license: opt("license"), credit: opt("credit"), alt: opt("alt"), decorative: flag("decorative"), origin_url: opt("origin-url"), design_system: opt("design-system"), actor }), `registered: ${arg}`);
+    if (verb === "fill") { const r = await fill({ venture, workspace }); return show(r, r.ok ? `filled: ${r.result.filled.length ? r.result.filled.join(", ") : "nothing changed"}${r.result.unregistered.length ? `\nnot registered: ${r.result.unregistered.join(", ")}` : ""}` : undefined); }
+    if (verb === "alt") return show(await setAlt({ venture, workspace, path: arg, text: opt("text"), actor }), `alt text of ${arg} written by ${actor}${actor === "agent" ? "; a person confirms it with mentura assets confirm" : ""}`);
+    if (verb === "confirm") {
+      // The person types the path to confirm, as with foundation statements (EE-051).
+      if (opt("confirm") !== arg) { console.error(`not confirmed: pass --confirm ${arg} to confirm the alt text of ${arg} as it stands`); return 1; }
+      return show(confirmAlt({ venture, workspace, path: arg, by: opt("by") ?? process.env.MENTURA_PERSON }), `confirmed: alt text of ${arg}`);
+    }
+    if (verb === "remote") return show(await addRemote({ venture, workspace, url: arg, license: opt("license"), credit: opt("credit"), id: opt("id"), alt: opt("alt"), note: opt("note"), actor }), `linked: ${arg}`);
+    if (verb === "hosts") return show(await setHosts({ venture, workspace, hosts: (arg ?? "").split(",").map((h) => h.trim()).filter(Boolean), actor }), `remote_hosts: ${arg ?? "none"}`);
+    if (verb === "facts") return show({ ok: true, result: allFacts(dir) }, allFacts(dir).map((x) => `${x.path}  ${x.type}${x.width ? ` ${x.width}x${x.height}` : ""}  ${x.bytes} bytes`).join("\n") || "public/ is empty");
+    if (verb === "check") {
+      const r = checkAssets(dir);
+      if (flag("json")) console.log(JSON.stringify(r, null, 2));
+      else { for (const e of r.errors) console.log(`error    ${e}`); for (const p of r.pending) console.log(`pending  ${p.path}: alt text by ${p.by}, not confirmed by a person`); console.log(r.ok ? `assets: ${r.assets} files, ${r.remote} remote links, ${r.pending.length} alt texts pending` : `assets: ${r.errors.length} errors`); }
+      return r.ok ? 0 : 1;
+    }
+  }
+
+  if (group === "brand") {
+    const brand = brandOf(dir);
+    const need = () => { console.error(`${venture} has no brand yet: write marketing/brand.json (mentura marketing/brand template)`); return 1; };
+    if (verb === "tokens" || verb === "css" || verb === "head") {
+      if (!brand) return need();
+      const t = tokens(dir, brand);
+      return show({ ok: true, result: verb === "tokens" ? t.tokens : verb === "head" ? t.head : t.css }, verb === "css" ? t.css.trimEnd() : undefined);
+    }
+    if (verb === "resolve") { if (!brand) return need(); return show({ ok: true, result: resolveBrand(brand, arg ?? "") }); }
+    if (verb === "terms") { const t = termsFor(dir, arg); return show({ ok: true, result: t }, t.terms.map((x) => `${x.term}  (${x.from}): ${x.meaning}`).join("\n") || `no terms reach ${arg}`); }
+    if (verb === "voice") {
+      const v = opt("text") !== undefined ? { violations: (await import("../schema/brand.mjs")).voiceCheck(opt("text"), brand ? resolveBrand(brand, opt("for") ?? "").voice.rules : []) } : voice(dir, brand);
+      const lines = v.violations.map((x) => `${x.file ? `${x.file}:` : "line "}${x.line}  "${x.found}" breaks ${x.rule}${x.use ? `; use "${x.use}"` : ""}`);
+      if (flag("json")) console.log(JSON.stringify(v, null, 2)); else console.log(lines.join("\n") || "keeps to the voice rules");
+      return v.violations.length ? 1 : 0;
+    }
+    if (verb === "check") {
+      const r = checkBrand(dir);
+      if (flag("json")) console.log(JSON.stringify(r, null, 2));
+      else { for (const e of r.errors) console.log(`error  ${e}`); for (const w of r.warnings) console.log(`warn   ${w}`); console.log(r.ok ? "brand: ok" : `brand: ${r.errors.length} errors`); }
+      return r.ok ? 0 : 1;
+    }
+    if (verb === "sitemap") {
+      const s = sitemapOf(dir);
+      if (!s) { console.error(`${venture} has no marketing sitemap yet: mentura operations/marketing/sitemap run, then write it to marketing/sitemap`); return 1; }
+      let xml;
+      try { xml = sitemapXml(s.record, opt("base") ?? ""); } catch (e) { console.error(`${e.message}; pass --base https://<your site>`); return 1; }
+      if (opt("out")) { const f = resolvePath(opt("out")); mkdirSync(dirname(f), { recursive: true }); writeFileSync(f, xml); console.log(`wrote ${opt("out")}: ${s.record.pages.length} pages from ${s.file}`); return 0; }
+      process.stdout.write(xml);
+      return 0;
+    }
+  }
+  console.error(readFileSync(new URL(import.meta.url), "utf8").split("\n").filter((l) => l.startsWith("//   mentura")).map((l) => l.slice(5)).join("\n"));
+  return 2;
+}

package/interface/cli/find-venture.mjs

@@ -0,0 +1,15 @@
+// The venture a command runs on when none is named: the nearest venture.json in the current
+// directory or its parents, the way next finds the project it runs in (I-2).
+
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+export function findVenture(from = process.cwd()) {
+  for (let d = resolve(from); ; d = dirname(d)) {
+    if (existsSync(join(d, "venture.json"))) return d;
+    if (dirname(d) === d) return null;
+  }
+}
+
+/** The router's view of a venture directory: its workspace is the folder that holds it. */
+export const asRouted = (dir) => ({ workspace: dirname(dir), venture: basename(dir) });

package/interface/cli/freshness.mjs

@@ -0,0 +1,59 @@
+// The freshness commands of the mentura CLI (Revalidating, V-1 to V-8). mentura.mjs hands these
+// commands here; the logic is schema/freshness.mjs.
+//
+//   mentura revalidate <target> --venture <id> [--reason <text>] [--as person] [--json]
+//          target: tag:<route or file> (the record and what depends on it), path:<folder>,
+//          package:<name>, or a plain route or file (a tag); a plain folder is refused with the tags to use
+//   mentura revalidate --pivot --venture <id> [--reason <text>]    every assumption in the validation package
+//   mentura verify <route|folder> --venture <id> [--reason <text>] [--as person]
+//          checked and still right, unchanged: its age starts again
+//   mentura phase <phase> --venture <id> --as person [--reason <text>]
+//          the venture changes phase; records with a per-phase profile go stale
+//   mentura freshness --venture <id> [--json] [--now <iso>] [--freeze <out dir>]
+//          what is fresh, stale, expired or a live hole; --freeze writes the static shell
+
+import { resolve } from "node:path";
+import { agentFromEnv } from "../provenance.mjs";
+import { ventureDir } from "../router.mjs";
+import { freeze, freshness, phase, revalidate, verify } from "../../schema/freshness.mjs";
+
+export const COMMANDS = ["revalidate", "verify", "phase", "freshness"];
+
+/** Runs one freshness command. Returns the exit code. */
+export async function main(cmd, argv, workspace) {
+  const opt = (n) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] : undefined; };
+  const flag = (n) => argv.includes(`--${n}`);
+  const target = argv[1] && !argv[1].startsWith("--") ? argv[1] : undefined;
+  const venture = opt("venture");
+  const dir = venture && ventureDir(venture, workspace);
+  const print = (x) => console.log(typeof x === "string" ? x : JSON.stringify(x, null, 2));
+  if (!dir) { console.error(venture ? `no venture ${venture}` : `usage: mentura ${cmd} ${cmd === "freshness" ? "" : "<target> "}--venture <id>`); return venture ? 1 : 2; }
+  const by = agentFromEnv(opt("as") === "person" ? "person" : "agent", "cli");
+  const now = opt("now");
+  let r;
+  if (cmd === "revalidate") {
+    if (!target && !flag("pivot")) { console.error("usage: mentura revalidate <tag:route|path:folder|package:name|route> --venture <id>, or --pivot"); return 2; }
+    r = await revalidate(dir, flag("pivot") ? "pivot" : target, { reason: opt("reason"), by, now });
+  } else if (cmd === "verify") {
+    if (!target) { console.error("usage: mentura verify <route|folder> --venture <id>"); return 2; }
+    r = verify(dir, target, { reason: opt("reason"), by, now });
+  } else if (cmd === "phase") {
+    if (!target) { console.error("usage: mentura phase <phase> --venture <id> --as person"); return 2; }
+    // A phase change is the founder's decision: an agent may suggest it, not make it.
+    if (opt("as") !== "person") { console.error(`a phase change is a person's: run mentura phase ${target} --venture ${venture} --as person`); return 1; }
+    r = phase(dir, target, { reason: opt("reason"), by, now });
+  } else if (cmd === "freshness") {
+    if (opt("freeze")) r = await freeze(dir, resolve(opt("freeze")), { now });
+    else { const f = await freshness(dir, { now }); print(flag("json") ? f : [`${f.venture} (${f.phase}): ${f.summary.fresh} fresh, ${f.summary.stale} stale, ${f.summary.expired} expired, ${f.summary.holes} live ${f.summary.holes === 1 ? "hole" : "holes"}, of ${f.summary.records} records.`,
+      ...f.items.filter((i) => i.state !== "fresh").map((i) => `  ${i.state.padEnd(7)} ${i.route}: ${i.reasons.map((x) => x.note).join("; ")}`),
+      ...f.copies.filter((c) => c.state !== "fresh").map((c) => `  ${c.state.padEnd(7)} ${c.path} (copy of ${c.parent}): ${c.note}`),
+      ...f.warnings.map((w) => `warning: ${w}`)].join("\n")); return 0; }
+  }
+  if (!r.ok) {
+    console.error(r.error);
+    if (r.suggest) console.error(`  ${r.suggest.join("\n  ")}\n  or, for the whole folder: mentura revalidate ${r.or} --venture ${venture}`);
+    return 1;
+  }
+  print(flag("json") ? r.result : r.result.note ?? r.result);
+  return 0;
+}

package/interface/cli/guard.mjs

@@ -0,0 +1,6 @@
+// The framework's global error for the command line (E-8, interface/boundaries.mjs). Imported first, so a
+// broken data model or manifest answers with recovery steps before any module that reads it loads.
+import { frameworkHealth, globalError } from "../boundaries.mjs";
+
+const fw = frameworkHealth();
+if (fw) { console.error(globalError(fw).error); process.exit(1); }