@shortlink-org/portolan 0.1.0

package/src/chat/prompt.ts

@@ -0,0 +1,157 @@
+// What the model is told, and what it may ask for.
+//
+// One file for both halves of the chat: the browser, when the reader brings
+// their own key, and the Cloudflare worker in proxy/, which imports this file
+// as it is. The rules a page path has to satisfy therefore cannot drift
+// between the two, and neither can the instructions.
+//
+// The model never sees the whole catalog. It sees llms.txt - the index, a few
+// hundred lines naming every page - and a tool that opens one page at a time.
+// Four opened pages cost a tenth of the tokens the full file would, which on
+// a free tier is the difference between a demo that answers all day and one
+// that stops before lunch.
+
+/** Longest page the tool hands back; the rest is cut with a note. */
+export const PAGE_LIMIT = 60_000;
+
+export type ToolName =
+  | "read_page"
+  | "show_service"
+  | "show_flow"
+  | "show_between"
+  | "show_lifecycle";
+
+/** A tool as both halves declare it: a sentence and a flat object schema. */
+export interface ToolSpec {
+  description: string;
+  input: {
+    type: "object";
+    properties: Record<string, { type: "string"; description: string }>;
+    required: string[];
+  };
+}
+
+/** Every tool, with the schema both halves declare it with. */
+export const TOOL_SPECS: Record<ToolName, ToolSpec> = {
+  read_page: {
+    description:
+      "Open one page of the catalog by the path the index gives, e.g. docs/auth/README.md. Returns its markdown.",
+    input: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "A path exactly as the index spells it",
+        },
+      },
+      required: ["path"],
+    },
+  },
+  show_service: {
+    description:
+      "Show one service as a card: its context, what it provides and consumes, its aggregates and events. Call it last, after the text.",
+    input: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The service id, e.g. shop.oms" },
+      },
+      required: ["id"],
+    },
+  },
+  show_flow: {
+    description:
+      "Draw one flow as a sequence diagram. Call it last, after the text.",
+    input: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The flow id or slug" },
+      },
+      required: ["id"],
+    },
+  },
+  show_between: {
+    description:
+      "Show what runs between two bounded contexts: every call one makes into the other. Call it last, after the text.",
+    input: {
+      type: "object",
+      properties: {
+        a: { type: "string", description: "A context id, e.g. shop" },
+        b: { type: "string", description: "Another context id, e.g. payments" },
+      },
+      required: ["a", "b"],
+    },
+  },
+  show_lifecycle: {
+    description:
+      "Draw an aggregate's state machine. Call it last, after the text.",
+    input: {
+      type: "object",
+      properties: {
+        aggregate: {
+          type: "string",
+          description: "The aggregate id, e.g. auth.auth.user",
+        },
+      },
+      required: ["aggregate"],
+    },
+  },
+};
+
+/** The tools that draw something and end the answer rather than continue it. */
+export const DISPLAY_TOOLS: readonly ToolName[] = [
+  "show_service",
+  "show_flow",
+  "show_between",
+  "show_lifecycle",
+];
+
+/** How many model calls one answer may take: reads, then the text, then a card. */
+export const MAX_STEPS = 6;
+
+/**
+ * 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
+ * a leading slash, and nothing else - no scheme, no `..`, no other extension.
+ */
+export function pagePath(input: unknown): string | null {
+  if (typeof input !== "string") return null;
+  let path = input.trim().replace(/^\.?\//, "");
+  if (!path.startsWith("docs/")) path = `docs/${path}`;
+  if (!path.endsWith(".md")) return null;
+  const segments = path.split("/");
+  if (
+    segments.some(
+      (segment) =>
+        segment === "" ||
+        segment === "." ||
+        segment === ".." ||
+        !/^[A-Za-z0-9._-]+$/.test(segment),
+    )
+  ) {
+    return null;
+  }
+  return path;
+}
+
+/** The page as the model gets it: cut at the limit, and told so. */
+export function clipPage(text: string): string {
+  if (text.length <= PAGE_LIMIT) return text;
+  return `${text.slice(0, PAGE_LIMIT)}\n\n[cut: the page goes on for ${text.length - PAGE_LIMIT} more characters]`;
+}
+
+/** The system prompt, with the index folded in. */
+export function instructions(index: string): string {
+  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.
+
+How to answer:
+- Answer in the language the question was asked in.
+- Before answering about a particular service, flow, decision, aggregate or context, call read_page on the page that documents it. The index says what each page covers. Open at most four pages per answer.
+- Name things by their catalog ids, spelled exactly as the catalog spells them (shop.oms, auth.auth.user.PasswordChanged, adr slugs), so they can be linked.
+- Be brief: a few sentences or a short list. Markdown is fine. Never draw diagrams yourself.
+- When a picture would help, finish with exactly one show_* call: show_service for one service, show_flow for a flow, show_between for what runs between two contexts, show_lifecycle for an aggregate's state machine. Write the text first; the call is the last thing in the answer.
+- When the catalog does not say, say so rather than guess.
+
+# Index
+
+${index}`;
+}

package/src/chat/store.ts

@@ -0,0 +1,35 @@
+// Shell state of the chat: open or not, and what the panel is waiting on.
+//
+// Kept apart from the panel because the top bar opens it and the transport
+// reports into it, and neither should have to import the panel - which is
+// loaded lazily and carries the SDK.
+
+import { create } from "zustand";
+
+/** What the reader is waiting for, when it is not the model's own words. */
+export type Phase = "index" | null;
+
+interface ChatUiState {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  /** "index" while the browser fetches llms.txt before the first question. */
+  phase: Phase;
+  setPhase: (phase: Phase) => void;
+  /** When the current question was sent, for the "took 31s" line. */
+  askedAt: number | null;
+  setAskedAt: (at: number | null) => void;
+  /** Seconds each answer took, by message id. */
+  took: Record<string, number>;
+  noteTook: (id: string, seconds: number) => void;
+}
+
+export const useChatUi = create<ChatUiState>()((set) => ({
+  open: false,
+  setOpen: (open) => set({ open }),
+  phase: null,
+  setPhase: (phase) => set({ phase }),
+  askedAt: null,
+  setAskedAt: (askedAt) => set({ askedAt }),
+  took: {},
+  noteTook: (id, seconds) => set((s) => ({ took: { ...s.took, [id]: seconds } })),
+}));

package/src/chat/tools.ts

@@ -0,0 +1,58 @@
+// The tools as the browser declares them, for a reader's own model.
+//
+// read_page runs here and fetches the page from the site itself; the show_*
+// tools have no execute on purpose - a call to one ends the answer, and the
+// panel draws the card from the catalog it already has.
+
+import { jsonSchema, tool } from "ai";
+import { clipPage, pagePath, TOOL_SPECS } from "./prompt";
+
+const base = import.meta.env.BASE_URL;
+
+/** 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}`);
+  if (!response.ok) return `No page at ${path}. Use a path from the index.`;
+  return clipPage(await response.text());
+}
+
+/** llms.txt, once per session. */
+let indexPromise: Promise<string> | null = null;
+export function loadIndex(): Promise<string> {
+  indexPromise ??= fetch(`${base}llms.txt`).then((response) => {
+    if (!response.ok) {
+      indexPromise = null;
+      throw new Error("the catalog index (llms.txt) could not be read");
+    }
+    return response.text();
+  });
+  return indexPromise;
+}
+
+export function browserTools() {
+  return {
+    read_page: tool({
+      description: TOOL_SPECS.read_page.description,
+      inputSchema: jsonSchema<{ path: string }>(TOOL_SPECS.read_page.input),
+      execute: ({ path }) => readPage(path),
+    }),
+    show_service: tool({
+      description: TOOL_SPECS.show_service.description,
+      inputSchema: jsonSchema<{ id: string }>(TOOL_SPECS.show_service.input),
+    }),
+    show_flow: tool({
+      description: TOOL_SPECS.show_flow.description,
+      inputSchema: jsonSchema<{ id: string }>(TOOL_SPECS.show_flow.input),
+    }),
+    show_between: tool({
+      description: TOOL_SPECS.show_between.description,
+      inputSchema: jsonSchema<{ a: string; b: string }>(TOOL_SPECS.show_between.input),
+    }),
+    show_lifecycle: tool({
+      description: TOOL_SPECS.show_lifecycle.description,
+      inputSchema: jsonSchema<{ aggregate: string }>(TOOL_SPECS.show_lifecycle.input),
+    }),
+  };
+}

