@shortlink-org/portolan 0.2.3 → 0.3.0

package/src/pages/Settings.tsx

@@ -48,7 +48,7 @@ import {
 import type { Discovery, ProjectDraft, ProjectPlan, RunEvent } from "../lib/local-api";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { localKeys, localStatusQuery } from "../lib/queries";
-import { sourceHref, treeHref } from "../lib/source-link";
+import { bare, sourceHref, treeHref } from "../lib/source-link";
 import { paths } from "../routes";
 import { CapabilityEmpty, Empty, SectionTitle } from "../components/PageHeader";
 import { Modal } from "../components/Overlay";
@@ -56,8 +56,14 @@ import { MachineDocs } from "../components/MachineDocs";
 import { DeliverySettings } from "./settings/DeliverySettings";
 import { PreferencesSettings } from "./settings/PreferencesSettings";
 import { AboutSettings } from "./settings/AboutSettings";
+import { IntegrationsSettings } from "./settings/IntegrationsSettings";
+import { DjangoAggregateChoices } from "./settings/DjangoAggregateChoices";
+import { djangoAggregateCandidates, djangoAggregateMessage } from "../lib/django-aggregates";
 import { CatEmptyState, CatIllustration } from "../components/CatIllustration";
 import { CommitLink } from "../components/CommitLink";
+import { groupDiagnostics, warningDiagnostic } from "../lib/warnings";
+import type { WarningDiagnostic, WarningSeverity } from "../lib/warnings";
+import { AnimatePresence, m, rise } from "../lib/motion";
 
 type Health = "healthy" | "changed" | "failed" | "unchecked";
 type ProjectSource = ProjectDraft["source"];
@@ -260,44 +266,89 @@ function PipelineSteps({ steps }: { steps: SetupRunStep[] }) {
   if (steps.length === 0) {
     return <p className="mono text-muted">No result recorded for these steps.</p>;
   }
+  const warnings = steps.flatMap((step) => step.warnings.map((message) => ({ plugin: step.plugin, message })));
+  const diagnostics = steps.flatMap((step) => step.diagnostics.length
+    ? step.diagnostics
+    : step.warnings.map((message) => warningDiagnostic({ plugin: step.plugin, message })));
   return (
-    <div className="divide-y divide-line rounded-control border border-line">
-      {steps.map((step) => (
-        <div key={step.ordinal} className="px-3 py-2">
-          <div className="grid gap-2 sm:grid-cols-[5rem_minmax(7rem,1fr)_auto_auto] sm:items-center">
-            <span className="mono text-muted">{step.phase}</span>
-            <span className="mono truncate text-ink" title={step.plugin}>{step.plugin}</span>
-            <span className="mono text-muted">{step.fileCount} {plural(step.fileCount, "file")}</span>
-            <div className="flex items-center justify-between gap-2 sm:justify-end">
-              <span className="mono text-muted">{duration(step.durationMs)}</span>
-              <StepStatus status={step.status} />
+    <div className="space-y-2">
+      <div className="divide-y divide-line rounded-control border border-line">
+        {steps.map((step) => (
+          <div key={step.ordinal} className="px-3 py-2">
+            <div className="grid gap-2 sm:grid-cols-[5rem_minmax(7rem,1fr)_auto_auto] sm:items-center">
+              <span className="mono text-muted">{step.phase}</span>
+              <span className="mono truncate text-ink" title={step.plugin}>{step.plugin}</span>
+              <span className="mono text-muted">{step.fileCount} {plural(step.fileCount, "file")}</span>
+              <div className="flex items-center justify-between gap-2 sm:justify-end">
+                <span className="mono text-muted">{duration(step.durationMs)}</span>
+                <StepStatus status={step.status} />
+              </div>
             </div>
           </div>
-          <StepWarnings warnings={step.warnings} />
-        </div>
-      ))}
+        ))}
+      </div>
+      {warnings.length ? <details open={warnings.length <= 5}>
+        <summary className="mono cursor-pointer text-muted">{warnings.length} {plural(warnings.length, "warning")}</summary>
+        <div className="mt-2"><WarningPanel diagnostics={diagnostics} compact /></div>
+      </details> : null}
     </div>
   );
 }
 
-// What a plugin could not read, in its own words. For a tree the extractor
-// only half understood this is the list of what to fix, so it is shown where
-// the step is rather than left on the terminal it scrolled off.
-function StepWarnings({ warnings }: { warnings: string[] }) {
-  if (warnings.length === 0) return null;
+function WarningPanel({ diagnostics, compact = false }: { diagnostics: WarningDiagnostic[]; compact?: boolean }) {
+  const groups = groupDiagnostics(diagnostics);
+  const plugins = [...new Set(groups.map((group) => group.plugin))].sort();
+  const rules = [...new Set(groups.map((group) => group.rule))].sort();
+  const [plugin, setPlugin] = useState("all");
+  const [rule, setRule] = useState("all");
+  const [severity, setSeverity] = useState<WarningSeverity | "all">("all");
+  const [visibility, setVisibility] = useState<"active" | "suppressed" | "all">("active");
+  const shown = groups.filter((group) =>
+    (plugin === "all" || group.plugin === plugin)
+    && (rule === "all" || group.rule === rule)
+    && (severity === "all" || group.severity === severity)
+    && (visibility === "all" || (visibility === "suppressed") === group.suppressed),
+  );
+  const activeCount = groups.filter((group) => !group.suppressed).reduce((sum, group) => sum + group.count, 0);
+  const suppressedCount = diagnostics.length - activeCount;
+
   return (
-    <details className="mt-2" open={warnings.length <= 5}>
-      <summary className="mono cursor-pointer text-muted">
-        {warnings.length} {plural(warnings.length, "warning")}
-      </summary>
-      <ul className="mono mt-1 space-y-1 text-muted">
-        {warnings.map((warning, index) => (
-          <li key={`${index}:${warning}`} className="break-words border-l-2 border-line pl-2">
-            {warning}
-          </li>
-        ))}
-      </ul>
-    </details>
+    <div className="space-y-2">
+      <div className="flex flex-wrap items-center gap-2">
+        <span className="mono text-muted">{activeCount} active · {groups.length} {plural(groups.length, "rule")}</span>
+        {suppressedCount ? <span className="chip status-verified">{suppressedCount} suppressed</span> : null}
+        <div className="flex flex-wrap gap-2 sm:ml-auto">
+          {plugins.length > 1 ? <select aria-label="Filter warnings by plugin" className={`${FIELD} w-auto py-1`} value={plugin} onChange={(event) => setPlugin(event.target.value)}><option value="all">all plugins</option>{plugins.map((name) => <option key={name} value={name}>{name}</option>)}</select> : null}
+          {rules.length > 1 ? <select aria-label="Filter warnings by rule" className={`${FIELD} w-auto py-1`} value={rule} onChange={(event) => setRule(event.target.value)}><option value="all">all rules</option>{rules.map((name) => <option key={name} value={name}>{name}</option>)}</select> : null}
+          <select aria-label="Filter warnings by severity" className={`${FIELD} w-auto py-1`} value={severity} onChange={(event) => setSeverity(event.target.value as WarningSeverity | "all")}><option value="all">all severities</option><option value="error">error</option><option value="warning">warning</option><option value="info">info</option></select>
+          <select aria-label="Filter active or suppressed warnings" className={`${FIELD} w-auto py-1`} value={visibility} onChange={(event) => setVisibility(event.target.value as "active" | "suppressed" | "all")}><option value="active">active</option><option value="suppressed">suppressed</option><option value="all">all</option></select>
+        </div>
+      </div>
+      {shown.length ? <div className="space-y-2">{shown.map((group) => {
+        const color = group.severity === "error" ? "text-unresolved" : group.severity === "warning" ? "text-declared" : "text-muted";
+        const candidates = group.messages.filter((warning) => warning.aggregateCandidates || djangoAggregateCandidates(warning.message));
+        const examples = group.messages.filter((warning) => !warning.aggregateCandidates && !djangoAggregateCandidates(warning.message)).slice(0, compact ? 3 : 12);
+        return <details key={`${group.plugin}:${group.rule}:${group.suppressed}`} className={`rounded-control border px-3 py-2 ${group.suppressed ? "border-line opacity-75" : group.severity === "error" ? "border-unresolved" : "border-line"}`} open={!compact && shown.length <= 4}>
+          <summary className="cursor-pointer list-none">
+            <span className="flex flex-wrap items-center gap-2">
+              <CircleAlert size={15} className={`shrink-0 ${color}`} />
+              <span className="mono text-ink">{group.plugin}</span>
+              <span className={`chip ${group.severity === "error" ? "status-unresolved" : group.severity === "warning" ? "status-declared" : ""}`}>{group.severity}</span>
+              <span className="mono text-muted">{group.rule}</span>
+              <span className="chip ml-auto">×{group.count}</span>
+            </span>
+            <span className="mt-1 block text-muted"><span className="font-medium text-ink">Next:</span> {group.action}</span>
+            {group.suppressionReason ? <span className="mt-1 block text-muted"><span className="font-medium text-ink">Suppressed:</span> {group.suppressionReason}</span> : null}
+          </summary>
+          <ul className="mono mt-2 space-y-1 text-muted">
+            {examples.map((warning, index) => <li key={`${index}:${warning.message}`} className="break-words border-l-2 border-line pl-2">{djangoAggregateMessage(warning.message)}</li>)}
+          </ul>
+          {candidates.length ? <DjangoAggregateChoices warnings={candidates} /> : null}
+          {group.count > examples.length + candidates.length ? <p className="mono mt-2 text-faint">{group.count - examples.length - candidates.length} more occurrences</p> : null}
+        </details>;
+      })}</div> : <p className="rounded-control border border-line px-3 py-2 text-muted">No warnings match these filters.</p>}
+      {!compact && groups.some((group) => !group.suppressed) ? <p className="text-faint">Suppress a reviewed limitation with a typed CEL entry in <span className="mono">portolan.json → warningPolicies</span>. The reason is required and remains visible here after regeneration.</p> : null}
+    </div>
   );
 }
 
@@ -306,11 +357,22 @@ function ProjectCard({ project, onRemove }: { project: SetupProject; onRemove?:
   const declared = setupInfo.steps.filter((step) => step.projectId === project.id);
   const runSteps = setupInfo.run?.steps.filter((step) => step.projectId === project.id) ?? [];
   const pluginNames = [...new Set(declared.map((step) => step.plugin))];
+  // A project rooted at the repository itself owns every source in it.
+  const rootedAtRepository = project.root === "." || project.root === "";
   const sources = catalogSources.filter(
-    (source) => source.path === project.root || source.path.startsWith(`${project.root}/`),
+    (source) => rootedAtRepository || source.path === project.root || source.path.startsWith(`${project.root}/`),
   );
   const outputs = [...new Set(runSteps.flatMap((step) => step.files))];
+  // A vendored project's provenance is its pin: the upstream commit the copy
+  // was fetched at, which is also what its source links open. The history of
+  // THIS checkout says when the copy landed here, which is a different fact.
+  const pin = project.repository
+    ? catalog.repos?.find((held) => bare(held.repo) === bare(project.repository!))
+    : undefined;
   const commits = [...new Set(sources.map((source) => source.commit).filter(Boolean))];
+  // "uncommitted" is what the history says of a file it does not hold yet;
+  // it is not a commit, and a link built from it would open nothing.
+  const committed = commits.filter((commit) => commit !== "uncommitted");
   const href = projectHref(project);
   const sourceLink = forge(project);
   const health = healthFor(runSteps, declared.length, setupInfo);
@@ -341,7 +403,7 @@ function ProjectCard({ project, onRemove }: { project: SetupProject; onRemove?:
         <dt>scope</dt><dd className="truncate text-ink">{project.components?.length ? `${project.group ?? project.context} · ${project.components.length} components` : [project.group ?? project.context, project.component ?? project.service].filter(Boolean).join(" · ") || "estate"}</dd>
         <dt>pipeline</dt><dd className="text-ink">{declared.length} {plural(declared.length, "step")}</dd>
         <dt>fragments</dt><dd className="text-ink">{sources.length}</dd>
-        <dt>commit</dt><dd className="truncate text-ink" title={commits.join(", ")}>{commits.length === 0 ? "not stamped" : commits.length === 1 ? <CommitLink commit={commits[0]!} repository={project.repository} length={12} /> : `${commits.length} source commits`}</dd>
+        <dt>commit</dt><dd className="truncate text-ink" title={pin ? pin.commit : commits.join(", ")}>{pin ? <CommitLink commit={pin.commit} repository={project.repository} length={12} /> : committed.length === 1 ? <CommitLink commit={committed[0]!} repository={project.repository} length={12} /> : committed.length > 1 ? `${committed.length} source commits` : commits.length > 0 ? "uncommitted" : "not stamped"}</dd>
       </dl>
 
       <div className="mt-4 flex flex-wrap gap-1.5" aria-label="Active plugins">
@@ -828,11 +890,15 @@ function Wizard({ open, initialSource, onClose, onAdded, onRunStarted }: { open:
   const trialRunning = stage === "trial" && !finished;
   const confirmedDeployables = discovery?.deployables.filter((candidate) => candidate.confidence === "high") ?? [];
   const splitsDeployables = confirmedDeployables.length > 1 && draft?.component === discovery?.defaults.component;
+  const trialDiagnostics = trial?.diagnostics ?? [];
+  const trialActiveWarnings = trial
+    ? groupDiagnostics(trialDiagnostics).filter((group) => !group.suppressed).reduce((sum, group) => sum + group.count, 0)
+    : 0;
   const quality = trial && draft ? [
     { label: "Stable project identity", done: Boolean(draft.id.trim() && draft.name.trim()) },
     { label: "Architecture placement", done: Boolean(draft.group.trim() && (splitsDeployables || draft.component.trim())) },
     { label: "Catalog facts extracted", done: trial.facts.some((fact) => fact.count > 0) },
-    { label: "Extraction without warnings", done: trial.warnings.length === 0 },
+    { label: "Extraction without active warnings", done: trialActiveWarnings === 0 },
   ] : [];
   const totalSteps = pipeline?.stepCount ?? plan?.steps.length ?? 0;
   const percent = totalSteps ? Math.round((completedSteps.length / totalSteps) * 100) : 0;
@@ -876,7 +942,7 @@ function Wizard({ open, initialSource, onClose, onAdded, onRunStarted }: { open:
               {discovery.detections.length ? <div className="grid gap-2">{discovery.detections.map((item) => {
                 const checked = draft.plugins.includes(item.plugin);
                 const capability = CAPABILITIES[item.plugin] ?? { title: item.plugin, summary: "Catalog facts extracted from project files." };
-                return <label key={item.plugin} className={`flex cursor-pointer items-start gap-3 rounded-control border px-3 py-3 transition-colors ${checked ? "border-accent bg-surface" : "border-line hover:bg-surface"}`}><input className="mt-1" type="checkbox" checked={checked} onChange={() => setDraft({ ...draft, plugins: checked ? draft.plugins.filter((name) => name !== item.plugin) : [...draft.plugins, item.plugin] })} /><span className="min-w-0 flex-1"><span className="flex flex-wrap items-center gap-2"><span className="font-medium text-ink">{capability.title}</span><span className={`chip ${item.confidence === "high" ? "status-verified" : "status-declared"}`}>{item.confidence} confidence</span>{item.candidates.length > 1 ? <span className="chip status-declared">{item.candidates.length} candidates</span> : null}</span><span className="mt-0.5 block text-muted">{capability.summary}</span><span className="mono mt-1 block truncate text-faint" title={item.evidence}>evidence · {item.evidence}</span><span className="mono mt-0.5 block text-faint">extractor · {item.plugin}</span></span></label>;
+                return <label key={item.plugin} className={`flex cursor-pointer items-start gap-3 rounded-control border px-3 py-3 transition-colors ${checked ? "border-accent bg-surface" : "border-line hover:bg-surface"}`}><input aria-label={`Toggle ${capability.title}`} className="mt-1" type="checkbox" checked={checked} onChange={() => setDraft({ ...draft, plugins: checked ? draft.plugins.filter((name) => name !== item.plugin) : [...draft.plugins, item.plugin] })} /><span className="min-w-0 flex-1"><span className="flex flex-wrap items-center gap-2"><span className="font-medium text-ink">{capability.title}</span><span className={`chip ${item.confidence === "high" ? "status-verified" : "status-declared"}`}>{item.confidence} confidence</span>{item.candidates.length > 1 ? <span className="chip status-declared">{item.candidates.length} candidates</span> : null}</span><span className="mt-0.5 block text-muted">{capability.summary}</span><span className="mono mt-1 block truncate text-faint" title={item.evidence}>evidence · {item.evidence}</span>{item.preview?.length ? <span className="mt-2 grid gap-1.5">{item.preview.slice(0, 3).map((preview) => <span key={preview.file} className="block rounded-control border border-line bg-canvas px-2 py-1.5"><span className="mono block truncate text-faint" title={preview.file}>{preview.file}</span><span className="mt-1 flex flex-wrap gap-x-3 gap-y-1 text-muted">{Object.entries(preview.fields).map(([field, value]) => <span key={field}><span className="text-faint">{field}</span> · <span className="text-ink">{value}</span></span>)}</span></span>)}{item.preview.length > 3 ? <span className="text-faint">+ {item.preview.length - 3} more recognized records</span> : null}</span> : null}<span className="mono mt-0.5 block text-faint">extractor · {item.plugin}</span></span></label>;
               })}</div> : <Empty>no supported project signals found</Empty>}
             </div>
           </div>
@@ -894,7 +960,7 @@ function Wizard({ open, initialSource, onClose, onAdded, onRunStarted }: { open:
             {trial ? <section><div className="label mb-2">what Portolan found</div>{trial.facts.length ? <div className="grid grid-cols-2 gap-2 sm:grid-cols-3">{trial.facts.map((fact) => <div key={fact.key} className="rounded-control border border-line bg-canvas px-3 py-2"><div className="tnum text-lg font-semibold text-ink">{fact.count}</div><div className="text-muted">{fact.label}</div></div>)}</div> : <div className="rounded-control border border-line bg-surface px-3 py-3 text-muted">Only component metadata was found. You can add APIs, domain models and stores later without re-adding the project.</div>}</section> : null}
             {trial ? <section><div className="label mb-2">catalog readiness</div><div className="grid gap-2 sm:grid-cols-2">{quality.map((item) => <div key={item.label} className="flex items-center gap-2 rounded-control border border-line px-3 py-2"><span className={`flex size-5 items-center justify-center rounded-full ${item.done ? "bg-verified text-canvas" : "bg-surface text-declared"}`}>{item.done ? <Check size={12} aria-hidden /> : <CircleAlert size={12} aria-hidden />}</span><span className={item.done ? "text-ink" : "text-muted"}>{item.label}</span></div>)}</div></section> : null}
             <section><div className="label mb-2">extractor results</div><div className="divide-y divide-line rounded-control border border-line">{(trial?.steps ?? completedSteps).map((step) => <div key={`${step.plugin}:${"ordinal" in step ? step.ordinal : "trial"}`} className="grid gap-1 px-3 py-2 sm:grid-cols-[1fr_auto_auto]"><span><span className="font-medium text-ink">{CAPABILITIES[step.plugin]?.title ?? step.plugin}</span><span className="mono ml-2 text-faint">{step.plugin}</span>{step.message ? <span className="mt-1 block text-unresolved">{step.message}</span> : null}</span><span className="mono text-muted">{step.fileCount} {plural(step.fileCount, "file")}</span><span className={`chip ${step.status === "failed" ? "status-unresolved" : "status-verified"}`}>{step.status === "failed" ? "failed" : "read"}</span></div>)}</div></section>
-            {trial?.warnings.length ? <section><div className="label mb-2">warnings · {trial.warnings.length}</div><div className="space-y-2">{trial.warnings.map((warning, index) => <div key={`${warning.plugin}:${index}`} className="flex gap-2 rounded-control border border-declared px-3 py-2 text-muted"><CircleAlert size={15} className="mt-0.5 shrink-0 text-declared" /><span><span className="mono text-ink">{warning.plugin}</span> · {warning.message}</span></div>)}</div></section> : null}
+            {trialDiagnostics.length ? <section><div className="label mb-2">diagnostics · {trialDiagnostics.length}</div><WarningPanel diagnostics={trialDiagnostics} /></section> : null}
             {finished?.status === "failed" && logs.length ? <details><summary className="cursor-pointer text-muted">Generator log · {logs.length} lines</summary><pre className="mono mt-2 max-h-48 overflow-auto whitespace-pre-wrap rounded-control bg-surface p-3 text-muted">{logs.map((event) => event.message).join("\n")}</pre></details> : null}
             {trial ? <div><div className="label mb-2">changes after apply</div><dl className="mono grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-2 text-muted"><dt>project</dt><dd className="text-ink">{plan.project.id}</dd>{plan.fetch ? <><dt>pin</dt><dd className="truncate text-ink"><CommitLink commit={plan.fetch.commit} repository={plan.fetch.repo} length={12} /></dd></> : null}<dt>source</dt><dd className="truncate text-ink">{plan.source}</dd><dt>pipeline</dt><dd className="text-ink">{plan.steps.length + (plan.fetch ? 1 : 0)} {plural(plan.steps.length + (plan.fetch ? 1 : 0), "extract step")}</dd><dt>fragments</dt><dd className="text-ink">{trial.generatedFiles} generated</dd></dl></div> : null}
           </div>
@@ -954,6 +1020,7 @@ const SETTINGS_LINKS = [
   ["Projects", paths.settingsProjects()],
   ["Pipeline", paths.settingsPipeline()],
   ["Delivery", paths.settingsDelivery()],
+  ["Integrations", paths.settingsIntegrations()],
   ["Preferences", paths.settingsPreferences()],
   ["About", paths.settingsAbout()],
 ] as const;
@@ -1046,6 +1113,10 @@ function OverviewSettings({ local, onGenerate }: { local: boolean; onGenerate: (
           <div className="font-semibold text-ink">Delivery</div>
           <p className="mt-1 text-muted">Install review checks and static catalog publishing for GitHub or GitLab.</p>
         </Link>
+        <Link to={paths.settingsIntegrations()} className="card">
+          <div className="font-semibold text-ink">Integrations</div>
+          <p className="mt-1 text-muted">Connect operational tools such as Kafka UI to the catalog.</p>
+        </Link>
         <Link to={paths.settingsPreferences()} className="card">
           <div className="font-semibold text-ink">Preferences</div>
           <p className="mt-1 text-muted">Theme, row density, source editor and Ask the catalog.</p>
@@ -1112,15 +1183,16 @@ function SettingsContent({ local, onAdd, onRemove, onGenerate }: { local: boolea
   const pathname = useLocation().pathname.replace(/\/$/, "");
   const overview = pathname === paths.settings();
   const about = pathname === paths.settingsAbout();
+  const browserIntegration = pathname === paths.settingsIntegrations();
   return (
     <div className="h-full overflow-y-auto p-gutter">
       <div className="max-w-table">
         <div className="flex flex-wrap items-start justify-between gap-3">
           <div>
             <div className="flex items-center gap-2"><h1 className="text-lg font-semibold">Settings</h1>{local ? <span className="chip status-verified">local mode</span> : null}</div>
-            <p className="mt-1 max-w-prose text-muted">Configure projects, extraction, delivery automation and local preferences. {local ? "This local session can write reviewed changes." : "Build configuration is read-only here."}</p>
+            <p className="mt-1 max-w-prose text-muted">Configure projects, extraction, delivery automation, integrations and local preferences. {local ? "This local session can write reviewed changes." : "Build configuration is read-only here."}</p>
           </div>
-          {local && !overview && !about ? <button type="button" className="product-primary" onClick={onGenerate}><Play size={15} /> Preview generated diff</button> : null}
+          {local && !overview && !about && !browserIntegration ? <button type="button" className="product-primary" onClick={onGenerate}><Play size={15} /> Preview generated diff</button> : null}
         </div>
         <SettingsNav />
         <div className="mt-section">
@@ -1129,17 +1201,100 @@ function SettingsContent({ local, onAdd, onRemove, onGenerate }: { local: boolea
             <Route path="projects" element={<ProjectsSettings local={local} onAdd={onAdd} onRemove={onRemove} />} />
             <Route path="pipeline" element={<PipelineSettings />} />
             <Route path="delivery" element={<section><SectionTitle right={local ? "preview before writing" : "local mode required"}>Delivery presets</SectionTitle><DeliverySettings local={local} /></section>} />
+            <Route path="integrations" element={<IntegrationsSettings />} />
             <Route path="preferences" element={<PreferencesSettings />} />
             <Route path="about" element={<AboutSettings />} />
             <Route path="*" element={<Navigate to={paths.settings()} replace />} />
           </Routes>
         </div>
-        {!about ? <div className="mono mt-section flex items-center gap-2 pb-section text-muted"><Box size={14} aria-hidden />{local ? "Changes are written only after preview; generated files remain reviewable in git." : "Configuration is embedded at build time; changing it requires a new catalog build."}</div> : null}
+        {!about ? <div className="mono mt-section flex items-center gap-2 pb-section text-muted"><Box size={14} aria-hidden />{browserIntegration ? "Integration settings stay in this browser and do not change the generated catalog." : local ? "Changes are written only after preview; generated files remain reviewable in git." : "Configuration is embedded at build time; changing it requires a new catalog build."}</div> : null}
       </div>
     </div>
   );
 }
 
+function RemoveProjectDialog({
+  project,
+  busy,
+  onClose,
+  onConfirm,
+}: {
+  project: SetupProject | null;
+  busy: boolean;
+  onClose: () => void;
+  onConfirm: () => void;
+}) {
+  const name = project?.name ?? "project";
+  return (
+    <Modal
+      open={project !== null}
+      onClose={busy ? () => {} : onClose}
+      label={`Remove ${name}`}
+      width="min(520px,92vw)"
+    >
+      <div className="flex items-center gap-3 border-b border-line px-5 py-4">
+        <m.span
+          animate={busy ? { rotate: 360 } : { rotate: 0 }}
+          transition={busy ? { duration: 0.9, ease: "linear", repeat: Infinity } : undefined}
+          className="flex size-8 shrink-0 items-center justify-center rounded-full bg-unresolved/10 text-unresolved"
+        >
+          {busy ? <LoaderCircle size={17} aria-hidden /> : <Trash2 size={16} aria-hidden />}
+        </m.span>
+        <div className="min-w-0">
+          <div className="font-semibold text-ink">{busy ? `Removing ${name}` : `Remove ${name}?`}</div>
+          <div className="mono mt-0.5 truncate text-faint">{project?.id}</div>
+        </div>
+      </div>
+
+      <div className="min-h-40 p-5">
+        <AnimatePresence mode="wait" initial={false}>
+          {busy ? (
+            <m.div key="removing" {...rise} aria-live="polite">
+              <p className="font-medium text-ink">Updating project configuration…</p>
+              <p className="mt-2 text-muted">
+                Portolan is removing the project and its extraction steps. The source tree remains untouched.
+              </p>
+              <div
+                role="progressbar"
+                aria-label={`Removing ${name}`}
+                className="mt-5 h-1.5 overflow-hidden rounded-full bg-surface"
+              >
+                <m.div
+                  className="h-full w-2/5 rounded-full bg-unresolved"
+                  initial={{ x: "-100%" }}
+                  animate={{ x: ["-100%", "250%"] }}
+                  transition={{ duration: 1.1, ease: "easeInOut", repeat: Infinity }}
+                />
+              </div>
+            </m.div>
+          ) : (
+            <m.div key="confirm" {...rise}>
+              <p className="text-muted">
+                This removes the project, its extraction steps and its dedicated catalog configuration from <span className="mono text-ink">portolan.json</span>. Your source code stays untouched.
+              </p>
+              <p className="mt-3 text-muted">
+                You can undo immediately. Generated documentation changes remain pending until you preview and apply them.
+              </p>
+            </m.div>
+          )}
+        </AnimatePresence>
+      </div>
+
+      <div className="flex justify-end gap-2 border-t border-line px-5 py-4">
+        <button type="button" className="tbtn" onClick={onClose} disabled={busy}>Cancel</button>
+        <button type="button" className="product-primary product-danger min-w-36" onClick={onConfirm} disabled={busy}>
+          <AnimatePresence mode="wait" initial={false}>
+            <m.span key={busy ? "busy" : "ready"} {...rise} className="flex items-center justify-center gap-2">
+              {busy ? <LoaderCircle size={15} aria-hidden /> : <Trash2 size={15} aria-hidden />}
+              {busy ? "Removing…" : "Remove project"}
+            </m.span>
+          </AnimatePresence>
+        </button>
+      </div>
+    </Modal>
+  );
+}
+
 export function Settings() {
   useDocumentTitle("Settings");
   const queryClient = useQueryClient();
@@ -1202,11 +1357,12 @@ export function Settings() {
     <SetupContext.Provider value={setup}>
       <SettingsContent local={local} onAdd={setWizardSource} onRemove={setRemoveTarget} onGenerate={() => void generate()} />
       <Wizard open={wizardSource !== null} initialSource={wizardSource ?? "local"} onClose={() => setWizardSource(null)} onAdded={setSetup} onRunStarted={(id) => { setRunId(id); setRunOpen(true); }} />
-      <Modal open={removeTarget !== null} onClose={removeBusy ? () => {} : () => setRemoveTarget(null)} label={`Remove ${removeTarget?.name ?? "project"}`} width="min(520px,92vw)">
-        <div className="border-b border-line px-5 py-4"><div className="font-semibold text-ink">Remove {removeTarget?.name}?</div></div>
-        <div className="p-5"><p className="text-muted">This removes the project, its extraction steps and its dedicated catalog configuration from <span className="mono text-ink">portolan.json</span>. Your source code stays untouched.</p><p className="mt-3 text-muted">You can undo immediately. Generated documentation changes remain pending until you preview and apply them.</p></div>
-        <div className="flex justify-end gap-2 border-t border-line px-5 py-4"><button type="button" className="tbtn" onClick={() => setRemoveTarget(null)} disabled={removeBusy}>Cancel</button><button type="button" className="product-primary" onClick={() => void confirmRemove()} disabled={removeBusy}>{removeBusy ? <LoaderCircle size={15} className="animate-spin" /> : <Trash2 size={15} />} Remove project</button></div>
-      </Modal>
+      <RemoveProjectDialog
+        project={removeTarget}
+        busy={removeBusy}
+        onClose={() => setRemoveTarget(null)}
+        onConfirm={() => void confirmRemove()}
+      />
       <RunDialog runId={runId} open={runOpen} onClose={() => setRunOpen(false)} onFinished={refresh} onApply={(preview) => void generate(preview)} />
     </SetupContext.Provider>
   );

package/src/pages/settings/DjangoAggregateChoices.tsx

@@ -0,0 +1,79 @@
+import { useState } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { djangoAggregateCandidates, djangoAggregateMessage } from "../../lib/django-aggregates";
+import { djangoAggregateProposals, saveDjangoAggregates } from "../../lib/local-api";
+import { localKeys, localStatusQuery } from "../../lib/queries";
+import type { WarningDiagnostic } from "../../lib/warnings";
+import { useToastStore } from "../../app/toast";
+
+const CANDIDATE_KEY = ["local", "django-aggregates"];
+
+export function DjangoAggregateChoices({ warnings }: { warnings: WarningDiagnostic[] }) {
+  const status = useQuery(localStatusQuery());
+  const queryClient = useQueryClient();
+  const say = useToastStore((state) => state.say);
+  const proposals = useQuery({
+    queryKey: [...CANDIDATE_KEY, status.data?.setup.run?.finishedAt],
+    queryFn: djangoAggregateProposals,
+    enabled: status.isSuccess,
+    retry: false,
+  });
+  const [choices, setChoices] = useState<Record<string, string>>({});
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+  const [saved, setSaved] = useState(false);
+  const rows = warnings.flatMap((warning) => {
+    const candidates = warning.aggregateCandidates ?? djangoAggregateCandidates(warning.message);
+    if (!candidates) return [];
+    const matches = proposals.data?.proposals.filter((proposal) => proposal.plugin === warning.plugin && proposal.app === candidates.app
+      && djangoAggregateMessage(proposal.message).slice(0, 500) === djangoAggregateMessage(warning.message).slice(0, 500)) ?? [];
+    return [{ ...candidates, key: `${warning.plugin}:${warning.message}`, proposal: matches.length === 1 ? matches[0] : undefined }];
+  });
+  const selections = rows.flatMap((row) => row.proposal && choices[row.key] ? [{ id: row.proposal.id, model: choices[row.key]! }] : []);
+  const canSave = Boolean(proposals.data && !proposals.data.stale && !status.data?.activeRun && selections.length && !busy);
+
+  async function save() {
+    if (!canSave || !proposals.data) return;
+    setBusy(true); setError(""); setSaved(false);
+    try {
+      await saveDjangoAggregates(proposals.data.revision, selections);
+      setSaved(true);
+      // Refreshing the manifest hides the now-stale report and unmounts this
+      // picker; keep the next step visible outside that report.
+      say("Aggregate roots saved to portolan.json. Preview generated diff to update the catalog.");
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: CANDIDATE_KEY }),
+        queryClient.invalidateQueries({ queryKey: localKeys.status }),
+      ]);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+    } finally { setBusy(false); }
+  }
+
+  return <div className="mt-3 space-y-3">
+    <p className="text-muted">Choose the model that owns each application’s aggregate. Other concrete models become its entities.</p>
+    {rows.map((row) => <div key={row.key} className="rounded-control border border-line p-3">
+      <label className="block font-medium text-ink">
+        Aggregate root for <span className="mono">{row.app}</span>
+        <select aria-label={`Aggregate root for ${row.app}`} className="mt-2 block w-full rounded-control border border-line bg-canvas px-3 py-2 text-ink" value={choices[row.key] ?? ""} onChange={(event) => { setChoices({ ...choices, [row.key]: event.target.value }); setSaved(false); }} disabled={busy}>
+          <option value="">Choose a model…</option>
+          {row.models.map((model) => <option key={model.name} value={model.name}>{model.name}</option>)}
+        </select>
+      </label>
+      <details className="mt-2 text-muted">
+        <summary className="cursor-pointer">{row.models.length} candidates · source locations</summary>
+        <ul className="mono mt-2 space-y-1">{row.models.map((model) => <li key={model.name} className="break-words">{model.name} · {model.path}:{model.line}</li>)}</ul>
+      </details>
+      {choices[row.key] ? <pre className="mono mt-2 overflow-auto rounded-control bg-canvas p-2 text-ink">{JSON.stringify({ aggregates: { [row.app]: choices[row.key] } }, null, 2)}</pre> : null}
+    </div>)}
+    {status.isSuccess ? <>
+      <button className="rounded-control border border-line bg-canvas px-3 py-2 font-medium text-accent hover:bg-surface disabled:cursor-not-allowed disabled:opacity-50" onClick={() => void save()} disabled={!canSave}>{busy ? "Saving…" : "Save selected roots"}</button>
+      <p className="text-muted">Saves to the matching extraction steps in portolan.json. Regenerate afterward to update the catalog and warnings.</p>
+      {proposals.data?.stale && !saved ? <p className="text-declared">Regenerate before saving: these candidates belong to an older manifest.</p> : null}
+      {proposals.isError ? <p role="alert" className="text-unresolved">Could not load the saved extraction report. Regenerate and reopen Settings.</p> : null}
+      {rows.some((row) => !row.proposal) && proposals.isSuccess ? <p className="text-muted">Candidates from a trial can be saved after applying the project and generating its catalog.</p> : null}
+    </> : <p className="text-muted">To save, open Portolan locally or copy the selected aggregates option into the matching extraction step in portolan.json.</p>}
+    {saved ? <p role="status" className="text-verified">Aggregate roots saved. Regenerate to apply the choices to the catalog.</p> : null}
+    {error ? <p role="alert" className="text-unresolved">{error}</p> : null}
+  </div>;
+}

package/src/pages/settings/IntegrationsSettings.tsx

@@ -0,0 +1,117 @@
+import { ExternalLink, Save, Trash2 } from "lucide-react";
+import { useState } from "react";
+import { SectionTitle } from "../../components/PageHeader";
+import { TechIcon } from "../../components/TechIcon";
+import { normalizeKafkaUiUrl, useKafkaUi } from "../../lib/kafka-ui";
+import { techGlyph } from "../../lib/tech";
+
+const FIELD =
+  "mono w-full rounded-control border border-line bg-canvas px-3 py-2 text-ink outline-none focus:border-accent";
+
+function KafkaUiCard() {
+  const configured = useKafkaUi((state) => state.url);
+  const setUrl = useKafkaUi((state) => state.setUrl);
+  const [draft, setDraft] = useState(configured);
+  const normalized = normalizeKafkaUiUrl(draft);
+  const valid = normalized !== null;
+  const dirty = valid && normalized !== configured;
+  const glyph = techGlyph("Kafka");
+
+  const save = () => {
+    if (normalized === null) return;
+    setUrl(normalized);
+    setDraft(normalized);
+  };
+
+  const remove = () => {
+    setUrl("");
+    setDraft("");
+  };
+
+  return (
+    <section className="rounded-card border border-line bg-canvas p-card shadow-xs">
+      <div className="flex items-start gap-3">
+        <span className="flex size-9 shrink-0 items-center justify-center rounded-control border border-line bg-surface text-ink">
+          {glyph ? <TechIcon glyph={glyph} size={18} /> : null}
+        </span>
+        <div className="min-w-0 flex-1">
+          <div className="flex flex-wrap items-center gap-2">
+            <h2 className="font-semibold text-ink">Kafka UI</h2>
+            <span className={`chip ${configured ? "status-verified" : "text-muted"}`}>
+              {configured ? "configured" : "not configured"}
+            </span>
+          </div>
+          <p className="mt-1 text-muted">
+            Opens catalogued Kafka topics in your Kafbat Kafka UI installation.
+          </p>
+        </div>
+      </div>
+
+      <label className="mt-4 block">
+        <span className="label mb-1.5 block">Kafka UI cluster URL</span>
+        <input
+          type="url"
+          value={draft}
+          onChange={(event) => setDraft(event.target.value)}
+          onKeyDown={(event) => {
+            if (event.key === "Enter" && dirty) save();
+          }}
+          placeholder="https://kafka.example/ui/clusters/production"
+          spellCheck={false}
+          autoComplete="off"
+          aria-invalid={!valid}
+          className={`${FIELD} ${valid ? "" : "border-unresolved"}`}
+        />
+      </label>
+      <p className={`mono mt-2 ${valid ? "text-muted" : "text-unresolved"}`}>
+        {valid
+          ? "Use a cluster or topics URL to open the exact topic. A plain installation URL opens Kafka UI itself."
+          : "Enter an http:// or https:// URL."}
+      </p>
+
+      <div className="mt-4 flex flex-wrap items-center gap-2 border-t border-line pt-4">
+        <button
+          type="button"
+          onClick={save}
+          disabled={!dirty}
+          className="product-primary"
+        >
+          <Save size={14} aria-hidden />
+          Save integration
+        </button>
+        {configured ? (
+          <>
+            <a
+              href={configured}
+              target="_blank"
+              rel="noreferrer"
+              className="tbtn px-3 py-1.5 text-ink"
+            >
+              Open Kafka UI
+              <ExternalLink size={14} aria-hidden />
+            </a>
+            <button
+              type="button"
+              onClick={remove}
+              className="tbtn ml-auto px-3 py-1.5 text-unresolved"
+            >
+              <Trash2 size={14} aria-hidden />
+              Remove
+            </button>
+          </>
+        ) : null}
+      </div>
+    </section>
+  );
+}
+
+export function IntegrationsSettings() {
+  return (
+    <section>
+      <SectionTitle right="stored in this browser">Integrations</SectionTitle>
+      <div className="grid gap-grid lg:grid-cols-2">
+        <KafkaUiCard />
+      </div>
+    </section>
+  );
+}

package/src/routes.test.ts

@@ -169,12 +169,14 @@ describe("routes", () => {
     expect(paths.settingsProjects()).toBe("/settings/projects");
     expect(paths.settingsPipeline()).toBe("/settings/pipeline");
     expect(paths.settingsDelivery()).toBe("/settings/delivery");
+    expect(paths.settingsIntegrations()).toBe("/settings/integrations");
     expect(paths.settingsPreferences()).toBe("/settings/preferences");
     expect(paths.settingsAbout()).toBe("/settings/about");
     for (const path of [
       paths.settingsProjects(),
       paths.settingsPipeline(),
       paths.settingsDelivery(),
+      paths.settingsIntegrations(),
       paths.settingsPreferences(),
       paths.settingsAbout(),
     ]) expect(isRoutable(path)).toBe(true);

package/src/routes.ts

@@ -45,6 +45,7 @@ export const paths = {
   settingsProjects: () => "/settings/projects",
   settingsPipeline: () => "/settings/pipeline",
   settingsDelivery: () => "/settings/delivery",
+  settingsIntegrations: () => "/settings/integrations",
   settingsPreferences: () => "/settings/preferences",
   settingsAbout: () => "/settings/about",
   external: (slug: string) => `/externals/${slug}`,
@@ -375,7 +376,7 @@ const ROUTES: RegExp[] = [
   /^\/language$/,
   /^\/problems$/,
   /^\/changes$/,
-  /^\/settings(?:\/(?:projects|pipeline|delivery|preferences|about))?$/,
+  /^\/settings(?:\/(?:projects|pipeline|delivery|integrations|preferences|about))?$/,
   /^\/externals\/[^/]+$/,
   /^\/map$/,
   /^\/adrs\/[^/]+$/,