@paperboyseo/cli 0.0.0-stage → 0.1.0

package/dist/commands/mcp.js

@@ -0,0 +1,194 @@
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline';
+import { CliError } from '../errors.js';
+import { resolveSiteId } from '../site.js';
+import { VERSION } from '../version.js';
+/**
+ * `paperboy mcp`: a Model Context Protocol server over stdio. It exposes the REST API as tools, with the same
+ * key and base URL as the rest of the CLI. Messages are newline-delimited JSON-RPC 2.0 on stdin and stdout;
+ * logs go to stderr. No SDK: the protocol surface used here is small.
+ */
+const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const site = { type: 'string', description: 'Site id or domain. Optional when the account has one site or a default is saved.' };
+const str = (args, key) => {
+    const v = args[key];
+    return typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined;
+};
+const whole = (args, key, fallback, max) => {
+    const v = args[key];
+    return typeof v === 'number' && Number.isInteger(v) && v >= 1 && v <= max ? v : fallback;
+};
+const need = (args, key) => {
+    const v = str(args, key);
+    if (!v)
+        throw new CliError('usage', `"${key}" is required.`);
+    return v;
+};
+const enc = encodeURIComponent;
+export const TOOLS = [
+    {
+        name: 'list_sites',
+        description: 'List the sites on this Paperboy account, with publish target and Search Console state.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true },
+        run: async (_a, d) => (await d.api.get('/api/v1/sites')).data,
+    },
+    {
+        name: 'suggest_topics',
+        description: 'Suggest articles worth writing next, from Search Console data, with the reason and signals for each.',
+        inputSchema: { type: 'object', properties: { site, n: { type: 'integer', minimum: 1, maximum: 50, description: 'How many topics. Default 5.' } }, additionalProperties: false },
+        annotations: { readOnlyHint: true },
+        run: async (a, d) => (await d.api.post(`/api/v1/sites/${enc(await d.resolveSite(str(a, 'site')))}/topics`, { n: whole(a, 'n', 5, 50) })).data,
+    },
+    {
+        name: 'write_article',
+        description: 'Start writing an article: research, write, fact check. This spends money on the Anthropic key the server uses. Returns a job id at once; poll get_job. Whether the article publishes by itself follows the site approval setting, so ask the user before calling this on a site set to autopilot.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                site,
+                topic_id: { type: 'string', description: 'A topic id from suggest_topics.' },
+                topic: { type: 'string', description: 'Free text topic, used when there is no topic id.' },
+            },
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+        run: async (a, d) => {
+            const body = { publish: false };
+            const id = str(a, 'topic_id');
+            const text = str(a, 'topic');
+            if (id)
+                body['topic_id'] = id;
+            else if (text)
+                body['topic'] = text;
+            const path = `/api/v1/sites/${enc(await d.resolveSite(str(a, 'site')))}/articles`;
+            return (await d.api.post(path, body, { idempotencyKey: randomUUID() })).data;
+        },
+    },
+    {
+        name: 'get_job',
+        description: 'Status of a job started by write_article: queued, running, done or failed, with the current step and the article id when done.',
+        inputSchema: { type: 'object', properties: { job_id: { type: 'string' } }, required: ['job_id'], additionalProperties: false },
+        annotations: { readOnlyHint: true },
+        run: async (a, d) => (await d.api.get(`/api/v1/jobs/${enc(need(a, 'job_id'))}`)).data,
+    },
+    {
+        name: 'get_article',
+        description: 'An article with its status, URL and the fact-check verdict: every check, and each held claim with the problem found.',
+        inputSchema: { type: 'object', properties: { article_id: { type: 'string' } }, required: ['article_id'], additionalProperties: false },
+        annotations: { readOnlyHint: true },
+        run: async (a, d) => (await d.api.get(`/api/v1/articles/${enc(need(a, 'article_id'))}`)).data,
+    },
+    {
+        name: 'fact_check',
+        description: 'Fact check a page URL or a Markdown draft. Every cited link is fetched and each claim is compared with the text of the page it cites. Returns pass, a score and one entry per claim: verified, held, unsupported or mismatch.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'A public page to check.' },
+                markdown: { type: 'string', description: 'A draft in Markdown, with its sources linked inline.' },
+                sources: { type: 'array', items: { type: 'string' }, description: 'Extra source URLs to read.' },
+            },
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+        run: async (a, d) => {
+            const body = {};
+            if (str(a, 'url'))
+                body['url'] = str(a, 'url');
+            else if (str(a, 'markdown'))
+                body['markdown'] = str(a, 'markdown');
+            else
+                throw new CliError('usage', 'Send "url" or "markdown".');
+            if (Array.isArray(a['sources']))
+                body['sources'] = a['sources'].filter((s) => typeof s === 'string');
+            return (await d.api.post('/api/v1/fact-check', body, { idempotencyKey: randomUUID(), timeoutMs: 120_000 })).data;
+        },
+    },
+    {
+        name: 'publish_article',
+        description: 'Publish an article that passed the fact check to the site publish target (WordPress, Ghost or webhook). This makes it public: confirm with the user first.',
+        inputSchema: { type: 'object', properties: { article_id: { type: 'string' } }, required: ['article_id'], additionalProperties: false },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+        run: async (a, d) => (await d.api.post(`/api/v1/articles/${enc(need(a, 'article_id'))}/publish`, {})).data,
+    },
+    {
+        name: 'get_performance',
+        description: 'Search Console totals (clicks, impressions, average position) and daily rows for a site.',
+        inputSchema: { type: 'object', properties: { site, days: { type: 'integer', minimum: 1, maximum: 365, description: 'Window in days. Default 28.' } }, additionalProperties: false },
+        annotations: { readOnlyHint: true },
+        run: async (a, d) => (await d.api.get(`/api/v1/sites/${enc(await d.resolveSite(str(a, 'site')))}/performance`, { query: { days: whole(a, 'days', 28, 365) } })).data,
+    },
+];
+const ok = (id, result) => ({ jsonrpc: '2.0', id: id ?? null, result });
+const fail = (id, code, message) => ({ jsonrpc: '2.0', id: id ?? null, error: { code, message } });
+/** Handles one JSON-RPC message. Returns the response, or null for notifications. */
+export async function handleMessage(msg, deps) {
+    const { id, method, params = {} } = msg;
+    if (typeof method !== 'string')
+        return id === undefined ? null : fail(id, -32600, 'Invalid request.');
+    if (id === undefined)
+        return null; // notifications/initialized, notifications/cancelled, and so on
+    switch (method) {
+        case 'initialize': {
+            const asked = typeof params['protocolVersion'] === 'string' ? params['protocolVersion'] : '';
+            return ok(id, {
+                protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+                capabilities: { tools: {} },
+                serverInfo: { name: 'paperboy', version: VERSION },
+                instructions: 'Paperboy writes and fact checks SEO articles. write_article spends money and publish_article makes content public: ask the user first.',
+            });
+        }
+        case 'ping':
+            return ok(id, {});
+        case 'tools/list':
+            return ok(id, { tools: TOOLS.map(({ name, description, inputSchema, annotations }) => ({ name, description, inputSchema, annotations })) });
+        case 'tools/call': {
+            const tool = TOOLS.find((t) => t.name === params['name']);
+            if (!tool)
+                return fail(id, -32602, `Unknown tool "${String(params['name'])}".`);
+            const args = params['arguments'] && typeof params['arguments'] === 'object' ? params['arguments'] : {};
+            try {
+                const data = await tool.run(args, deps);
+                return ok(id, { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] });
+            }
+            catch (err) {
+                return ok(id, { isError: true, content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }] });
+            }
+        }
+        default:
+            return fail(id, -32601, `Method not found: ${method}`);
+    }
+}
+export async function mcp(ctx) {
+    const api = ctx.client({ timeoutMs: 130_000 });
+    const deps = {
+        api,
+        resolveSite: (s) => resolveSiteId(s ? { ...ctx, settings: { ...ctx.settings, site: s } } : ctx),
+    };
+    const send = (m) => process.stdout.write(JSON.stringify(m) + '\n');
+    process.stderr.write(`paperboy mcp ${VERSION} ready on stdio (${ctx.settings.baseUrl})\n`);
+    const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    const pending = new Set();
+    for await (const line of rl) {
+        if (!line.trim())
+            continue;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            send(fail(null, -32700, 'Parse error.'));
+            continue;
+        }
+        // Tool calls can take minutes: do not hold up other requests.
+        const job = handleMessage(msg, deps).then((res) => {
+            if (res)
+                send(res);
+        });
+        pending.add(job);
+        void job.finally(() => pending.delete(job));
+    }
+    await Promise.all(pending);
+    return 0;
+}

