@taskmark/ui 0.2.4 → 0.2.5

package/README.md

@@ -12,6 +12,15 @@ npx taskmark serve
 
 Opens [http://localhost:8275](http://localhost:8275) bound to **this** board.
 
+### Development (live board reload)
+
+```bash
+npx taskmark dev
+# or: npm run dev / yarn dev
+```
+
+Runs Next.js in development on port **8275** and refreshes the UI when board `.md` files change.
+
 Without a local install (once published):
 
 ```bash
@@ -49,16 +58,17 @@ You do **not** need to clone `taskmark-frontend`.
   "scripts": {
     "start": "taskmark serve --no-open",
     "serve": "taskmark serve",
+    "dev": "taskmark dev",
     "build": "taskmark build --board . --out out",
     "preview": "taskmark preview"
   },
   "dependencies": {
-    "@taskmark/ui": "^0.2.4"
+    "@taskmark/ui": "^0.2.5"
   }
 }
 ```
 
-Then `npm install && npm run serve` (or `npm start`). For **Vercel**, use `npm run build` (static HTML in `out/`) — see the board-ui-stub `vercel.json`.
+Then `npm install && npm run serve` (or `npm start`). Use `npm run dev` while editing board markdown. For **Vercel**, use `npm run build` (static HTML in `out/`) — see the board-ui-stub `vercel.json`.
 
 ### Static production build
 
@@ -78,14 +88,15 @@ Favicon, webmanifest, and Open Graph assets ship in `public/` and are included i
 ```bash
 npm install
 npm run build    # next standalone + dist/ for the CLI
-npm run serve    # local bin against cwd/env board
-npm run dev      # Next dev server on :3000 (setup wizard unless auto-bound)
+npm run serve    # production standalone against cwd/env board
+npm run dev      # taskmark dev (Next + markdown live reload) on :8275
 ```
 
-Zero-config for `npm run dev`: `TASKMARK_BOARD` / `TASKMARK_MASTER` / cwd (see above). Cookie multi-master setup still works when unbound.
+Zero-config for `npm run dev` / `serve`: `TASKMARK_BOARD` / `TASKMARK_MASTER` / cwd (see above). Cookie multi-master setup still works when unbound.
 
 ## Stack
 
-- Next.js standalone server packaged for `taskmark serve`
+- Next.js production server packaged for `taskmark serve` (`next start` + slim `dist/prod-next`)
+- `taskmark dev` for live board markdown reload
 - Tailwind CSS v4
 - Local markdown boards only (no hosted sync)

package/app/api/taskmark-reload/route.ts

@@ -0,0 +1,103 @@
+import fs from "node:fs"
+import path from "node:path"
+
+import { cwdCandidates } from "@/lib/taskmark/autoconfig"
+import { resolveBoardAtPath } from "@/lib/taskmark/discover"
+
+export const dynamic = "force-dynamic"
+export const runtime = "nodejs"
+
+function resolveBoardRoot(): string | null {
+  const env = process.env.TASKMARK_BOARD?.trim()
+  if (env) {
+    const board = resolveBoardAtPath(path.resolve(env))
+    if (board) return board
+  }
+  for (const candidate of cwdCandidates()) {
+    const board = resolveBoardAtPath(candidate)
+    if (board) return board
+  }
+  return null
+}
+
+function walkMarkdownFiles(root: string, out: string[] = []): string[] {
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "out") {
+      continue
+    }
+    const full = path.join(root, entry.name)
+    if (entry.isDirectory()) {
+      walkMarkdownFiles(full, out)
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      out.push(full)
+    }
+  }
+  return out
+}
+
+function latestMarkdownMtime(boardRoot: string): number {
+  let latest = 0
+  for (const file of walkMarkdownFiles(boardRoot)) {
+    try {
+      const mtime = fs.statSync(file).mtimeMs
+      if (mtime > latest) latest = mtime
+    } catch {
+      // ignore transient deletes
+    }
+  }
+  return latest
+}
+
+/**
+ * SSE stream that emits `reload` when any board `.md` mtime changes.
+ * Used only by `taskmark dev` / Next development mode.
+ */
+export async function GET() {
+  if (process.env.NODE_ENV !== "development") {
+    return new Response("Not available", { status: 404 })
+  }
+
+  const boardRoot = resolveBoardRoot()
+  if (!boardRoot) {
+    return new Response("No board", { status: 404 })
+  }
+
+  const encoder = new TextEncoder()
+  let last = latestMarkdownMtime(boardRoot)
+  let interval: ReturnType<typeof setInterval> | null = null
+
+  const stream = new ReadableStream({
+    start(controller) {
+      const send = (event: string, data: string) => {
+        controller.enqueue(encoder.encode(`event: ${event}\ndata: ${data}\n\n`))
+      }
+      send("hello", String(Date.now()))
+      interval = setInterval(() => {
+        const next = latestMarkdownMtime(boardRoot)
+        if (next > last) {
+          last = next
+          send("reload", String(Date.now()))
+        } else {
+          send("ping", String(Date.now()))
+        }
+      }, 750)
+    },
+    cancel() {
+      if (interval) clearInterval(interval)
+    },
+  })
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+    },
+  })
+}

