@shortlink-org/portolan 0.1.0 → 0.2.0

package/src/landing/ProductFrame.tsx

@@ -0,0 +1,68 @@
+import type { ReactNode } from "react";
+import { CompassRose } from "../components/logo";
+
+export function ProductFrame({
+  title,
+  eyebrow,
+  children,
+  className = "",
+  aside = true,
+}: {
+  title: string;
+  eyebrow: string;
+  children: ReactNode;
+  className?: string;
+  /** The sketched catalog tree down the left. Off for a canvas that wants the whole width. */
+  aside?: boolean;
+}) {
+  return (
+    <div
+      className={`overflow-hidden rounded-[18px] border border-line bg-canvas shadow-md ${className}`}
+    >
+      <div className="flex h-11 items-center gap-3 border-b border-line bg-surface px-4">
+        <div className="flex gap-1.5" aria-hidden>
+          <span className="size-2 rounded-full bg-unresolved/70" />
+          <span className="size-2 rounded-full bg-declared/70" />
+          <span className="size-2 rounded-full bg-verified/70" />
+        </div>
+        <div className="mono flex min-w-0 flex-1 items-center justify-center gap-1.5 text-faint">
+          <CompassRose size={13} />
+          <span className="truncate">{title}</span>
+        </div>
+        <span className="w-[35px]" aria-hidden />
+      </div>
+      <div
+        className={`grid min-h-0 grid-cols-1 ${
+          aside ? "sm:grid-cols-[132px_minmax(0,1fr)]" : ""
+        }`}
+      >
+        {aside ? (
+        <aside className="hidden border-r border-line bg-canvas p-3 sm:block">
+          <div className="label mb-3">{eyebrow}</div>
+          <div className="space-y-1.5" aria-hidden>
+            <div className="h-2 w-20 rounded-full bg-line-strong" />
+            <div className="h-2 w-16 rounded-full bg-line" />
+            <div className="h-2 w-24 rounded-full bg-line" />
+          </div>
+          <div className="label mt-6 mb-3">catalog</div>
+          <div className="space-y-2" aria-hidden>
+            <div className="flex items-center gap-2">
+              <span className="size-1.5 rounded-[1px] bg-[var(--ctx-0)]" />
+              <div className="h-2 w-16 rounded-full bg-line" />
+            </div>
+            <div className="flex items-center gap-2">
+              <span className="size-1.5 rounded-[1px] bg-[var(--ctx-1)]" />
+              <div className="h-2 w-20 rounded-full bg-line" />
+            </div>
+            <div className="flex items-center gap-2">
+              <span className="size-1.5 rounded-[1px] bg-[var(--ctx-2)]" />
+              <div className="h-2 w-14 rounded-full bg-line" />
+            </div>
+          </div>
+        </aside>
+        ) : null}
+        <div className="landing-grid min-w-0">{children}</div>
+      </div>
+    </div>
+  );
+}

package/src/landing/ProductTour.tsx