package/dist/commands/publish.js

@@ -0,0 +1,20 @@
+import { CliError } from '../errors.js';
+export async function publish(ctx) {
+    const { out, flags } = ctx;
+    const id = ctx.args[0];
+    if (!id)
+        throw new CliError('usage', 'Usage: paperboy publish <article-id>');
+    if (ctx.deps.interactive && !flags.yes && !out.json) {
+        const ok = await ctx.deps.confirm(`Publish article ${id} now?`);
+        if (!ok)
+            throw new CliError('cancelled', 'Cancelled. Nothing was published.');
+    }
+    const { data } = await ctx.client().post(`/api/v1/articles/${encodeURIComponent(id)}/publish`, {});
+    out.result('publish', data, () => {
+        if (data.published)
+            out.line(`${out.style.green('Published')}${data.url ? `: ${data.url}` : ''}`);
+        else
+            out.line(`${out.style.yellow('Not published.')} The article was not published; check the fact-check verdict with \`paperboy status\`.`);
+    });
+    return data.published ? 0 : 1;
+}

package/dist/commands/report.js

@@ -0,0 +1,38 @@
+import { intFlag } from '../args.js';
+import { fixed, num, padLeft, padRight, sparkline } from '../output.js';
+import { resolveSiteId } from '../site.js';
+export async function report(ctx) {
+    const { out, flags } = ctx;
+    const days = intFlag(flags.days, 'days', 28, 365);
+    const site = await resolveSiteId(ctx);
+    const api = ctx.client();
+    const base = `/api/v1/sites/${encodeURIComponent(site)}`;
+    if (flags.markdown) {
+        const { data } = await api.post(`${base}/reports`, { days });
+        out.result('report', data, () => out.line(data.markdown.replace(/\n+$/, '')));
+        return 0;
+    }
+    const { data } = await api.get(`${base}/performance`, { query: { days } });
+    out.result('report', data, () => {
+        const s = out.style;
+        const t = data.totals ?? {};
+        const daily = data.daily ?? [];
+        const ctr = t.impressions && t.clicks !== undefined ? (t.clicks / t.impressions) * 100 : t.ctr !== undefined ? t.ctr * 100 : undefined;
+        out.line(s.bold(`Last ${data.days ?? days} days`));
+        out.line(`  clicks        ${num(t.clicks)}`);
+        out.line(`  impressions   ${num(t.impressions)}`);
+        out.line(`  avg position  ${fixed(t.position)}`);
+        if (ctr !== undefined)
+            out.line(`  ctr           ${fixed(ctr, 2)}%`);
+        if (daily.length) {
+            out.line();
+            out.line(`clicks per day  ${sparkline(daily.map((d) => d.clicks))}`);
+            out.line();
+            out.line(s.dim(`${padRight('date', 12)}${padLeft('clicks', 8)}${padLeft('impressions', 13)}`));
+            for (const d of daily.slice(-7)) {
+                out.line(`${padRight(d.date, 12)}${padLeft(num(d.clicks), 8)}${padLeft(num(d.impressions), 13)}`);
+            }
+        }
+    });
+    return 0;
+}

