@shortlink-org/portolan 0.1.0 → 0.2.0

package/src/chat/page-context.ts

@@ -0,0 +1,128 @@
+// What the reader is looking at when they open Ask the catalog.
+//
+// The route is navigation context, not evidence. It gives the model a useful
+// referent for “this flow” and lets the empty conversation offer questions
+// about the thing already on screen. The answer must still read the generated
+// markdown page before it claims anything about that thing.
+
+import type { Kind } from "../lib/kinds";
+import type { PaletteItem } from "../lib/palette";
+import { catalog } from "../data";
+import { paletteItems } from "../lib/palette";
+
+export interface ChatPageContext {
+  kind: Kind;
+  id: string;
+  title: string;
+  /** Path relative to the profile's docs directory, as llms.txt spells it. */
+  docPath: string | null;
+}
+
+const items = paletteItems(catalog);
+
+function docsPath(item: PaletteItem): string | null {
+  if (!item.path) return null;
+  const parts = item.path.split("?")[0]?.split("#")[0]?.split("/").filter(Boolean) ?? [];
+
+  switch (item.kind) {
+    case "context":
+      return `${item.id}/README.md`;
+    case "service":
+      return parts.length >= 3 ? `${parts[1]}/${parts[2]}/README.md` : null;
+    case "aggregate":
+    case "event":
+    case "vo":
+    case "entity":
+    case "enum":
+    case "command":
+    case "query":
+      return parts.length >= 4
+        ? `${parts[1]}/${parts[2]}/aggregates/${parts[3]}.md`
+        : null;
+    case "flow":
+      return `flows/${item.name}.md`;
+    case "adr":
+      return `adr/${item.id}.md`;
+    case "external":
+      return parts[1] ? `externals/${parts[1]}.md` : null;
+    case "module":
+      return parts[1] ? `modules/${parts[1]}.md` : null;
+    default:
+      return null;
+  }
+}
+
+function titleOf(item: PaletteItem): string {
+  if (item.kind === "flow" || item.kind === "adr" || item.kind === "context") {
+    return item.detail;
+  }
+  return item.name;
+}
+
+/** The exact catalog entity page at this route, if there is one. */
+export function pageContextFrom(
+  candidates: readonly PaletteItem[],
+  pathname: string,
+): ChatPageContext | null {
+  const item = candidates.find((candidate) => candidate.path === pathname);
+  if (!item) return null;
+  return {
+    kind: item.kind,
+    id: item.id,
+    title: titleOf(item),
+    docPath: docsPath(item),
+  };
+}
+
+export function pageContext(pathname: string): ChatPageContext | null {
+  return pageContextFrom(items, pathname);
+}
+
+/** Questions that use the current page instead of making the reader restate it. */
+export function contextQuestions(context: ChatPageContext): string[] {
+  const id = context.id;
+  switch (context.kind) {
+    case "flow":
+      return [
+        `Summarize ${id} and its trust status.`,
+        `Which contexts and services does ${id} cross?`,
+        `Which steps in ${id} are declared rather than verified?`,
+        `Which decisions explain ${id}?`,
+      ];
+    case "context":
+      return [
+        `What does ${id} own?`,
+        `Which services and aggregates are inside ${id}?`,
+        `Which flows cross the boundary of ${id}?`,
+        `Which problems and decisions touch ${id}?`,
+      ];
+    case "service":
+      return [
+        `Summarize ${id} and what it owns.`,
+        `What does ${id} provide and consume?`,
+        `Which flows pass through ${id}?`,
+        `Which decisions and problems touch ${id}?`,
+      ];
+    case "aggregate":
+      return [
+        `Summarize the invariants of ${id}.`,
+        `Show the lifecycle of ${id}.`,
+        `Which commands, queries and events belong to ${id}?`,
+        `Which flows change ${id}?`,
+      ];
+    case "adr":
+      return [
+        `Summarize ${id} and its consequences.`,
+        `Which parts of the catalog does ${id} affect?`,
+        `Which flows are explained by ${id}?`,
+        `What evidence supports ${id}?`,
+      ];
+    default:
+      return [
+        `Summarize ${id}.`,
+        `What is connected to ${id}?`,
+        `Which flows touch ${id}?`,
+        `Which decisions and problems touch ${id}?`,
+      ];
+  }
+}