package/src/chat/transport.ts

@@ -0,0 +1,70 @@
+// How a question reaches a model.
+//
+// Through the proxy it is one POST to the worker, which holds the key and the
+// tools. With the reader's own key the whole loop runs in the browser: the
+// agent, the read_page tool and the index it needs - fetched on the first
+// question, not at load, because most readers never open the panel.
+
+import {
+  DefaultChatTransport,
+  DirectChatTransport,
+  ToolLoopAgent,
+  stepCountIs,
+} from "ai";
+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 { useChatUi } from "./store";
+import { browserTools, loadIndex } from "./tools";
+
+type Answering = Extract<ChatRoute, { kind: "proxy" | "own" }>;
+
+class OwnTransport implements ChatTransport<UIMessage> {
+  private inner: Promise<ChatTransport<UIMessage>> | null = null;
+
+  constructor(private readonly own: OwnModel) {}
+
+  private async build(): Promise<ChatTransport<UIMessage>> {
+    const ui = useChatUi.getState();
+    ui.setPhase("index");
+    let index: string;
+    try {
+      index = await loadIndex();
+    } finally {
+      useChatUi.getState().setPhase(null);
+    }
+    const provider = createOpenAICompatible({
+      name: "own",
+      baseURL: this.own.baseUrl.trim().replace(/\/+$/, ""),
+      ...(this.own.apiKey.trim() ? { apiKey: this.own.apiKey.trim() } : {}),
+    });
+    const agent = new ToolLoopAgent({
+      model: provider.chatModel(this.own.model.trim()),
+      instructions: instructions(index),
+      tools: browserTools(),
+      stopWhen: stepCountIs(MAX_STEPS),
+    });
+    return new DirectChatTransport({ agent }) as unknown as ChatTransport<UIMessage>;
+  }
+
+  async sendMessages(
+    options: Parameters<ChatTransport<UIMessage>["sendMessages"]>[0],
+  ): Promise<ReadableStream<UIMessageChunk>> {
+    this.inner ??= this.build().catch((error: unknown) => {
+      this.inner = null;
+      throw error;
+    });
+    return (await this.inner).sendMessages(options);
+  }
+
+  async reconnectToStream(): Promise<ReadableStream<UIMessageChunk> | null> {
+    return null;
+  }
+}
+
+export function transportFor(route: Answering): ChatTransport<UIMessage> {
+  return route.kind === "proxy"
+    ? new DefaultChatTransport<UIMessage>({ api: route.url })
+    : new OwnTransport(route.model);
+}

