@vercel/board 0.21.1 → 0.22.0

package/dist/commands-D_ODblQY.mjs

@@ -0,0 +1,770 @@
+//#region src/cli/commands.ts
+/** Every option, by name: what the parser accepts, and what each means where a command doesn't say more. */
+const options = {
+	re: {
+		type: "string",
+		value: "id",
+		description: "in a thread: its root's ID"
+	},
+	by: {
+		type: "string",
+		value: "handle",
+		description: "by an author: a handle, me, or an actor ID"
+	},
+	mentions: {
+		type: "string",
+		value: "@handle",
+		optionalValue: true,
+		description: "mentioning a handle, or you without one"
+	},
+	label: {
+		type: "string",
+		multiple: true,
+		value: "k[=v|w]",
+		description: "with a label on the message or its thread's root"
+	},
+	from: {
+		type: "string",
+		value: "source",
+		description: "from a source: a sync key such as slack, or board"
+	},
+	text: {
+		type: "string",
+		value: "words",
+		description: "containing these words"
+	},
+	after: {
+		type: "string",
+		value: "id",
+		description: "after a message or a cursor"
+	},
+	url: {
+		type: "string",
+		value: "url",
+		description: "the board at this URL, not the one the environment points at"
+	},
+	scope: {
+		type: "string",
+		value: "team",
+		description: "a team's board in Vercel's API, by its slug or ID"
+	},
+	team: {
+		type: "string",
+		value: "team",
+		description: "the same as --scope",
+		hidden: true
+	},
+	as: {
+		type: "string",
+		value: "profile",
+		description: "write as a profile, such as an agent's name"
+	},
+	avatar: {
+		type: "string",
+		value: "url",
+		description: "the profile's avatar, with --as"
+	},
+	human: {
+		type: "boolean",
+		description: "write as yourself, with no profile or session"
+	},
+	handle: {
+		type: "string",
+		value: "h",
+		description: "your handle (default: your Vercel username)"
+	},
+	json: {
+		type: "boolean",
+		description: "one JSON object per line, for programs"
+	},
+	help: {
+		type: "boolean",
+		short: "h",
+		description: "this help, or a command's"
+	},
+	version: {
+		type: "boolean",
+		short: "v",
+		description: "the CLI's version"
+	},
+	limit: {
+		type: "string",
+		short: "n",
+		value: "N",
+		description: "how many"
+	},
+	id: {
+		type: "string",
+		value: "key",
+		description: "a client ID: sending the same one again posts once"
+	},
+	sync: {
+		type: "string",
+		multiple: true,
+		value: "target",
+		description: "sync the new thread to a target too, e.g. slack:#incidents"
+	},
+	"no-sync": {
+		type: "boolean",
+		description: "keep it on the board: sync it nowhere"
+	},
+	attach: {
+		type: "string",
+		multiple: true,
+		value: "file",
+		description: "attach a file"
+	},
+	unset: {
+		type: "string",
+		multiple: true,
+		value: "k",
+		description: "remove a label"
+	},
+	channel: {
+		type: "string",
+		value: "c",
+		description: "in a channel"
+	},
+	remove: {
+		type: "boolean",
+		description: "take the reaction back"
+	},
+	all: {
+		type: "boolean",
+		short: "a",
+		description: "everything, not only what most want"
+	},
+	timeout: {
+		type: "string",
+		value: "duration",
+		description: "how long to wait (default: 30m)"
+	},
+	code: {
+		type: "boolean",
+		description: "post a code from your account instead of signing in"
+	},
+	"no-wait": {
+		type: "boolean",
+		description: "start linking, and don't wait for it to finish"
+	},
+	"no-open": {
+		type: "boolean",
+		description: "don't open the browser"
+	},
+	in: {
+		type: "string",
+		value: "duration",
+		description: "once, this long from now, e.g. 1d"
+	},
+	at: {
+		type: "string",
+		value: "time",
+		description: "at a time: once, or with --every, the first"
+	},
+	every: {
+		type: "string",
+		value: "duration",
+		description: "repeating at this interval, e.g. 30m"
+	},
+	until: {
+		type: "string",
+		short: "u",
+		value: "time",
+		description: "repeating until a time"
+	},
+	for: {
+		type: "string",
+		value: "duration",
+		description: "repeating for this long, e.g. 24h"
+	},
+	times: {
+		type: "string",
+		value: "N",
+		description: "repeating this many times"
+	},
+	port: {
+		type: "string",
+		value: "N",
+		description: "the port to listen on"
+	},
+	dir: {
+		type: "string",
+		value: "dir",
+		description: "where the board keeps its log (default: .board/)"
+	},
+	"no-inspect": {
+		type: "boolean",
+		description: "don't start the inspector"
+	},
+	agent: {
+		type: "string",
+		value: "name",
+		description: "the agent whose turn ended",
+		hidden: true
+	}
+};
+/** The option `name`, saying `description` (and taking `value`) where it means something particular to a command. */
+const option = (name, description, value) => ({
+	name,
+	...options[name],
+	...description ? { description } : {},
+	...value ? { value } : {}
+});
+/** What `read`, `tail`, and `wait` match: every one given must hold. */
+const filters = [
+	"re",
+	"by",
+	"from",
+	"label",
+	"text",
+	"mentions",
+	"after"
+].map((name) => option(name));
+/** What every command takes. */
+const globalOptions = [
+	"url",
+	"scope",
+	"team",
+	"as",
+	"avatar",
+	"human",
+	"handle",
+	"json",
+	"help",
+	"version"
+].map((name) => option(name));
+const id = (description = "a message ID, as read shows it (#812)") => ({
+	name: "id",
+	required: true,
+	description
+});
+const text = (description = "what it says: - reads it from stdin, and it may be left out when you --attach") => ({
+	name: "text",
+	required: false,
+	description
+});
+/** What one of the CLI's help pages lists together, in this order. */
+const groups = [
+	"you",
+	"the board",
+	"messages",
+	"agents",
+	"live"
+];
+/** Board's commands, by `groups`, in the order its help lists them. */
+const commands = [
+	{
+		group: "you",
+		name: "whoami",
+		description: "who am I, on which board, with which token, and what I can do",
+		arguments: [],
+		options: [],
+		examples: [{
+			name: "see who you are on the board",
+			value: "whoami"
+		}]
+	},
+	{
+		group: "you",
+		name: "link",
+		description: "link this project to a board (.board/config.json)",
+		arguments: [{
+			name: "url",
+			required: true,
+			description: "the board's URL"
+		}],
+		options: [],
+		examples: [{
+			name: "link this project to a team's board",
+			value: "link https://www.example.com/api/board"
+		}]
+	},
+	{
+		group: "you",
+		name: "use",
+		description: "save the default board",
+		arguments: [{
+			name: "url",
+			required: true,
+			description: "the board's URL"
+		}],
+		options: [],
+		examples: [{
+			name: "use a board everywhere nothing else is linked",
+			value: "use https://www.example.com/api/board"
+		}]
+	},
+	{
+		group: "the board",
+		name: "channels",
+		description: "channels, grouped by path prefix",
+		arguments: [],
+		options: [],
+		examples: [{
+			name: "list the channels",
+			value: "channels"
+		}]
+	},
+	{
+		group: "the board",
+		name: "actors",
+		description: "actors and their handles",
+		arguments: [],
+		options: [],
+		examples: [{
+			name: "list who has written here",
+			value: "actors"
+		}]
+	},
+	{
+		group: "the board",
+		name: "identity",
+		description: "your linked Slack and GitHub accounts",
+		arguments: [],
+		options: [],
+		runsWithoutSubcommand: true,
+		examples: [{
+			name: "list your linked accounts",
+			value: "identity"
+		}],
+		subcommands: [{
+			name: "link",
+			description: "link your account on a sync entry: sign in, or post a code from it",
+			arguments: [{
+				name: "key",
+				required: true,
+				description: "the sync entry, e.g. slack"
+			}],
+			options: [
+				option("code"),
+				option("no-wait"),
+				option("no-open")
+			],
+			examples: [{
+				name: "link your Slack account",
+				value: "identity link slack"
+			}]
+		}, {
+			name: "unlink",
+			description: "unlink one, by handle or actor ID",
+			arguments: [{
+				name: "account",
+				required: true,
+				description: "a handle or actor ID from identity"
+			}],
+			options: [],
+			examples: [{
+				name: "unlink an account",
+				value: "identity unlink @ada"
+			}]
+		}]
+	},
+	{
+		group: "messages",
+		name: "read",
+		description: "the latest threads, one each (root, replies, latest reply), or one thread, every message",
+		arguments: [{
+			name: "channel|id|link",
+			required: false,
+			description: "a channel (every channel without one), a message's ID, or a Slack or GitHub link the board synced"
+		}],
+		options: [option("limit", "threads to list (default: 50)")],
+		filters: true,
+		examples: [
+			{
+				name: "list a channel's latest threads",
+				value: "read dev"
+			},
+			{
+				name: "read one thread, every message",
+				value: "read 812"
+			},
+			{
+				name: "list the open bugs",
+				value: "read dev --label kind=bug --label state=open"
+			}
+		]
+	},
+	{
+		group: "messages",
+		name: "post",
+		description: "a new thread in a channel, or with an ID, a reply in its thread",
+		arguments: [{
+			name: "channel|id",
+			required: true,
+			description: "a channel, or a message ID to reply in its thread"
+		}, text()],
+		options: [
+			option("label", "label it", "k=v"),
+			option("attach"),
+			option("sync"),
+			option("no-sync"),
+			option("id")
+		],
+		examples: [{
+			name: "start a thread",
+			value: "post dev \"deploys are green again\""
+		}, {
+			name: "start a labeled thread",
+			value: "post dev \"checkout times out\" --label kind=bug"
+		}]
+	},
+	{
+		group: "messages",
+		name: "reply",
+		description: "a reply in a thread",
+		arguments: [id("the ID of a message in the thread"), text()],
+		options: [
+			option("attach"),
+			option("id"),
+			option("no-sync")
+		],
+		examples: [{
+			name: "reply in a thread",
+			value: "reply 812 \"on it\""
+		}]
+	},
+	{
+		group: "messages",
+		name: "schedule",
+		description: "post later, as you: once (--in or --at), or repeating (--every) until a stop or until canceled",
+		arguments: [{
+			name: "channel|id",
+			required: true,
+			description: "a channel, or a message ID to reply in its thread"
+		}, text()],
+		options: [
+			option("in"),
+			option("at"),
+			option("every"),
+			option("until"),
+			option("for"),
+			option("times"),
+			option("label", "label it", "k=v"),
+			option("attach"),
+			option("no-sync")
+		],
+		examples: [{
+			name: "reply in a thread tomorrow",
+			value: "schedule 812 \"still broken?\" --in 1d"
+		}, {
+			name: "post every morning",
+			value: "schedule dev \"standup\" --at 2026-11-02T09:00:00Z --every 1d"
+		}],
+		runsWithoutSubcommand: true,
+		subcommands: [{
+			name: "cancel",
+			description: "stop one (yours, or with manage)",
+			arguments: [{
+				name: "schedule",
+				required: true,
+				description: "its ID, as schedules shows it (s12)"
+			}],
+			options: [],
+			examples: [{
+				name: "cancel a schedule",
+				value: "schedule cancel s12"
+			}]
+		}]
+	},
+	{
+		group: "messages",
+		name: "schedules",
+		description: "pending schedules, or a thread's with an ID",
+		arguments: [{
+			name: "id",
+			required: false,
+			description: "a message in the thread"
+		}],
+		options: [
+			option("by", "scheduled by a handle"),
+			option("channel", "posting in a channel"),
+			option("all", "done and canceled ones too")
+		],
+		examples: [{
+			name: "list pending schedules",
+			value: "schedules"
+		}]
+	},
+	{
+		group: "messages",
+		name: "edit",
+		description: "change a message's text",
+		arguments: [id(), {
+			name: "text",
+			required: true,
+			description: "its new text: - reads it from stdin"
+		}],
+		options: [],
+		examples: [{
+			name: "fix a typo",
+			value: "edit 812 \"deploys are green again\""
+		}]
+	},
+	{
+		group: "messages",
+		name: "delete",
+		aliases: ["rm", "del"],
+		description: "delete a message, leaving a tombstone",
+		arguments: [id()],
+		options: [],
+		examples: [{
+			name: "delete a message",
+			value: "delete 812"
+		}]
+	},
+	{
+		group: "messages",
+		name: "react",
+		description: "react to a message",
+		arguments: [id(), {
+			name: "emoji",
+			required: true,
+			description: "its name or the emoji itself: eyes, 👀"
+		}],
+		options: [option("remove")],
+		examples: [{
+			name: "react with eyes",
+			value: "react 812 eyes"
+		}]
+	},
+	{
+		group: "messages",
+		name: "label",
+		description: "set labels on a message, or remove them",
+		arguments: [id(), {
+			name: "k=v",
+			required: false,
+			multiple: true,
+			description: "a label to set"
+		}],
+		options: [option("unset")],
+		examples: [{
+			name: "mark a bug fixed",
+			value: "label 812 state=fixed --unset wip"
+		}]
+	},
+	{
+		group: "messages",
+		name: "typing",
+		description: "show typing in the thread's synced platform threads (marks WhatsApp read)",
+		arguments: [id(), {
+			name: "status",
+			required: false,
+			description: "what Slack shows instead of \"Typing…\""
+		}],
+		options: [],
+		examples: [{
+			name: "show typing while you work",
+			value: "typing 812 \"looking into it\""
+		}]
+	},
+	{
+		group: "messages",
+		name: "sync",
+		description: "where the thread is synced, or with a target, attach it there (backfilling it)",
+		arguments: [id(), {
+			name: "target",
+			required: false,
+			description: "where to sync it, e.g. slack:#incidents"
+		}],
+		options: [],
+		examples: [{
+			name: "list where a thread is synced",
+			value: "sync 812"
+		}, {
+			name: "sync a thread to a Slack channel",
+			value: "sync 812 slack:#incidents"
+		}]
+	},
+	{
+		group: "messages",
+		name: "inbox",
+		description: "raw platform events, for debugging sync",
+		arguments: [{
+			name: "key",
+			required: true,
+			description: "the sync entry, e.g. slack"
+		}, {
+			name: "channel",
+			required: false,
+			description: "the board channel its events went to"
+		}],
+		options: [option("limit", "events to list")],
+		examples: [{
+			name: "list Slack's latest events",
+			value: "inbox slack"
+		}]
+	},
+	{
+		group: "messages",
+		name: "sources",
+		description: "the board's sources: its sync entries (slack, github, …)",
+		arguments: [{
+			name: "key",
+			required: false,
+			description: "a sync entry, e.g. slack"
+		}],
+		options: [],
+		runsWithoutSubcommand: true,
+		argumentsBeforeSubcommand: true,
+		examples: [{
+			name: "list the board's sources",
+			value: "sources"
+		}],
+		subcommands: [{
+			name: "read",
+			description: "read a source's channel, thread, or message link without syncing it (full access only)",
+			arguments: [{
+				name: "target",
+				required: true,
+				description: "a channel ('#general'), a thread, or a message link"
+			}],
+			options: [option("limit", "messages to read")],
+			examples: [{
+				name: "read a Slack channel",
+				value: "sources slack read '#general'"
+			}]
+		}, {
+			name: "join",
+			description: "add the app to a public channel so it can be read, where the board opted in (full access only)",
+			arguments: [{
+				name: "channel",
+				required: true,
+				description: "a channel or its link"
+			}],
+			options: [],
+			examples: [{
+				name: "join a Slack channel",
+				value: "sources slack join '#general'"
+			}]
+		}]
+	},
+	{
+		group: "messages",
+		name: "download",
+		description: "save an attachment (its name, here, by default; - for stdout)",
+		arguments: [{
+			name: "attachment",
+			required: true,
+			description: "the ID read shows on a file line"
+		}, {
+			name: "path",
+			required: false,
+			description: "where to save it, or - for stdout"
+		}],
+		options: [],
+		examples: [{
+			name: "save an attachment",
+			value: "download Yt2mR8vQ1x0pLk3sF7dA9w"
+		}]
+	},
+	{
+		group: "messages",
+		name: "conformance",
+		description: "check that the board speaks the protocol (1 if a check fails): it posts, and deletes what it posted",
+		arguments: [],
+		options: [option("channel", "the channel to check in (default: conformance)")],
+		examples: [{
+			name: "check the board",
+			value: "conformance"
+		}]
+	},
+	{
+		group: "agents",
+		name: "hooks",
+		description: "the turn-end hooks an earlier board installed",
+		arguments: [],
+		options: [],
+		examples: [],
+		subcommands: [{
+			name: "uninstall",
+			description: "remove the turn-end hooks an earlier board installed, from every agent or the ones named",
+			arguments: [{
+				name: "agent",
+				required: false,
+				multiple: true,
+				description: "claude, codex, cursor, or pi"
+			}],
+			options: [],
+			examples: [{
+				name: "remove every hook",
+				value: "hooks uninstall"
+			}]
+		}]
+	},
+	{
+		group: "agents",
+		name: "hook",
+		description: "what an earlier turn-end hook runs: it does nothing now",
+		arguments: [{
+			name: "event",
+			required: false,
+			multiple: true
+		}],
+		options: [option("agent")],
+		examples: [],
+		hidden: true
+	},
+	{
+		group: "live",
+		name: "tail",
+		description: "what happens, live, until Ctrl-C",
+		arguments: [{
+			name: "channel",
+			required: false,
+			description: "a channel, or a path prefix (dev/)"
+		}],
+		options: [option("all", "delivery receipts too")],
+		filters: true,
+		examples: [{
+			name: "follow the bugs",
+			value: "tail dev --label kind=bug"
+		}]
+	},
+	{
+		group: "live",
+		name: "wait",
+		description: "block for the next match, print it, then exit (124 on timeout)",
+		arguments: [{
+			name: "channel",
+			required: false,
+			description: "a channel, or a path prefix (dev/)"
+		}],
+		options: [option("timeout")],
+		filters: true,
+		examples: [{
+			name: "wait for a mention",
+			value: "wait dev --mentions --timeout 10m"
+		}]
+	},
+	{
+		group: "live",
+		name: "help",
+		description: "this help, or a command's",
+		arguments: [{
+			name: "command",
+			required: false,
+			multiple: true
+		}],
+		options: [],
+		examples: [],
+		hidden: true
+	}
+];
+/** One line of `usage`: a command's path and its arguments, as `<required>` and `[optional]`. */
+function usage(path) {
+	const words = [];
+	path.forEach((command, at) => {
+		const last = at === path.length - 1;
+		words.push(command.name);
+		if (last || command.argumentsBeforeSubcommand) for (const argument of command.arguments) {
+			const required = argument.required || !last;
+			words.push(`${required ? `<${argument.name}>` : `[${argument.name}]`}${argument.multiple ? "..." : ""}`);
+		}
+	});
+	if (path.at(-1)?.filters) words.push("[filters]");
+	return words.join(" ");
+}
+//#endregion
+export { option as a, groups as i, filters as n, options as o, globalOptions as r, usage as s, commands as t };