@nickmeriano/task 0.3.0 → 0.4.1

package/src/cli.ts

@@ -14,6 +14,7 @@ import type { Server } from "node:http"
 import { basename, join } from "node:path"
 import process from "node:process"
 import { resolveAuthor } from "./author.js"
+import { detectRepo, parseSlug, publish, resolveHost } from "./publish.js"
 import { createTaskServer } from "./server.js"
 import { CONFIG_FILE, TASK_DIR, TaskStore, findBoards, findRoot, initProject } from "./store.js"
 import { STATUSES, isStatus, type Status, type Task, type TaskPatch } from "./types.js"
@@ -64,6 +65,9 @@ const BOOLEAN_FLAGS = new Set([
   "open",
   "no-open",
   "strict-port",
+  "public",
+  "private",
+  "no-wait",
 ])
 
 function parseArgs(argv: string[]): Args {
@@ -403,6 +407,100 @@ function cmdServe(args: Args): void {
   })
 }
 
+/**
+ * `task publish` — the board, at a URL.
+ *
+ * Visibility is the only real decision here, and the default is the cautious
+ * one: **every board starts private, including a public repository's**. A repo
+ * being open source says its code is readable; it says nothing about whether
+ * its owner wants a live feed of what they're working on next. Going public is
+ * `--public`, said out loud, and it can be changed either way at any time by
+ * running this again.
+ */
+async function cmdPublish(args: Args): Promise<void> {
+  if (args.flags.public && args.flags.private) {
+    fail("--public and --private contradict each other — pass one")
+  }
+  // `undefined`, not a default: an omitted flag means "leave it alone" so that
+  // re-publishing to reconnect a repo can't silently change who can see it.
+  const visibility = args.flags.public ? "public" : args.flags.private ? "private" : null
+
+  const repo = resolveRepoArg(args)
+  console.log(`Publishing ${repo.owner}/${repo.repo}${visibility ? ` (${visibility})` : ""}`)
+
+  const result = await runPublishFlow(args, repo, "publish", visibility)
+  if (!result) return
+
+  console.log("")
+  console.log(`✓ Published${result.approvedBy ? ` by ${result.approvedBy}` : ""}`)
+  console.log(`  ${result.boardUrl}`)
+  console.log(
+    result.visibility === "public"
+      ? "  Public — anyone with the link can view this board."
+      : "  Private — only people who can see the repo on GitHub can view it.",
+  )
+  console.log("")
+  console.log("The board reads .task/ from your default branch, so commit and push to update it.")
+}
+
+/**
+ * `task unpublish` — take the URL away.
+ *
+ * Small on purpose, and worth saying so at the prompt: this removes a board,
+ * not a backlog. The tasks were never anywhere but `.task/` in your repo, so
+ * there is nothing here that can lose them — which is also why this doesn't ask
+ * for a `--yes`. The browser step already puts a confirmation in front of a
+ * human, and `task publish` puts it straight back.
+ */
+async function cmdUnpublish(args: Args): Promise<void> {
+  const repo = resolveRepoArg(args)
+  console.log(`Unpublishing ${repo.owner}/${repo.repo}`)
+
+  const result = await runPublishFlow(args, repo, "unpublish", null)
+  if (!result) return
+
+  console.log("")
+  console.log(`✓ Unpublished${result.approvedBy ? ` by ${result.approvedBy}` : ""}`)
+  console.log(`  ${result.boardUrl} now returns a 404.`)
+  console.log("")
+  console.log("Your tasks are untouched — .task/ is where they always were.")
+  console.log("The task app stays installed on the repo; remove it in GitHub settings")
+  console.log("to revoke its read access too. `task publish` puts the board back.")
+}
+
+/** The repo both commands operate on: `--repo owner/name`, else the remote. */
+function resolveRepoArg(args: Args): { owner: string; repo: string } {
+  const slug = str(args.flags, "repo")
+  const repo = slug ? parseSlug(slug) : detectRepo(process.cwd())
+  if (!repo) {
+    fail(
+      slug
+        ? `--repo must look like owner/name, got "${slug}"`
+        : "couldn't work out the GitHub repo from your git remotes — pass --repo owner/name",
+    )
+  }
+  return repo
+}
+
+function runPublishFlow(
+  args: Args,
+  repo: { owner: string; repo: string },
+  action: "publish" | "unpublish",
+  visibility: "public" | "private" | null,
+) {
+  return publish({
+    host: resolveHost(str(args.flags, "host")),
+    repo,
+    action,
+    visibility,
+    noWait: Boolean(args.flags["no-wait"]),
+    open: (url) => {
+      if (!args.flags["no-open"] && !process.env.CI) openBrowser(url)
+    },
+    log: (line) => console.log(line),
+  })
+}
+
 // ── Help + dispatch ──────────────────────────────────────────────────────────
 
 const HELP = `task — a task manager that lives in your repo
@@ -434,6 +532,16 @@ Usage
                                 fails instead). Serves every board at or below
                                 here — in a monorepo the header becomes a
                                 board switcher
+  task publish [--public | --private] [--repo <owner/name>]
+                                give this repo's board a URL at
+                                task.nickmeriano.com, read-only, updated from
+                                your default branch. Private by default —
+                                *including for public repos* — so only people
+                                who can see the repo can see the board. Run it
+                                again with --public or --private to change that
+  task unpublish [--repo <owner/name>]
+                                take that URL down. Removes the board, not the
+                                tasks — those are in .task/ either way
 
 Values
   <id>          TASK-12, or just 12
@@ -449,7 +557,8 @@ Every read/write command accepts --json for machine-readable output — that's
 the interface AI agents should use.
 `
 
