@shortlink-org/portolan 0.1.0

package/src/chat/Starter.tsx

@@ -0,0 +1,67 @@
+// What the panel shows before the first question.
+//
+// Two lines on what it can do, and four questions this catalog can answer,
+// drawn as rows the way the palette draws its results - a list to pick from,
+// not a stack of buttons.
+
+import { KindIcon } from "../components/kind";
+import type { Kind } from "../lib/kinds";
+import { catalog } from "../data";
+
+interface Example {
+  kind: Kind;
+  contextId?: string;
+  question: string;
+}
+
+/** Questions this catalog can answer, built from what it has. */
+function examples(): Example[] {
+  const contexts = catalog.contexts.map((c) => c.id);
+  const flow = catalog.flows[0];
+  const out: Example[] = [];
+  if (contexts.length >= 2 && contexts[0]) {
+    out.push({
+      kind: "context",
+      contextId: contexts[0],
+      question: `What runs between ${contexts[0]} and ${contexts[1]}?`,
+    });
+  }
+  if (contexts[1])
+    out.push({ kind: "event", question: `Which events does ${contexts[1]} consume?` });
+  if (flow) out.push({ kind: "flow", question: `Show the "${flow.name}" flow` });
+  if (contexts[0])
+    out.push({ kind: "adr", question: `Which decisions touch ${contexts[0]}?` });
+  return out;
+}
+
+export function Starter({ onAsk }: { onAsk: (question: string) => void }) {
+  return (
+    <div className="pt-1">
+      <p className="text-muted">
+        Answers are read from the catalog's own pages, and every id in them is a
+        link. Ask about a service, a flow, a decision, or what stands between two
+        contexts.
+      </p>
+      <div className="label mt-5 mb-1">try one</div>
+      <ul className="-mx-1">
+        {examples().map((example) => (
+          <li key={example.question}>
+            <button
+              type="button"
+              onClick={() => onAsk(example.question)}
+              className="flex w-full items-center gap-2.5 rounded-control border-l-2 border-transparent px-2 py-1.5 text-left text-ink transition-colors hover:border-accent hover:bg-raised"
+            >
+              <KindIcon
+                kind={example.kind}
+                {...(example.contextId ? { contextId: example.contextId } : {})}
+                size={15}
+                className="shrink-0"
+              />
+              <span className="min-w-0 truncate">{example.question}</span>
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/src/chat/Steps.tsx

@@ -0,0 +1,45 @@
+// The pages an answer was read from, folded into one line.
+//
+// Three "read docs/…" rows above every answer were the loudest thing in the
+// panel and the least read. One line says how many, and opens to the list
+// for the reader who wants to check the model's sources - which is the whole
+// point of having them.
+
+import { ChevronRight, FileText } from "lucide-react";
+
+const base = import.meta.env.BASE_URL;
+
+export interface Read {
+  path: string;
+}
+
+export function ReadSteps({ reads }: { reads: Read[] }) {
+  if (reads.length === 0) return null;
+  return (
+    <details className="group">
+      <summary className="mono flex cursor-pointer select-none items-center gap-1.5 text-muted transition-colors hover:text-ink [&::-webkit-details-marker]:hidden">
+        <ChevronRight
+          size={12}
+          aria-hidden
+          className="transition-transform group-open:rotate-90"
+        />
+        <FileText size={13} aria-hidden />
+        read {reads.length} {reads.length === 1 ? "page" : "pages"}
+      </summary>
+      <ul className="mono mt-1 space-y-0.5 pl-6">
+        {reads.map((read, index) => (
+          <li key={`${read.path}:${index}`} className="truncate">
+            <a
+              href={`${base}${read.path}`}
+              target="_blank"
+              rel="noreferrer"
+              className="text-accent hover:underline"
+            >
+              {read.path}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </details>
+  );
+}

package/src/chat/Waiting.tsx

@@ -0,0 +1,87 @@
+// The half minute between a question and its first word.
+//
+// A free tier answers slowly, and a panel that shows nothing for thirty
+// seconds looks broken. So: a small boat on a wave, eight frames in one inline
+// SVG stepped along by CSS, and a line saying which part of the wait this is.
+// Inline rather than a background image so it is drawn in currentColor and
+// follows the theme.
+
+const FRAMES = 8;
+const SIZE = 24;
+
+/** One frame: the wave at a phase, the boat lifted with it. */
+function Frame({ index }: { index: number }) {
+  const phase = (index / FRAMES) * Math.PI * 2;
+  const lift = Math.round(Math.sin(phase) * 1.5);
+  const shift = (index / FRAMES) * 8;
+  // Two wave periods across the frame, slid by the phase.
+  const wave = `M${-8 + shift} 19 q2 -2 4 0 t4 0 t4 0 t4 0 t4 0 t4 0 t4 0`;
+  return (
+    <g transform={`translate(${index * SIZE} 0)`}>
+      <g transform={`translate(0 ${lift})`}>
+        {/* hull */}
+        <path d="M6 15 h12 l-2 3 h-8 z" fill="currentColor" />
+        {/* mast and sail */}
+        <path d="M12 15 v-9" stroke="currentColor" strokeWidth="1.2" />
+        <path d="M12.6 6.5 l5 7 h-5 z" fill="currentColor" opacity="0.75" />
+      </g>
+      <path
+        d={wave}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1"
+        opacity="0.55"
+      />
+    </g>
+  );
+}
+
+export function Sprite({ className = "" }: { className?: string }) {
+  return (
+    <svg
+      width={SIZE}
+      height={SIZE}
+      viewBox={`0 0 ${SIZE} ${SIZE}`}
+      className={`shrink-0 overflow-hidden ${className}`}
+      aria-hidden
+    >
+      <g
+        style={{
+          animation: `chat-sprite 1.1s steps(${FRAMES}) infinite`,
+        }}
+      >
+        {Array.from({ length: FRAMES }, (_, index) => (
+          <Frame key={index} index={index} />
+        ))}
+      </g>
+    </svg>
+  );
+}
+
+/** The boat at rest: frame one, for the gutter beside an answer. */
+export function Boat({ size = 24, className = "" }: { size?: number; className?: string }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox={`0 0 ${SIZE} ${SIZE}`}
+      className={`shrink-0 ${className}`}
+      aria-hidden
+    >
+      <Frame index={0} />
+    </svg>
+  );
+}
+
+/** The sprite and what it is waiting for. */
+export function Waiting({ label }: { label: string }) {
+  return (
+    <div
+      role="status"
+      className="mono flex items-center gap-2 py-1 text-muted"
+    >
+      <Sprite />
+      <span className="truncate">{label}</span>
+    </div>
+  );
+}

package/src/chat/flags.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { chatRoute, ownReady, parsePrefs, routeLabel } from "./flags";
+import type { ChatBuild, OwnModel } from "./flags";
+
+const withProxy: ChatBuild = { built: true, proxyUrl: "https://x.workers.dev/chat" };
+const noProxy: ChatBuild = { built: true, proxyUrl: "" };
+const notBuilt: ChatBuild = { built: false, proxyUrl: "https://x.workers.dev/chat" };
+const own: OwnModel = { baseUrl: "https://api.groq.com/openai/v1", apiKey: "k", model: "llama" };
+
+describe("chatRoute", () => {
+  it("is off when the build has no chat, whatever the reader set", () => {
+    expect(chatRoute(notBuilt, { enabled: true, own })).toEqual({ kind: "off" });
+  });
+
+  it("is off when the reader switched it off, even with a proxy and a key", () => {
+    expect(chatRoute(withProxy, { enabled: false, own })).toEqual({ kind: "off" });
+  });
+
+  it("uses the proxy by default when the build has one", () => {
+    expect(chatRoute(withProxy, { enabled: null, own: null })).toEqual({
+      kind: "proxy",
+      url: withProxy.proxyUrl,
+    });
+  });
+
+  it("prefers the reader's own model over the proxy", () => {
+    expect(chatRoute(withProxy, { enabled: null, own })).toEqual({ kind: "own", model: own });
+  });
+
+  it("stays off without a proxy until switched on, then asks to be configured", () => {
+    expect(chatRoute(noProxy, { enabled: null, own: null })).toEqual({ kind: "off" });
+    expect(chatRoute(noProxy, { enabled: true, own: null })).toEqual({ kind: "unconfigured" });
+  });
+
+  it("does not count a half-filled model as one", () => {
+    expect(ownReady({ baseUrl: "", apiKey: "k", model: "m" })).toBe(false);
+    expect(ownReady({ baseUrl: "https://a", apiKey: "", model: "m" })).toBe(true);
+    expect(chatRoute(noProxy, { enabled: true, own: { baseUrl: "https://a", apiKey: "", model: " " } })).toEqual({ kind: "unconfigured" });
+  });
+});
+
+describe("routeLabel", () => {
+  it("names the model and the host, or the proxy", () => {
+    expect(routeLabel({ kind: "own", model: own })).toBe("llama · api.groq.com");
+    expect(routeLabel({ kind: "proxy", url: "u" })).toBe("demo proxy");
+    expect(routeLabel({ kind: "off" })).toBe("");
+  });
+});
+
+describe("parsePrefs", () => {
+  it("reads the switch and the model, and shrugs at junk", () => {
+    expect(parsePrefs("on", null)).toEqual({ enabled: true, own: null });
+    expect(parsePrefs("off", "{bad json")).toEqual({ enabled: false, own: null });
+    expect(parsePrefs(null, JSON.stringify({ baseUrl: "https://a", model: "m" }))).toEqual({
+      enabled: null,
+      own: { baseUrl: "https://a", apiKey: "", model: "m" },
+    });
+  });
+});

package/src/chat/flags.ts

@@ -0,0 +1,155 @@
+// Whether there is a chat, and who answers it.
+//
+// Three switches, from the outside in:
+//
+//   VITE_CHAT=off          the build has no chat: no button, no settings
+//                          section, and the panel's code is not in the bundle
+//   VITE_CHAT_PROXY_URL    the worker that answers with the demo's key; a
+//                          self-hosted build usually has none
+//   the reader             a switch in Settings, and a model of their own with
+//                          its key, both kept in this browser
+//
+// The pure decision is here so it can be tested without a window. The store
+// that reads localStorage is in prefs.ts.
+
+export interface ChatBuild {
+  built: boolean;
+  proxyUrl: string;
+}
+
+/** A provider the reader brings: any OpenAI-compatible chat endpoint. */
+export interface OwnModel {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+}
+
+export interface ChatPrefs {
+  /** null until the reader has touched the switch. */
+  enabled: boolean | null;
+  own: OwnModel | null;
+}
+
+export type ChatRoute =
+  | { kind: "off" }
+  | { kind: "proxy"; url: string }
+  | { kind: "own"; model: OwnModel }
+  /** Switched on by hand, but nothing to answer with yet. */
+  | { kind: "unconfigured" };
+
+export const BUILD: ChatBuild = {
+  built: import.meta.env.VITE_CHAT !== "off",
+  proxyUrl: (import.meta.env.VITE_CHAT_PROXY_URL ?? "").trim(),
+};
+
+const OFF: ChatRoute = { kind: "off" };
+
+/** A model of the reader's own that can be called: an endpoint and a name. A key is optional - Ollama has none. */
+export function ownReady(own: OwnModel | null): own is OwnModel {
+  return own !== null && own.baseUrl.trim() !== "" && own.model.trim() !== "";
+}
+
+/**
+ * Who answers. The reader's own model wins over the proxy: it is the one
+ * thing they set by hand. With neither, the chat is off until they switch it
+ * on - and then it opens to a hint rather than to nothing.
+ */
+export function chatRoute(build: ChatBuild, prefs: ChatPrefs): ChatRoute {
+  if (!build.built) return OFF;
+  if (prefs.enabled === false) return OFF;
+  if (ownReady(prefs.own)) return { kind: "own", model: prefs.own };
+  if (build.proxyUrl !== "") return { kind: "proxy", url: build.proxyUrl };
+  return prefs.enabled === true ? { kind: "unconfigured" } : OFF;
+}
+
+/** What the panel's header says about who is answering. */
+export function routeLabel(route: ChatRoute): string {
+  switch (route.kind) {
+    case "proxy":
+      return "demo proxy";
+    case "own": {
+      let host = route.model.baseUrl;
+      try {
+        host = new URL(route.model.baseUrl).host;
+      } catch {
+        /* not a URL yet: show it as typed */
+      }
+      return `${route.model.model} · ${host}`;
+    }
+    default:
+      return "";
+  }
+}
+
+/** The stored preferences, from the two raw strings localStorage holds. */
+export function parsePrefs(
+  enabledRaw: string | null,
+  ownRaw: string | null,
+): ChatPrefs {
+  const enabled =
+    enabledRaw === "on" ? true : enabledRaw === "off" ? false : null;
+  let own: OwnModel | null = null;
+  if (ownRaw) {
+    try {
+      const parsed = JSON.parse(ownRaw) as Partial<OwnModel>;
+      own = {
+        baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : "",
+        apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : "",
+        model: typeof parsed.model === "string" ? parsed.model : "",
+      };
+    } catch {
+      own = null;
+    }
+  }
+  return { enabled, own };
+}
+
+export interface Preset {
+  id: string;
+  name: string;
+  baseUrl: string;
+  model: string;
+  /** Whether the endpoint wants a key at all. */
+  key: boolean;
+  /** Where to get one. */
+  keysUrl?: string;
+}
+
+/**
+ * The endpoints a reader is likely to reach for. Each speaks the OpenAI chat
+ * protocol; the model names are the ones current when this was written, and
+ * every field stays editable.
+ */
+export const PRESETS: Preset[] = [
+  {
+    id: "gemini",
+    name: "Gemini",
+    baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+    model: "gemini-3.6-flash",
+    key: true,
+    keysUrl: "https://aistudio.google.com/apikey",
+  },
+  {
+    id: "groq",
+    name: "Groq",
+    baseUrl: "https://api.groq.com/openai/v1",
+    model: "llama-3.3-70b-versatile",
+    key: true,
+    keysUrl: "https://console.groq.com/keys",
+  },
+  {
+    id: "openrouter",
+    name: "OpenRouter",
+    baseUrl: "https://openrouter.ai/api/v1",
+    model: "",
+    key: true,
+    keysUrl: "https://openrouter.ai/keys",
+  },
+  {
+    id: "ollama",
+    name: "Ollama",
+    baseUrl: "http://localhost:11434/v1",
+    model: "llama3.2",
+    key: false,
+  },
+];

package/src/chat/linkify.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { linkify } from "./linkify";
+
+const links = new Map([
+  ["shop.oms", "/p/c/shop/oms"],
+  ["shop.oms.order", "/p/c/shop/oms/order"],
+  ["payments", "/p/c/payments"],
+]);
+
+describe("linkify", () => {
+  it("links a bare id and one in backticks", () => {
+    expect(linkify("Ask shop.oms first.", links)).toBe("Ask [shop.oms](/p/c/shop/oms) first.");
+    expect(linkify("Ask `shop.oms` first.", links)).toBe("Ask [`shop.oms`](/p/c/shop/oms) first.");
+  });
+
+  it("takes the longest id and leaves paths and longer words alone", () => {
+    expect(linkify("shop.oms.order holds it", links)).toBe("[shop.oms.order](/p/c/shop/oms/order) holds it");
+    expect(linkify("see docs/shop.oms/README.md", links)).toBe("see docs/shop.oms/README.md");
+    expect(linkify("payments-ledger", links)).toBe("payments-ledger");
+  });
+
+  it("does not touch fenced code or existing links", () => {
+    expect(linkify("```\nshop.oms\n```", links)).toBe("```\nshop.oms\n```");
+    expect(linkify("[shop.oms](/x)", links)).toBe("[shop.oms](/x)");
+  });
+
+  it("is a no-op without ids", () => {
+    expect(linkify("shop.oms", new Map())).toBe("shop.oms");
+  });
+});

package/src/chat/linkify.ts

@@ -0,0 +1,45 @@
+// Ids in an answer become links to their pages.
+//
+// The model is told to name things by their catalog ids, and the catalog
+// knows the page of every id, so the join is a string replacement - done on
+// the markdown before it is rendered, which keeps Markdown.tsx as it is.
+// Fenced code is left alone; a bare id or one in backticks is linked; text
+// already inside a link is not linked twice.
+
+export type LinkTable = ReadonlyMap<string, string>;
+
+function escape(id: string): string {
+  return id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Skips fenced blocks and existing links; the rest is prose. */
+const KEEP = /(```[\s\S]*?```|\[[^\]\n]*\]\([^)\n]*\))/g;
+
+export function linkify(markdown: string, links: LinkTable): string {
+  if (links.size === 0 || markdown === "") return markdown;
+  // Longest first, so `shop.oms.order` is not eaten by `shop.oms`.
+  const ids = [...links.keys()].sort((a, b) => b.length - a.length);
+  const alternatives = ids.map(escape).join("|");
+  // Not preceded by a word character, a dot, a dash or a slash (part of a
+  // longer id or a path), not followed by one either. A trailing dot is
+  // punctuation and is left outside the match.
+  const bare = new RegExp(
+    `(?<![\\w.\\-/])(${alternatives})(?![\\w\\-/]|\\.[\\w])`,
+    "g",
+  );
+  const inCode = new RegExp(`\`(${alternatives})\``, "g");
+
+  return markdown
+    .split(KEEP)
+    .map((piece, index) => {
+      if (index % 2 === 1) return piece; // a kept block
+      return piece
+        .replace(inCode, (_, id: string) => `[\`${id}\`](${links.get(id)})`)
+        .replace(bare, (match, id: string, offset: number, whole: string) => {
+          // Inside the link text just written by the step above.
+          if (whole.slice(0, offset).endsWith("[`")) return match;
+          return `[${id}](${links.get(id)})`;
+        });
+    })
+    .join("");
+}

package/src/chat/prefs.ts

@@ -0,0 +1,56 @@
+// The reader's side of the chat: the switch and their own model, in this
+// browser. The decision that combines them with the build is in flags.ts.
+
+import { useMemo } from "react";
+import { create } from "zustand";
+import { BUILD, chatRoute, parsePrefs } from "./flags";
+import type { ChatPrefs, ChatRoute, OwnModel } from "./flags";
+
+const KEY_ENABLED = "portolan.chat.enabled";
+const KEY_OWN = "portolan.chat.model";
+
+function read(key: string): string | null {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function write(key: string, value: string | null): void {
+  try {
+    if (value === null) localStorage.removeItem(key);
+    else localStorage.setItem(key, value);
+  } catch {
+    /* private mode: this session keeps the setting, the next one starts over */
+  }
+}
+
+interface PrefsState extends ChatPrefs {
+  setEnabled: (enabled: boolean) => void;
+  setOwn: (own: OwnModel | null) => void;
+}
+
+export const usePrefs = create<PrefsState>()((set) => ({
+  ...parsePrefs(read(KEY_ENABLED), read(KEY_OWN)),
+  setEnabled: (enabled) => {
+    write(KEY_ENABLED, enabled ? "on" : "off");
+    set({ enabled });
+  },
+  setOwn: (own) => {
+    write(KEY_OWN, own ? JSON.stringify(own) : null);
+    set({ own });
+  },
+}));
+
+/** Who answers, for this build and this reader. */
+export function useChatRoute(): ChatRoute {
+  const enabled = usePrefs((s) => s.enabled);
+  const own = usePrefs((s) => s.own);
+  return useMemo(() => chatRoute(BUILD, { enabled, own }), [enabled, own]);
+}
+
+/** Whether the top bar shows the button at all. */
+export function useChatAvailable(): boolean {
+  return useChatRoute().kind !== "off";
+}

package/src/chat/prompt.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { clipPage, instructions, pagePath, PAGE_LIMIT } from "./prompt";
+
+describe("pagePath", () => {
+  it("accepts a path as the index spells it", () => {
+    expect(pagePath("docs/auth/README.md")).toBe("docs/auth/README.md");
+  });
+
+  it("forgives a dropped docs/ and a leading slash", () => {
+    expect(pagePath("auth/README.md")).toBe("docs/auth/README.md");
+    expect(pagePath("/docs/auth/README.md")).toBe("docs/auth/README.md");
+    expect(pagePath("./docs/flows/checkout.md")).toBe("docs/flows/checkout.md");
+  });
+
+  it("refuses anything that is not a markdown page under docs/", () => {
+    expect(pagePath("docs/../secret.md")).toBeNull();
+    expect(pagePath("docs/auth/../../x.md")).toBeNull();
+    expect(pagePath("docs//auth/README.md")).toBeNull();
+    expect(pagePath("https://example.com/docs/a.md")).toBeNull();
+    expect(pagePath("docs/llms.txt")).toBeNull();
+    expect(pagePath("docs/auth/README.md?x=1")).toBeNull();
+    expect(pagePath(42)).toBeNull();
+    expect(pagePath("")).toBeNull();
+  });
+});
+
+describe("clipPage", () => {
+  it("leaves a short page alone and cuts a long one with a note", () => {
+    expect(clipPage("hello")).toBe("hello");
+    const long = "x".repeat(PAGE_LIMIT + 10);
+    const clipped = clipPage(long);
+    expect(clipped.startsWith("x".repeat(PAGE_LIMIT))).toBe(true);
+    expect(clipped).toContain("10 more characters");
+  });
+});
+
+describe("instructions", () => {
+  it("folds the index in after the rules", () => {
+    const text = instructions("- [Auth](docs/auth/README.md)");
+    expect(text).toContain("read_page");
+    expect(text.endsWith("- [Auth](docs/auth/README.md)")).toBe(true);
+  });
+});