@rcpooley/botyard 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# botyard
+
+Read and send in Discord through your own bot, hosted by
+[Botyard](https://botyard.rcpooley.dev). Made for AI agents like Claude Code,
+and fine for people too.
+
+```sh
+npm install -g @rcpooley/botyard     # Node 20 or newer
+```
+
+## Connecting
+
+You don't type a key. On your bot's page at Botyard, click **Connect an agent**,
+choose what the agent may do, and paste the prompt you get into your agent. It
+runs:
+
+```sh
+botyard connect byc_…
+```
+
+The code works once and expires in an hour. The CLI exchanges it for an API key
+and stores the key in `~/.config/botyard/config.json`, which only you can read.
+It never prints the key. Several bots can be connected; one is the default.
+
+## Using it
+
+Run `botyard` with no arguments for the full guide: the connected bots, every
+command, and the rules an agent should follow. A taste:
+
+```sh
+botyard servers
+botyard read "My Server" general --limit 20
+botyard send "My Server" general "hello from my agent"
+echo "multi-line text" | botyard send "My Server" general -
+botyard react "My Server" general 1234567890 👍
+```
+
+`--json` prints the raw API response. `--bot <name>` picks a bot.
+`botyard skill install` adds a Claude Code skill so future sessions know the CLI
+is there.
+
+For scripts, `BOTYARD_KEY` (and optionally `BOTYARD_URL`) overrides the stored
+config.
+
+## What it can't do
+
+Delete messages, kick, ban, or manage channels and roles. Botyard leaves those
+out on purpose. Each key is also limited to the permissions and servers its
+owner picked on Botyard, where it can be changed or revoked at any time.

package/dist/api.js

@@ -0,0 +1,53 @@
+/**
+ * The Botyard agent API, over fetch. Every failure becomes an Error whose
+ * message is the API's own sentence -- those are written for whoever is calling,
+ * so the CLI passes them on rather than inventing its own.
+ */
+export class ApiFailure extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** A wait Discord or Botyard asks for that is short enough to just sit out, once. */
+const MAX_RETRY_WAIT_S = 10;
+export async function call(url, key, method, path, body, retried = false) {
+    let res;
+    try {
+        res = await fetch(`${url.replace(/\/+$/, '')}/api/v1${path}`, {
+            method,
+            headers: {
+                ...(key ? { authorization: `Bearer ${key}` } : {}),
+                ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+                'user-agent': 'botyard-cli',
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (e) {
+        throw new ApiFailure(0, `Could not reach ${url}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (res.status === 429 && !retried) {
+        const wait = Number(res.headers.get('retry-after'));
+        if (Number.isFinite(wait) && wait > 0 && wait <= MAX_RETRY_WAIT_S) {
+            await new Promise((r) => setTimeout(r, wait * 1000));
+            return call(url, key, method, path, body, true);
+        }
+    }
+    const text = await res.text();
+    if (!res.ok) {
+        let message = `HTTP ${res.status}`;
+        try {
+            message = JSON.parse(text).error ?? message;
+        }
+        catch {
+            // Not JSON: something in front of Botyard answered. The status will do.
+        }
+        throw new ApiFailure(res.status, message);
+    }
+    return (text ? JSON.parse(text) : undefined);
+}
+/** A path segment from something a person typed: a name with spaces, a #channel, an emoji. */
+export const seg = (s) => encodeURIComponent(s);

package/dist/botyard.js

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { parseArgs } from 'node:util';
+import { ApiFailure, call, seg } from "./api.js";
+import { configPath, DEFAULT_URL, load, pickBot, save } from "./config.js";
+import * as fmt from "./format.js";
+import { installSkill, SKILL, skillDir, skillInstalled } from "./skill.js";
+/**
+ * botyard: Discord through Botyard, from a terminal. Made for AI agents first,
+ * so the guide (no arguments, or --help) is written to one, and every error is
+ * a sentence saying what to do next.
+ *
+ * One table of commands drives dispatch, the guide and per-command help, so
+ * none of them can describe a command the others do not know.
+ */
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+// --- what a command needs --------------------------------------------------
+/** The bot to act as: BOTYARD_KEY wins (for scripts), then --bot, then the default. */
+function target(opts) {
+    if (process.env.BOTYARD_KEY)
+        return { url: process.env.BOTYARD_URL || DEFAULT_URL, key: process.env.BOTYARD_KEY, bot: null };
+    const bot = pickBot(load(), opts.bot);
+    return { url: bot.url, key: bot.key, bot };
+}
+async function api(opts, method, path, body) {
+    const { url, key } = target(opts);
+    return call(url, key, method, path, body);
+}
+const json = (value) => JSON.stringify(value, null, 2);
+/** Message text: the words given, or stdin when the text is "-". */
+function text(raw) {
+    if (raw !== '-')
+        return raw;
+    const input = readFileSync(0, 'utf8');
+    return input.endsWith('\n') ? input.slice(0, -1) : input;
+}
+function where(server, channel) {
+    return `/servers/${seg(server)}/channels/${seg(channel.replace(/^#/, ''))}`;
+}
+// --- the commands ------------------------------------------------------------
+const COMMANDS = [
+    {
+        name: 'me',
+        group: 'Reading',
+        usage: 'me',
+        summary: 'which bot this is, what it may do, and the servers it can reach',
+        args: 0,
+        run: async (_a, opts) => {
+            const m = await api(opts, 'GET', '/me');
+            return opts.json ? json(m) : fmt.me(m);
+        },
+    },
+    {
+        name: 'servers',
+        group: 'Reading',
+        usage: 'servers',
+        summary: 'servers you can reach',
+        args: 0,
+        run: async (_a, opts) => {
+            const list = await api(opts, 'GET', '/servers');
+            return opts.json ? json(list) : fmt.servers(list);
+        },
+    },
+    {
+        name: 'channels',
+        group: 'Reading',
+        usage: 'channels <server>',
+        summary: 'channels and active threads in a server',
+        args: 1,
+        run: async ([server], opts) => {
+            const list = await api(opts, 'GET', `/servers/${seg(server)}/channels`);
+            return opts.json ? json(list) : fmt.channels(list);
+        },
+    },
+    {
+        name: 'read',
+        group: 'Reading',
+        usage: 'read <server> <channel> [--limit 50] [--before <message id>]',
+        summary: 'recent messages, oldest first',
+        details: ['--limit is 1-100 (default 50). When there are older messages, the output ends with the command for the next page.'],
+        args: 2,
+        run: async ([server, channel], opts) => {
+            const q = new URLSearchParams();
+            if (opts.limit)
+                q.set('limit', opts.limit);
+            if (opts.before)
+                q.set('before', opts.before);
+            const res = await api(opts, 'GET', `${where(server, channel)}/messages${q.size ? `?${q}` : ''}`);
+            if (opts.json)
+                return json(res);
+            const more = res.older ? `Older: botyard read ${quote(server)} ${quote(channel)} --before ${res.older}` : null;
+            return fmt.messages(res.messages, `#${channel.replace(/^#/, '')} in ${server}`, more);
+        },
+    },
+    {
+        name: 'message',
+        group: 'Reading',
+        usage: 'message <server> <channel> <message id>',
+        summary: 'one message',
+        args: 3,
+        run: async ([server, channel, id], opts) => {
+            const m = await api(opts, 'GET', `${where(server, channel)}/messages/${seg(id)}`);
+            return opts.json ? json(m) : fmt.message(m);
+        },
+    },
+    {
+        name: 'pins',
+        group: 'Reading',
+        usage: 'pins <server> <channel>',
+        summary: 'pinned messages',
+        args: 2,
+        run: async ([server, channel], opts) => {
+            const res = await api(opts, 'GET', `${where(server, channel)}/pins`);
+            if (opts.json)
+                return json(res);
+            return fmt.messages(res.messages, `pins in #${channel.replace(/^#/, '')}`, res.more ? '(more pins not shown)' : null);
+        },
+    },
+    {
+        name: 'reactions',
+        group: 'Reading',
+        usage: 'reactions <server> <channel> <message id>',
+        summary: 'who reacted with what',
+        details: ['One Discord call per emoji, so use it when you need names; `read` already shows the counts.'],
+        args: 3,
+        run: async ([server, channel, id], opts) => {
+            const list = await api(opts, 'GET', `${where(server, channel)}/messages/${seg(id)}/reactions`);
+            return opts.json ? json(list) : fmt.reactions(list);
+        },
+    },
+    {
+        name: 'send',
+        group: 'Writing',
+        usage: 'send <server> <channel> <text | -> [--reply-to <id>] [--mentions users|none|all]',
+        summary: 'post a message ("-" reads the text from stdin)',
+        details: [
+            'Up to 2000 characters. Use "-" and pipe the text in for anything multi-line or full of quotes.',
+            'Mentions ping people by default, but @everyone, @here and roles go out as plain text.',
+            '--mentions all lets them ping; only use it when your human asked for exactly that. --mentions none pings nobody.',
+        ],
+        args: 3,
+        rest: true,
+        run: async ([server, channel, words], opts) => {
+            const body = { content: text(words), replyTo: opts['reply-to'], mentions: opts.mentions };
+            const m = await api(opts, 'POST', `${where(server, channel)}/messages`, body);
+            return opts.json ? json(m) : `Sent ${m.id}\n${m.url}`;
+        },
+    },
+    {
+        name: 'edit',
+        group: 'Writing',
+        usage: 'edit <server> <channel> <message id> <text | ->',
+        summary: "replace the text of one of the bot's own messages",
+        args: 4,
+        rest: true,
+        run: async ([server, channel, id, words], opts) => {
+            const m = await api(opts, 'PATCH', `${where(server, channel)}/messages/${seg(id)}`, { content: text(words), mentions: opts.mentions });
+            return opts.json ? json(m) : `Edited ${m.id}\n${m.url}`;
+        },
+    },
+    ...['pin', 'unpin'].map((name) => ({
+        name,
+        group: 'Writing',
+        usage: `${name} <server> <channel> <message id>`,
+        summary: name === 'pin' ? 'pin a message' : 'unpin a message',
+        args: 3,
+        run: async ([server, channel, id], opts) => {
+            await api(opts, name === 'pin' ? 'PUT' : 'DELETE', `${where(server, channel)}/messages/${seg(id)}/pin`);
+            return `${name === 'pin' ? 'Pinned' : 'Unpinned'} ${id}`;
+        },
+    })),
+    ...['react', 'unreact'].map((name) => ({
+        name,
+        group: 'Writing',
+        usage: `${name} <server> <channel> <message id> <emoji>`,
+        summary: name === 'react' ? 'add a reaction' : "remove the bot's own reaction",
+        details: ['The emoji itself (👍), or a custom one as <:name:id>. :shortcodes: are a Discord-app feature and do not work.'],
+        args: 4,
+        run: async ([server, channel, id, emoji], opts) => {
+            await api(opts, name === 'react' ? 'PUT' : 'DELETE', `${where(server, channel)}/messages/${seg(id)}/reactions/${seg(emoji)}`);
+            return `${name === 'react' ? 'Reacted' : 'Removed'} ${emoji} ${name === 'react' ? 'to' : 'from'} ${id}`;
+        },
+    })),
+    {
+        name: 'connect',
+        group: 'Bots',
+        usage: 'connect <code> [--url <site>]',
+        summary: 'connect a bot, with the code from a Botyard prompt',
+        details: [
+            "The code comes from the prompt on the bot's page at Botyard (Connect an agent). It works once, within the hour.",
+            'The key it is exchanged for is stored for you and never printed.',
+        ],
+        args: 1,
+        run: async ([code], opts) => {
+            const url = (opts.url || DEFAULT_URL).replace(/\/+$/, '');
+            const res = await call(url, null, 'POST', '/connect', { code, client: `botyard CLI on ${hostname()}` });
+            const config = load();
+            const previous = config.bots[res.me.bot.id];
+            config.bots[res.me.bot.id] = {
+                id: res.me.bot.id,
+                name: res.me.bot.name,
+                keyId: res.me.token.keyId,
+                key: res.key,
+                url,
+                connectedAt: new Date().toISOString(),
+            };
+            if (!config.default || !config.bots[config.default])
+                config.default = res.me.bot.id;
+            save(config);
+            if (opts.json)
+                return json(res.me);
+            return [
+                `Connected to ${res.me.bot.name}.`,
+                '',
+                fmt.me(res.me),
+                '',
+                previous && previous.keyId !== res.me.token.keyId
+                    ? `This replaces the key you had for this bot (${previous.keyId}). It still works until its owner revokes it on Botyard.\n`
+                    : '',
+                config.default === res.me.bot.id ? 'It is your default bot.' : `Your default bot is still ${config.bots[config.default].name}; pass --bot ${quote(res.me.bot.name)} to use this one.`,
+                'Next: run botyard with no arguments to see what you can do.',
+            ]
+                .filter((l) => l !== '')
+                .join('\n');
+        },
+    },
+    {
+        name: 'bots',
+        group: 'Bots',
+        usage: 'bots',
+        summary: 'the bots connected here (* = default)',
+        args: 0,
+        run: async (_a, opts) => {
+            const config = load();
+            const list = Object.values(config.bots);
+            if (opts.json)
+                return json(list.map(({ key: _key, ...rest }) => ({ ...rest, default: rest.id === config.default })));
+            return list.length === 0 ? 'No bots connected yet.' : botLines(config).join('\n');
+        },
+    },
+    {
+        name: 'use',
+        group: 'Bots',
+        usage: 'use <bot>',
+        summary: 'make a bot the default (by name or id)',
+        args: 1,
+        run: async ([ref]) => {
+            const config = load();
+            const bot = pickBot(config, ref);
+            config.default = bot.id;
+            save(config);
+            return `${bot.name} is now the default.`;
+        },
+    },
+    {
+        name: 'disconnect',
+        group: 'Bots',
+        usage: 'disconnect <bot>',
+        summary: "forget a bot's key here (revoke it on Botyard to end it everywhere)",
+        args: 1,
+        run: async ([ref]) => {
+            const config = load();
+            const bot = pickBot(config, ref);
+            delete config.bots[bot.id];
+            if (config.default === bot.id)
+                config.default = Object.keys(config.bots)[0] ?? null;
+            save(config);
+            return `Forgot ${bot.name}. Its key (${bot.keyId}) still works until it is revoked on the bot's page at Botyard.`;
+        },
+    },
+    {
+        name: 'skill',
+        group: 'Setup',
+        usage: 'skill <install | show>',
+        summary: 'install the Claude Code skill that tells future sessions about botyard',
+        details: [`install writes ${skillDir()}/SKILL.md (set CLAUDE_CONFIG_DIR to change where). show prints it instead.`],
+        args: 1,
+        run: async ([action]) => {
+            if (action === 'show')
+                return SKILL;
+            if (action === 'install')
+                return `Installed ${installSkill()}. New Claude Code sessions will know about botyard.`;
+            throw new Error("Use 'botyard skill install' or 'botyard skill show'.");
+        },
+    },
+];
+// --- the guide -------------------------------------------------------------
+function botLines(config) {
+    return Object.values(config.bots).map((b) => `${b.id === config.default ? '*' : ' '} ${b.name} (${b.id})  key ${b.keyId}${b.url === DEFAULT_URL ? '' : `  ${b.url}`}`);
+}
+function guide() {
+    let bots;
+    try {
+        const config = load();
+        bots = Object.keys(config.bots).length
+            ? botLines(config)
+            : ["  None yet. On the bot's page at Botyard, click Connect an agent, and follow the prompt it gives you."];
+    }
+    catch (e) {
+        bots = [`  ${e instanceof Error ? e.message : String(e)}`];
+    }
+    if (process.env.BOTYARD_KEY)
+        bots.unshift('  (BOTYARD_KEY is set, so commands use that key instead)');
+    // Usage on one line, what it does under it: the usages are too long to share
+    // a line with anything and still fit a terminal.
+    const groups = ['Reading', 'Writing', 'Bots', 'Setup'].map((g) => [`${g}:`, ...COMMANDS.filter((c) => c.group === g).map((c) => `  botyard ${c.usage}\n      ${c.summary}`)].join('\n'));
+    return [
+        `botyard ${VERSION}: read and send in Discord through your own bot, hosted by Botyard.`,
+        '',
+        'Connected bots:',
+        ...bots,
+        '',
+        ...groups.flatMap((g) => [g, '']),
+        'Options: --bot <name|id> picks a bot, --json prints raw API responses, botyard <command> --help explains one command.',
+        'A <server> or <channel> is an id or a name ("general" or "#general"); quote names with spaces.',
+        '',
+        'Rules, for agents:',
+        `- Never print, copy or store the key. The CLI keeps it (in ${configPath()}) and sends it for you.`,
+        "- Read before you write, and check with your human before posting anything they didn't ask you to post.",
+        '- Mentions ping people, not @everyone/@here/roles, unless you pass --mentions all. Only do that when asked.',
+        "- If something is refused, the error says why. Permissions belong to the bot's owner, on Botyard; ask them.",
+        '- Writes are limited to 60 a minute. Never send or react in a loop.',
+        '',
+        skillInstalled()
+            ? `Claude Code skill: installed (${skillDir()}).`
+            : 'Setup: run `botyard skill install` now, so future Claude Code sessions know this CLI is here.',
+    ].join('\n');
+}
+function commandHelp(c) {
+    return [`botyard ${c.usage}`, '', `${c.summary[0].toUpperCase()}${c.summary.slice(1)}.`, ...(c.details ? ['', ...c.details] : [])].join('\n');
+}
+function quote(s) {
+    return /^[\w#.-]+$/.test(s) ? s : `"${s.replace(/"/g, '\\"')}"`;
+}
+// --- main ----------------------------------------------------------------------
+async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                json: { type: 'boolean', default: false },
+                help: { type: 'boolean', short: 'h', default: false },
+                version: { type: 'boolean', short: 'v', default: false },
+                bot: { type: 'string' },
+                url: { type: 'string' },
+                limit: { type: 'string' },
+                before: { type: 'string' },
+                'reply-to': { type: 'string' },
+                mentions: { type: 'string' },
+            },
+        });
+    }
+    catch (e) {
+        process.stderr.write(`botyard: ${e instanceof Error ? e.message : String(e)}. Run botyard for usage.\n`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    if (values.version) {
+        process.stdout.write(`${VERSION}\n`);
+        return 0;
+    }
+    const [name, ...args] = positionals;
+    if (!name) {
+        process.stdout.write(guide() + '\n');
+        return 0;
+    }
+    const command = COMMANDS.find((c) => c.name === name);
+    if (!command) {
+        if (name === 'help' || name === 'guide') {
+            process.stdout.write(guide() + '\n');
+            return 0;
+        }
+        process.stderr.write(`botyard: no command '${name}'. Run botyard with no arguments for the list.\n`);
+        return 2;
+    }
+    if (values.help) {
+        process.stdout.write(commandHelp(command) + '\n');
+        return 0;
+    }
+    const given = command.rest && args.length > command.args ? [...args.slice(0, command.args - 1), args.slice(command.args - 1).join(' ')] : args;
+    if (given.length !== command.args) {
+        process.stderr.write(`botyard: usage: botyard ${command.usage}\n`);
+        return 2;
+    }
+    try {
+        const out = await command.run(given, values);
+        if (out)
+            process.stdout.write(out + '\n');
+        return 0;
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`botyard: ${message}\n`);
+        return e instanceof ApiFailure && e.status === 0 ? 3 : 1;
+    }
+}
+process.exitCode = await main(process.argv.slice(2));

package/dist/config.js

@@ -0,0 +1,63 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Where the CLI keeps the keys it has been given, one per bot. The key is the
+ * one secret here: the directory is owner-only and the file owner-read/write,
+ * and nothing the CLI prints ever includes it. (An agent running as the same
+ * user could still read the file -- this keeps the key out of transcripts and
+ * screenshots, not out of reach.)
+ */
+export const DEFAULT_URL = 'https://botyard.rcpooley.dev';
+export function configDir() {
+    if (process.env.BOTYARD_CONFIG_DIR)
+        return process.env.BOTYARD_CONFIG_DIR;
+    if (process.platform === 'win32' && process.env.APPDATA)
+        return join(process.env.APPDATA, 'botyard');
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'botyard');
+}
+export function configPath() {
+    return join(configDir(), 'config.json');
+}
+export function load() {
+    const path = configPath();
+    if (!existsSync(path))
+        return { version: 1, default: null, bots: {} };
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        return { version: 1, default: raw.default ?? null, bots: raw.bots ?? {} };
+    }
+    catch {
+        throw new Error(`${path} is not valid JSON. Fix or delete it, then connect again.`);
+    }
+}
+/** Written to a temp file and renamed, so a crash mid-write never leaves half a config. */
+export function save(config) {
+    const dir = configDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const tmp = join(dir, `config.json.${process.pid}.tmp`);
+    writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, configPath());
+}
+/** A bot by id or name (case-insensitive), or the default; an error that lists the choices otherwise. */
+export function pickBot(config, ref) {
+    const bots = Object.values(config.bots);
+    if (bots.length === 0) {
+        throw new Error("No bots connected yet. On the bot's page at Botyard, click Connect an agent and follow the prompt.");
+    }
+    if (ref === undefined) {
+        const chosen = (config.default && config.bots[config.default]) || (bots.length === 1 ? bots[0] : undefined);
+        if (chosen)
+            return chosen;
+        throw new Error(`Several bots are connected and none is the default. Pass --bot, or run: botyard use <bot>. Bots: ${names(bots)}`);
+    }
+    const wanted = ref.trim().toLowerCase();
+    const found = config.bots[ref.trim()] ?? bots.find((b) => b.name.toLowerCase() === wanted);
+    if (found)
+        return found;
+    throw new Error(`No connected bot matches '${ref}'. Bots: ${names(bots)}`);
+}
+function names(bots) {
+    return bots.map((b) => `${b.name} (${b.id})`).join(', ');
+}

package/dist/format.js

@@ -0,0 +1,76 @@
+/**
+ * Readable output: what an agent parses easily and a person can skim. --json
+ * skips all of this and prints the API's own response.
+ */
+/** "2026-10-01 13:55 UTC": unambiguous, and short enough to sit on a line with the author. */
+export function when(iso) {
+    return iso.replace('T', ' ').slice(0, 16) + ' UTC';
+}
+function pad(s, n) {
+    return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+export function me(m) {
+    const servers = m.servers.length ? m.servers.map((s) => `  ${s.id}  ${s.name}`).join('\n') : '  (none)';
+    return [
+        `Bot:      ${m.bot.name} (${m.bot.id}), ${m.bot.status}`,
+        `Key:      ${m.token.name} (${m.token.keyId})`,
+        `Can:      ${m.token.scopes.join(', ')}`,
+        `Servers:  ${m.token.allServers ? 'all of the bot\'s servers, now and later' : 'only these'}`,
+        servers,
+    ].join('\n');
+}
+export function servers(list) {
+    if (list.length === 0)
+        return 'No servers this key can reach. The bot may not be in any yet.';
+    return list.map((s) => `${pad(s.id, 20)}  ${s.name}`).join('\n');
+}
+export function channels(list) {
+    if (list.length === 0)
+        return 'No channels the bot can see.';
+    const byId = new Map(list.map((c) => [c.id, c]));
+    return list
+        .filter((c) => c.kind !== 'category')
+        .map((c) => {
+        const parent = c.parentId ? byId.get(c.parentId) : undefined;
+        const under = parent ? (c.kind === 'thread' ? `  (thread in #${parent.name})` : `  (in ${parent.name})`) : '';
+        return `${pad(c.id, 20)}  ${pad(c.kind, 12)}  #${c.name}${under}`;
+    })
+        .join('\n');
+}
+/** One message as a block: a head line, then the content indented, then what hangs off it. */
+export function message(m) {
+    const name = m.author.displayName && m.author.displayName !== m.author.username ? `${m.author.displayName} (${m.author.username})` : m.author.username;
+    const flags = [m.author.bot ? '[bot]' : '', m.editedAt ? '(edited)' : '', m.pinned ? '[pinned]' : '', m.replyTo ? `↩ reply to ${m.replyTo}` : '']
+        .filter(Boolean)
+        .join(' ');
+    const head = `${m.id}  ${when(m.createdAt)}  ${name}${flags ? ' ' + flags : ''}`;
+    const text = m.content || (m.system ? '(system message)' : '(no text)');
+    const lines = [head, ...text.split('\n').map((l) => `    ${l}`)];
+    if (m.reactions.length)
+        lines.push('    ' + m.reactions.map((r) => `${r.emoji} ${r.count}${r.me ? ' (me)' : ''}`).join('   '));
+    for (const a of m.attachments)
+        lines.push(`    [attachment] ${a.name} ${a.url}`);
+    for (const e of m.embeds)
+        if (e.title || e.url || e.description)
+            lines.push(`    [embed] ${[e.title, e.url, e.description].filter(Boolean).join(' — ')}`);
+    return lines.join('\n');
+}
+export function messages(list, where, more) {
+    if (list.length === 0)
+        return `No messages in ${where}.`;
+    const out = [`${where}: ${list.length} message${list.length === 1 ? '' : 's'}, oldest first`, '', list.map(message).join('\n\n')];
+    if (more)
+        out.push('', more);
+    return out.join('\n');
+}
+export function reactions(list) {
+    if (list.length === 0)
+        return 'No reactions.';
+    return list
+        .map((r) => {
+        const shown = r.users.map((u) => u.username).join(', ');
+        const hidden = r.count - r.users.length;
+        return `${r.emoji}  ${r.count}   ${shown}${hidden > 0 ? `${shown ? ', ' : ''}+${hidden} more` : ''}`;
+    })
+        .join('\n');
+}

package/dist/skill.js

@@ -0,0 +1,35 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * A Claude Code skill, so a future session knows this CLI exists without being
+ * told. Deliberately thin: it says when to reach for botyard and to run it for
+ * usage, and repeats no commands -- so it cannot drift from the CLI it points
+ * at, whatever version is installed later.
+ */
+export function skillDir() {
+    return join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'skills', 'botyard');
+}
+export function skillInstalled() {
+    return existsSync(join(skillDir(), 'SKILL.md'));
+}
+export const SKILL = `---
+name: botyard
+description: Read and send Discord messages through the user's own bot, using the botyard CLI. Use whenever the user asks about Discord -- reading a channel, catching up on a server, posting, replying, reacting or pinning -- or mentions Botyard.
+---
+
+# botyard
+
+The \`botyard\` CLI is installed and connected to the user's Discord bot (or bots), through Botyard.
+
+**Run \`botyard\` with no arguments first.** It lists the connected bots, every command with an example, and the rules for using them. \`botyard <command> --help\` covers one command.
+
+Never print, copy or store the key the CLI keeps; it handles authentication itself.
+`;
+export function installSkill() {
+    const dir = skillDir();
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, 'SKILL.md');
+    writeFileSync(path, SKILL);
+    return path;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@rcpooley/botyard",
+  "version": "0.1.0",
+  "description": "Read and send in Discord through your own bot, hosted by Botyard. Made for AI agents.",
+  "type": "module",
+  "bin": {
+    "botyard": "dist/botyard.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "discord",
+    "bot",
+    "agent",
+    "cli",
+    "claude"
+  ],
+  "homepage": "https://botyard.rcpooley.dev",
+  "license": "UNLICENSED"
+}