@shortlink-org/portolan 0.1.0

package/src/lib/lifecycle.ts

@@ -0,0 +1,165 @@
+// The lifecycle of an aggregate, laid out for drawing.
+//
+// A state machine read off code is small - a handful of states, a fan of
+// moves out of the first - and the picture worth having is the one a person
+// would sketch: the initial state on the left, what it can become to its
+// right, and anything that leads back drawn underneath so it reads as the
+// exception it is. Everything here is geometry over the catalog's own facts,
+// so the diagram is asserted in a test rather than eyeballed.
+
+import type { Lifecycle, Transition } from "../catalog";
+
+export interface LifecycleBox {
+  state: string;
+  /** The state a new root starts in: the first the code lists. */
+  initial: boolean;
+  /** Nothing leads out: the root is a record from here on. */
+  terminal: boolean;
+  column: number;
+  row: number;
+  x: number;
+  y: number;
+}
+
+export interface LifecycleEdge extends Transition {
+  /** Leads to a column at or before its own: drawn underneath. */
+  back: boolean;
+  path: string;
+  labelX: number;
+  labelY: number;
+}
+
+export interface LifecycleLayout {
+  width: number;
+  height: number;
+  boxes: LifecycleBox[];
+  edges: LifecycleEdge[];
+}
+
+export interface Metrics {
+  boxWidth: number;
+  boxHeight: number;
+  gapX: number;
+  gapY: number;
+  pad: number;
+}
+
+/** The gap between columns is what holds a label - `mergeInto · BasketMerged` - clear of both boxes. */
+export const METRICS: Metrics = { boxWidth: 128, boxHeight: 36, gapX: 224, gapY: 28, pad: 12 };
+
+/** How far above its line a forward label sits, so the arrow stays readable under it. */
+const LIFT = 10;
+
+/** How deep below the row of boxes a back edge dips. */
+const DIP = 36;
+
+export function isTerminal(lifecycle: Lifecycle, state: string): boolean {
+  return !lifecycle.transitions.some((t) => t.from === state && t.to !== state);
+}
+
+/**
+ * Columns by how many moves a state is from the initial one; a state nothing
+ * reaches sits in a column of its own at the far right, so it is drawn and
+ * seen rather than dropped. Rows follow the order the code listed the states.
+ */
+export function columnsOf(lifecycle: Lifecycle): Map<string, number> {
+  const depth = new Map<string, number>();
+  const [initial] = lifecycle.states;
+  if (initial === undefined) return depth;
+  depth.set(initial, 0);
+  const queue = [initial];
+  while (queue.length > 0) {
+    const from = queue.shift()!;
+    for (const t of lifecycle.transitions) {
+      if (t.from !== from || depth.has(t.to)) continue;
+      depth.set(t.to, depth.get(from)! + 1);
+      queue.push(t.to);
+    }
+  }
+  const beyond = Math.max(-1, ...depth.values()) + 1;
+  for (const state of lifecycle.states) if (!depth.has(state)) depth.set(state, beyond);
+  return depth;
+}
+
+export function layoutLifecycle(lifecycle: Lifecycle, m: Metrics = METRICS): LifecycleLayout {
+  const columns = columnsOf(lifecycle);
+  const perColumn = new Map<number, string[]>();
+  for (const state of lifecycle.states) {
+    const c = columns.get(state)!;
+    perColumn.set(c, [...(perColumn.get(c) ?? []), state]);
+  }
+  const columnCount = perColumn.size === 0 ? 0 : Math.max(...perColumn.keys()) + 1;
+  const tallest = Math.max(0, ...[...perColumn.values()].map((s) => s.length));
+  const stride = { x: m.boxWidth + m.gapX, y: m.boxHeight + m.gapY };
+  const rowsHeight = tallest * m.boxHeight + Math.max(0, tallest - 1) * m.gapY;
+
+  const boxes: LifecycleBox[] = [];
+  const at = new Map<string, LifecycleBox>();
+  for (const state of lifecycle.states) {
+    const column = columns.get(state)!;
+    const column_ = perColumn.get(column)!;
+    const row = column_.indexOf(state);
+    // Each column is centred on the tallest, so a fan reads as a fan.
+    const offset = (rowsHeight - (column_.length * m.boxHeight + (column_.length - 1) * m.gapY)) / 2;
+    const box: LifecycleBox = {
+      state,
+      initial: state === lifecycle.states[0],
+      terminal: isTerminal(lifecycle, state),
+      column,
+      row,
+      x: m.pad + column * stride.x,
+      y: m.pad + offset + row * stride.y,
+    };
+    boxes.push(box);
+    at.set(state, box);
+  }
+
+  // Two moves between the same pair - a lock lapsing on a wrong password and
+  // on a right one - are two edges, and each needs its own line and label:
+  // the second dips deeper, or sits a step higher, than the first.
+  const seen = new Map<string, number>();
+  let deepest = 0;
+  const edges: LifecycleEdge[] = lifecycle.transitions.map((t) => {
+    const a = at.get(t.from)!;
+    const z = at.get(t.to)!;
+    const pair = `${t.from}→${t.to}`;
+    const k = seen.get(pair) ?? 0;
+    seen.set(pair, k + 1);
+    const back = z.column <= a.column;
+    if (!back) {
+      const x1 = a.x + m.boxWidth;
+      const y1 = a.y + m.boxHeight / 2;
+      const x2 = z.x;
+      const y2 = z.y + m.boxHeight / 2;
+      const bend = (x2 - x1) / 2;
+      return {
+        ...t,
+        back,
+        path: `M ${x1} ${y1} C ${x1 + bend} ${y1}, ${x2 - bend} ${y2}, ${x2} ${y2}`,
+        labelX: (x1 + x2) / 2,
+        labelY: (y1 + y2) / 2 - LIFT * (k + 1),
+      };
+    }
+    // Underneath, from the bottom of one box to the bottom of the other.
+    const x1 = a.x + m.boxWidth / 2;
+    const x2 = z.x + m.boxWidth / 2;
+    const y1 = a.y + m.boxHeight;
+    const y2 = z.y + m.boxHeight;
+    const low = m.pad + rowsHeight + DIP * (k + 1);
+    deepest = Math.max(deepest, DIP * (k + 1));
+    return {
+      ...t,
+      back,
+      path: `M ${x1} ${y1} C ${x1} ${low}, ${x2} ${low}, ${x2} ${y2}`,
+      labelX: (x1 + x2) / 2,
+      labelY: low - 6,
+    };
+  });
+
+  return {
+    width: m.pad * 2 + columnCount * m.boxWidth + Math.max(0, columnCount - 1) * m.gapX,
+    height: m.pad * 2 + rowsHeight + deepest,
+    boxes,
+    edges,
+  };
+}

