@cookiecrumbs-eu/mcp 0.7.0

package/dist/cli/src/jobs.js

@@ -0,0 +1,59 @@
+import { CliError } from "./errors.js";
+import { human, spinner } from "./output.js";
+import { pollMs, sleep } from "./util.js";
+const WORKER_HINT = 'Export jobs are processed by cc-worker; make sure a worker is running (npm run start -w @cookiecrumbs/cc-worker).';
+/** Poll GET /v1/exports/:id every 3 s (default) until completed/failed/expired or the timeout. */
+export async function waitForExport(api, id, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 10 * 60 * 1000;
+    const started = Date.now();
+    const s = spinner(`${opts.label ?? 'Export'} ${id} queued — ${WORKER_HINT}`);
+    let polls = 0;
+    for (;;) {
+        const job = await api.exportJob(id);
+        polls++;
+        if (job.status === 'completed') {
+            s.stop(`${opts.label ?? 'Export'} ${id} completed${job.record_count != null ? ` (${job.record_count} records)` : ''}`);
+            return job;
+        }
+        if (job.status === 'failed' || job.status === 'expired') {
+            s.fail(`${opts.label ?? 'Export'} ${id} ${job.status}${job.error ? `: ${job.error}` : ''}`);
+            throw new CliError(`export_${job.status}`, `Export job ${id} ${job.status}${job.error ? `: ${job.error}` : ''}.`, 1, { extra: { job } });
+        }
+        const elapsed = Math.round((Date.now() - started) / 1000);
+        s.message(`${opts.label ?? 'Export'} ${id} ${job.status} (${elapsed}s) — ${job.status === 'queued' ? 'waiting for a worker' : 'running'}`);
+        if (Date.now() - started > timeoutMs) {
+            s.fail(`Gave up after ${Math.round(timeoutMs / 1000)}s; the job is still ${job.status}`);
+            throw new CliError('export_timeout', `Export job ${id} is still ${job.status} after ${Math.round(timeoutMs / 1000)}s. ${WORKER_HINT} Re-attach later with --job ${id}.`, 1, { extra: { job, polls } });
+        }
+        await sleep(pollMs(3000));
+    }
+}
+const DONE = ['completed', 'failed', 'cancelled'];
+/** Poll GET /v1/scans/:id every 5 s (default) until it finishes or the timeout. */
+export async function waitForScan(api, id, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 30 * 60 * 1000;
+    const started = Date.now();
+    const s = spinner(`Checking scan ${id}`);
+    for (;;) {
+        const scan = await api.scan(id);
+        if (DONE.includes(scan.status)) {
+            if (scan.status === 'completed')
+                s.stop(`Scan ${id} completed`);
+            else
+                s.fail(`Scan ${id} ${scan.status}${scan.error ? `: ${scan.error}` : ''}`);
+            return scan;
+        }
+        const pages = scan.pages_crawled != null ? ` · ${scan.pages_crawled}${scan.page_cap ? `/${scan.page_cap}` : ''} pages` : '';
+        const prog = scan.progress && typeof scan.progress === 'object' ? scan.progress : {};
+        const url = typeof prog.url === 'string' ? ` · ${prog.url}` : '';
+        s.message(`Scan ${id} ${scan.status}${pages}${url} (${Math.round((Date.now() - started) / 1000)}s)`);
+        if (Date.now() - started > timeoutMs) {
+            s.fail(`Gave up after ${Math.round(timeoutMs / 1000)}s; the scan is still ${scan.status}`);
+            throw new CliError('scan_timeout', `Scan ${id} is still ${scan.status} after ${Math.round(timeoutMs / 1000)}s. Re-attach with --scan-id ${id}.`, 1, { extra: { scan } });
+        }
+        await sleep(pollMs(5000));
+    }
+}
+export function noteWorker() {
+    human.info(WORKER_HINT);
+}

package/dist/cli/src/merge.js

