@seungyeop-lee/beads-desk 0.1.0

package/bin/daemon.js

@@ -0,0 +1,376 @@
+import { spawn } from "node:child_process";
+import {
+  closeSync,
+  linkSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { connect, createServer } from "node:net";
+import { join } from "node:path";
+import { findWorkspaceRoot } from "./workspaceRoot.js";
+
+const HOST = "127.0.0.1";
+const MAX_PORT_ATTEMPTS = 100;
+const SERVER_READY_TIMEOUT_MS = 30_000;
+const STOP_TIMEOUT_MS = 5_000;
+/** 다른 bd-desk 명령이 서버를 띄우는 동안 기다리는 시간입니다. 서버 준비 시간보다 길어야 합니다. */
+const LOCK_TIMEOUT_MS = SERVER_READY_TIMEOUT_MS + STOP_TIMEOUT_MS + 5_000;
+
+/**
+ * background 서버를 시작, 종료, 재시작합니다. 각 명령은 종료 코드를 돌려줍니다.
+ *
+ * @param {object} options
+ * @param {string} options.runtimeDir 상태 파일(`server.json`), 로그(`server.log`), lock 파일을 두는 디렉터리입니다.
+ * @param {(port: number, workspaceRoot: string) => { command: string; args: string[]; cwd?: string; env: NodeJS.ProcessEnv }} options.serverCommand
+ * @param {(url: string) => void} options.openBrowser
+ * @param {number} options.defaultPort 포트를 지정하지 않으면 이 포트부터 비어 있는 포트를 씁니다.
+ * @param {(message: string) => void} [options.print]
+ */
+export function createDaemon({
+  runtimeDir,
+  serverCommand,
+  openBrowser,
+  defaultPort,
+  print = console.log,
+}) {
+  mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
+  const statePath = join(runtimeDir, "server.json");
+  const logPath = join(runtimeDir, "server.log");
+  const lockPath = join(runtimeDir, "command.lock");
+
+  return {
+    /**
+     * 이미 실행 중이면 새로 띄우지 않고 cwd를 workspace로 등록해 현재 workspace로 바꿉니다.
+     *
+     * @param {{ cwd: string; port?: number; open: boolean }} options
+     */
+    start: ({ cwd, port, open }) =>
+      withLock(async () => {
+        const root = workspaceRootOf(cwd);
+        const running = await runningServer();
+        if (running) {
+          const list = await registerWorkspace(running.url, root, true);
+          print(`Switched the running server to workspace: ${list.current}`);
+          print(`URL: ${running.url}`);
+          if (port && port !== running.port) {
+            print(
+              `The server is already running on port ${running.port}, so port ${port} was not applied. To change the port, run: bd-desk restart --port ${port}`,
+            );
+          }
+          if (open) openBrowser(running.url);
+          return 0;
+        }
+        const server = await launch(root, port);
+        print(`workspace: ${root}`);
+        print(`URL: ${server.url}`);
+        print("To stop the server, run: bd-desk stop");
+        if (open) openBrowser(server.url);
+        return 0;
+      }),
+
+    /** 서버가 응답하지 않아도 끌 수 있도록 응답을 기다리지 않고 종료합니다. */
+    stop: () =>
+      withLock(async () => {
+        const state = readState();
+        if (!state || !isServerAlive(state.pid)) {
+          rmSync(statePath, { force: true });
+          print("No beads-desk server is running.");
+          return 2;
+        }
+        await terminate(state.pid);
+        print("Server stopped.");
+        return 0;
+      }),
+
+    /**
+     * 같은 포트로 다시 시작하고, 등록한 workspace를 같은 순서로 등록한 뒤 현재 workspace를 고릅니다.
+     *
+     * @param {{ port?: number; open: boolean }} options
+     */
+    restart: ({ port, open }) =>
+      withLock(async () => {
+        const running = await runningServer();
+        if (!running) {
+          const root = workspaceRootOf(process.cwd());
+          print("No server is running. Starting a new one.");
+          const server = await launch(root, port);
+          print(`URL: ${server.url}`);
+          if (open) openBrowser(server.url);
+          return 0;
+        }
+        const list = await readWorkspaces(running.url);
+        await terminate(running.pid);
+
+        // 그사이 지워진 workspace는 건너뜁니다. 남은 것이 없으면 이전 현재 workspace로 띄웁니다.
+        const existing = [];
+        const missing = [];
+        for (const workspace of list.workspaces) {
+          (isWorkspaceRoot(workspace) ? existing : missing).push(workspace);
+        }
+        const [first = list.current, ...rest] = existing;
+        const server = await launch(first, port ?? running.port);
+        for (const workspace of rest) {
+          await registerWorkspace(server.url, workspace, false);
+        }
+        for (const workspace of missing) {
+          print(`Workspace not found, so it was not registered again: ${workspace}`);
+        }
+        const current = isWorkspaceRoot(list.current)
+          ? (await registerWorkspace(server.url, list.current, true)).current
+          : first;
+        print(`workspace: ${current}`);
+        print(`URL: ${server.url}`);
+        if (open) openBrowser(server.url);
+        return 0;
+      }),
+  };
+
+  /** 서버를 background로 시작하고, 요청을 받을 수 있을 때까지 기다립니다. */
+  async function launch(workspaceRoot, requestedPort) {
+    if (requestedPort && !(await isPortAvailable(requestedPort))) {
+      throw new Error(`Port ${requestedPort} is already in use.`);
+    }
+    const port = requestedPort ?? (await findAvailablePort(defaultPort));
+    if (!requestedPort && port !== defaultPort) {
+      print(`Port ${defaultPort} is already in use. Starting on port ${port}.`);
+    }
+
+    const url = `http://${HOST}:${port}`;
+    const { command, args, cwd, env } = serverCommand(port, workspaceRoot);
+    const log = openSync(logPath, "a");
+    // 명령을 실행한 터미널이 닫혀도 서버가 남도록 새 process group으로 분리합니다.
+    const server = spawn(command, args, {
+      cwd,
+      env,
+      stdio: ["ignore", log, log],
+      detached: true,
+      windowsHide: true,
+    });
+    closeSync(log);
+    server.unref();
+    writeFileSync(statePath, JSON.stringify({ pid: server.pid, port, url }));
+
+    try {
+      await waitForServer(url, server.pid);
+    } catch (error) {
+      await terminate(server.pid);
+      throw new Error(`${error.message} Log: ${logPath}`, { cause: error });
+    }
+    if ((await readHealth(url))?.runtime?.bdVersion === null) {
+      print(
+        "Warning: the server could not run bd. Make sure bd is on PATH, or set BD_BIN to its path.",
+      );
+    }
+    return { url, port };
+  }
+
+  /** 상태 파일의 서버가 살아 있으면 요청을 받을 때까지 기다린 뒤 돌려줍니다. 종료된 서버의 상태 파일은 지웁니다. */
+  async function runningServer() {
+    const state = readState();
+    if (!state) return null;
+    if (!isServerAlive(state.pid)) {
+      rmSync(statePath, { force: true });
+      return null;
+    }
+    try {
+      await waitForServer(state.url, state.pid);
+    } catch (error) {
+      throw new Error(
+        `The running server (pid ${state.pid}) is not responding. Stop it with bd-desk stop, then start again.`,
+        { cause: error },
+      );
+    }
+    return state;
+  }
+
+  function readState() {
+    try {
+      return JSON.parse(readFileSync(statePath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+
+  /** pid를 쓴 임시 파일을 lock 이름으로 hard link해, lock 파일이 항상 주인 pid를 담은 채로 생기게 합니다. */
+  function acquireLock() {
+    const candidate = `${lockPath}.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    writeFileSync(candidate, String(process.pid));
+    try {
+      linkSync(candidate, lockPath);
+      return true;
+    } catch (error) {
+      if (error.code === "EEXIST") return false;
+      throw error;
+    } finally {
+      rmSync(candidate, { force: true });
+    }
+  }
+
+  /** lock이 없으면 null을 돌려줍니다. */
+  function lockOwner() {
+    try {
+      return Number(readFileSync(lockPath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+
+  async function terminate(pid) {
+    signalGroup(pid, "SIGTERM");
+    const deadline = Date.now() + STOP_TIMEOUT_MS;
+    while (isAlive(pid) && Date.now() < deadline) await sleep(100);
+    if (isAlive(pid)) signalGroup(pid, "SIGKILL");
+    rmSync(statePath, { force: true });
+  }
+
+  /**
+   * 상태 파일을 읽고 쓰는 명령이 겹치지 않게 lock 파일을 잡고 실행합니다.
+   * lock을 잡은 명령이 비정상 종료돼 lock만 남았으면 그 lock은 무시합니다.
+   */
+  async function withLock(command) {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    while (!acquireLock()) {
+      const owner = lockOwner();
+      if (owner !== null && !isAlive(owner)) {
+        rmSync(lockPath, { force: true });
+        continue;
+      }
+      if (Date.now() > deadline) {
+        throw new Error("Timed out waiting for another bd-desk command to finish.");
+      }
+      await sleep(100);
+    }
+    try {
+      return await command();
+    } finally {
+      rmSync(lockPath, { force: true });
+    }
+  }
+}
+
+// 서버가 띄운 하위 process까지 함께 끝나도록 process group 전체에 보냅니다.
+function signalGroup(pid, signal) {
+  try {
+    process.kill(process.platform === "win32" ? pid : -pid, signal);
+  } catch {
+    // 이미 종료됐습니다.
+  }
+}
+
+/**
+ * pid(음수면 process group)가 살아 있는지 확인합니다.
+ * process가 존재해도 신호를 보낼 권한이 없으면 EPERM이 나므로 살아 있는 것으로 봅니다.
+ */
+function isAlive(target) {
+  try {
+    process.kill(target, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+
+/**
+ * 서버는 detached로 띄워 자기 process group의 리더가 됩니다.
+ * 상태 파일의 pid를 다른 process가 재사용하고 있으면 그 pid의 group이 없으므로 서버가 아닌 것으로 봅니다.
+ */
+function isServerAlive(pid) {
+  // windows에는 process group이 없으므로 pid로 확인합니다.
+  return isAlive(process.platform === "win32" ? pid : -pid);
+}
+
+/** cwd에서 bd가 쓰는 workspace 디렉터리를 찾고, 없으면 실패합니다. */
+function workspaceRootOf(cwd) {
+  const root = findWorkspaceRoot(cwd);
+  if (!root) throw new Error(`No beads workspace found: ${cwd}`);
+  return root;
+}
+
+function isWorkspaceRoot(root) {
+  return findWorkspaceRoot(root) === root;
+}
+
+/** 서버 상태 본문을 읽어 돌려줍니다. 서버가 응답하지 않으면 null을 돌려줍니다. */
+async function readHealth(url) {
+  try {
+    const response = await fetch(`${url}/api/health`);
+    return response.ok ? await response.json() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function waitForServer(url, pid) {
+  const deadline = Date.now() + SERVER_READY_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (!isAlive(pid)) throw new Error("The server exited before it was ready.");
+    if ((await readHealth(url)) !== null) return;
+    await sleep(250);
+  }
+  throw new Error("Timed out waiting for the server to be ready.");
+}
+
+async function registerWorkspace(url, path, select) {
+  const response = await fetch(`${url}/api/workspaces`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ path, select }),
+  });
+  const body = await response.json();
+  if (!body.ok) throw new Error(body.error);
+  return body.data;
+}
+
+async function readWorkspaces(url) {
+  const body = await (await fetch(`${url}/api/workspaces`)).json();
+  if (!body.ok) throw new Error(body.error);
+  return body.data;
+}
+
+async function findAvailablePort(startPort) {
+  for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt += 1) {
+    if (await isPortAvailable(startPort + attempt)) return startPort + attempt;
+  }
+  throw new Error("No free local port found.");
+}
+
+/**
+ * 서버가 이 포트를 열 수 있고, 다른 서버가 localhost의 IPv4와 IPv6 어느 쪽에서도 요청을 받고 있지 않아야 비어 있다고 봅니다.
+ * macOS는 다른 서버가 `::`나 `0.0.0.0`에서 같은 포트를 받고 있어도 `127.0.0.1`을 열게 해 주므로, 열어 보는 것만으로는 판정할 수 없습니다.
+ * 열어 보는 probe에 연결 확인이 붙지 않도록 연결 확인을 먼저 끝냅니다.
+ */
+async function isPortAvailable(port) {
+  return (
+    !(await isAnswering(port, HOST)) &&
+    !(await isAnswering(port, "::1")) &&
+    (await canListenOn(port))
+  );
+}
+
+function canListenOn(port) {
+  return new Promise((resolvePort) => {
+    const probe = createServer();
+    probe.once("error", () => resolvePort(false));
+    probe.once("listening", () => probe.close(() => resolvePort(true)));
+    probe.listen(port, HOST);
+  });
+}
+
+/** IPv6를 쓸 수 없는 환경처럼 연결이 어떤 이유로든 실패하면 받는 서버가 없다고 봅니다. */
+function isAnswering(port, host) {
+  return new Promise((resolveAnswer) => {
+    const socket = connect(port, host);
+    socket.once("connect", () => {
+      socket.destroy();
+      resolveAnswer(true);
+    });
+    socket.once("error", () => resolveAnswer(false));
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}

package/bin/workspaceRoot.js

@@ -0,0 +1,62 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+// launcher와 서버가 함께 쓰는 workspace 탐색 규칙입니다. launcher는 서버 bundle을 불러올 수 없으므로
+// 규칙을 이 파일에 plain JS로 두고, 서버(`src/server/infra/runtime/serverRuntime.ts`)는 이 파일을 bundle에 넣어 씁니다.
+
+/**
+ * path에서 bd가 쓰는 workspace 디렉터리를 찾습니다. 디렉터리가 없거나 workspace를 찾지 못하면 null을 돌려줍니다.
+ *
+ * bd가 workspace를 찾는 방식을 따릅니다. path부터 git 저장소 최상위까지(git 밖이면 파일 시스템 루트까지) 올라가며 `.beads`를 찾고,
+ * git worktree라 찾지 못했으면 bd처럼 main 저장소의 `.beads`를 씁니다. 이때 workspace는 worktree 최상위 디렉터리로 두어,
+ * bd 실행과 git을 읽는 기능이 그 worktree의 브랜치를 기준으로 동작하게 합니다.
+ * symlink를 거친 경로와 실제 경로가 다른 workspace로 등록되지 않게 실제 경로를 돌려줍니다.
+ *
+ * @param {string} path
+ * @returns {string | null}
+ */
+export function findWorkspaceRoot(path) {
+  if (!isDirectory(resolve(path))) return null;
+  const start = realpathSync(resolve(path));
+  const git = gitRepository(start);
+  for (let dir = start; ; dir = dirname(dir)) {
+    if (hasBeadsProject(dir)) return dir;
+    if (dir === git?.topLevel || dirname(dir) === dir) break;
+  }
+  return git && hasBeadsProject(dirname(git.commonDir)) ? git.topLevel : null;
+}
+
+// bd는 설정이나 DB 파일이 있는 `.beads`만 workspace로 봅니다. bd가 전역 상태를 두는 `~/.beads`는 workspace가 아닙니다.
+function hasBeadsProject(dir) {
+  const beads = join(dir, ".beads");
+  return (
+    isDirectory(beads) &&
+    readdirSync(beads).some(
+      (name) => name === "metadata.json" || name === "config.yaml" || name.endsWith(".db"),
+    )
+  );
+}
+
+/**
+ * dir이 속한 git 저장소의 최상위 디렉터리와 공용 git 디렉터리를 돌려줍니다. worktree면 공용 git 디렉터리가 main 저장소의 `.git`입니다.
+ * git 저장소가 아니거나 git이 없으면 null을 돌려줍니다.
+ */
+function gitRepository(dir) {
+  // git hook 안에서 실행하면 GIT_DIR 등이 다른 저장소를 가리키므로, dir만으로 저장소를 찾게 GIT_ 환경 변수를 뺍니다.
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) if (key.startsWith("GIT_")) delete env[key];
+  const result = spawnSync(
+    "git",
+    ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"],
+    { cwd: dir, env, encoding: "utf8" },
+  );
+  const [topLevel, commonDir] = result.status === 0 ? result.stdout.trim().split("\n") : [];
+  return topLevel && commonDir
+    ? { topLevel: realpathSync(topLevel), commonDir: realpathSync(commonDir) }
+    : null;
+}
+
+function isDirectory(path) {
+  return existsSync(path) && statSync(path).isDirectory();
+}

package/next.config.ts

@@ -0,0 +1,9 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  allowedDevOrigins: ["127.0.0.1"],
+  // next dev가 packages/app에 AGENTS.md를 만들지 않게 합니다. 같은 안내는 저장소 루트의 AGENTS.md에 있습니다.
+  agentRules: false,
+};
+
+export default nextConfig;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@seungyeop-lee/beads-desk",
+  "version": "0.1.0",
+  "description": "Local web UI for Beads (bd)",
+  "keywords": [
+    "bd",
+    "beads",
+    "issue-tracker",
+    "kanban",
+    "local-first",
+    "web-ui"
+  ],
+  "homepage": "https://github.com/seungyeop-lee/beads-desk#readme",
+  "bugs": {
+    "url": "https://github.com/seungyeop-lee/beads-desk/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "seungyeop-lee",
+    "url": "https://github.com/seungyeop-lee"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seungyeop-lee/beads-desk.git",
+    "directory": "packages/app"
+  },
+  "bin": {
+    "bd-desk": "bin/bd-desk.js"
+  },
+  "files": [
+    ".next/BUILD_ID",
+    ".next/app-path-routes-manifest.json",
+    ".next/build-manifest.json",
+    ".next/export-marker.json",
+    ".next/fallback-build-manifest.json",
+    ".next/images-manifest.json",
+    ".next/package.json",
+    ".next/prerender-manifest.json",
+    ".next/required-server-files.js",
+    ".next/required-server-files.json",
+    ".next/routes-manifest.json",
+    ".next/server",
+    ".next/static",
+    "bin/bd-desk.js",
+    "bin/daemon.js",
+    "bin/workspaceRoot.js",
+    "next.config.ts"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "next": "^16.4.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}