@taskmark/ui 0.2.5 → 0.3.0

package/README.md

@@ -2,12 +2,47 @@
 
 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
+```
+
+> **`npx taskmark` only works where `@taskmark/ui` is installed.** `taskmark` is the
+> *bin* name, not a package name — an unrelated `taskmark` package exists on npm, and
+> npx will fetch that one instead. Use `npx @taskmark/ui` when running from a folder
+> with no local install, or install the CLI once (see below).
+
+### Install the CLI globally
+
+```bash
+npm install -g @taskmark/ui   # published release
+# from a clone of taskmark-frontend:
+npm run build && npm link      # local build on PATH as `taskmark`
+```
+
+Then `taskmark` works anywhere: setup / project picker outside a board, bound board inside one.
+
+`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.
@@ -24,20 +59,23 @@ Runs Next.js in development on port **8275** and refreshes the UI when board `.m
 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
 
@@ -87,12 +125,14 @@ 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    # production standalone against cwd/env board
-npm run dev      # taskmark dev (Next + markdown live reload) on :8275
+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` / `serve`: `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
 

package/app/board/page.tsx

@@ -1,49 +1,7 @@
-import { Suspense } from "react"
-import Link from "next/link"
-import { redirect } from "next/navigation"
-
-import { AppBar } from "@/components/board/app-bar"
-import { EpicList } from "@/components/board/epic-list"
-import { ListViewSwitcher } from "@/components/board/list-view-switcher"
-import { OverallWorkItemsList } from "@/components/board/overall-work-items-list"
-import { ProjectStatusMetricsStrip } from "@/components/board/project-status-metrics-strip"
-import { StaticBoardApp } from "@/components/board/static-board-app"
-import { TaskList } from "@/components/board/task-list"
-import { WorkItemsList } from "@/components/board/work-items-list"
-import { WorkItemSheetProvider } from "@/components/board/work-item-sheet"
-import { resolveActiveProject } from "@/lib/taskmark/active-project"
-import {
-  getActiveProjectCookie,
-  getHideCompletedCookies,
-  getMasterFoldersCookie,
-} from "@/lib/taskmark/cookies"
-import {
-  LIST_VIEW_LABELS,
-  boardHref,
-  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 {
-  parseWorkItemsForEpic,
-  parseWorkItemsViewForProject,
-} from "@/lib/taskmark/parse-flat-lists"
-import { parseItemsForStory } from "@/lib/taskmark/parse-items"
-import {
-  collectCompletedLeafPointSamples,
-  collectMetricLeaves,
-  computeProjectStatusMetrics,
-} from "@/lib/taskmark/project-metrics"
-import { isStaticRuntime } from "@/lib/taskmark/static-mode"
-import { loadWorkspace } from "@/lib/taskmark/workspace"
+import { BoardScreen } from "@/components/board/board-screen"
 
 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[]
@@ -53,234 +11,7 @@ type BoardPageProps = {
   }>
 }
 
-function paramValue(value: string | string[] | undefined): string | null {
-  if (typeof value === "string" && value.trim()) return value.trim()
-  return null
-}
-
-function headingForView(view: ListViewMode): string {
-  if (view === "overall") return "Epics"
-  return LIST_VIEW_LABELS[view]
-}
-
+/** Alias of `/` — kept so older links and bookmarks keep working. */
 export default async function BoardPage({ searchParams }: BoardPageProps) {
-  if (isStaticRuntime()) {
-    const snapshot = loadSnapshotFromPublic()
-    return (
-      <Suspense fallback={<div className="p-8 text-sm text-muted-foreground">Loading board…</div>}>
-        <StaticBoardApp snapshot={snapshot} />
-      </Suspense>
-    )
-  }
-
-  const masters = await getMasterFoldersCookie()
-  const workspace = loadWorkspace(masters)
-  if (workspace.projects.length === 0) {
-    redirect("/setup")
-  }
-
-  const savedActiveId = await getActiveProjectCookie()
-  const hideCompletedPrefs = await getHideCompletedCookies()
-  const activeProject = resolveActiveProject(
-    workspace.projects,
-    // Autoconfig: prefer the bound board; ignore stale active-project cookies.
-    workspace.autoconfig ? null : savedActiveId
-  )
-  if (!activeProject) {
-    redirect("/setup")
-  }
-
-  const params = await searchParams
-  const activeView = parseListViewMode(params.view)
-  const selectedEpicId =
-    activeView === "overall" ? paramValue(params.epic) : null
-  const selectedStoryId =
-    activeView === "overall" && selectedEpicId
-      ? paramValue(params.story)
-      : null
-  const selectedItemId = paramValue(params.item)
-
-  const list = parseEpicsForProject(activeProject)
-  const epicCount = list.epics.length
-  const errorCount = list.errors.length
-
-  const selectedEpic = selectedEpicId
-    ? list.epics.find((e) => e.id === selectedEpicId) ?? null
-    : null
-
-  const epicWorkItems =
-    activeView === "overall" && selectedEpicId != null
-      ? parseWorkItemsForEpic(
-          activeProject,
-          selectedEpicId,
-          selectedEpic?.title ?? null
-        )
-      : null
-
-  const selectedStory =
-    epicWorkItems && selectedStoryId
-      ? (epicWorkItems.rows.find(
-          (row) => row.kind === "story" && row.id === selectedStoryId
-        ) ?? null)
-      : null
-
-  const itemList =
-    activeView === "overall" &&
-    selectedEpicId != null &&
-    selectedStory != null
-      ? parseItemsForStory(activeProject, selectedEpicId, selectedStory.id)
-      : null
-
-  const workItemsList =
-    activeView === "overall" || activeView === "workitems"
-      ? parseWorkItemsViewForProject(activeProject)
-      : null
-
-  /** Match Current Speed exactly: completed task/bug leaf points only. */
-  const countableCompletions = collectCompletedLeafPointSamples(
-    collectMetricLeaves(activeProject)
-  )
-
-  const statusMetrics = computeProjectStatusMetrics(activeProject)
-
-  return (
-    <WorkItemSheetProvider>
-      <div className="min-h-svh bg-[linear-gradient(180deg,_#fff_0%,_#f7f4ff_100%)]">
-        <AppBar
-          projects={workspace.projects}
-          activeProjectId={activeProject.id}
-          autoconfig={workspace.autoconfig}
-        />
-
-        <div className="mx-auto flex w-full max-w-5xl flex-col gap-6 px-4 py-8">
-          <div className="flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between">
-            <div>
-              <h1 className="font-head text-3xl tracking-tight">
-                {headingForView(activeView)}
-              </h1>
-              <p className="mt-1 text-sm text-muted-foreground">
-                {activeProject.name}
-                {activeView === "overall"
-                  ? ` · ${epicCount} epic${epicCount === 1 ? "" : "s"}`
-                  : ""}
-                {activeView === "overall" && errorCount > 0
-                  ? ` · ${errorCount} parse issue${errorCount === 1 ? "" : "s"}`
-                  : ""}
-                {activeView === "workitems" && workItemsList
-                  ? ` · ${workItemsList.rows.length} item${workItemsList.rows.length === 1 ? "" : "s"}`
-                  : ""}
-                {activeView === "overall" && selectedEpic
-                  ? ` · selected ${selectedEpic.id}`
-                  : activeView === "overall" && selectedEpicId
-                    ? ` · epic ${selectedEpicId} not in list`
-                    : activeView === "overall"
-                      ? " · select an epic to view work items"
-                      : ""}
-                {activeView === "overall" && selectedStory
-                  ? ` · story ${selectedStory.id}`
-                  : activeView === "overall" && selectedStoryId
-                    ? ` · story ${selectedStoryId} not in list`
-                    : ""}
-              </p>
-            </div>
-            <ListViewSwitcher
-              activeView={activeView}
-              selectedEpicId={selectedEpicId}
-              selectedStoryId={selectedStory?.id ?? null}
-            />
-          </div>
-
-          <ProjectStatusMetricsStrip metrics={statusMetrics} />
-
-          {activeView === "overall" ? (
-            <>
-              <EpicList
-                lists={[list]}
-                selectedEpicId={selectedEpicId}
-                countableCompletions={countableCompletions}
-                initialHideCompleted={hideCompletedPrefs.epics}
-              />
-
-              {epicWorkItems ? (
-                <div className="flex flex-col gap-3">
-                  <div className="flex items-baseline justify-between gap-3">
-                    <h2 className="font-head text-2xl tracking-tight">
-                      Work items for{" "}
-                      {epicWorkItems.epicTitle ?? epicWorkItems.epicId}
-                    </h2>
-                    <Link
-                      href={boardHref({
-                        view: "overall",
-                        item: selectedItemId,
-                      })}
-                      className="text-sm text-muted-foreground underline-offset-2 hover:underline"
-                    >
-                      Clear selection
-                    </Link>
-                  </div>
-                  <p className="text-sm text-muted-foreground">
-                    {epicWorkItems.rows.length} work item
-                    {epicWorkItems.rows.length === 1 ? "" : "s"}
-                    {epicWorkItems.errors.length > 0
-                      ? ` · ${epicWorkItems.errors.length} issue${epicWorkItems.errors.length === 1 ? "" : "s"}`
-                      : ""}
-                    {!selectedStory
-                      ? " · select a story to view its sub tasks"
-                      : ""}
-                  </p>
-                  <OverallWorkItemsList
-                    list={epicWorkItems}
-                    selectedStoryId={selectedStory?.id ?? null}
-                    countableCompletions={countableCompletions}
-                    initialHideCompleted={hideCompletedPrefs.overallWorkItems}
-                  />
-                </div>
-              ) : null}
-
-              {itemList && selectedStory ? (
-                <div className="flex flex-col gap-3">
-                  <div className="flex items-baseline justify-between gap-3">
-                    <h2 className="font-head text-2xl tracking-tight">
-                      Sub Tasks for{" "}
-                      {itemList.storyTitle ?? itemList.storyId}
-                    </h2>
-                    <Link
-                      href={boardHref({
-                        view: "overall",
-                        epic: itemList.epicId,
-                        item: selectedItemId,
-                      })}
-                      className="text-sm text-muted-foreground underline-offset-2 hover:underline"
-                    >
-                      Clear story
-                    </Link>
-                  </div>
-                  <p className="text-sm text-muted-foreground">
-                    {itemList.items.length} sub task
-                    {itemList.items.length === 1 ? "" : "s"}
-                    {itemList.errors.length > 0
-                      ? ` · ${itemList.errors.length} issue${itemList.errors.length === 1 ? "" : "s"}`
-                      : ""}
-                  </p>
-                  <TaskList
-                    list={itemList}
-                    countableCompletions={countableCompletions}
-                    initialHideCompleted={hideCompletedPrefs.tasks}
-                  />
-                </div>
-              ) : null}
-            </>
-          ) : null}
-
-          {activeView === "workitems" && workItemsList ? (
-            <WorkItemsList
-              list={workItemsList}
-              countableCompletions={countableCompletions}
-              initialHideCompleted={hideCompletedPrefs.workItems}
-            />
-          ) : null}
-        </div>
-      </div>
-    </WorkItemSheetProvider>
-  )
+  return <BoardScreen searchParams={searchParams} />
 }

package/app/page.tsx

@@ -1,17 +1,17 @@
-import { redirect } from "next/navigation"
+import { BoardScreen } from "@/components/board/board-screen"
 
-import { getMasterFoldersCookie } from "@/lib/taskmark/cookies"
-import { isStaticRuntime } from "@/lib/taskmark/static-mode"
-import { loadWorkspace } from "@/lib/taskmark/workspace"
+export const dynamic = "force-dynamic"
 
-export default async function HomePage() {
-  if (isStaticRuntime()) {
-    redirect("/board")
-  }
-  const masters = await getMasterFoldersCookie()
-  const workspace = loadWorkspace(masters)
-  if (workspace.projects.length > 0) {
-    redirect("/board")
-  }
-  redirect("/setup")
+type HomePageProps = {
+  searchParams: Promise<{
+    view?: string | string[]
+    epic?: string | string[]
+    story?: string | string[]
+    item?: string | string[]
+  }>
+}
+
+/** The board is the default view; BoardScreen sends unbound setups to /setup. */
+export default async function HomePage({ searchParams }: HomePageProps) {
+  return <BoardScreen searchParams={searchParams} />
 }

package/app/setup/actions.ts

@@ -64,7 +64,7 @@ export async function saveMasterFolder(
     await setActiveProjectCookie(preferred.id)
   }
 
-  redirect("/board")
+  redirect("/")
 }
 
 export type PickMasterFolderState = {
@@ -89,7 +89,7 @@ export async function openAddProject(): Promise<void> {
     "@/lib/taskmark/autoconfig"
   )
   if (resolveAutoconfigWorkspace()?.projects.length) {
-    redirect("/board")
+    redirect("/")
   }
   redirect("/setup?mode=add")
 }
@@ -100,8 +100,8 @@ export async function selectActiveProject(formData: FormData): Promise<void> {
     return
   }
   await setActiveProjectCookie(projectId)
-  revalidatePath("/board")
-  redirect("/board")
+  revalidatePath("/")
+  redirect("/")
 }
 
 /** Optional: clear everything and start over (not shown in app bar by default). */

package/app/setup/page.tsx

@@ -6,26 +6,34 @@ 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 }>
 }
 
+// Depends on runtime env (workspace vs bound) and cookies — never prerender in
+// server mode, or a build-time redirect gets baked in and loops against `/`.
+// The static build rewrites this to force-static (see scripts/build-static.mjs).
+export const dynamic = "force-dynamic"
+
 export default async function SetupPage({ searchParams }: SetupPageProps) {
   if (isStaticRuntime()) {
-    redirect("/board")
+    redirect("/")
   }
 
   const auto = resolveAutoconfigWorkspace()
   if (auto && auto.projects.length > 0) {
     // Zero-config bind — setup wizard is not needed.
-    redirect("/board")
+    redirect("/")
   }
 
   const params = searchParams ? await searchParams : {}
   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,13 +58,13 @@ export default async function SetupPage({ searchParams }: SetupPageProps) {
           </p>
         </div>
         <SetupWizard
-          initialPath=""
+          initialPath={suggestedPath}
           adding={adding}
           hasExistingProjects={hasProjects}
         />
         {adding ? (
           <p className="text-sm text-muted-foreground">
-            <Link href="/board" className="underline underline-offset-2">
+            <Link href="/" className="underline underline-offset-2">
               Cancel and return to board
             </Link>
           </p>

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
 }