@shortlink-org/portolan 0.2.1 → 0.2.2

package/scripts/local-api.mjs

@@ -30,6 +30,7 @@ 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;
@@ -155,6 +156,51 @@ function componentCandidates(files) {
     });
 }
 
+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 {
@@ -190,7 +236,7 @@ function goDomainEvidence(root, files) {
       .join("");
     let source = "";
     try { source = readFileSync(join(root, name), "utf8"); } catch { continue; }
-    const packagePattern = new RegExp(`\\bpackage\\s+${packageName}\\b`);
+    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;
   }
@@ -345,18 +391,30 @@ export function discoverProject(workspace, input) {
   const files = walk(absolute);
   const detections = detectionsFor(absolute, files);
   const components = componentCandidates(files);
-  const id = slug(basename(absolute)) || "service";
+  const deployables = goDeployables(absolute, files);
   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 },
+    deployables,
+    defaults: projectDefaults(basename(absolute)),
     detections,
   };
 }
 
+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 };
+}
+
+export function externalProjectDefaults(repository, sourcePath = "") {
+  const repo = repositoryParts(repository);
+  const clean = cleanSourcePath(sourcePath);
+  return projectDefaults(clean ? posix.basename(clean) : repo.name);
+}
+
 function repositoryParts(repository) {
   const value = String(repository ?? "").trim();
   if (!value || value.startsWith("-") || /[\r\n\0]/.test(value)) throw new Error("Repository URL is required.");
@@ -585,7 +643,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 +687,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 +773,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 +854,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,10 +977,77 @@ 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 = JSON.parse(before);
+  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 = JSON.parse(before);
+  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 = JSON.parse(undo.before);
+  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) {
@@ -954,7 +1279,7 @@ 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 { plan } = projectRequestPlan(workspace, manifest, request);
   const fingerprint = workspaceFingerprint(workspace);
   const snapshot = snapshotWorkspace(workspace);
   if (workspaceFingerprint(workspace) !== fingerprint) {
@@ -1018,7 +1343,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();
@@ -1162,12 +1487,22 @@ export function localApiPlugin(workspace = process.cwd(), publicSetupFrom) {
           }
           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));
+            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";