@@ -0,0 +1,38 @@
+import { createHash } from 'node:crypto';
+/**
+ * Stable JSON: keys sorted bytewise, no whitespace. Unlike the hashed-document
+ * canonJson in @cookiecrumbs/config this allows numbers (BannerConfig carries
+ * radius, expiry_months, …), so it is only used for local change detection.
+ */
+export function stableJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(stableJson).join(',') + ']';
+    const obj = value;
+    const keys = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableJson(obj[k])).join(',') + '}';
+}
+export const configHash = (value) => createHash('sha256').update(stableJson(value)).digest('hex');
+/**
+ * Three-way decision on hashes:
+ *  - remote unchanged since the last pull (or identical to local) → keep local
+ *  - local unchanged since the last pull → overwrite with remote
+ *  - both changed → conflict (caller writes cookiecrumbs.config.remote.json, exit 2)
+ */
+export function decide({ base, local, remote }) {
+    if (local === remote)
+        return 'keep';
+    if (base !== null && remote === base)
+        return 'keep';
+    if (base !== null && local === base)
+        return 'overwrite';
+    return 'conflict';
+}
+export function mergeDecision(base, local, remote) {
+    const localHash = configHash(local);
+    const remoteHash = configHash(remote);
+    return { decision: decide({ base, local: localHash, remote: remoteHash }), localHash, remoteHash };
+}

package/dist/cli/src/output.js