-function main(): void {
+/** Sync but for `publish`, which waits on a browser — hence the union. */
+function main(): void | Promise<void> {
   const [command, ...rest] = process.argv.slice(2)
   const args = parseArgs(rest)
 
@@ -487,13 +596,21 @@ function main(): void {
       return cmdDelete(args)
     case "serve":
       return cmdServe(args)
+    case "publish":
+      return cmdPublish(args)
+    case "unpublish":
+      return cmdUnpublish(args)
     default:
       fail(`unknown command "${command}" — run \`task help\``)
   }
 }
 
 try {
-  main()
+  // `publish` is the only async command; everything else has already finished
+  // by the time this returns, and its errors are caught below.
+  void Promise.resolve(main()).catch((error: unknown) =>
+    fail(error instanceof Error ? error.message : String(error)),
+  )
 } catch (error) {
   fail(error instanceof Error ? error.message : String(error))
 }

package/src/publish.ts

@@ -0,0 +1,192 @@
+/**
+ * `task publish` / `task unpublish` — give this repo's board a URL, or take it
+ * away.
+ *
+ * The CLI cannot install a GitHub App or sign anyone in; both are browser
+ * flows. So it does the one thing it is well placed to do — work out *which*
+ * repository you mean — opens a ticket for it, sends you to a browser, and
+ * waits. The credential it holds is a single short-lived ticket id that is good
+ * for nothing but asking "is this done yet".
+ *
+ * Both directions are the same handshake with a different verb, deliberately:
+ * taking a board down needs exactly the permission putting one up does, and one
+ * code path is one place for that check to be right.
+ *
+ * Nothing is written to `.task/` either way. The link between a repo and its
+ * board lives on the host, keyed by the GitHub remote, so there is no state to
+ * commit, no token in the repo, and re-running this from a fresh clone is the
+ * same operation as re-running it here.
+ */
+
+import { execFileSync } from "node:child_process"
+import process from "node:process"
+
+/** Overridable so the flow can be exercised against a local `vite dev`. */
+export const DEFAULT_HOST = "https://task.nickmeriano.com"
+
+export type Visibility = "private" | "public"
+
+export type Action = "publish" | "unpublish"
+
+export interface RepoRef {
+  owner: string
+  repo: string
+}
+
+/**
+ * The GitHub repo this working copy pushes to.
+ *
+ * `origin` first, then the only remote if there's exactly one — a clone with
+ * `upstream` and a fork remote should not silently publish the wrong one, so
+ * ambiguity is an error the user resolves with `--repo`.
+ */
+export function detectRepo(cwd: string): RepoRef | null {
+  const remotes = gitRemotes(cwd)
+  const url = remotes.get("origin") ?? (remotes.size === 1 ? [...remotes.values()][0] : null)
+  return url ? parseRemote(url) : null
+}
+
+function gitRemotes(cwd: string): Map<string, string> {
+  const out = new Map<string, string>()
+  let raw: string
+  try {
+    raw = execFileSync("git", ["remote", "-v"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+  } catch {
+    return out
+  }
+  for (const line of raw.split("\n")) {
+    const match = /^(\S+)\s+(\S+)\s+\(fetch\)$/.exec(line.trim())
+    if (match) out.set(match[1], match[2])
+  }
+  return out
+}
+
+/**
+ * Every shape git writes a GitHub remote in: https, ssh, `git@`-scp, with or
+ * without `.git`, and with or without credentials embedded in the host.
+ */
+export function parseRemote(url: string): RepoRef | null {
+  const cleaned = url.trim().replace(/\.git$/, "")
+  const match =
+    /^(?:https?:\/\/|ssh:\/\/)?(?:[^@/]+@)?github\.com[:/]([^/]+)\/([^/]+?)\/?$/.exec(cleaned)
+  if (!match) return null
+  const [, owner, repo] = match
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(owner)) return null
+  if (!/^[A-Za-z0-9._-]{1,100}$/.test(repo)) return null
+  return { owner, repo }
+}
+
+/** `owner/repo`, for `--repo`. */
+export function parseSlug(slug: string): RepoRef | null {
+  const [owner, repo, ...rest] = slug.split("/")
+  if (!owner || !repo || rest.length > 0) return null
+  return parseRemote(`https://github.com/${owner}/${repo}`)
+}
+
+interface StartResponse {
+  ticket: string
+  url: string
+  boardUrl: string
+  expiresAt: string
+}
+
+interface StatusResponse {
+  status: "pending" | "complete" | "denied" | "expired"
+  action: Action
+  approvedBy: string | null
+  error: string | null
+  boardUrl: string
+  visibility: Visibility | null
+}
+
+async function postJson<T>(url: string, body: unknown): Promise<T> {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  })
+  const data = (await res.json().catch(() => ({}))) as T & { error?: string }
+  if (!res.ok) throw new Error(data.error ?? `${res.status} from ${url}`)
+  return data
+}
+
+export interface PublishOptions {
+  host: string
+  repo: RepoRef
+  action: Action
+  /** Ignored for `unpublish`, which has no visibility to state. */
+  visibility: Visibility | null
+  /** Print the URL and exit instead of waiting for the browser. */
+  noWait: boolean
+  open: (url: string) => void
+  log: (line: string) => void
+}
+
+export interface PublishResult {
+  boardUrl: string
+  approvedBy: string | null
+  visibility: Visibility | null
+}
+
+/** Poll interval — fast enough to feel immediate, slow enough to be polite. */
+const POLL_MS = 1500
+
+/**
+ * Runs the whole handshake. Resolves when the browser half completes; rejects
+ * with a message meant to be printed as-is.
+ */
+export async function publish(options: PublishOptions): Promise<PublishResult | null> {
+  const { host, repo, action, visibility } = options
+  const start = await postJson<StartResponse>(`${host}/publish/start`, {
+    owner: repo.owner,
+    repo: repo.repo,
+    action,
+    visibility,
+  })
+
+  options.log(`Approve in your browser:\n  ${start.url}`)
+  if (options.noWait) return null
+  options.open(start.url)
+  options.log("")
+  options.log("Waiting…  (Ctrl-C to stop — the link above stays valid for 10 minutes)")
+
+  const deadline = Date.parse(start.expiresAt)
+  for (;;) {
+    await new Promise((resolve) => setTimeout(resolve, POLL_MS))
+    if (Date.now() > deadline) throw new Error("that link expired — run `task publish` again")
+
+    let status: StatusResponse
+    try {
+      const res = await fetch(`${host}/publish/status?ticket=${encodeURIComponent(start.ticket)}`)
+      if (res.status === 404) throw new Error("that link expired — run `task publish` again")
+      status = (await res.json()) as StatusResponse
+    } catch (error) {
+      // A blip between here and the host is not a failed publish. Keep waiting
+      // until the ticket's own deadline says otherwise.
+      if (error instanceof Error && error.message.includes("expired")) throw error
+      continue
+    }
+
+    if (status.status === "complete") {
+      return {
+        boardUrl: status.boardUrl,
+        approvedBy: status.approvedBy,
+        visibility: status.visibility,
+      }
+    }
+    if (status.status === "denied") {
+      throw new Error(status.error ?? `${action === "unpublish" ? "unpublishing" : "publishing"} was canceled`)
+    }
+    if (status.status === "expired") throw new Error("that link expired — run `task publish` again")
+  }
+}
+
+/** `TASK_HOST` exists so the flow can be pointed at a local dev server. */
+export function resolveHost(flag: string | undefined): string {
+  const host = flag ?? process.env.TASK_HOST ?? DEFAULT_HOST
+  return host.replace(/\/+$/, "")
+}