@botdocs/cli 0.12.1 → 0.13.0

package/dist/commands/proposals.js

@@ -0,0 +1,556 @@
+import * as p from '@clack/prompts';
+import { ApiError, apiFetch, friendlyApiErrorDetail, getApiUrl } from '../lib/api.js';
+import { loadAuth } from '../lib/config.js';
+import { parseRef } from '../lib/ref.js';
+import { fileSetHash } from '../lib/proposals.js';
+import { complete, detectProvider, LlmError } from '../lib/llm.js';
+import { renderDiff } from '../lib/diff.js';
+const VALID_STATUSES = new Set(['OPEN', 'ACCEPTED', 'REJECTED', 'all']);
+/** System prompt for the merge. The model receives the live file set and N
+ * proposed change-sets and must return ONE coherent merged file set as JSON. */
+const SYNTHESIZE_SYSTEM = `You merge multiple proposed edits to an agent-skill file set into ONE coherent result.
+
+You are given:
+1. The CURRENT (live) file set — the base every proposal was derived from.
+2. N PROPOSALS, each a full proposed file set (an alternative version of the same skill).
+
+Produce a SINGLE merged file set that incorporates the intent of every proposal
+without conflicting edits. Preserve content none of the proposals touched. When
+two proposals change the same region differently, reconcile them sensibly rather
+than dropping one. Do not invent files that no proposal introduced.
+
+Output ONLY a JSON object of this exact shape, no prose, no code fences:
+{"files":[{"filename":"<path>","content":"<full file content>"}, ...]}
+
+Every filename present in the CURRENT set (or added by a proposal) must appear
+exactly once in "files" with its full final content.`;
+/** Bail before any API call if the user isn't logged in. The LIST + accept
+ * endpoints both require auth (admitted for list, author for accept). */
+function requireAuth(options) {
+    if (loadAuth())
+        return;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, error: 'not logged in', hint: 'Run `botdocs login` first.' }));
+    }
+    else {
+        console.error('\n  ✗ Not logged in. Run `botdocs login` first.\n');
+    }
+    process.exit(1);
+}
+/**
+ * `botdocs proposals @user/slug [--status OPEN|ACCEPTED|REJECTED|all]` — list
+ * the proposals queued against a skill as a table (or `--json`).
+ *
+ * Authors see full metadata; non-author readers see the redacted status view
+ * (Q5: visibility without the ability to accept/reject).
+ */
+export async function proposals(rawRef, options) {
+    requireAuth(options);
+    let ref;
+    try {
+        ref = parseRef(rawRef);
+    }
+    catch (err) {
+        console.error(`\n  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+    const refStr = `@${ref.username}/${ref.slug}`;
+    const status = options.status;
+    if (status && !VALID_STATUSES.has(status)) {
+        console.error(`\n  ✗ Invalid --status "${status}". Use OPEN, ACCEPTED, REJECTED, or all.\n`);
+        process.exit(1);
+    }
+    const query = status ? `?status=${encodeURIComponent(status)}` : '';
+    let data;
+    try {
+        data = await apiFetch(`/api/skills/${ref.username}/${ref.slug}/proposals${query}`, { auth: true });
+    }
+    catch (err) {
+        handleListError(err, refStr, options);
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(data));
+        return;
+    }
+    if (data.proposals.length === 0) {
+        const label = status && status !== 'all' ? status.toLowerCase() : 'open';
+        console.log(`\n  No ${label} proposals for ${refStr}.\n`);
+        return;
+    }
+    console.log(`\n  Proposals for ${refStr} (current v${data.currentVersion}):\n`);
+    printProposalsTable(data.proposals);
+    if (data.isAuthor) {
+        console.log(`\n  Accept one with: botdocs proposals accept ${refStr} --id <id>\n`);
+    }
+    else {
+        console.log('');
+    }
+}
+/** Render the proposals as an aligned table in `botdocs search`/`list` style. */
+function printProposalsTable(rows) {
+    const idWidth = Math.max(2, ...rows.map((r) => r.id.length));
+    const fromWidth = Math.max(4, ...rows.map((r) => proposerLabel(r).length));
+    const statusWidth = Math.max(6, ...rows.map((r) => r.status.length));
+    const header = [
+        'ID'.padEnd(idWidth),
+        'From'.padEnd(fromWidth),
+        'Status'.padEnd(statusWidth),
+        'Base'.padStart(5),
+        'Files',
+    ].join('  ');
+    console.log(`  ${header}`);
+    console.log(`  ${'-'.repeat(header.length)}`);
+    for (const r of rows) {
+        const row = [
+            r.id.padEnd(idWidth),
+            proposerLabel(r).padEnd(fromWidth),
+            r.status.padEnd(statusWidth),
+            `v${r.baseVersion}`.padStart(5),
+            String(r.fileNames.length),
+        ].join('  ');
+        console.log(`  ${row}`);
+    }
+}
+/** A short, server-derived "From" label. `trust` is authoritative (set
+ * server-side from source + author identity); the self-reported `agentLabel`
+ * is appended only as a hint, never as the trust signal itself. */
+function proposerLabel(r) {
+    const base = r.trust === 'author' ? 'you' : r.trust === 'synthesis' ? 'synthesis' : 'agent';
+    if (r.agentLabel && r.trust === 'agent')
+        return `${base} (${r.agentLabel})`;
+    return base;
+}
+/**
+ * `botdocs proposals accept @user/slug --id X` — accept a proposal, publishing
+ * it as a new version. Author-only (the server 403s non-authors).
+ *
+ * Fetches the current version first so we can send `basedOnCurrentVersion` —
+ * the optimistic-concurrency anchor. If the skill moved since (a 409
+ * stale-base), we tell the user to re-review rather than silently clobbering.
+ */
+export async function proposalsAccept(rawRef, options) {
+    requireAuth(options);
+    let ref;
+    try {
+        ref = parseRef(rawRef);
+    }
+    catch (err) {
+        console.error(`\n  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+    const refStr = `@${ref.username}/${ref.slug}`;
+    const id = options.id;
+    if (!id) {
+        console.error('\n  ✗ --id <proposalId> is required. Run `botdocs proposals ' + refStr + '` to list ids.\n');
+        process.exit(1);
+    }
+    // Read the current version so accept can send the stale-base anchor.
+    let currentVersion;
+    try {
+        const list = await apiFetch(`/api/skills/${ref.username}/${ref.slug}/proposals?status=all`, { auth: true });
+        currentVersion = list.currentVersion;
+    }
+    catch (err) {
+        handleListError(err, refStr, options);
+        return;
+    }
+    let result;
+    try {
+        result = await apiFetch(`/api/skills/${ref.username}/${ref.slug}/proposals/${id}`, {
+            method: 'PATCH',
+            auth: true,
+            body: { decision: 'accept', basedOnCurrentVersion: currentVersion },
+        });
+    }
+    catch (err) {
+        handleAcceptError(err, refStr, id, options);
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, ref: refStr, id, version: result.version }));
+        return;
+    }
+    console.log(`\n  ✓ Accepted proposal ${id} — published v${result.version} of ${refStr}.\n`);
+}
+/**
+ * `botdocs proposals synthesize @user/slug` — merge a skill's OPEN proposals
+ * into ONE synthesis proposal for the author to review.
+ *
+ * Runs with a SYNTHESIZER token (a low-privilege principal the author minted,
+ * scoped to this skill). The synthesizer can ONLY read the skill's proposals
+ * and create a synthesis — it can never accept, publish, or edit. The author
+ * still reviews and approves the merge through the normal accept path.
+ *
+ * Steps:
+ *   1. List OPEN proposals (permitted for a scoped synthesizer).
+ *   2. Fetch each OPEN proposal's full contents + the skill's live file set
+ *      (the DETAIL endpoint returns both `files` and `currentFiles`).
+ *   3. Merge the live set + the N proposed sets into one file set via the LLM.
+ *   4. Preview the merge (live vs merged) and confirm unless `--yes`.
+ *   5. POST the synthesis with basedFileHash = fileSetHash(live files).
+ *
+ * A 409 `duplicate_synthesis` is treated as a NO-OP SUCCESS (exit 0): the same
+ * merge already exists OPEN, so an end-of-day cron re-running this is safe.
+ */
+export async function proposalsSynthesize(rawRef, options) {
+    requireAuth(options);
+    let ref;
+    try {
+        ref = parseRef(rawRef);
+    }
+    catch (err) {
+        console.error(`\n  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+    const refStr = `@${ref.username}/${ref.slug}`;
+    // Fail fast if no LLM key is configured — the merge can't run without it.
+    try {
+        detectProvider({ keyEnv: options.keyEnv });
+    }
+    catch (err) {
+        if (err instanceof LlmError) {
+            console.error(`\n  ✗ ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    const base = `/api/skills/${ref.username}/${ref.slug}/proposals`;
+    // 1. List OPEN proposals (permitted for a scoped synthesizer).
+    let list;
+    try {
+        list = await apiFetch(`${base}?status=OPEN`, { auth: true });
+    }
+    catch (err) {
+        handleSynthesizeError(err, refStr, options);
+        return;
+    }
+    const openProposals = list.proposals.filter((pr) => pr.status === 'OPEN');
+    if (openProposals.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify({ ok: true, ref: refStr, skipped: 'no_open_proposals' }));
+        }
+        else {
+            console.log(`\n  No open proposals to synthesize for ${refStr}. Nothing to do.\n`);
+        }
+        return;
+    }
+    if (openProposals.length === 1) {
+        // A "merge" of one proposal is just that proposal — synthesizing adds no
+        // value and would only create a duplicate of the existing OPEN proposal.
+        if (options.json) {
+            console.log(JSON.stringify({ ok: true, ref: refStr, skipped: 'single_open_proposal' }));
+        }
+        else {
+            console.log(`\n  Only one open proposal for ${refStr}; nothing to merge. ` +
+                `The author can review it directly.\n`);
+        }
+        return;
+    }
+    // 2. Fetch each OPEN proposal's full contents + the live file set.
+    const sourceProposalIds = openProposals.map((pr) => pr.id);
+    let details;
+    try {
+        details = await Promise.all(sourceProposalIds.map((id) => apiFetch(`${base}/${encodeURIComponent(id)}`, { auth: true })));
+    }
+    catch (err) {
+        handleSynthesizeError(err, refStr, options);
+        return;
+    }
+    // The live file set (merge base) is identical across DETAIL responses; take
+    // the first. basedFileHash anchors the synthesis to this exact base — the
+    // server's accept-time drift guard checks against it.
+    const liveFiles = details[0].currentFiles.map((f) => ({
+        filename: f.filename,
+        content: f.content,
+    }));
+    const basedFileHash = fileSetHash(liveFiles);
+    if (!options.json) {
+        console.log(`\n  Merging ${openProposals.length} open proposals for ${refStr} (live v${list.currentVersion})…`);
+    }
+    // 3. Merge client-side via the LLM.
+    let merged;
+    try {
+        merged = await mergeProposals(liveFiles, details, options.keyEnv);
+    }
+    catch (err) {
+        if (err instanceof LlmError) {
+            console.error(`\n  ✗ ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // 4. Preview + confirm (unless --yes / --json non-interactive).
+    if (!options.json) {
+        printMergePreview(liveFiles, merged);
+    }
+    if (!options.yes && !options.json) {
+        const choice = await p.confirm({
+            message: `Submit this merge as a synthesis proposal for ${refStr}?`,
+        });
+        if (p.isCancel(choice) || !choice) {
+            console.log('\n  Cancelled. No synthesis submitted.\n');
+            return;
+        }
+    }
+    // 5. POST the synthesis.
+    let result;
+    try {
+        result = await apiFetch(`${base}/synthesize`, {
+            method: 'POST',
+            auth: true,
+            body: {
+                sourceProposalIds,
+                files: merged.map((f, i) => ({
+                    filename: f.filename,
+                    content: f.content,
+                    sortOrder: i,
+                })),
+                changelog: options.message,
+                agentLabel: options.agentLabel,
+                basedFileHash,
+            },
+        });
+    }
+    catch (err) {
+        handleSynthesizeError(err, refStr, options);
+        return;
+    }
+    // The author reviews + approves the synthesis — the synthesizer cannot
+    // publish anything itself. Print a review link (the author's #proposals tab).
+    const reviewUrl = `${getApiUrl()}/${refStr}`;
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            ref: refStr,
+            proposalId: result.proposalId,
+            status: result.status,
+            sourceProposalIds,
+            url: reviewUrl,
+        }));
+        return;
+    }
+    console.log(`\n  ✓ Synthesis proposal queued for ${refStr} (id ${result.proposalId}).`);
+    console.log(`    It merges ${sourceProposalIds.length} proposals into one.`);
+    console.log(`    The author reviews and approves it before anything goes live: ${reviewUrl}\n`);
+}
+/** Build the merge prompt from the live set + the proposal details, call the
+ * LLM, and parse its JSON output into a typed merged file set.
+ *
+ * Throws {@link LlmError} on an empty/unparseable response so the caller can
+ * surface a clean message rather than POSTing garbage. */
+async function mergeProposals(liveFiles, details, keyEnv) {
+    const prompt = buildMergePrompt(liveFiles, details);
+    const resp = await complete({ system: SYNTHESIZE_SYSTEM, prompt, keyEnv });
+    return parseMergedFiles(resp.text);
+}
+/** Render the live file set + each proposal's proposed file set into the user
+ * prompt the merge model reads. */
+function buildMergePrompt(liveFiles, details) {
+    const sections = [];
+    sections.push('CURRENT (live) FILE SET:');
+    for (const f of liveFiles) {
+        sections.push(`--- FILE: ${f.filename} ---\n${f.content}`);
+    }
+    details.forEach((d, idx) => {
+        sections.push(`\nPROPOSAL ${idx + 1} (id ${d.proposal.id}):`);
+        if (d.proposal.changelog)
+            sections.push(`Changelog: ${d.proposal.changelog}`);
+        for (const f of d.files) {
+            sections.push(`--- FILE: ${f.filename} ---\n${f.content}`);
+        }
+    });
+    return sections.join('\n');
+}
+/** Parse the LLM's JSON merge output. Tolerates an accidental ```json fence by
+ * extracting the first {...} block. Throws LlmError on anything that isn't a
+ * well-formed `{ files: [{filename, content}] }`. */
+function parseMergedFiles(text) {
+    const trimmed = text.trim();
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start === -1 || end === -1 || end < start) {
+        throw new LlmError('The merge model did not return JSON. Try again.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed.slice(start, end + 1));
+    }
+    catch {
+        throw new LlmError('The merge model returned invalid JSON. Try again.');
+    }
+    const filesRaw = parsed.files;
+    if (!Array.isArray(filesRaw) || filesRaw.length === 0) {
+        throw new LlmError('The merge model returned no files. Try again.');
+    }
+    const out = [];
+    for (const f of filesRaw) {
+        if (typeof f !== 'object' || f === null) {
+            throw new LlmError('The merge model returned a malformed file entry. Try again.');
+        }
+        const { filename, content } = f;
+        if (typeof filename !== 'string' || typeof content !== 'string') {
+            throw new LlmError('The merge model returned a file without filename/content. Try again.');
+        }
+        out.push({ filename, content });
+    }
+    return out;
+}
+/** Print a per-file diff of the live set vs the merged set, so the operator can
+ * see exactly what the synthesis would change before submitting. */
+function printMergePreview(liveFiles, merged) {
+    const liveByName = new Map(liveFiles.map((f) => [f.filename, f.content]));
+    for (const f of merged) {
+        console.log(`\n  ${f.filename}:`);
+        console.log(renderDiff(liveByName.get(f.filename) ?? '', f.content));
+    }
+}
+/** Map a synthesize API error to a friendly, cron-safe CLI message.
+ *
+ * 409 `duplicate_synthesis` — the same merge already exists OPEN. Treated as a
+ *     NO-OP SUCCESS (exit 0) so a re-running cron doesn't fail.
+ * 409 `source_not_open` — a source proposal was decided since we listed it.
+ *     Re-run to pick up the new queue state.
+ * 401/403 — the token isn't a synthesizer scoped to this skill.
+ * 404 — skill not found / unreadable. */
+function handleSynthesizeError(err, refStr, options) {
+    if (!(err instanceof ApiError)) {
+        throw err;
+    }
+    const body = err.body;
+    // 409 duplicate — idempotent no-op success. Exit 0 so a cron is safe.
+    if (err.status === 409 && body?.error === 'duplicate_synthesis') {
+        if (options.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                ref: refStr,
+                skipped: 'duplicate_synthesis',
+                existingProposalId: body.existingProposalId ?? null,
+            }));
+        }
+        else {
+            console.log(`\n  An identical synthesis is already open for ${refStr}` +
+                (body.existingProposalId ? ` (id ${body.existingProposalId})` : '') +
+                `. Nothing to do.\n`);
+        }
+        return; // exit 0
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: false,
+            ref: refStr,
+            status: err.status,
+            error: body?.error ?? err.message,
+            message: body?.message ?? null,
+        }));
+        process.exit(1);
+    }
+    if (err.status === 401 || err.status === 403) {
+        console.error(`\n  ✗ This command needs a synthesizer token scoped to ${refStr}.` +
+            `\n    The skill author can mint one at ${getApiUrl()}/settings/tokens.\n`);
+    }
+    else if (err.status === 404) {
+        console.error(`\n  ✗ Skill not found: ${refStr}\n`);
+    }
+    else if (err.status === 409 && body?.error === 'source_not_open') {
+        console.error(`\n  ✗ One or more proposals were decided since they were listed.` +
+            `\n    Re-run \`botdocs proposals synthesize ${refStr}\` to pick up the current queue.\n`);
+    }
+    else if (err.status === 413) {
+        console.error(`\n  ✗ The merged file set is too large for ${refStr}. Trim and try again.\n`);
+    }
+    else {
+        console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
+    }
+    process.exit(1);
+}
+/** Map a LIST API error to a friendly message (shared by list + accept's
+ * version pre-fetch). */
+function handleListError(err, refStr, options) {
+    if (!(err instanceof ApiError)) {
+        throw err;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, ref: refStr, status: err.status, error: err.message }));
+        process.exit(1);
+    }
+    if (err.status === 404) {
+        console.error(`\n  ✗ Skill not found: ${refStr}\n`);
+    }
+    else if (err.status === 401) {
+        console.error(`\n  ✗ ${err.message}\n`);
+    }
+    else {
+        console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
+    }
+    process.exit(1);
+}
+/** Map an accept API error to a friendly message.
+ *
+ * 403 — you don't own this skill (only the author can accept).
+ * 404 — the proposal or skill doesn't exist.
+ * 409 — a conflict: the proposal was already decided, or the skill moved while
+ *       you reviewed (stale base). Tell the user to re-list / re-review. */
+function handleAcceptError(err, refStr, id, options) {
+    if (!(err instanceof ApiError)) {
+        throw err;
+    }
+    const body = err.body;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, ref: refStr, id, status: err.status, error: err.message }));
+        process.exit(1);
+    }
+    if (err.status === 403) {
+        console.error(`\n  ✗ Only the author of ${refStr} can accept proposals.\n`);
+    }
+    else if (err.status === 404) {
+        console.error(`\n  ✗ Proposal ${id} not found for ${refStr}.\n`);
+    }
+    else if (err.status === 409) {
+        // Already decided, or the skill moved since the base was read. Either way
+        // the safe next step is to re-list and re-review.
+        const detail = body?.error ?? 'this proposal can no longer be accepted as-is';
+        console.error(`\n  ✗ ${detail}.`);
+        console.error(`    Run \`botdocs proposals ${refStr}\` to see the current state.\n`);
+    }
+    else if (err.status === 401) {
+        console.error(`\n  ✗ ${err.message}\n`);
+    }
+    else {
+        console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
+    }
+    process.exit(1);
+}
+/**
+ * Register the `proposals` command (list, default) and its `accept`
+ * subcommand on the program. Done in a registrar helper (like `team`/`backups`)
+ * so the nested `accept` subcommand lives in this file rather than inline in
+ * index.ts — keeping index.ts's top-level surface clean and the quickstart
+ * drift-check parser happy (it lists only the parent verb `proposals`).
+ */
+export function registerProposalsCommands(program) {
+    const proposalsCmd = program
+        .command('proposals <ref>')
+        .description('List proposals queued against a skill (author sees full metadata)')
+        .option('--status <status>', 'Filter by status: OPEN (default), ACCEPTED, REJECTED, or all')
+        .action(async (ref, opts) => {
+        await proposals(ref, { ...opts, json: program.opts().json });
+    });
+    proposalsCmd
+        .command('accept <ref>')
+        .description('Accept a proposal, publishing it as a new version (author-only)')
+        .requiredOption('--id <proposalId>', 'The proposal id to accept')
+        .action(async (ref, opts) => {
+        await proposalsAccept(ref, { ...opts, json: program.opts().json });
+    });
+    proposalsCmd
+        .command('synthesize <ref>')
+        .description("Merge a skill's open proposals into one synthesis for the author to review")
+        .option('--message <message>', 'Changelog describing the merge')
+        .option('--agent-label <label>', 'Self-reported agent identity (untrusted)')
+        .option('--key-env <name>', 'Env var holding the LLM API key (e.g. BOTDOCS_ANTHROPIC_KEY)')
+        .option('-y, --yes', 'Skip the confirmation prompt (for cron / non-interactive use)')
+        .action(async (ref, opts) => {
+        await proposalsSynthesize(ref, { ...opts, json: program.opts().json });
+    });
+}

package/dist/commands/propose.d.ts

@@ -0,0 +1,18 @@
+interface ProposeOptions {
+    /** Proposal changelog — what this change does, for the reviewing author. */
+    message?: string;
+    /** Self-reported agent identity (e.g. "hermes-v2"). UNTRUSTED server-side. */
+    agentLabel?: string;
+    json?: boolean;
+}
+/**
+ * `botdocs propose @user/slug [path]` — queue a change to a skill for the
+ * author to review, instead of publishing directly.
+ *
+ * Collects the local files (directory or single markdown file, default cwd),
+ * computes `basedFileHash` over the skill's CURRENT live file set (the base
+ * the author will diff against), and POSTs the proposal. The author reviews +
+ * accepts/rejects from the Proposals tab or `botdocs proposals accept`.
+ */
+export declare function propose(rawRef: string, pathArg: string | undefined, options: ProposeOptions): Promise<void>;
+export {};