@vercel/board 0.28.0 → 0.29.0

package/dist/sync-linear.mjs

@@ -1,6 +1,7 @@
-import { i as UnreadableError, s as channels } from "./provider-poIkXapd.mjs";
-import { i as eventSchema, r as envelope } from "./events-CewD4kw7.mjs";
-import { r as markdownOf, t as ChatSyncProvider } from "./chat-provider-DnHibqnM.mjs";
+import { i as UnreadableError, s as channels } from "./provider-BaVmi4Hi.mjs";
+import { i as eventSchema, r as envelope } from "./events-qf5XG5VQ.mjs";
+import { r as markdownOf, t as ChatSyncProvider } from "./chat-provider-COtsU5jB.mjs";
+import { n as tagOf, t as slug } from "./tags-BpFo6q0_.mjs";
 import "zod";
 import { connectLinearAdapter } from "@vercel/connect/chat";
 import { createLinearAdapter } from "@chat-adapter/linear";
@@ -30,6 +31,41 @@ const author = (user, isBot) => ({
 });
 /** `ENG` from `ENG-123`, or from a Linear URL that names an issue (`…/issue/ENG-123/…`). */
 const teamOf = (identifierOrUrl) => /(?:^|\/issue\/)([A-Z0-9_]+)-\d+/i.exec(identifierOrUrl ?? "")?.[1]?.toUpperCase() ?? null;
+/** An issue's description, or null when it has none. */
+const bodyOf = (description) => description?.trim() || null;
+/**
+* An issue's properties as board labels: `priority=high`, `project=v0-accessibility`, a label per
+* Linear label (`tag.bug`), and its assignee (`assignee.ada`). Only what the payload says: a
+* property it carries empty is unset, and one it names without its details is left as it was.
+* `priority` and `project` are single keys, so they're unset by name; `tag.` and `assignee.` are
+* prefixes the mirror owns, so a key under them that Linear doesn't have goes.
+*/
+function propertiesOf(data) {
+	const labels = {};
+	const unset = [];
+	const owns = [];
+	if (data.priority === 0 || data.priorityLabel === "No priority") unset.push("priority");
+	else if (data.priorityLabel && slug(data.priorityLabel)) labels.priority = slug(data.priorityLabel).slice(0, 256);
+	if (data.project?.name && slug(data.project.name)) labels.project = slug(data.project.name).slice(0, 256);
+	else if (data.project === null || data.projectId === null) unset.push("project");
+	if (Array.isArray(data.labels)) {
+		owns.push("tag.");
+		for (const label of data.labels) {
+			const tag = tagOf("tag", label.name);
+			if (tag) labels[tag[0]] = tag[1];
+		}
+	}
+	if (data.assignee) {
+		owns.push("assignee.");
+		const tag = tagOf("assignee", handleOf(data.assignee));
+		if (tag) labels[tag[0]] = tag[1];
+	} else if (data.assignee === null || data.assigneeId === null) owns.push("assignee.");
+	return {
+		labels,
+		unset,
+		owns
+	};
+}
 /** The copy of an issue the board opened: the issue itself, not a comment. */
 const OPENED = "issue";
 /** A root's copy: one the board opened, or imported (`lifecycle:<event>`, `root:<event>`). Comment IDs are UUIDs. */