package/app/board/page.tsx

@@ -23,6 +23,7 @@ import {
   parseListViewMode,
   type ListViewMode,
 } from "@/lib/taskmark/list-view-mode"
+import { DEV_RELOAD_TOKEN } from "@/lib/taskmark/dev-reload-token"
 import { loadSnapshotFromPublic } from "@/lib/taskmark/load-snapshot-server"
 import { parseEpicsForProject } from "@/lib/taskmark/parse-epics"
 import {
@@ -38,6 +39,11 @@ import {
 import { isStaticRuntime } from "@/lib/taskmark/static-mode"
 import { loadWorkspace } from "@/lib/taskmark/workspace"
 
+export const dynamic = "force-dynamic"
+
+// Keep this import so `taskmark dev` can touch the token module and refresh RSC.
+void DEV_RELOAD_TOKEN
+
 type BoardPageProps = {
   searchParams: Promise<{
     view?: string | string[]
@@ -143,7 +149,6 @@ export default async function BoardPage({ searchParams }: BoardPageProps) {
         <AppBar
           projects={workspace.projects}
           activeProjectId={activeProject.id}
-          masterCount={workspace.masters.length}
           autoconfig={workspace.autoconfig}
         />
 
@@ -177,9 +182,6 @@ export default async function BoardPage({ searchParams }: BoardPageProps) {
                     ? ` · story ${selectedStoryId} not in list`
                     : ""}
               </p>
-              <p className="mt-1 font-mono text-xs text-muted-foreground">
-                {activeProject.boardPath}
-              </p>
             </div>
             <ListViewSwitcher
               activeView={activeView}

package/app/layout.tsx

@@ -1,5 +1,6 @@
 import type { Metadata, Viewport } from "next"
 import { Archivo_Black, Space_Grotesk } from "next/font/google"
+import { BoardDevReloader } from "@/components/board/board-dev-reloader"
 import { Toaster } from "@/components/ui/sonner"
 import { SITE } from "@/lib/site"
 import "./globals.css"
@@ -80,6 +81,7 @@ export default function RootLayout({
         className={`${archivoBlack.variable} ${spaceGrotesk.variable} font-sans antialiased`}
       >
         <Toaster />
+        <BoardDevReloader />
         {children}
       </body>
     </html>

package/bin/lib/watch-board-markdown.mjs

@@ -0,0 +1,65 @@
+import fs from "node:fs"
+import path from "node:path"
+
+const IGNORE_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "out",
+  ".next",
+  "dist",
+  ".taskmark-ui-build",
+])
+
+function shouldIgnoreDir(name) {
+  return IGNORE_DIRS.has(name) || name.startsWith(".")
+}
+
+function latestMarkdownMtime(boardRoot) {
+  let latest = 0
+  const walk = (dir) => {
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (!shouldIgnoreDir(entry.name)) walk(full)
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        try {
+          latest = Math.max(latest, fs.statSync(full).mtimeMs)
+        } catch {
+          // ignore races
+        }
+      }
+    }
+  }
+  walk(boardRoot)
+  return latest
+}
+
+/**
+ * Poll a board directory for `.md` mtime changes.
+ * Uses polling (not recursive fs.watch) to avoid EMFILE on large boards.
+ * Returns a stop function.
+ */
+export function watchBoardMarkdown(boardRoot, onChange) {
+  let stopped = false
+  let lastStamp = latestMarkdownMtime(boardRoot)
+
+  const interval = setInterval(() => {
+    if (stopped) return
+    const next = latestMarkdownMtime(boardRoot)
+    if (next > lastStamp) {
+      lastStamp = next
+      onChange()
+    }
+  }, 750)
+
+  return () => {
+    stopped = true
+    clearInterval(interval)
+  }
+}

package/bin/taskmark.js

@@ -3,23 +3,28 @@ import { spawn } from "node:child_process"
 import fs from "node:fs"
 import http from "node:http"
 import path from "node:path"
+import { createRequire } from "node:module"
 import { fileURLToPath } from "node:url"
 
 import { resolveServeBoard } from "./lib/resolve-board.mjs"
 import { startStaticServer } from "./lib/static-preview.mjs"
+import { watchBoardMarkdown } from "./lib/watch-board-markdown.mjs"
 
 const DEFAULT_PORT = 8275
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const packageRoot = path.resolve(__dirname, "..")
+const requireFromPackage = createRequire(path.join(packageRoot, "package.json"))
 
 function printHelp() {
   console.log(`Usage:
   taskmark serve [options]
+  taskmark dev [options]
   taskmark build [options]
   taskmark preview [options]
 
 Commands:
   serve              Start the prebuilt local UI server (default port ${DEFAULT_PORT})
+  dev                Next.js development server with board markdown live reload
   build              Production static HTML export for Vercel / static hosting
   preview            Serve an existing static export (default: <board>/out)
 
@@ -27,7 +32,7 @@ Options:
   --port, -p <n>     Listen port (default ${DEFAULT_PORT}; env PORT / TASKMARK_PORT)
   --board <path>     Board or product root (sets TASKMARK_BOARD)
   --out <dir>        Static output directory for build/preview (default: <board>/out)
-  --no-open          Do not open a browser (serve / preview)
+  --no-open          Do not open a browser (serve / preview / dev)
   --help, -h         Show help
 
 Board resolution (same as the UI):
@@ -38,6 +43,7 @@ Board resolution (same as the UI):
 
 Examples:
   npm i @taskmark/ui --save && npx taskmark serve
+  npx taskmark dev --board .
   npx taskmark build --board .
   npm run preview
   npx taskmark preview --port 9000
@@ -97,15 +103,73 @@ function resolvePort(raw) {
   return n
 }
 
-function findStandaloneServer() {
-  const candidates = [
-    path.join(packageRoot, "dist", "standalone", "server.js"),
-    path.join(packageRoot, ".next", "standalone", "server.js"),
-  ]
-  for (const candidate of candidates) {
-    if (fs.existsSync(candidate)) return candidate
+function resolveNextBin() {
+  try {
+    return requireFromPackage.resolve("next/dist/bin/next")
+  } catch {
+    const fallback = path.join(
+      packageRoot,
+      "node_modules",
+      "next",
+      "dist",
+      "bin",
+      "next"
+    )
+    if (fs.existsSync(fallback)) return fallback
+    throw new Error(
+      "next binary not found. Reinstall @taskmark/ui (next is required for serve/dev)."
+    )
   }
-  return null
+}
+
+/**
+ * Ensure packageRoot/.next points at a usable production build.
+ * Published packages ship dist/prod-next (npm cannot pack nested node_modules
+ * used by Next standalone).
+ */
+function ensureProdNext() {
+  const nextDir = path.join(packageRoot, ".next")
+  const shipped = path.join(packageRoot, "dist", "prod-next")
+  const hasLocalServer = fs.existsSync(path.join(nextDir, "server"))
+  const hasShippedServer = fs.existsSync(path.join(shipped, "server"))
+
+  if (hasLocalServer) return nextDir
+  if (!hasShippedServer) {
+    throw new Error(`Prebuilt UI not found.
+
+Expected ${shipped} (or a local .next/server from npm run build).
+Reinstall @taskmark/ui or rebuild the package.`)
+  }
+
+  if (fs.existsSync(nextDir)) {
+    const st = fs.lstatSync(nextDir)
+    if (st.isSymbolicLink() || st.isDirectory()) {
+      fs.rmSync(nextDir, { recursive: true, force: true })
+    }
+  }
+
+  try {
+    const type = process.platform === "win32" ? "junction" : "dir"
+    fs.symlinkSync(shipped, nextDir, type)
+  } catch {
+    fs.cpSync(shipped, nextDir, { recursive: true })
+  }
+  return nextDir
+}
+
+function touchDevReloadToken() {
+  const tokenFile = path.join(
+    packageRoot,
+    "lib",
+    "taskmark",
+    "dev-reload-token.ts"
+  )
+  const stamp = String(Date.now())
+  fs.writeFileSync(
+    tokenFile,
+    `/**\n * Touched by \`taskmark dev\` when board markdown changes so Next Fast Refresh\n * re-runs server components that import this module.\n */\nexport const DEV_RELOAD_TOKEN = "${stamp}"\n`,
+    "utf8"
+  )
 }
 
 function openBrowser(url) {
@@ -155,8 +219,8 @@ function waitForServer(port, timeoutMs = 60_000) {
   })
 }
 
-async function serve(args) {
-  const resolved = resolveServeBoard(args.board)
+function resolveBoardOrExit(boardArg, command) {
+  const resolved = resolveServeBoard(boardArg)
   if (!resolved) {
     console.error(`No Taskmark board found.
 
@@ -166,50 +230,126 @@ Looked for:
   - cwd layouts: nested ./taskmark/ or dedicated *-taskmark root
 
 Fix: cd into a product repo (with ./taskmark/) or a board root, or set TASKMARK_BOARD.
-Then re-run: npx taskmark serve
-(or: npx -p @taskmark/ui taskmark serve)`)
+Then re-run: npx taskmark ${command}
+(or: npx -p @taskmark/ui taskmark ${command})`)
     process.exit(1)
   }
+  return resolved
+}
 
-  const serverJs = findStandaloneServer()
-  if (!serverJs) {
-    console.error(`Prebuilt server not found.
+function attachChildLifecycle(child, onShutdown) {
+  const shutdown = (signal) => {
+    onShutdown?.()
+    if (!child.killed) child.kill(signal)
+  }
+  process.on("SIGINT", () => shutdown("SIGINT"))
+  process.on("SIGTERM", () => shutdown("SIGTERM"))
+  child.on("exit", (code, signal) => {
+    onShutdown?.()
+    if (signal) process.exit(1)
+    process.exit(code ?? 0)
+  })
+  return shutdown
+}
 
-From the taskmark package source, run:
-  npm run build
+async function serve(args) {
+  const resolved = resolveBoardOrExit(args.board, "serve")
+  const port = resolvePort(args.port)
+  const url = `http://localhost:${port}`
+  const nextBin = resolveNextBin()
 
-Or install a published build that includes dist/standalone.`)
+  try {
+    ensureProdNext()
+  } catch (err) {
+    console.error(String(err?.message || err))
     process.exit(1)
   }
 
+  console.log(`Taskmark UI`)
+  console.log(`  board:  ${resolved.boardPath} (${resolved.source})`)
+  console.log(`  listen: ${url}`)
+
+  const child = spawn(
+    process.execPath,
+    [nextBin, "start", "-H", "0.0.0.0", "-p", String(port)],
+    {
+      cwd: packageRoot,
+      env: {
+        ...process.env,
+        PORT: String(port),
+        HOSTNAME: "0.0.0.0",
+        TASKMARK_BOARD: resolved.boardPath,
+        NODE_ENV: "production",
+      },
+      stdio: "inherit",
+    }
+  )
+
+  const shutdown = attachChildLifecycle(child)
+
+  const hosted =
+    Boolean(process.env.VERCEL) ||
+    Boolean(process.env.NOW_REGION) ||
+    process.env.CI === "true"
+  const shouldOpen = args.open && !hosted
+
+  try {
+    await waitForServer(port)
+    if (shouldOpen) {
+      openBrowser(url)
+    } else {
+      console.log(`Ready: ${url}`)
+    }
+  } catch (err) {
+    console.error(String(err?.message || err))
+    shutdown("SIGTERM")
+    process.exit(1)
+  }
+}
+
+async function dev(args) {
+  const resolved = resolveBoardOrExit(args.board, "dev")
   const port = resolvePort(args.port)
   const url = `http://localhost:${port}`
-  const standaloneDir = path.dirname(serverJs)
+  const nextBin = resolveNextBin()
 
-  console.log(`Taskmark UI`)
+  console.log(`Taskmark UI (dev)`)
   console.log(`  board:  ${resolved.boardPath} (${resolved.source})`)
   console.log(`  listen: ${url}`)
+  console.log(`  watch:  **/*.md under board`)
 
-  const child = spawn(process.execPath, [serverJs], {
-    cwd: standaloneDir,
-    env: {
-      ...process.env,
-      PORT: String(port),
-      HOSTNAME: "0.0.0.0",
-      TASKMARK_BOARD: resolved.boardPath,
-    },
-    stdio: "inherit",
+  const child = spawn(
+    process.execPath,
+    [nextBin, "dev", "--webpack", "-H", "0.0.0.0", "-p", String(port)],
+    {
+      cwd: packageRoot,
+      env: {
+        ...process.env,
+        PORT: String(port),
+        TASKMARK_BOARD: resolved.boardPath,
+        TASKMARK_CWD: resolved.boardPath,
+        NODE_ENV: "development",
+      },
+      stdio: "inherit",
+    }
+  )
+
+  let debounce = null
+  const stopWatch = watchBoardMarkdown(resolved.boardPath, () => {
+    if (debounce) clearTimeout(debounce)
+    debounce = setTimeout(() => {
+      try {
+        touchDevReloadToken()
+        console.log(`[taskmark] board markdown changed — refreshing`)
+      } catch (err) {
+        console.warn(`[taskmark] reload touch failed: ${err?.message || err}`)
+      }
+    }, 200)
   })
 
-  const shutdown = (signal) => {
-    if (!child.killed) child.kill(signal)
-  }
-  process.on("SIGINT", () => shutdown("SIGINT"))
-  process.on("SIGTERM", () => shutdown("SIGTERM"))
-
-  child.on("exit", (code, signal) => {
-    if (signal) process.exit(1)
-    process.exit(code ?? 0)
+  const shutdown = attachChildLifecycle(child, () => {
+    stopWatch()
+    if (debounce) clearTimeout(debounce)
   })
 
   const hosted =
@@ -219,7 +359,7 @@ Or install a published build that includes dist/standalone.`)
   const shouldOpen = args.open && !hosted
 
   try {
-    await waitForServer(port)
+    await waitForServer(port, 120_000)
     if (shouldOpen) {
       openBrowser(url)
     } else {
@@ -241,19 +381,7 @@ async function preview(args) {
   }
 
   const boardArg = resolveCallerPath(args.board)
-  const resolved = resolveServeBoard(boardArg)
-  if (!resolved) {
-    console.error(`No Taskmark board found.
-
-Looked for:
-  - --board / TASKMARK_BOARD
-  - TASKMARK_MASTER
-  - cwd layouts: nested ./taskmark/ or dedicated *-taskmark root
-
-Fix: cd into a product repo (with ./taskmark/) or a board root, or set TASKMARK_BOARD.
-Then re-run: npx taskmark preview`)
-    process.exit(1)
-  }
+  const resolved = resolveBoardOrExit(boardArg, "preview")
 
   const outDir = args.out
     ? resolveCallerPath(args.out)
@@ -308,6 +436,15 @@ async function main() {
     }
     return
   }
+  if (args.command === "dev") {
+    try {
+      await dev(args)
+    } catch (err) {
+      console.error(String(err?.message || err))
+      process.exit(1)
+    }
+    return
+  }
   if (args.command === "preview") {
     try {
       await preview(args)
@@ -319,14 +456,11 @@ async function main() {
   }
   if (args.command === "build") {
     const buildScript = path.join(packageRoot, "scripts", "build-static.mjs")
-    // Resolve relative paths against the caller's cwd (npm/yarn script dir),
-    // not packageRoot — the child runs with cwd = @taskmark/ui.
     const callerCwd = process.env.INIT_CWD || process.cwd()
     const childArgs = [buildScript]
     if (args.board) {
       childArgs.push("--board", path.resolve(callerCwd, args.board))
     } else {
-      // Prefer the invoke directory as the board when no --board flag.
       childArgs.push("--board", callerCwd)
     }
     if (args.out) {