package/src/components/AdrRow.tsx

@@ -0,0 +1,29 @@
+import { Link } from "react-router";
+import type { Adr } from "../catalog";
+import { paths } from "../routes";
+import { AdrNumber, AdrScopePill, AdrStatusChip } from "./primitives";
+
+/**
+ * The columns a list of these rows declares, so every field starts at the
+ * same x down the list: number, title, status, scope, date.
+ */
+export const ADR_ROW_COLUMNS = "grid-cols-[auto_minmax(0,1fr)_auto_auto_auto]";
+
+/**
+ * One decision in a list that is not the decisions index itself. The list
+ * is a `.rows` grid with {@link ADR_ROW_COLUMNS}; the row is a subgrid of
+ * it, so the title takes what is left and the chips line up.
+ */
+export function AdrRow({ adr }: { adr: Adr }) {
+  return (
+    <Link to={paths.adr(adr.slug)} data-nav-item className="row">
+      <AdrNumber adr={adr} />
+      <span className="truncate font-semibold" title={adr.title}>
+        {adr.title}
+      </span>
+      <AdrStatusChip status={adr.status} />
+      <AdrScopePill scope={adr.scope} link={false} />
+      <span className="mono tnum text-muted">{adr.date}</span>
+    </Link>
+  );
+}

package/src/components/AnchorLink.tsx

@@ -0,0 +1,67 @@
+// The link back to a heading.
+//
+// Every section in this app already has an id - the counts in a page header
+// link to them, and the TOC walks them - but until now the only way to get one
+// out of the app was to read the TOC's href off the status bar. This is the
+// other half: a real <a> to the fragment, so the browser's own "copy link
+// address" works, and a click that also puts the absolute URL on the clipboard,
+// because that is what the reader wanted from the click.
+//
+// It is hidden until the heading is hovered or something in it takes focus,
+// for the same reason RowActions is: a page with nine sections must not also be
+// a page with nine little chain icons down the left.
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Check, Link2 } from "lucide-react";
+import { anchorUrl, toClipboard } from "../lib/clipboard";
+
+const SHOWN_MS = 1000;
+
+export function AnchorLink({
+  id,
+  label,
+}: {
+  /** The id of the element on the page this points at. */
+  id: string;
+  /** What the link says it points at, for the accessible name. */
+  label?: string;
+}) {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  // No preventDefault: the browser still moves to the fragment and puts it in
+  // the address bar, which is half of what "link to this" means. The copy is
+  // the other half, and it rides along.
+  const onClick = useCallback(() => {
+    void toClipboard(anchorUrl(id)).then((ok) => {
+      setCopied(ok);
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = setTimeout(() => setCopied(false), SHOWN_MS);
+    });
+  }, [id]);
+
+  const what = label ? `link to ${label}` : "link to this section";
+
+  return (
+    <a
+      href={`#${id}`}
+      onClick={onClick}
+      className="anchor-link"
+      aria-label={`Copy ${what}`}
+      title={copied ? "copied" : `Copy ${what}`}
+    >
+      {copied ? (
+        <Check size={12} aria-hidden />
+      ) : (
+        <Link2 size={12} aria-hidden />
+      )}
+    </a>
+  );
+}