package/src/lib/local-api.ts

@@ -0,0 +1,194 @@
+import type { SetupInfo, SetupPhase, SetupRunStepStatus } from "./setup-info";
+
+const ROOT = "/__portolan";
+const LOCAL_HEADER = { "Content-Type": "application/json", "X-Portolan-Local": "1" };
+
+export interface Detection {
+  plugin: string;
+  confidence: "high" | "medium";
+  evidence: string;
+  candidates: string[];
+  options: Record<string, unknown>;
+  selected: boolean;
+}
+
+export interface Discovery {
+  root: string;
+  filesScanned: number;
+  truncated: boolean;
+  components: Array<{ path: string; name: string; markers: string[]; technologies: string[] }>;
+  componentsTruncated: boolean;
+  defaults: { id: string; name: string; group: string; component: string; context: string; service: string };
+  detections: Detection[];
+}
+
+export interface ProjectDraft {
+  source: "local" | "external";
+  root: string;
+  repository: string;
+  ref: string;
+  commit: string;
+  sourcePath: string;
+  id: string;
+  name: string;
+  group: string;
+  component: string;
+  context?: string;
+  service?: string;
+  groupKind?: "bounded-context" | "system" | "product" | "team" | "namespace";
+  componentKind?: "service" | "application" | "webapp" | "worker" | "job" | "function" | "cli" | "library" | "data-pipeline";
+  plugins: string[];
+}
+
+export interface ProjectPlan {
+  project: { id: string; name: string; root: string; group?: string; component?: string; groupKind?: string; componentKind?: string; context?: string; service?: string; repository?: string };
+  plugins: string[];
+  steps: Array<{ plugin: string; in: string; out: string; options: Record<string, unknown> }>;
+  source: string;
+  discovery: Discovery;
+  fetch: { repo: string; commit: string; paths: string[] } | null;
+}
+
+export interface RepositoryInspection {
+  repository: string;
+  ref: string;
+  commit: string;
+  sourcePath: string;
+  checkoutRoot: string;
+  discovery: Discovery;
+}
+
+export interface GeneratedFileDiff {
+  path: string;
+  status: "added" | "changed" | "removed";
+  diff: string;
+}
+
+export interface ProjectTrialFact {
+  key: string;
+  label: string;
+  count: number;
+}
+
+export interface ProjectTrialStep {
+  plugin: string;
+  status: SetupRunStepStatus;
+  durationMs: number;
+  fileCount: number;
+  changedCount: number;
+  warnings: string[];
+  message?: string;
+}
+
+export interface ProjectTrial {
+  plan: ProjectPlan;
+  steps: ProjectTrialStep[];
+  facts: ProjectTrialFact[];
+  warnings: Array<{ plugin: string; message: string }>;
+  generatedFiles: number;
+  previewUrl?: string;
+  previewError?: string;
+}
+
+export type RunEvent =
+  | { type: "run-started"; at: string; runId: string; mode: "write" | "check" | "preview" | "project-preview" }
+  | { type: "pipeline-ready"; at: string; stepCount: number }
+  | { type: "step-started"; at: string; ordinal: number; phase: SetupPhase; plugin: string; input?: string; output: string }
+  | { type: "step-finished"; at: string; ordinal: number; phase: SetupPhase; plugin: string; status: SetupRunStepStatus; durationMs: number; fileCount: number; changedCount: number; changes: Array<{ kind: "added" | "changed" | "removed"; path: string }>; files: string[]; warnings?: string[]; message?: string }
+  | { type: "preview-ready"; at: string; files: GeneratedFileDiff[]; totalFiles: number; truncated: boolean }
+  | ({ type: "project-trial-ready"; at: string } & ProjectTrial)
+  | { type: "run-finished"; at: string; status: string; durationMs?: number; message?: string }
+  | { type: "process-finished"; at: string; status: string; durationMs?: number; message?: string }
+  | { type: "log"; at: string; stream: "stdout" | "stderr"; message: string };
+
+async function json<T>(path: string, init?: RequestInit): Promise<T> {
+  const response = await fetch(`${ROOT}${path}`, init);
+  const value = await response.json() as T & { error?: string; code?: string; retryable?: boolean; provider?: string; host?: string; credentialSupported?: boolean; credentialPresent?: boolean };
+  if (!response.ok) throw new LocalApiError(value.error || `Local API returned ${response.status}.`, {
+    status: response.status,
+    code: value.code,
+    retryable: value.retryable,
+    provider: value.provider,
+    host: value.host,
+    credentialSupported: value.credentialSupported,
+    credentialPresent: value.credentialPresent,
+  });
+  return value;
+}
+
+export class LocalApiError extends Error {
+  readonly status: number;
+  readonly code?: string;
+  readonly retryable: boolean;
+  readonly provider?: string;
+  readonly host?: string;
+  readonly credentialSupported: boolean;
+  readonly credentialPresent: boolean;
+
+  constructor(message: string, options: { status: number; code?: string; retryable?: boolean; provider?: string; host?: string; credentialSupported?: boolean; credentialPresent?: boolean }) {
+    super(message);
+    this.name = "LocalApiError";
+    this.status = options.status;
+    this.code = options.code;
+    this.retryable = options.retryable ?? false;
+    this.provider = options.provider;
+    this.host = options.host;
+    this.credentialSupported = options.credentialSupported ?? false;
+    this.credentialPresent = options.credentialPresent ?? false;
+  }
+}
+
+export async function localStatus(): Promise<{ local: true; workspace: string; setup: SetupInfo; activeRun: { id: string; mode: "write" | "check" | "preview" } | null }> {
+  return json("/status");
+}
+
+export async function discover(path: string): Promise<Discovery> {
+  return json("/discover", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify({ path }) });
+}
+
+export async function inspectRepository(repository: string, ref: string, sourcePath: string): Promise<RepositoryInspection> {
+  return json("/repositories/prepare", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify({ repository, ref, sourcePath }) });
+}
+
+export async function saveRepositoryCredential(repository: string, token: string): Promise<{ host: string; provider: string; scope: "session"; stored: true }> {
+  return json("/repositories/credentials", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify({ repository, token }) });
+}
+
+export async function forgetRepositoryCredential(repository: string): Promise<{ host: string; provider: string; scope: "session"; stored: false }> {
+  return json("/repositories/credentials/forget", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify({ repository }) });
+}
+
+export async function previewProject(draft: ProjectDraft): Promise<ProjectPlan> {
+  return json("/projects/preview", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify(draft) });
+}
+
+export async function addProject(draft: ProjectDraft): Promise<ProjectPlan & { setup: SetupInfo }> {
+  return json("/projects", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify(draft) });
+}
+
+export async function startProjectTrial(draft: ProjectDraft): Promise<{ runId: string; mode: "project-preview"; plan: ProjectPlan }> {
+  return json("/projects/trials", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify(draft) });
+}
+
+export async function applyProjectTrial(runId: string, generate: boolean): Promise<ProjectPlan & { setup: SetupInfo; run: { runId: string; mode: "write" } | null }> {
+  return json(`/projects/trials/${encodeURIComponent(runId)}/apply`, { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify({ generate }) });
+}
+
+export async function disposeProjectTrial(runId: string): Promise<void> {
+  await json(`/projects/trials/${encodeURIComponent(runId)}/dispose`, { method: "POST", headers: LOCAL_HEADER, body: "{}" });
+}
+
+export async function startGeneration(mode: "write" | "check" | "preview" = "preview", previewRunId?: string): Promise<{ runId: string; mode: "write" | "check" | "preview" }> {
+  return json("/runs", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify({ mode, previewRunId }) });
+}
+
+export async function cancelGeneration(runId: string): Promise<void> {
+  await json(`/runs/${encodeURIComponent(runId)}/cancel`, { method: "POST", headers: LOCAL_HEADER, body: "{}" });
+}
+
+export function subscribeToRun(runId: string, onEvent: (event: RunEvent) => void, onEnd: () => void): () => void {
+  const source = new EventSource(`${ROOT}/runs/${encodeURIComponent(runId)}/events`);
+  source.onmessage = (message) => onEvent(JSON.parse(message.data) as RunEvent);
+  source.onerror = () => { source.close(); onEnd(); };
+  return () => source.close();
+}

