@paperboyseo/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,189 @@
-# Temporary Holding Version
+# @paperboyseo/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The command line for [Paperboy](https://paperboyseo.com), the open-source growth engine. Paperboy reads your Google Search Console data, picks topics worth writing, writes and fact-checks articles, publishes them and measures the result. This CLI drives all of that from your terminal or from CI.
+
+- Zero runtime dependencies, Node 22 or newer.
+- Works against the hosted service (`https://paperboyseo.com`) or your own self-hosted instance.
+- Every command has a stable `--json` mode.
+
+## Install
+
+`@paperboyseo/cli` is not on npm. Run it from a clone of the repository (Node 22 or newer):
+
+```sh
+git clone https://github.com/paperboyseo/paperboy.git && cd paperboy
+npm ci --prefix packages/cli && npm run build --prefix packages/cli
+alias paperboy="node $PWD/packages/cli/dist/cli.js"     # also available as paperboy-seo via the package bin
+paperboy connect
+```
+
+Note: the unscoped npm package named `paperboy` is a different project, so do not `npx paperboy`.
+
+## Quick start
+
+```sh
+paperboy connect https://yoursite.com   # sign in, add the site, connect Search Console
+paperboy topics                         # what should we write next?
+paperboy write --topic top_abc123 --wait
+paperboy report
+```
+
+## Commands
+
+Global flags: `--json`, `--site <id|domain>`, `--api-key <key>`, `--base-url <url>`, `--no-color`, `--yes`, `--help`, `--version`.
+
+### connect
+
+```sh
+paperboy connect [site-url] [--self-host <baseUrl>] [--api-key <key>] [--no-wait] [--no-open]
+```
+
+Signs in with the OAuth 2.0 device flow: the CLI prints a short code and a URL, opens your browser, and waits until you approve. The API key is saved to the config file. With `--api-key` the browser step is skipped and the key you paste is verified and saved.
+
+If you pass a site URL, Paperboy adds the site, saves it as your default, and walks you through the Search Console authorization. The CLI waits up to 5 minutes for it to complete; use `--no-wait` to just print the link.
+
+```sh
+paperboy connect https://yoursite.com
+paperboy connect --self-host http://localhost:3000
+paperboy connect --api-key pb_live_xxxxxxxx --self-host https://paperboy.example.com
+```
+
+### topics
+
+```sh
+paperboy topics [--n 5]
+```
+
+Lists the best topics to write next, each with why it was picked and the signals behind it (impressions, average position, SERP gate).
+
+```
+1. Best coffee grinders  [top_1]
+   query: best coffee grinder
+   why: Page two with rising impressions
+   signals: 12,400 impressions, position 11.3, serp gate: pass
+```
+
+### write
+
+```sh
+paperboy write [--topic <id|"free text">] [--publish] [--wait | --no-wait]
+```
+
+Starts an article job. `--topic` takes a topic id from `paperboy topics`, or free text in quotes (anything containing whitespace is treated as text). Without `--topic` Paperboy picks one. With `--wait` (the default on a terminal) the CLI follows the job, then prints the title, status, URL and the fact-check summary (claims verified and held). Without it, the job id is printed and the command returns immediately. Each write sends an `Idempotency-Key` so retries never double-charge credits.
+
+### check
+
+```sh
+paperboy check <url|file.md> [--sources sources.txt]
+```
+
+Fact-checks a live URL or a local markdown file. `--sources` is a text file with one extra source URL per line (blank lines and lines starting with `#` are ignored). Claims are reported as VERIFIED, HELD, UNSUPPORTED or MISMATCH. The exit code is 0 when the check passes and 1 when it does not, so it drops straight into CI:
+
+```sh
+paperboy check docs/launch-post.md || exit 1
+```
+
+### publish
+
+```sh
+paperboy publish <article-id>
+```
+
+Publishes an article through the site's configured publish method. On a terminal it asks for confirmation unless you pass `--yes`.
+
+### status
+
+```sh
+paperboy status
+```
+
+Shows the account owner, the credits balance (when credits are enabled), the site domain, its publish method, whether Search Console is connected, and the latest articles.
+
+### report
+
+```sh
+paperboy report [--days 28] [--markdown]
+```
+
+Prints totals (clicks, impressions, average position, CTR), a unicode sparkline of daily clicks and the last seven days. With `--markdown` the server renders a full markdown report instead.
+
+### mcp
+
+```sh
+paperboy mcp
+```
+
+Runs a Model Context Protocol server on stdio, so an AI agent can use the commands above as tools (`list_sites`, `suggest_topics`, `write_article`, `get_job`, `get_article`, `fact_check`, `publish_article`, `get_performance`). It uses the same key and base URL as every other command. Setup for Claude Code, Claude Desktop and Cursor: [docs/mcp.md](../../docs/mcp.md).
+
+## Choosing a site
+
+Resolution order: `--site <id|domain>`, then the saved `default_site`, then the only site on your account. If you have several sites and none is selected, the CLI lists them and exits with an error.
+
+## JSON output
+
+With `--json`, every command prints exactly one JSON object on stdout and nothing else. Progress text and the device-flow code go to stderr.
+
+Success:
+
+```json
+{ "ok": true, "command": "topics", "data": { "topics": [] } }
+```
+
+`data` is the API response for the command (for `write --wait` it is `{ "job_id", "article" }`, for `connect` it holds the base URL, a masked key preview, the config path and the site).
+
+Failure:
+
+```json
+{ "ok": false, "error": { "code": "unauthorized", "message": "...", "status": 401 } }
+```
+
+`status` is present for HTTP errors. Error codes come from the API when available, plus CLI codes such as `usage`, `network_error`, `timeout`, `bad_response`, `job_failed`, `site_required`, `no_site`, `expired_token` and `access_denied`.
+
+## Exit codes
+
+| Code | Meaning |
+| ---- | ------- |
+| 0 | Success (for `check`: the fact-check passed) |
+| 1 | `check` did not pass, or `publish` did not publish |
+| 2 | Error: bad usage, network or API error, job failure |
+
+In `--json` mode a failing `check` still prints `"ok": true` (the command ran) with `data.pass` set to `false`, and exits 1.
+
+## Configuration
+
+Settings resolve in this order: command-line flag, then environment variable, then config file.
+
+| Setting | Flag | Environment | Config key |
+| ------- | ---- | ----------- | ---------- |
+| API key | `--api-key` | `PAPERBOY_API_KEY` | `api_key` |
+| Base URL | `--base-url` | `PAPERBOY_BASE_URL` | `base_url` |
+| Site | `--site` | none | `default_site` |
+
+The config file lives at `~/.config/paperboy/config.json` (or `$XDG_CONFIG_HOME/paperboy/config.json`; `PAPERBOY_CONFIG_DIR` overrides the directory). The directory is created with mode 0700 and the file with mode 0600. The CLI never prints your API key, only the first 12 characters followed by `...`.
+
+Other environment variables: `NO_COLOR` (disable color), `FORCE_COLOR` (enable color), `PAPERBOY_NO_OPEN=1` (never open a browser).
+
+## Self-hosting
+
+Point the CLI at your own instance once and it remembers:
+
+```sh
+paperboy connect --self-host http://localhost:3000
+paperboy status
+```
+
+Or per command: `paperboy topics --base-url http://localhost:3000`, or set `PAPERBOY_BASE_URL`.
+
+## Development
+
+```sh
+npm ci
+npm run build
+npm test
+```
+
+Tests run the CLI end to end against a local mock HTTP server.
+
+## License
+
+AGPL-3.0-only, copyright Hive Asset Group, LLC. See the LICENSE file in this package.

