npm - @nickmeriano/task - Versions diffs - 0.9.0 → 0.11.0 - Mend

@nickmeriano/task 0.9.0 → 0.11.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 (46) hide show

package/README.md +129 -0
package/dist/asks.test.js +6 -0
package/dist/asks.test.js.map +1 -1
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 +99 -1
package/dist/claim.d.ts.map +1 -1
package/dist/claim.js +271 -6
package/dist/claim.js.map +1 -1
package/dist/claim.test.d.ts +8 -0
package/dist/claim.test.d.ts.map +1 -1
package/dist/claim.test.js +211 -2
package/dist/claim.test.js.map +1 -1
package/dist/cli.js +193 -7
package/dist/cli.js.map +1 -1
package/dist/export.d.ts +132 -0
package/dist/export.d.ts.map +1 -0
package/dist/export.js +199 -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 +185 -0
package/dist/export.test.js.map +1 -0
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 +1 -1
package/skill/SKILL.md +34 -1
package/src/asks.test.ts +15 -0
package/src/claim-io.ts +12 -3
package/src/claim.test.ts +286 -2
package/src/claim.ts +375 -6
package/src/cli.ts +208 -7
package/src/export.test.ts +254 -0
package/src/export.ts +276 -0
package/src/server.ts +12 -3
package/src/trailers.ts +65 -0
package/ui/dist/assets/{index-CoKCUYic.css → index-eHsqltgs.css} +1 -1
package/ui/dist/assets/{index-BjsorZOU.js → index-mJmm4sWq.js} +53 -53
package/ui/dist/index.html +3 -3

package/src/export.ts ADDED Viewed

@@ -0,0 +1,276 @@
+/**
+ * `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 { join, resolve } from "node:path"
+import { resolveAuthor } from "./author.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 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
+}
+export interface ExportSummary {
+  outDir: string
+  base: string
+  boards: number
+  tasks: number
+  commit: string | null
+  builtAt: string
+}
+/**
+ * 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 })
+  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`)
+  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,
+  }
+}

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