npm - @nickmeriano/task - Versions diffs - 0.10.0 → 0.12.0 - Mend

@nickmeriano/task 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (101) hide show

package/README.md +232 -1
package/dist/asks.test.js +6 -0
package/dist/asks.test.js.map +1 -1
package/dist/board/github.d.ts +68 -0
package/dist/board/github.d.ts.map +1 -0
package/dist/board/github.js +112 -0
package/dist/board/github.js.map +1 -0
package/dist/board/handler.d.ts +50 -0
package/dist/board/handler.d.ts.map +1 -0
package/dist/board/handler.js +183 -0
package/dist/board/handler.js.map +1 -0
package/dist/board/handler.test.d.ts +11 -0
package/dist/board/handler.test.d.ts.map +1 -0
package/dist/board/handler.test.js +229 -0
package/dist/board/handler.test.js.map +1 -0
package/dist/board/pages-function.d.ts +23 -0
package/dist/board/pages-function.d.ts.map +1 -0
package/dist/board/pages-function.js +34 -0
package/dist/board/pages-function.js.map +1 -0
package/dist/board/source.d.ts +118 -0
package/dist/board/source.d.ts.map +1 -0
package/dist/board/source.js +333 -0
package/dist/board/source.js.map +1 -0
package/dist/board/source.test.d.ts +12 -0
package/dist/board/source.test.d.ts.map +1 -0
package/dist/board/source.test.js +165 -0
package/dist/board/source.test.js.map +1 -0
package/dist/board/tar.d.ts +28 -0
package/dist/board/tar.d.ts.map +1 -0
package/dist/board/tar.js +188 -0
package/dist/board/tar.js.map +1 -0
package/dist/board/tar.test.d.ts +9 -0
package/dist/board/tar.test.d.ts.map +1 -0
package/dist/board/tar.test.js +110 -0
package/dist/board/tar.test.js.map +1 -0
package/dist/claim-io.d.ts.map +1 -1
package/dist/claim-io.js +4 -3
package/dist/claim-io.js.map +1 -1
package/dist/claim.d.ts +14 -2
package/dist/claim.d.ts.map +1 -1
package/dist/claim.js +9 -3
package/dist/claim.js.map +1 -1
package/dist/claim.test.js +41 -1
package/dist/claim.test.js.map +1 -1
package/dist/cli.js +127 -7
package/dist/cli.js.map +1 -1
package/dist/export.d.ts +163 -0
package/dist/export.d.ts.map +1 -0
package/dist/export.js +259 -0
package/dist/export.js.map +1 -0
package/dist/export.test.d.ts +12 -0
package/dist/export.test.d.ts.map +1 -0
package/dist/export.test.js +264 -0
package/dist/export.test.js.map +1 -0
package/dist/functions/board.js +709 -0
package/dist/git-serve.d.ts +14 -1
package/dist/git-serve.d.ts.map +1 -1
package/dist/git-serve.js +30 -2
package/dist/git-serve.js.map +1 -1
package/dist/git-serve.test.d.ts +1 -0
package/dist/git-serve.test.d.ts.map +1 -1
package/dist/git-serve.test.js +36 -1
package/dist/git-serve.test.js.map +1 -1
package/dist/index.d.ts +2 -0
package/dist/index.d.ts.map +1 -1
package/dist/index.js +6 -0
package/dist/index.js.map +1 -1
package/dist/server.d.ts +6 -0
package/dist/server.d.ts.map +1 -1
package/dist/server.js +12 -3
package/dist/server.js.map +1 -1
package/dist/trailers.d.ts +51 -0
package/dist/trailers.d.ts.map +1 -0
package/dist/trailers.js +32 -0
package/dist/trailers.js.map +1 -0
package/package.json +3 -3
package/skill/SKILL.md +16 -1
package/src/asks.test.ts +15 -0
package/src/board/github.ts +151 -0
package/src/board/handler.test.ts +276 -0
package/src/board/handler.ts +228 -0
package/src/board/pages-function.ts +42 -0
package/src/board/source.test.ts +203 -0
package/src/board/source.ts +422 -0
package/src/board/tar.test.ts +128 -0
package/src/board/tar.ts +199 -0
package/src/claim-io.ts +12 -3
package/src/claim.test.ts +56 -1
package/src/claim.ts +27 -4
package/src/cli.ts +127 -7
package/src/export.test.ts +361 -0
package/src/export.ts +354 -0
package/src/git-serve.test.ts +41 -1
package/src/git-serve.ts +30 -2
package/src/index.ts +10 -0
package/src/server.ts +12 -3
package/src/trailers.ts +65 -0
package/ui/dist/assets/index-B8M_DaOt.js +229 -0
package/ui/dist/assets/{index-CoKCUYic.css → index-eHsqltgs.css} +1 -1
package/ui/dist/index.html +3 -3
package/ui/dist/assets/index-BjsorZOU.js +0 -229

