@shortlink-org/portolan 0.2.4 → 0.4.0

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

@@ -1,21 +1,45 @@
 import { ExternalLink, Save, Trash2 } from "lucide-react";
 import { useState } from "react";
+import type { StoreApi, UseBoundStore } from "zustand";
 import { SectionTitle } from "../../components/PageHeader";
 import { TechIcon } from "../../components/TechIcon";
-import { normalizeKafkaUiUrl, useKafkaUi } from "../../lib/kafka-ui";
+import { useConfluence } from "../../lib/confluence";
+import { normalizeIntegrationUrl } from "../../lib/integration-url";
+import type { IntegrationState } from "../../lib/integration-url";
+import { useKafkaUi } from "../../lib/kafka-ui";
+import { useNotion } from "../../lib/notion";
 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);
+function IntegrationCard({
+  name,
+  brand,
+  summary,
+  label,
+  placeholder,
+  hint,
+  store,
+}: {
+  /** The heading, and what the open button says. */
+  name: string;
+  /** The brand whose mark sits beside the heading. */
+  brand: string;
+  summary: string;
+  label: string;
+  placeholder: string;
+  /** What a valid URL means: shown under the field. */
+  hint: string;
+  store: UseBoundStore<StoreApi<IntegrationState>>;
+}) {
+  const configured = store((state) => state.url);
+  const setUrl = store((state) => state.setUrl);
   const [draft, setDraft] = useState(configured);
-  const normalized = normalizeKafkaUiUrl(draft);
+  const normalized = normalizeIntegrationUrl(draft);
   const valid = normalized !== null;
   const dirty = valid && normalized !== configured;
-  const glyph = techGlyph("Kafka");
+  const glyph = techGlyph(brand);
 
   const save = () => {
     if (normalized === null) return;
@@ -36,19 +60,17 @@ function KafkaUiCard() {
         </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>
+            <h2 className="font-semibold text-ink">{name}</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>
+          <p className="mt-1 text-muted">{summary}</p>
         </div>
       </div>
 
       <label className="mt-4 block">
-        <span className="label mb-1.5 block">Kafka UI cluster URL</span>
+        <span className="label mb-1.5 block">{label}</span>
         <input
           type="url"
           value={draft}
@@ -56,7 +78,7 @@ function KafkaUiCard() {
           onKeyDown={(event) => {
             if (event.key === "Enter" && dirty) save();
           }}
-          placeholder="https://kafka.example/ui/clusters/production"
+          placeholder={placeholder}
           spellCheck={false}
           autoComplete="off"
           aria-invalid={!valid}
@@ -64,9 +86,7 @@ function KafkaUiCard() {
         />
       </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."}
+        {valid ? hint : "Enter an http:// or https:// URL."}
       </p>
 
       <div className="mt-4 flex flex-wrap items-center gap-2 border-t border-line pt-4">
@@ -87,7 +107,7 @@ function KafkaUiCard() {
               rel="noreferrer"
               className="tbtn px-3 py-1.5 text-ink"
             >
-              Open Kafka UI
+              Open {name}
               <ExternalLink size={14} aria-hidden />
             </a>
             <button
@@ -110,7 +130,33 @@ export function IntegrationsSettings() {
     <section>
       <SectionTitle right="stored in this browser">Integrations</SectionTitle>
       <div className="grid gap-grid lg:grid-cols-2">
-        <KafkaUiCard />
+        <IntegrationCard
+          name="Kafka UI"
+          brand="Kafka"
+          summary="Opens catalogued Kafka topics in your Kafbat Kafka UI installation."
+          label="Kafka UI cluster URL"
+          placeholder="https://kafka.example/ui/clusters/production"
+          hint="Use a cluster or topics URL to open the exact topic. A plain installation URL opens Kafka UI itself."
+          store={useKafkaUi}
+        />
+        <IntegrationCard
+          name="Confluence"
+          brand="Confluence"
+          summary="Searches your wiki for a service or context by name, from its page."
+          label="Confluence site or space URL"
+          placeholder="https://acme.atlassian.net/wiki/spaces/ARCH"
+          hint="A space URL searches that space only. A site URL searches the whole wiki. Cloud and Server are both understood."
+          store={useConfluence}
+        />
+        <IntegrationCard
+          name="Notion"
+          brand="Notion"
+          summary="Opens the Notion workspace where the documentation lives, from a service or context page."
+          label="Notion workspace or teamspace URL"
+          placeholder="https://www.notion.so/acme"
+          hint="Notion has no search address, so every page opens this URL as it is."
+          store={useNotion}
+        />
       </div>
     </section>
   );

package/src/pages/settings/RecordingSettings.tsx

@@ -0,0 +1,138 @@
+// Recordings, for the whole estate: what the catalog was verified against,
+// and a place to add one without first finding the flow it shows.
+//
+// A recording added here goes to the project the reader names. The trial
+// then says which flows it showed - which is how a reader with an export
+// from the collector and no idea which flow it is finds out.
+
+import { useMemo, useRef, useState } from "react";
+import { Disc3, Upload } from "lucide-react";
+import { Link } from "react-router";
+import { catalog } from "../../data";
+import { useToastStore } from "../../app/toast";
+import { TraceTrialPanel } from "../../flow/TraceTrial";
+import { forgetTraceTrial, recallTraceTrial, rememberTraceTrial, sessionStore } from "../../flow/trace-trial-resume";
+import { plural } from "../../lib/format";
+import { startTraceTrial } from "../../lib/local-api";
+import type { SetupProject } from "../../lib/setup-info";
+import { paths } from "../../routes";
+
+const FIELD = "w-full rounded-control border border-line bg-canvas px-2.5 py-1.5 text-ink";
+const SCOPE = "settings";
+
+/** Every recording the catalog names, with the flows it is an example of. */
+function recordingsInCatalog() {
+  const byFile = new Map<string, { traces: Set<string>; flows: Map<string, string> }>();
+  for (const flow of catalog.flows) {
+    for (const example of flow.examples ?? []) {
+      const entry = byFile.get(example.recording) ?? { traces: new Set(), flows: new Map() };
+      entry.traces.add(example.traceId);
+      entry.flows.set(flow.slug, flow.name);
+      byFile.set(example.recording, entry);
+    }
+  }
+  return [...byFile.entries()]
+    .map(([recording, entry]) => ({ recording, traces: entry.traces.size, flows: [...entry.flows.entries()] }))
+    .sort((a, b) => a.recording.localeCompare(b.recording));
+}
+
+export function RecordingSettings({ local, projects }: { local: boolean; projects: readonly SetupProject[] }) {
+  const say = useToastStore((s) => s.say);
+  const input = useRef<HTMLInputElement | null>(null);
+  const [projectId, setProjectId] = useState(projects[0]?.id ?? "");
+  // Picked back up from before a reload: keeping a recording reloads the
+  // page twice, and the panel outlives it.
+  const [resumed] = useState(() => recallTraceTrial(sessionStore(), SCOPE));
+  const [runId, setRunId] = useState<string | null>(resumed?.runId ?? null);
+  const [busy, setBusy] = useState(false);
+  const known = useMemo(recordingsInCatalog, []);
+
+  async function upload(file: File) {
+    if (!projectId) return;
+    setBusy(true);
+    try {
+      const started = await startTraceTrial(file, projectId);
+      rememberTraceTrial(sessionStore(), SCOPE, { runId: started.runId, writeRunId: null });
+      setRunId(started.runId);
+    } catch (cause) {
+      say(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      setBusy(false);
+      if (input.current) input.current.value = "";
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-5">
+      <div className="rounded-card border border-line p-card shadow-xs">
+        <div className="flex items-center gap-2 font-semibold text-ink">
+          <Disc3 size={16} className="text-accent" /> Add a recording
+        </div>
+        <p className="mt-1 max-w-prose text-muted">
+          An OTLP JSON export - one batch per file or one per line, as a collector's file exporter writes it. The generator runs over a copy of the workspace with it in place and shows which flows it verified, what it added to them and which names it could not place, before the recording is kept beside the project.
+        </p>
+        {local ? (
+          <div className="mt-3 flex flex-wrap items-end gap-3">
+            <label className="min-w-56">
+              <span className="label mb-1.5 block">project</span>
+              <select className={FIELD} value={projectId} onChange={(e) => setProjectId(e.target.value)}>
+                {projects.length ? null : <option value="">no projects in portolan.json</option>}
+                {projects.map((p) => <option key={p.id} value={p.id}>{p.name} · {p.root}</option>)}
+              </select>
+            </label>
+            <button type="button" className="product-primary" disabled={busy || !projectId || runId !== null} onClick={() => input.current?.click()}>
+              <Upload size={14} /> Choose a file
+            </button>
+            <input
+              ref={input}
+              type="file"
+              accept=".jsonl,.json,.ndjson,application/json"
+              className="hidden"
+              onChange={(e) => { const file = e.target.files?.[0]; if (file) void upload(file); }}
+            />
+          </div>
+        ) : (
+          <div className="empty mt-3">
+            Start <code>portolan dev</code> to add recordings in this repository.
+          </div>
+        )}
+        {runId ? (
+          <div className="mt-4 border-t border-line pt-4">
+            <TraceTrialPanel
+              key={runId}
+              runId={runId}
+              initialWriteRunId={resumed?.runId === runId ? resumed.writeRunId : null}
+              onWriteStarted={(writeRunId) => rememberTraceTrial(sessionStore(), SCOPE, { runId, writeRunId })}
+              onDone={() => { forgetTraceTrial(sessionStore()); setRunId(null); }}
+            />
+          </div>
+        ) : null}
+      </div>
+
+      <section>
+        <div className="label mb-2">recordings the catalog was verified against · {known.length}</div>
+        {known.length ? (
+          <div className="divide-y divide-line rounded-control border border-line">
+            {known.map((entry) => (
+              <div key={entry.recording} className="grid gap-1 px-3 py-2 sm:grid-cols-[1fr_auto]">
+                <div className="min-w-0">
+                  <div className="mono truncate text-ink" title={entry.recording}>{entry.recording}</div>
+                  <div className="mt-0.5 flex flex-wrap gap-x-2 text-muted">
+                    {entry.flows.map(([slug, name]) => (
+                      <Link key={slug} to={paths.flow(slug)} className="hover:underline">{name}</Link>
+                    ))}
+                  </div>
+                </div>
+                <span className="mono text-muted sm:text-right">{entry.traces} {plural(entry.traces, "trace")} kept as {plural(entry.traces, "an example", "examples")}</span>
+              </div>
+            ))}
+          </div>
+        ) : (
+          <div className="rounded-control border border-line bg-surface px-3 py-3 text-muted">
+            No flow in this catalog carries a recording yet. A verify step with the otel plugin reads them; adding one above writes that step for you.
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}