excalidrop 0.1.1

package/src/target.ts

@@ -0,0 +1,208 @@
+/** Dynamic backend target: local canvas (HTTP) or remote GitHub repo.
+ *  Agents switch with the switch_remote tool; writes commit straight to GitHub.
+ *  Token resolution (no user setup): GITHUB_TOKEN env → `gh auth token` →
+ *  ~/.config/excalidrop/gh_token (written by github_login device flow).
+ */
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import logger from './utils/logger.js';
+import { generateId, ServerElement } from './types.js';
+
+export type Target = { kind: 'local' } | { kind: 'remote'; repo: string };
+let active: Target = { kind: 'local' };
+export const getTarget = (): Target => active;
+
+/** Shared Excalidrop GitHub App Client ID (public, not a secret). */
+export const APP_CLIENT_ID = process.env.GITHUB_OAUTH_CLIENT_ID || 'Iv23liuS2fx3QOEIoDmx';
+
+const CONFIG_NAME = '.excalidrop.json';
+/** Walk up from cwd to find the project config (same pattern as the CLI's ports). */
+function findConfigDir(): string | null {
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+  while (true) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(path.join(dir, CONFIG_NAME), 'utf8'));
+      if (raw && typeof raw === 'object') return dir;
+    } catch { /* keep walking */ }
+    if (dir === root) return null;
+    dir = path.dirname(dir);
+  }
+}
+/** Remember the remote target per-project so agents don't pass it every call. */
+function persistTarget(repo: string | null): void {
+  const dir = findConfigDir();
+  if (!dir) return;
+  try {
+    const file = path.join(dir, CONFIG_NAME);
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (repo) raw.remote = repo; else delete raw.remote;
+    fs.writeFileSync(file, JSON.stringify(raw, null, 2) + '\n');
+  } catch (e) { logger.warn('could not persist remote target: ' + (e as Error).message); }
+}
+/** Restore the remembered target (called once at MCP startup). */
+export function loadSavedTarget(): string | null {
+  const dir = findConfigDir();
+  if (!dir) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(dir, CONFIG_NAME), 'utf8'));
+    return typeof raw.remote === 'string' ? raw.remote : null;
+  } catch { return null; }
+}
+
+const TOKEN_FILE = path.join(os.homedir(), '.config', 'excalidrop', 'gh_token');
+export function resolveToken(): string {
+  if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
+  try {
+    const t = execSync('gh auth token', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (t) return t;
+  } catch { /* no gh */ }
+  try {
+    const t = fs.readFileSync(TOKEN_FILE, 'utf8').trim();
+    if (t) return t;
+  } catch { /* no stored token */ }
+  return '';
+}
+export function storeToken(t: string): void {
+  fs.mkdirSync(path.dirname(TOKEN_FILE), { recursive: true });
+  fs.writeFileSync(TOKEN_FILE, t + '\n', { mode: 0o600 });
+}
+
+/** Parse owner/repo from "owner/repo" or a https://<owner>.github.io/<repo>/ URL. */
+export function parseRepo(input: string): string {
+  const s = input.trim().replace(/\/$/, '');
+  const m = s.match(/^https?:\/\/([a-z0-9-]+)\.github\.io\/([a-z0-9_.-]+)/i);
+  if (m) return `${m[1]}/${m[2]}`.toLowerCase();
+  if (/^[a-z0-9_.-]+\/[a-z0-9_.-]+$/i.test(s)) return s.toLowerCase();
+  throw new Error(`Cannot parse repo from "${input}" — use owner/repo or a *.github.io/<repo> URL`);
+}
+
+// ─── remote scene store (per-target memory + debounced commit) ───
+const scenes = new Map<string, { elements: Map<string, ServerElement>; sha: string | null; dirty: boolean }>();
+let timer: ReturnType<typeof setTimeout> | null = null;
+const SCENE_PATH = process.env.SCENE_PATH || 'canvas.excalidraw';
+
+function headers(): Record<string, string> {
+  return { Authorization: `Bearer ${resolveToken()}`, Accept: 'application/vnd.github+json', 'User-Agent': 'excalidrop', 'Content-Type': 'application/json' };
+}
+
+export async function switchRemote(input?: string): Promise<{ target: Target; elements: number }> {
+  if (!input) { active = { kind: 'local' }; persistTarget(null); return { target: active, elements: 0 }; }
+  const repo = parseRepo(input);
+  active = { kind: 'remote', repo };
+  const st = await ensureLoaded(repo);
+  persistTarget(repo);
+  return { target: active, elements: st.elements.size };
+}
+
+async function ensureLoaded(repo: string) {
+  let st = scenes.get(repo);
+  if (st) return st;
+  const tok = resolveToken();
+  if (!tok) throw new Error('No GitHub token. Run github_login or `gh auth login` first.');
+  const r = await fetch(`https://api.github.com/repos/${repo}/contents/${SCENE_PATH}?ref=main`, { headers: headers(), signal: AbortSignal.timeout(20000) });
+  st = { elements: new Map(), sha: null, dirty: false };
+  if (r.ok) {
+    const j = await r.json() as any;
+    const doc = JSON.parse(Buffer.from(j.content, 'base64').toString('utf8'));
+    for (const el of doc.elements || []) st.elements.set(el.id, el);
+    st.sha = j.sha;
+  }
+  scenes.set(repo, st);
+  return st;
+}
+
+function current(): { elements: Map<string, ServerElement>; sha: string | null; dirty: boolean } {
+  if (active.kind !== 'remote') throw new Error('not in remote mode');
+  const st = scenes.get(active.repo);
+  if (!st) throw new Error('call switch_remote first');
+  return st;
+}
+
+function scheduleCommit(): void {
+  if (active.kind !== 'remote') return;
+  if (timer) clearTimeout(timer);
+  timer = setTimeout(() => { void commitNow('excalidrop: autosync from MCP'); }, 10000);
+}
+
+export async function commitNow(message?: string): Promise<{ sha: string; count: number }> {
+  if (active.kind !== 'remote') throw new Error('not in remote mode');
+  const repo = active.repo;
+  const st = current();
+  const elements = Array.from(st.elements.values());
+  const doc = { type: 'excalidraw', version: 2, source: 'excalidrop', elements };
+  // Shared putFile handles: sha optimistic concurrency (409) + bootstrapping
+  // main on empty repos (forks off gh-pages) — same path as the remote server.
+  const gh = await import('./utils/github.js');
+  const newSha = await gh.putFile(repo, SCENE_PATH, doc, message || `excalidrop: update ${elements.length} elements`, 'main', st.sha || undefined);
+  st.sha = newSha;
+  st.dirty = false;
+  // mirror to gh-pages viewer copy
+  try {
+    const cur = await gh.getFile(repo, SCENE_PATH, 'gh-pages').catch(() => null);
+    await gh.putFile(repo, SCENE_PATH, doc, 'excalidrop: sync viewer', 'gh-pages', cur?.sha);
+  } catch (e) { logger.warn('viewer mirror failed: ' + (e as Error).message); }
+  logger.info(`Committed ${elements.length} elements to ${repo}`);
+  return { sha: st.sha as string, count: elements.length };
+}
+
+// Element ops (remote side)
+export function rCreate(el: ServerElement): ServerElement {
+  const st = current();
+  const full = { ...el, id: el.id || generateId() };
+  st.elements.set(full.id, full); st.dirty = true; scheduleCommit();
+  return full;
+}
+export function rBatch(els: ServerElement[]): ServerElement[] { return els.map(rCreate); }
+export function rUpdate(id: string, updates: Partial<ServerElement>): ServerElement {
+  const st = current();
+  const cur = st.elements.get(id);
+  if (!cur) throw new Error(`Element ${id} not found`);
+  const u = { ...cur, ...updates };
+  st.elements.set(id, u); st.dirty = true; scheduleCommit();
+  return u;
+}
+export function rDelete(id: string): void { const st = current(); st.elements.delete(id); st.dirty = true; scheduleCommit(); }
+export function rGet(id: string): ServerElement | null { return current().elements.get(id) || null; }
+export function rList(type?: string): ServerElement[] {
+  return Array.from(current().elements.values()).filter(e => !type || e.type === type);
+}
+export function rClear(): number { const st = current(); const n = st.elements.size; st.elements.clear(); st.dirty = true; scheduleCommit(); return n; }
+export const isRemote = (): boolean => active.kind === 'remote';
+
+// ─── GitHub App device flow (Node — no CORS issues here) ───
+// NOTE: deliberate device-flow (not web flow): static hosting has nowhere to
+// keep a client_secret, and device flow is the only secretless path per docs.
+// App user-tokens carry no scopes — permissions = user ∩ app. Optional
+// repository_id restricts the token to a single repo (least privilege).
+export async function deviceStart(clientId: string): Promise<{ user_code: string; verification_uri: string; device_code: string; interval: number }> {
+  const r = await fetch('https://github.com/login/device/code', {
+    method: 'POST', headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify({ client_id: clientId }),
+  });
+  if (!r.ok) throw new Error('device flow start failed');
+  return r.json() as any;
+}
+export async function repoId(owner: string, repo: string): Promise<number | null> {
+  try {
+    const r = await fetch(`https://api.github.com/repos/${owner}/${repo}`, { headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'excalidrop' } });
+    if (!r.ok) return null;
+    return ((await r.json()) as any).id ?? null;
+  } catch { return null; }
+}
+export async function devicePoll(clientId: string, deviceCode: string, intervalSec: number, timeoutSec = 300, repositoryId?: number): Promise<string> {
+  const deadline = Date.now() + timeoutSec * 1000;
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, intervalSec * 1000));
+    const r = await fetch('https://github.com/login/oauth/access_token', {
+      method: 'POST', headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+      body: JSON.stringify({ client_id: clientId, device_code: deviceCode, grant_type: 'urn:ietf:params:oauth:grant-type:device_code', ...(repositoryId ? { repository_id: repositoryId } : {}) }),
+    });
+    const j = await r.json() as any;
+    if (j.access_token) { storeToken(j.access_token); return j.access_token; }
+    if (j.error && j.error !== 'authorization_pending' && j.error !== 'slow_down') throw new Error(j.error_description || j.error);
+  }
+  throw new Error('device login timed out');
+}