@@ -0,0 +1,112 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { CliError } from "./errors.js";
+let current = { json: false, api: '', cwd: process.cwd() };
+export const setCtx = (c) => (current = c);
+export const ctx = () => current;
+export const isInteractive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY) && !process.env.CI;
+/** Print the single JSON object a `--json` run is allowed to emit. */
+export function printJson(obj) {
+    process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+// ---- human output (silent under --json) ---------------------------------
+export const human = {
+    intro(text) {
+        if (!current.json)
+            p.intro(pc.bgCyan(pc.black(' cookiecrumbs ')) + ' ' + text);
+    },
+    outro(text) {
+        if (!current.json)
+            p.outro(text);
+    },
+    info(text) {
+        if (!current.json)
+            p.log.info(text);
+    },
+    step(text) {
+        if (!current.json)
+            p.log.step(text);
+    },
+    success(text) {
+        if (!current.json)
+            p.log.success(text);
+    },
+    warn(text) {
+        if (!current.json)
+            p.log.warn(text);
+    },
+    error(text) {
+        if (!current.json)
+            p.log.error(text);
+    },
+    message(text) {
+        if (!current.json)
+            p.log.message(text);
+    },
+    note(text, title) {
+        if (!current.json)
+            p.note(text, title);
+    },
+    /** Raw lines to stdout (e.g. a diff) — still suppressed under --json. */
+    print(text) {
+        if (!current.json)
+            process.stdout.write(text.endsWith('\n') ? text : text + '\n');
+    },
+};
+/** A clack spinner on a TTY, plain log lines otherwise, nothing under --json. */
+export function spinner(start) {
+    if (current.json)
+        return { message: () => { }, stop: () => { }, fail: () => { } };
+    if (isInteractive()) {
+        const s = p.spinner();
+        s.start(start);
+        return {
+            message: (t) => s.message(t),
+            stop: (t) => s.stop(t ?? start),
+            fail: (t) => s.stop(pc.red(t), 1),
+        };
+    }
+    process.stdout.write(`… ${start}\n`);
+    return {
+        message: (t) => process.stdout.write(`… ${t}\n`),
+        stop: (t) => process.stdout.write(`✓ ${t ?? start}\n`),
+        fail: (t) => process.stdout.write(`✗ ${t}\n`),
+    };
+}
+// ---- prompts (never under --json or on a non-TTY) ------------------------
+function guard(flag) {
+    if (current.json || !isInteractive()) {
+        throw new CliError('non_interactive', `Not a terminal: pass ${flag} instead of answering a prompt.`, 2);
+    }
+}
+function cancelled(value) {
+    p.cancel('Cancelled.');
+    throw new CliError('cancelled', 'Cancelled.', 2, { extra: { value: String(value) } });
+}
+export async function askText(message, flag, opts = {}) {
+    guard(flag);
+    const v = await p.text({ message, placeholder: opts.placeholder, initialValue: opts.initial, validate: opts.validate });
+    if (p.isCancel(v))
+        cancelled(v);
+    return String(v);
+}
+export async function askSelect(message, flag, options) {
+    guard(flag);
+    const v = await p.select({ message, options: options });
+    if (p.isCancel(v))
+        cancelled(v);
+    return v;
+}
+export async function askConfirm(message, flag, initial = true) {
+    guard(flag);
+    const v = await p.confirm({ message, initialValue: initial });
+    if (p.isCancel(v))
+        cancelled(v);
+    return Boolean(v);
+}
+export const dim = pc.dim;
+export const bold = pc.bold;
+export const green = pc.green;
+export const red = pc.red;
+export const yellow = pc.yellow;
+export const cyan = pc.cyan;

package/dist/cli/src/project.js

@@ -0,0 +1,269 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createJiti } from 'jiti';
+import { BannerConfigSchema } from "./configpkg.js";
+import { CliError } from "./errors.js";
+export const CONFIG_TS = 'cookiecrumbs.config.ts';
+export const CONFIG_JSON = 'cookiecrumbs.config.json';
+export const CONFIG_REMOTE = 'cookiecrumbs.config.remote.json';
+export const TEXTS_DIR = join('cookiecrumbs', 'texts');
+export const STATE_DIR = '.cookiecrumbs';
+export const STATE_FILE = join(STATE_DIR, 'state.json');
+export const PULLED_FILE = join(STATE_DIR, 'last-pulled.json');
+// ---- project root -------------------------------------------------------
+/** Walk up from cwd to the nearest folder holding a config file or .cookiecrumbs/; default cwd. */
+export function findProjectRoot(cwd) {
+    let dir = resolve(cwd);
+    for (let i = 0; i < 20; i++) {
+        if (existsSync(join(dir, CONFIG_TS)) || existsSync(join(dir, CONFIG_JSON)) || existsSync(join(dir, STATE_FILE)))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return resolve(cwd);
+}
+export function configFile(root) {
+    if (existsSync(join(root, CONFIG_TS)))
+        return { path: join(root, CONFIG_TS), format: 'ts' };
+    if (existsSync(join(root, CONFIG_JSON)))
+        return { path: join(root, CONFIG_JSON), format: 'json' };
+    return null;
+}
+// ---- state --------------------------------------------------------------
+export function readState(root) {
+    const f = join(root, STATE_FILE);
+    if (!existsSync(f))
+        return null;
+    try {
+        return JSON.parse(readFileSync(f, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeState(root, state) {
+    mkdirSync(join(root, STATE_DIR), { recursive: true });
+    writeFileSync(join(root, STATE_FILE), JSON.stringify(state, null, 2) + '\n');
+}
+export function requireState(root) {
+    const s = readState(root);
+    if (!s?.site_id)
+        throw new CliError('not_linked', `No ${STATE_FILE} here. Run \`cookiecrumbs init\` or \`cookiecrumbs link --site <id>\`.`, 2);
+    return s;
+}
+export function readPulled(root) {
+    const f = join(root, PULLED_FILE);
+    if (!existsSync(f))
+        return null;
+    try {
+        return JSON.parse(readFileSync(f, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writePulled(root, config) {
+    mkdirSync(join(root, STATE_DIR), { recursive: true });
+    writeFileSync(join(root, PULLED_FILE), JSON.stringify(config, null, 2) + '\n');
+}
+export function readTextsDir(root) {
+    const dir = join(root, TEXTS_DIR);
+    const out = {};
+    if (!existsSync(dir))
+        return out;
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith('.json'))
+            continue;
+        const lang = f.slice(0, -5);
+        try {
+            const raw = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+            out[lang] = { texts: raw.texts ?? {}, category_texts: raw.category_texts ?? {} };
+        }
+        catch (e) {
+            throw new CliError('texts_invalid', `${relative(root, join(dir, f))} is not valid JSON: ${e.message}`, 1);
+        }
+    }
+    return out;
+}
+export function writeTextsDir(root, config) {
+    const dir = join(root, TEXTS_DIR);
+    mkdirSync(dir, { recursive: true });
+    const langs = new Set([...Object.keys(config.texts ?? {}), ...Object.keys(config.category_texts ?? {})]);
+    const written = [];
+    for (const lang of [...langs].sort()) {
+        const doc = { texts: config.texts?.[lang] ?? {}, category_texts: config.category_texts?.[lang] ?? {} };
+        const file = join(dir, `${lang}.json`);
+        writeFileSync(file, JSON.stringify(doc, null, 2) + '\n');
+        written.push(file);
+    }
+    // drop files for languages that no longer exist
+    for (const f of readdirSync(dir))
+        if (f.endsWith('.json') && !langs.has(f.slice(0, -5)))
+            rmSync(join(dir, f));
+    return written;
+}
+/** Merge cookiecrumbs/texts/<lang>.json over the config file's own texts (the file may omit them). */
+export function mergeTexts(config, texts) {
+    const out = { ...config };
+    const t = { ...(config.texts ?? {}) };
+    const ct = { ...(config.category_texts ?? {}) };
+    for (const [lang, doc] of Object.entries(texts)) {
+        if (Object.keys(doc.texts).length)
+            t[lang] = { ...(t[lang] ?? {}), ...doc.texts };
+        if (Object.keys(doc.category_texts).length)
+            ct[lang] = { ...(ct[lang] ?? {}), ...doc.category_texts };
+    }
+    out.texts = t;
+    out.category_texts = ct;
+    return out;
+}
+// ---- loader -------------------------------------------------------------
+/** Path of the compiled (or source) @cookiecrumbs/config entry shipped with the CLI, for the jiti alias. */
+export function bundledConfigPackage() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const rel of ['../../config/src/index.js', '../../config/src/index.ts']) {
+        const p = resolve(here, rel);
+        if (existsSync(p))
+            return p;
+    }
+    return '@cookiecrumbs/config';
+}
+/** Load cookiecrumbs.config.ts|json (jiti for TS, JSON fallback) and merge the texts folder. Validates against the schema. */
+export async function loadLocalConfig(root) {
+    const file = configFile(root);
+    if (!file)
+        throw new CliError('no_config', `No ${CONFIG_TS} or ${CONFIG_JSON} in ${root}. Run \`cookiecrumbs init\`.`, 2);
+    let raw;
+    if (file.format === 'json') {
+        try {
+            raw = JSON.parse(readFileSync(file.path, 'utf8'));
+        }
+        catch (e) {
+            throw new CliError('config_invalid', `${CONFIG_JSON} is not valid JSON: ${e.message}`, 1);
+        }
+    }
+    else {
+        raw = await loadTs(file.path);
+    }
+    if (!raw || typeof raw !== 'object')
+        throw new CliError('config_invalid', `${relative(root, file.path)} does not export a config object.`, 1);
+    const texts = readTextsDir(root);
+    const merged = mergeTexts(raw, texts);
+    const parsed = BannerConfigSchema.safeParse(merged);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`);
+        throw new CliError('schema', `Config does not match the BannerConfig schema:\n  ${issues.join('\n  ')}`, 1, { extra: { issues: parsed.error.issues } });
+    }
+    return { config: parsed.data, raw: merged, file: file.path, format: file.format, langs: Object.keys(texts).sort() };
+}
+async function loadTs(path) {
+    const jiti = createJiti(pathToFileURL(path).href, {
+        interopDefault: true,
+        moduleCache: false,
+        fsCache: false,
+        alias: { '@cookiecrumbs/config': bundledConfigPackage() },
+    });
+    let mod;
+    try {
+        mod = await jiti.import(path, { default: true });
+    }
+    catch (e) {
+        throw new CliError('config_invalid', `Could not load ${path}: ${e.message}`, 1);
+    }
+    if (typeof mod === 'function')
+        mod = await mod();
+    return mod;
+}
+// ---- writer -------------------------------------------------------------
+const IDENT = /^[A-Za-z_$][\w$]*$/;
+/** Readable TypeScript object literal (2-space indent, unquoted identifier keys, JSON-escaped strings). */
+export function toTsLiteral(value, indent = 0) {
+    const pad = '  '.repeat(indent);
+    const inner = '  '.repeat(indent + 1);
+    if (value === null || value === undefined)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        const simple = value.every((v) => typeof v !== 'object' || v === null);
+        if (simple)
+            return '[' + value.map((v) => toTsLiteral(v, indent + 1)).join(', ') + ']';
+        return '[\n' + value.map((v) => inner + toTsLiteral(v, indent + 1)).join(',\n') + ',\n' + pad + ']';
+    }
+    const entries = Object.entries(value).filter(([, v]) => v !== undefined);
+    if (entries.length === 0)
+        return '{}';
+    return ('{\n' +
+        entries.map(([k, v]) => `${inner}${IDENT.test(k) ? k : JSON.stringify(k)}: ${toTsLiteral(v, indent + 1)}`).join(',\n') +
+        ',\n' +
+        pad +
+        '}');
+}
+/**
+ * Writes the project config. With splitTexts (default) texts/category_texts go to
+ * cookiecrumbs/texts/<lang>.json and the config file keeps empty placeholders
+ * (the schema still requires the keys; the loader merges the folder back in).
+ */
+export function writeLocalConfig(root, config, opts = {}) {
+    const format = opts.format ?? 'ts';
+    const split = opts.splitTexts ?? true;
+    const written = [];
+    const body = { ...config };
+    if (split) {
+        written.push(...writeTextsDir(root, config));
+        body.texts = {};
+        body.category_texts = {};
+    }
+    if (format === 'json') {
+        const file = join(root, CONFIG_JSON);
+        writeFileSync(file, JSON.stringify(body, null, 2) + '\n');
+        written.unshift(file);
+        if (existsSync(join(root, CONFIG_TS)))
+            rmSync(join(root, CONFIG_TS));
+        return written;
+    }
+    const ordered = orderConfig(body);
+    const lines = [
+        "import { defineConfig } from '@cookiecrumbs/config';",
+        '',
+        '// CookieCrumbs banner configuration. Edit, then `cookiecrumbs push`.',
+        split ? '// Texts per language live in cookiecrumbs/texts/<lang>.json and are merged on push.' : '// Texts are inline; `cookiecrumbs pull` rewrites this file.',
+        '',
+        `export default defineConfig(${toTsLiteral(ordered)});`,
+        '',
+    ];
+    const file = join(root, CONFIG_TS);
+    writeFileSync(file, lines.join('\n'));
+    written.unshift(file);
+    if (existsSync(join(root, CONFIG_JSON)))
+        rmSync(join(root, CONFIG_JSON));
+    return written;
+}
+const KEY_ORDER = ['schema_version', 'layout', 'theme', 'default_lang', 'languages', 'texts', 'category_texts', 'categories', 'block', 'regions', 'consent_mode', 'behaviour'];
+function orderConfig(c) {
+    const out = {};
+    for (const k of KEY_ORDER)
+        if (k in c)
+            out[k] = c[k];
+    for (const k of Object.keys(c))
+        if (!(k in out))
+            out[k] = c[k];
+    return out;
+}
+export function writeRemoteConflict(root, config) {
+    const file = join(root, CONFIG_REMOTE);
+    writeFileSync(file, JSON.stringify(config, null, 2) + '\n');
+    return file;
+}
+export function clearRemoteConflict(root) {
+    const file = join(root, CONFIG_REMOTE);
+    if (existsSync(file))
+        rmSync(file);
+}

package/dist/cli/src/util.js

@@ -0,0 +1,122 @@
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const DEFAULT_API = 'https://api.cookiecrumbs.eu';
+export const DEFAULT_APP = 'https://app.cookiecrumbs.eu';
+/** Version from this package's package.json (works from src/ via tsx and from dist/). */
+export function cliVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+                if (pkg.name === 'cookiecrumbs' && pkg.version)
+                    return pkg.version;
+            }
+            catch {
+                /* keep walking */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    try {
+        return createRequire(import.meta.url)('cookiecrumbs/package.json').version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Poll intervals can be shortened in tests through COOKIECRUMBS_POLL_MS. */
+export function pollMs(defaultMs) {
+    const v = Number(process.env.COOKIECRUMBS_POLL_MS);
+    return Number.isFinite(v) && v > 0 ? v : defaultMs;
+}
+/** Normalise an API base: strip trailing slashes and a trailing /v1 (paths add it). */
+export function normaliseApi(base) {
+    let b = base.trim().replace(/\/+$/, '');
+    if (b.endsWith('/v1'))
+        b = b.slice(0, -3);
+    return b;
+}
+/** The base the banner runtime talks to (consent/config/declaration functions). */
+export function runtimeApiBase(api) {
+    const b = normaliseApi(api);
+    return b.endsWith('/api') ? b.slice(0, -4) : b;
+}
+export function appUrl() {
+    return (process.env.COOKIECRUMBS_APP ?? DEFAULT_APP).replace(/\/+$/, '');
+}
+/** Open a URL in the user's browser; never throws (the URL is always printed too). */
+export function openBrowser(url) {
+    try {
+        const platform = process.platform;
+        const child = platform === 'win32'
+            ? spawn('cmd', ['/c', 'start', '""', url.replace(/&/g, '^&')], { detached: true, stdio: 'ignore', windowsHide: true })
+            : platform === 'darwin'
+                ? spawn('open', [url], { detached: true, stdio: 'ignore' })
+                : spawn('xdg-open', [url], { detached: true, stdio: 'ignore' });
+        child.on('error', () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `2026-08-01` or any ISO string → ISO timestamp (dates are taken as 00:00 UTC). */
+export function toIso(input, fallback) {
+    if (!input)
+        return fallback().toISOString();
+    const s = input.trim();
+    const d = /^\d{4}-\d{2}-\d{2}$/.test(s) ? new Date(`${s}T00:00:00.000Z`) : new Date(s);
+    if (Number.isNaN(d.getTime()))
+        throw new Error(`Not a date: ${input}`);
+    return d.toISOString();
+}
+export const firstOfMonth = () => {
+    const n = new Date();
+    return new Date(Date.UTC(n.getUTCFullYear(), n.getUTCMonth(), 1));
+};
+export function formatDate(iso) {
+    if (!iso)
+        return '—';
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return String(iso);
+    return d.toISOString().replace('T', ' ').slice(0, 16) + 'Z';
+}
+/** Small fixed-width table for human output. */
+export function table(rows, header) {
+    const all = header ? [header, ...rows] : rows;
+    const widths = [];
+    for (const r of all)
+        r.forEach((c, i) => (widths[i] = Math.max(widths[i] ?? 0, c.length)));
+    const line = (r) => r.map((c, i) => c.padEnd(widths[i])).join('  ').trimEnd();
+    const out = all.map(line);
+    if (header)
+        out.splice(1, 0, widths.map((w) => '-'.repeat(w)).join('  '));
+    return out.join('\n');
+}
+export function parseCsvList(v) {
+    if (!v)
+        return undefined;
+    return v
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export function parseIntOpt(name) {
+    return (v) => {
+        const n = Number.parseInt(v, 10);
+        if (!Number.isFinite(n) || n < 0)
+            throw new Error(`${name} must be a non-negative integer`);
+        return n;
+    };
+}