@@ -0,0 +1,371 @@
+// Four stops through the product, on the example estate. Two of them are the
+// product's own canvases in a smaller box; the other two are read straight
+// out of the same catalog. Nothing on this page is drawn from a mock-up.
+
+import { lazy, Suspense, useMemo, useState } from "react";
+import { Link } from "react-router";
+import {
+  AlertTriangle,
+  ArrowRight,
+  Braces,
+  ExternalLink,
+  FileCode2,
+  GitBranch,
+  Network,
+  Radio,
+} from "lucide-react";
+import { catalog, index } from "../data";
+import { DiagramSkeleton } from "../components/DiagramSkeleton";
+import { contextVar } from "../lib/context-color";
+import { allProblems } from "../lib/all-problems";
+import {
+  AnimatePresence,
+  LayoutGroup,
+  m,
+  page,
+  staggerStyle,
+  transitions,
+} from "../lib/motion";
+import { eventPath, paths } from "../routes";
+import { catalogTo } from "./catalog";
+import { ProductFrame } from "./ProductFrame";
+import { DraggableReveal } from "./DraggableReveal";
+
+type DemoId = "estate" | "flow" | "contract" | "problems";
+
+// The two canvases carry elk and React Flow; they arrive when their tab does.
+const EstateGraph = lazy(() =>
+  import("./EstateGraph").then((mod) => ({ default: mod.EstateGraph })),
+);
+const FlowPlayback = lazy(() =>
+  import("./FlowPlayback").then((mod) => ({ default: mod.FlowPlayback })),
+);
+
+const tours: Array<{
+  id: DemoId;
+  number: string;
+  title: string;
+  copy: string;
+  icon: typeof Network;
+}> = [
+  {
+    id: "estate",
+    number: "01",
+    title: "See the whole estate",
+    copy: "See every service and event between them. Switch views, focus a service, or export the map.",
+    icon: Network,
+  },
+  {
+    id: "flow",
+    number: "02",
+    title: "Follow one real flow",
+    copy: "Follow a checkout across HTTP, gRPC, the database and the bus, one step at a time, with its source line.",
+    icon: GitBranch,
+  },
+  {
+    id: "contract",
+    number: "03",
+    title: "Inspect the contract",
+    copy: "The event's payload, the channel it leaves on, who listens, and the file it was read from.",
+    icon: Braces,
+  },
+  {
+    id: "problems",
+    number: "04",
+    title: "Catch architecture drift",
+    copy: "Catch unresolved calls, second writers and unpublished channels during the merge, before review.",
+    icon: AlertTriangle,
+  },
+];
+
+const EVENT_ID = "shop.cart.basket.BasketCheckedOut";
+
+function ContractDemo() {
+  const event = index.eventById.get(EVENT_ID);
+  const owner = index.eventOwner.get(EVENT_ID);
+  const version = event?.versions.at(-1);
+  const href = eventPath(EVENT_ID);
+  if (!event || !owner || !version) {
+    return (
+      <div className="p-6 text-sm text-muted">
+        The example catalog does not carry {EVENT_ID}.
+      </div>
+    );
+  }
+  const context = index.serviceContext.get(owner.service.id);
+
+  return (
+    <div className="p-4 sm:p-6">
+      <div className="flex flex-wrap items-start justify-between gap-3">
+        <div className="min-w-0">
+          <div className="mono text-event">domain event · {version.version}</div>
+          <div className="mt-1 text-md font-semibold text-ink">{event.name}</div>
+          <div className="mono mt-1 truncate text-muted">{event.id}</div>
+        </div>
+        {event.wire ? (
+          <span className="chip status-verified">
+            <Radio size={12} /> {event.wire.channel ?? event.wire.name}
+          </span>
+        ) : null}
+      </div>
+      {version.doc ? (
+        <p className="mt-3 max-w-[560px] text-sm leading-6 text-muted">
+          {version.doc}
+        </p>
+      ) : null}
+      <div className="mt-5 grid gap-4 lg:grid-cols-[minmax(0,1fr)_200px]">
+        <div className="overflow-hidden rounded-card border border-line bg-canvas">
+          <div className="label border-b border-line bg-surface px-3 py-2">
+            payload
+          </div>
+          {version.fields.map((field, i) => (
+            <div
+              key={field.name}
+              style={staggerStyle(i)}
+              className="stagger-in grid grid-cols-[minmax(0,1fr)_auto] gap-3 border-b border-line px-3 py-2 last:border-b-0"
+            >
+              <span className="mono text-ink">{field.name}</span>
+              <span className="mono text-muted">{field.type}</span>
+            </div>
+          ))}
+        </div>
+        <div>
+          <div className="label mb-2">
+            published by
+          </div>
+          <div
+            className="rounded-control border border-line bg-canvas p-2.5"
+            style={{ color: contextVar(context?.id) }}
+          >
+            <div className="font-medium text-ink">{owner.service.id}</div>
+            <div className="mono mt-0.5 text-muted">{owner.aggregate.name}</div>
+          </div>
+          <div className="label mt-4 mb-2">
+            consumed by
+          </div>
+          {event.consumers.length === 0 ? (
+            <div className="mono text-faint">nobody yet</div>
+          ) : (
+            <div className="space-y-2">
+              {event.consumers.map((consumer, i) => (
+                <div
+                  key={consumer.service}
+                  style={staggerStyle(i + 2)}
+                  className="stagger-in flex items-center justify-between gap-2 rounded-control border border-line bg-canvas p-2.5"
+                >
+                  <div className="min-w-0">
+                    <div className="truncate font-medium text-ink">
+                      {consumer.service}
+                    </div>
+                    {consumer.note ? (
+                      <div className="mono mt-0.5 truncate text-muted">
+                        {consumer.note}
+                      </div>
+                    ) : null}
+                  </div>
+                  <span className={`chip status-${consumer.status}`}>
+                    {consumer.status}
+                  </span>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      </div>
+      <div className="mt-4 flex flex-wrap items-center gap-3">
+        <div className="mono flex min-w-0 flex-1 items-center gap-2 rounded-control border border-line bg-surface px-3 py-2 text-muted">
+          <FileCode2 size={13} className="shrink-0" />
+          <span className="truncate">{version.source}</span>
+          <ExternalLink size={12} className="ml-auto shrink-0" />
+        </div>
+        {href ? (
+          <Link
+            to={catalogTo(href)}
+            className="inline-flex shrink-0 items-center gap-1 text-sm text-accent hover:underline"
+          >
+            Open the event <ArrowRight size={13} />
+          </Link>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+const SHOWN_PROBLEMS = 4;
+
+function ProblemsDemo() {
+  const all = useMemo(() => allProblems(catalog, index), []);
+  const errors = all.filter((p) => p.severity === "error").length;
+  const shown = all.slice(0, SHOWN_PROBLEMS);
+
+  return (
+    <div className="p-4 sm:p-6">
+      <div className="mb-5 flex flex-wrap items-start justify-between gap-3">
+        <div>
+          <div className="text-md font-semibold text-ink">
+            Architecture problems
+          </div>
+          <div className="mt-1 text-sm text-muted">
+            Every edge that leaves the measured model, found at merge time
+          </div>
+        </div>
+        <div className="flex gap-2">
+          {errors > 0 ? (
+            <span className="chip status-unresolved">{errors} errors</span>
+          ) : null}
+          {all.length - errors > 0 ? (
+            <span className="chip status-declared">
+              {all.length - errors} warnings
+            </span>
+          ) : null}
+        </div>
+      </div>
+      {shown.length === 0 ? (
+        <div className="rounded-card border border-line bg-canvas p-4 text-sm text-muted">
+          Nothing leaves the model: every call and every consumer resolves.
+        </div>
+      ) : (
+        <div className="space-y-2">
+          {shown.map((problem, i) => (
+            <div
+              key={`${problem.kind}:${problem.id}:${problem.peer}`}
+              style={staggerStyle(i)}
+              className="stagger-in grid grid-cols-[20px_minmax(0,1fr)_auto] items-start gap-3 rounded-card border border-line bg-canvas p-3"
+            >
+              <AlertTriangle
+                size={16}
+                className={
+                  problem.severity === "error"
+                    ? "mt-0.5 text-unresolved"
+                    : "mt-0.5 text-declared"
+                }
+              />
+              <div className="min-w-0">
+                <div className="truncate font-medium text-ink">
+                  {problem.note ?? problem.id}
+                </div>
+                <div
+                  className="mono mt-1 truncate text-muted"
+                  title={`${problem.service} → ${problem.peer}`}
+                >
+                  <span style={{ color: contextVar(problem.context) }}>
+                    {problem.service}
+                  </span>{" "}
+                  → {problem.peer}
+                </div>
+              </div>
+              <span className="chip border-line text-muted">
+                {problem.kind}
+              </span>
+            </div>
+          ))}
+        </div>
+      )}
+      <div className="mt-4 flex items-center justify-between gap-3">
+        <span className="mono text-faint">
+          {all.length > shown.length
+            ? `${all.length - shown.length} more on the problems page`
+            : `${all.length} in total`}
+        </span>
+        <Link
+          to={catalogTo(paths.problems())}
+          className="inline-flex items-center gap-1 text-sm text-accent hover:underline"
+        >
+          Open the problems page <ArrowRight size={13} />
+        </Link>
+      </div>
+    </div>
+  );
+}
+
+function Demo({ id }: { id: DemoId }) {
+  switch (id) {
+    case "flow":
+      return <FlowPlayback />;
+    case "contract":
+      return <ContractDemo />;
+    case "problems":
+      return <ProblemsDemo />;
+    default:
+      return <EstateGraph />;
+  }
+}
+
+export function ProductTour() {
+  const [active, setActive] = useState<DemoId>("estate");
+  const selected = tours.find((tour) => tour.id === active) ?? tours[0]!;
+
+  return (
+    <div className="grid items-start gap-8 lg:grid-cols-[minmax(260px,0.72fr)_minmax(0,1.55fr)] lg:gap-12">
+      <LayoutGroup id="product-tour">
+        <div
+          role="tablist"
+          aria-label="Portolan product tour"
+          className="grid gap-2 sm:grid-cols-2 lg:grid-cols-1"
+        >
+          {tours.map((tour) => {
+            const Icon = tour.icon;
+            const on = tour.id === active;
+            return (
+              <button
+                key={tour.id}
+                type="button"
+                role="tab"
+                aria-selected={on}
+                aria-controls="landing-product-demo"
+                onClick={() => setActive(tour.id)}
+                className={`group relative rounded-card border border-line/60 p-4 text-left transition-colors ${
+                  on ? "" : "hover:border-line-strong hover:bg-surface"
+                }`}
+              >
+                {on ? (
+                  <m.span
+                    layoutId="tour-ring"
+                    transition={transitions.settle}
+                    className="absolute inset-0 rounded-card border border-accent bg-accent/5"
+                    aria-hidden
+                  />
+                ) : null}
+                <div className="relative flex items-center gap-3">
+                  <span
+                    className={`mono flex size-8 items-center justify-center rounded-control border transition-colors ${
+                      on
+                        ? "border-accent text-accent"
+                        : "border-line text-muted group-hover:text-ink"
+                    }`}
+                  >
+                    <Icon size={15} aria-hidden />
+                  </span>
+                  <div>
+                    <div className="mono text-faint">{tour.number}</div>
+                    <div className="font-semibold text-ink">{tour.title}</div>
+                  </div>
+                </div>
+                <p className="relative mt-3 text-sm text-muted">{tour.copy}</p>
+              </button>
+            );
+          })}
+        </div>
+      </LayoutGroup>
+
+      <div id="landing-product-demo" role="tabpanel" aria-live="polite">
+        <DraggableReveal>
+          <ProductFrame
+            title={`${selected.title} · portolan`}
+            eyebrow={active}
+            // The two canvases want every pixel of width they can get.
+            aside={active === "contract" || active === "problems"}
+          >
+            <AnimatePresence mode="wait" initial={false}>
+              <m.div key={active} {...page} className="relative min-h-[470px]">
+                <Suspense fallback={<DiagramSkeleton />}>
+                  <Demo id={active} />
+                </Suspense>
+              </m.div>
+            </AnimatePresence>
+          </ProductFrame>
+        </DraggableReveal>
+      </div>
+    </div>
+  );
+}

package/src/landing/catalog.ts

@@ -0,0 +1,25 @@
+// The landing's link into the catalog it demonstrates.
+//
+// The landing shows the example estate (data.ts picks that profile for the
+// `/landing` route), and every "open this in the catalog" it offers has to
+// land on the same estate after a reload as it does on a click. So the profile
+// is spelled on the URL, the way the catalog app itself keeps it there.
+
+import { useEffect } from "react";
+import { activeCatalogProfile } from "../data";
+import { useSelectionStore } from "../selection/store";
+
+export function catalogTo(pathname: string): { pathname: string; search: string } {
+  return { pathname, search: `?catalog=${activeCatalogProfile.id}` };
+}
+
+/**
+ * The canvases on the landing write to the app's one selection store, the
+ * same as they do on their own pages. A demo that is unmounted - a tab
+ * switched, the page left - must not leave its selection behind for the
+ * catalog's detail panel to open on.
+ */
+export function useSelectionCleared(): void {
+  const clear = useSelectionStore((s) => s.clear);
+  useEffect(() => () => clear("diagram"), [clear]);
+}

package/src/landing/motion.tsx

@@ -0,0 +1,52 @@
+// Motion the landing adds on top of lib/motion: things that arrive as the
+// reader scrolls to them, and a hero that arrives in order. Same clock as the
+// app - the narrative duration and the ease-out - so a card rising on the
+// landing rises the way a row rises in the catalog.
+
+import type { ReactNode } from "react";
+import type { Variants } from "motion/react";
+import { DURATION, EASE_OUT, m } from "../lib/motion";
+
+const VIEWPORT = { once: true, margin: "-10% 0px -10% 0px" } as const;
+
+/**
+ * A block that rises the fourteen pixels once, the first time it scrolls into
+ * view. `delay` staggers siblings; keep it under a third of a second, or the
+ * last card in a row is still arriving when the reader has read the first.
+ */
+export function Reveal({
+  children,
+  delay = 0,
+  className,
+}: {
+  children: ReactNode;
+  delay?: number;
+  className?: string;
+}) {
+  return (
+    <m.div
+      className={className}
+      initial={{ opacity: 0, y: 14 }}
+      whileInView={{ opacity: 1, y: 0 }}
+      viewport={VIEWPORT}
+      transition={{ duration: DURATION.narrative, ease: EASE_OUT, delay }}
+    >
+      {children}
+    </m.div>
+  );
+}
+
+/** The hero's column: eyebrow, headline, copy, buttons, one after another. */
+export const heroColumn: Variants = {
+  hidden: {},
+  shown: { transition: { staggerChildren: 0.08, delayChildren: 0.05 } },
+};
+
+export const heroLine: Variants = {
+  hidden: { opacity: 0, y: 14 },
+  shown: {
+    opacity: 1,
+    y: 0,
+    transition: { duration: DURATION.narrative, ease: EASE_OUT },
+  },
+};

package/src/lib/all-problems.ts

@@ -0,0 +1,28 @@
+// Every reading the catalog makes of itself, in one list.
+//
+// Four readers, each answering a different question: edges that resolve to
+// nothing, schemas that name a method the module lacks, tables and columns
+// that disagree with the model, and channels that documents and events do not
+// agree on. The problems page, the overview and the landing all want the
+// union, errors first - a boundary leak is not the same kind of news as a
+// column whose type has drifted, and mixing them buries the first.
+
+import type { Catalog, CatalogIndex } from "../catalog";
+import { dataProblems } from "./data-problems";
+import { problems } from "./derive";
+import type { Problem } from "./derive";
+import { protoProblems } from "./proto-problems";
+import { wireProblems } from "./wire-problems";
+
+export function allProblems(catalog: Catalog, index: CatalogIndex): Problem[] {
+  const found = [
+    ...problems(catalog),
+    ...protoProblems(catalog, index),
+    ...dataProblems(catalog, index),
+    ...wireProblems(catalog, index),
+  ];
+  return [
+    ...found.filter((p) => p.severity === "error"),
+    ...found.filter((p) => p.severity === "warning"),
+  ];
+}

package/src/lib/local-api.ts

@@ -1,6 +1,6 @@
 import type { SetupInfo, SetupPhase, SetupRunStepStatus } from "./setup-info";
 
-const ROOT = "/__portolan";
+const ROOT = `${import.meta.env.BASE_URL}__portolan`;
 const LOCAL_HEADER = { "Content-Type": "application/json", "X-Portolan-Local": "1" };
 
 export interface Detection {
@@ -64,6 +64,27 @@ export interface GeneratedFileDiff {
   diff: string;
 }
 
+export type DeliveryProvider = "github" | "gitlab";
+
+export interface DeliveryPresetFile {
+  path: string;
+  status: "added" | "changed" | "unchanged" | "conflict";
+  diff: string;
+  message?: string;
+}
+
+export interface DeliveryPreset {
+  provider: DeliveryProvider;
+  detectedProvider: DeliveryProvider | null;
+  remote: string | null;
+  repository: string;
+  defaultBranch: string;
+  status: "available" | "installed" | "update" | "conflict";
+  revision: string;
+  features: string[];
+  files: DeliveryPresetFile[];
+}
+
 export interface ProjectTrialFact {
   key: string;
   label: string;
@@ -142,6 +163,19 @@ export async function localStatus(): Promise<{ local: true; workspace: string; s
   return json("/status");
 }
 
+export async function previewDeliveryPreset(provider?: DeliveryProvider): Promise<DeliveryPreset> {
+  const query = provider ? `?provider=${encodeURIComponent(provider)}` : "";
+  return json(`/delivery-presets${query}`);
+}
+
+export async function installDeliveryPreset(provider: DeliveryProvider, revision: string): Promise<DeliveryPreset & { written: string[] }> {
+  return json("/delivery-presets/install", {
+    method: "POST",
+    headers: LOCAL_HEADER,
+    body: JSON.stringify({ provider, revision }),
+  });
+}
+
 export async function discover(path: string): Promise<Discovery> {
   return json("/discover", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify({ path }) });
 }

package/src/lib/setup-info.test.ts

@@ -16,6 +16,7 @@ describe("publicSetupFrom", () => {
         },
         { name: "docs", wasm: { url: "https://example.com/docs.wasm" } },
         { name: "unused", process: { command: "unused" } },
+        { name: "vendor", host: "fetch-git" },
       ],
       extract: [
         {
@@ -58,6 +59,13 @@ describe("publicSetupFrom", () => {
         stepCount: 0,
         projectIds: [],
       },
+      {
+        name: "vendor",
+        runtime: "host",
+        phases: [],
+        stepCount: 0,
+        projectIds: [],
+      },
     ]);
     expect(JSON.stringify(setup)).not.toContain("secret");
     expect(JSON.stringify(setup)).not.toContain("command");

package/src/lib/setup-info.ts

@@ -32,7 +32,7 @@ export interface SetupStep {
 
 export interface SetupPlugin {
   name: string;
-  runtime: "wasm" | "process";
+  runtime: "wasm" | "process" | "host";
   phases: SetupPhase[];
   stepCount: number;
   projectIds: string[];
@@ -82,6 +82,7 @@ interface ManifestPlugin {
   name?: unknown;
   wasm?: unknown;
   process?: unknown;
+  host?: unknown;
 }
 
 interface ManifestStep {
@@ -345,7 +346,7 @@ function pluginFrom(
     // Settings prints this as a promise about filesystem, network and
     // environment access, so a `wasm` that is not a module - null, a bare
     // true, a half-written object - answers "process", which promises nothing.
-    runtime: typeof record(item.wasm)["url"] === "string" ? "wasm" : "process",
+    runtime: typeof record(item.wasm)["url"] === "string" ? "wasm" : typeof item.host === "string" ? "host" : "process",
     phases: PHASES.filter((phase) => own.some((step) => step.phase === phase)),
     stepCount: own.length,
     projectIds: [

package/src/lib/source-code.ts

@@ -1,6 +1,7 @@
 import type { RemoteSourceLocation, SourceLocation } from "./source-link";
 
 const MAX_SOURCE_BYTES = 1024 * 1024;
+const LOCAL_SOURCE_URL = `${import.meta.env.BASE_URL}__portolan/source`;
 
 export type SourceFile = {
   content: string;
@@ -145,7 +146,7 @@ async function loadRemote(
 async function loadLocal(
   location: Extract<SourceLocation, { kind: "local" }>,
 ): Promise<SourceFile> {
-  const response = await fetch("/__portolan/source", {
+  const response = await fetch(LOCAL_SOURCE_URL, {
     method: "POST",
     headers: { "Content-Type": "application/json", "X-Portolan-Local": "1" },
     body: JSON.stringify({ path: location.path }),