@nickmeriano/task 0.11.0 → 0.12.0

package/src/board/tar.test.ts

@@ -0,0 +1,128 @@
+/**
+ * The tar walk is hand-written against a binary format, so it's tested the
+ * way the SQLite reader used to be: against archives built independently —
+ * here by a minimal tar *writer* that produces the same shapes GitHub's
+ * tarballs contain (ustar headers, a pax_global_header, pax path overrides,
+ * a wrapping root directory), gzipped through node:zlib.
+ */
+
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { gzipSync } from "node:zlib"
+import { readTar, TarError } from "./tar.ts"
+
+const encoder = new TextEncoder()
+
+interface Entry {
+  name: string
+  type?: string
+  data?: string
+  /** Extra pax header naming this entry, the way GitHub emits long paths. */
+  paxPath?: string
+}
+
+function header(name: string, type: string, size: number): Uint8Array {
+  const block = new Uint8Array(512)
+  block.set(encoder.encode(name).subarray(0, 100), 0)
+  block.set(encoder.encode("0000644\0"), 100)
+  block.set(encoder.encode(size.toString(8).padStart(11, "0") + "\0"), 124)
+  block.set(encoder.encode("00000000000\0"), 136)
+  block[156] = type.charCodeAt(0)
+  block.set(encoder.encode("ustar\x0000"), 257)
+  // Checksum: field treated as spaces while summing.
+  block.set(encoder.encode("        "), 148)
+  const sum = block.reduce((a, b) => a + b, 0)
+  block.set(encoder.encode(sum.toString(8).padStart(6, "0") + "\0 "), 148)
+  return block
+}
+
+function tarball(entries: Entry[]): Uint8Array {
+  const blocks: Uint8Array[] = []
+  for (const entry of entries) {
+    if (entry.paxPath) {
+      const record = ` path=${entry.paxPath}\n`
+      const body = `${record.length + String(record.length + 2).length}${record}`
+      const bytes = encoder.encode(body)
+      blocks.push(header("./PaxHeaders/x", "x", bytes.length), pad(bytes))
+    }
+    const data = encoder.encode(entry.data ?? "")
+    blocks.push(header(entry.name, entry.type ?? "0", data.length))
+    if (data.length > 0) blocks.push(pad(data))
+  }
+  blocks.push(new Uint8Array(1024))
+  const total = blocks.reduce((n, b) => n + b.length, 0)
+  const out = new Uint8Array(total)
+  let at = 0
+  for (const block of blocks) {
+    out.set(block, at)
+    at += block.length
+  }
+  return out
+}
+
+function pad(data: Uint8Array): Uint8Array {
+  const padded = new Uint8Array(Math.ceil(data.length / 512) * 512)
+  padded.set(data)
+  return padded
+}
+
+function stream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new Response(gzipSync(bytes)).body!.pipeThrough(
+    new DecompressionStream("gzip"),
+  ) as ReadableStream<Uint8Array>
+}
+
+test("walks a GitHub-shaped tarball: root stripped, kept bytes kept, rest skipped", async () => {
+  const bytes = tarball([
+    { name: "pax_global_header", type: "g", data: "52 comment=1234\n" },
+    { name: "owner-repo-abc123/", type: "5" },
+    { name: "owner-repo-abc123/README.md", data: "# hi" },
+    { name: "owner-repo-abc123/.task/config.json", data: '{"name":"x","prefix":"X","version":2}' },
+    { name: "owner-repo-abc123/.task/tickets/1/ticket.md", data: "---\nstatus: todo\n---\n\n# T\n" },
+    { name: "owner-repo-abc123/big/blob.bin", data: "z".repeat(5000) },
+    { name: "owner-repo-abc123/pkg/.task/config.json", data: "{}" },
+  ])
+  const { paths, files } = await readTar(stream(bytes), (path) => path.includes(".task/"))
+  assert.deepEqual(paths, [
+    "README.md",
+    ".task/config.json",
+    ".task/tickets/1/ticket.md",
+    "big/blob.bin",
+    "pkg/.task/config.json",
+  ])
+  assert.deepEqual([...files.keys()], [
+    ".task/config.json",
+    ".task/tickets/1/ticket.md",
+    "pkg/.task/config.json",
+  ])
+  assert.equal(new TextDecoder().decode(files.get(".task/tickets/1/ticket.md")), "---\nstatus: todo\n---\n\n# T\n")
+})
+
+test("pax path records override the header name, as GitHub does for long paths", async () => {
+  const longPath = `owner-repo-abc123/${"deeply/".repeat(20)}.task/config.json`
+  const bytes = tarball([
+    { name: "owner-repo-abc123/x", paxPath: longPath, data: "{}" },
+  ])
+  const { paths, files } = await readTar(stream(bytes), () => true)
+  assert.deepEqual(paths, [longPath.slice("owner-repo-abc123/".length)])
+  assert.equal(files.size, 1)
+})
+
+test("ustar prefix fields are joined back onto the name", async () => {
+  const bytes = tarball([{ name: "owner-repo-abc123/plain.txt", data: "ok" }])
+  // Craft one entry using the prefix field by hand.
+  const block = header("tail.txt", "0", 2)
+  block.set(encoder.encode("owner-repo-abc123/some/dir"), 345)
+  const data = pad(encoder.encode("ok"))
+  const joined = new Uint8Array(bytes.length + block.length + data.length)
+  joined.set(block, 0)
+  joined.set(data, block.length)
+  joined.set(bytes, block.length + data.length)
+  const { paths } = await readTar(stream(joined), () => false)
+  assert.deepEqual(paths, ["some/dir/tail.txt", "plain.txt"])
+})
+
+test("a truncated archive throws instead of returning half a repository", async () => {
+  const bytes = tarball([{ name: "owner-repo-abc123/a.txt", data: "hello" }])
+  await assert.rejects(readTar(stream(bytes.subarray(0, 600)), () => true), TarError)
+})