package/src/chat/prompt.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { clipPage, instructions, pagePath, PAGE_LIMIT } from "./prompt";
+import {
+  clipPage,
+  instructions,
+  pagePath,
+  PAGE_LIMIT,
+  promptPageContext,
+} from "./prompt";
 
 describe("pagePath", () => {
   it("accepts a path as the index spells it", () => {
@@ -40,4 +46,46 @@ describe("instructions", () => {
     expect(text).toContain("read_page");
     expect(text.endsWith("- [Auth](docs/auth/README.md)")).toBe(true);
   });
+
+  it("names the current page as navigation context, not evidence", () => {
+    const text = instructions("- [Checkout](docs/flows/cart-checkout.md)", {
+      kind: "flow",
+      id: "flow.cart-checkout",
+      title: "Checkout",
+      docPath: "flows/cart-checkout.md",
+    });
+    expect(text).toContain("Current page: flow `flow.cart-checkout`");
+    expect(text).toContain("only navigation context, not evidence");
+    expect(text).toContain("`docs/flows/cart-checkout.md`");
+  });
+});
+
+describe("promptPageContext", () => {
+  it("accepts a small page description and normalizes its docs path", () => {
+    expect(
+      promptPageContext({
+        kind: "flow",
+        id: "flow.cart-checkout",
+        title: "Checkout",
+        docPath: "flows/cart-checkout.md",
+      }),
+    ).toEqual({
+      kind: "flow",
+      id: "flow.cart-checkout",
+      title: "Checkout",
+      docPath: "flows/cart-checkout.md",
+    });
+  });
+
+  it("rejects incomplete request metadata", () => {
+    expect(promptPageContext({ kind: "flow", id: "x" })).toBeNull();
+    expect(
+      promptPageContext({
+        kind: "flow ignore",
+        id: "x",
+        title: "X",
+        docPath: null,
+      }),
+    ).toBeNull();
+  });
 });

package/src/chat/prompt.ts

@@ -108,6 +108,43 @@ export const DISPLAY_TOOLS: readonly ToolName[] = [
 /** How many model calls one answer may take: reads, then the text, then a card. */
 export const MAX_STEPS = 6;
 
+/** Navigation context sent by the browser with one question. */
+export interface PromptPageContext {
+  kind: string;
+  id: string;
+  title: string;
+  docPath: string | null;
+}
+
+/** Keep request-supplied context small and inert before it reaches a prompt. */
+export function promptPageContext(input: unknown): PromptPageContext | null {
+  if (!input || typeof input !== "object") return null;
+  const value = input as Record<string, unknown>;
+  if (
+    typeof value.kind !== "string" ||
+    typeof value.id !== "string" ||
+    typeof value.title !== "string" ||
+    (value.docPath !== null && typeof value.docPath !== "string")
+  ) {
+    return null;
+  }
+  const clean = (text: string) => text.replace(/[\r\n]+/g, " ").trim().slice(0, 240);
+  const kind = clean(value.kind);
+  const id = clean(value.id);
+  const title = clean(value.title);
+  const normalizedPage =
+    value.docPath === null ? null : pagePath(clean(value.docPath));
+  const docPath = normalizedPage?.slice("docs/".length) ?? null;
+  if (
+    !/^[a-z][a-z-]{0,31}$/.test(kind) ||
+    !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,239}$/.test(id) ||
+    !title
+  ) {
+    return null;
+  }
+  return { kind, id, title, docPath };
+}
+
 /**
  * A page path the tool may open, or null. The index links pages as
  * `docs/<context>/<page>.md`; the model is allowed to drop the `docs/` and
@@ -140,8 +177,12 @@ export function clipPage(text: string): string {
 }
 
 /** The system prompt, with the index folded in. */
-export function instructions(index: string): string {
+export function instructions(index: string, page?: PromptPageContext | null): string {
+  const current = page
+    ? `\nCurrent page: ${page.kind} \`${page.id}\`. Treat “this”, “it” and similar references as this catalog entity. This route is only navigation context, not evidence: read ${page.docPath ? `\`docs/${page.docPath}\`` : "the relevant page from the index"} before making claims about it.\n`
+    : "";
   return `You are the guide to an architecture catalog: bounded contexts, services, aggregates, events, flows and decisions (ADRs). The index of its pages is below.
+${current}
 
 How to answer:
 - Answer in the language the question was asked in.

package/src/chat/tools.ts

@@ -6,14 +6,19 @@
 
 import { jsonSchema, tool } from "ai";
 import { clipPage, pagePath, TOOL_SPECS } from "./prompt";
+import { activeCatalogProfile } from "../data";
 
 const base = import.meta.env.BASE_URL;
+const profileSuffix =
+  activeCatalogProfile.id === "portolan" ? "" : `${activeCatalogProfile.id}/`;
+const docsBase = `${base}docs/${profileSuffix}`;
+const indexUrl = profileSuffix ? `${docsBase}llms.txt` : `${base}llms.txt`;
 
 /** One page of the generated docs, as the model gets it. */
 export async function readPage(raw: unknown): Promise<string> {
   const path = pagePath(raw);
   if (!path) return "That is not a page of the catalog. Use a path from the index.";
-  const response = await fetch(`${base}${path}`);
+  const response = await fetch(`${docsBase}${path.slice("docs/".length)}`);
   if (!response.ok) return `No page at ${path}. Use a path from the index.`;
   return clipPage(await response.text());
 }
@@ -21,7 +26,7 @@ export async function readPage(raw: unknown): Promise<string> {
 /** llms.txt, once per session. */
 let indexPromise: Promise<string> | null = null;
 export function loadIndex(): Promise<string> {
-  indexPromise ??= fetch(`${base}llms.txt`).then((response) => {
+  indexPromise ??= fetch(indexUrl).then((response) => {
     if (!response.ok) {
       indexPromise = null;
       throw new Error("the catalog index (llms.txt) could not be read");

package/src/chat/transport.ts

@@ -14,7 +14,11 @@ import {
 import type { ChatTransport, UIMessage, UIMessageChunk } from "ai";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import type { ChatRoute, OwnModel } from "./flags";
-import { instructions, MAX_STEPS } from "./prompt";
+import {
+  instructions,
+  MAX_STEPS,
+  promptPageContext,
+} from "./prompt";
 import { useChatUi } from "./store";
 import { browserTools, loadIndex } from "./tools";
 
@@ -22,10 +26,11 @@ type Answering = Extract<ChatRoute, { kind: "proxy" | "own" }>;
 
 class OwnTransport implements ChatTransport<UIMessage> {
   private inner: Promise<ChatTransport<UIMessage>> | null = null;
+  private contextKey = "";
 
   constructor(private readonly own: OwnModel) {}
 
-  private async build(): Promise<ChatTransport<UIMessage>> {
+  private async build(pageContext: unknown): Promise<ChatTransport<UIMessage>> {
     const ui = useChatUi.getState();
     ui.setPhase("index");
     let index: string;
@@ -41,7 +46,7 @@ class OwnTransport implements ChatTransport<UIMessage> {
     });
     const agent = new ToolLoopAgent({
       model: provider.chatModel(this.own.model.trim()),
-      instructions: instructions(index),
+      instructions: instructions(index, promptPageContext(pageContext)),
       tools: browserTools(),
       stopWhen: stepCountIs(MAX_STEPS),
     });
@@ -51,7 +56,14 @@ class OwnTransport implements ChatTransport<UIMessage> {
   async sendMessages(
     options: Parameters<ChatTransport<UIMessage>["sendMessages"]>[0],
   ): Promise<ReadableStream<UIMessageChunk>> {
-    this.inner ??= this.build().catch((error: unknown) => {
+    const pageContext = (options.body as { pageContext?: unknown } | undefined)
+      ?.pageContext;
+    const nextContextKey = JSON.stringify(promptPageContext(pageContext));
+    if (this.contextKey !== nextContextKey) {
+      this.inner = null;
+      this.contextKey = nextContextKey;
+    }
+    this.inner ??= this.build(pageContext).catch((error: unknown) => {
       this.inner = null;
       throw error;
     });

package/src/components/ProblemRow.tsx

@@ -0,0 +1,182 @@
+// One problem, as a row: what the near end is, where both ends live, and
+// the words for what is wrong with the edge between them. The problems page
+// lists every one of these; the overview shows the first few.
+
+import { Link } from "react-router";
+import type { Problem } from "../lib/derive";
+import { ctxStyle } from "../lib/context-color";
+import { staggerStyle } from "../lib/motion";
+import {
+  eventPath,
+  servicePath,
+  storePath,
+  tablePath,
+  viewPath,
+} from "../routes";
+import { KindIcon } from "./kind";
+import { Ident } from "./Ident";
+
+/** The icon a problem row carries: what the near end of the edge IS. */
+const KIND_OF: Record<Problem["kind"], "service" | "event" | "table"> = {
+  rpc: "service",
+  consumer: "event",
+  "cross-service-fk": "table",
+  "cross-service-lineage": "table",
+  "shared-store": "table",
+  "persistence-drift": "table",
+  "column-type": "table",
+  "outbox-payload": "table",
+  "proto-missing": "service",
+  "shared-channel": "event",
+  "channel-undeclared": "event",
+  "channel-unpublished": "service",
+  "subscription-unresolved": "service",
+};
+
+const KIND_NOTE: Record<Problem["kind"], string> = {
+  rpc: "the provider of this call is not in the catalog",
+  consumer: "this consumer of the event is not in the catalog",
+  "cross-service-fk": "foreign key across a service boundary",
+  "cross-service-lineage": "a value copied from another service's schema",
+  "shared-store": "a second service writes this database",
+  "persistence-drift": "this table no longer carries the aggregate it claims",
+  "column-type": "column type and domain type disagree",
+  "outbox-payload": "an outbox with no payload column",
+  "proto-missing":
+    "the provider is in the catalog but answers on no such method",
+  "shared-channel": "a second service publishes on this channel",
+  "channel-undeclared":
+    "this event goes out on a channel the service does not declare",
+  "channel-unpublished": "a declared channel no event of this service names",
+  "subscription-unresolved":
+    "nothing in the catalog publishes what this service listens for",
+};
+
+/** Where the near end of a problem lives, by what kind of edge it is. */
+function nearPath(problem: Problem): string | null {
+  switch (problem.kind) {
+    case "rpc":
+    // The near end is the CALLING service either way. `rpc` is a call whose
+    // peer is nobody; this is a call whose peer is known and whose method is
+    // not - and in both the thing to go and look at is the caller.
+    case "proto-missing":
+      return servicePath(problem.service);
+    case "consumer":
+    case "channel-undeclared":
+      return eventPath(problem.id);
+    // The near end is an event when the service has one on the channel, and
+    // the service itself when the claim comes from its document alone.
+    case "shared-channel":
+      return eventPath(problem.id) ?? servicePath(problem.service);
+    case "channel-unpublished":
+    case "subscription-unresolved":
+      return servicePath(problem.service);
+    case "shared-store":
+    case "persistence-drift":
+    case "outbox-payload":
+      return tablePath(problem.id);
+    // The id is "<relation>.<column>", so the relation is its own id minus the
+    // last segment — and the relation is what the canvas can actually show.
+    case "cross-service-fk":
+    case "column-type":
+      return relationPath(problem.id.split(".").slice(0, -1).join("."));
+    // Lineage is stated on a column, except when a view states it whole, so
+    // the id is one or the other and both are looked up the same way.
+    case "cross-service-lineage":
+      return (
+        relationPath(problem.id) ??
+        relationPath(problem.id.split(".").slice(0, -1).join("."))
+      );
+  }
+}
+
+/** A table or a view, whichever the id turns out to name. */
+function relationPath(id: string): string | null {
+  return tablePath(id) ?? viewPath(id);
+}
+
+/** Where the far end lives, when the catalog knows it. */
+function peerPath(problem: Problem): string | null {
+  switch (problem.kind) {
+    case "cross-service-fk":
+      return tablePath(problem.peer);
+    case "cross-service-lineage":
+      return (
+        relationPath(problem.peer) ??
+        relationPath(problem.peer.split(".").slice(0, -1).join("."))
+      );
+    case "shared-store":
+    case "shared-channel":
+      return servicePath(problem.peer);
+    case "outbox-payload":
+      return storePath(problem.peer);
+    default:
+      return null;
+  }
+}
+
+export function ProblemRow({ problem, index }: { problem: Problem; index: number }) {
+  const near = nearPath(problem);
+  const peerTo = peerPath(problem);
+  const tone =
+    problem.severity === "error"
+      ? "var(--status-unresolved)"
+      : "var(--status-declared)";
+
+  return (
+    <div
+      className="stagger-in flex flex-wrap items-baseline gap-x-3 gap-y-1 rounded-control border px-3 py-2"
+      style={{ ...staggerStyle(index), borderColor: tone }}
+    >
+      <KindIcon kind={KIND_OF[problem.kind]} />
+      {near ? (
+        <Link
+          to={near}
+          data-nav-item
+          className="mono rounded-control text-accent hover:underline"
+          title={problem.id}
+        >
+          {problem.id}
+        </Link>
+      ) : (
+        <Ident value={problem.id} />
+      )}
+      <span aria-hidden className="text-muted">
+        →
+      </span>
+      {peerTo ? (
+        <Link
+          to={peerTo}
+          className="mono rounded-control hover:underline"
+          style={{ color: tone }}
+          title={problem.peer}
+        >
+          {problem.peer}
+        </Link>
+      ) : (
+        <Ident
+          value={problem.peer}
+          className={
+            problem.severity === "error" ? "text-unresolved" : "text-declared"
+          }
+          title={`${problem.peer} — ${KIND_NOTE[problem.kind]}. Click to copy.`}
+        />
+      )}
+      <span className="chip ctx" style={ctxStyle(problem.context)}>
+        <span aria-hidden className="dot" />
+        {problem.context}
+      </span>
+      <span className="mono ml-auto text-muted">{KIND_NOTE[problem.kind]}</span>
+      {problem.note ? (
+        <p className="w-full border-l-2 pl-2 border-line-strong text-muted">
+          {problem.note}
+        </p>
+      ) : null}
+      {problem.source ? (
+        <div className="mono w-full text-muted">
+          <Ident value={problem.source} />
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/data.ts

@@ -35,11 +35,26 @@ import manifestJson from "../portolan.json";
 
 const manifest = manifestJson as CatalogProfileManifest & { sources: string[] };
 export const catalogProfiles: CatalogProfile[] = profilesFromManifest(manifest);
-const requestedProfile =
-  typeof window === "undefined"
-    ? null
-    : new URLSearchParams(window.location.search).get("catalog");
-export const activeCatalogProfile = catalogProfileNamed(manifest, requestedProfile);
+/**
+ * The catalog the public landing page demonstrates. The landing has no
+ * `?catalog=` of its own - it is a page about the product, not about one
+ * estate - and the product is best shown on the example estate rather than on
+ * the three-service catalog Portolan keeps about itself. A manifest without
+ * an `example` profile falls back to its default, as any unknown name does.
+ */
+const LANDING_PROFILE = "example";
+
+function requestedProfileFromUrl(): string | null {
+  if (typeof window === "undefined") return null;
+  const named = new URLSearchParams(window.location.search).get("catalog");
+  if (named) return named;
+  return /\/landing\/?$/.test(window.location.pathname) ? LANDING_PROFILE : null;
+}
+
+export const activeCatalogProfile = catalogProfileNamed(
+  manifest,
+  requestedProfileFromUrl(),
+);
 
 /**
  * Where sources are looked for. The patterns are written out because

package/src/er/ErCanvas.tsx

@@ -342,7 +342,7 @@ function Canvas({
         wrapper={wrapper}
         name={store.id}
       />
-      <div className="relative min-h-0 flex-1">
+      <div className="canvas-motion relative min-h-0 flex-1">
         {layout.ready ? null : <DiagramSkeleton />}
         <ReactFlow
           nodes={nodes}

package/src/graph/DependencyGraph.tsx

@@ -51,6 +51,12 @@ export interface DependencyGraphProps {
    * one it replaced.
    */
   fitKey: string;
+  /**
+   * Whether the wheel zooms the canvas. On the graph's own page it does; on a
+   * page the graph is embedded in, the wheel belongs to the page and the
+   * canvas is zoomed by pinch or by the fit control instead.
+   */
+  zoomOnScroll?: boolean;
 }
 
 export function DependencyGraph({
@@ -58,6 +64,7 @@ export function DependencyGraph({
   mode,
   onMode,
   fitKey,
+  zoomOnScroll = true,
 }: DependencyGraphProps) {
   const navigate = useNavigate();
   const [layout, setLayout] = useState<Layout | null>(null);
@@ -217,7 +224,7 @@ export function DependencyGraph({
   return (
     /* The box is the box whether elk has answered or not: the skeleton is
        laid over it, never in place of it, so nothing reflows on arrival. */
-    <div className="relative h-full w-full">
+    <div className="canvas-motion relative h-full w-full">
       {ready ? null : <DiagramSkeleton />}
       <TinyZoom.Provider value={tiny}>
         <ReactFlow
@@ -238,6 +245,8 @@ export function DependencyGraph({
           proOptions={{ hideAttribution: true }}
           fitView
           fitViewOptions={FIT_OPTIONS}
+          zoomOnScroll={zoomOnScroll}
+          preventScrolling={zoomOnScroll}
           minZoom={0.08}
           maxZoom={2}
           key={ready ? `fit-${fitKey}-${nodes.length}-${edges.length}` : "pending"}

package/src/graph/FocusedEventGraph.tsx

@@ -161,7 +161,7 @@ export function FocusedEventGraph({
   return (
     <div
       style={{ height: canvasHeight }}
-      className="relative w-full overflow-hidden rounded-card border border-line shadow-xs"
+      className="canvas-motion relative w-full overflow-hidden rounded-card border border-line shadow-xs"
     >
       {ready ? null : <DiagramSkeleton />}
       <ReactFlow

package/src/graph/GraphToolbar.tsx

@@ -66,13 +66,11 @@ export function GraphToolbar({
           type="button"
           onClick={() => onFocusing(!focusing)}
           aria-pressed={focusing}
-          className={focusing ? "is-on" : undefined}
+          className={`flex items-center gap-1.5 ${focusing ? "is-on" : ""}`}
           title="Click a service to dim everything more than one hop away (Esc clears)"
         >
           <Crosshair size={13} aria-hidden />
-          <span className="ml-1.5">
-            {focused && focusing ? focusedLabel(focused) : "focus"}
-          </span>
+          <span>{focused && focusing ? focusedLabel(focused) : "focus"}</span>
         </button>
       </div>