@@ -52,6 +88,51 @@ function titleOf(markdown) {
 function stateOf(state) {
 	return state?.type ?? state?.name?.toLowerCase() ?? null;
 }
+const ISSUE_FIELDS = `id identifier title description url createdAt priority priorityLabel
+  state { name } assignee { name displayName url } creator { name displayName url } project { name }
+  labels(first: 10) { nodes { name } }`;
+const ISSUES_PER_PAGE = 100;
+const DESCRIPTION_IN_LIST = 1500;
+const MAX_COMMENTS = 1e3;
+/** What a read names: a project (by its link), a team (by its key), or an issue (by its ID or link). */
+function readTargetOf(target) {
+	const project = /\/project\/(?:[^/?#]*-)?([0-9a-f]{8,})(?:[/?#]|$)/i.exec(target);
+	if (project) return {
+		kind: "project",
+		slugId: project[1]
+	};
+	const issue = /(?:^|\/issue\/)([A-Z0-9_]+-\d+)(?:[/?#]|$)/i.exec(target.trim());
+	if (issue) return {
+		kind: "issue",
+		id: issue[1].toUpperCase()
+	};
+	if (/^[A-Z0-9_]+$/i.test(target.trim())) return {
+		kind: "team",
+		key: target.trim().toUpperCase()
+	};
+	throw new UnreadableError("invalid_target", `can't read ${target} from Linear: name a project by its link, a team by its key (ENG), or an issue (ENG-123)`);
+}
+/** An issue as a read shows it: its title, its properties on one line, its link, and what it says. */
+function issueMessage(issue, descriptionMax) {
+	const properties = [
+		issue.state?.name,
+		issue.priority ? issue.priorityLabel : void 0,
+		issue.assignee ? `assigned to ${handleOf(issue.assignee)}` : "unassigned",
+		issue.project?.name,
+		...(issue.labels?.nodes ?? []).map((label) => label.name)
+	].filter(Boolean);
+	const description = bodyOf(issue.description);
+	const shown = description && descriptionMax !== null && description.length > descriptionMax ? `${description.slice(0, descriptionMax)}…` : description;
+	return {
+		id: issue.identifier,
+		thread: issue.identifier,
+		author: handleOf(issue.creator ?? void 0) ?? "unknown",
+		text: [`${issue.identifier}: ${issue.title}\n${properties.join(" · ")}\n${issue.url}`, shown].filter(Boolean).join("\n\n"),
+		createdAt: issue.createdAt,
+		replies: issue.comments?.nodes.length ?? 0,
+		files: []
+	};
+}
 var LinearProvider = class extends ChatSyncProvider {
 	linear;
 	teamIds = /* @__PURE__ */ new Map();
@@ -133,13 +214,14 @@ var LinearProvider = class extends ChatSyncProvider {
 				const { data } = payload;
 				const created = payload.action === "create";
 				if (!created && payload.action !== "update") return [];
-				const retitled = payload.action === "update" && payload.updatedFrom?.title !== void 0;
+				const retitled = payload.action === "update" && (payload.updatedFrom?.title !== void 0 || payload.updatedFrom?.description !== void 0);
 				const team = data.team?.key ?? teamOf(data.identifier);
 				const state = stateOf(data.state);
 				const bot = adapter.defaultBotUserId;
 				const own = payload.actor?.id !== void 0 && payload.actor.id === bot;
 				const opens = created ? !own : !own && (bot === null || data.creatorId !== bot) && payload.actor?.type === "user" && !data.archivedAt;
 				const delivery = headers.get("linear-delivery") ?? `${payload.webhookId}:${payload.webhookTimestamp}`;
+				const properties = propertiesOf(data);
 				return [{
 					event: {
 						kind: "lifecycle",
@@ -148,11 +230,14 @@ var LinearProvider = class extends ChatSyncProvider {
 						type: created ? "issue.created" : "issue.updated",
 						title: `${data.identifier}: ${data.title}`,
 						url: data.url ?? payload.url ?? null,
+						body: bodyOf(data.description),
 						labels: {
 							issue: data.identifier,
-							...state ? { state } : {}
+							...state ? { state } : {},
+							...properties.labels
 						},
-						unset: [],
+						unset: properties.unset,
+						owns: properties.owns,
 						reply: null,
 						createRoot: opens,
 						...retitled ? { retitled: true } : {},
@@ -173,6 +258,84 @@ var LinearProvider = class extends ChatSyncProvider {
 		await this.ready();
 		return this.linear.isConnectMode() ? this.linear.withConnectClient(void 0, fn) : fn();
 	}
+	/**
+	* A project's or team's issues, newest first, or one issue and its comments, read on demand:
+	* nothing is synced or stored. `next` pages past a read's `limit`.
+	*/
+	async read(target, { limit, after }) {
+		const wanted = readTargetOf(target);
+		const query = (text, variables) => this.api(async () => (await this.client().client.rawRequest(text, variables)).data);
+		if (wanted.kind === "issue") {
+			let issue = null;
+			const comments = [];
+			let cursor = null;
+			do {
+				const data = await query(`query BoardReadIssue($id: String!, $first: Int!, $after: String) { issue(id: $id) { ${ISSUE_FIELDS}
+            comments(first: $first, after: $after) { nodes { id body createdAt user { name displayName url } } pageInfo { hasNextPage endCursor } } } }`, {
+					id: wanted.id,
+					first: ISSUES_PER_PAGE,
+					after: cursor
+				});
+				if (!data?.issue) throw new UnreadableError("channel_not_found", `no Linear issue ${wanted.id}`);
+				issue = data.issue;
+				comments.push(...issue.comments?.nodes ?? []);
+				const page = issue.comments?.pageInfo;
+				cursor = page?.hasNextPage ? page.endCursor ?? null : null;
+			} while (cursor !== null && comments.length < MAX_COMMENTS);
+			comments.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+			const from = after === null ? 0 : Math.max(0, Number.parseInt(after, 10) || 0);
+			const shown = comments.slice(from, from + Math.min(limit, ISSUES_PER_PAGE));
+			const to = from + shown.length;
+			return {
+				channel: teamOf(issue.identifier) ?? wanted.id,
+				name: null,
+				thread: issue.identifier,
+				messages: [...from === 0 ? [{
+					...issueMessage(issue, null),
+					replies: comments.length
+				}] : [], ...shown.map((comment) => ({
+					id: comment.id,
+					thread: issue.identifier,
+					author: handleOf(comment.user ?? void 0) ?? "unknown",
+					text: comment.body ?? "",
+					createdAt: comment.createdAt,
+					replies: 0,
+					files: []
+				}))],
+				more: to < comments.length,
+				next: to < comments.length ? String(to) : null
+			};
+		}
+		let filter;
+		let channel;
+		let name;
+		if (wanted.kind === "project") {
+			const project = (await query("query BoardReadProject($slugId: String!) { projects(filter: { slugId: { eq: $slugId } }, first: 1) { nodes { id name url } } }", { slugId: wanted.slugId }))?.projects.nodes[0];
+			if (!project) throw new UnreadableError("channel_not_found", `no Linear project ${target}`);
+			filter = { project: { id: { eq: project.id } } };
+			channel = project.url;
+			name = project.name;
+		} else {
+			await this.team(wanted.key);
+			filter = { team: { key: { eq: wanted.key } } };
+			channel = wanted.key;
+			name = null;
+		}
+		const issues = (await query(`query BoardReadIssues($filter: IssueFilter, $first: Int!, $after: String) {
+        issues(filter: $filter, first: $first, after: $after) { nodes { ${ISSUE_FIELDS} comments(first: 20) { nodes { id createdAt } } } pageInfo { hasNextPage endCursor } } }`, {
+			filter,
+			first: Math.min(limit, ISSUES_PER_PAGE),
+			after
+		}))?.issues;
+		return {
+			channel,
+			name,
+			thread: null,
+			messages: (issues?.nodes ?? []).map((issue) => issueMessage(issue, DESCRIPTION_IN_LIST)),
+			more: issues?.pageInfo.hasNextPage ?? false,
+			next: issues?.pageInfo.hasNextPage ? issues.pageInfo.endCursor ?? null : null
+		};
+	}
 	async resolveChannel(key) {
 		await this.team(key);
 		return key.toUpperCase();
@@ -207,10 +370,26 @@ var LinearProvider = class extends ChatSyncProvider {
 	async fetchRoot(thread) {
 		return this.api(async () => {
 			const issue = await this.client().issue(parseThread(thread).issue);
-			const [state, creator] = await Promise.all([issue.state, issue.creator]);
+			const [state, creator, project, assignee, tags] = await Promise.all([
+				issue.state,
+				issue.creator,
+				issue.project,
+				issue.assignee,
+				issue.labels?.()
+			]);
 			const found = stateOf(state);
+			const properties = propertiesOf({
+				id: issue.id,
+				identifier: issue.identifier,
+				title: issue.title,
+				priority: issue.priority,
+				priorityLabel: issue.priorityLabel,
+				project,
+				assignee,
+				labels: tags?.nodes
+			});
 			return {
-				text: `${issue.identifier}: ${issue.title}\n${issue.url}`,
+				text: [`${issue.identifier}: ${issue.title}\n${issue.url}`, bodyOf(issue.description)].filter(Boolean).join("\n\n"),
 				raw: { issue: {
 					id: issue.id,
 					identifier: issue.identifier,
@@ -220,7 +399,8 @@ var LinearProvider = class extends ChatSyncProvider {
 				author: author(creator, false),
 				labels: {
 					issue: issue.identifier,
-					...found ? { state: found } : {}
+					...found ? { state: found } : {},
+					...properties.labels
 				}
 			};
 		});

package/dist/sync-slack.d.mts

@@ -1,6 +1,6 @@
-import { f as ExternalLink } from "./folds-jS9wlh9_.mjs";
-import { C as channels, _ as withUserTokens, d as ResolvedTarget, f as SyncContext, h as UserTokens, o as ProviderPost, r as ProviderDelivery, y as SyncFn } from "./provider-Cdg1qadh.mjs";
-import { n as ChatSyncProvider, t as ChatInput } from "./chat-provider-DsNEBQiA.mjs";
+import { f as ExternalLink } from "./folds-ZkHM4M-v.mjs";
+import { C as channels, _ as withUserTokens, d as ResolvedTarget, f as SyncContext, h as UserTokens, o as ProviderPost, r as ProviderDelivery, y as SyncFn } from "./provider-DmSTp9lI.mjs";
+import { n as ChatSyncProvider, t as ChatInput } from "./chat-provider-BWHbChcQ.mjs";
 import { z } from "zod";
 import { Adapter } from "chat";
 //#region src/sync/slack.d.ts
@@ -67,6 +67,31 @@ export type SlackClient = {
     delete(args: {
       file: string;
     }): Promise<unknown>;
+    /** Uploads files and shares them in one message, with `initial_comment` as its text; needs `files:write`. */
+    uploadV2?(args: {
+      channel_id: string;
+      initial_comment: string;
+      file_uploads: {
+        file: Buffer;
+        filename: string;
+      }[];
+    }): Promise<{
+      files?: {
+        files?: {
+          id?: string;
+        }[];
+      }[];
+    }>;
+    /** Where a file was shared (`shares`), to find the message an upload made; needs `files:read`. */
+    info?(args: {
+      file: string;
+    }): Promise<{
+      file?: {
+        shares?: Partial<Record<'public' | 'private', Record<string, {
+          ts?: string;
+        }[]>>>;
+      };
+    }>;
   };
   /** Posts an agent's message under its own name; needs `chat:write.customize` for `username` and `icon_url`. */
   chat?: {
@@ -296,6 +321,7 @@ export declare const SlackEvent: z.ZodDiscriminatedUnion<[z.ZodObject<{
   type: z.ZodString;
   title: z.ZodString;
   url: z.ZodNullable<z.ZodString>;
+  body: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   labels: z.ZodRecord<z.ZodString, z.ZodString>;
   unset: z.ZodArray<z.ZodString>;
   owns: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -339,7 +365,7 @@ export type SlackOptions = {
 export declare function slack(app: string | SlackOptions, sync: SyncFn<SlackEvent>): SlackProvider;
 export declare class SlackProvider extends ChatSyncProvider<SlackEvent> {
   private readonly web;
-  private customize;
+  private scopes;
   constructor(given: SlackOptions, sync: SyncFn<SlackEvent>);
   /**
    * An agent's message goes out under its own name (`clever-lemur via vboard-factory`), and its
@@ -347,11 +373,21 @@ export declare class SlackProvider extends ChatSyncProvider<SlackEvent> {
    * `**name**: ` label dropped. Without `chat:write.customize` it posts as the app, label and all.
    */
   post(target: string, kind: ResolvedTarget['kind'], body: ProviderPost): Promise<ProviderDelivery>;
+  /**
+   * A new thread whose root shows its files under its text, as one message: Slack makes
+   * that message from an upload's `initial_comment`, and names it only on the file, a
+   * moment later. A file upload can't set a username, so it goes out as the app, label and all.
+   * Null, before anything is sent, where the client can't, or the app can't read files
+   * (`files:read`) to find that message.
+   */
+  private postWithFiles;
   /** An edit keeps the label out only where the message went out under the agent's name. */
   edit(thread: string, message: string, body: ProviderPost): Promise<void>;
   private postNamed;
-  /** Whether the app may set a message's username and icon (`chat:write.customize`), asked once. */
+  /** Whether the app may set a message's username and icon (`chat:write.customize`). */
   private canCustomize;
+  /** Whether the app has a scope, from its scopes, asked once. */
+  private hasScope;
   /** Whether a message Slack has went out under `name`. */
   private sentAs;
   /**

package/dist/sync-slack.mjs

@@ -1,9 +1,9 @@
-import { m as MESSAGE_TEXT_MAX } from "./schemas-Be08nyfW.mjs";
-import "./external-BV_cUncs.mjs";
-import { i as UnreadableError, s as channels } from "./provider-poIkXapd.mjs";
-import { i as eventSchema, r as envelope } from "./events-CewD4kw7.mjs";
+import { m as MESSAGE_TEXT_MAX } from "./schemas-DBmUO6pr.mjs";
+import "./external-D3p5T57R.mjs";
+import { i as UnreadableError, s as channels } from "./provider-BaVmi4Hi.mjs";
+import { i as eventSchema, r as envelope } from "./events-qf5XG5VQ.mjs";
 import { r as withUserTokens, t as connectUserTokens } from "./users-yryHKFMo.mjs";
-import { r as markdownOf, t as ChatSyncProvider } from "./chat-provider-DnHibqnM.mjs";
+import { r as markdownOf, t as ChatSyncProvider } from "./chat-provider-COtsU5jB.mjs";
 import { z } from "zod";
 import { stringifyMarkdown } from "chat";
 import { createSlackAdapter } from "@chat-adapter/slack";
@@ -220,6 +220,8 @@ const SlackEvent = eventSchema("slack", "message");
 function slack(app, sync) {
 	return new SlackProvider(typeof app === "string" ? { adapter: app } : app, sync);
 }
+/** How many times to look for the message an upload made, about 15 seconds in all. */
+const SHARE_POLLS = 10;
 /**
 * Slack's client retries 10 times over about 30 minutes by default, which outlives any function:
 * here a call gets 3 more tries. Each still waits out Slack's `Retry-After` (about a minute at
@@ -250,7 +252,7 @@ function fromConnector(connector) {
 }
 var SlackProvider = class extends ChatSyncProvider {
 	web;
-	customize;
+	scopes;
 	constructor(given, sync) {
 		const connected = typeof given.adapter === "string" ? fromConnector(given.adapter) : null;
 		const options = connected ? {
@@ -386,6 +388,7 @@ var SlackProvider = class extends ChatSyncProvider {
 			platform: "slack",
 			adapter: options.adapter,
 			canStartThreads: true,
+			startsThreadsWithFiles: true,
 			async uploadFiles(thread, files) {
 				const sent = await options.adapter.postMessage(thread, {
 					markdown: "",
@@ -681,8 +684,60 @@ var SlackProvider = class extends ChatSyncProvider {
 			...given,
 			markdown: withoutHtml(given.markdown)
 		};
+		if (kind === "channel" && post.files?.length && post.markdown.trim()) {
+			const sent = await this.postWithFiles(target, post.markdown, post.files);
+			if (sent) return sent;
+			const { files: _files, ...text } = post;
+			return (as ? await this.postNamed(target, as, text.markdown) : null) ?? super.post(target, kind, text);
+		}
 		return (as && !post.files?.length ? await this.postNamed(target, as, post.markdown) : null) ?? super.post(target, kind, post);
 	}
+	/**
+	* A new thread whose root shows its files under its text, as one message: Slack makes
+	* that message from an upload's `initial_comment`, and names it only on the file, a
+	* moment later. A file upload can't set a username, so it goes out as the app, label and all.
+	* Null, before anything is sent, where the client can't, or the app can't read files
+	* (`files:read`) to find that message.
+	*/
+	async postWithFiles(target, markdown, files) {
+		const adapter = await this.ready();
+		const web = await this.web();
+		const toMrkdwn = adapter.formatConverter?.toResponseUrlText;
+		if (!web?.files?.uploadV2 || !web.files.info || !toMrkdwn || !await this.hasScope(web, "files:read")) return null;
+		const threadId = this.toChat(target);
+		const { channel } = adapter.decodeThreadId(threadId);
+		const message = { markdown };
+		const resolved = await adapter.resolveMessageMentions?.(message, threadId) ?? message;
+		const ids = ((await web.files.uploadV2({
+			channel_id: channel,
+			initial_comment: toMrkdwn.call(adapter.formatConverter, resolved),
+			file_uploads: files.map((file) => ({
+				file: Buffer.from(file.data),
+				filename: slackFileName(file.filename, file.mimeType)
+			}))
+		})).files?.[0]?.files ?? []).map((file) => file.id).filter((id) => !!id);
+		const found = async () => {
+			for (let attempt = 0; attempt < SHARE_POLLS; attempt++) {
+				const shares = (await web.files.info({ file: ids[0] })).file?.shares;
+				const ts = shares?.public?.[channel]?.[0]?.ts ?? shares?.private?.[channel]?.[0]?.ts;
+				if (ts) return ts;
+				await new Promise((resolve) => setTimeout(resolve, Math.min(250 * 2 ** attempt, 2e3)));
+			}
+			throw new Error("never shared");
+		};
+		if (!ids[0]) throw new Error("slack: files.uploadV2 returned no file IDs");
+		let ts;
+		try {
+			ts = await found();
+		} catch (error) {
+			throw new Error(`slack: couldn't find the message uploading ${ids[0]} made in ${channel} (${slackError(error)})`);
+		}
+		return {
+			thread: this.toNative(`${adapter.name}:${channel}:${ts}`),
+			message: ts,
+			files: ids
+		};
+	}
 	/** An edit keeps the label out only where the message went out under the agent's name. */
 	async edit(thread, message, body) {
 		const { as, ...given } = body;
@@ -720,14 +775,18 @@ var SlackProvider = class extends ChatSyncProvider {
 			message: sent.ts
 		};
 	}
-	/** Whether the app may set a message's username and icon (`chat:write.customize`), asked once. */
+	/** Whether the app may set a message's username and icon (`chat:write.customize`). */
 	canCustomize(web) {
-		this.customize ??= (async () => (await web.auth?.test())?.response_metadata?.scopes?.includes("chat:write.customize") ?? false)().catch((error) => {
-			this.customize = void 0;
+		return this.hasScope(web, "chat:write.customize");
+	}
+	/** Whether the app has a scope, from its scopes, asked once. */
+	async hasScope(web, scope) {
+		this.scopes ??= (async () => (await web.auth?.test())?.response_metadata?.scopes ?? [])().catch((error) => {
+			this.scopes = void 0;
 			console.warn(`[board] slack: couldn't check the app's scopes (${slackError(error)}); posting as the app`);
-			return false;
+			return [];
 		});
-		return this.customize;
+		return (await this.scopes).includes(scope);
 	}
 	/** Whether a message Slack has went out under `name`. */
 	async sentAs(thread, message, name) {

package/dist/sync.chat.d.mts

@@ -1,2 +1,2 @@
-import { i as externalAuthor, n as ChatSyncProvider, r as ChatTransport, t as ChatInput } from "./chat-provider-DsNEBQiA.mjs";
+import { i as externalAuthor, n as ChatSyncProvider, r as ChatTransport, t as ChatInput } from "./chat-provider-BWHbChcQ.mjs";
 export { ChatInput, ChatSyncProvider, ChatTransport, externalAuthor };

package/dist/sync.chat.mjs

@@ -1,2 +1,2 @@
-import { n as externalAuthor, t as ChatSyncProvider } from "./chat-provider-DnHibqnM.mjs";
+import { n as externalAuthor, t as ChatSyncProvider } from "./chat-provider-COtsU5jB.mjs";
 export { ChatSyncProvider, externalAuthor };

package/dist/sync.d.mts

@@ -1,3 +1,3 @@
-import { d as ExternalFile, l as ExternalAuthor, u as ExternalEvent } from "./folds-jS9wlh9_.mjs";
-import { A as SyncOverrides, C as channels, D as EventBase, E as render, M as SyncRoot, N as envelope, O as ProviderEvent, P as eventSchema, S as SyncUnit, T as mirror, _ as withUserTokens, a as ProviderOptions, b as SyncIn, c as ReceivedEvent, d as ResolvedTarget, f as SyncContext, g as connectUserTokens, h as UserTokens, i as ProviderFile, j as SyncResult, k as RootOverride, l as RenderInput, m as UnreadableError, n as FileDelivery, o as ProviderPost, p as SyncProvider, r as ProviderDelivery, s as Receive, u as Renderer, v as Sync, w as into, x as SyncOut, y as SyncFn } from "./provider-Cdg1qadh.mjs";
+import { d as ExternalFile, l as ExternalAuthor, u as ExternalEvent } from "./folds-ZkHM4M-v.mjs";
+import { A as SyncOverrides, C as channels, D as EventBase, E as render, M as SyncRoot, N as envelope, O as ProviderEvent, P as eventSchema, S as SyncUnit, T as mirror, _ as withUserTokens, a as ProviderOptions, b as SyncIn, c as ReceivedEvent, d as ResolvedTarget, f as SyncContext, g as connectUserTokens, h as UserTokens, i as ProviderFile, j as SyncResult, k as RootOverride, l as RenderInput, m as UnreadableError, n as FileDelivery, o as ProviderPost, p as SyncProvider, r as ProviderDelivery, s as Receive, u as Renderer, v as Sync, w as into, x as SyncOut, y as SyncFn } from "./provider-DmSTp9lI.mjs";
 export { EventBase, type ExternalAuthor, ExternalEvent, type ExternalFile, type FileDelivery, type ProviderDelivery, type ProviderEvent, type ProviderFile, type ProviderOptions, type ProviderPost, type Receive, ReceivedEvent, type RenderInput, type Renderer, ResolvedTarget, type RootOverride, type Sync, type SyncContext, type SyncFn, type SyncIn, type SyncOut, SyncOverrides, SyncProvider, type SyncResult, type SyncRoot, type SyncUnit, UnreadableError, type UserTokens, channels, connectUserTokens, envelope, eventSchema, into, mirror, render, withUserTokens };

package/dist/sync.mjs

@@ -1,5 +1,5 @@
-import { n as ExternalEvent } from "./external-BV_cUncs.mjs";
-import { c as into, i as UnreadableError, l as mirror, n as ResolvedTarget, r as SyncProvider, s as channels, t as ReceivedEvent, u as render } from "./provider-poIkXapd.mjs";
-import { i as eventSchema, n as SyncOverrides, r as envelope, t as EventBase } from "./events-CewD4kw7.mjs";
+import { n as ExternalEvent } from "./external-D3p5T57R.mjs";
+import { c as into, i as UnreadableError, l as mirror, n as ResolvedTarget, r as SyncProvider, s as channels, t as ReceivedEvent, u as render } from "./provider-BaVmi4Hi.mjs";
+import { i as eventSchema, n as SyncOverrides, r as envelope, t as EventBase } from "./events-qf5XG5VQ.mjs";
 import { r as withUserTokens, t as connectUserTokens } from "./users-yryHKFMo.mjs";
 export { EventBase, ExternalEvent, ReceivedEvent, ResolvedTarget, SyncOverrides, SyncProvider, UnreadableError, channels, connectUserTokens, envelope, eventSchema, into, mirror, render, withUserTokens };

package/dist/tags-BpFo6q0_.mjs

@@ -0,0 +1,14 @@
+//#region src/sync/tags.ts
+/** `good first issue` → `good-first-issue`: the part of a label key a name gives. Empty when nothing's left. */
+const slug = (name) => name.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^[-_.]+|-+$/g, "");
+/**
+* A platform's label or assignee as a board label: `bug` → `tag.bug=bug`,
+* `julianbenegas` → `assignee.julianbenegas=julianbenegas`. The keys don't
+* name the platform, so a filter like `--label tag.bug` holds for any of them.
+*/
+function tagOf(prefix, name) {
+	const key = name ? slug(name) : "";
+	return key ? [`${prefix}.${key}`.slice(0, 64), name.slice(0, 256)] : null;
+}
+//#endregion
+export { tagOf as n, slug as t };

package/dist/{targets-C-wdR5wP.mjs → targets-Cgjs29T0.mjs}

@@ -1,4 +1,4 @@
-import { l as isThreadTarget } from "./external-BV_cUncs.mjs";
+import { l as isThreadTarget } from "./external-D3p5T57R.mjs";
 import { n as replaceMentions, t as extractMentions } from "./mentions-CB6ShY4R.mjs";
 //#region src/server/targets.ts
 /** A target as a post or a receipt names it, resolved: a plain one's kind goes by its shape. */

package/dist/{tokens-BuCU-61R.mjs → tokens-CC3izSNr.mjs}

@@ -1,5 +1,5 @@
 import { l as unauthorized } from "./errors-CusN4x2l.mjs";
-import { f as markVerified, m as trustedIssuers, n as TOKENS, r as VERCEL_ISSUER, u as issuerName } from "./auth-lTkOgvcE.mjs";
+import { f as markVerified, m as trustedIssuers, n as TOKENS, r as VERCEL_ISSUER, u as issuerName } from "./auth-JO22iIwr.mjs";
 import { createRemoteJWKSet, decodeJwt, jwtVerify } from "jose";
 //#region src/server/identity.ts
 let fromDisk;

package/dist/{types-aCAf6lGU.d.mts → types-No0WdhE5.d.mts}

@@ -1,4 +1,4 @@
-import { a as ExternalCopy, c as SyncedThread, g as BoardEvent, o as Message } from "./folds-jS9wlh9_.mjs";
+import { a as ExternalCopy, c as SyncedThread, g as BoardEvent, o as Message } from "./folds-ZkHM4M-v.mjs";
 import { t as A2Store } from "./store-D0MhBvg6-4Z2L0Kqd.mjs";
 //#region src/store/types.d.ts
 /**

package/dist/{watchers-hash-7DJU9b-n.mjs → watchers-hash-BDhLVkV5.mjs}

@@ -1,8 +1,8 @@
 import { n as DIRECT_UPLOAD_BYTES_MAX, t as ATTACHMENT_BYTES_MAX } from "./files-SniSmeEr.mjs";
-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 { 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-DBmUO6pr.mjs";
+import { a as Link, i as ExternalTarget, n as ExternalEvent, o as Origin, t as ExternalAuthor } from "./external-D3p5T57R.mjs";
 import { r as badRequest, t as HttpError } from "./errors-CusN4x2l.mjs";
-import { o as options } from "./commands-BFookFtn.mjs";
+import { o as options } from "./commands-C3R1AWgm.mjs";
 import { z } from "zod";
 //#region src/api/routes.ts
 /**
@@ -172,7 +172,9 @@ const AckBody = z.object({
 */
 const SourceReadQuery = z.object({
 	target: z.string().min(1).max(4e3),
-	limit: z.coerce.number().int().min(1).max(200).optional()
+	limit: z.coerce.number().int().min(1).max(200).optional(),
+	/** Where the last read left off: its `next`. */
+	after: z.string().min(1).max(400).optional()
 });
 /** A channel to add the board's app to, so it can be read on demand: `#name`, an ID, or a link into it. */
 const SourceJoinBody = z.object({ target: z.string().min(1).max(4e3) });
@@ -662,7 +664,7 @@ const routes = {
 const SYNC = "@sync";
 //#endregion
 //#region src/version.ts
-const VERSION = "0.28.0";
+const VERSION = "0.29.0";
 //#endregion
 //#region src/server/routing.ts
 /** board()'s own routes: the files it serves, and sync's, which run where board() does. */

package/docs/02-sync/03-slack.md

@@ -156,8 +156,12 @@ who can see it there:
 📎 [shot.png](https://files.slack.com/…) (7 B) didn't come over: this board keeps no files
 ```
 
-**To Slack:** the text posts first, then the files upload into the same thread as a
-message of their own (it needs `files:write`). A failed upload retries alone, and
+**To Slack:** a new thread's root goes out as one message, its files under its text
+(it needs `files:write`, and `files:read` to find the message the upload made;
+without `files:read`, the files follow in a message of their own). A
+file upload can't set a username, so that root goes out as the app, with the
+agent's name in front. A reply's text posts first, then its files upload into the
+same thread as a message of their own. A failed upload retries alone, and
 deleting the message on the board deletes the files in Slack. If Slack refuses
 files, the text is edited to add a line per file:
 

package/docs/02-sync/07-linear.md

@@ -46,13 +46,16 @@ in the map stays off the board, except threads someone syncs by hand.
 ## An issue's life in one thread
 
 1. **An issue opens.** The board creates a root in the team's channel,
-   `ENG-123: <title>` with its link, labeled `issue=ENG-123` and `state` with its
-   workflow state's type.
+   `ENG-123: <title>` with its link and, under them, its description. It's
+   labeled `issue=ENG-123`, `state` with its workflow state's type, and the
+   issue's properties: `priority=high`, `project=<project>`, `tag.<label>` for
+   each Linear label, and `assignee.<handle>`.
 2. **Comments** arrive as replies. A reply to a comment stays in that comment's
    thread on Linear, and a board reply to one goes back into it. Edits and
    deletes sync too.
-3. **Moving the issue** to another state updates `state`. A new title edits a
-   root that Linear opened to say it. An issue that was open before the mirror
+3. **Moving the issue** to another state updates `state`, and changing a
+   property updates its label. A new title or description edits a root that
+   Linear opened to say it. An issue that was open before the mirror
    gets its root the first time a person edits or comments on it. Linear's own
    automations and archiving don't bring old issues in.
 4. **A root posted on the board** in a mirrored channel opens an issue in that
@@ -79,8 +82,8 @@ the board follows the team it's in now. The old thread stays as it was.
 
 | Event | What the mirror does |
 | --- | --- |
-| `issue.created` | A root labeled `issue=ENG-123` and `state=<type>` |
-| `issue.updated` | A new state sets `state`; a new title edits a root Linear opened. A person's edit to an issue the board hasn't seen opens its root, so older issues come in when they're next touched (a bulk edit brings in a whole view). Automations and archiving don't |
+| `issue.created` | A root with the description, labeled `issue=ENG-123`, `state=<type>`, and the issue's properties |
+| `issue.updated` | A new state sets `state`, and properties update their labels; a new title or description edits a root Linear opened. A person's edit to an issue the board hasn't seen opens its root, so older issues come in when they're next touched (a bulk edit brings in a whole view). Automations and archiving don't |
 | `comment` | A reply. Edits and deletes sync too |
 
 `state` is the workflow state's type: `triage`, `backlog`, `unstarted`,
@@ -96,6 +99,25 @@ A comment on an issue that opened before you mapped its team still lands: the
 board fetches the issue through Linear's API, creates its root, then posts the
 comment as a reply.
 
+## Read on demand
+
+`vb sources <key> read` reads Linear without syncing anything, so an agent can
+work through a project's issues without a thread for each one:
+
+```bash
+vb sources linear read https://linear.app/acme/project/checkout-a1b2c3d4e5f6   # a project's issues
+vb sources linear read ENG                                                     # a team's issues
+vb sources linear read ENG-123                                                 # one issue and its comments
+```
+
+A project or team read lists issues newest first, each with its state,
+priority, assignee, project, labels, link, and description (cut at 1,500
+characters). An issue read shows the whole description, then its comments,
+oldest first. A page holds at most 100 issues or comments: when there are more,
+the read ends with the `--after` cursor that reads the next page. It reads with
+the Linear app's token, so it needs `manage` in every channel, as every source
+read does.
+
 ## Reactions
 
 A reaction on the board goes to its comment on Linear, while it's added: Linear