package/src/board/tar.ts

@@ -0,0 +1,199 @@
+/**
+ * A minimal streaming tar reader — just enough to walk a GitHub repository
+ * tarball. One pass, bounded memory: every entry's *path* is recorded, but
+ * bytes are kept only for the paths the caller's `keep` predicate selects;
+ * everything else is discarded chunk by chunk as it streams through, so a big
+ * repository costs no more memory than its boards.
+ *
+ * Understands what GitHub's tarballs actually contain: ustar headers with the
+ * split `prefix` field, a leading `pax_global_header`, and pax extended
+ * headers (`x`) or GNU longname entries (`L`) for paths longer than the
+ * header's 100 bytes. Checksums are not verified — the bytes come off a TLS
+ * connection from GitHub, not a tape from 1988.
+ */
+
+export class TarError extends Error {}
+
+const BLOCK = 512
+
+/** Reads exact byte counts off a stream, buffering only what's unconsumed. */
+class ByteReader {
+  private reader: ReadableStreamDefaultReader<Uint8Array>
+  private chunks: Uint8Array[] = []
+  private have = 0
+  private done = false
+
+  constructor(stream: ReadableStream<Uint8Array>) {
+    this.reader = stream.getReader()
+  }
+
+  private async pull(): Promise<boolean> {
+    if (this.done) return false
+    const { done, value } = await this.reader.read()
+    if (done) {
+      this.done = true
+      return false
+    }
+    if (value && value.length > 0) {
+      this.chunks.push(value)
+      this.have += value.length
+    }
+    return true
+  }
+
+  /** Exactly `n` bytes; null at a clean end-of-stream, throws mid-entry. */
+  async read(n: number): Promise<Uint8Array | null> {
+    while (this.have < n) {
+      if (!(await this.pull())) {
+        if (this.have === 0) return null
+        throw new TarError("truncated archive")
+      }
+    }
+    const out = new Uint8Array(n)
+    let filled = 0
+    while (filled < n) {
+      const head = this.chunks[0]
+      const take = Math.min(head.length, n - filled)
+      out.set(head.subarray(0, take), filled)
+      filled += take
+      if (take === head.length) this.chunks.shift()
+      else this.chunks[0] = head.subarray(take)
+    }
+    this.have -= n
+    return out
+  }
+
+  /** Discard `n` bytes without accumulating them. */
+  async skip(n: number): Promise<void> {
+    while (n > 0) {
+      if (this.chunks.length === 0) {
+        if (!(await this.pull())) throw new TarError("truncated archive")
+        continue
+      }
+      const head = this.chunks[0]
+      const take = Math.min(head.length, n)
+      if (take === head.length) this.chunks.shift()
+      else this.chunks[0] = head.subarray(take)
+      this.have -= take
+      n -= take
+    }
+  }
+}
+
+const decoder = new TextDecoder()
+
+function field(header: Uint8Array, start: number, length: number): string {
+  const slice = header.subarray(start, start + length)
+  const nul = slice.indexOf(0)
+  return decoder.decode(nul < 0 ? slice : slice.subarray(0, nul))
+}
+
+function octal(header: Uint8Array, start: number, length: number): number {
+  const text = field(header, start, length).trim()
+  if (text === "") return 0
+  const value = parseInt(text, 8)
+  if (Number.isNaN(value) || value < 0) throw new TarError("bad size field")
+  return value
+}
+
+/** The `path=` record of a pax extended header, if it has one. */
+function paxPath(data: Uint8Array): string | null {
+  // Records are "<len> <key>=<value>\n", len covering the whole record.
+  const text = decoder.decode(data)
+  for (let at = 0; at < text.length; ) {
+    const space = text.indexOf(" ", at)
+    if (space < 0) break
+    const length = Number(text.slice(at, space))
+    if (!Number.isInteger(length) || length <= 0) break
+    const record = text.slice(space + 1, at + length)
+    if (record.startsWith("path=")) return record.slice(5).replace(/\n$/, "")
+    at += length
+  }
+  return null
+}
+
+export interface TarContents {
+  /** Every regular file's path, root directory stripped. */
+  paths: string[]
+  /** Bytes of the paths `keep` selected. */
+  files: Map<string, Uint8Array>
+}
+
+/**
+ * Walk a (decompressed) tar stream. Paths are reported with the archive's
+ * root directory stripped — GitHub tarballs wrap everything in
+ * `<owner>-<repo>-<sha>/` — matching what a git tree listing would say.
+ */
+export async function readTar(
+  stream: ReadableStream<Uint8Array>,
+  keep: (path: string) => boolean,
+): Promise<TarContents> {
+  const bytes = new ByteReader(stream)
+  const paths: string[] = []
+  const files = new Map<string, Uint8Array>()
+
+  let overridePath: string | null = null
+  for (;;) {
+    const header = await bytes.read(BLOCK)
+    if (header === null) break
+    if (header.every((b) => b === 0)) {
+      // End marker: two zero blocks, then maybe padding. Nothing left to parse.
+      break
+    }
+
+    const size = octal(header, 124, 12)
+    const padded = Math.ceil(size / BLOCK) * BLOCK
+    const type = header[156]
+
+    // Extended headers name the *next* entry; the global one ('g') is skipped.
+    if (type === 0x78 /* x */ || type === 0x4c /* L */) {
+      const data = await bytes.read(size)
+      if (data === null) throw new TarError("truncated archive")
+      overridePath =
+        type === 0x78 ? (paxPath(data) ?? overridePath) : decoder.decode(data).replace(/\0+$/, "")
+      await bytes.skip(padded - size)
+      continue
+    }
+
+    let name = field(header, 0, 100)
+    // ustar splits long paths into prefix + name.
+    const prefix = field(header, 257, 6).startsWith("ustar") ? field(header, 345, 155) : ""
+    if (prefix) name = `${prefix}/${name}`
+    if (overridePath !== null) {
+      name = overridePath
+      overridePath = null
+    }
+
+    // Regular file entries only — directories, links and the global header
+    // carry no board bytes. Type '0' or the ancient NUL both mean "file".
+    if (type !== 0x30 && type !== 0) {
+      await bytes.skip(padded)
+      continue
+    }
+
+    // Strip the tarball's root directory. A path without one (no slash) is
+    // the metadata GitHub puts at the top level — not repository content.
+    const slash = name.indexOf("/")
+    if (slash < 0) {
+      await bytes.skip(padded)
+      continue
+    }
+    const path = name.slice(slash + 1)
+    if (path === "") {
+      await bytes.skip(padded)
+      continue
+    }
+
+    paths.push(path)
+    if (keep(path)) {
+      const data = await bytes.read(size)
+      if (data === null) throw new TarError("truncated archive")
+      files.set(path, data)
+      await bytes.skip(padded - size)
+    } else {
+      await bytes.skip(padded)
+    }
+  }
+
+  return { paths, files }
+}