package/src/lib/motion-features.ts

@@ -0,0 +1,11 @@
+// The Motion feature bundle, in a file of its own so that Vite can put it in
+// a chunk of its own. `domMax` is everything: animations, exit, gestures and
+// layout - layout is what `layoutId` needs, and an indicator that slides
+// from one tab to the next is the reason the library is here at all.
+//
+// Nothing imports this statically. The provider in motion.tsx loads it with
+// a dynamic import, after first paint.
+
+import { domMax } from "motion/react";
+
+export default domMax;

package/src/lib/motion.test.ts

@@ -0,0 +1,120 @@
+// The Motion presets and the CSS tokens are one clock. This test reads the
+// tokens out of index.css and holds the numbers in motion.tsx to them, so a
+// change to either side fails here rather than as a panel that leaves slower
+// than it arrived.
+
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import {
+  DURATION,
+  EASE_IN_OUT,
+  EASE_OUT,
+  fade,
+  page,
+  rise,
+  scaleIn,
+  slideFrom,
+  transitions,
+  unfold,
+} from "./motion";
+
+const css = readFileSync(new URL("../index.css", import.meta.url), "utf8");
+
+/** `--name: value;` out of index.css, or a failing message. */
+function token(name: string): string {
+  const match = css.match(new RegExp(`--${name}:\\s*([^;]+);`));
+  const value = match?.[1];
+  if (!value) throw new Error(`index.css declares no --${name}`);
+  return value.trim();
+}
+
+function bezier(value: string): number[] {
+  const inner = value.match(/^cubic-bezier\(([^)]+)\)$/);
+  const list = inner?.[1];
+  if (!list) throw new Error(`not a cubic-bezier: ${value}`);
+  return list.split(",").map((n) => Number(n.trim()));
+}
+
+describe("the clock", () => {
+  it.each(["micro", "panel", "page", "narrative"] as const)(
+    "--dur-%s is DURATION.%s in seconds",
+    (name) => {
+      expect(token(`dur-${name}`)).toBe(`${DURATION[name] * 1000}ms`);
+    },
+  );
+
+  it("--ease-out is EASE_OUT", () => {
+    expect(bezier(token("ease-out"))).toEqual([...EASE_OUT]);
+  });
+
+  it("--ease-in-out is EASE_IN_OUT", () => {
+    expect(bezier(token("ease-in-out"))).toEqual([...EASE_IN_OUT]);
+  });
+});
+
+describe("transitions", () => {
+  it("the duration tokens use the easing the CSS uses", () => {
+    expect(transitions.micro).toEqual({ duration: 0.15, ease: EASE_OUT });
+    expect(transitions.panel).toEqual({ duration: 0.25, ease: EASE_OUT });
+    expect(transitions.page).toEqual({ duration: 0.25, ease: EASE_OUT });
+    expect(transitions.narrative).toEqual({
+      duration: 0.4,
+      ease: EASE_IN_OUT,
+    });
+  });
+
+  it("settle is the one spring, and it does not bounce", () => {
+    expect(transitions.settle.type).toBe("spring");
+    // Damping ratio ζ = c / (2·sqrt(k·m)); at or above 0.9 a spring lands
+    // without a visible overshoot.
+    const { stiffness, damping, mass } = transitions.settle;
+    const zeta = damping / (2 * Math.sqrt(stiffness * mass));
+    expect(zeta).toBeGreaterThanOrEqual(0.9);
+  });
+});
+
+describe("presence", () => {
+  it.each([
+    ["fade", fade],
+    ["scaleIn", scaleIn],
+    ["rise", rise],
+    ["unfold", unfold],
+    ["slideFrom", slideFrom("100%")],
+  ])("%s leaves the way it came", (_, p) => {
+    const { transition, ...exit } = p.exit;
+    expect(transition).toBeDefined();
+    expect(exit).toEqual(p.initial);
+  });
+
+  it.each([
+    ["fade", fade],
+    ["scaleIn", scaleIn],
+    ["rise", rise],
+    ["unfold", unfold],
+    ["slideFrom", slideFrom("100%")],
+  ])("%s runs on the panel duration, both ways", (_, p) => {
+    expect(p.animate.transition).toBe(transitions.panel);
+    expect(p.exit.transition).toBe(transitions.panel);
+  });
+
+  it("a page and a row rise the same eight pixels", () => {
+    expect(page.initial.y).toBe(8);
+    expect(rise.initial.y).toBe(8);
+  });
+
+  it("a page arrives on the page duration and leaves faster, opacity only", () => {
+    expect(page.animate.transition).toBe(transitions.page);
+    expect(page.exit.transition).toBe(transitions.micro);
+    expect(Object.keys(page.exit)).toEqual(["opacity", "transition"]);
+  });
+
+  it("scaleIn grows the two percent palette-in grows", () => {
+    expect(css).toMatch(/@keyframes palette-in \{[^}]*scale\(0\.98\)/);
+    expect(scaleIn.initial.scale).toBe(0.98);
+  });
+
+  it("slideFrom keeps the offset it was given", () => {
+    expect(slideFrom("-100%").initial.x).toBe("-100%");
+    expect(slideFrom(16).initial.x).toBe(16);
+  });
+});