package/dist/api.js

@@ -0,0 +1,121 @@
+import { ApiError, CliError } from './errors.js';
+import { VERSION } from './version.js';
+export class ApiClient {
+    baseUrl;
+    apiKey;
+    fetchFn;
+    timeoutMs;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.apiKey = opts.apiKey;
+        this.fetchFn = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+    }
+    get(path, opts = {}) {
+        return this.request('GET', path, opts);
+    }
+    post(path, body, opts = {}) {
+        return this.request('POST', path, { ...opts, body: body ?? {} });
+    }
+    async request(method, path, opts = {}) {
+        const auth = opts.auth ?? true;
+        if (auth && !this.apiKey) {
+            throw new ApiError({ code: 'unauthenticated', status: 401 });
+        }
+        let url = this.baseUrl + path;
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(opts.query ?? {})) {
+            if (value !== undefined)
+                params.set(key, String(value));
+        }
+        const qs = params.toString();
+        if (qs)
+            url += (url.includes('?') ? '&' : '?') + qs;
+        const headers = {
+            Accept: 'application/json',
+            'User-Agent': `paperboy-cli/${VERSION}`,
+        };
+        if (auth && this.apiKey)
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        if (opts.idempotencyKey)
+            headers['Idempotency-Key'] = opts.idempotencyKey;
+        const init = { method, headers, signal: AbortSignal.timeout(opts.timeoutMs ?? this.timeoutMs) };
+        if (opts.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(opts.body);
+        }
+        let res;
+        try {
+            res = await this.fetchFn(url, init);
+        }
+        catch (err) {
+            throw networkError(err, this.baseUrl);
+        }
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch (err) {
+            throw networkError(err, this.baseUrl);
+        }
+        const parsed = parseJson(text);
+        if (!res.ok)
+            throw toApiError(res.status, parsed, text);
+        if (parsed === undefined && text.trim() !== '') {
+            throw new CliError('bad_response', `${this.baseUrl} did not return JSON. Check the URL (use --base-url or --self-host).`, res.status);
+        }
+        return { status: res.status, data: (parsed ?? {}) };
+    }
+}
+function parseJson(text) {
+    if (text.trim() === '')
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function networkError(err, baseUrl) {
+    const name = err instanceof Error ? err.name : '';
+    if (name === 'TimeoutError' || name === 'AbortError') {
+        return new CliError('timeout', `The request to ${baseUrl} timed out.`);
+    }
+    const cause = err instanceof Error && err.cause instanceof Error ? err.cause.message : undefined;
+    const message = cause ?? (err instanceof Error ? err.message : String(err));
+    return new CliError('network_error', `Could not reach ${baseUrl}: ${message}`);
+}
+/** Accepts both {error:{code,message,request_id}} and the RFC 6749 style {error:"code"}. */
+export function toApiError(status, body, rawText = '') {
+    let code = `http_${status}`;
+    let apiMessage;
+    let requestId;
+    if (body && typeof body === 'object') {
+        const err = body['error'];
+        if (typeof err === 'string') {
+            code = err;
+            const desc = body['error_description'];
+            if (typeof desc === 'string')
+                apiMessage = desc;
+        }
+        else if (err && typeof err === 'object') {
+            const e = err;
+            if (typeof e['code'] === 'string')
+                code = e['code'];
+            if (typeof e['message'] === 'string')
+                apiMessage = e['message'];
+            if (typeof e['request_id'] === 'string')
+                requestId = e['request_id'];
+        }
+    }
+    else if (rawText && rawText.length < 200 && !rawText.trimStart().startsWith('<')) {
+        apiMessage = rawText.trim();
+    }
+    const opts = { code, status };
+    if (apiMessage !== undefined)
+        opts.apiMessage = apiMessage;
+    if (requestId !== undefined)
+        opts.requestId = requestId;
+    return new ApiError(opts);
+}

package/dist/args.js

@@ -0,0 +1,40 @@
+import { parseArgs } from 'node:util';
+import { CliError } from './errors.js';
+export const OPTIONS = {
+    json: { type: 'boolean' },
+    site: { type: 'string' },
+    'api-key': { type: 'string' },
+    'base-url': { type: 'string' },
+    'no-color': { type: 'boolean' },
+    yes: { type: 'boolean', short: 'y' },
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' },
+    'self-host': { type: 'string' },
+    'no-wait': { type: 'boolean' },
+    'no-open': { type: 'boolean' },
+    wait: { type: 'boolean' },
+    n: { type: 'string', short: 'n' },
+    topic: { type: 'string' },
+    publish: { type: 'boolean' },
+    sources: { type: 'string' },
+    days: { type: 'string' },
+    markdown: { type: 'boolean' },
+};
+export function parse(argv) {
+    try {
+        const { values, positionals } = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+        return { flags: values, positionals };
+    }
+    catch (err) {
+        throw new CliError('usage', (err instanceof Error ? err.message : String(err)) + ' (see `paperboy --help`)');
+    }
+}
+export function intFlag(value, name, fallback, max) {
+    if (value === undefined)
+        return fallback;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > max) {
+        throw new CliError('usage', `--${name} must be a whole number between 1 and ${max}.`);
+    }
+    return n;
+}