package/src/components/ApiReference.tsx

@@ -0,0 +1,134 @@
+// The OpenAPI document itself, rendered.
+//
+// This is the one place in portolan that draws something the catalog did not
+// give it. Everywhere else the rule holds - the catalog is the input, the site
+// is the output - and it holds here too in the sense that matters: the catalog
+// is what says this service has a document and where it lives. What the
+// catalog cannot carry is the document's own shape, endpoint by endpoint, and
+// re-deriving that into the schema would be rebuilding OpenAPI inside it.
+//
+// So the provides tab keeps the extracted facts - the ones that are searchable,
+// linkable and comparable with a proto service next door - and this tab shows
+// the source document beside them.
+
+import { lazy, Suspense, useEffect, useState } from "react";
+import { useTheme } from "../app/theme";
+import { loaderFor as loaderIn } from "../lib/spec-files";
+import { Empty } from "./PageHeader";
+
+/**
+ * Loaded on demand, so a reader who never opens this tab never waits for it and
+ * the reference does not sit in the chunk the app boots from.
+ */
+const Reference = lazy(async () => {
+  // The stylesheet is a separate export and the bundle does not pull it in, so
+  // it is imported here rather than at the top of the file: alongside the
+  // component it styles, and only when that component is actually wanted.
+  await import("@scalar/api-reference-react/style.css");
+  const { ApiReferenceReact } = await import("@scalar/api-reference-react");
+
+  return { default: ApiReferenceReact };
+});
+
+/**
+ * The documents in the repository, by path, loaded on demand.
+ *
+ * A spec that lives in another repository is not here, and that is the normal
+ * case for a real estate: the catalog still lists what the service answers,
+ * and this tab says plainly that it has nothing to show.
+ */
+const SPECS = import.meta.glob<string>(
+  [
+    "../../**/openapi*.yaml",
+    "../../**/openapi*.yml",
+    "../../**/openapi*.json",
+    "../../**/swagger*.yaml",
+    "../../**/swagger*.yml",
+    "../../**/swagger*.json",
+    "../../examples/**/openapi*.yaml",
+    "../../examples/**/openapi*.yml",
+    "../../examples/**/openapi*.json",
+    "../../examples/**/swagger*.yaml",
+    "../../examples/**/swagger*.yml",
+    "../../examples/**/swagger*.json",
+    "../../vendor/repos/**/openapi*.yaml",
+    "../../vendor/repos/**/openapi*.yml",
+    "../../vendor/repos/**/openapi*.json",
+    "../../vendor/repos/**/swagger*.yaml",
+    "../../vendor/repos/**/swagger*.yml",
+    "../../vendor/repos/**/swagger*.json",
+    // Local onboarding writes generated documents under the project's
+    // conventional portolan directory, wherever that project lives.
+    "../../**/portolan/openapi*.yaml",
+    "../../**/portolan/openapi*.yml",
+    "../../**/portolan/openapi*.json",
+    "!../../node_modules/**",
+    "!../../dist/**",
+    "!../../.portolan/**",
+  ],
+  { query: "?raw", import: "default" },
+);
+
+function loaderFor(source: string): (() => Promise<string>) | null {
+  return loaderIn(SPECS, source);
+}
+
+/** Whether the document a catalog entry points at is one this site can show. */
+export function hasSpec(source: string): boolean {
+  return loaderFor(source) !== null;
+}
+
+export function ApiReference({ source }: { source: string }) {
+  const { theme } = useTheme();
+  const [spec, setSpec] = useState<string | null>(null);
+  const [missing, setMissing] = useState(false);
+
+  useEffect(() => {
+    const load = loaderFor(source);
+    if (!load) {
+      setMissing(true);
+
+      return;
+    }
+
+    let live = true;
+    load()
+      .then((text) => {
+        if (live) setSpec(text);
+      })
+      .catch(() => {
+        if (live) setMissing(true);
+      });
+
+    return () => {
+      live = false;
+    };
+  }, [source]);
+
+  if (missing) {
+    return (
+      <Empty>
+        this service&apos;s document is not in this repository — only what the
+        catalog extracted from it is
+      </Empty>
+    );
+  }
+
+  if (spec === null) return <Empty>reading the document…</Empty>;
+
+  return (
+    <div className="rounded-card border border-line">
+      <Suspense fallback={<Empty>loading the reference…</Empty>}>
+        <Reference
+          configuration={{
+            content: spec,
+            // Its sidebar would be a second navigation tree beside the one the
+            // app already has, listing the same endpoints.
+            showSidebar: false,
+            forceDarkModeState: theme,
+          }}
+        />
+      </Suspense>
+    </div>
+  );
+}

