@frebreco/canvas 0.0.1 → 0.2.0-next.1

package/src/server/files.ts

@@ -0,0 +1,136 @@
+/**
+ * Files of the working dir, read-only (ADR 0002). The host's browser opens
+ * the paths its file frames show; the server sends each one now and again on
+ * every change (an agent writing a file shows up live), and the list of all
+ * shared files whenever it changes. Board paths come from guests, so every
+ * read goes through the shared set.
+ *
+ * One recursive watcher covers the working dir: editors and agents often
+ * replace files rather than write them in place, and a frame may wait for a
+ * file (or its directory) that does not exist yet.
+ */
+
+import { readFileSync, statSync, watch, type FSWatcher } from "node:fs";
+import { sep } from "node:path";
+import type { FileContent } from "../shared/protocol";
+import { SharedSet } from "./shared-set";
+
+export const MAX_FILE_BYTES = 1024 * 1024;
+const SETTLE_MS = 150;
+
+export class Files {
+  private readonly shared: SharedSet;
+  /** Open paths → the clients that opened them. */
+  private readonly subscribers = new Map<string, Set<unknown>>();
+  /** What each open path last looked like, to only report real changes. */
+  private readonly last = new Map<string, string>();
+  private watcher: FSWatcher | null = null;
+  private treeWatched = false;
+  private lastTree = "";
+  private changed = new Set<string>();
+  private everything = false;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    dir: string,
+    private readonly onFile: (path: string, file: FileContent) => void,
+    private readonly onTree: (paths: ReadonlyArray<string>) => void,
+  ) {
+    this.shared = new SharedSet(dir);
+  }
+
+  read(path: string): FileContent {
+    let absolute: string;
+    try {
+      absolute = this.shared.resolve(path);
+    } catch (error) {
+      return { kind: "denied", reason: (error as Error).message };
+    }
+    const stat = statSync(absolute, { throwIfNoEntry: false });
+    if (!stat) return { kind: "missing" };
+    if (!stat.isFile()) return { kind: "denied", reason: `${path} is not a file` };
+    if (stat.size > MAX_FILE_BYTES) return { kind: "too-large", size: stat.size };
+    const bytes = readFileSync(absolute);
+    if (bytes.subarray(0, 8000).includes(0)) return { kind: "binary", size: stat.size };
+    return { kind: "text", text: bytes.toString("utf8") };
+  }
+
+  open(path: string, client: unknown): void {
+    let set = this.subscribers.get(path);
+    if (!set) this.subscribers.set(path, (set = new Set()));
+    set.add(client);
+    this.send(path);
+    this.ensureWatcher();
+  }
+
+  close(path: string, client: unknown): void {
+    const set = this.subscribers.get(path);
+    set?.delete(client);
+    if (set?.size) return;
+    this.subscribers.delete(path);
+    this.last.delete(path);
+  }
+
+  /** A client went away: close everything it had open. */
+  drop(client: unknown): void {
+    for (const path of [...this.subscribers.keys()]) this.close(path, client);
+  }
+
+  watchTree(): void {
+    this.treeWatched = true;
+    this.lastTree = "";
+    this.sendTree();
+    this.ensureWatcher();
+  }
+
+  stop(): void {
+    this.watcher?.close();
+    if (this.timer) clearTimeout(this.timer);
+  }
+
+  private send(path: string) {
+    const file = this.read(path);
+    const key = JSON.stringify(file);
+    if (this.last.get(path) === key) return;
+    this.last.set(path, key);
+    this.onFile(path, file);
+  }
+
+  private sendTree() {
+    const paths = this.shared.list();
+    const key = paths.join("\0");
+    if (key === this.lastTree) return;
+    this.lastTree = key;
+    this.onTree(paths);
+  }
+
+  private ensureWatcher() {
+    if (this.watcher) return;
+    this.watcher = watch(this.shared.dir, { recursive: true }, (_, name) => {
+      if (name === null) this.everything = true;
+      else {
+        const path = name.split(sep).join("/");
+        // Our own state (the board is saved every few hundred ms).
+        if (path === ".canvas" || path.startsWith(".canvas/")) return;
+        this.changed.add(path);
+      }
+      if (!this.timer) this.timer = setTimeout(() => this.settle(), SETTLE_MS);
+    });
+  }
+
+  /** A burst of changes is over: re-read what it touched. */
+  private settle() {
+    this.timer = null;
+    const changed = this.changed;
+    const everything = this.everything;
+    this.changed = new Set();
+    this.everything = false;
+    for (const path of this.subscribers.keys()) {
+      // The file itself, or a directory above it (renamed, created, removed).
+      const touched =
+        everything || changed.has(path) || [...changed].some((name) => path.startsWith(`${name}/`));
+      if (touched) this.send(path);
+    }
+    if (this.treeWatched) this.sendTree();
+  }
+}