package/src/cli.ts

@@ -96,6 +96,7 @@ const BOOLEAN_FLAGS = new Set([
   "fix",
   "next",
   "force",
+  "no-functions",
   "reopen",
   "lock-only",
   "dry-run",
@@ -1334,6 +1335,22 @@ function cmdExport(args: Args): void {
   const out = str(args.flags, "out") ?? join(serveRoot, DEFAULT_OUT_DIR)
   const outDir = isAbsolute(out) ? out : resolve(process.cwd(), out)
 
+  // The live proxy is written unless told not to. It is inert until the host
+  // has a token — it answers 503 and the board reads the snapshot — so the
+  // default costs nothing, and turning a deploy live becomes one secret
+  // rather than a re-export. The repository it reads is baked in: the export
+  // already knows (the same remote detection `task publish` uses), and one
+  // fewer setting on the host is one fewer thing to get wrong.
+  let functions: { repo: string } | undefined
+  let noRemote = false
+  if (!args.flags["no-functions"]) {
+    const slug = str(args.flags, "repo")
+    const ref = slug ? parseSlug(slug) : detectRepo(serveRoot)
+    if (slug && !ref) fail(`--repo must be owner/name — got ${JSON.stringify(slug)}`)
+    if (ref) functions = { repo: `${ref.owner}/${ref.repo}` }
+    else noRemote = true
+  }
+
   let summary
   try {
     summary = writeExport({
@@ -1342,6 +1359,7 @@ function cmdExport(args: Args): void {
       uiDir: UI_DIR,
       force: Boolean(args.flags.force),
       base: str(args.flags, "base"),
+      functions,
     })
   } catch (error) {
     fail(error instanceof Error ? error.message : String(error))
@@ -1355,6 +1373,15 @@ function cmdExport(args: Args): void {
   console.log(`Exported ${what}${summary.commit ? ` at ${summary.commit.slice(0, 7)}` : ""}`)
   console.log(`  ${summary.outDir}`)
   console.log("Serve that directory from any static host — the board reads snapshot.json.")
+  if (summary.functions && functions) {
+    // One line, every run: this tier has no viewer auth, and the moment the
+    // function is written is the moment to say so. The README says the rest.
+    console.log(
+      `  ${summary.functions} reads ${functions.repo} live once the host has a TASK_GITHUB_TOKEN secret — to anyone who can reach it (README: "Live data for an exported board")`,
+    )
+  } else if (noRemote) {
+    console.log("  no live function written — no GitHub remote to read from; pass --repo owner/name to add one")
+  }
 }
 
 /**
@@ -1648,7 +1675,7 @@ Usage
                                 fails instead). Serves every board at or below
                                 here — in a monorepo the header becomes a
                                 board switcher
-  task export [--out <dir>] [--base <path>] [--force]
+  task export [--out <dir>] [--base <path>] [--force] [--no-functions | --repo <owner/name>]
                                 write the board out as static files — the same
                                 UI plus a snapshot.json it reads instead of an
                                 API, so any static host serves it read-only
@@ -1660,7 +1687,14 @@ Usage
                                 domain root. Re-exporting refreshes an earlier
                                 export in place and leaves anything else in
                                 there alone; a non-empty directory that isn't
-                                one needs --force
+                                one needs --force. Also writes a Cloudflare
+                                Pages Function that reads the repo live from
+                                GitHub: inert until the host has a
+                                TASK_GITHUB_TOKEN secret (a fine-grained PAT,
+                                Contents: read-only), at which point the same
+                                deploy upgrades itself — no viewer auth, mind.
+                                The repo comes from your remotes; --repo sets
+                                it, --no-functions skips the function
   task publish [--public | --private] [--repo <owner/name>]
                                 give this repo's board a URL at
                                 task.nickmeriano.com, read-only, updated from

package/src/export.test.ts

@@ -23,7 +23,15 @@ import {
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { initProject, openBoard } from "./file-store.ts"
-import { buildSnapshot, writeExport, SNAPSHOT_FILE, SNAPSHOT_VERSION, type Snapshot } from "./export.ts"
+import {
+  buildSnapshot,
+  functionPath,
+  renderFunction,
+  writeExport,
+  SNAPSHOT_FILE,
+  SNAPSHOT_VERSION,
+  type Snapshot,
+} from "./export.ts"
 import { STATUSES } from "./types.ts"
 
 function tempRoot(): string {
@@ -159,6 +167,7 @@ test("the export is the assets plus the snapshot", () => {
     tasks: snapshot.data["."].tasks.length,
     commit: null,
     builtAt: snapshot.meta.builtAt,
+    functions: null,
   })
 })
 
@@ -252,3 +261,101 @@ test("a base that isn't a plain URL path is refused", () => {
     )
   }
 })
+
+// ── The live proxy, written beside the snapshot ─────────────────────────────
+
+/** A stand-in for `dist/functions/board.js`: the placeholders are the contract. */
+function fakeBundle(): string {
+  const dir = tempRoot()
+  const path = join(dir, "board.js")
+  writeFileSync(
+    path,
+    'const REPO = "__TASK_EXPORT_REPO__";\nconst BASE_PATH = "__TASK_EXPORT_BASE_PATH__";\nexport const onRequest = () => [REPO, BASE_PATH];\n',
+  )
+  return path
+}
+
+test("--functions writes the Pages Function where the SPA will look for its API", () => {
+  const root = board()
+  const out = join(tempRoot(), "board")
+  const summary = writeExport({
+    serveRoot: root,
+    outDir: out,
+    uiDir: fakeUi(),
+    functions: { repo: "acme/widgets", bundle: fakeBundle() },
+  })
+  assert.equal(summary.functions, join("functions", "api", "[[path]].js"))
+  const written = readFileSync(join(out, summary.functions!), "utf8")
+  assert.match(written, /const REPO = "acme\/widgets";/)
+  assert.match(written, /const BASE_PATH = "\/api";/)
+  assert.ok(!written.includes("__TASK_EXPORT_"))
+  // The snapshot is still there: the function is an upgrade, not a replacement.
+  assert.ok(existsSync(join(out, SNAPSHOT_FILE)))
+})
+
+test("under --base the function moves with the mount point", () => {
+  assert.equal(functionPath("/"), join("functions", "api", "[[path]].js"))
+  assert.equal(functionPath("board"), join("functions", "board", "api", "[[path]].js"))
+  assert.equal(functionPath("/a/b/"), join("functions", "a", "b", "api", "[[path]].js"))
+
+  const out = join(tempRoot(), "sub")
+  const summary = writeExport({
+    serveRoot: board(),
+    outDir: out,
+    uiDir: fakeUi(),
+    base: "/board/",
+    functions: { repo: "acme/widgets", bundle: fakeBundle() },
+  })
+  assert.equal(summary.functions, join("functions", "board", "api", "[[path]].js"))
+  assert.match(readFileSync(join(out, summary.functions!), "utf8"), /const BASE_PATH = "\/board\/api";/)
+})
+
+test("a re-export without --functions leaves the function as deployed; with it, refreshes it", () => {
+  const root = board()
+  const out = join(tempRoot(), "board")
+  const ui = fakeUi()
+  const first = writeExport({
+    serveRoot: root,
+    outDir: out,
+    uiDir: ui,
+    functions: { repo: "acme/widgets", bundle: fakeBundle() },
+  })
+  const file = join(out, first.functions!)
+  writeFileSync(file, "// hand-edited on the host")
+
+  const plain = writeExport({ serveRoot: root, outDir: out, uiDir: ui })
+  assert.equal(plain.functions, null)
+  assert.equal(readFileSync(file, "utf8"), "// hand-edited on the host")
+
+  writeExport({ serveRoot: root, outDir: out, uiDir: ui, functions: { repo: "acme/gadgets", bundle: fakeBundle() } })
+  assert.match(readFileSync(file, "utf8"), /acme\/gadgets/)
+})
+
+test("a repo that isn't owner/name, or a missing bundle, fails before anything is written", () => {
+  const out = join(tempRoot(), "board")
+  assert.throws(
+    () =>
+      writeExport({
+        serveRoot: board(),
+        outDir: out,
+        uiDir: fakeUi(),
+        functions: { repo: 'acme/"; fetch("evil', bundle: fakeBundle() },
+      }),
+    /owner\/name/,
+  )
+  assert.ok(!existsSync(out))
+  assert.throws(
+    () =>
+      writeExport({
+        serveRoot: board(),
+        outDir: out,
+        uiDir: fakeUi(),
+        functions: { repo: "acme/widgets", bundle: join(tempRoot(), "missing.js") },
+      }),
+    /function bundle not found/,
+  )
+  assert.ok(!existsSync(out))
+  // A bundle without the placeholders is not the function — refuse rather
+  // than ship a file that reads the wrong repository.
+  assert.throws(() => renderFunction("export const onRequest = 1", "acme/widgets", "/"), /placeholder|__TASK_EXPORT_/)
+})

package/src/export.ts

@@ -19,8 +19,10 @@
 
 import { execFileSync } from "node:child_process"
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
-import { join, resolve } from "node:path"
+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"
@@ -40,6 +42,17 @@ 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)."
 
@@ -211,6 +224,13 @@ export interface WriteExportOptions {
   /** 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 {
@@ -220,6 +240,39 @@ export interface ExportSummary {
   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)
 }
 
 /**
@@ -243,6 +296,18 @@ export function writeExport(options: WriteExportOptions): ExportSummary {
   }
 
   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) {
@@ -264,6 +329,13 @@ export function writeExport(options: WriteExportOptions): ExportSummary {
   // 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,
@@ -272,5 +344,11 @@ export function writeExport(options: WriteExportOptions): ExportSummary {
     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")
+}