beehaven 0.8.16

package/dist/commands/mention.js

@@ -0,0 +1,257 @@
+/**
+ * `beehaven comment` · `beehaven comments` · `beehaven mention` — comments and @mentions on every
+ * workspace surface (SS-41).
+ *
+ *   beehaven comment <ref> "text"            comment on a document, sheet, deck, ticket, board,
+ *                                            thought or canvas — <ref> is an id, a key (SS-41,
+ *                                            CLR-42) or an exact title
+ *       --quote "…"   document passage       --slide 3      deck slide (1-based or id)
+ *       --cell B4     sheet cell ("Tab!B4")  --sheet Tab    sheet tab when --cell names none
+ *       --column todo board column           --pin <id>     reply to a canvas pin
+ *       --x 120 --y 80  new canvas pin       --reply <id>   reply to a comment
+ *   beehaven comments <ref> [--all]          read the thread (--all includes resolved)
+ *
+ *   beehaven mention                         where YOU were @mentioned (pending)
+ *   beehaven mention ack <id>                mark one dealt with — or it replays in every brief
+ *   beehaven mention who [query]             who an @ can reach (people and agents)
+ *   beehaven mention resolve "text"          dry run: what the @s in some text would reach
+ *
+ * ⚠ ONE VERB PER DIRECTION, ANY SURFACE. The worker's `comment` / `comments` resolve the reference
+ * and dispatch to the surface's own verb, so every anchor rule and permission applies unchanged.
+ * ⚠ THE RECEIPT IS PRINTED. A mention that reached nobody is said out loud at post time — the one
+ * moment the author can still fix the handle.
+ */
+import { agentRpc as rpcOnce, getTimeout } from './workspace.js';
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    violet: (s) => `\x1b[35m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+/** ⚠ `rpcOnce` returns `{ error }` as a VALUE and never throws. */
+function failure(res) {
+    if (!res || typeof res !== 'object')
+        return null;
+    if (typeof res.error === 'string' && res.error)
+        return res.error;
+    if (res.ok === false)
+        return String(res.message ?? res.code ?? 'the workspace refused the call');
+    return null;
+}
+function die(msg, hint) {
+    console.error(`  Error: ${msg}`);
+    if (hint)
+        console.error(c.dim(`  ${hint}`));
+    process.exit(1);
+}
+const ago = (ts) => {
+    const d = Date.now() - Number(ts || 0);
+    if (d < 60_000)
+        return 'just now';
+    if (d < 3_600_000)
+        return `${Math.round(d / 60_000)}m ago`;
+    if (d < 86_400_000)
+        return `${Math.round(d / 3_600_000)}h ago`;
+    return `${Math.round(d / 86_400_000)}d ago`;
+};
+/** Print what a post's @s did. Exported so `ticket comment` reports the same way. */
+export function printMentionReceipt(res) {
+    const mentions = Array.isArray(res?.mentions) ? res.mentions : [];
+    const unmatched = Array.isArray(res?.unmatchedMentions) ? res.unmatchedMentions : [];
+    const ambiguous = Array.isArray(res?.ambiguousMentions) ? res.ambiguousMentions : [];
+    const people = mentions.filter((m) => m?.kind !== 'agent').map((m) => `@${m.handle}`);
+    const agents = mentions.filter((m) => m?.kind === 'agent').map((m) => `@${m.handle}`);
+    if (people.length)
+        console.log(c.dim(`  Mentioned ${people.join(', ')} — notified`));
+    if (agents.length)
+        console.log(c.dim(`  Queued for ${agents.map(c.violet).join(', ')} — in their next brief`));
+    if (unmatched.length)
+        console.log(c.yellow(`  ⚠ ${unmatched.map((m) => `@${m}`).join(', ')} matched nobody — not delivered. Try: beehaven mention who`));
+    if (ambiguous.length)
+        console.log(c.yellow(`  ⚠ ${ambiguous.map((m) => `@${m}`).join(', ')} matched more than one — not delivered. Use a handle from: beehaven mention who`));
+}
+const ANCHOR_FLAGS = [
+    ['quote', 'quote'], ['slide', 'slide'], ['cell', 'cell'], ['sheet', 'sheet'],
+    ['column', 'column'], ['pin', 'pinId'], ['kind', 'kind'],
+];
+export async function cmdComment(rest, values) {
+    const t = getTimeout(values);
+    const ref = rest[0];
+    const text = rest.slice(1).join(' ').trim() || String(values.body ?? '').trim();
+    if (!ref || !text)
+        die('usage: beehaven comment <ref> "<text>"', 'ref = id, key (SS-41, CLR-42) or exact title · @handle mentions a person or agent · beehaven mention who');
+    const input = { on: ref, body: text };
+    for (const [flag, key] of ANCHOR_FLAGS)
+        if (values[flag] !== undefined && values[flag] !== '')
+            input[key] = String(values[flag]);
+    if (values.x !== undefined)
+        input.x = Number(values.x);
+    if (values.y !== undefined)
+        input.y = Number(values.y);
+    if (values.reply)
+        input.parentId = String(values.reply);
+    const res = await rpcOnce('comment', input, t);
+    const f = failure(res);
+    if (f)
+        die(f, res?.hint);
+    if (values.json) {
+        console.log(JSON.stringify(res, null, 2));
+        return;
+    }
+    const on = res?.on ?? {};
+    const where = on.key || on.title || on.id || ref;
+    const anchor = res?.cell ? ` · ${res.cell}${res.sheetName ? ` (${res.sheetName})` : ''}`
+        : res?.anchorKind === 'slide' ? ` · ${String(res.anchor).replace(/^slide:/, 'slide ')}`
+            : res?.column ? ` · column ${res.column}`
+                : res?.pinId ? ` · pin ${res.pinId}` : '';
+    console.log(`  Commented on ${c.cyan(String(where))} ${c.dim(`(${on.surface || on.kind || 'item'})${anchor}`)}`);
+    if (res?.warning)
+        console.log(c.yellow(`  ⚠ ${res.warning}`));
+    printMentionReceipt(res);
+}
+export async function cmdComments(rest, values) {
+    const t = getTimeout(values);
+    const ref = rest[0];
+    if (!ref)
+        die('usage: beehaven comments <ref> [--all]');
+    const res = await rpcOnce('comments', { on: ref, ...(values.all ? { includeResolved: true } : {}), ...(values.kind ? { kind: String(values.kind) } : {}) }, t);
+    const f = failure(res);
+    if (f)
+        die(f, res?.hint);
+    if (values.json) {
+        console.log(JSON.stringify(res, null, 2));
+        return;
+    }
+    // Canvas threads are pins with messages; every other surface returns `comments`.
+    const rows = Array.isArray(res?.comments) ? res.comments
+        : Array.isArray(res?.pins) ? res.pins.flatMap((p) => (p.messages ?? []).map((m, i) => ({
+            id: m.id || `${p.id}#${i}`, body: m.text, authorName: m.authorName, author: m.author, at: m.at,
+            parentId: i ? p.id : null, anchorLabel: `pin ${p.id}`, resolved: p.resolved,
+        }))) : [];
+    const on = res?.on ?? {};
+    console.log('');
+    console.log(`  ${c.bold(String(on.key || on.title || ref))} ${c.dim(`— ${on.surface || on.kind || ''}`)}`);
+    if (!rows.length) {
+        console.log(c.dim('  No comments.'));
+        return;
+    }
+    for (const r of rows) {
+        const who = r.authorName || (String(r.author || '').startsWith('agent:') ? String(r.author).slice(6) : r.author) || 'someone';
+        const anchor = r.cell ? `${r.cell}${r.sheetName ? `·${r.sheetName}` : ''}` : r.slide ? `slide ${r.slide}` : r.column ? `col ${r.column}` : r.anchorLabel || '';
+        const indent = r.parentId ? '      ↳ ' : '  ';
+        console.log(`${indent}${c.cyan(String(who))}${anchor ? c.dim(` [${anchor}]`) : ''}${r.resolved ? c.dim(' (resolved)') : ''} ${c.dim(ago(r.at))}`);
+        console.log(`${r.parentId ? '        ' : '    '}${String(r.body ?? '')}`);
+    }
+}
+export async function cmdMention(sub, rest, values) {
+    const t = getTimeout(values);
+    if (sub === 'help') {
+        console.log(`
+  ${c.cyan('beehaven mention')} — where you were @mentioned, and who an @ can reach
+
+    beehaven mention                   your pending mentions (--all for acknowledged too)
+    beehaven mention ack <id>          mark one dealt with (it otherwise replays in every brief)
+    beehaven mention who [query]       people and agents an @ resolves to
+    beehaven mention resolve "text"    dry run — what the @s in the text would reach
+
+  Comment anywhere with: beehaven comment <ref> "text @handle"
+`);
+        return;
+    }
+    if (!sub || sub === 'list' || sub === 'ls') {
+        const res = await rpcOnce('mention-list', { pendingOnly: !values.all }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const rows = res?.mentions ?? [];
+        if (!rows.length) {
+            console.log(c.dim(values.all ? '  No mentions.' : '  Nothing waiting — no pending mentions.'));
+            return;
+        }
+        console.log('');
+        for (const m of rows) {
+            const on = m.on ?? {};
+            const acted = m.acted || m.read;
+            console.log(`  ${c.violet(String(m.id).slice(0, 8))}  ${c.cyan(String(m.from))} ${c.dim(`on ${on.kind || 'item'} “${on.title || on.id || ''}” · ${ago(m.at)}`)}${acted ? c.dim(' ✓') : ''}`);
+            console.log(`            ${String(m.text ?? m.title ?? '').replace(/\s+/g, ' ').slice(0, 160)}`);
+            if (on.href)
+                console.log(c.dim(`            ${on.href}`));
+        }
+        if (res?.for === 'agent' && res?.pending)
+            console.log(c.dim(`\n  Act, reply with \`beehaven comment <ref> "…"\`, then \`beehaven mention ack <id>\`.`));
+        return;
+    }
+    if (sub === 'ack') {
+        const id = rest[0];
+        if (!id)
+            die('usage: beehaven mention ack <id>');
+        // ⚠ The list prints an 8-char prefix; resolve it against the full ids before acking.
+        let full = id;
+        if (id.length < 32) {
+            const listed = await rpcOnce('mention-list', { pendingOnly: false, limit: 200 }, t);
+            const hit = (listed?.mentions ?? []).filter((m) => String(m.id).startsWith(id));
+            if (hit.length === 1)
+                full = String(hit[0].id);
+            else if (hit.length > 1)
+                die(`"${id}" matches ${hit.length} mentions — give more of the id`);
+        }
+        const res = await rpcOnce('mention-ack', { id: full, ...(values.body ? { note: String(values.body) } : {}) }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(res?.already ? c.dim('  Already acknowledged.') : '  Acknowledged — it will not appear in your next brief.');
+        return;
+    }
+    if (sub === 'who') {
+        const res = await rpcOnce('mentionable', { ...(rest[0] ? { query: rest[0] } : {}) }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const rows = res?.people ?? [];
+        if (!rows.length) {
+            console.log(c.dim('  Nobody matches.'));
+            return;
+        }
+        console.log('');
+        for (const p of rows) {
+            const tag = p.kind === 'agent' ? c.violet('agent') : c.dim('person');
+            console.log(`  ${c.cyan('@' + p.handle).padEnd(34)} ${tag}  ${p.name && p.name !== p.handle ? p.name : ''}`);
+        }
+        console.log(c.dim(`\n  A person is notified; an agent gets it queued in its inbox (its next brief).`));
+        return;
+    }
+    if (sub === 'resolve') {
+        const text = rest.join(' ').trim();
+        if (!text)
+            die('usage: beehaven mention resolve "text with @handles"');
+        const res = await rpcOnce('mention-resolve', { text }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const m = res?.mentions ?? [];
+        for (const x of m)
+            console.log(`  ${c.cyan('@' + x.handle)} → ${x.kind === 'agent' ? c.violet('agent') : 'person'} ${x.name ?? ''}`);
+        printMentionReceipt({ unmatchedMentions: res?.unmatched, ambiguousMentions: res?.ambiguous });
+        if (!m.length && !(res?.unmatched?.length) && !(res?.ambiguous?.length))
+            console.log(c.dim('  No @mentions in that text.'));
+        return;
+    }
+    die(`unknown subcommand "${sub}"`, 'beehaven mention help');
+}