@vercel/board 0.25.1 → 0.26.0

package/dist/{node-Bkd1x0QI.mjs → node-Ybi9E6bO.mjs}

@@ -1,7 +1,7 @@
 import { t as BoardError } from "./client-D0Px7KzF.mjs";
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -118,54 +118,89 @@ const expiry = (token) => {
 	}
 };
 /**
-* Where `audience`'s token is cached: one per board, and with a login the Vercel CLI hands over
-* (`VERCEL_AUTH_TOKEN`), one per login too, since it can be someone else's than `vercel login`'s.
+* Where `audience`'s token is cached: one per board, and with a login a CLI hands over, one per
+* login too, since it can be someone else's than `vercel login`'s.
 */
-const cacheFile = (audience) => {
-	const login = process.env.VERCEL_AUTH_TOKEN;
+const cacheFile = (audience, login) => {
 	const key = login ? `${audience}\n${login}` : audience;
 	return join(configDir(), "tokens", `${createHash("sha256").update(key).digest("hex").slice(0, 32)}.json`);
 };
-async function readCache(audience) {
+async function readCache(audience, login) {
 	try {
-		const cached = JSON.parse(await readFile(cacheFile(audience), "utf8"));
+		const cached = JSON.parse(await readFile(cacheFile(audience, login), "utf8"));
 		return cached.expiresAt - 3e5 > Date.now() ? cached : null;
 	} catch {
 		return null;
 	}
 }
-async function writeCache(audience, cached) {
-	await mkdir(join(configDir(), "tokens"), {
+async function writeCache(audience, login, cached) {
+	const tokens = join(configDir(), "tokens");
+	await mkdir(tokens, {
 		recursive: true,
 		mode: 448
 	});
-	await writeFile(cacheFile(audience), JSON.stringify(cached), { mode: 384 });
+	await writeFile(cacheFile(audience, login), JSON.stringify(cached), { mode: 384 });
+	const dead = Date.now() - 864e5;
+	for (const name of await readdir(tokens).catch(() => [])) {
+		const file = join(tokens, name);
+		const written = (await stat(file).catch(() => null))?.mtimeMs;
+		if (written !== void 0 && written < dead) await unlink(file).catch(() => {});
+	}
 }
+/** The login a CLI that runs board's hands it to ask for (`vercel board`'s), while one does. */
+let handed = null;
 /**
-* Your Vercel login: what the Vercel CLI hands a CLI it runs, as `vercel board` (`VERCEL_AUTH_TOKEN`,
-* from its `--token` or its own login), or else what `vercel login` saved.
+* Hands board a login to ask for when a request needs one, as `vercel board` does with its own:
+* nothing asks for it before then, so help, a typo, or misuse never refreshes or prompts. Null
+* takes it back.
 */
-const vercelLogin = () => process.env.VERCEL_AUTH_TOKEN ? Promise.resolve(process.env.VERCEL_AUTH_TOKEN) : getVercelToken();
+function handLogin(login) {
+	handed = login;
+}
+/** Whether the login is one a CLI handed over (`createApp`'s `login`, or `VERCEL_AUTH_TOKEN`). */
+const loginHanded = () => handed !== null || !!process.env.VERCEL_AUTH_TOKEN;
+/**
+* Your Vercel login: what the CLI that runs board's hands it, as `vercel board` does (its `login`,
+* or `VERCEL_AUTH_TOKEN` from its `--token`), or else what `vercel login` saved.
+*/
+const vercelLogin = () => handed ? handed() : process.env.VERCEL_AUTH_TOKEN ? Promise.resolve(process.env.VERCEL_AUTH_TOKEN) : getVercelToken();
+/**
+* A handed login's token, which its board tokens are cached by: null for `vercel login`'s own. One
+* that fails fails the request: `vercel login`'s, cached or in the `vercel` on PATH, can be someone
+* else's.
+*/
+async function handedToken() {
+	if (!loginHanded()) return null;
+	try {
+		return await vercelLogin();
+	} catch {
+		throw new BoardError("not_logged_in", "You're not logged in to Vercel.", 0, { hint: "Run vercel login." });
+	}
+}
+/** The login to call Vercel's API with: a handed one, or `vercel login`'s, or none it can read (the keychain's). */
+const apiLogin = async (handed) => handed ?? await getVercelToken().catch(() => null);
 /**
 * A person's token: their Vercel CLI login mints a development token for the
 * project the board's host is a deployment of, exchanged so its audience is the
 * board's URL. Cached on disk for its 12-hour life.
 */
 async function personToken(audience, discovery) {
-	const cached = await readCache(audience);
+	const login = await handedToken();
+	const cached = await readCache(audience, login);
 	if (cached && cached.name === void 0) {
-		const user = await vercelLogin().then(vercelUser).catch(() => null);
+		const authToken = await apiLogin(login);
+		const user = authToken ? await vercelUser(authToken) : null;
 		const filled = {
 			...cached,
 			name: user?.name ?? null,
 			avatar: user?.avatar ?? null
 		};
-		await writeCache(audience, filled).catch(() => {});
+		await writeCache(audience, login, filled).catch(() => {});
 		return filled;
 	}
 	if (cached) return cached;
 	if (!discovery.project_id) throw new BoardError("no_project", `The board at ${audience} doesn't know its Vercel project, so there's no Vercel login token to mint for it.`, 0, { hint: "Pass a token it accepts in BOARD_TOKEN." });
-	const authToken = await vercelLogin().catch(() => null);
+	const authToken = await apiLogin(login);
 	const project = await boardProject(audience, discovery, authToken);
 	let development;
 	try {
@@ -178,7 +213,7 @@ async function personToken(audience, discovery) {
 		if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
 		development = (await response.json()).token;
 	} catch (error) {
-		if (error instanceof BoardError) throw error;
+		if (error instanceof BoardError || login) throw error;
 		development = await tokenFromVercelCli(project);
 	}
 	const token = await exchangeVercelOidcToken({
@@ -193,7 +228,7 @@ async function personToken(audience, discovery) {
 		name: user?.name ?? null,
 		avatar: user?.avatar ?? null
 	};
-	await writeCache(audience, fresh).catch(() => {});
+	await writeCache(audience, login, fresh).catch(() => {});
 	return fresh;
 }
 /**
@@ -546,23 +581,18 @@ const automationBypass = (bypasses) => Object.entries(bypasses ?? {}).find(([, v
 */
 async function projectBypass(url, host, doFetch) {
 	const blocked = (why, fix) => new BoardError("protected", `${url} is behind Vercel Deployment Protection, and your Vercel login ${why}.`, 0, { hint: `${fix}, or set VERCEL_AUTOMATION_BYPASS_SECRET (${WHERE}).` });
-	let api;
-	try {
-		const token = await vercelLogin();
-		api = async (method, path) => {
-			const response = await doFetch(`https://api.vercel.com${path}`, {
-				method,
-				headers: {
-					authorization: `Bearer ${token}`,
-					...method === "PATCH" ? { "content-type": "application/json" } : {}
-				},
-				...method === "PATCH" ? { body: "{}" } : {}
-			});
-			return response.ok ? await response.json() : null;
-		};
-	} catch {
-		api = vercelCliApi;
-	}
+	const token = await apiLogin(await handedToken());
+	const api = token ? async (method, path) => {
+		const response = await doFetch(`https://api.vercel.com${path}`, {
+			method,
+			headers: {
+				authorization: `Bearer ${token}`,
+				...method === "PATCH" ? { "content-type": "application/json" } : {}
+			},
+			...method === "PATCH" ? { body: "{}" } : {}
+		});
+		return response.ok ? await response.json() : null;
+	} : vercelCliApi;
 	const project = await findProject(api, host);
 	if (!project) throw blocked("can't see its project", "Log in as someone on its project's team (vercel login), ask for access");
 	const scope = project.ownerId.startsWith("team_") ? `?teamId=${project.ownerId}` : "";
@@ -628,4 +658,4 @@ const vercelCliApi = async (method, path) => {
 	}
 };
 //#endregion
-export { projectDir as a, localTokenFile as i, connect as n, vercelLogin as o, environmentProfile as r, vercelProjectFile as s, boardUrl as t };
+export { localTokenFile as a, vercelLogin as c, handLogin as i, vercelProjectFile as l, connect as n, loginHanded as o, environmentProfile as r, projectDir as s, boardUrl as t };

package/dist/{serve-D2O0C6Kk.mjs → serve-BbHEQk_Y.mjs}

@@ -1,8 +1,8 @@
 import { t as BoardError } from "./client-D0Px7KzF.mjs";
-import { i as localTokenFile } from "./node-Bkd1x0QI.mjs";
-import { t as board } from "./server-BF4WJ7qi.mjs";
+import { a as localTokenFile } from "./node-Ybi9E6bO.mjs";
+import { t as board } from "./server-Bphio_82.mjs";
 import { t as oidcTokens } from "./tokens-BuCU-61R.mjs";
-import { n as fsBlob, t as a2 } from "./a2-A830f5NS.mjs";
+import { n as fsBlob, t as a2 } from "./a2-Qzj0kCWU.mjs";
 import { t as localScheduler } from "./local-DhkrAqPP.mjs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { userInfo } from "node:os";

package/dist/{server-BF4WJ7qi.mjs → server-Bphio_82.mjs}

@@ -1,5 +1,5 @@
-import { t as createBoard } from "./exports-DCqgO_mr.mjs";
-import { t as http } from "./backend-http-CJd4Fu0U.mjs";
+import { t as createBoard } from "./exports-NFjBgIT2.mjs";
+import { t as http } from "./backend-http-F0W6e36G.mjs";
 //#region src/server/index.ts
 /**
 * The handle on a board. With a `backend`, the board lives there: `a2()` keeps it in this

package/dist/{watchers-hash-BHNXy_N7.mjs → watchers-hash-BfDPW95j.mjs}

@@ -2,7 +2,7 @@ import { n as DIRECT_UPLOAD_BYTES_MAX, t as ATTACHMENT_BYTES_MAX } from "./files
 import { S as storable, a as AttachmentId, c as ChannelPath, d as LabelKey, g as MessageText, l as Emoji, m as MESSAGE_TEXT_MAX, n as ActorId, p as Labels, x as platformAvatar } from "./schemas-Be08nyfW.mjs";
 import { a as Link, i as ExternalTarget, n as ExternalEvent, o as Origin, t as ExternalAuthor } from "./external-BV_cUncs.mjs";
 import { r as badRequest, t as HttpError } from "./errors-CusN4x2l.mjs";
-import { o as options } from "./commands-BtL4jFq8.mjs";
+import { o as options } from "./commands-nEG47RM_.mjs";
 import { z } from "zod";
 //#region src/api/routes.ts
 /**
@@ -662,7 +662,7 @@ const routes = {
 const SYNC = "@sync";
 //#endregion
 //#region src/version.ts
-const VERSION = "0.25.1";
+const VERSION = "0.26.0";
 //#endregion
 //#region src/server/routing.ts
 /** board()'s own routes: the files it serves, and sync's, which run where board() does. */
@@ -865,7 +865,7 @@ const FILTER_FLAGS = {
 	by: options.by,
 	mentions: options.mentions,
 	label: options.label,
-	from: options.from,
+	source: options.source,
 	text: options.text
 };
 /** `--mentions` alone means mentions of me; `--mentions @ada`, mentions of ada. */
@@ -961,7 +961,7 @@ function parseWatchTail(expression) {
 		...values.by ? { by: values.by.replace(/^@/, "") } : {},
 		...values.mentions ? { mentions: values.mentions.replace(/^@/, "") } : {},
 		...values.label?.length ? { label: values.label } : {},
-		...values.from ? { from: values.from } : {},
+		...values.source ? { from: values.source } : {},
 		...values.text ? { text: values.text } : {}
 	});
 	if (!parsed.success) {

package/docs/01-board/04-messages.md

@@ -164,7 +164,7 @@ await team.reply('812', { text: 'fixed, see after', attachments: [shot] })
 A retry shouldn't post twice. Give a post or reply an ID of your own:
 
 ```bash
-vb post deploys "a1b2c3 is live" --id deploy-a1b2c3
+vb post deploys "a1b2c3 is live" --idempotency-key deploy-a1b2c3
 ```
 
 The same ID with the same write returns the message it already posted. The same

package/docs/01-board/05-reading.md

@@ -75,14 +75,14 @@ read includes it.
 | `--re <id>` | the thread rooted at `<id>`: the root and its replies |
 | `--by <handle>` | messages by that actor: a handle without the `@`, or an exact actor ID |
 | `--mentions` | messages that mention you; `--mentions @ada` for someone else |
-| `--from <source>` | where it was written: a sync key (`slack`, `github`), or `board` |
+| `--source <source>` | where it was written: a sync key (`slack`, `github`), or `board` |
 | `--label <key>` | messages with that label; `key=value`, or `key=a\|b` for either |
 | `--text <words>` | text containing the words, case-insensitive (a substring, not search) |
 | `--after <id>` | messages after that message ID or cursor; for `read`, threads with activity after it |
 
 ```bash
 vb read prs --label state=open                  # what's pending
-vb read issues --label tag.bug --from github
+vb read issues --label tag.bug --source github
 vb read --mentions                              # everywhere I'm mentioned
 vb read errors-www --by ada --text ENOTFOUND
 ```

package/docs/01-board/06-watchers.md

@@ -21,7 +21,7 @@ const team = board({
   // sync as in Sync
   watch: {
     triage: {
-      tail: 'firehose --from slack',
+      tail: 'firehose --source slack',
       run: async ({ event, board }) => {
         if (event.type === 'message.posted' && event.message?.re === null)
           await board.reply(event.message.id, 'Thanks! Tracking it.') // synced to the Slack thread
@@ -37,13 +37,13 @@ export const { scheduler } = backend
 would print, exactly as `vb tail --json` prints it. Try it in a terminal first:
 
 ```bash
-vb tail firehose --from slack --json
+vb tail firehose --source slack --json
 ```
 
 ## The expression
 
 A channel (or `prefix/` for a subtree) and the shared
-[filters](./05-reading.md#filters): `--re`, `--by`, `--mentions`, `--from`,
+[filters](./05-reading.md#filters): `--re`, `--by`, `--mentions`, `--source`,
 `--label`, `--text`, and `--all`.
 
 - **Positions aren't filters.** A watcher starts at the head when it's deployed

package/docs/02-sync/01-overview.md

@@ -95,7 +95,7 @@ see [Sync functions](./02-functions.md).
 
 **Entry keys** (`slack`, `github`, or `acme` for a second Slack workspace) are
 names you choose; the adapter decides the platform. The key appears in external
-IDs (`acme:C0999XYZ:1727.9`), in sync targets, in `--from` filters, and in the
+IDs (`acme:C0999XYZ:1727.9`), in sync targets, in `--source` filters, and in the
 webhook path (`/webhooks/acme`).
 
 **Map keys** are the platform's names or IDs: `'#prs'` or `'C0123ABC'` for
@@ -303,7 +303,7 @@ written to the log. It needs `post` and `read` in the thread's channel.
 vb sources                              # the board's sync entries and their platforms
 vb inbox slack                          # raw platform events, newest first: did Slack send it?
 vb inbox slack '#errors-www' --limit 5
-vb tail --from slack --all              # board events from Slack, delivery receipts included
+vb tail --source slack --all              # board events from Slack, delivery receipts included
 ```
 
 `vb inbox` needs `sync` in every channel for the board's own inbox, and every

package/docs/03-guides/03-ci.md

@@ -24,7 +24,7 @@ jobs:
       - uses: actions/checkout@v4
       # your deploy steps…
       - if: failure()
-        run: npx -y @vercel/board post errors-www "deploy failed on $SHA" --label source=ci --id "deploy-$SHA"
+        run: npx -y @vercel/board post errors-www "deploy failed on $SHA" --label source=ci --idempotency-key "deploy-$SHA"
         env:
           BOARD_URL: https://team.example/api/board
           SHA: ${{ github.sha }}
@@ -34,7 +34,7 @@ jobs:
   whose audience is the board's URL, so it's good for that board and nothing
   else. Without `id-token: write`, GitHub gives the job no token, so the CLI
   falls through to a `vercel login` the runner doesn't have, and fails.
-- **`--id` makes a retried step post once.** The same ID with the same write
+- **`--idempotency-key` makes a retried step post once.** The same ID with the same write
   returns the message already posted.
 - **The post is an ordinary thread.** If `errors-www` mirrors a Slack channel,
   it lands there, and a reply in Slack reaches the board.

package/docs/03-guides/04-triage.md

@@ -18,10 +18,10 @@ messages.
 
 ```bash
 # in a terminal:
-vb tail firehose --from slack --json
+vb tail firehose --source slack --json
 ```
 
-`tail` prints one line of JSON per event, live, until Ctrl-C. `--from slack`
+`tail` prints one line of JSON per event, live, until Ctrl-C. `--source slack`
 keeps messages that came from Slack. Each line carries the event and the
 message it concerns, as it is after the event:
 
@@ -38,7 +38,7 @@ report is a `message.posted` whose message has `re: null`: a thread root.
 
 ```bash
 # triage.sh: runs until you stop it
-vb tail firehose --from slack --json | while read -r event; do
+vb tail firehose --source slack --json | while read -r event; do
   [ "$(jq -r '.type' <<<"$event")" = "message.posted" ] || continue
   [ "$(jq -r '.message.re' <<<"$event")" = "null" ] || continue
   id=$(jq -r '.message.id' <<<"$event")
@@ -63,7 +63,7 @@ prints it, and exits, so each turn handles one event. Every event carries a
 ```bash
 # triage-turn.sh: one event per run
 last=$(cat .triage-cursor 2>/dev/null)
-next=$(vb wait firehose --from slack ${last:+--after "$last"} --json --timeout 1h) || exit 0
+next=$(vb wait firehose --source slack ${last:+--after "$last"} --json --timeout 1h) || exit 0
 jq -r '.cursor' <<<"$next" > .triage-cursor
 
 [ "$(jq -r '.type' <<<"$next")" = "message.posted" ] || exit 0
@@ -117,7 +117,7 @@ const team = board({
   // sync: { slack: slack('slack/acme', channels({ '#firehose': 'firehose' })) },
   watch: {
     triage: {
-      tail: 'firehose --from slack',
+      tail: 'firehose --source slack',
       run: async ({ event, board }) => {
         const message = event.message
         if (event.type !== 'message.posted' || !message || message.re !== null) return

package/docs/04-reference/01-cli.md

@@ -47,6 +47,11 @@ const code = await createApp({
   onError: (failure, { json }) => console.error(json ? JSON.stringify(failure) : failureLines(failure).join('\n')),
   // { reason, message }: a write that went through, with something to say. With --json, it's in the result.
   onWarning: (warning) => console.error(warning.message),
+  // Your Vercel login, and the team whose board to use when --scope names none, as this CLI
+  // resolves its own: asked for only when a request needs them. Help, a typo, or misuse never asks.
+  // A login that throws fails the request: board never falls back to `vercel login`'s.
+  login: async () => process.env.VERCEL_AUTH_TOKEN!,
+  team: async () => process.env.VERCEL_ORG_ID ?? null,
 }).run(process.argv.slice(3))
 ```
 
@@ -485,7 +490,7 @@ schedules that reply in that thread. `--all` adds done and canceled ones.
 ### post
 
 ```text
-vb post <channel|id> ["<text>"] [--label k=v]... [--attach <file>]... [--sync <target>]... [--no-sync] [--id <key>]
+vb post <channel|id> ["<text>"] [--label k=v]... [--attach <file>]... [--sync <target>]... [--no-sync] [--idempotency-key <key>]
 ```
 
 Starts a thread. The channel is created by its first post. Given a message ID
@@ -499,7 +504,7 @@ for new threads only.
 | `--attach <file>` | uploads a file (at most 4 MB, or 100 MB on a board whose blob store takes direct uploads; 10 per message) and attaches it. Every file is checked before any uploads. A board that keeps no files refuses: ``error: this board keeps no files: pass `blob` to `a2()` `` |
 | `--sync <target>` | also starts or joins a thread there: `slack:#incidents`, `github:owner/repo:12`; new threads only |
 | `--no-sync` | keeps the message on the board: it reaches none of the channel's mirrored channels |
-| `--id <key>` | an idempotency key: the same key never posts twice |
+| `--idempotency-key <key>` | the same key never posts twice, so a retried step posts once |
 
 `--sync` and `--no-sync` together are a usage error. See
 [Messages](../01-board/04-messages.md) and
@@ -508,7 +513,7 @@ for new threads only.
 ### reply
 
 ```text
-vb reply <id> ["<text>"] [--attach <file>]... [--no-sync] [--id <key>]
+vb reply <id> ["<text>"] [--attach <file>]... [--no-sync] [--idempotency-key <key>]
 ```
 
 Replies in a thread. `<id>` may be any message in it: the board stores the
@@ -739,7 +744,7 @@ of them must match.
 | `--by <handle>` | messages by an actor, by handle or exact actor ID. A person's handle covers their agents (`julian/claude`) and linked accounts |
 | `--mentions` | messages that mention you |
 | `--mentions @handle` | messages that mention that actor |
-| `--from <source>` | where a message came from: a sync key (`slack`, `github`), or `board` for messages written on the board |
+| `--source <source>` | where a message came from: a sync key (`slack`, `github`), or `board` for messages written on the board |
 | `--label <key>` | messages with the label, any value |
 | `--label <key>=<value>` | that value; `state=open\|draft` means either |
 | `--text <words>` | a case-insensitive substring of the text (1 to 200 characters), not search |

package/docs/index.md

@@ -110,7 +110,7 @@ const team = board({
   // sync as above
   watch: {
     triage: {
-      tail: 'errors-www --from slack',
+      tail: 'errors-www --source slack',
       run: async ({ event, board }) => {
         if (event.type !== 'message.posted' || event.message?.re !== null) return
         // the reply reaches the Slack thread too:
@@ -124,7 +124,7 @@ export const { scheduler } = backend
 ```
 
 A watcher is a `vb tail` the board runs for you. Try the expression in a
-terminal first (`vb tail errors-www --from slack --json`); `run` gets exactly
+terminal first (`vb tail errors-www --source slack --json`); `run` gets exactly
 those events, durably, with retries and nothing kept open. See
 [Watchers](./01-board/06-watchers.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/board",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "A message board you mount in one route: one durable log, verified authors, live tail, and two-way sync.",
   "license": "MIT",
   "type": "module",