package/dist/commands/status.js

@@ -0,0 +1,47 @@
+import { CliError } from '../errors.js';
+import { num } from '../output.js';
+import { resolveSiteId } from '../site.js';
+function ownerLabel(me) {
+    if (typeof me.owner === 'string')
+        return me.owner;
+    return me.owner?.email ?? me.owner?.name ?? me.owner?.id ?? me.email ?? 'unknown';
+}
+export async function status(ctx) {
+    const { out } = ctx;
+    const api = ctx.client();
+    const { data: me } = await api.get('/api/v1/me');
+    let site = null;
+    try {
+        const id = await resolveSiteId(ctx);
+        const res = await api.get(`/api/v1/sites/${encodeURIComponent(id)}`);
+        site = res.data.site;
+    }
+    catch (err) {
+        if (!(err instanceof CliError && err.code === 'no_site'))
+            throw err;
+    }
+    out.result('status', { me, site }, () => {
+        const s = out.style;
+        out.line(`${s.bold('owner:')}    ${ownerLabel(me)}`);
+        if (me.credits?.enabled)
+            out.line(`${s.bold('credits:')}  ${num(me.credits.balance)}`);
+        if (!site) {
+            out.line('site:     none yet. Run `paperboy connect https://yoursite.com` to add one.');
+            return;
+        }
+        out.line(`${s.bold('site:')}     ${site.domain} (${site.id})`);
+        out.line(`${s.bold('publish:')}  ${site.publish_method ?? 'not configured'}`);
+        out.line(`${s.bold('gsc:')}      ${site.gsc_connected ? s.green('connected') : s.yellow('not connected')}`);
+        const articles = site.articles ?? [];
+        if (articles.length) {
+            out.line(s.bold('last articles:'));
+            for (const a of articles) {
+                out.line(`  ${a.title}  ${s.dim(`[${a.id}] ${a.status ?? ''}${a.url ? ` ${a.url}` : ''}`.trimEnd())}`);
+            }
+        }
+        else {
+            out.line('last articles: none yet');
+        }
+    });
+    return 0;
+}