package/src/server/server.ts

@@ -0,0 +1,194 @@
+/**
+ * `canvas serve`: the local half of canvas. One WebSocket endpoint that only
+ * the host's browser may use (it presents the token from the printed link).
+ * Nothing here knows about guests — the host's browser is the relay.
+ */
+
+import type { ServerWebSocket } from "bun";
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ClientToServer, ServerToClient } from "../shared/protocol";
+import { AgentManager, detectAgents } from "./agents";
+import { BoardMcp } from "./board-mcp";
+import { Files } from "./files";
+import { Store } from "./store";
+import { Terminals } from "./terminals";
+
+export interface ServeOptions {
+  readonly dir: string;
+  readonly port: number;
+  readonly hostname: string;
+  readonly tls?: { readonly cert: string; readonly key: string };
+}
+
+export async function serve(options: ServeOptions) {
+  const store = new Store(options.dir);
+  excludeFromGit(options.dir);
+  const room = await store.room();
+  const clients = new Set<ServerWebSocket<unknown>>();
+  const broadcast = (message: ServerToClient) => {
+    const text = JSON.stringify(message);
+    for (const ws of clients) ws.send(text);
+  };
+
+  const files = new Files(
+    options.dir,
+    (path, file) => broadcast({ t: "file", path, file }),
+    (paths) => broadcast({ t: "tree", paths }),
+  );
+  process.on("exit", () => files.stop());
+  // Board tools: an agent's call goes to one host browser (the board is there).
+  const boardMcp = new BoardMcp({
+    read: (path) => files.read(path),
+    relay: (call) => {
+      const [ws] = clients;
+      if (!ws) return false;
+      ws.send(JSON.stringify({ t: "board-call", ...call } satisfies ServerToClient));
+      return true;
+    },
+  });
+  process.on("exit", () => boardMcp.stop());
+
+  const agentDefinitions = detectAgents();
+  const agents = new AgentManager({
+    dir: options.dir,
+    agents: agentDefinitions,
+    restored: store.sessions(),
+    mcpServers: (sessionId) => [boardMcp.serverFor(sessionId)],
+    onMeta: (meta) => {
+      store.appendMeta(meta);
+      broadcast({ t: "agent-meta", meta });
+    },
+    onEvent: (sessionId, event) => {
+      store.appendEvent(sessionId, event);
+      broadcast({ t: "agent-event", sessionId, event });
+    },
+    // Live state of the agent, not persisted: the meta keeps the values.
+    onOptions: (sessionId, options) => broadcast({ t: "agent-options", sessionId, options }),
+    onError: (message) => broadcast({ t: "error", message }),
+  });
+  process.on("exit", () => agents.close());
+  const terminals = new Terminals(
+    options.dir,
+    (id, data) => broadcast({ t: "term-data", id, data }),
+    (id, code) => broadcast({ t: "term-exit", id, code }),
+  );
+
+  const handle = (ws: ServerWebSocket<unknown>, message: ClientToServer) => {
+    switch (message.t) {
+      case "board-save":
+        return store.saveBoard(Buffer.from(message.state, "base64"));
+      case "agent-create":
+        return agents.create(message.id, message.agent);
+      case "agent-prompt":
+        return agents.prompt(message.sessionId, message.text, message.author);
+      case "agent-cancel":
+        return agents.cancel(message.sessionId);
+      case "agent-config":
+        return void agents
+          .configure(message.sessionId, message.configId, message.value)
+          .catch((error: unknown) => sendError(ws, error));
+      case "agent-permission":
+        return agents.resolvePermission(
+          message.sessionId,
+          message.requestId,
+          message.optionId,
+          message.by,
+        );
+      case "file-open":
+        return files.open(message.path, ws);
+      case "file-close":
+        return files.close(message.path, ws);
+      case "tree-watch":
+        return files.watchTree();
+      case "term-open": {
+        const scrollback = terminals.open(message.id, message.cols, message.rows);
+        if (scrollback)
+          ws.send(
+            JSON.stringify({
+              t: "term-data",
+              id: message.id,
+              data: scrollback,
+            } satisfies ServerToClient),
+          );
+        return;
+      }
+      case "term-input":
+        return terminals.input(message.id, message.data);
+      case "term-resize":
+        return terminals.resize(message.id, message.cols, message.rows);
+      case "board-result":
+        return boardMcp.result(message.callId, message.ok, message.text);
+    }
+  };
+
+  const server = Bun.serve({
+    port: options.port,
+    hostname: options.hostname,
+    ...(options.tls && {
+      tls: { cert: Bun.file(options.tls.cert), key: Bun.file(options.tls.key) },
+    }),
+    fetch(req, server) {
+      const url = new URL(req.url);
+      if (url.pathname !== "/ws")
+        return new Response("canvas server — open the link printed in your terminal", {
+          status: 404,
+        });
+      // A WebSocket is not subject to CORS: any page could open one to
+      // localhost. The token is what keeps other sites out.
+      if (url.searchParams.get("token") !== room.token)
+        return new Response("bad token", { status: 401 });
+      return server.upgrade(req) ? undefined : new Response("upgrade failed", { status: 400 });
+    },
+    websocket: {
+      maxPayloadLength: 64 * 1024 * 1024,
+      open(ws) {
+        clients.add(ws);
+        const board = store.board();
+        const { token: _, ...secrets } = room;
+        ws.send(
+          JSON.stringify({
+            t: "welcome",
+            room: secrets,
+            cwd: options.dir,
+            agents: agentDefinitions.map(({ kind, label }) => ({ kind, label })),
+            board: board ? Buffer.from(board).toString("base64") : null,
+            sessions: agents.snapshots(),
+          } satisfies ServerToClient),
+        );
+      },
+      message(ws, data) {
+        try {
+          handle(ws, JSON.parse(String(data)) as ClientToServer);
+        } catch (error) {
+          sendError(ws, error);
+        }
+      },
+      close(ws) {
+        clients.delete(ws);
+        files.drop(ws);
+      },
+    },
+  });
+
+  return { server, room };
+}
+
+function sendError(ws: ServerWebSocket<unknown>, error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  ws.send(JSON.stringify({ t: "error", message } satisfies ServerToClient));
+}
+
+/**
+ * Keep canvas's own files out of the user's commits: `.canvas/` holds board
+ * and session state. `.git/info/exclude` is local to the clone and never
+ * committed itself.
+ */
+function excludeFromGit(dir: string) {
+  const exclude = join(dir, ".git", "info", "exclude");
+  if (!existsSync(join(dir, ".git", "info"))) return;
+  const current = existsSync(exclude) ? readFileSync(exclude, "utf8") : "";
+  const missing = [".canvas/"].filter((line) => !current.split("\n").includes(line));
+  if (missing.length)
+    appendFileSync(exclude, `\n# canvas: local state, never committed\n${missing.join("\n")}\n`);
+}

