@shortlink-org/portolan 0.2.1 → 0.2.3

package/scripts/local-discovery.mjs

@@ -0,0 +1,378 @@
+import {
+  lstatSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { basename, join, posix, relative, resolve, sep } from "node:path";
+
+const SKIP = new Set([".git", ".portolan", "build", "dist", "node_modules", "target", "vendor"]);
+const MAX_FILES = 12_000;
+const MAX_COMPONENTS = 100;
+const MAX_SOURCE_BYTES = 1024 * 1024;
+
+function safeRoot(workspace, input) {
+  if (typeof input !== "string" || !input.trim()) throw new Error("Project path is required.");
+  const clean = input.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
+  if (clean.startsWith("/") || clean.split("/").includes("..")) throw new Error("Project path must stay inside this repository.");
+  const workspaceReal = realpathSync(workspace);
+  const targetReal = realpathSync(resolve(workspaceReal, clean));
+  if (targetReal !== workspaceReal && !targetReal.startsWith(`${workspaceReal}${sep}`)) {
+    throw new Error("Project path resolves outside this repository.");
+  }
+  const root = relative(workspaceReal, targetReal).replaceAll(sep, "/") || ".";
+  return { root, absolute: targetReal };
+}
+
+/** A UTF-8 source file inside the served workspace, never outside it. */
+export function readLocalSource(workspace, input) {
+  if (typeof input !== "string" || !input.trim()) throw new Error("Source path is required.");
+  const clean = input.trim().replaceAll("\\", "/").replace(/^\.\//, "");
+  if (clean.includes("\0") || clean.startsWith("/") || clean.split("/").includes("..")) {
+    throw new Error("Source path must stay inside this repository.");
+  }
+  const workspaceReal = realpathSync(workspace);
+  const targetReal = realpathSync(resolve(workspaceReal, clean));
+  if (targetReal !== workspaceReal && !targetReal.startsWith(`${workspaceReal}${sep}`)) {
+    throw new Error("Source path resolves outside this repository.");
+  }
+  const stat = statSync(targetReal);
+  if (!stat.isFile()) throw new Error("Source path is not a file.");
+  if (stat.size > MAX_SOURCE_BYTES) throw new Error("Source file is larger than the 1 MB preview limit.");
+  const bytes = readFileSync(targetReal);
+  if (bytes.includes(0)) throw new Error("Source file is binary.");
+  let content;
+  try {
+    content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new Error("Source file is not UTF-8 text.");
+  }
+  return {
+    path: relative(workspaceReal, targetReal).replaceAll(sep, "/"),
+    content,
+  };
+}
+
+export function walk(root) {
+  const files = new Set();
+  const pending = [{ absolute: root, relative: "" }];
+  while (pending.length && files.size < MAX_FILES) {
+    const current = pending.pop();
+    for (const entry of readdirSync(current.absolute, { withFileTypes: true })) {
+      if (SKIP.has(entry.name) || (entry.isDirectory() && entry.name.startsWith("."))) continue;
+      const name = current.relative ? `${current.relative}/${entry.name}` : entry.name;
+      const absolute = join(current.absolute, entry.name);
+      const stat = lstatSync(absolute);
+      if (stat.isSymbolicLink()) continue;
+      if (stat.isDirectory()) pending.push({ absolute, relative: name });
+      else if (stat.isFile()) files.add(name);
+      if (files.size >= MAX_FILES) break;
+    }
+  }
+  return files;
+}
+
+export function slug(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+export function matches(files, pattern) {
+  return [...files].filter((name) => pattern.test(name)).sort((a, b) => a.split("/").length - b.split("/").length || a.localeCompare(b));
+}
+
+function compactDirectories(paths) {
+  const directories = [...new Set(paths.map((name) => posix.dirname(name)))].sort((a, b) => a.length - b.length);
+  return directories.filter((dir, index) => !directories.some((parent, other) => other < index && (dir === parent || dir.startsWith(`${parent}/`))));
+}
+
+const COMPONENT_MARKERS = new Map([
+  ["go.mod", "Go"],
+  ["package.json", "Node.js"],
+  ["Cargo.toml", "Rust"],
+  ["pom.xml", "Java"],
+  ["build.gradle", "Java"],
+  ["build.gradle.kts", "Kotlin"],
+  ["manage.py", "Django"],
+]);
+
+function componentCandidates(files) {
+  const roots = new Map();
+  for (const name of files) {
+    const marker = posix.basename(name);
+    const technology = COMPONENT_MARKERS.get(marker);
+    if (!technology) continue;
+    const path = posix.dirname(name);
+    const key = path === "." ? "." : path;
+    if (key.split("/").some((segment) => ["fixture", "fixtures", "test", "tests", "testdata"].includes(segment.toLowerCase()))) continue;
+    const found = roots.get(key) ?? { path: key, markers: new Set(), technologies: new Set() };
+    found.markers.add(marker);
+    found.technologies.add(technology);
+    roots.set(key, found);
+  }
+  return [...roots.values()]
+    .sort((a, b) => a.path === "." ? -1 : b.path === "." ? 1 : a.path.localeCompare(b.path))
+    .slice(0, MAX_COMPONENTS)
+    .map((candidate) => {
+      const base = candidate.path === "." ? "repository root" : posix.basename(candidate.path);
+      return {
+        path: candidate.path,
+        name: base.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((part) => part[0]?.toUpperCase() + part.slice(1)).join(" ") || base,
+        markers: [...candidate.markers].sort(),
+        technologies: [...candidate.technologies].sort(),
+      };
+    });
+}
+
+function titleFromSlug(value) {
+  const acronyms = new Set(["api", "cli", "grpc", "http"]);
+  return value.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((part) => acronyms.has(part.toLowerCase()) ? part.toUpperCase() : part[0]?.toUpperCase() + part.slice(1)).join(" ") || value;
+}
+
+// cmd/* is a convention, not an architectural boundary by itself: many Go
+// repositories keep migrations and administrative tools there. A runnable is
+// promoted to a deployable only when build/deployment evidence independently
+// names the same entrypoint.
+function goDeployables(root, files) {
+  if (!files.has("go.mod")) return [];
+  const mains = new Map();
+  for (const name of matches(files, /^cmd\/[^/]+\/[^/]+\.go$/)) {
+    let source = "";
+    try { source = readFileSync(join(root, name), "utf8"); } catch { continue; }
+    if (!/^\s*package\s+main\b/m.test(source) || !/\bfunc\s+main\s*\(/.test(source)) continue;
+    const component = name.split("/")[1];
+    const found = mains.get(component) ?? [];
+    found.push(name);
+    mains.set(component, found);
+  }
+
+  const buildFiles = matches(files, /(^|\/)(?:Dockerfile|[^/]+\.Dockerfile|Makefile|[^/]*compose[^/]*\.ya?ml|[^/]+\.ya?ml)$/i);
+  const out = [];
+  for (const [component, entrypoints] of [...mains].sort(([a], [b]) => a.localeCompare(b))) {
+    const escaped = component.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const target = new RegExp(`(?:^|[\\s"'=])(?:\\./)?cmd/${escaped}(?=$|[\\s"'])`, "m");
+    const corroboration = [];
+    for (const name of buildFiles) {
+      let source = "";
+      try { source = readFileSync(join(root, name), "utf8"); } catch { continue; }
+      if (target.test(source)) corroboration.push(name);
+    }
+    out.push({
+      slug: slug(component),
+      name: titleFromSlug(component),
+      path: `cmd/${component}`,
+      kind: "service",
+      confidence: corroboration.length ? "high" : "medium",
+      evidence: [...entrypoints, ...corroboration],
+    });
+  }
+  return out;
+}
+
+function detected(plugin, candidates, options = {}, label = candidates[0], ambiguous = false, selected = true) {
+  if (!candidates.length) return null;
+  return {
+    plugin,
+    confidence: ambiguous && candidates.length > 1 ? "medium" : "high",
+    evidence: label,
+    candidates,
+    options,
+    selected,
+  };
+}
+
+function compatibleAdrs(root, candidates) {
+  return candidates.filter((name) => {
+    let source = "";
+    try { source = readFileSync(join(root, name), "utf8"); } catch { return false; }
+    return /^#\s+[^\n]+\.\d{4}\s+[—-]/m.test(source) && /^-\s+\*\*Status:\*\*/mi.test(source) && /^-\s+\*\*Date:\*\*/mi.test(source);
+  });
+}
+
+function goDomainEvidence(root, files) {
+  const layout = /^internal\/(?:domain\/([^/]+)|([^/]+)\/domain)\/[^/]+\.go$/i;
+  const candidates = matches(files, layout);
+  for (const name of candidates) {
+    const match = layout.exec(name);
+    if (!match) continue;
+    const aggregate = match[1] ?? match[2];
+    const packageName = aggregate.replace(/[^a-zA-Z0-9_]/g, "_");
+    const rootName = aggregate
+      .split(/[^a-zA-Z0-9]+|_/)
+      .filter(Boolean)
+      .map((part) => part[0]?.toUpperCase() + part.slice(1))
+      .join("");
+    let source = "";
+    try { source = readFileSync(join(root, name), "utf8"); } catch { continue; }
+    const packagePattern = new RegExp(`\\bpackage\\s+(?:${packageName}|domain)\\b`);
+    const rootPattern = new RegExp(`\\btype\\s+${rootName}\\s+struct\\s*\\{`);
+    if (packagePattern.test(source) && rootPattern.test(source)) return name;
+  }
+  return "";
+}
+
+function laidOutDomainEvidence(root, files, language) {
+  const extension = language === "typescript" ? "ts" : language === "rust" ? "rs" : "java";
+  const prefix = language === "java" ? /(?:^|\/)domain\/([^/]+)\/[^/]+\.java$/i : /^src\/domain\/([^/]+)\/[^/]+\.(?:ts|rs)$/i;
+  for (const name of matches(files, prefix)) {
+    if (!name.endsWith(`.${extension}`)) continue;
+    const match = prefix.exec(name);
+    if (!match) continue;
+    const rootName = match[1].split(/[^a-zA-Z0-9]+|_/).filter(Boolean).map((part) => part[0]?.toUpperCase() + part.slice(1)).join("");
+    let source = "";
+    try { source = readFileSync(join(root, name), "utf8"); } catch { continue; }
+    const claim = language === "typescript"
+      ? new RegExp(`\\b(?:export\\s+)?class\\s+${rootName}\\b`)
+      : language === "rust"
+        ? new RegExp(`\\bpub\\s+struct\\s+${rootName}\\b`)
+        : /@AggregateRoot\b/.test(source) || new RegExp(`\\bclass\\s+${rootName}\\b`).test(source);
+    if (claim instanceof RegExp ? claim.test(source) : claim) return name;
+  }
+  return "";
+}
+
+function goHTTPClientEvidence(root, files) {
+  for (const name of matches(files, /\.go$/).filter((name) => !name.endsWith("_test.go"))) {
+    let source = "";
+    try { source = readFileSync(join(root, name), "utf8"); } catch { continue; }
+    if (
+      /\bhttp\.(?:NewRequest(?:WithContext)?|Get|Post|PostForm|Head)\s*\(/.test(source)
+      || /ClientWithResponses(?:Interface)?\b/.test(source)
+      || /github\.com\/hooklift\/gowsdl\/soap/.test(source)
+    ) return name;
+  }
+  return "";
+}
+
+function goSOAPClientEvidence(root, files) {
+  for (const name of matches(files, /\.go$/).filter((name) => !name.endsWith("_test.go"))) {
+    let source = "";
+    try { source = readFileSync(join(root, name), "utf8"); } catch { continue; }
+    if (
+      /github\.com\/hooklift\/gowsdl\/soap/.test(source)
+      || /\bCallContext\s*\([^,]+,\s*[^,]*(?:soap)?action/i.test(source)
+      || /(?:Header\.)?(?:Add|Set)\s*\(\s*["'](?:SOAPAction|Content-Type)["']/i.test(source)
+    ) return name;
+  }
+  return "";
+}
+
+function goRedisEvidence(root, files) {
+  const redisImport = /github\.com\/(?:redis\/go-redis(?:\/v\d+)?|go-redis\/redis(?:\/v\d+)?|redis\/rueidis|gomodule\/redigo\/redis)(?=\")/g;
+  for (const name of matches(files, /\.go$/).filter((name) => !name.endsWith("_test.go"))) {
+    let source = "";
+    try { source = readFileSync(join(root, name), "utf8"); } catch { continue; }
+    const imports = [...source.matchAll(redisImport)].map((match) => match[0]);
+    if (!imports.length) continue;
+
+    const aliases = new Set();
+    for (const importPath of imports) {
+      const escaped = importPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const declaration = new RegExp(`(?:^|\\n)\\s*(?:import\\s+)?(?:([A-Za-z_][A-Za-z0-9_]*)\\s+)?\"${escaped}\"`, "m").exec(source);
+      const alias = declaration?.[1];
+      if (alias && alias !== "_" && alias !== ".") aliases.add(alias);
+      else aliases.add(importPath.includes("rueidis") ? "rueidis" : "redis");
+    }
+    if ([...aliases].some((alias) => new RegExp(`\\b${alias}\\.(?:NewClient|NewClusterClient|NewFailoverClient|NewFailoverClusterClient|Dial|DialURL)\\s*\\(`).test(source))) {
+      return name;
+    }
+  }
+  return "";
+}
+
+function detectionsFor(root, files) {
+  let goMod = "";
+  if (files.has("go.mod")) {
+    try { goMod = readFileSync(join(root, "go.mod"), "utf8"); } catch {}
+  }
+  const openapi = matches(files, /(^|\/)(openapi|swagger)[^/]*\.(ya?ml|json)$/i);
+  const wsdls = matches(files, /\.wsdl$/i);
+  const asyncapi = matches(files, /(^|\/)asyncapi[^/]*\.(ya?ml|json)$/i);
+  const graphql = matches(files, /\.graphqls?$/i);
+  const protos = matches(files, /\.proto$/i);
+  const sql = matches(files, /(^|\/)(migrations?|repository)(\/|.*\/).*\.sql$/i);
+  const adrs = matches(files, /(^|\/)(docs\/adr|adr)\/.*\.md$/i);
+  const supportedAdrs = compatibleAdrs(root, adrs);
+  const glossaries = matches(files, /(^|\/)glossary\.md$/i);
+  // The app module is the one file a Celery project always has; the tasks
+  // and the calls that enqueue them are found from there.
+  const celery = matches(files, /(^|\/)celery\.py$/);
+  const sqlRoots = [...new Set(sql.map((name) => {
+    const segments = name.split("/");
+    const repository = segments.findIndex((part) => /^(repository|repositories)$/i.test(part));
+    return repository >= 0 ? segments.slice(0, repository + 1).join("/") : "";
+  }).filter(Boolean))];
+  const featureSql = sqlRoots.some((name) => /^internal\/[^/]+\/infrastructure\/repository$/i.test(name));
+  const sqlRoot = sqlRoots.length === 1 && !featureSql ? sqlRoots[0] : "";
+  const graphqlDirs = compactDirectories(graphql);
+  const protoDirs = compactDirectories(protos);
+  const projectMarkers = ["go.mod", "package.json", "Cargo.toml", "pom.xml", "build.gradle", "build.gradle.kts", "manage.py", "Dockerfile", "README.md"].filter((name) => files.has(name));
+  const projectEvidence = projectMarkers.length ? projectMarkers : [[...files].sort()[0]].filter(Boolean);
+  const goDomain = files.has("go.mod") ? goDomainEvidence(root, files) : "";
+  const goHTTPClient = files.has("go.mod") ? goHTTPClientEvidence(root, files) : "";
+  const goSOAPClient = files.has("go.mod") ? goSOAPClientEvidence(root, files) : "";
+  const goRedis = files.has("go.mod") ? goRedisEvidence(root, files) : "";
+  const tsDomain = files.has("package.json") ? laidOutDomainEvidence(root, files, "typescript") : "";
+  const rustDomain = files.has("Cargo.toml") ? laidOutDomainEvidence(root, files, "rust") : "";
+  const javaDomain = ["pom.xml", "build.gradle", "build.gradle.kts"].some((name) => files.has(name)) ? laidOutDomainEvidence(root, files, "java") : "";
+  return [
+    detected("project", projectEvidence, {}, projectEvidence.join(", ")),
+    detected("go-domain", goDomain ? [goDomain] : [], {}, goDomain),
+    detected("ts-domain", tsDomain ? [tsDomain] : [], {}, tsDomain),
+    detected("rust-domain", rustDomain ? [rustDomain] : [], {}, rustDomain),
+    detected("java-domain", javaDomain ? [javaDomain] : [], {}, javaDomain),
+    detected("django-domain", files.has("manage.py") && matches(files, /(^|\/)models(?:\/[^/]+)?\.py$/i).length ? ["manage.py"] : []),
+    detected("celery", celery, {}, celery[0]),
+    detected("openapi", openapi, openapi[0] ? { spec: openapi[0] } : {}, openapi[0], true),
+    detected(
+      "wsdl",
+      wsdls,
+      {
+        ...(wsdls.length === 1 ? { spec: wsdls[0] } : {}),
+        ...(goSOAPClient ? { mode: "external" } : {}),
+      },
+      wsdls.length === 1 ? wsdls[0] : `${wsdls.length} WSDL documents`,
+      true,
+    ),
+    detected("http-clients", goHTTPClient ? [goHTTPClient] : [], {}, goHTTPClient),
+    detected("redis", goRedis ? [goRedis] : [], {}, goRedis),
+    detected("river", goMod.includes("github.com/riverqueue/river") ? ["go.mod"] : [], {}, "go.mod · github.com/riverqueue/river"),
+    detected("watermill", goMod.includes("github.com/ThreeDotsLabs/watermill") ? ["go.mod"] : [], {}, "go.mod · github.com/ThreeDotsLabs/watermill"),
+    detected("asyncapi", asyncapi, asyncapi[0] ? { spec: asyncapi[0] } : {}, asyncapi[0], true),
+    detected("graphql", graphql, graphqlDirs[0] ? { schema: graphqlDirs.length === 1 ? graphqlDirs[0] : graphql[0] } : {}, graphqlDirs.length === 1 ? graphqlDirs[0] : graphql[0]),
+    detected("proto", protos, protoDirs.length ? { paths: protoDirs } : {}, protoDirs.join(", ")),
+    detected("sql", sql, sqlRoot ? { repositories: sqlRoot } : {}, sqlRoot || (sqlRoots.length > 1 ? `${sqlRoots.length} repository packages` : sql[0])),
+    detected(
+      "adr",
+      adrs,
+      supportedAdrs[0] ? { files: [`${posix.dirname(supportedAdrs[0])}/*.md`] } : {},
+      supportedAdrs[0] ? `${posix.dirname(supportedAdrs[0])}/*.md` : `${posix.dirname(adrs[0] ?? "docs/adr/x.md")}/*.md (format not recognized)`,
+      !supportedAdrs.length,
+      supportedAdrs.length > 0,
+    ),
+    detected("glossary", glossaries, glossaries.length ? { files: glossaries } : {}, glossaries.join(", ")),
+  ].filter(Boolean);
+}
+
+export function discoverProject(workspace, input) {
+  const { root, absolute } = safeRoot(workspace, input);
+  const files = walk(absolute);
+  const detections = detectionsFor(absolute, files);
+  const components = componentCandidates(files);
+  const deployables = goDeployables(absolute, files);
+  return {
+    root,
+    filesScanned: files.size,
+    truncated: files.size >= MAX_FILES,
+    components,
+    componentsTruncated: components.length >= MAX_COMPONENTS,
+    deployables,
+    defaults: projectDefaults(basename(absolute)),
+    detections,
+  };
+}
+
+export function projectDefaults(value) {
+  const id = slug(value) || "service";
+  return { id, name: id.split("-").map((part) => part[0]?.toUpperCase() + part.slice(1)).join(" "), group: id, component: id, context: id, service: id };
+}

package/scripts/manifest.mjs

@@ -25,7 +25,19 @@ const schemaFile = () => process.env.PORTOLAN_SCHEMA || "schema/portolan.schema.
  *   that has not run `npm run schema` yet should still be able to generate.
  */
 export function loadManifest(path = "portolan.json") {
-  const manifest = JSON.parse(readFileSync(path, "utf8"));
+  return parseManifest(readFileSync(path, "utf8"), path);
+}
+
+/**
+ * Parses and validates manifest text. This is for manifests that do not live
+ * in the working tree, such as the copy read from another git revision.
+ *
+ * @param {string} text
+ * @param {string} path
+ * @returns {{manifest: object, problems: string[]}}
+ */
+export function parseManifest(text, path = "portolan.json") {
+  const manifest = JSON.parse(text);
 
   let schema;
   try {
@@ -42,6 +54,35 @@ export function loadManifest(path = "portolan.json") {
   return { manifest, problems: explain(validate.errors ?? [], manifest, schema, path) };
 }
 
+/**
+ * The runtime entry point: a caller either gets a schema-valid manifest or a
+ * single actionable error. Code that wants to present every problem itself
+ * can keep using loadManifest/parseManifest.
+ *
+ * @param {string} path
+ * @returns {object}
+ */
+export function readManifest(path = "portolan.json") {
+  return requireValidManifest(loadManifest(path));
+}
+
+/** @param {string} text @param {string} [path] */
+export function readManifestText(text, path = "portolan.json") {
+  return requireValidManifest(parseManifest(text, path));
+}
+
+/** @param {{manifest: object, problems: string[]}} loaded */
+export function requireValidManifest(loaded) {
+  if (loaded.problems.length > 0) {
+    throw new Error(
+      `portolan.json does not match schema/portolan.schema.json:\n${loaded.problems
+        .map((problem) => `  - ${problem}`)
+        .join("\n")}`,
+    );
+  }
+  return loaded.manifest;
+}
+
 /**
  * Turns ajv's errors into lines somebody can act on.
  *

package/scripts/manifest.test.mjs

@@ -8,7 +8,14 @@ import { join } from "node:path";
 
 import { describe, expect, it } from "vitest";
 
-import { loadManifest, stepKeys } from "./manifest.mjs";
+import {
+  loadManifest,
+  parseManifest,
+  readManifest,
+  readManifestText,
+  requireValidManifest,
+  stepKeys,
+} from "./manifest.mjs";
 
 const dir = mkdtempSync(join(tmpdir(), "portolan-manifest-"));
 
@@ -108,6 +115,22 @@ describe("the manifest schema", () => {
     expect(problems).toHaveLength(1);
     expect(problems[0]).toContain('extract/0: "out" is missing');
   });
+
+  it("parses manifest text through the same validator", () => {
+    expect(parseManifest(JSON.stringify(good), "from-git:portolan.json").problems).toEqual([]);
+  });
+
+  it("gives runtime callers only a valid manifest", () => {
+    const path = join(dir, "good.json");
+    writeFileSync(path, JSON.stringify(good));
+    expect(readManifest(path)).toEqual(good);
+    expect(readManifestText(JSON.stringify(good), "memory:portolan.json")).toEqual(good);
+
+    expect(() => requireValidManifest({
+      manifest: {},
+      problems: ['portolan.json: "sources" is missing'],
+    })).toThrow('portolan.json: "sources" is missing');
+  });
 });
 
 describe("stepKeys", () => {

package/scripts/plugin-host.mjs

@@ -41,7 +41,7 @@ const HOST_LIMITS = Object.freeze({
  *   gets no filesystem at all, which is what a generator and a describe
  *   request should get. A process plugin is unaffected: it already has the
  *   whole machine.
- * @returns {Promise<{files: {name: string, contents: string}[], describe?: object}>}
+ * @returns {Promise<{files: {name: string, contents: string, encoding?: "base64"}[], describe?: object}>}
  */
 export async function runPlugin(plugin, request, requestedLimits = {}, access = {}) {
   const limits = lowerLimits(requestedLimits);
@@ -158,7 +158,7 @@ export function validateResponse(name, response) {
       throw new Error(`plugin ${name}: files[${index}] is not an object`);
     }
     const keys = Object.keys(file);
-    if (keys.some((key) => !["name", "contents"].includes(key))) {
+    if (keys.some((key) => !["name", "contents", "encoding"].includes(key))) {
       throw new Error(`plugin ${name}: files[${index}] has unsupported properties`);
     }
     if (typeof file.name !== "string" || !safeFileName(file.name)) {
@@ -167,17 +167,28 @@ export function validateResponse(name, response) {
     if (typeof file.contents !== "string") {
       throw new Error(`plugin ${name}: files[${index}].contents is not a string`);
     }
+    if (file.encoding !== undefined && file.encoding !== "base64") {
+      throw new Error(`plugin ${name}: files[${index}].encoding is not supported`);
+    }
+    if (file.encoding === "base64" && !validBase64(file.contents)) {
+      throw new Error(`plugin ${name}: files[${index}].contents is not valid base64`);
+    }
     if (seen.has(file.name)) {
       throw new Error(`plugin ${name}: duplicate output file ${file.name}`);
     }
     seen.add(file.name);
-    return { name: file.name, contents: file.contents };
+    return { name: file.name, contents: file.contents, ...(file.encoding ? { encoding: file.encoding } : {}) };
   });
 
   if (response.describe !== undefined) validateDescriptor(name, response.describe);
   return { files, ...(response.describe === undefined ? {} : { describe: response.describe }) };
 }
 
+function validBase64(value) {
+  return value.length % 4 === 0
+    && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+}
+
 function safeFileName(name) {
   if (!name || name.includes("\0") || isAbsolute(name) || /^[A-Za-z]:[\\/]/.test(name)) return false;
   const parts = name.split(/[\\/]/);

package/scripts/plugin-host.test.mjs

@@ -13,6 +13,14 @@ describe("plugin response validation", () => {
     });
   });
 
+  it("accepts canonical base64 files and rejects malformed binary output", () => {
+    expect(validateResponse("fixture", { files: [{ name: "image.png", contents: "iVBORw==", encoding: "base64" }] })).toEqual({
+      files: [{ name: "image.png", contents: "iVBORw==", encoding: "base64" }],
+    });
+    expect(() => validateResponse("fixture", { files: [{ name: "image.png", contents: "not base64", encoding: "base64" }] })).toThrow("not valid base64");
+    expect(() => validateResponse("fixture", { files: [{ name: "image.png", contents: "x", encoding: "binary" }] })).toThrow("encoding is not supported");
+  });
+
   it.each(["../secret", "/tmp/result", "C:\\tmp\\result", "a/../../secret", "./result"])(
     "rejects unsafe output name %s",
     (name) => {

package/scripts/run-builtin.mjs

@@ -7,14 +7,16 @@
 // host (portolan.0008).
 
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { readManifest } from "./manifest.mjs";
+
 const installRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const workspace = process.cwd();
 const name = process.argv[2];
-const manifest = JSON.parse(readFileSync(resolve(installRoot, "portolan.json"), "utf8"));
+const manifest = readManifest(resolve(installRoot, "portolan.json"));
 const plugin = (manifest.plugins ?? []).find((candidate) => candidate.name === name);
 
 if (!plugin?.process) {

package/scripts/schema.mjs

@@ -23,6 +23,10 @@ import { describePlugin } from "./plugin-host.mjs";
 const OUT = "schema/portolan.schema.json";
 
 const check = process.argv.includes("--check");
+// Bootstrap exception: this command produces the schema that loadManifest
+// validates against, so requiring the previous schema here would make a new
+// manifest field impossible to introduce. Every consumer of the composed
+// schema goes through scripts/manifest.mjs.
 const manifest = JSON.parse(readFileSync("portolan.json", "utf8"));
 
 const described = new Map();
@@ -207,6 +211,13 @@ function compose() {
             minLength: 1,
             description: "Component slug inside the group.",
           },
+          components: {
+            type: "array",
+            minItems: 2,
+            uniqueItems: true,
+            items: { type: "string", minLength: 1 },
+            description: "Deployable component slugs discovered inside one repository-backed project.",
+          },
           groupKind: {
             enum: ["bounded-context", "system", "product", "team", "namespace"],
             description: "Semantic role of the project's top-level group.",

package/scripts/site-docs.mjs

@@ -26,7 +26,7 @@ import { cpSync, existsSync, readFileSync, statSync, writeFileSync } from "node:
 import { extname, isAbsolute, join, normalize, posix, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { loadManifest } from "./manifest.mjs";
+import { loadManifest, readManifest } from "./manifest.mjs";
 
 const LLMS = "llms.txt";
 const LLMS_FULL = "llms-full.txt";
@@ -261,7 +261,7 @@ export function siteDocsPlugin(workspace = process.cwd()) {
         const url = new URL(req.url ?? "/", "http://localhost");
         let manifest;
         try {
-          manifest = JSON.parse(readFileSync(join(workspace, "portolan.json"), "utf8"));
+          manifest = readManifest(join(workspace, "portolan.json"));
         } catch {
           return next();
         }

package/src/app/CatalogApp.tsx

@@ -98,7 +98,13 @@ function ChatLoading() {
  * way out the router already says the next address, and the page leaving
  * must keep drawing the one it was.
  */
-function AppRoutes({ location }: { location: Location }) {
+function AppRoutes({
+  location,
+  onOpenSearch,
+}: {
+  location: Location;
+  onOpenSearch: () => void;
+}) {
   return (
     <Routes location={location}>
       <Route path="/" element={<Overview />} />
@@ -200,7 +206,10 @@ function AppRoutes({ location }: { location: Location }) {
         }
       />
       <Route path="/index.html" element={<Navigate to="/" replace />} />
-      <Route path="*" element={<NotFoundPage />} />
+      <Route
+        path="*"
+        element={<NotFoundPage onOpenSearch={onOpenSearch} />}
+      />
     </Routes>
   );
 }
@@ -346,15 +355,18 @@ function Shell() {
       {narrow ? (
         <>
           {/* `key` on the route content is what makes the page transition
-              fire: a new pathname is a new element. The old one leaves first,
-              on the micro duration, then the new one rises. */}
-          <AnimatePresence mode="wait">
+              fire: a new pathname is a new element. `popLayout` lets the old
+              page lift away while the new one rises, without a blank frame. */}
+          <AnimatePresence mode="popLayout" initial={false}>
             <m.main
               key={pathname}
               {...page}
               className="min-h-0 flex-1 overflow-hidden"
             >
-              <AppRoutes location={location} />
+              <AppRoutes
+                location={location}
+                onOpenSearch={() => setPalette(true)}
+              />
             </m.main>
           </AnimatePresence>
           <SidebarDrawer />
@@ -386,13 +398,16 @@ function Shell() {
           <Panel id="main" className="h-full min-w-0" onResize={settle}>
             {/* The detail rail rides along with every page that draws a
                 diagram, so a selection made anywhere has somewhere to be read. */}
-            <AnimatePresence mode="wait">
+            <AnimatePresence mode="popLayout" initial={false}>
               <m.main
                 key={pathname}
                 {...page}
                 className="h-full overflow-hidden"
               >
-                <AppRoutes location={location} />
+                <AppRoutes
+                  location={location}
+                  onOpenSearch={() => setPalette(true)}
+                />
               </m.main>
             </AnimatePresence>
           </Panel>