package/src/export.ts ADDED Viewed

@@ -0,0 +1,354 @@
+/**
+ * `task export` — the board as a directory of files.
+ *
+ * The third deployment of this app (after `task serve` and the hosted board)
+ * is a static host: the same prebuilt UI the package already ships for serve,
+ * plus a `snapshot.json` this module writes out of the local `.task/`. There
+ * is no server behind it, so the app reads its answers out of that file —
+ * `ui/src/snapshot.ts` is the reader, and this is the writer.
+ *
+ * The whole correctness question is one sentence: **the snapshot must answer
+ * what `routeApi` answers**. Every field below is sourced from the same store
+ * call the matching `/api/…` route makes, so a board rendered from a file and
+ * a board rendered from the server differ only in how stale they are.
+ *
+ * Split in two on purpose: `buildSnapshot` is the shape (no writes, so it is
+ * testable without a built UI, and the UI's own test can round-trip it through
+ * `parseSnapshot`), `writeExport` is the directory.
+ */
+import { execFileSync } from "node:child_process"
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { resolveAuthor } from "./author.ts"
+import { REPO_PATTERN } from "./board/handler.ts"
+import { openBoard } from "./file-store.ts"
+import { findBoards } from "./store.ts"
+import { STATUSES, type Comment, type Goal, type Status, type Task } from "./types.ts"
+/**
+ * The version the reader accepts, restated from `ui/src/snapshot.ts`. The UI
+ * is built separately from this NodeNext package, so the contract is mirrored
+ * rather than cross-imported — the same precedent `ui/src/api.ts` sets for
+ * `types.ts`. `ui/src/deployment.test.ts` imports `buildSnapshot` and feeds
+ * the result to the real `parseSnapshot`, which is what keeps the two honest.
+ */
+export const SNAPSHOT_VERSION = 2
+/** The file's name in the output directory, matching `SNAPSHOT_PATH`. */
+export const SNAPSHOT_FILE = "snapshot.json"
+/** Where an export goes when `--out` doesn't say. */
+export const DEFAULT_OUT_DIR = "task-export"
+/**
+ * The live-proxy function, bundled by `vite.functions.config.ts` into one
+ * dependency-free file. Resolved from this module the way `UI_DIR` is: the
+ * same relative path works from `src/` (run from source) and from `dist/`.
+ */
+export const FUNCTION_BUNDLE = fileURLToPath(new URL("../dist/functions/board.js", import.meta.url))
+/** The sentence for a missing bundle, in the shape `NO_UI_BUILD` sets. */
+const NO_FUNCTION_BUILD =
+  "function bundle not found — run the package build (vite build -c vite.functions.config.ts)."
+/** The sentence `serveStatic` prints for the same missing directory. */
+const NO_UI_BUILD = "UI build not found — run the package build (vite build ui)."
+/**
+ * The assets are built with relative refs (`base: "./"` in ui/vite.config.ts)
+ * because one build ships three ways and can't know where it will live. The
+ * `<base href>` each deployment stamps into index.html is what completes them:
+ * the browser resolves `./assets/…` — and the app resolves its routes, API and
+ * snapshot fetch — against it instead of the page's own URL, which is what
+ * keeps deep links working under any mount point.
+ */
+/** `board` / `/board` / `board/` → `/board/`; `""` and `/` → `/`. */
+export function normalizeBase(base: string): string {
+  let path = base.trim()
+  if (path === "" || path === "/") return "/"
+  if (!path.startsWith("/")) path = `/${path}`
+  if (!path.endsWith("/")) path = `${path}/`
+  if (path.includes("//") || /[\s<>"']/.test(path)) {
+    throw new Error(`--base must be a plain URL path like /board/ — got ${JSON.stringify(base)}`)
+  }
+  return path
+}
+/**
+ * Stamp the deployment's mount point into the built page. The built
+ * index.html always has exactly one `<head>` for this to anchor on; refusing
+ * a page without one beats silently shipping a board that 404s its assets.
+ */
+export function injectBase(html: string, base: string): string {
+  if (!html.includes("<head>")) {
+    throw new Error("index.html has no <head> to carry the <base> tag — is this the built UI?")
+  }
+  return html.replace("<head>", `<head><base href="${normalizeBase(base)}" />`)
+}
+export interface SnapshotMeta {
+  /** The commit exported from (`git rev-parse HEAD`), or null outside a repo. */
+  commit: string | null
+  /** When the export ran, ISO-8601 — the other half of the staleness banner. */
+  builtAt: string
+}
+/** What `/api/boards` answers, per board. */
+export interface SnapshotBoardInfo {
+  id: string
+  name: string
+  prefix: string
+}
+/** What `/api/project` answers. `readOnly` is the reader's call, not ours. */
+export interface SnapshotProject {
+  name: string
+  prefix: string
+  statuses: readonly Status[]
+  author: string
+}
+/** One board's baked answers, in the shapes the serve API returns. */
+export interface SnapshotBoard {
+  project: SnapshotProject
+  tasks: Task[]
+  goals: Goal[]
+  /** Task key to its comments, oldest first; absent means none. */
+  comments: Record<string, Comment[]>
+}
+export interface Snapshot {
+  version: number
+  meta: SnapshotMeta
+  boards: SnapshotBoardInfo[]
+  data: Record<string, SnapshotBoard>
+}
+export interface BuildSnapshotOptions {
+  /** Overridable so tests get a fixed build time. */
+  builtAt?: string
+}
+/**
+ * The commit this export is of.
+ *
+ * Every way this can fail — git not installed, not a repository, a repo with
+ * no commits yet — is the same non-answer, so they all collapse to null. The
+ * reader's type already says `string | null` and its banner degrades to
+ * "snapshot, built …", which is the honest thing to show.
+ */
+export function exportedCommit(cwd: string): string | null {
+  try {
+    const out = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 2000,
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+    return out.trim() || null
+  } catch {
+    return null
+  }
+}
+/**
+ * Bake every board at or below `serveRoot` into one snapshot.
+ *
+ * Anchoring matches `cmdServe` exactly (`findRoot` ?? cwd, then `findBoards`),
+ * so "export what serve would serve" is true by construction — one board in a
+ * package, every nested board at a monorepo root, `.` first either way.
+ */
+export function buildSnapshot(serveRoot: string, options: BuildSnapshotOptions = {}): Snapshot {
+  const refs = findBoards(serveRoot)
+  if (refs.length === 0) {
+    throw new Error(
+      `no .task directory found at or below ${serveRoot} — run \`task init\` first`,
+    )
+  }
+  // Resolved once, server-side, exactly as `createTaskServer` does it: all the
+  // boards live in one checkout, so one resolution covers them.
+  const author = resolveAuthor(undefined, serveRoot).name
+  const boards: SnapshotBoardInfo[] = []
+  const data: Record<string, SnapshotBoard> = {}
+  for (const ref of refs) {
+    const store = openBoard(ref.root)
+    try {
+      boards.push({ id: ref.id, name: store.config.name, prefix: store.config.prefix })
+      const counts = store.commentCounts()
+      const tasks = store.list().map((task) => ({
+        ...task,
+        commentCount: counts.get(task.key) ?? 0,
+      }))
+      const comments: Record<string, Comment[]> = {}
+      for (const task of tasks) {
+        const list = store.comments(task.key)
+        // Omitted rather than empty: the reader defaults a missing key to [],
+        // and a snapshot is a file people open.
+        if (list.length > 0) comments[task.key] = list
+      }
+      data[ref.id] = {
+        project: { name: store.config.name, prefix: store.config.prefix, statuses: STATUSES, author },
+        tasks,
+        // Archived goals ride along flagged, as `/api/goals` sends them, so an
+        // old chip on a task can still resolve a title.
+        goals: [...store.goals(), ...store.goals(true)],
+        comments,
+      }
+    } finally {
+      store.close()
+    }
+  }
+  return {
+    version: SNAPSHOT_VERSION,
+    meta: {
+      commit: exportedCommit(serveRoot),
+      builtAt: options.builtAt ?? new Date().toISOString(),
+    },
+    boards,
+    data,
+  }
+}
+export interface WriteExportOptions {
+  serveRoot: string
+  outDir: string
+  /** The built SPA to copy. Injectable so tests never need a vite build. */
+  uiDir: string
+  /** Write into a directory that isn't a previous export. Never deletes. */
+  force?: boolean
+  /** URL path the export will be served under (default `/`) — see `injectBase`. */
+  base?: string
+  builtAt?: string
+  /**
+   * Also write the live-proxy function — `renderFunction` at `functionPath`.
+   * `repo` is the
+   * GitHub repository it will read, `owner/name`; `bundle` is the built
+   * function to copy, injectable so tests never need a vite build.
+   */
+  functions?: { repo: string; bundle?: string }
+}
+export interface ExportSummary {
+  outDir: string
+  base: string
+  boards: number
+  tasks: number
+  commit: string | null
+  builtAt: string
+  /** Path of the function written, relative to `outDir`; null when none was. */
+  functions: string | null
+}
+/**
+ * Where a Cloudflare Pages Function has to sit to answer `<base>api/*`: the
+ * `functions/` tree mirrors URL paths, and `[[path]]` is Pages' catch-all.
+ */
+export function functionPath(base: string): string {
+  const mount = normalizeBase(base).slice(1) // "" or "board/"
+  return join("functions", ...mount.split("/").filter(Boolean), "api", "[[path]].js")
+}
+/**
+ * The bundled function, with the two things that are per-deploy filled in.
+ *
+ * Both replacements are validated first because they land inside string
+ * literals in a file that gets executed: `REPO_PATTERN` admits no quote, and
+ * `normalizeBase` refuses one.
+ */
+export function renderFunction(bundle: string, repo: string, base: string): string {
+  if (!REPO_PATTERN.test(repo)) {
+    throw new Error(`--repo must be owner/name — got ${JSON.stringify(repo)}`)
+  }
+  const basePath = `${normalizeBase(base)}api`
+  for (const placeholder of ["__TASK_EXPORT_REPO__", "__TASK_EXPORT_BASE_PATH__"]) {
+    if (!bundle.includes(placeholder)) {
+      throw new Error(`function bundle has no ${placeholder} to fill — is this the built function?`)
+    }
+  }
+  return bundle
+    .replace("__TASK_EXPORT_REPO__", repo)
+    .replace("__TASK_EXPORT_BASE_PATH__", basePath)
+}
+/**
+ * Write the assets and the snapshot into `outDir`.
+ *
+ * Refresh is the interesting case. Re-exporting over a previous export
+ * replaces the UI's own entries and `snapshot.json` and leaves everything else
+ * alone — notably a `functions/` directory, so a deployed live-proxy function
+ * survives a re-export. Anything else in a non-empty directory is refused
+ * rather than overwritten: `--out .` against a repo is the one genuinely
+ * destructive mistake available here.
+ */
+export function writeExport(options: WriteExportOptions): ExportSummary {
+  const { serveRoot, outDir, uiDir, force = false } = options
+  const base = normalizeBase(options.base ?? "/")
+  if (!existsSync(uiDir)) throw new Error(NO_UI_BUILD)
+  // Exporting onto the assets it copies from would clear them first and then
+  // copy an empty directory — the one way this can destroy the package itself.
+  if (resolve(outDir) === resolve(uiDir)) {
+    throw new Error(`${outDir} is the UI build itself — export somewhere else`)
+  }
+  const snapshot = buildSnapshot(serveRoot, { builtAt: options.builtAt })
+  // Rendered before anything is written, so a bad --repo or a missing bundle
+  // fails the export rather than leaving half of one behind.
+  const functions = options.functions
+    ? {
+        path: functionPath(base),
+        source: renderFunction(
+          readFunctionBundle(options.functions.bundle ?? FUNCTION_BUNDLE),
+          options.functions.repo,
+          base,
+        ),
+      }
+    : null
+  const existing = existsSync(outDir) ? readdirSync(outDir) : null
+  if (existing && existing.length > 0 && !existing.includes(SNAPSHOT_FILE) && !force) {
+    throw new Error(
+      `${outDir} is not empty and isn't a previous export — pass --force to write into it anyway`,
+    )
+  }
+  mkdirSync(outDir, { recursive: true })
+  // Clear only what this export is about to write: a stale `assets/` full of
+  // last build's hashed bundles is dead weight, and everything else in there
+  // belongs to whoever put it there.
+  for (const entry of readdirSync(uiDir)) {
+    rmSync(join(outDir, entry), { recursive: true, force: true })
+  }
+  cpSync(uiDir, outDir, { recursive: true })
+  const indexPath = join(outDir, "index.html")
+  writeFileSync(indexPath, injectBase(readFileSync(indexPath, "utf8"), base))
+  // Pretty-printed: this lands in CI artifacts and gets diffed, and at this
+  // size the whitespace costs nothing.
+  writeFileSync(join(outDir, SNAPSHOT_FILE), `${JSON.stringify(snapshot, null, 2)}\n`)
+  // The function is the one thing under `functions/` this export owns; the
+  // rest of that directory is whoever's it was. Without `functions`, a
+  // function from an earlier export stays exactly as deployed.
+  if (functions) {
+    mkdirSync(dirname(join(outDir, functions.path)), { recursive: true })
+    writeFileSync(join(outDir, functions.path), functions.source)
+  }
+  return {
+    outDir,
+    base,
+    boards: snapshot.boards.length,
+    tasks: Object.values(snapshot.data).reduce((n, board) => n + board.tasks.length, 0),
+    commit: snapshot.meta.commit,
+    builtAt: snapshot.meta.builtAt,
+    functions: functions?.path ?? null,
+  }
+}
+function readFunctionBundle(path: string): string {
+  if (!existsSync(path)) throw new Error(NO_FUNCTION_BUILD)
+  return readFileSync(path, "utf8")
+}

package/src/git-serve.test.ts CHANGED Viewed

@@ -11,11 +11,12 @@
  *    runs; the board's own origin and origin-less clients pass.
  * 4. Degradation: a repo with no origin advertises no `git` capability and
  *    404s the whole route group — the self-hiding rule the UI builds on.
+ * 5. A board reached through a symlinked path is still a board (TAS-qn8td).
  */
 import assert from "node:assert/strict"
 import { after, test } from "node:test"
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs"
+import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { spawnSync } from "node:child_process"
@@ -232,6 +233,45 @@ test("a plain directory (no git at all) behaves the same", async () => {
   assert.equal("git" in project.body, false)
 })
+test("a repo reached through a symlink still finds its boards", async () => {
+  // `git rev-parse --show-toplevel` resolves symlinks and a Store's taskDir
+  // does not, so comparing them unresolved drops every board — commit 400s and
+  // status calls board files `otherDirty`, quietly. The symlink is explicit
+  // here rather than inherited from tmpdir(): on macOS /var/folders is already
+  // one (which is how this was found), on Linux it is not, and the property
+  // has to hold on both.
+  const home = tempDir()
+  const real = join(home, "real")
+  mkdirSync(real)
+  const bare = join(real, "origin.git")
+  sh(real, "git", "init", "--quiet", "--bare", "-b", "main", bare)
+  sh(real, "git", "clone", "--quiet", bare, join(real, "clone"))
+  const link = join(home, "link")
+  symlinkSync(real, link)
+  const clone = join(link, "clone")
+  sh(clone, "git", "config", "user.name", "Test")
+  sh(clone, "git", "config", "user.email", "test@example.com")
+  const store = initProject(clone, { name: "linked", prefix: "LNK" })
+  const first = store.create({ title: "First", status: "todo" }).key
+  sh(clone, "git", "add", "-A")
+  sh(clone, "git", "commit", "--quiet", "-m", "board")
+  sh(clone, "git", "push", "--quiet", "-u", "origin", "main")
+  const base = await serve(clone)
+  await call(base, `/api/tasks/${first}`, Object.assign(post({ status: "in_progress" }), { method: "PATCH" }))
+  const status = await call(base, "/api/git/status")
+  assert.equal(status.status, 200)
+  const dirty = status.body.dirty as { path: string }[]
+  assert.ok(dirty.length > 0, `board edits must read as board dirt: ${JSON.stringify(status.body)}`)
+  assert.ok(dirty.every((f) => f.path.startsWith(".task/")))
+  assert.equal(status.body.otherDirty, 0, "and must not be counted as other people's mess")
+  const commit = await call(base, "/api/git/commit", post({ message: "chore(board): through a link" }))
+  assert.equal(commit.status, 200, JSON.stringify(commit.body))
+})
 test("the gh-less PR fallback is the exact GitHub compare URL, branches escaped", () => {
   assert.equal(
     compareUrl({ owner: "nicmeriano", repo: "nickmeriano.com" }, "main", "board/2026-09-01"),

package/src/git-serve.ts CHANGED Viewed

@@ -19,6 +19,7 @@
  */
 import { spawnSync } from "node:child_process"
+import { realpathSync } from "node:fs"
 import { relative, sep } from "node:path"
 import { claimBranch, claimNamespace, release } from "./claim.ts"
 import { remoteClaimTips, syncClaimRefs } from "./claim-io.ts"
@@ -31,6 +32,19 @@ export interface ServedBoard {
   store: Store
 }
+/**
+ * A path with its symlinks resolved, or the path itself when it cannot be —
+ * a board directory that does not exist on disk yet makes `realpathSync`
+ * throw ENOENT, and that is not a reason to lose the board.
+ */
+function realPath(path: string): string {
+  try {
+    return realpathSync(path)
+  } catch {
+    return path
+  }
+}
 /** A failure the route turns into a JSON error with this status. */
 export class GitServeError extends Error {
   readonly status: number
@@ -194,11 +208,25 @@ export class GitServe {
     return records
   }
-  /** Each board's `.task` dir as a toplevel-relative posix pathspec. */
+  /**
+   * Each board's `.task` dir as a toplevel-relative posix pathspec.
+   *
+   * Both sides are resolved through {@link realPath} before they are
+   * compared. `git rev-parse --show-toplevel` already returns a symlink-free
+   * path, while a store's `taskDir` is built from whatever path the process
+   * was given — so on a checkout reached through a symlink the two disagree,
+   * `relative()` answers `../../…`, and the guard below silently drops every
+   * board. That is not a corner case on macOS, where `os.tmpdir()` is
+   * `/var/folders/…` → `/private/var/folders/…`; it is also any repo under a
+   * symlinked parent. Dropping every board turns `commit` into a 400 and,
+   * worse, makes `status` report board files as `otherDirty` with an empty
+   * `dirty` list — a board that looks clean while `.task/` is full of edits.
+   */
   private boardDirs(top: string): Map<string, string> {
+    const root = realPath(top)
     const dirs = new Map<string, string>()
     for (const { id, store } of this.boards()) {
-      const rel = relative(top, store.taskDir).split(sep).join("/")
+      const rel = relative(root, realPath(store.taskDir)).split(sep).join("/")
       if (rel === "" || rel.startsWith("..")) continue
       dirs.set(id, rel)
     }

package/src/index.ts CHANGED Viewed

@@ -42,5 +42,15 @@ export {
   type ReleaseResult,
 } from "./claim.ts"
 export { createTaskServer } from "./server.ts"
+// The live proxy for an exported board: the same read routes `task serve`
+// answers, from a GitHub repository, as one platform-neutral fetch handler.
+// `task export` ships it as a Cloudflare Pages Function beside the snapshot;
+// any other host gets this and a three-line adapter — see the README.
+export {
+  createBoardHandler,
+  type BoardHandler,
+  type BoardHandlerOptions,
+} from "./board/handler.ts"
+export { buildSnapshot, writeExport, type ExportSummary, type WriteExportOptions } from "./export.ts"
 export { resolveAuthor, ANONYMOUS, type Author, type AuthorSource } from "./author.ts"
 export * from "./types.ts"

package/src/server.ts CHANGED Viewed

@@ -4,14 +4,19 @@ import { extname, join, normalize } from "node:path"
 import { fileURLToPath } from "node:url"
 import { resolveAuthor } from "./author.ts"
 import { addAskRouted, deleteAskRouted, setAskResolvedRouted } from "./claim-io.ts"
+import { injectBase } from "./export.ts"
 import { openBoard } from "./file-store.ts"
 import { GitServe, GitServeError } from "./git-serve.ts"
 import { buildInbox } from "./inbox.ts"
 import { boardConfig, findBoards, type BoardRef, type Store } from "./store.ts"
 import { STATUSES, isStatus, type TaskPatch } from "./types.ts"
-/** The prebuilt SPA, shipped inside the package next to dist/. */
-const UI_DIR = fileURLToPath(new URL("../ui/dist", import.meta.url))
+/**
+ * The prebuilt SPA, shipped inside the package next to dist/. Exported because
+ * `task export` copies the same assets it serves — one definition of where the
+ * UI lives, or the two deployments drift.
+ */
+export const UI_DIR = fileURLToPath(new URL("../ui/dist", import.meta.url))
 const MIME: Record<string, string> = {
   ".html": "text/html; charset=utf-8",
@@ -535,7 +540,11 @@ export function createTaskServer(serveRoot: string): Server {
       "Content-Type": MIME[extname(file)] ?? "application/octet-stream",
       "Cache-Control": "no-cache",
     })
-    res.end(readFileSync(file))
+    // The build's asset refs are relative (ui/vite.config.ts) and the page —
+    // this one included, when it's the SPA fallback for a deep link — needs a
+    // `<base>` to resolve them against. serve always mounts the app at the
+    // origin root; `task export --base` is where any other answer lives.
+    res.end(file.endsWith("index.html") ? injectBase(readFileSync(file, "utf8"), "/") : readFileSync(file))
   }
   return server

package/src/trailers.ts ADDED Viewed

@@ -0,0 +1,65 @@
+/**
+ * The commit-trailer contract: every commit the CLI itself authors for a
+ * board operation carries machine-readable git trailers naming the operation
+ * and the ticket, so automation can react to board events without parsing
+ * human prose. Subjects like "chore(board): resolve ask [1] on TAS-x" are
+ * presentation and may be reworded freely; the trailers are the interface.
+ *
+ *     chore(board): resolve ask [1] on TAS-x7k4m
+ *
+ *     Task-Op: resolve-ask
+ *     Task-Id: TAS-x7k4m
+ *
+ * Git parses trailers natively — consumers read them with
+ * `git log -1 --format='%(trailers:key=Task-Op,valueonly)'`, or match
+ * `Task-Op: <op>` in a forge webhook's head-commit message (each routed
+ * write is its own single-commit push, so the head commit is the operation).
+ *
+ * STABILITY: `Task-Op` and `Task-Id` are a documented, test-pinned contract
+ * (see the "commit trailers" tests). Existing op names never change meaning
+ * or disappear; new ops may be added. Renaming an op or dropping a trailer
+ * is a breaking change to every consumer's automation.
+ */
+/**
+ * The operation vocabulary. Emitted today:
+ *
+ * - `claim`       — the claim branch's first commit, the in_progress flip
+ *                   (plain and --lock-only alike)
+ * - `ask`         — an ask filed onto a claim branch (routed write)
+ * - `resolve-ask` — an ask checked off on a claim branch: the signal that a
+ *                   stalled claim may be implementable again
+ * - `reopen-ask`  — a resolved ask put back
+ * - `delete-ask`  — an ask removed from a claim branch
+ *
+ * Reserved, not yet emitted:
+ *
+ * - `begin-implement` — a worker marking the start of an implement pass on a
+ *   claim (an empty commit pushed at tick start), so "this claim is being
+ *   worked right now" becomes board state a dispatcher can read instead of a
+ *   blind spot. Designed for the mid-flight-visibility problem; deliberately
+ *   deferred until collisions prove worth the extra moving part. Consumers
+ *   should treat unknown ops as "not the op I'm looking for", never an error.
+ */
+export type TaskOp =
+  | "claim"
+  | "ask"
+  | "resolve-ask"
+  | "reopen-ask"
+  | "delete-ask"
+  | "begin-implement"
+/**
+ * Compose a board commit message: the human subject, then one trailer block.
+ * `extra` rides in the same block (e.g. lock-only's `Delivered-By:`) — git
+ * only recognizes a *contiguous* trailing block, so every trailer must go
+ * through this one seam.
+ */
+export function boardCommitMessage(
+  subject: string,
+  op: TaskOp,
+  id: string,
+  extra: string[] = [],
+): string {
+  return `${subject}\n\n${[...extra, `Task-Op: ${op}`, `Task-Id: ${id}`].join("\n")}`
+}