package/src/types.ts

@@ -0,0 +1,338 @@
+export interface ExcalidrawElementBase {
+  id: string;
+  type: ExcalidrawElementType;
+  x: number;
+  y: number;
+  width?: number;
+  height?: number;
+  angle?: number;
+  strokeColor?: string;
+  backgroundColor?: string;
+  fillStyle?: string;
+  strokeWidth?: number;
+  strokeStyle?: string;
+  roughness?: number;
+  opacity?: number;
+  groupIds?: string[];
+  frameId?: string | null;
+  roundness?: {
+    type: number;
+    value?: number;
+  } | null;
+  seed?: number;
+  versionNonce?: number;
+  isDeleted?: boolean;
+  locked?: boolean;
+  link?: string | null;
+  customData?: Record<string, any> | null;
+  boundElements?: readonly ExcalidrawBoundElement[] | null;
+  updated?: number;
+  containerId?: string | null;
+}
+
+export interface ExcalidrawTextElement extends ExcalidrawElementBase {
+  type: 'text';
+  text: string;
+  fontSize?: number;
+  fontFamily?: number;
+  textAlign?: string;
+  verticalAlign?: string;
+  baseline?: number;
+  lineHeight?: number;
+}
+
+export interface ExcalidrawRectangleElement extends ExcalidrawElementBase {
+  type: 'rectangle';
+  width: number;
+  height: number;
+}
+
+export interface ExcalidrawEllipseElement extends ExcalidrawElementBase {
+  type: 'ellipse';
+  width: number;
+  height: number;
+}
+
+export interface ExcalidrawDiamondElement extends ExcalidrawElementBase {
+  type: 'diamond';
+  width: number;
+  height: number;
+}
+
+export interface ExcalidrawArrowElement extends ExcalidrawElementBase {
+  type: 'arrow';
+  points: readonly [number, number][];
+  lastCommittedPoint?: readonly [number, number] | null;
+  startBinding?: ExcalidrawBinding | null;
+  endBinding?: ExcalidrawBinding | null;
+  startArrowhead?: string | null;
+  endArrowhead?: string | null;
+}
+
+export interface ExcalidrawLineElement extends ExcalidrawElementBase {
+  type: 'line';
+  points: readonly [number, number][];
+  lastCommittedPoint?: readonly [number, number] | null;
+  startBinding?: ExcalidrawBinding | null;
+  endBinding?: ExcalidrawBinding | null;
+}
+
+export interface ExcalidrawFreedrawElement extends ExcalidrawElementBase {
+  type: 'freedraw';
+  points: readonly [number, number][];
+  pressures?: readonly number[];
+  simulatePressure?: boolean;
+  lastCommittedPoint?: readonly [number, number] | null;
+}
+
+export type ExcalidrawElement = 
+  | ExcalidrawTextElement
+  | ExcalidrawRectangleElement
+  | ExcalidrawEllipseElement
+  | ExcalidrawDiamondElement
+  | ExcalidrawArrowElement
+  | ExcalidrawLineElement
+  | ExcalidrawFreedrawElement;
+
+export interface ExcalidrawBoundElement {
+  id: string;
+  type: 'text' | 'arrow';
+}
+
+export interface ExcalidrawBinding {
+  elementId: string;
+  focus: number;
+  gap: number;
+  fixedPoint?: readonly [number, number] | null;
+}
+
+export type ExcalidrawElementType = 'rectangle' | 'ellipse' | 'diamond' | 'arrow' | 'text' | 'line' | 'freedraw' | 'image';
+
+// Excalidraw element types
+export const EXCALIDRAW_ELEMENT_TYPES: Record<string, ExcalidrawElementType> = {
+  RECTANGLE: 'rectangle',
+  ELLIPSE: 'ellipse',
+  DIAMOND: 'diamond',
+  ARROW: 'arrow',
+  TEXT: 'text',
+  FREEDRAW: 'freedraw',
+  LINE: 'line',
+  IMAGE: 'image'
+} as const;
+
+// Server-side element with metadata
+export interface ServerElement extends Omit<ExcalidrawElementBase, 'id'> {
+  id: string;
+  type: ExcalidrawElementType;
+  createdAt?: string;
+  updatedAt?: string;
+  version?: number;
+  syncedAt?: string;
+  source?: string;
+  syncTimestamp?: string;
+  text?: string;
+  originalText?: string;
+  fontSize?: number;
+  fontFamily?: string | number;
+  label?: {
+    text: string;
+  };
+  points?: any;
+  // Arrow element binding: connect arrows to shapes by element ID
+  start?: { id: string };
+  end?: { id: string };
+}
+
+// API Response types
+export interface ApiResponse<T = any> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  message?: string;
+}
+
+export interface ElementsResponse extends ApiResponse {
+  elements: ServerElement[];
+  count: number;
+}
+
+export interface ElementResponse extends ApiResponse {
+  element: ServerElement;
+}
+
+export interface SyncResponse extends ApiResponse {
+  count: number;
+  syncedAt: string;
+  beforeCount: number;
+  afterCount: number;
+}
+
+// WebSocket message types
+export interface WebSocketMessage {
+  type: WebSocketMessageType;
+  [key: string]: any;
+}
+
+export type WebSocketMessageType =
+  | 'initial_elements'
+  | 'element_created'
+  | 'element_updated'
+  | 'element_deleted'
+  | 'elements_batch_created'
+  | 'elements_synced'
+  | 'sync_status'
+  | 'mermaid_convert'
+  | 'canvas_cleared'
+  | 'export_image_request'
+  | 'set_viewport'
+  | 'files_added'
+  | 'file_deleted';
+
+export interface InitialElementsMessage extends WebSocketMessage {
+  type: 'initial_elements';
+  elements: ServerElement[];
+}
+
+export interface ElementCreatedMessage extends WebSocketMessage {
+  type: 'element_created';
+  element: ServerElement;
+}
+
+export interface ElementUpdatedMessage extends WebSocketMessage {
+  type: 'element_updated';
+  element: ServerElement;
+}
+
+export interface ElementDeletedMessage extends WebSocketMessage {
+  type: 'element_deleted';
+  elementId: string;
+}
+
+export interface BatchCreatedMessage extends WebSocketMessage {
+  type: 'elements_batch_created';
+  elements: ServerElement[];
+}
+
+export interface SyncStatusMessage extends WebSocketMessage {
+  type: 'sync_status';
+  elementCount: number;
+  timestamp: string;
+}
+
+export interface MermaidConvertMessage extends WebSocketMessage {
+  type: 'mermaid_convert';
+  mermaidDiagram: string;
+  config?: MermaidConfig;
+  timestamp: string;
+}
+
+// Mermaid conversion types
+export interface MermaidConfig {
+  startOnLoad?: boolean;
+  flowchart?: {
+    curve?: 'linear' | 'basis';
+  };
+  themeVariables?: {
+    fontSize?: string;
+  };
+  maxEdges?: number;
+  maxTextSize?: number;
+}
+
+export interface MermaidConversionRequest {
+  mermaidDiagram: string;
+  config?: MermaidConfig;
+}
+
+export interface MermaidConversionResponse extends ApiResponse {
+  elements: ServerElement[];
+  files?: any;
+  count: number;
+}
+
+// Canvas cleared message
+export interface CanvasClearedMessage extends WebSocketMessage {
+  type: 'canvas_cleared';
+  timestamp: string;
+}
+
+// Image export types
+export interface ExportImageRequestMessage extends WebSocketMessage {
+  type: 'export_image_request';
+  requestId: string;
+  format: 'png' | 'svg';
+  background?: boolean;
+}
+
+// Viewport control types
+export interface SetViewportMessage extends WebSocketMessage {
+  type: 'set_viewport';
+  requestId: string;
+  scrollToContent?: boolean;
+  scrollToElementId?: string;
+  zoom?: number;
+  offsetX?: number;
+  offsetY?: number;
+}
+
+// Snapshot types
+export interface Snapshot {
+  name: string;
+  elements: ServerElement[];
+  createdAt: string;
+}
+
+// In-memory storage for Excalidraw elements
+export const elements = new Map<string, ServerElement>();
+
+// In-memory storage for snapshots
+export const snapshots = new Map<string, Snapshot>();
+
+// In-memory file storage for image elements (Excalidraw BinaryFiles)
+export interface ExcalidrawFile {
+  id: string;
+  dataURL: string;
+  mimeType: string;
+  created: number;
+}
+export const files = new Map<string, ExcalidrawFile>();
+
+// Validation function for Excalidraw elements
+export function validateElement(element: Partial<ServerElement>): element is ServerElement {
+  const requiredFields: (keyof ServerElement)[] = ['type', 'x', 'y'];
+  const hasRequiredFields = requiredFields.every(field => field in element);
+  
+  if (!hasRequiredFields) {
+    throw new Error(`Missing required fields: ${requiredFields.join(', ')}`);
+  }
+
+  if (!Object.values(EXCALIDRAW_ELEMENT_TYPES).includes(element.type as ExcalidrawElementType)) {
+    throw new Error(`Invalid element type: ${element.type}`);
+  }
+
+  return true;
+}
+
+// Helper function to generate unique IDs
+export function generateId(): string {
+  return Date.now().toString(36) + Math.random().toString(36).substring(2);
+}
+
+// Normalize fontFamily from string names to numeric values that Excalidraw expects
+// Excalidraw uses: 1 = Virgil (handwritten), 2 = Helvetica (sans-serif), 3 = Cascadia (monospace)
+// 5 = Excalifont, 6 = Nunito, 7 = Lilita One, 8 = Comic Shanns
+export function normalizeFontFamily(fontFamily: string | number | undefined): number | undefined {
+  if (fontFamily === undefined) return undefined;
+  if (typeof fontFamily === 'number') return fontFamily;
+  const map: Record<string, number> = {
+    'virgil': 1, 'hand': 1, 'handwritten': 1,
+    'helvetica': 2, 'sans': 2, 'sans-serif': 2,
+    'cascadia': 3, 'mono': 3, 'monospace': 3,
+    'excalifont': 5,
+    'nunito': 6,
+    'lilita': 7, 'lilita one': 7,
+    'comic shanns': 8, 'comic': 8,
+    '1': 1, '2': 2, '3': 3, '5': 5, '6': 6, '7': 7, '8': 8,
+  };
+  return map[fontFamily.toLowerCase()];
+}