package/src/components/AsyncApiReference.tsx

@@ -0,0 +1,120 @@
+// The AsyncAPI document itself, rendered.
+//
+// The same argument the OpenAPI reference makes beside it holds here, and for
+// the same reason: the catalog says the service has a document and where it
+// lives, the bus tab keeps the facts read out of it - the channels, and which
+// way each message travels - and this shows the document those were read from.
+// Re-deriving a document's own shape into the schema would be rebuilding
+// AsyncAPI inside it.
+//
+// What it does NOT do is draw the channels. Those are catalog facts by the time
+// they reach a page: they link to the event that publishes a message and to the
+// service that listens for one, which a rendered document cannot do because it
+// has never heard of the estate around it.
+
+import { lazy, Suspense, useEffect, useState } from "react";
+import { loaderFor as loaderIn } from "../lib/spec-files";
+import { Empty } from "./PageHeader";
+
+/**
+ * Loaded on demand. This one is worth more than the OpenAPI reference is: the
+ * component brings the AsyncAPI parser with it, which is most of its weight,
+ * and a reader who never opens the tab pays none of it.
+ */
+// The parser inside the component is a Node library that reached the browser
+// unchanged - it calls Buffer, util and process while it loads - and the shims
+// it needs are named in vite.config.ts.
+const Reference = lazy(async () => {
+  // The stylesheet is a separate file the bundle does not pull in, so it is
+  // imported here rather than at the top: alongside the component it styles,
+  // and only when that component is wanted. Everything in it is scoped under
+  // `.aui-root`, so it meets the app's own styles nowhere.
+  await import("@asyncapi/react-component/styles/default.min.css");
+  const { default: AsyncApiComponent } = await import(
+    "@asyncapi/react-component"
+  );
+
+  return { default: AsyncApiComponent };
+});
+
+/**
+ * The documents in the repository, by path, loaded on demand. A document that
+ * lives in another repository is not here, and that is the normal case: the
+ * catalog still lists the channels, and this tab says plainly it has nothing
+ * to show.
+ */
+const SPECS = import.meta.glob<string>(
+  [
+    "../../**/asyncapi.yaml",
+    "../../**/asyncapi.yml",
+    "!../../node_modules/**",
+    "!../../dist/**",
+    "!../../.portolan/**",
+  ],
+  { query: "?raw", import: "default" },
+);
+
+/** Whether the document a catalog entry points at is one this site can show. */
+export function hasAsyncSpec(source: string): boolean {
+  return loaderIn(SPECS, source) !== null;
+}
+
+export function AsyncApiReference({ source }: { source: string }) {
+  const [spec, setSpec] = useState<string | null>(null);
+  const [missing, setMissing] = useState(false);
+
+  useEffect(() => {
+    const load = loaderIn(SPECS, source);
+    if (!load) {
+      setMissing(true);
+
+      return;
+    }
+
+    let live = true;
+    load()
+      .then((text) => {
+        if (live) setSpec(text);
+      })
+      .catch(() => {
+        if (live) setMissing(true);
+      });
+
+    return () => {
+      live = false;
+    };
+  }, [source]);
+
+  if (missing) {
+    return (
+      <Empty>
+        this service&apos;s document is not in this repository — only the
+        channels the catalog extracted from it are
+      </Empty>
+    );
+  }
+
+  if (spec === null) return <Empty>reading the document…</Empty>;
+
+  return (
+    /* A sheet of paper on a dark desk: the document is drawn light whatever the
+       app's theme is, because the component's own stylesheet has no dark mode
+       to switch. `.spec-sheet` in index.css is where that is arranged, and why
+       it takes re-declaring the palette rather than painting a background. */
+    <div className="spec-sheet overflow-x-auto rounded-card border border-line p-2">
+      <Suspense fallback={<Empty>loading the reference…</Empty>}>
+        <Reference
+          schema={spec}
+          config={{
+            show: {
+              // Its sidebar would be a second navigation tree beside the one
+              // the app already has, over the same channels.
+              sidebar: false,
+              errors: true,
+            },
+          }}
+        />
+      </Suspense>
+    </div>
+  );
+}