package/dist/commands/topics.js

@@ -0,0 +1,44 @@
+import { intFlag } from '../args.js';
+import { num } from '../output.js';
+import { resolveSiteId } from '../site.js';
+export function describeSignals(signals) {
+    if (!signals)
+        return '';
+    const parts = [];
+    if (typeof signals.impressions === 'number')
+        parts.push(`${num(signals.impressions)} impressions`);
+    if (typeof signals.position === 'number')
+        parts.push(`position ${signals.position.toFixed(1)}`);
+    const gate = signals.serp_gate;
+    if (gate !== undefined && gate !== null) {
+        const text = typeof gate === 'boolean' ? (gate ? 'pass' : 'blocked') : typeof gate === 'string' ? gate : JSON.stringify(gate);
+        parts.push(`serp gate: ${text}`);
+    }
+    return parts.join(', ');
+}
+export async function topics(ctx) {
+    const { out } = ctx;
+    const n = intFlag(ctx.flags.n, 'n', 5, 50);
+    const site = await resolveSiteId(ctx);
+    const { data } = await ctx.client().post(`/api/v1/sites/${encodeURIComponent(site)}/topics`, { n });
+    const list = data.topics ?? [];
+    out.result('topics', data, () => {
+        if (list.length === 0) {
+            out.line('No topics yet. Search Console may still be collecting data for this site.');
+            return;
+        }
+        list.forEach((t, i) => {
+            out.line(`${out.style.bold(`${i + 1}. ${t.title}`)}  ${out.style.dim(`[${t.id}]`)}`);
+            if (t.query)
+                out.line(`   query: ${t.query}`);
+            if (t.reason)
+                out.line(`   why: ${t.reason}`);
+            const signals = describeSignals(t.signals);
+            if (signals)
+                out.line(`   signals: ${signals}`);
+            out.line();
+        });
+        out.line(`Write one with: paperboy write --topic ${list[0]?.id ?? '<id>'}`);
+    });
+    return 0;
+}

package/dist/commands/write.js

@@ -0,0 +1,70 @@
+import { randomUUID } from 'node:crypto';
+import { CliError } from '../errors.js';
+import { pollJob } from '../jobs.js';
+import { resolveSiteId } from '../site.js';
+export function summarizeChecks(checks) {
+    let verified = 0;
+    let held = 0;
+    let other = 0;
+    for (const c of checks) {
+        if (c.status === 'verified')
+            verified++;
+        else if (c.status === 'held')
+            held++;
+        else
+            other++;
+    }
+    return { verified, held, other };
+}
+export async function write(ctx) {
+    const { out, flags } = ctx;
+    const api = ctx.client();
+    const site = await resolveSiteId(ctx);
+    // Free text always has a space in it; ids never do.
+    const body = { publish: Boolean(flags.publish) };
+    if (flags.topic !== undefined) {
+        if (flags.topic.trim() === '')
+            throw new CliError('usage', '--topic needs a topic id or some text.');
+        body[/\s/.test(flags.topic.trim()) ? 'topic' : 'topic_id'] = flags.topic.trim();
+    }
+    if (flags.publish && ctx.deps.interactive && !flags.yes && !out.json) {
+        const ok = await ctx.deps.confirm('Publish automatically when the fact-check passes?');
+        if (!ok)
+            throw new CliError('cancelled', 'Cancelled. Re-run without --publish to keep it as a draft.');
+    }
+    const wait = flags.wait ?? (flags['no-wait'] ? false : ctx.deps.interactive);
+    const { data: started } = await api.post(`/api/v1/sites/${encodeURIComponent(site)}/articles`, body, { idempotencyKey: randomUUID() });
+    out.info(`Started job ${started.job_id}.`);
+    if (!wait) {
+        out.result('write', started, () => {
+            out.line(`The article is being written. Check on it with: paperboy status`);
+        });
+        return 0;
+    }
+    const job = await pollJob(ctx, api, started.job_id);
+    const articleId = job.article_id ?? started.article_id;
+    if (!articleId)
+        throw new CliError('bad_response', 'The job finished but no article id was returned.');
+    const raw = await api.get(`/api/v1/articles/${encodeURIComponent(articleId)}`);
+    const article = 'article' in raw.data ? raw.data.article : raw.data;
+    out.result('write', { job_id: started.job_id, article }, () => {
+        const checks = article.verdict?.checks ?? [];
+        const counts = summarizeChecks(checks);
+        out.line();
+        out.line(out.style.bold(article.title));
+        out.line(`status: ${article.status}`);
+        if (article.url)
+            out.line(`url: ${article.url}`);
+        if (article.verdict) {
+            const verdict = article.verdict.pass ? out.style.green('PASS') : out.style.red('FAIL');
+            const score = typeof article.verdict.score === 'number' ? ` (score ${article.verdict.score})` : '';
+            out.line(`fact-check: ${verdict}${score}: ${counts.verified} claims verified, ${counts.held} held`);
+            for (const c of checks.filter((x) => x.status !== 'verified')) {
+                out.line(`  ${out.style.yellow(c.status.toUpperCase())} ${c.claim}`);
+            }
+        }
+        if (!article.url)
+            out.line(`Publish it with: paperboy publish ${article.id}`);
+    });
+    return 0;
+}

