@shortlink-org/portolan 0.2.1 → 0.2.3

package/scripts/local-api.mjs

@@ -18,18 +18,25 @@ import { tmpdir } from "node:os";
 import { createServer as createNetServer } from "node:net";
 import { basename, dirname, join, posix, relative, resolve, sep } from "node:path";
 
-import { loadManifest } from "./manifest.mjs";
+import { loadManifest, readManifest, readManifestText } from "./manifest.mjs";
 import { builtinPluginNames } from "./builtin-plugins.mjs";
 import { installDeliveryPreset, planDeliveryPreset, publicDeliveryPreset } from "./delivery-presets.mjs";
+import {
+  discoverProject,
+  matches,
+  projectDefaults,
+  readLocalSource,
+  slug,
+  walk,
+} from "./local-discovery.mjs";
+
+export { discoverProject, readLocalSource } from "./local-discovery.mjs";
 
 export const LOCAL_API_PREFIX = "/__portolan";
 export const GENERATOR_EVENT_PREFIX = "::portolan-event::";
 
-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;
 const jobs = new Map();
+const removalUndos = new Map();
 const repositoryCredentials = new Map();
 const SNAPSHOT_SKIP = new Set([".git", ".portolan", "dist", "node_modules", "target"]);
 const PROJECT_PREVIEW_TTL_MS = 15 * 60 * 1000;
@@ -43,318 +50,11 @@ export function localApiPath(pathname, base = "/") {
   return pathname;
 }
 
-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,
-  };
-}
-
-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;
-}
-
-function slug(value) {
-  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-}
-
-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 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}\\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 id = slug(basename(absolute)) || "service";
-  return {
-    root,
-    filesScanned: files.size,
-    truncated: files.size >= MAX_FILES,
-    components,
-    componentsTruncated: components.length >= MAX_COMPONENTS,
-    defaults: { id, name: id.split("-").map((part) => part[0]?.toUpperCase() + part.slice(1)).join(" "), group: id, component: id, context: id, service: id },
-    detections,
-  };
+export function externalProjectDefaults(repository, sourcePath = "") {
+  const repo = repositoryParts(repository);
+  const clean = cleanSourcePath(sourcePath);
+  return projectDefaults(clean ? posix.basename(clean) : repo.name);
 }
 
 function repositoryParts(repository) {
@@ -585,7 +285,8 @@ export function prepareRepository(workspace, request) {
     }
   }
   if (sourcePath && !lstatExists(join(checkout, sourcePath))) throw new Error(`Repository path \"${sourcePath}\" does not exist at ${commit.slice(0, 7)}.`);
-  const discovery = discoverProject(workspace, root);
+  const discovered = discoverProject(workspace, root);
+  const discovery = { ...discovered, defaults: externalProjectDefaults(repo.value, sourcePath) };
   return { repository: repo.value, ref, commit, sourcePath, checkoutRoot: root, discovery };
 }
 
@@ -628,13 +329,77 @@ function pluginOptions(plugin, project, detectedOptions = {}) {
   return {};
 }
 