package/src/server/shared-set.ts

@@ -0,0 +1,175 @@
+/**
+ * The files `canvas serve` is willing to show anyone (ADR 0002). Board paths
+ * are chosen by guests, so this is the ceiling of what a frame can reach:
+ *
+ *  - inside the working dir, after resolving symlinks;
+ *  - not in `.git/` or `.canvas/`, and not a well-known secret file;
+ *  - in a git repo: not ignored by git (tracked files count as not ignored);
+ *    outside git: not under `node_modules/` or a dot-directory.
+ *
+ * The tree lists the same set. The server cannot tell the host's own requests
+ * from a guest's, so the host sees the same set.
+ */
+
+import { lstatSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const HIDDEN_DIRS = new Set([".git", ".canvas"]);
+const SECRET_NAMES = new Set([
+  ".env",
+  ".npmrc",
+  ".netrc",
+  ".pypirc",
+  ".git-credentials",
+  ".htpasswd",
+  "id_rsa",
+  "id_ecdsa",
+  "id_ed25519",
+  "id_dsa",
+]);
+const SECRET_EXTENSIONS = [".pem", ".key", ".p12", ".pfx"];
+const HARMLESS_ENV = /\.(example|sample|template)$/;
+/** A walk outside git stops here rather than stream a whole disk. */
+const WALK_LIMIT = 50_000;
+
+/** Why a working-dir-relative path is never shared, whatever git says; null if it may be. */
+export function refusal(path: string): string | null {
+  const segments = path.split(/[\\/]/);
+  if (segments.some((segment) => HIDDEN_DIRS.has(segment)))
+    return "canvas never shares .git or .canvas";
+  const name = segments.at(-1) ?? "";
+  if (
+    SECRET_NAMES.has(name) ||
+    (name.startsWith(".env.") && !HARMLESS_ENV.test(name)) ||
+    SECRET_EXTENSIONS.some((extension) => name.endsWith(extension))
+  )
+    return "looks like a secret";
+  return null;
+}
+
+export class SharedSet {
+  readonly dir: string;
+  readonly git: boolean;
+
+  constructor(dir: string) {
+    this.dir = realpathSync(dir);
+    this.git = Bun.spawnSync(["git", "rev-parse", "--is-inside-work-tree"], { cwd: this.dir })
+      .stdout.toString()
+      .startsWith("true");
+  }
+
+  /**
+   * The absolute path behind a board path, if it is shared; throws why not.
+   * The file need not exist yet — an agent may be about to write it.
+   */
+  resolve(path: string): string {
+    if (!path || isAbsolute(path) || path.includes("\0"))
+      throw new Error(`not a file path: ${path}`);
+    const absolute = resolve(this.dir, path);
+    const rel = relative(this.dir, absolute);
+    if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+      throw new Error(`${path} is outside the working dir`);
+    this.check(rel, path);
+
+    // Symlinks: what the path really points at must pass the same rules.
+    let real: string;
+    try {
+      real = realpathOfNearest(absolute);
+    } catch {
+      throw new Error(`${path} is a broken link`);
+    }
+    const realRel = relative(this.dir, real);
+    if (realRel === ".." || realRel.startsWith(`..${sep}`) || isAbsolute(realRel))
+      throw new Error(`${path} links outside the working dir`);
+    if (realRel && realRel !== rel) this.check(realRel, path);
+    return absolute;
+  }
+
+  private check(rel: string, path: string) {
+    const refused = refusal(rel);
+    if (refused) throw new Error(`${path} is not shared: ${refused}`);
+    if (this.git) {
+      // 0: ignored, 1: not ignored, 128: git refuses (e.g. beyond a symlink).
+      const { exitCode } = Bun.spawnSync(["git", "check-ignore", "-q", "--", rel], {
+        cwd: this.dir,
+      });
+      if (exitCode === 0) throw new Error(`${path} is not shared: ignored by git`);
+      if (exitCode !== 1) throw new Error(`${path} is not shared: git can't place it (a symlink?)`);
+    } else if (
+      rel
+        .split(sep)
+        .some((s, i, all) => s === "node_modules" || (s.startsWith(".") && i < all.length - 1))
+    )
+      throw new Error(`${path} is not shared: in a hidden or dependency dir`);
+  }
+
+  /**
+   * Every shared file, as working-dir-relative paths with `/` separators.
+   * Symlinks are listed only if what they point at is shared too. Git knows
+   * which tracked files are links; only untracked ones need an lstat (one
+   * per file costs ~280 ms on a 21k-file repo, too slow for every change).
+   */
+  list(): string[] {
+    if (!this.git) return this.walk();
+    const git = (...args: string[]) =>
+      Bun.spawnSync(["git", "ls-files", "-z", ...args], { cwd: this.dir })
+        .stdout.toString()
+        .split("\0")
+        .filter(Boolean);
+    const links: string[] = [];
+    // `<mode> <object> <stage>\t<path>`; 120000 is a symlink.
+    const tracked = git("--stage").map((entry) => {
+      const path = entry.slice(entry.indexOf("\t") + 1);
+      if (entry.startsWith("120000")) links.push(path);
+      return path;
+    });
+    const untracked = git("--others", "--exclude-standard");
+    for (const path of untracked)
+      if (lstatSync(join(this.dir, path), { throwIfNoEntry: false })?.isSymbolicLink())
+        links.push(path);
+    const hidden = new Set([...git("--deleted"), ...links.filter((path) => !this.shares(path))]);
+    return [...new Set([...tracked, ...untracked])]
+      .filter((path) => !hidden.has(path) && !refusal(path))
+      .sort();
+  }
+
+  private shares(path: string): boolean {
+    try {
+      this.resolve(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private walk(): string[] {
+    const paths: string[] = [];
+    const visit = (dir: string) => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (paths.length >= WALK_LIMIT) return;
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+          visit(path);
+        } else if (entry.isFile() || entry.isSymbolicLink()) {
+          const rel = relative(this.dir, path).split(sep).join("/");
+          if (!refusal(rel) && (entry.isFile() || this.shares(rel))) paths.push(rel);
+        }
+      }
+    };
+    visit(this.dir);
+    return paths.sort();
+  }
+}
+
+/**
+ * realpath of the path, or of its nearest ancestor that exists (plus the
+ * rest). A dangling symlink counts as existing, so it throws rather than let
+ * a later write follow it.
+ */
+function realpathOfNearest(absolute: string): string {
+  let existing = absolute;
+  while (!lstatSync(existing, { throwIfNoEntry: false }) && dirname(existing) !== existing)
+    existing = dirname(existing);
+  return join(realpathSync(existing), relative(existing, absolute));
+}

package/src/server/store.ts

@@ -0,0 +1,98 @@
+/**
+ * Everything `canvas serve` persists lives in `<dir>/.canvas/`:
+ *
+ *   room.json              room id, trystero key, host keypair, host token
+ *   board.bin              the latest Yjs state of the board
+ *   sessions/<id>.ndjson   one agent session: a meta line, then its events
+ *
+ * Keeping the room stable across restarts keeps the links people already
+ * have working.
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { AgentEvent, RoomSecrets, SessionMeta, SessionSnapshot } from "../shared/protocol";
+
+export interface RoomFile extends RoomSecrets {
+  /** Proves a WebSocket client is the host's browser. */
+  readonly token: string;
+}
+
+const randomId = (bytes: number) =>
+  Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString("base64url");
+
+export class Store {
+  private readonly root: string;
+
+  constructor(dir: string) {
+    this.root = join(dir, ".canvas");
+    mkdirSync(join(this.root, "sessions"), { recursive: true });
+  }
+
+  async room(): Promise<RoomFile> {
+    const path = join(this.root, "room.json");
+    if (existsSync(path)) return JSON.parse(readFileSync(path, "utf8")) as RoomFile;
+
+    const pair = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, [
+      "sign",
+      "verify",
+    ]);
+    const raw = new Uint8Array(await crypto.subtle.exportKey("raw", pair.publicKey));
+    const room: RoomFile = {
+      roomId: randomId(9),
+      key: randomId(18),
+      hostPublicKey: Buffer.from(raw).toString("base64url"),
+      hostPrivateKey: await crypto.subtle.exportKey("jwk", pair.privateKey),
+      token: randomId(24),
+    };
+    writeFileSync(path, JSON.stringify(room, null, 2), { mode: 0o600 });
+    return room;
+  }
+
+  board(): Uint8Array | null {
+    const path = join(this.root, "board.bin");
+    return existsSync(path) ? new Uint8Array(readFileSync(path)) : null;
+  }
+
+  saveBoard(state: Uint8Array): void {
+    writeFileSync(join(this.root, "board.bin"), state);
+  }
+
+  sessions(): SessionSnapshot[] {
+    const dir = join(this.root, "sessions");
+    return readdirSync(dir)
+      .filter((name) => name.endsWith(".ndjson"))
+      .flatMap((name) => {
+        let meta: SessionMeta | undefined;
+        const events: AgentEvent[] = [];
+        for (const line of readFileSync(join(dir, name), "utf8").split("\n")) {
+          if (!line) continue;
+          const record = JSON.parse(line) as { meta?: SessionMeta; event?: AgentEvent };
+          if (record.meta) meta = record.meta;
+          if (record.event) events.push(record.event);
+        }
+        return meta ? [{ meta, events }] : [];
+      });
+  }
+
+  appendMeta(meta: SessionMeta): void {
+    appendFileSync(
+      join(this.root, "sessions", `${meta.id}.ndjson`),
+      `${JSON.stringify({ meta })}\n`,
+    );
+  }
+
+  appendEvent(sessionId: string, event: AgentEvent): void {
+    appendFileSync(
+      join(this.root, "sessions", `${sessionId}.ndjson`),
+      `${JSON.stringify({ event })}\n`,
+    );
+  }
+}