package/dist/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { run } from './main.js';
+process.exitCode = await run(process.argv.slice(2), {
+    env: process.env, stdout: process.stdout, stderr: process.stderr,
+});

package/dist/commands/check.js

@@ -0,0 +1,51 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { CliError } from '../errors.js';
+import { pollJob } from '../jobs.js';
+function readText(path, what) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        const reason = err instanceof Error && 'code' in err ? String(err.code) : 'unreadable';
+        throw new CliError('file_error', `Could not read ${what} "${path}" (${reason}).`);
+    }
+}
+export async function check(ctx) {
+    const { out, flags } = ctx;
+    const target = ctx.args[0];
+    if (!target)
+        throw new CliError('usage', 'Usage: paperboy check <url|file.md> [--sources file]');
+    const body = /^https?:\/\//i.test(target) ? { url: target } : { markdown: readText(target, 'file') };
+    if (flags.sources) {
+        body['sources'] = readText(flags.sources, 'sources file')
+            .split(/\r?\n/)
+            .map((l) => l.trim())
+            .filter((l) => l !== '' && !l.startsWith('#'));
+    }
+    const api = ctx.client({ timeoutMs: 120_000 });
+    const res = await api.post('/api/v1/fact-check', body, { idempotencyKey: randomUUID() });
+    let result;
+    if (res.status === 202 || 'job_id' in res.data) {
+        const jobId = res.data.job_id;
+        out.info(`Fact-check queued (${jobId}).`);
+        const job = await pollJob(ctx, api, jobId, { intervalMs: 2000 });
+        result = (job.result ?? job);
+    }
+    else {
+        result = res.data;
+    }
+    const checks = result.checks ?? [];
+    const total = result.claims_total ?? checks.length;
+    const verified = result.claims_verified ?? checks.filter((c) => c.status === 'verified').length;
+    out.result('check', result, () => {
+        const s = out.style;
+        out.line(`${result.pass ? s.green('PASS') : s.red('FAIL')}: ${verified} of ${total} claims verified`);
+        for (const c of checks) {
+            const label = c.status === 'verified' ? s.green('VERIFIED') : c.status === 'held' ? s.yellow('HELD') : s.red(c.status.toUpperCase());
+            const extra = [c.note, c.source ? `source: ${c.source}` : undefined].filter(Boolean).join('; ');
+            out.line(`  ${label} ${c.claim}${extra ? s.dim(` (${extra})`) : ''}`);
+        }
+    });
+    return result.pass ? 0 : 1;
+}

