forma-diagrams 0.5.2

package/packages/cli/src/remote.ts

@@ -0,0 +1,228 @@
+import { readFile, writeFile, rename, unlink, lstat } from 'node:fs/promises';
+import { resolve, dirname, join, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { parseDocument, serializeDocument } from '../../core/src/index';
+import { HttpError } from './file-library';
+
+export function remoteOrigin(value: string) {
+  const url = new URL(value);
+  if (
+    url.username ||
+    url.password ||
+    url.pathname !== '/' ||
+    url.search ||
+    url.hash ||
+    !(
+      url.protocol === 'https:' ||
+      (url.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(url.hostname))
+    )
+  )
+    throw new Error(
+      'FORMA_REMOTE_URL must be an HTTPS origin (loopback HTTP is allowed for development).',
+    );
+  return url.origin;
+}
+
+export async function remoteClient(env: NodeJS.ProcessEnv = process.env) {
+  if (!env.FORMA_REMOTE_URL) throw new Error('Set FORMA_REMOTE_URL to your hosted Forma origin.');
+  const origin = remoteOrigin(env.FORMA_REMOTE_URL);
+  if (env.FORMA_AGENT_TOKEN && env.FORMA_AGENT_TOKEN_FILE)
+    throw new Error('Use either FORMA_AGENT_TOKEN or FORMA_AGENT_TOKEN_FILE, not both.');
+  let token = env.FORMA_AGENT_TOKEN?.trim();
+  if (env.FORMA_AGENT_TOKEN_FILE) {
+    const stat = await lstat(env.FORMA_AGENT_TOKEN_FILE);
+    if (
+      !stat.isFile() ||
+      stat.size > 4096 ||
+      (process.platform !== 'win32' && (stat.mode & 0o077) !== 0)
+    )
+      throw new Error('Use a regular private token file (chmod 600), no larger than 4 KB.');
+    token = (await readFile(env.FORMA_AGENT_TOKEN_FILE, 'utf8')).trim();
+  }
+  if (!/^forma_[a-f0-9]{24}_[a-f0-9]{64}$/.test(token ?? ''))
+    throw new Error(
+      'Set a Forma agent token using FORMA_AGENT_TOKEN or a private FORMA_AGENT_TOKEN_FILE.',
+    );
+  const request = async (path: string, body?: unknown) => {
+    let response: Response;
+    try {
+      response = await fetch(origin + '/api/agent/' + path, {
+        method: body === undefined ? 'GET' : 'POST',
+        headers: {
+          Authorization: `Bearer ${token}`,
+          ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        redirect: 'error',
+        signal: AbortSignal.timeout(30000),
+      });
+    } catch {
+      throw new Error(
+        'Could not reach the configured Forma server. Redirects are not followed; check its exact origin.',
+      );
+    }
+    const reader = response.body?.getReader();
+    let size = 0;
+    const chunks: Uint8Array[] = [];
+    if (reader)
+      while (true) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        size += chunk.value.length;
+        if (size > 8_000_000) {
+          await reader.cancel();
+          throw new Error('Server response exceeds 8 MB.');
+        }
+        chunks.push(chunk.value);
+      }
+    let data;
+    try {
+      data = JSON.parse(Buffer.concat(chunks).toString());
+    } catch {
+      throw new Error('The server returned an invalid response.');
+    }
+    if (!response.ok)
+      throw new HttpError(
+        response.status,
+        `Forma HTTP ${response.status}: ${data.error ?? 'Request rejected.'}`,
+      );
+    return data;
+  };
+  const service = {
+    me: () => request('me'),
+    list: () => request('diagrams'),
+    read: (path: string) => request('document?path=' + encodeURIComponent(path)),
+    write: (data: unknown) => request('document', data),
+  };
+  return { origin, service };
+}
+
+const bindingSchema = z
+  .object({
+    version: z.literal(1),
+    server: z.string(),
+    owner: z.string(),
+    path: z.string(),
+    revision: z.string().regex(/^[a-f0-9]{64}$/),
+  })
+  .strict();
+
+async function atomic(path: string, text: string) {
+  const temp = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temp, text, { flag: 'wx', mode: 0o600 });
+    await rename(temp, path);
+  } finally {
+    await unlink(temp).catch(() => {});
+  }
+}
+
+export async function remoteCommand(args: string[]) {
+  const { origin, service } = await remoteClient();
+  const operation = args.shift();
+  if (operation === 'whoami' && !args.length) return service.me();
+  if (operation === 'list' && !args.length) return service.list();
+  if (operation === 'pull') {
+    const path = args.shift(),
+      options: Record<string, string | boolean> = {};
+    while (args.length) {
+      const key = args.shift();
+      if (key === '--overwrite') options[key] = true;
+      else if (key === '--output' && args.length) options[key] = args.shift()!;
+      else throw new Error('Usage: forma remote pull PATH --output FILE [--overwrite]');
+    }
+    if (!path || typeof options['--output'] !== 'string')
+      throw new Error('Usage: forma remote pull PATH --output FILE [--overwrite]');
+    const file = resolve(options['--output']),
+      sidecar = file + '.forma-remote.json';
+    if (!options['--overwrite'])
+      for (const target of [file, sidecar]) {
+        try {
+          await lstat(target);
+          throw new Error(
+            'Local file or remote binding exists. Use a new output path, or --overwrite after preserving local edits.',
+          );
+        } catch (e) {
+          if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e;
+        }
+      }
+    const value = await service.read(path),
+      doc = parseDocument(value.document);
+    const binding = bindingSchema.parse({
+      version: 1,
+      server: origin,
+      owner: value.owner,
+      path,
+      revision: value.revision,
+    });
+    if (options['--overwrite']) await atomic(file, serializeDocument(doc));
+    else await writeFile(file, serializeDocument(doc), { flag: 'wx', mode: 0o600 });
+    await atomic(sidecar, JSON.stringify(binding, null, 2) + '\n');
+    return { ok: true, command: 'remote pull', output: file, path, revision: binding.revision };
+  }
+  if (operation === 'push') {
+    const source = args.shift();
+    let create = false,
+      path: string | undefined;
+    while (args.length) {
+      const key = args.shift();
+      if (key === '--create') create = true;
+      else if (key === '--path' && args.length) path = args.shift();
+      else throw new Error('Usage: forma remote push FILE [--create --path PATH]');
+    }
+    if (!source) throw new Error('Usage: forma remote push FILE [--create --path PATH]');
+    const file = resolve(source),
+      sidecar = file + '.forma-remote.json',
+      doc = parseDocument(JSON.parse(await readFile(file, 'utf8'))),
+      identity = await service.me();
+    let revision: string | null = null;
+    if (!create) {
+      const binding = bindingSchema.parse(JSON.parse(await readFile(sidecar, 'utf8')));
+      if (
+        binding.server !== origin ||
+        binding.owner !== identity.owner ||
+        (path && path !== binding.path)
+      )
+        throw new Error(
+          'This file is bound to another server, user or path. Pull the correct document first.',
+        );
+      path = binding.path;
+      revision = binding.revision;
+    }
+    if (!path) throw new Error('A new file requires --create --path FOLDER/NAME.forma.json.');
+    const saved = await service.write({ path, revision, document: doc });
+    try {
+      await atomic(
+        sidecar,
+        JSON.stringify(
+          bindingSchema.parse({
+            version: 1,
+            server: origin,
+            owner: identity.owner,
+            path,
+            revision: saved.revision,
+          }),
+          null,
+          2,
+        ) + '\n',
+      );
+    } catch {
+      throw new Error(
+        'The server saved the diagram, but the local revision binding could not be updated. Pull into a new file before another push.',
+      );
+    }
+    return { ok: true, command: 'remote push', path, revision: saved.revision };
+  }
+  throw new Error(
+    'Usage: forma remote whoami|list|pull PATH --output FILE|push FILE [--create --path PATH]',
+  );
+}
+
+export async function serveMcpStdio() {
+  const { service } = await remoteClient();
+  const { createMcpAdapter } = await import('./mcp'),
+    { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+  // The remote HTTP API still authenticates every operation; no privileges live in the bridge.
+  await createMcpAdapter(service).connect(new StdioServerTransport());
+}

package/packages/cli/src/server.ts

@@ -0,0 +1,69 @@
+import { createServer } from 'node:http';
+import { isAbsolute } from 'node:path';
+import { createFileLibrary, HttpError } from './file-library';
+import { json, readBody, serveAsset } from './http';
+/** Optional loopback adapter. Hosted mode uses a separate authenticated server. */
+export async function createLocalServer(options: {
+  directory: string;
+  assets: string;
+  port?: number;
+}) {
+  let library = await createFileLibrary(options.directory),
+    mutations = Promise.resolve();
+  const server = createServer(async (req, res) => {
+    try {
+      const port = (server.address() as { port: number }).port;
+      if (![`127.0.0.1:${port}`, `localhost:${port}`].includes(req.headers.host ?? ''))
+        throw new HttpError(403, 'Unrecognized local host.');
+      const origin = `http://${req.headers.host}`;
+      if (req.headers.origin && req.headers.origin !== origin)
+        throw new HttpError(403, 'Cross-origin access is not allowed.');
+      const url = new URL(req.url ?? '/', origin);
+      if (url.pathname.startsWith('/api/')) {
+        if (req.method === 'GET' && url.pathname === '/api/library') {
+          json(res, 200, await library.list());
+          return;
+        }
+        if (req.method === 'GET' && url.pathname === '/api/document') {
+          json(
+            res,
+            200,
+            await library.read(
+              url.searchParams.get('path') ?? '',
+              url.searchParams.get('workspace') ?? '',
+            ),
+          );
+          return;
+        }
+        if (req.method !== 'POST') throw new HttpError(405, 'Unsupported library request.');
+        const data = await readBody(req);
+        const operation = async () => {
+          if (url.pathname === '/api/library') {
+            if (typeof data.directory !== 'string' || !isAbsolute(data.directory))
+              throw new HttpError(400, 'Enter an absolute folder path.');
+            library = await createFileLibrary(data.directory);
+            return library.list();
+          }
+          if (url.pathname === '/api/document') return library.save(data);
+          throw new HttpError(404, 'Unknown library operation.');
+        };
+        const result = mutations.then(operation);
+        mutations = result.then(
+          () => {},
+          () => {},
+        );
+        json(res, 200, await result);
+        return;
+      }
+      await serveAsset(req, res, url, options.assets, 'local');
+    } catch (error) {
+      const e = error as NodeJS.ErrnoException & { status?: number };
+      json(res, e.status ?? (e.code === 'ENOENT' ? 404 : 400), { error: e.message });
+    }
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(options.port ?? 4242, '127.0.0.1', resolve);
+  });
+  return server;
+}

package/packages/cli/src/signed-cookie.ts

@@ -0,0 +1,42 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { z, type ZodType } from 'zod';
+
+export function signCookie(secret: string, payload: unknown) {
+  const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const mac = createHmac('sha256', secret).update(body).digest('base64url');
+  return `${body}.${mac}`;
+}
+
+export function verifyCookie<T>(secret: string, value: string | undefined, schema: ZodType<T>) {
+  if (!value) return null;
+  const split = value.lastIndexOf('.');
+  if (split < 1) return null;
+  const body = value.slice(0, split),
+    mac = value.slice(split + 1);
+  const expected = createHmac('sha256', secret).update(body).digest('base64url');
+  if (expected.length !== mac.length || !timingSafeEqual(Buffer.from(expected), Buffer.from(mac)))
+    return null;
+  try {
+    return schema.parse(JSON.parse(Buffer.from(body, 'base64url').toString('utf8')));
+  } catch {
+    return null;
+  }
+}
+
+export const sessionCookieSchema = z.object({
+  identity: z.object({
+    sub: z.string(),
+    email: z.string().optional(),
+    email_verified: z.boolean().optional(),
+    name: z.string().optional(),
+    hd: z.string().optional(),
+  }),
+  expires: z.number(),
+});
+export const loginCookieSchema = z.object({
+  state: z.string(),
+  verifier: z.string(),
+  nonce: z.string(),
+  challenge: z.string(),
+  expires: z.number(),
+});

package/packages/core/src/align.ts

@@ -0,0 +1,237 @@
+import type { Point } from './document';
+import type { Box, SceneNode } from './scene';
+import { overlaps } from './geometry';
+
+export const alignEdges = ['left', 'center', 'right', 'top', 'middle', 'bottom'] as const;
+export type AlignEdge = (typeof alignEdges)[number];
+export const distributeAxes = ['horizontal', 'vertical'] as const;
+export type DistributeAxis = (typeof distributeAxes)[number];
+export const NEAR_ALIGN_PX = 8;
+
+const round = (value: number) => Math.round(value * 100) / 100;
+const horizontal = (edge: AlignEdge) => edge === 'left' || edge === 'center' || edge === 'right';
+
+export function edgeValue(box: Box, edge: AlignEdge) {
+  if (edge === 'left') return box.x;
+  if (edge === 'center') return box.x + box.width / 2;
+  if (edge === 'right') return box.x + box.width;
+  if (edge === 'top') return box.y;
+  if (edge === 'middle') return box.y + box.height / 2;
+  return box.y + box.height;
+}
+
+export function placeBox(box: Box, edge: AlignEdge, value: number): Point {
+  if (edge === 'left') return { x: round(value), y: round(box.y) };
+  if (edge === 'center') return { x: round(value - box.width / 2), y: round(box.y) };
+  if (edge === 'right') return { x: round(value - box.width), y: round(box.y) };
+  if (edge === 'top') return { x: round(box.x), y: round(value) };
+  if (edge === 'middle') return { x: round(box.x), y: round(value - box.height / 2) };
+  return { x: round(box.x), y: round(value - box.height) };
+}
+
+function rangesOverlap(a0: number, a1: number, b0: number, b1: number) {
+  return a0 < b1 - 0.5 && b0 < a1 - 0.5;
+}
+
+function columnPair(a: Box, b: Box) {
+  const yOverlap = rangesOverlap(a.y, a.y + a.height, b.y, b.y + b.height);
+  const xOverlap = rangesOverlap(a.x, a.x + a.width, b.x, b.x + b.width);
+  const centerGap = Math.abs(a.x + a.width / 2 - (b.x + b.width / 2));
+  return !yOverlap && (xOverlap || centerGap < Math.max(a.width, b.width));
+}
+
+function rowPair(a: Box, b: Box) {
+  const yOverlap = rangesOverlap(a.y, a.y + a.height, b.y, b.y + b.height);
+  const xOverlap = rangesOverlap(a.x, a.x + a.width, b.x, b.x + b.width);
+  const centerGap = Math.abs(a.y + a.height / 2 - (b.y + b.height / 2));
+  return !xOverlap && (yOverlap || centerGap < Math.max(a.height, b.height));
+}
+
+function median(values: number[]) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid]! : (sorted[mid - 1]! + sorted[mid]!) / 2;
+}
+
+export function alignmentTarget(boxes: Box[], edge: AlignEdge) {
+  if (edge === 'left') return Math.min(...boxes.map((b) => b.x));
+  if (edge === 'right') return Math.max(...boxes.map((b) => b.x + b.width));
+  if (edge === 'top') return Math.min(...boxes.map((b) => b.y));
+  if (edge === 'bottom') return Math.max(...boxes.map((b) => b.y + b.height));
+  if (edge === 'center') {
+    const min = Math.min(...boxes.map((b) => b.x));
+    const max = Math.max(...boxes.map((b) => b.x + b.width));
+    return (min + max) / 2;
+  }
+  const min = Math.min(...boxes.map((b) => b.y));
+  const max = Math.max(...boxes.map((b) => b.y + b.height));
+  return (min + max) / 2;
+}
+
+export interface AlignmentCluster {
+  edge: AlignEdge;
+  ids: string[];
+  target: number;
+  delta: number;
+}
+
+export function nearAlignmentClusters(nodes: SceneNode[]): AlignmentCluster[] {
+  const found: AlignmentCluster[] = [];
+  for (const edge of alignEdges) {
+    const parent = nodes.map((_, i) => i);
+    const find = (i: number): number => (parent[i] === i ? i : (parent[i] = find(parent[i]!)));
+    const unite = (i: number, j: number) => {
+      i = find(i);
+      j = find(j);
+      if (i !== j) parent[i] = j;
+    };
+    const related = (a: SceneNode, b: SceneNode) =>
+      !overlaps(a, b) && (horizontal(edge) ? columnPair(a, b) : rowPair(a, b));
+    for (let i = 0; i < nodes.length; i++)
+      for (let j = i + 1; j < nodes.length; j++) {
+        const gap = Math.abs(edgeValue(nodes[i]!, edge) - edgeValue(nodes[j]!, edge));
+        if (gap >= 1 && gap <= NEAR_ALIGN_PX && related(nodes[i]!, nodes[j]!)) unite(i, j);
+      }
+    const groups = new Map<number, SceneNode[]>();
+    for (const [i, node] of nodes.entries()) {
+      const root = find(i);
+      groups.set(root, [...(groups.get(root) ?? []), node]);
+    }
+    for (const members of groups.values()) {
+      if (members.length < 2) continue;
+      const values = members.map((n) => edgeValue(n, edge));
+      const delta = round(Math.max(...values) - Math.min(...values));
+      if (delta < 1 || delta > NEAR_ALIGN_PX) continue;
+      const sizes = members.map((n) => (horizontal(edge) ? n.width : n.height));
+      const centers = members.map((n) =>
+        horizontal(edge) ? n.x + n.width / 2 : n.y + n.height / 2,
+      );
+      const centerSpan = Math.max(...centers) - Math.min(...centers);
+      const sizeDiff = Math.max(...sizes) - Math.min(...sizes);
+      const allowed =
+        edge === 'top' || edge === 'bottom'
+          ? NEAR_ALIGN_PX
+          : edge === 'left' || edge === 'right'
+            ? NEAR_ALIGN_PX + sizeDiff / 2
+            : Infinity;
+      if (centerSpan > allowed + 0.01) continue;
+      const pinned = members.filter((n) => n.pinned);
+      if (!pinned.length) continue;
+      found.push({
+        edge,
+        ids: members.map((n) => n.id),
+        target: round(
+          pinned.length ? median(pinned.map((n) => edgeValue(n, edge))) : median(values),
+        ),
+        delta,
+      });
+    }
+  }
+  return found;
+}
+
+const edgePreference = (edge: AlignEdge) =>
+  edge === 'center' || edge === 'middle' ? 2 : edge === 'left' || edge === 'top' ? 1 : 0;
+
+export function selectedAlignmentClusters(nodes: SceneNode[]) {
+  const assignedX = new Set<string>(),
+    assignedY = new Set<string>(),
+    chosen: AlignmentCluster[] = [];
+  const ranked = [...nearAlignmentClusters(nodes)].sort(
+    (a, b) =>
+      b.ids.length - a.ids.length ||
+      a.delta - b.delta ||
+      edgePreference(b.edge) - edgePreference(a.edge),
+  );
+  for (const cluster of ranked) {
+    const xAxis = horizontal(cluster.edge);
+    const used = xAxis ? assignedX : assignedY;
+    const ids = cluster.ids.filter((id) => !used.has(id));
+    if (ids.length < 2) continue;
+    chosen.push({ ...cluster, ids });
+    for (const id of ids) used.add(id);
+  }
+  return chosen;
+}
+
+export function alignNodes(nodes: SceneNode[], ids: string[], edge: AlignEdge) {
+  const boxes = ids.map((id) => {
+    const node = nodes.find((n) => n.id === id);
+    if (!node) throw new Error(`Unknown node: ${id}`);
+    return node;
+  });
+  if (boxes.length < 2) throw new Error('Alignment needs at least two components.');
+  const target = round(alignmentTarget(boxes, edge));
+  return boxes.map((node) => ({ id: node.id, position: placeBox(node, edge, target) }));
+}
+
+export function distributeNodes(nodes: SceneNode[], ids: string[], axis: DistributeAxis) {
+  const boxes = ids.map((id) => {
+    const node = nodes.find((n) => n.id === id);
+    if (!node) throw new Error(`Unknown node: ${id}`);
+    return node;
+  });
+  if (boxes.length < 3) throw new Error('Distribution needs at least three components.');
+  const vertical = axis === 'vertical';
+  const sorted = [...boxes].sort((a, b) => (vertical ? a.y - b.y : a.x - b.x));
+  const start = vertical ? sorted[0]!.y : sorted[0]!.x;
+  const end = vertical
+    ? sorted.at(-1)!.y + sorted.at(-1)!.height
+    : sorted.at(-1)!.x + sorted.at(-1)!.width;
+  const total = sorted.reduce((sum, n) => sum + (vertical ? n.height : n.width), 0);
+  const gap = (end - start - total) / (sorted.length - 1);
+  let cursor = start;
+  return sorted.map((node) => {
+    const position = vertical
+      ? { x: round(node.x), y: round(cursor) }
+      : { x: round(cursor), y: round(node.y) };
+    cursor += (vertical ? node.height : node.width) + gap;
+    return { id: node.id, position };
+  });
+}
+
+export function snapUnpinned(nodes: SceneNode[]) {
+  for (const cluster of selectedAlignmentClusters(nodes)) {
+    for (const id of cluster.ids) {
+      const node = nodes.find((n) => n.id === id);
+      if (!node || node.pinned) continue;
+      Object.assign(node, placeBox(node, cluster.edge, cluster.target));
+    }
+  }
+}
+
+export function mergeAlignmentPins(
+  nodes: SceneNode[],
+  operations: { ids: string[]; edge: AlignEdge }[],
+) {
+  const positions = new Map(nodes.map((n) => [n.id, { x: n.x, y: n.y }]));
+  for (const operation of operations) {
+    for (const move of alignNodes(nodes, operation.ids, operation.edge)) {
+      const current = positions.get(move.id)!;
+      const xAxis = horizontal(operation.edge);
+      positions.set(move.id, {
+        x: xAxis ? move.position.x : current.x,
+        y: xAxis ? current.y : move.position.y,
+      });
+    }
+  }
+  return [...positions]
+    .filter(([id, position]) => {
+      const node = nodes.find((n) => n.id === id)!;
+      return node.x !== position.x || node.y !== position.y;
+    })
+    .map(([id, position]) => ({ id, position }));
+}
+
+export function nudgeNodes(
+  nodes: SceneNode[],
+  ids: string[],
+  delta: Point,
+): { id: string; position: Point }[] {
+  return ids.flatMap((id) => {
+    const node = nodes.find((n) => n.id === id);
+    return node
+      ? [{ id, position: { x: round(node.x + delta.x), y: round(node.y + delta.y) } }]
+      : [];
+  });
+}