package/src/utils/auth.ts

@@ -0,0 +1,61 @@
+import crypto from 'node:crypto';
+import type { Request, Response, NextFunction } from 'express';
+
+const SECRET = () => process.env.AUTH_SECRET || process.env.GITHUB_CLIENT_SECRET || 'excalidrop-dev-secret';
+
+export interface Session { login: string; id: number; iat: number; }
+
+function b64u(buf: Buffer | string): string {
+  return Buffer.from(buf as any).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function unb64u(s: string): Buffer { s = s.replace(/-/g, '+').replace(/_/g, '/'); while (s.length % 4) s += '='; return Buffer.from(s, 'base64'); }
+
+export function signSession(s: Session): string {
+  const payload = b64u(JSON.stringify(s));
+  const sig = b64u(crypto.createHmac('sha256', SECRET()).update(payload).digest());
+  return `${payload}.${sig}`;
+}
+export function verifySession(token: string): Session | null {
+  try {
+    const [p, sig] = token.split('.');
+    if (!p || !sig) return null;
+    const expect = b64u(crypto.createHmac('sha256', SECRET()).update(p).digest());
+    if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expect))) return null;
+    const s = JSON.parse(unb64u(p).toString()) as Session;
+    if (Date.now() / 1000 - s.iat > 30 * 24 * 3600) return null;
+    return s;
+  } catch { return null; }
+}
+
+export function getToken(req: Request): string | null {
+  const h = req.headers.authorization;
+  if (h?.startsWith('Bearer ')) return h.slice(7);
+  const cookie = req.headers.cookie || '';
+  const m = cookie.match(/excalidrop_token=([^;]+)/);
+  return m ? decodeURIComponent(m[1] as string) : null;
+}
+
+export function authOptional(req: Request, _res: Response, next: NextFunction) {
+  const t = getToken(req);
+  (req as any).user = t ? verifySession(t) : null;
+  next();
+}
+
+/** Writes always require auth when GitHub OAuth is configured. Reads are public iff PUBLIC_READ=true. */
+export function requireWriteAuth(req: Request, res: Response, next: NextFunction) {
+  if (!process.env.GITHUB_CLIENT_ID) return next(); // local dev: open
+  const tok = getToken(req);
+  const user = tok ? verifySession(tok) : null;
+  if (user) { (req as any).user = user; return next(); }
+  return res.status(401).json({ success: false, error: 'Authentication required. Login with GitHub.' });
+}
+
+export function requireReadAuth(req: Request, res: Response, next: NextFunction) {
+  if (String(process.env.PUBLIC_READ || 'false').toLowerCase() === 'true') { const t = getToken(req); (req as any).user = t ? verifySession(t) : null; return next(); }
+  if (!process.env.GITHUB_CLIENT_ID) return next();
+  return requireWriteAuth(req, res, next);
+}
+
+export function allowedLogins(): string[] {
+  return (process.env.ALLOWED_GITHUB_USERS || '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+}