package/dist/commands/connect.js

@@ -0,0 +1,161 @@
+import { maskKey, updateConfig, configPath } from '../config.js';
+import { ApiError, CliError } from '../errors.js';
+const GSC_POLL_MS = 3000;
+const GSC_TIMEOUT_MS = 5 * 60_000;
+function normalizeBase(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new CliError('usage', `"${value}" is not a valid URL. Example: http://localhost:3000`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new CliError('usage', `"${value}" must start with http:// or https://`);
+    }
+    return value.replace(/\/+$/, '');
+}
+function normalizeSiteUrl(value) {
+    return /^https?:\/\//i.test(value) ? value : `https://${value}`;
+}
+export async function connect(ctx) {
+    const { flags, out, env } = ctx;
+    const baseUrl = normalizeBase(flags['self-host'] ?? ctx.settings.baseUrl);
+    const shouldOpen = !out.json && !flags['no-open'] && !env['PAPERBOY_NO_OPEN'];
+    const open = (url) => {
+        if (shouldOpen)
+            ctx.deps.open(url);
+    };
+    let apiKey;
+    let usedDeviceFlow = false;
+    if (flags['api-key']) {
+        apiKey = flags['api-key'];
+        await verifyKey(ctx.client({ baseUrl, apiKey }), baseUrl);
+    }
+    else {
+        apiKey = await deviceFlow(ctx, ctx.client({ baseUrl, apiKey: undefined }), open);
+        usedDeviceFlow = true;
+    }
+    const file = updateConfig(env, { base_url: baseUrl, api_key: apiKey });
+    const api = ctx.client({ baseUrl, apiKey });
+    const data = {
+        base_url: baseUrl,
+        api_key_preview: maskKey(apiKey),
+        config_path: file,
+        auth: usedDeviceFlow ? 'device_flow' : 'api_key',
+    };
+    out.prompt(`${out.style.green('Signed in.')} Saved key ${maskKey(apiKey)} to ${configPath(env)}`);
+    const siteArg = ctx.args[0];
+    if (siteArg) {
+        const site = await addSite(ctx, api, normalizeSiteUrl(siteArg), open, data);
+        data['site'] = site;
+    }
+    out.result('connect', data, () => {
+        if (data['site']) {
+            const site = data['site'];
+            out.line(`Site: ${site.domain} (${site.id})`);
+            out.line(`Search Console: ${site.gsc_connected ? out.style.green('connected') : out.style.yellow('not connected yet')}`);
+        }
+        out.line('Next: `paperboy topics` to see what to write.');
+    });
+    return 0;
+}
+async function verifyKey(api, baseUrl) {
+    try {
+        await api.get('/api/v1/me');
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 401) {
+            throw new CliError('invalid_api_key', `${baseUrl} rejected that API key.`, 401);
+        }
+        throw err;
+    }
+}
+async function deviceFlow(ctx, api, open) {
+    const { out } = ctx;
+    const { data: code } = await api.post('/api/v1/device/code', { client: 'paperboy-cli' }, { auth: false });
+    const url = code.verification_uri_complete ?? code.verification_uri;
+    out.prompt('To sign in, open this page in your browser:');
+    out.prompt(`  ${out.style.cyan(url)}`);
+    out.prompt(`and confirm this code: ${out.style.bold(code.user_code)}`);
+    out.prompt('Waiting for approval...');
+    open(url);
+    let intervalMs = Math.max(0, (code.interval ?? 5) * 1000);
+    const expiresMs = (code.expires_in ?? 600) * 1000;
+    let waited = 0;
+    for (;;) {
+        if (waited >= expiresMs)
+            throw expired();
+        await ctx.deps.sleep(intervalMs);
+        waited += intervalMs;
+        try {
+            const { data } = await api.post('/api/v1/device/token', { device_code: code.device_code }, { auth: false });
+            if (!data.api_key)
+                throw new CliError('bad_response', 'The server approved the sign-in but returned no API key.');
+            return data.api_key;
+        }
+        catch (err) {
+            if (!(err instanceof ApiError))
+                throw err;
+            switch (err.code) {
+                case 'authorization_pending':
+                    break;
+                case 'slow_down':
+                    intervalMs += 5000;
+                    break;
+                case 'expired_token':
+                    throw expired();
+                case 'access_denied':
+                    throw new CliError('access_denied', 'Sign-in was denied in the browser. Run `paperboy connect` to try again.');
+                default:
+                    throw err;
+            }
+        }
+    }
+}
+function expired() {
+    return new CliError('expired_token', 'The sign-in code expired before it was approved. Run `paperboy connect` again.');
+}
+async function addSite(ctx, api, siteUrl, open, data) {
+    const { out, env } = ctx;
+    const created = await api.post('/api/v1/sites', { url: siteUrl });
+    let site = created.data.site;
+    updateConfig(env, { default_site: site.id });
+    out.prompt(`Added ${out.style.bold(site.domain)} (${site.id}) and set it as your default site.`);
+    if (site.gsc_connected)
+        return site;
+    let link = created.data.gsc_connect_url;
+    if (!link) {
+        try {
+            const res = await api.post(`/api/v1/sites/${encodeURIComponent(site.id)}/gsc/connect`, {});
+            link = res.data.url;
+        }
+        catch (err) {
+            // A self-host without its own Google OAuth client can still write and fact check, just without Search Console data.
+            if (err instanceof CliError && err.code === 'gsc_not_configured') {
+                out.prompt('Search Console is not set up on this server (GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET). Skipping it; see docs/self-host.md.');
+                return site;
+            }
+            throw err;
+        }
+    }
+    data['gsc_connect_url'] = link;
+    out.prompt('Connect Google Search Console so Paperboy can read your data:');
+    out.prompt(`  ${out.style.cyan(link)}`);
+    open(link);
+    if (ctx.flags['no-wait'])
+        return site;
+    out.prompt('Waiting for Search Console authorization...');
+    let waited = 0;
+    while (!site.gsc_connected) {
+        if (waited >= GSC_TIMEOUT_MS) {
+            throw new CliError('gsc_timeout', 'Search Console was not connected within 5 minutes. Open the link above, then run `paperboy status`.');
+        }
+        await ctx.deps.sleep(GSC_POLL_MS);
+        waited += GSC_POLL_MS;
+        const res = await api.get(`/api/v1/sites/${encodeURIComponent(site.id)}`);
+        site = res.data.site;
+    }
+    out.prompt(out.style.green('Search Console connected.'));
+    return site;
+}