+function deployableProtoPaths(paths, deployable) {
+  const prefixes = [`internal/${deployable.slug}/`, `cmd/${deployable.slug}/`, `services/${deployable.slug}/`];
+  return (paths ?? []).filter((path) => prefixes.some((prefix) => `${path}/`.startsWith(prefix)));
+}
+
+function deployableProtoPeers(root, files, deployables, context) {
+  const peers = new Map();
+  const ambiguous = new Set();
+  for (const name of matches(files, /\.proto$/i)) {
+    const owner = deployables.find((candidate) =>
+      name.startsWith(`internal/${candidate.slug}/`) || name.startsWith(`cmd/${candidate.slug}/`) || name.startsWith(`services/${candidate.slug}/`),
+    );
+    if (!owner) continue;
+    let source = "";
+    try { source = readFileSync(join(root, name), "utf8"); } catch { continue; }
+    const packageName = /(?:^|[;\n])\s*package\s+([A-Za-z_][A-Za-z0-9_.]*)\s*;/m.exec(source)?.[1];
+    if (!packageName || ambiguous.has(packageName)) continue;
+    const service = `${context}.${owner.slug}`;
+    const existing = peers.get(packageName);
+    if (existing && existing !== service) {
+      peers.delete(packageName);
+      ambiguous.add(packageName);
+    } else {
+      peers.set(packageName, service);
+    }
+  }
+  return Object.fromEntries([...peers].sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function goModule(root) {
+  try {
+    const match = /^\s*module\s+(\S+)/m.exec(readFileSync(join(root, "go.mod"), "utf8"));
+    return match?.[1] ?? "";
+  } catch { return ""; }
+}
+
+function deployableEvidenceOwners(root, files, deployables, evidence) {
+  const module = goModule(root);
+  if (!module) return [];
+  const evidenceDirs = [...new Set((evidence ?? []).flatMap((name) => {
+    const parts = posix.dirname(name).split("/");
+    const out = [];
+    while (parts.length > 1) { out.push(parts.join("/")); parts.pop(); }
+    return out;
+  }))];
+  return deployables.filter((deployable) => {
+    if ((evidence ?? []).some((name) => name.startsWith(`internal/${deployable.slug}/`) || name.startsWith(`cmd/${deployable.slug}/`))) return true;
+    const scoped = [...files].filter((name) =>
+      name.endsWith(".go") && (
+        name.startsWith(`cmd/${deployable.slug}/`) ||
+        name.startsWith(`internal/${deployable.slug}/`) ||
+        name === `internal/di/${deployable.slug}.go`
+      ),
+    );
+    return scoped.some((name) => {
+      let source = "";
+      try { source = readFileSync(join(root, name), "utf8"); } catch { return false; }
+      return evidenceDirs.some((dir) => source.includes(`"${module}/${dir}"`));
+    });
+  });
+}
+
 export function planProject(workspace, manifest, request) {
   const external = request.source === "external";
   const repo = external ? repositoryParts(request.repository) : null;
   const sourcePath = external ? cleanSourcePath(request.sourcePath) : "";
   if (external && !/^[0-9a-f]{40}$/i.test(String(request.commit ?? ""))) throw new Error("Inspect the repository to resolve an immutable commit first.");
   const inspectedRoot = external ? inspectionRoot(repo.value, String(request.commit), sourcePath) : request.root;
-  const discovery = discoverProject(workspace, inspectedRoot);
+  const discovered = discoverProject(workspace, inspectedRoot);
+  const discovery = external ? { ...discovered, defaults: externalProjectDefaults(repo.value, sourcePath) } : discovered;
+  const confirmedDeployables = discovery.deployables.filter((candidate) => candidate.confidence === "high");
   const declared = new Set([
     ...builtinPluginNames(),
     ...(manifest.plugins ?? []).map((plugin) => plugin.name),
@@ -650,31 +415,75 @@ export function planProject(workspace, manifest, request) {
     ? ["vendor", "repos", repo.owner, repo.name, sourcePath].filter(Boolean).join("/")
     : discovery.root;
   if ((manifest.projects ?? []).some((project) => project.root === finalRoot)) throw new Error(`Project path \"${finalRoot}\" already exists.`);
+  const requestedComponent = slug(String(request.component ?? request.service ?? ""));
+  const splitDeployables = confirmedDeployables.length > 1 && requestedComponent === discovery.defaults.component;
   const project = {
     id,
     name: String(request.name ?? "").trim() || discovery.defaults.name,
     root: finalRoot,
     ...(String(request.group ?? request.context ?? "").trim() ? { group: slug(String(request.group ?? request.context)) } : {}),
-    ...(String(request.component ?? request.service ?? "").trim() ? { component: slug(String(request.component ?? request.service)) } : {}),
+    ...(!splitDeployables && String(request.component ?? request.service ?? "").trim() ? { component: requestedComponent } : {}),
     ...(String(request.groupKind ?? "").trim() ? { groupKind: String(request.groupKind).trim() } : {}),
-    ...(String(request.componentKind ?? "").trim() ? { componentKind: String(request.componentKind).trim() } : {}),
+    ...(!splitDeployables && String(request.componentKind ?? "").trim() ? { componentKind: String(request.componentKind).trim() } : {}),
+    ...(splitDeployables ? { components: confirmedDeployables.map((candidate) => candidate.slug) } : {}),
     ...(String(request.repository ?? "").trim() ? { repository: String(request.repository).trim() } : {}),
   };
   const out = posix.join(finalRoot, "portolan");
   const detectionByPlugin = new Map(discovery.detections.map((item) => [item.plugin, item]));
   const hasDomainModel = plugins.some((plugin) => ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain"].includes(plugin));
-  const steps = plugins.map((plugin) => ({
-    plugin,
-    in: finalRoot,
-    out,
-    options: pluginOptions(
-      plugin,
-      project,
-      plugin === "project"
-        ? { groupKind: hasDomainModel ? "bounded-context" : "system", ...(hasDomainModel ? { componentKind: "service" } : {}) }
-        : detectionByPlugin.get(plugin)?.options,
-    ),
-  }));
+  const projectDetectionOptions = {
+    groupKind: splitDeployables ? "system" : hasDomainModel ? "bounded-context" : "system",
+    ...(hasDomainModel ? { componentKind: "service" } : {}),
+    ...(String(request.contextName ?? "").trim() ? { groupName: String(request.contextName).trim() } : {}),
+    ...(String(request.contextSummary ?? "").trim() ? { groupSummary: String(request.contextSummary).trim() } : {}),
+    ...(String(request.classification ?? "").trim() ? { classification: String(request.classification).trim() } : {}),
+    ...(splitDeployables ? { components: confirmedDeployables.map(({ slug, name, kind }) => ({ slug, name, kind })) } : {}),
+  };
+  const domainDetectionOptions = (plugin) => ({
+    ...detectionByPlugin.get(plugin)?.options,
+    ...(String(request.contextName ?? "").trim() ? { contextName: String(request.contextName).trim() } : {}),
+    ...(String(request.contextSummary ?? "").trim() ? { contextSummary: String(request.contextSummary).trim() } : {}),
+    ...(String(request.classification ?? "").trim() ? { classification: String(request.classification).trim() } : {}),
+  });
+  const rootAbsolute = resolve(workspace, inspectedRoot);
+  const rootFiles = splitDeployables ? walk(rootAbsolute) : new Set();
+  const protoPeers = splitDeployables ? deployableProtoPeers(rootAbsolute, rootFiles, confirmedDeployables, project.group ?? project.context ?? id) : {};
+  const redisOwners = splitDeployables
+    ? new Set(deployableEvidenceOwners(rootAbsolute, rootFiles, confirmedDeployables, detectionByPlugin.get("redis")?.candidates).map((owner) => owner.slug))
+    : new Set();
+  const steps = plugins.flatMap((plugin) => {
+    if (!splitDeployables) {
+      const options = plugin === "project"
+        ? projectDetectionOptions
+        : ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain"].includes(plugin)
+          ? domainDetectionOptions(plugin)
+          : detectionByPlugin.get(plugin)?.options;
+      return [{ plugin, in: finalRoot, out, options: pluginOptions(plugin, project, options) }];
+    }
+    if (plugin === "project") {
+      return [{ plugin, in: finalRoot, out, options: pluginOptions(plugin, project, projectDetectionOptions) }];
+    }
+    const detectedOptions = detectionByPlugin.get(plugin)?.options ?? {};
+    let owners = confirmedDeployables;
+    if (plugin === "proto") owners = confirmedDeployables.filter((candidate) => deployableProtoPaths(detectedOptions.paths, candidate).length > 0);
+    else if (plugin === "redis") owners = deployableEvidenceOwners(rootAbsolute, rootFiles, confirmedDeployables, detectionByPlugin.get(plugin)?.candidates);
+    else if (plugin === "go-domain") owners = confirmedDeployables;
+    else owners = confirmedDeployables.slice(0, 1);
+    return owners.map((owner) => {
+      const scopedProject = { ...project, component: owner.slug, componentKind: owner.kind, name: owner.name };
+      const scopedOptions = plugin === "proto"
+        ? { ...detectedOptions, paths: deployableProtoPaths(detectedOptions.paths, owner) }
+        : plugin === "go-domain"
+          ? { ...detectedOptions, scope: owner.slug, ...(Object.keys(protoPeers).length ? { peers: protoPeers } : {}), ...(redisOwners.has(owner.slug) ? { store: "redis" } : {}) }
+          : detectedOptions;
+      return {
+        plugin,
+        in: finalRoot,
+        out,
+        options: { ...pluginOptions(plugin, scopedProject, scopedOptions), out: `${plugin}-${owner.slug}.json` },
+      };
+    });
+  });
   const source = external ? "vendor/repos/**/portolan/*.json" : `${out}/*.json`;
   const fetch = external ? { repo: repo.value, commit: String(request.commit), paths: sourcePath ? [sourcePath] : [] } : null;
   return { project, plugins, steps, source, discovery, fetch };
@@ -687,23 +496,114 @@ export function manifestWithProject(manifest, plan, { isolated = false } = {}) {
     if (!builtinPluginNames().has("git") && !manifest.plugins?.some((plugin) => plugin.name === "git")) throw new Error("The built-in git fetcher is not available.");
     if (!isolated && fetchIndex >= 0) {
       const fetchStep = extract[fetchIndex];
-      extract[fetchIndex] = { ...fetchStep, options: { ...fetchStep.options, repos: [...(fetchStep.options?.repos ?? []), plan.fetch] } };
+      const repos = [...(fetchStep.options?.repos ?? []), plan.fetch].filter((repo, index, all) => {
+        const key = `${repo.repo}\0${repo.commit}\0${[...(repo.paths ?? [])].sort().join("\0")}`;
+        return all.findIndex((candidate) => `${candidate.repo}\0${candidate.commit}\0${[...(candidate.paths ?? [])].sort().join("\0")}` === key) === index;
+      });
+      extract[fetchIndex] = { ...fetchStep, options: { ...fetchStep.options, repos } };
     } else {
       extract.unshift({ plugin: "git", in: "vendor", out: "vendor/repos", options: { cache: "vendor/repos", repos: [plan.fetch] } });
     }
   }
   extract.push(...plan.steps);
+  const emptyStarterSources = !isolated
+    && (manifest.projects ?? []).length === 0
+    && (manifest.extract ?? []).length === 0
+    && (manifest.sources ?? []).length === 1
+    && manifest.sources[0] === "portolan/*.json";
+  const targetCatalog = manifest.defaultCatalog ?? manifest.catalogs?.[0]?.id;
+  const catalogs = !isolated && manifest.catalogs
+    ? manifest.catalogs.map((catalog) => catalog.id === targetCatalog ? {
+        ...catalog,
+        sources: [...new Set([...catalog.sources, plan.source])],
+        contexts: [...new Set([...catalog.contexts, plan.project.group ?? plan.project.context].filter(Boolean))],
+        projects: [...new Set([...catalog.projects, plan.project.id])],
+      } : catalog)
+    : manifest.catalogs;
   return {
     ...manifest,
     projects: isolated ? [plan.project] : [...(manifest.projects ?? []), plan.project],
     sources: isolated
       ? [...(plan.fetch ? ["vendor/repos/*/*/git.repo.json"] : []), plan.source]
-      : [...new Set([...(manifest.sources ?? []), ...(plan.fetch ? ["vendor/repos/*/*/git.repo.json"] : []), plan.source])],
+      : [...new Set([...(emptyStarterSources ? [] : (manifest.sources ?? [])), ...(plan.fetch ? ["vendor/repos/*/*/git.repo.json"] : []), plan.source])],
     extract,
+    ...(catalogs ? { catalogs } : {}),
     ...(isolated ? { verify: [], generate: [] } : {}),
   };
 }
 
+/**
+ * Remove one project's complete catalog slice while leaving neighbouring
+ * projects and shared estate inputs intact. A single placeholder source is
+ * retained when the workspace becomes empty because `sources` is the one
+ * required manifest field; the next added project replaces that placeholder.
+ */
+export function manifestWithoutProject(manifest, projectId) {
+  const id = String(projectId ?? "").trim();
+  const project = (manifest.projects ?? []).find((candidate) => candidate.id === id);
+  if (!project) throw new Error(`Project \"${id}\" does not exist.`);
+
+  const projects = (manifest.projects ?? []).filter((candidate) => candidate.id !== id);
+  const projectOut = posix.join(project.root, "portolan");
+  const projectSource = `${projectOut}/*.json`;
+  const projectGroup = project.group ?? project.context;
+  const groupStillUsed = projectGroup && projects.some((candidate) => (candidate.group ?? candidate.context) === projectGroup);
+  const belongsToProject = (step) => step?.out === projectOut;
+  const extract = (manifest.extract ?? []).filter((step) => !belongsToProject(step));
+  const verify = (manifest.verify ?? []).filter((step) => !belongsToProject(step));
+  let sources = (manifest.sources ?? []).filter((source) => source !== projectSource);
+  if (sources.length === 0) sources = ["portolan/*.json"];
+
+  const removedCatalogs = [];
+  const catalogs = (manifest.catalogs ?? []).flatMap((catalog) => {
+    const affected = catalog.projects.includes(id) || catalog.sources.includes(projectSource);
+    if (!affected) return [catalog];
+    const next = {
+      ...catalog,
+      sources: catalog.sources.filter((source) => source !== projectSource),
+      contexts: projectGroup && !groupStillUsed ? catalog.contexts.filter((context) => context !== projectGroup) : catalog.contexts,
+      projects: catalog.projects.filter((candidate) => candidate !== id),
+    };
+    if (next.sources.length > 0 && next.contexts.length > 0) return [next];
+    removedCatalogs.push(catalog.id);
+    return [];
+  });
+  const generate = (manifest.generate ?? []).filter((step) => !removedCatalogs.includes(step.catalog));
+  const removedOutputs = [
+    ...new Set((manifest.generate ?? [])
+      .filter((step) => removedCatalogs.includes(step.catalog) || (!(manifest.catalogs ?? []).length && (manifest.projects ?? []).length === 1))
+      .map((step) => step.out)
+      .filter(Boolean)),
+  ];
+
+  const next = { ...manifest, projects, sources, extract, verify, generate };
+  if (manifest.catalogs) {
+    if (catalogs.length > 0) next.catalogs = catalogs;
+    else delete next.catalogs;
+  }
+  if (removedCatalogs.includes(manifest.defaultCatalog)) {
+    if (catalogs[0]) next.defaultCatalog = catalogs[0].id;
+    else delete next.defaultCatalog;
+  }
+  return { manifest: next, project, projectOut, removedOutputs };
+}
+
+export function starterManifestProject(manifest) {
+  if ((manifest.projects ?? []).length !== 1) return null;
+  const project = manifest.projects[0];
+  if (project.root !== "." || project.groupKind || project.componentKind) return null;
+  const output = posix.join(project.root, "portolan");
+  const steps = (manifest.extract ?? []).filter((step) => step.out === output);
+  return steps.length === 1 && steps[0]?.plugin === "project" ? project : null;
+}
+
+function projectRequestPlan(workspace, manifest, request) {
+  const starter = request.replaceStarter ? starterManifestProject(manifest) : null;
+  const base = starter ? manifestWithoutProject(manifest, starter.id).manifest : manifest;
+  const plan = planProject(workspace, base, request);
+  return { base, plan, starter };
+}
+
 export function writeManifest(path, manifest) {
   const staging = mkdtempSync(join(dirname(path), ".portolan-manifest-"));
   const temp = join(staging, "portolan.json");
@@ -719,17 +619,85 @@ export function writeManifest(path, manifest) {
 
 export function writeProject(workspace, request) {
   const manifestPath = join(workspace, "portolan.json");
-  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-  const plan = planProject(workspace, manifest, request);
-  writeManifest(manifestPath, manifestWithProject(manifest, plan));
-  return plan;
+  const before = readFileSync(manifestPath, "utf8");
+  const manifest = readManifestText(before, manifestPath);
+  const { base, plan, starter } = projectRequestPlan(workspace, manifest, request);
+  writeManifest(manifestPath, manifestWithProject(base, plan));
+  const undoToken = rememberManifestUndo(workspace, before, readFileSync(manifestPath, "utf8"));
+  return { ...plan, ...(starter ? { replacedProject: starter } : {}), undoToken };
+}
+
+function rememberManifestUndo(workspace, before, after) {
+  const undoToken = randomUUID();
+  removalUndos.set(undoToken, {
+    workspace: realpathSync(workspace),
+    before,
+    afterSha256: createHash("sha256").update(after).digest("hex"),
+    expiresAt: Date.now() + 15 * 60 * 1000,
+  });
+  return undoToken;
+}
+
+function backupGeneratedSlice(workspace, output) {
+  const root = resolve(workspace);
+  const target = resolve(root, output);
+  if (target === root || !target.startsWith(`${root}${sep}`)) throw new Error(`Generated output \"${output}\" resolves outside this repository.`);
+  if (!lstatExists(target)) return null;
+  const holder = mkdtempSync(join(tmpdir(), "portolan-undo-"));
+  const backup = join(holder, "slice");
+  cpSync(target, backup, { recursive: true });
+  return { target, holder, backup };
+}
+
+export function removeProject(workspace, projectId) {
+  const manifestPath = join(workspace, "portolan.json");
+  const before = readFileSync(manifestPath, "utf8");
+  const manifest = readManifestText(before, manifestPath);
+  const result = manifestWithoutProject(manifest, projectId);
+  const generated = backupGeneratedSlice(workspace, result.projectOut);
+  try {
+    writeManifest(manifestPath, result.manifest);
+    if (generated) rmSync(generated.target, { recursive: true, force: true });
+  } catch (cause) {
+    writeManifest(manifestPath, manifest);
+    if (generated) {
+      rmSync(generated.target, { recursive: true, force: true });
+      mkdirSync(dirname(generated.target), { recursive: true });
+      cpSync(generated.backup, generated.target, { recursive: true });
+      rmSync(generated.holder, { recursive: true, force: true });
+    }
+    throw cause;
+  }
+  const after = readFileSync(manifestPath, "utf8");
+  const undoToken = rememberManifestUndo(workspace, before, after);
+  removalUndos.get(undoToken).generated = generated;
+  return { project: result.project, removedOutputs: result.removedOutputs, undoToken };
+}
+
+export function undoProjectRemoval(workspace, undoToken) {
+  const undo = removalUndos.get(String(undoToken ?? ""));
+  if (!undo || undo.expiresAt < Date.now() || undo.workspace !== realpathSync(workspace)) throw new Error("This removal can no longer be undone.");
+  const manifestPath = join(workspace, "portolan.json");
+  const current = readFileSync(manifestPath, "utf8");
+  if (createHash("sha256").update(current).digest("hex") !== undo.afterSha256) throw new Error("portolan.json changed after the removal; undo would overwrite newer work.");
+  const manifest = readManifestText(undo.before, manifestPath);
+  writeManifest(manifestPath, manifest);
+  if (undo.generated) {
+    rmSync(undo.generated.target, { recursive: true, force: true });
+    mkdirSync(dirname(undo.generated.target), { recursive: true });
+    cpSync(undo.generated.backup, undo.generated.target, { recursive: true });
+    rmSync(undo.generated.holder, { recursive: true, force: true });
+  }
+  removalUndos.delete(String(undoToken));
+  return { restored: true };
 }
 
 function setup(workspace, publicSetupFrom) {
-  const manifestText = readFileSync(join(workspace, "portolan.json"), "utf8");
+  const manifestPath = join(workspace, "portolan.json");
+  const manifestText = readFileSync(manifestPath, "utf8");
   let report;
   try { report = JSON.parse(readFileSync(join(workspace, ".portolan/build-report.json"), "utf8")); } catch {}
-  return publicSetupFrom(JSON.parse(manifestText), report, createHash("sha256").update(manifestText).digest("hex"));
+  return publicSetupFrom(readManifestText(manifestText, manifestPath), report, createHash("sha256").update(manifestText).digest("hex"));
 }
 
 function send(res, status, value) {
@@ -953,8 +921,8 @@ export function summarizeProjectTrial(snapshot, plan, events) {
 }
 
 function prepareProjectTrial(workspace, request) {
-  const manifest = JSON.parse(readFileSync(join(workspace, "portolan.json"), "utf8"));
-  const plan = planProject(workspace, manifest, request);
+  const manifest = readManifest(join(workspace, "portolan.json"));
+  const { plan } = projectRequestPlan(workspace, manifest, request);
   const fingerprint = workspaceFingerprint(workspace);
   const snapshot = snapshotWorkspace(workspace);
   if (workspaceFingerprint(workspace) !== fingerprint) {
@@ -1018,7 +986,7 @@ async function startProjectPreview(job) {
   job.previewChild = child;
   await waitForPreview(origin, child);
   const context = job.projectPlan.project.group ?? job.projectPlan.discovery.defaults.group;
-  const component = job.projectPlan.project.component ?? job.projectPlan.discovery.defaults.component;
+  const component = job.projectPlan.project.components?.[0] ?? job.projectPlan.project.component ?? job.projectPlan.discovery.defaults.component;
   job.previewUrl = `${origin}/c/${encodeURIComponent(context)}/${encodeURIComponent(component)}`;
   job.previewTimer = setTimeout(() => disposeProjectTrial(job), PROJECT_PREVIEW_TTL_MS);
   job.previewTimer.unref();
@@ -1110,7 +1078,13 @@ export function localApiPlugin(workspace = process.cwd(), publicSetupFrom) {
             return send(res, 200, { local: true, workspace: realpathSync(workspace), setup: setup(workspace, publicSetupFrom), activeRun: active ? { id: active.id, mode: active.mode } : null });
           }
           if (req.method === "GET" && url.pathname === `${LOCAL_API_PREFIX}/delivery-presets`) {
-            return send(res, 200, publicDeliveryPreset(planDeliveryPreset(workspace, url.searchParams.get("provider"))));
+            const features = url.searchParams.has("features")
+              ? url.searchParams.get("features").split(",").filter(Boolean)
+              : undefined;
+            return send(res, 200, publicDeliveryPreset(planDeliveryPreset(workspace, {
+              provider: url.searchParams.get("provider") || undefined,
+              features,
+            })));
           }
           const eventMatch = url.pathname.match(/^\/__portolan\/runs\/([^/]+)\/events$/);
           if (req.method === "GET" && eventMatch) {
@@ -1161,13 +1135,23 @@ export function localApiPlugin(workspace = process.cwd(), publicSetupFrom) {
             return send(res, 200, { runId: trial.id, status: "disposed" });
           }
           if (url.pathname === `${LOCAL_API_PREFIX}/projects/preview`) {
-            const manifest = JSON.parse(readFileSync(join(workspace, "portolan.json"), "utf8"));
-            return send(res, 200, planProject(workspace, manifest, input));
+            const manifest = readManifest(join(workspace, "portolan.json"));
+            return send(res, 200, projectRequestPlan(workspace, manifest, input).plan);
           }
           if (url.pathname === `${LOCAL_API_PREFIX}/projects`) {
             const result = writeProject(workspace, input);
             return send(res, 201, { ...result, setup: setup(workspace, publicSetupFrom) });
           }
+          const removeProjectMatch = url.pathname.match(/^\/__portolan\/projects\/([^/]+)\/remove$/);
+          if (removeProjectMatch) {
+            if ([...jobs.values()].some((job) => job.status === "running")) return send(res, 409, { error: "A generator run is already active." });
+            const result = removeProject(workspace, decodeURIComponent(removeProjectMatch[1]));
+            return send(res, 200, { ...result, setup: setup(workspace, publicSetupFrom) });
+          }
+          if (url.pathname === `${LOCAL_API_PREFIX}/projects/removals/undo`) {
+            const result = undoProjectRemoval(workspace, input.undoToken);
+            return send(res, 200, { ...result, setup: setup(workspace, publicSetupFrom) });
+          }
           if (url.pathname === `${LOCAL_API_PREFIX}/runs`) {
             if ([...jobs.values()].some((job) => job.status === "running")) return send(res, 409, { error: "A generator run is already active." });
             const mode = ["check", "preview"].includes(input.mode) ? input.mode : "write";