package/src/server/terminals.ts

@@ -0,0 +1,65 @@
+/**
+ * Shell sessions on a PTY (`Bun.Terminal`). Output is kept in a bounded
+ * scrollback so a browser that reconnects, or a guest who joins late, can
+ * replay the screen.
+ */
+
+const SCROLLBACK = 200_000;
+
+interface Term {
+  terminal: Bun.Terminal;
+  scrollback: string;
+}
+
+export class Terminals {
+  private readonly terms = new Map<string, Term>();
+  private readonly decoder = new TextDecoder();
+
+  constructor(
+    private readonly dir: string,
+    private readonly onData: (id: string, data: string) => void,
+    private readonly onExit: (id: string, code: number | null) => void,
+  ) {}
+
+  /** Open (or re-attach to) a terminal; returns the scrollback to replay. */
+  open(id: string, cols: number, rows: number): string {
+    const existing = this.terms.get(id);
+    if (existing) {
+      existing.terminal.resize(cols, rows);
+      return existing.scrollback;
+    }
+
+    const term: Term = {
+      scrollback: "",
+      terminal: new Bun.Terminal({
+        cols,
+        rows,
+        data: (_, bytes) => {
+          const data = this.decoder.decode(bytes, { stream: true });
+          term.scrollback = (term.scrollback + data).slice(-SCROLLBACK);
+          this.onData(id, data);
+        },
+      }),
+    };
+    this.terms.set(id, term);
+    const shell = process.env.SHELL ?? "bash";
+    const proc = Bun.spawn([shell, "-l"], {
+      cwd: this.dir,
+      terminal: term.terminal,
+      env: { ...process.env, TERM: "xterm-256color" },
+    });
+    void proc.exited.then((code) => {
+      this.terms.delete(id);
+      this.onExit(id, code);
+    });
+    return "";
+  }
+
+  input(id: string, data: string): void {
+    this.terms.get(id)?.terminal.write(data);
+  }
+
+  resize(id: string, cols: number, rows: number): void {
+    this.terms.get(id)?.terminal.resize(cols, rows);
+  }
+}