@taskmark/ui 0.2.4 → 0.2.6

package/README.md

@@ -2,33 +2,65 @@
 
 Install in a Taskmark board folder (or product root with `./taskmark/`) and open the board in the browser.
 
+## Two modes
+
+| Mode | When | Behaviour |
+|------|------|-----------|
+| **Bound** | Board found in/near cwd, or `serve` / `dev` | Opens that one board. No setup wizard, no project picker. |
+| **Workspace** | No local board, or `open` / `--workspace` | Standalone setup wizard + app-bar project picker. |
+
+```bash
+# Global / any folder without a board → setup & pick projects
+npx @taskmark/ui
+# or: npx -p @taskmark/ui taskmark
+
+# Inside a board folder (or product with ./taskmark/) → that board only
+cd my-app-taskmark && npx taskmark
+# or: npm i @taskmark/ui --save && npx taskmark serve
+```
+
+`taskmark open` always forces the setup / picker, even when a board is nearby. Chosen master folders and the active project persist in cookies.
+
 ## Install and serve
 
 ```bash
 # from nested ./taskmark/ or a dedicated *-taskmark board root
 npm install @taskmark/ui --save
-npx taskmark serve
+npx taskmark
+# or: 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
-npx -p @taskmark/ui taskmark serve
+npx @taskmark/ui
+# or: npx -p @taskmark/ui taskmark
 ```
 
 | Option | Meaning |
 |--------|---------|
 | `--port` / `-p` | Listen port (default **8275**; also `PORT` / `TASKMARK_PORT`) |
 | `--board <path>` | Board or product root (sets `TASKMARK_BOARD`) |
+| `--workspace` / `-w` | Force setup / multi-project mode; cannot be combined with `--board` |
 | `--no-open` | Print the URL only |
 
-Board resolution:
+Board resolution (bound mode only):
 
 1. `--board` / `TASKMARK_BOARD`
 2. `TASKMARK_MASTER`
 3. `TASKMARK_CWD` → npm `INIT_CWD` → `process.cwd()` — nested `./taskmark/` or flat `*-taskmark` root
+4. Sibling `<parent>-taskmark` next to a product repo (multi-git workspaces)
 
 ### Nested vs flat boards
 
@@ -49,16 +81,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
 
@@ -77,15 +110,18 @@ 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 build          # next standalone + dist/ for the CLI
+npm run serve          # production standalone against cwd/env board
+npm run dev            # taskmark dev (Next + markdown live reload) on :8275
+npm run dev:workspace  # same, but unbound — work on the setup wizard / picker
+npm run open           # prebuilt UI in workspace mode
 ```
 
-Zero-config for `npm run dev`: `TASKMARK_BOARD` / `TASKMARK_MASTER` / cwd (see above). Cookie multi-master setup still works when unbound.
+`npm run dev` / `serve` always bind to a board (sibling `taskmark-taskmark` from this repo). Bare `node ./bin/taskmark.js` uses the smart default. Use `open` / `dev:workspace` to work on the setup wizard.
 
 ## 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/app/setup/page.tsx

@@ -6,6 +6,7 @@ import { SetupWizard } from "@/components/setup/setup-wizard"
 import { resolveAutoconfigWorkspace } from "@/lib/taskmark/autoconfig"
 import { getMasterFoldersCookie } from "@/lib/taskmark/cookies"
 import { isStaticRuntime } from "@/lib/taskmark/static-mode"
+import { workspaceStartPath } from "@/lib/taskmark/workspace-mode"
 
 type SetupPageProps = {
   searchParams?: Promise<{ mode?: string }>
@@ -26,6 +27,8 @@ export default async function SetupPage({ searchParams }: SetupPageProps) {
   const masters = await getMasterFoldersCookie()
   const hasProjects = masters.length > 0
   const adding = params.mode === "add" && hasProjects
+  // First run: offer the directory `taskmark` was launched from as the master.
+  const suggestedPath = adding || hasProjects ? "" : workspaceStartPath()
 
   return (
     <div className="relative flex min-h-svh flex-col items-center justify-center px-4 py-16">
@@ -50,7 +53,7 @@ export default async function SetupPage({ searchParams }: SetupPageProps) {
           </p>
         </div>
         <SetupWizard
-          initialPath=""
+          initialPath={suggestedPath}
           adding={adding}
           hasExistingProjects={hasProjects}
         />

package/bin/lib/resolve-board.mjs

@@ -48,6 +48,50 @@ export function resolveBoardAtPath(candidatePath) {
   return null
 }
 
+/**
+ * Multi-git layout: product repo beside a dedicated `<common>-taskmark` board.
+ * Prefer `<parentDirBasename>-taskmark`, else a unique `*-taskmark` sibling,
+ * else a sibling whose board prefix matches the product repo name.
+ */
+export function resolveSiblingDedicatedBoard(fromDir) {
+  const resolved = path.resolve(fromDir)
+  const parent = path.dirname(resolved)
+  const parentName = path.basename(parent)
+  const preferred = path.join(parent, `${parentName}-taskmark`)
+  if (
+    isDedicatedBoardRepoName(path.basename(preferred)) &&
+    hasBoardMarkers(preferred)
+  ) {
+    return preferred
+  }
+
+  let entries
+  try {
+    entries = fs.readdirSync(parent, { withFileTypes: true })
+  } catch {
+    return null
+  }
+
+  const boards = []
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !isDedicatedBoardRepoName(entry.name)) continue
+    const full = path.join(parent, entry.name)
+    if (hasBoardMarkers(full)) boards.push(full)
+  }
+  if (boards.length === 0) return null
+  if (boards.length === 1) return boards[0]
+
+  const cwdBase = path.basename(resolved)
+  const parts = cwdBase.split("-").filter(Boolean)
+  for (let i = parts.length - 1; i >= 1; i--) {
+    const prefix = parts.slice(0, i).join("-")
+    const hit = boards.find((b) => path.basename(b) === `${prefix}-taskmark`)
+    if (hit) return hit
+  }
+
+  return null
+}
+
 function cwdCandidates() {
   const out = []
   const seen = new Set()
@@ -74,7 +118,7 @@ function cwdCandidates() {
 
 /**
  * Same precedence as the Next app autoconfig:
- * TASKMARK_BOARD → TASKMARK_MASTER (as board-or-master) → cwd.
+ * TASKMARK_BOARD → TASKMARK_MASTER (as board-or-master) → cwd → sibling *-taskmark.
  * @returns {{ boardPath: string, source: string } | null}
  */
 export function resolveServeBoard(explicitBoard) {
@@ -104,5 +148,10 @@ export function resolveServeBoard(explicitBoard) {
     if (board) return { boardPath: board, source: "cwd" }
   }
 
+  for (const candidate of cwdCandidates()) {
+    const sibling = resolveSiblingDedicatedBoard(candidate)
+    if (sibling) return { boardPath: sibling, source: "sibling" }
+  }
+
   return null
 }

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)
+  }
+}