@shortlink-org/portolan 0.3.0 → 0.4.0

package/src/lib/integration-url.ts

@@ -0,0 +1,63 @@
+// What every reader-side integration shares: a web address the reader typed
+// in, kept in this browser and nowhere else.
+//
+// The value belongs to the reader, not to the catalog: two readers can point
+// the same generated estate at different installations. It therefore lives in
+// localStorage, like the editor and display preferences, and never reaches
+// portolan.json or a page that is committed.
+
+import { create } from "zustand";
+
+/**
+ * A trimmed http(s) URL without its fragment and trailing slash, "" for an
+ * empty value, and null for anything that cannot be opened safely - a
+ * javascript: address, or words that are not a URL at all.
+ */
+export function normalizeIntegrationUrl(value: string): string | null {
+  const clean = value.trim();
+  if (!clean) return "";
+  try {
+    const url = new URL(clean);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+
+export interface IntegrationState {
+  url: string;
+  setUrl: (url: string) => void;
+}
+
+/** One store per integration, read from localStorage under its own key. */
+export function createIntegrationStore(key: string) {
+  const read = (): string => {
+    try {
+      const value = localStorage.getItem(key) ?? "";
+      return normalizeIntegrationUrl(value) ?? "";
+    } catch {
+      return "";
+    }
+  };
+
+  const write = (value: string): void => {
+    try {
+      if (value) localStorage.setItem(key, value);
+      else localStorage.removeItem(key);
+    } catch {
+      /* private mode: keep the value for this session */
+    }
+  };
+
+  return create<IntegrationState>()((set) => ({
+    url: read(),
+    setUrl: (url) => {
+      const normalized = normalizeIntegrationUrl(url);
+      if (normalized === null) return;
+      write(normalized);
+      set({ url: normalized });
+    },
+  }));
+}

package/src/lib/kafka-ui.ts

@@ -7,24 +7,13 @@
 // installation URL remains useful and opens Kafka UI without inventing a
 // cluster name.
 
-import { create } from "zustand";
 import type { Catalog, Channel } from "../catalog";
 import { walkSteps } from "../catalog";
+import { createIntegrationStore, normalizeIntegrationUrl } from "./integration-url";
 
 export const KAFKA_UI_KEY = "portolan.integrations.kafka-ui";
 
-export function normalizeKafkaUiUrl(value: string): string | null {
-  const clean = value.trim();
-  if (!clean) return "";
-  try {
-    const url = new URL(clean);
-    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
-    url.hash = "";
-    return url.toString().replace(/\/$/, "");
-  } catch {
-    return null;
-  }
-}
+export const normalizeKafkaUiUrl = normalizeIntegrationUrl;
 
 /** Build Kafbat's topic route when the configured URL names a cluster. */
 export function kafkaUiTopicUrl(
@@ -71,35 +60,4 @@ export function isKafkaChannel(
     || handoffChannels.has(channel.address);
 }
 
-function read(): string {
-  try {
-    const value = localStorage.getItem(KAFKA_UI_KEY) ?? "";
-    return normalizeKafkaUiUrl(value) ?? "";
-  } catch {
-    return "";
-  }
-}
-
-function write(value: string): void {
-  try {
-    if (value) localStorage.setItem(KAFKA_UI_KEY, value);
-    else localStorage.removeItem(KAFKA_UI_KEY);
-  } catch {
-    /* private mode: keep the value for this session */
-  }
-}
-
-interface KafkaUiState {
-  url: string;
-  setUrl: (url: string) => void;
-}
-
-export const useKafkaUi = create<KafkaUiState>()((set) => ({
-  url: read(),
-  setUrl: (url) => {
-    const normalized = normalizeKafkaUiUrl(url);
-    if (normalized === null) return;
-    write(normalized);
-    set({ url: normalized });
-  },
-}));
+export const useKafkaUi = createIntegrationStore(KAFKA_UI_KEY);

package/src/lib/local-api.ts

@@ -1,5 +1,6 @@
 import type { SetupDiagnostic, SetupInfo, SetupPhase, SetupProject, SetupRunStepStatus } from "./setup-info";
 import type { DjangoAggregateCandidates } from "./django-aggregates";
+import type { ProblemRuleEntry } from "./problem-rules";
 
 const ROOT = `${import.meta.env.BASE_URL}__portolan`;
 const LOCAL_HEADER = { "Content-Type": "application/json", "X-Portolan-Local": "1" };
@@ -130,13 +131,60 @@ export interface ProjectTrial {
   previewError?: string;
 }
 
+/** One flow the verifier wrote after reading an uploaded recording. */
+export interface TraceTrialFlow {
+  id: string;
+  slug: string;
+  name: string;
+  owner: string;
+  kind: "declared" | "observed";
+  /** Whether the uploaded recording itself showed this flow. */
+  inRecording: boolean;
+  /** Traces in the uploaded recording that showed it. */
+  traces: number;
+  verified: number;
+  unresolved: number;
+  /** Hops the recordings showed that the code does not declare. */
+  added: number;
+  /** Distinct steps the uploaded recording showed. */
+  shown: number;
+  steps: number;
+  examples: number;
+}
+
+export interface TraceTrialWarning {
+  kind: "service" | "event" | "route" | "call" | "channel" | "other";
+  /** The name the verifier could not place, for a service or an event. */
+  name?: string;
+  message: string;
+}
+
+/** What a trial run said about an uploaded recording. */
+export interface TraceTrial {
+  project: string;
+  /** Where the recording lands, relative to the project root. */
+  recording: string;
+  /** Whether keeping it adds or widens the project's verify step. */
+  stepAdded: boolean;
+  /** What keeping it does to portolan.json: a new verify step, one more glob on the step it has, or nothing. */
+  stepChange: "added" | "widened" | "none";
+  status: SetupRunStepStatus;
+  spans: number;
+  flows: TraceTrialFlow[];
+  warnings: TraceTrialWarning[];
+  mappings: { services: Record<string, string>; events: Record<string, string>; routes: Record<string, string> };
+}
+
+export type RunMode = "write" | "check" | "preview" | "project-preview" | "trace-preview";
+
 export type RunEvent =
-  | { type: "run-started"; at: string; runId: string; mode: "write" | "check" | "preview" | "project-preview" }
+  | { type: "run-started"; at: string; runId: string; mode: RunMode }
   | { type: "pipeline-ready"; at: string; stepCount: number }
   | { type: "step-started"; at: string; ordinal: number; phase: SetupPhase; plugin: string; input?: string; output: string }
   | { type: "step-finished"; at: string; ordinal: number; phase: SetupPhase; plugin: string; status: SetupRunStepStatus; durationMs: number; fileCount: number; changedCount: number; changes: Array<{ kind: "added" | "changed" | "removed"; path: string }>; files: string[]; warnings?: string[]; diagnostics?: SetupDiagnostic[]; message?: string }
   | { type: "preview-ready"; at: string; files: GeneratedFileDiff[]; totalFiles: number; truncated: boolean }
   | ({ type: "project-trial-ready"; at: string } & ProjectTrial)
+  | ({ type: "trace-trial-ready"; at: string } & TraceTrial)
   | { type: "run-finished"; at: string; status: string; durationMs?: number; message?: string }
   | { type: "process-finished"; at: string; status: string; durationMs?: number; message?: string }
   | { type: "log"; at: string; stream: "stdout" | "stderr"; message: string };
@@ -178,7 +226,7 @@ export class LocalApiError extends Error {
   }
 }
 
-export async function localStatus(): Promise<{ local: true; workspace: string; setup: SetupInfo; activeRun: { id: string; mode: "write" | "check" | "preview" } | null }> {
+export async function localStatus(): Promise<{ local: true; workspace: string; setup: SetupInfo; activeRun: { id: string; mode: RunMode } | null }> {
   return json("/status");
 }
 
@@ -196,6 +244,21 @@ export async function saveDjangoAggregates(revision: string, selections: Array<{
   return json("/django-aggregates", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify({ revision, selections }) });
 }
 
+/** The manifest's `problemRules`, with a revision a save must quote. */
+export interface ProblemRulesState {
+  revision: string;
+  rules: ProblemRuleEntry[];
+}
+
+export async function problemRules(): Promise<ProblemRulesState> {
+  return json("/rules");
+}
+
+/** Replaces `problemRules` in portolan.json, once the server has type-checked every expression. */
+export async function saveProblemRules(revision: string, rules: ProblemRuleEntry[]): Promise<ProblemRulesState> {
+  return json("/rules", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify({ revision, rules }) });
+}
+
 export async function previewDeliveryPreset(provider?: DeliveryProvider, features?: DeliveryFeatureId[]): Promise<DeliveryPreset> {
   const query = new URLSearchParams();
   if (provider) query.set("provider", provider);
@@ -255,6 +318,37 @@ export async function disposeProjectTrial(runId: string): Promise<void> {
   await json(`/projects/trials/${encodeURIComponent(runId)}/dispose`, { method: "POST", headers: LOCAL_HEADER, body: "{}" });
 }
 
+/**
+ * Uploads a recording and runs the generator over a copy of the workspace
+ * with it in place. The bytes go as they are; the project and the file's
+ * name go as headers, because a JSON envelope around 30 MB of spans is a
+ * copy nobody wants.
+ */
+export async function startTraceTrial(file: File, projectId: string): Promise<{ runId: string; mode: "trace-preview"; recording: string; project: string; stepAdded: boolean; spans: number }> {
+  const response = await fetch(`${ROOT}/traces/trials`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/octet-stream",
+      "X-Portolan-Local": "1",
+      "X-Portolan-Project": projectId,
+      "X-Portolan-Filename": encodeURIComponent(file.name),
+    },
+    body: file,
+  });
+  const value = await response.json() as { runId: string; mode: "trace-preview"; recording: string; project: string; stepAdded: boolean; spans: number; error?: string };
+  if (!response.ok) throw new LocalApiError(value.error || `Local API returned ${response.status}.`, { status: response.status });
+  return value;
+}
+
+/** Keeps the recording beside the project, with the names mapped, and regenerates when asked. */
+export async function applyTraceTrial(runId: string, options: { generate: boolean; services?: Record<string, string>; events?: Record<string, string>; routes?: Record<string, string> }): Promise<{ recording: string; project: string; stepAdded: boolean; manifestChanged: boolean; undoToken: string | null; setup: SetupInfo; run: { runId: string; mode: "write" } | null }> {
+  return json(`/traces/trials/${encodeURIComponent(runId)}/apply`, { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify(options) });
+}
+
+export async function disposeTraceTrial(runId: string): Promise<void> {
+  await json(`/traces/trials/${encodeURIComponent(runId)}/dispose`, { method: "POST", headers: LOCAL_HEADER, body: "{}" });
+}
+
 export async function startGeneration(mode: "write" | "check" | "preview" = "preview", previewRunId?: string): Promise<{ runId: string; mode: "write" | "check" | "preview" }> {
   return json("/runs", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify({ mode, previewRunId }) });
 }

package/src/lib/notion.ts

@@ -0,0 +1,13 @@
+// The optional hand-off from the catalog to the Notion workspace where a
+// team writes.
+//
+// Notion has no search address a link can open, so this is the workspace or
+// teamspace itself: a page says where the documentation lives without
+// pretending to know the page. An exact page would need the catalog to carry
+// its URL, which is a field, not a reader preference.
+
+import { createIntegrationStore } from "./integration-url";
+
+export const NOTION_KEY = "portolan.integrations.notion";
+
+export const useNotion = createIntegrationStore(NOTION_KEY);