package/dist/config.js

@@ -0,0 +1,66 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_BASE_URL } from './version.js';
+export function configDir(env) {
+    if (env['PAPERBOY_CONFIG_DIR'])
+        return env['PAPERBOY_CONFIG_DIR'];
+    if (env['XDG_CONFIG_HOME'])
+        return join(env['XDG_CONFIG_HOME'], 'paperboy');
+    return join(env['HOME'] ?? env['USERPROFILE'] ?? homedir(), '.config', 'paperboy');
+}
+export function configPath(env) {
+    return join(configDir(env), 'config.json');
+}
+export function readConfig(env) {
+    try {
+        const parsed = JSON.parse(readFileSync(configPath(env), 'utf8'));
+        if (!parsed || typeof parsed !== 'object')
+            return {};
+        const raw = parsed;
+        const out = {};
+        if (typeof raw['base_url'] === 'string')
+            out.base_url = raw['base_url'];
+        if (typeof raw['api_key'] === 'string')
+            out.api_key = raw['api_key'];
+        if (typeof raw['default_site'] === 'string')
+            out.default_site = raw['default_site'];
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Merge `patch` into the stored config. Directory is 0700 and the file 0600. */
+export function updateConfig(env, patch) {
+    const dir = configDir(env);
+    const file = configPath(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        // Not fatal, for example on filesystems without permissions.
+    }
+    const next = { ...readConfig(env), ...patch };
+    writeFileSync(file, JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // Same as above.
+    }
+    return file;
+}
+/** Precedence: flag, then environment, then config file. */
+export function resolveSettings(flags, env, file) {
+    const baseUrl = flags['base-url'] || env['PAPERBOY_BASE_URL'] || file.base_url || DEFAULT_BASE_URL;
+    return {
+        baseUrl: baseUrl.replace(/\/+$/, ''),
+        apiKey: flags['api-key'] || env['PAPERBOY_API_KEY'] || file.api_key || undefined,
+        site: flags.site || file.default_site || undefined,
+    };
+}
+export function maskKey(key) {
+    return key.slice(0, 12) + '...';
+}

package/dist/context.js

@@ -0,0 +1,9 @@
+import { ApiClient } from './api.js';
+export function makeClient(ctx, overrides = {}) {
+    return new ApiClient({
+        baseUrl: overrides.baseUrl ?? ctx.settings.baseUrl,
+        apiKey: 'apiKey' in overrides ? overrides.apiKey : ctx.settings.apiKey,
+        fetch: ctx.deps.fetch,
+        timeoutMs: overrides.timeoutMs,
+    });
+}

package/dist/errors.js

@@ -0,0 +1,47 @@
+/** An error the CLI knows how to present to the user. */
+export class CliError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.status = status;
+    }
+}
+/** An error response from the Paperboy API, already mapped to a friendly message. */
+export class ApiError extends CliError {
+    requestId;
+    apiMessage;
+    constructor(opts) {
+        super(opts.code, friendlyMessage(opts.status, opts.apiMessage, opts.requestId), opts.status);
+        this.name = 'ApiError';
+        this.requestId = opts.requestId;
+        this.apiMessage = opts.apiMessage;
+    }
+}
+export function friendlyMessage(status, apiMessage, requestId) {
+    const detail = apiMessage ? ` ${apiMessage}` : '';
+    const ref = requestId ? ` (request ${requestId})` : '';
+    switch (status) {
+        case 401:
+            return 'Not signed in, or the API key was rejected. Run `paperboy connect` to sign in.';
+        case 402:
+            return `Not enough credits for this action. Add credits in your Paperboy dashboard and try again.${ref}`;
+        case 403:
+            return `You do not have access to that.${detail}${ref}`;
+        case 404:
+            return `Not found.${detail}${ref}`;
+        case 409:
+            return `Conflict.${detail}${ref}`;
+        case 422:
+            return `The request was not accepted.${detail}${ref}`;
+        case 429:
+            return `Rate limited. Wait a moment and try again.${ref}`;
+        default:
+            if (status >= 500) {
+                return `The Paperboy server had a problem (HTTP ${status}). Try again shortly.${detail}${ref}`;
+            }
+            return `${apiMessage ?? `Request failed with HTTP ${status}.`}${ref}`;
+    }
+}

package/dist/help.js

@@ -0,0 +1,39 @@
+export const HELP = `paperboy - the open-source growth engine from the command line
+
+Usage: paperboy <command> [options]
+
+Commands:
+  connect [site-url]     Sign in (device flow) and optionally add a site + Search Console
+  topics                 Pick topics worth writing, from Search Console data
+  write                  Write, fact-check and (optionally) publish an article
+  check <url|file.md>    Fact-check a page or a markdown file (exit 1 if it fails)
+  publish <article-id>   Publish a drafted article
+  status                 Show account, credits and site status
+  report                 Search performance report for the site
+  mcp                    Run an MCP server on stdio, so an AI agent can use these commands as tools
+
+Global options:
+  --json                 Print exactly one JSON object per command
+  --site <id|domain>     Site to use (default: saved default, or your only site)
+  --api-key <key>        API key (env PAPERBOY_API_KEY)
+  --base-url <url>       API base URL (env PAPERBOY_BASE_URL, default https://paperboyseo.com)
+  --no-color             Disable colored output (also honors NO_COLOR)
+  -y, --yes              Do not ask for confirmation
+  -h, --help             Show this help
+  -v, --version          Show the version
+
+Command options:
+  connect  --self-host <url>  Use a self-hosted instance (saved as base_url)
+           --api-key <key>    Skip the browser flow and save this key
+           --no-wait          Print the Search Console link without waiting
+           --no-open          Do not open the browser
+  topics   -n, --n <count>    How many topics (default 5)
+  write    --topic <id|text>  A topic id from \`paperboy topics\`, or free text in quotes
+           --publish          Publish when the fact-check passes
+           --wait / --no-wait Wait for the job (default: wait on a terminal)
+  check    --sources <file>   Extra source URLs or notes, one per line
+  report   --days <n>         Window in days (default 28)
+           --markdown         Render a markdown report on the server
+
+Exit codes: 0 ok, 1 fact-check failed (or nothing published), 2 error.
+Docs: https://paperboyseo.com/docs/cli`;

package/dist/jobs.js

@@ -0,0 +1,34 @@
+import { CliError } from './errors.js';
+function jobErrorMessage(error) {
+    if (!error)
+        return 'The job failed.';
+    if (typeof error === 'string')
+        return error;
+    return error.message ?? error.code ?? 'The job failed.';
+}
+/**
+ * Poll GET /api/v1/jobs/{id} until it is done or failed. Time is counted from the
+ * sleeps themselves so the loop is deterministic when `sleep` is stubbed in tests.
+ */
+export async function pollJob(ctx, api, jobId, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 2000;
+    const timeoutMs = opts.timeoutMs ?? 10 * 60_000;
+    let waited = 0;
+    let lastStep;
+    for (;;) {
+        const { data: job } = await api.get(`/api/v1/jobs/${encodeURIComponent(jobId)}`);
+        if (job.step && job.step !== lastStep) {
+            lastStep = job.step;
+            ctx.out.info(ctx.out.style.dim(`  ${job.step}`));
+        }
+        if (job.status === 'done')
+            return job;
+        if (job.status === 'failed')
+            throw new CliError('job_failed', jobErrorMessage(job.error));
+        if (waited >= timeoutMs) {
+            throw new CliError('job_timeout', `Job ${jobId} is still running. Check on it later with \`paperboy status\`.`);
+        }
+        await ctx.deps.sleep(intervalMs);
+        waited += intervalMs;
+    }
+}