@cookiecrumbs-eu/mcp 0.7.0

package/dist/cli/src/commands/install.js

@@ -0,0 +1,77 @@
+import { CliError } from "../errors.js";
+import { human, bold, dim, green, red, spinner } from "../output.js";
+import { formatDate, pollMs, parseIntOpt, sleep, table } from "../util.js";
+import { api, finish, siteIdOf } from "./_shared.js";
+function describe(c) {
+    const r = (c.result ?? {});
+    const lines = [
+        `${bold('Checked')}  ${formatDate(c.checked_at)}  ${c.ok ? green('OK') : red('not OK')}`,
+        `${bold('Page')}     ${c.url}`,
+    ];
+    for (const [k, v] of Object.entries(r)) {
+        if (v === null || v === undefined)
+            continue;
+        lines.push(`${bold(k.padEnd(8))} ${typeof v === 'object' ? JSON.stringify(v) : String(v)}`);
+    }
+    return lines.join('\n');
+}
+export function register(program) {
+    const install = program.command('install').description('Is cc.js on the site? Queue an install check and read the results');
+    install
+        .command('status', { isDefault: true })
+        .description('The most recent install checks')
+        .option('--site <id>', 'site id (default: the linked site)')
+        .option('--limit <n>', 'rows (1..100)', parseIntOpt('--limit'), 5)
+        .action(async (opts) => {
+        const items = await api().installChecks(siteIdOf(opts.site), opts.limit);
+        finish({ checks: items, ok: items[0]?.ok ?? null }, () => {
+            if (!items.length)
+                return human.print(dim('No install check has run yet. Start one with `cookiecrumbs install check --wait`.'));
+            human.print(table(items.map((c) => [c.ok ? green('OK') : red('fail'), formatDate(c.checked_at), c.kind, c.url]), ['result', 'checked', 'kind', 'page']));
+            human.message(describe(items[0]));
+        });
+    });
+    install
+        .command('check')
+        .description('Queue an install check of the site (the worker fetches the page and looks for cc.js)')
+        .option('--site <id>', 'site id (default: the linked site)')
+        .option('--url <url>', 'page to check (default: the home page)')
+        .option('--wait', 'wait for the result and exit 1 if the install is broken')
+        .option('--timeout <seconds>', 'give up waiting after this long', parseIntOpt('--timeout'), 120)
+        .action(async (opts) => {
+        const a = api();
+        const site = siteIdOf(opts.site);
+        const queued = await a.requestInstallCheck(site, opts.url);
+        if (!opts.wait) {
+            finish({ ...queued, waited: false }, () => {
+                human.success(`Queued an install check of ${queued.url}`);
+                human.outro(`Read the result with ${dim('cookiecrumbs install status')} in a moment, or run with --wait.`);
+            });
+            return;
+        }
+        const s = spinner(`Checking ${queued.url}`);
+        // requested_at and checked_at are both server clocks, so a plain comparison tells this run's
+        // result from the one before it.
+        const since = Date.parse(queued.requested_at) || Date.now();
+        const deadline = Date.now() + opts.timeout * 1000;
+        let found = null;
+        while (Date.now() < deadline) {
+            await sleep(pollMs(3000));
+            const items = await a.installChecks(site, 5);
+            found = items.find((c) => c.kind === 'install' && Date.parse(c.checked_at) >= since) ?? null;
+            if (found)
+                break;
+        }
+        if (!found) {
+            s.fail('No result within the timeout');
+            throw new CliError('timeout', `No install check result within ${opts.timeout}s. Is a worker running? The check stays queued; read it later with \`cookiecrumbs install status\`.`, 1, { extra: { ...queued, waited: true } });
+        }
+        s.stop(found.ok ? green('Install OK') : red('Install broken'));
+        const json = { ...queued, waited: true, check: found, ok: found.ok };
+        if (!found.ok) {
+            human.message(describe(found));
+            throw new CliError('install_broken', `cc.js was not found working on ${found.url}.`, 1, { extra: json });
+        }
+        finish(json, () => human.message(describe(found)));
+    });
+}

package/dist/cli/src/commands/issues.js

@@ -0,0 +1,61 @@
+import { usage } from "../errors.js";
+import { human, bold, dim, red, yellow } from "../output.js";
+import { formatDate, table } from "../util.js";
+import { api, finish, siteIdOf } from "./_shared.js";
+const STATUSES = ['open', 'resolved', 'suppressed', 'all'];
+const colourSeverity = (s) => (s === 'critical' || s === 'high' ? red(s) : s === 'medium' ? yellow(s) : dim(s));
+function describe(i) {
+    const rule = (i.rule ?? {});
+    return [
+        `${bold('Issue')}     ${i.id}`,
+        `${bold('Code')}      ${i.code}  ${colourSeverity(String(i.severity))}`,
+        `${bold('Status')}    ${i.status}${i.suppress_reason ? `  ${dim(String(i.suppress_reason))}` : ''}`,
+        rule.title ? `${bold('Rule')}      ${rule.title}` : '',
+        rule.summary ? `           ${dim(rule.summary)}` : '',
+        `${bold('Seen')}      ${formatDate(i.first_seen)} → ${formatDate(i.last_seen)}`,
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+export function register(program) {
+    const issues = program.command('issues').description('Compliance issues of a site, and their suppression');
+    issues
+        .command('list', { isDefault: true })
+        .description('List issues (open by default)')
+        .option('--site <id>', 'site id (default: the linked site)')
+        .option('--status <status>', `${STATUSES.join(', ')} (default: open)`)
+        .action(async (opts) => {
+        const status = (opts.status ?? 'open').toLowerCase();
+        if (!STATUSES.includes(status))
+            throw usage(`--status must be one of ${STATUSES.join(', ')}`);
+        const items = await api().issuesOf(siteIdOf(opts.site), status);
+        finish({ issues: items, status }, () => {
+            if (!items.length)
+                return human.print(dim(`No ${status === 'all' ? '' : status + ' '}issues. There is no score; each issue stands on its own rule.`));
+            human.print(table(items.map((i) => [i.id, i.code, colourSeverity(String(i.severity)), String(i.status), formatDate(i.last_seen), String(i.evidence?.key ?? '').slice(0, 40)]), ['id', 'code', 'severity', 'status', 'last seen', 'evidence']));
+        });
+    });
+    issues
+        .command('suppress <id>')
+        .description('Suppress an issue with a reason (the reason is the record)')
+        .requiredOption('--reason <text>', 'why this issue does not apply')
+        .action(async (id, opts) => {
+        if (!opts.reason.trim())
+            throw usage('--reason must not be empty');
+        const issue = await api().suppressIssue(id, opts.reason.trim());
+        finish({ issue }, () => {
+            human.success(`Suppressed ${id}`);
+            human.message(describe(issue));
+        });
+    });
+    issues
+        .command('unsuppress <id>')
+        .description('Reopen a suppressed issue')
+        .action(async (id) => {
+        const issue = await api().unsuppressIssue(id);
+        finish({ issue }, () => {
+            human.success(`Reopened ${id}`);
+            human.message(describe(issue));
+        });
+    });
+}

package/dist/cli/src/commands/link.js

@@ -0,0 +1,41 @@
+import { resolve } from 'node:path';
+import { askSelect, ctx, human, bold } from "../output.js";
+import { findProjectRoot, readState, writeState } from "../project.js";
+import { api, envOf, finish } from "./_shared.js";
+export function register(program) {
+    program
+        .command('link')
+        .description('Point this folder at a site/environment without rewriting the config')
+        .option('--site <id>', 'site id')
+        .option('--env <env>', 'preview or production')
+        .action(async (opts) => {
+        human.intro('link');
+        const root = findProjectRoot(ctx().cwd) || resolve(ctx().cwd);
+        const prev = readState(root);
+        const a = api();
+        const me = await a.me();
+        let siteId = opts.site;
+        if (!siteId) {
+            const sites = await a.sites();
+            siteId = await askSelect('Which site?', '--site <id>', sites.map((s) => ({ value: s.id, label: s.name, hint: s.primary_domain })));
+        }
+        const site = await a.site(siteId);
+        const env = envOf(opts.env, prev?.env ?? 'preview');
+        const sameSite = prev?.site_id === site.id && prev?.env === env;
+        writeState(root, {
+            site_id: site.id,
+            env,
+            last_pulled_hash: sameSite ? prev.last_pulled_hash : null,
+            last_pulled_updated_at: sameSite ? prev.last_pulled_updated_at : null,
+            site_name: site.name,
+            org_slug: me.org.slug,
+            public_keys: Object.fromEntries((site.environments ?? []).map((e) => [e.name, e.public_key])),
+        });
+        finish({ site: { id: site.id, name: site.name }, env, root, reset_sync: !sameSite }, () => {
+            human.success(`Linked ${bold(site.name)} (${site.id}) · ${env}`);
+            if (!sameSite)
+                human.info('Sync state reset: run `cookiecrumbs pull` (or `push`) next.');
+            human.outro('Done');
+        });
+    });
+}

package/dist/cli/src/commands/logs.js

@@ -0,0 +1,98 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { CliError, usage } from "../errors.js";
+import { noteWorker, waitForExport } from "../jobs.js";
+import { ctx, human, bold, dim, green, yellow } from "../output.js";
+import { findProjectRoot, requireState } from "../project.js";
+import { firstOfMonth, parseIntOpt, toIso } from "../util.js";
+import { api, envOf, finish } from "./_shared.js";
+/** Download a completed export job to `file` and verify the X-Content-SHA256 header against the bytes. */
+export async function downloadExport(a, job, file) {
+    const d = await a.exportDownload(job.id);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, d.bytes);
+    const sha256 = createHash('sha256').update(d.bytes).digest('hex');
+    const header = d.headers['x-content-sha256'] ?? job.sha256 ?? null;
+    return {
+        job,
+        file,
+        bytes: d.bytes.length,
+        sha256,
+        sha256_header: header,
+        sha256_verified: header ? header.toLowerCase() === sha256 : null,
+        signature: d.headers['x-signature-ed25519'] ?? job.signature ?? null,
+        kid: d.headers['x-signing-kid'] ?? null,
+    };
+}
+export function describeDownload(r) {
+    return [
+        `${bold('File')}       ${r.file} ${dim(`(${r.bytes} bytes)`)}`,
+        `${bold('sha256')}     ${r.sha256} ${r.sha256_verified === true ? green('matches X-Content-SHA256') : r.sha256_verified === false ? yellow('DOES NOT match X-Content-SHA256') : dim('(no header to compare)')}`,
+        `${bold('Signature')}  ${r.signature ? `${r.signature.slice(0, 24)}… ${dim(`Ed25519, kid ${r.kid ?? '?'}`)}` : dim('none')}`,
+    ].join('\n');
+}
+/** Create (or re-attach to) an export job and wait for it. */
+export async function runExportJob(a, siteId, body, opts) {
+    let job;
+    if (opts.jobId) {
+        job = await a.exportJob(opts.jobId);
+        human.info(`Attached to export job ${job.id} (${job.status})`);
+    }
+    else {
+        try {
+            job = await a.createExport(siteId, body);
+        }
+        catch (e) {
+            if (e instanceof CliError && /export_in_progress/i.test(e.code + e.detail)) {
+                noteWorker();
+                throw new CliError('export_in_progress', `${e.detail} Another export job for this site is still queued or running; wait for it (or re-attach with --job <id>).`, 1, { status: e.status, extra: e.extra });
+            }
+            throw e;
+        }
+        human.step(`Export job ${bold(job.id)} ${job.status} (${body.kind})`);
+    }
+    if (job.status === 'completed')
+        return job;
+    return waitForExport(a, job.id, { timeoutMs: opts.timeoutMs, label: opts.label });
+}
+export function register(program) {
+    const logs = program.command('logs').description('Consent log exports');
+    logs
+        .command('export')
+        .description('Export consent records (signed JSONL or CSV) through an export job')
+        .option('--from <date>', 'start (YYYY-MM-DD or ISO; default: first day of this month)')
+        .option('--to <date>', 'end (default: now)')
+        .option('--env <env>', 'preview or production (default: the linked environment)')
+        .option('--format <fmt>', 'jsonl or csv', 'jsonl')
+        .option('--out <file>', 'output file (default: cookiecrumbs-consents-<env>-<from>-<to>.<ext>)')
+        .option('--job <id>', 're-attach to an existing export job (extension)')
+        .option('--timeout <seconds>', 'give up waiting after this many seconds', parseIntOpt('--timeout'), 600)
+        .action(async (opts) => {
+        human.intro('logs export');
+        const root = findProjectRoot(ctx().cwd);
+        const state = requireState(root);
+        const env = envOf(opts.env, state.env);
+        const format = opts.format.toLowerCase();
+        if (format !== 'jsonl' && format !== 'csv')
+            throw usage('--format must be jsonl or csv');
+        const kind = format === 'csv' ? 'consent_csv' : 'consent_jsonl';
+        let from;
+        let to;
+        try {
+            from = toIso(opts.from, firstOfMonth);
+            to = toIso(opts.to, () => new Date());
+        }
+        catch (e) {
+            throw usage(e.message);
+        }
+        const a = api();
+        const job = await runExportJob(a, state.site_id, { kind, from, to, env }, { jobId: opts.job, timeoutMs: opts.timeout * 1000, label: 'Consent export' });
+        const file = resolve(ctx().cwd, opts.out ?? job.filename ?? `cookiecrumbs-consents-${env}-${from.slice(0, 10)}-${to.slice(0, 10)}.${format}`);
+        const r = await downloadExport(a, job, file);
+        finish({ env, from, to, format, ...r, job: { ...r.job } }, () => {
+            human.message(describeDownload(r));
+            human.outro(`Verify later: openssl dgst -sha256 ${file}`);
+        });
+    });
+}

package/dist/cli/src/commands/open.js

@@ -0,0 +1,45 @@
+import { usage } from "../errors.js";
+import { ctx, human } from "../output.js";
+import { findProjectRoot, requireState, writeState } from "../project.js";
+import { appUrl, openBrowser } from "../util.js";
+import { api, finish } from "./_shared.js";
+const PAGES = {
+    overview: '',
+    banner: 'banner',
+    versions: 'banner/versions',
+    services: 'services',
+    inbox: 'services/inbox',
+    declaration: 'declaration',
+    scans: 'scans',
+    logs: 'logs',
+    exports: 'logs/exports',
+    issues: '',
+    settings: 'settings',
+    developers: '__workspace__/developers',
+};
+export function register(program) {
+    program
+        .command('open [page]')
+        .description(`Open the dashboard page for the linked site (${Object.keys(PAGES).join(', ')})`)
+        .option('--no-open', 'print the URL only')
+        .action(async (page, opts) => {
+        const root = findProjectRoot(ctx().cwd);
+        const state = requireState(root);
+        const key = (page ?? 'overview').toLowerCase();
+        if (!(key in PAGES))
+            throw usage(`Unknown page "${page}". One of: ${Object.keys(PAGES).join(', ')}`);
+        let slug = state.org_slug;
+        if (!slug) {
+            slug = (await api().me()).org.slug;
+            writeState(root, { ...state, org_slug: slug });
+        }
+        const path = PAGES[key];
+        const url = path.startsWith('__workspace__/') ? `${appUrl()}/w/${slug}/${path.slice('__workspace__/'.length)}` : `${appUrl()}/w/${slug}/s/${state.site_id}${path ? '/' + path : ''}`;
+        const opened = opts.open && !ctx().json ? openBrowser(url) : false;
+        finish({ url, page: key, opened }, () => {
+            human.print(url);
+            if (!opened)
+                human.print('(copy the URL into your browser)');
+        });
+    });
+}

package/dist/cli/src/commands/pull.js

@@ -0,0 +1,89 @@
+import { relative } from 'node:path';
+import { diffConfigs, formatDiff, summariseDiff } from "../diff.js";
+import { CliError } from "../errors.js";
+import { configHash, mergeDecision } from "../merge.js";
+import { ctx, human, bold, dim } from "../output.js";
+import { CONFIG_REMOTE, clearRemoteConflict, configFile, findProjectRoot, loadLocalConfig, requireState, writeLocalConfig, writePulled, writeRemoteConflict, writeState } from "../project.js";
+import { api, envOf, finish } from "./_shared.js";
+export function register(program) {
+    program
+        .command('pull')
+        .description('Fetch the remote draft (three-way: overwrite, keep or conflict)')
+        .option('--env <env>', 'preview or production (default: the linked environment)')
+        .option('--force', 'overwrite local changes with the remote draft')
+        .action(async (opts) => {
+        human.intro('pull');
+        const root = findProjectRoot(ctx().cwd);
+        const state = requireState(root);
+        const env = envOf(opts.env, state.env);
+        const a = api();
+        const remote = await a.getDraft(state.site_id, env);
+        const existing = configFile(root);
+        let local = null;
+        if (existing && !opts.force) {
+            local = (await loadLocalConfig(root)).config;
+        }
+        else if (existing) {
+            try {
+                local = (await loadLocalConfig(root)).config;
+            }
+            catch {
+                local = null; // --force: a broken local file is simply replaced
+            }
+        }
+        const base = env === state.env ? state.last_pulled_hash : null;
+        const remoteHash = configHash(remote.config);
+        let decision = local ? mergeDecision(base, local, remote.config).decision : 'overwrite';
+        const localHash = local ? configHash(local) : null;
+        const diff = local ? diffConfigs(local, remote.config) : diffConfigs({}, remote.config);
+        if (decision === 'conflict' && opts.force)
+            decision = 'overwrite';
+        const write = () => {
+            const files = writeLocalConfig(root, remote.config, { format: existing?.format ?? 'ts' });
+            writePulled(root, remote.config);
+            writeState(root, { ...state, env, last_pulled_hash: remoteHash, last_pulled_updated_at: remote.updated_at ?? null });
+            clearRemoteConflict(root);
+            return files.map((f) => relative(root, f));
+        };
+        if (decision === 'overwrite') {
+            const files = write();
+            finish({ env, decision, changed: diff.length > 0, diff, remote_hash: remoteHash, local_hash: localHash, base_hash: base, updated_at: remote.updated_at, files }, () => {
+                if (diff.length) {
+                    human.print(formatDiff(diff));
+                    human.success(`Pulled the ${env} draft (${summariseDiff(diff)}) → ${files.join(', ')}`);
+                }
+                else
+                    human.success(`Pulled the ${env} draft — files rewritten, no content changes.`);
+                human.outro(dim(`Draft updated ${remote.updated_at ?? '—'}`));
+            });
+            return;
+        }
+        if (decision === 'keep') {
+            const remoteUnchanged = remoteHash === base || remoteHash === localHash;
+            // Keep the If-Match timestamp fresh when nothing new is upstream.
+            if (remoteUnchanged && remote.updated_at && remote.updated_at !== state.last_pulled_updated_at && env === state.env) {
+                writeState(root, { ...state, last_pulled_updated_at: remote.updated_at });
+            }
+            const localChanged = localHash !== base && localHash !== remoteHash;
+            finish({ env, decision, changed: false, local_changed: localChanged, diff, remote_hash: remoteHash, local_hash: localHash, base_hash: base, updated_at: remote.updated_at }, () => {
+                if (!localChanged)
+                    human.success('No changes — local config matches the remote draft.');
+                else
+                    human.success(`Remote draft unchanged; kept your local changes (${summariseDiff(diff)} vs remote). Run ${bold('cookiecrumbs push')} when ready.`);
+                human.outro('Done');
+            });
+            return;
+        }
+        // conflict
+        const file = writeRemoteConflict(root, remote.config);
+        if (diff.length)
+            human.print(formatDiff(diff));
+        if (ctx().json) {
+            throw new CliError('conflict', `Both the local config and the ${env} draft changed since the last pull.`, 2, {
+                extra: { decision, env, diff, remote_file: CONFIG_REMOTE, remote_hash: remoteHash, local_hash: localHash, base_hash: base, updated_at: remote.updated_at },
+            });
+        }
+        throw new CliError('conflict', `Both the local config and the ${env} draft changed since the last pull (${summariseDiff(diff)}).\n` +
+            `The remote draft was written to ${relative(root, file)}. Merge by hand, then \`cookiecrumbs push\`; or \`cookiecrumbs pull --force\` to take the remote version.`, 2);
+    });
+}

package/dist/cli/src/commands/push.js

@@ -0,0 +1,110 @@
+import { lintConfig } from "../configpkg.js";
+import { diffConfigs, formatDiff, summariseDiff } from "../diff.js";
+import { CliError } from "../errors.js";
+import { configHash } from "../merge.js";
+import { ctx, human, bold, dim, spinner } from "../output.js";
+import { findProjectRoot, loadLocalConfig, readPulled, requireState, writePulled, writeState } from "../project.js";
+import { api, envOf, finish, lintError, lintFromError, printLint } from "./_shared.js";
+/** Validate locally → PUT draft (If-Match) → POST versions. Shared by `push` and `init --publish`. */
+export async function pushProject(root, opts) {
+    const state = requireState(root);
+    const env = opts.env ?? state.env;
+    const a = api();
+    const local = await loadLocalConfig(root);
+    const lint = lintConfig(local.config);
+    printLint(lint, 'Local lint');
+    if (!lint.ok)
+        throw lintError(lint);
+    const base = readPulled(root);
+    let remote = null;
+    try {
+        remote = await a.getDraft(state.site_id, env);
+    }
+    catch (e) {
+        if (!(e instanceof CliError && e.status === 404))
+            throw e;
+    }
+    const diff = diffConfigs(base ?? remote?.config ?? {}, local.config);
+    if (diff.length)
+        human.print(formatDiff(diff));
+    human.info(`${summariseDiff(diff)} vs ${base ? 'the last pulled config' : 'the remote draft'}`);
+    if (opts.dryRun)
+        return { env, version: null, diff, lint, dry_run: true, draft_updated_at: remote?.updated_at ?? null };
+    const sameEnv = env === state.env;
+    const ifMatch = sameEnv ? state.last_pulled_updated_at : null;
+    const s = spinner(`Saving draft to ${env}`);
+    let saved;
+    try {
+        saved = await a.putDraft(state.site_id, env, local.config, ifMatch);
+    }
+    catch (e) {
+        if (e instanceof CliError && (e.status === 409 || e.status === 412)) {
+            s.fail('The remote draft changed since your last pull');
+            throw new CliError('draft_conflict', `The ${env} draft changed since your last pull. Run \`cookiecrumbs pull\` first (it merges or writes cookiecrumbs.config.remote.json).`, 2, { status: e.status, extra: e.extra });
+        }
+        s.fail('Saving the draft failed');
+        throw e;
+    }
+    s.stop(`Draft saved to ${env}`);
+    printLint(saved.lint, 'Server lint');
+    if (saved.lint && saved.lint.ok === false)
+        throw lintError(saved.lint);
+    const publishSpinner = spinner(`Publishing to ${env}`);
+    let version;
+    try {
+        version = await a.publish(state.site_id, { env, note: opts.note, material: Boolean(opts.material) });
+    }
+    catch (e) {
+        publishSpinner.fail('Publish failed');
+        if (e instanceof CliError) {
+            const l = lintFromError(e);
+            if (l)
+                printLint(l, 'Lint (server)');
+            if (e.status === 402)
+                throw new CliError(e.code, `${e.detail} — upgrade the plan or change the config.`, 1, { status: 402, extra: e.extra });
+        }
+        throw e;
+    }
+    publishSpinner.stop(`Published version ${bold(String(version.number))} to ${env}`);
+    // Refresh the sync state: the server draft now equals the local config.
+    let updatedAt = saved.updated_at ?? null;
+    try {
+        updatedAt = (await a.getDraft(state.site_id, env)).updated_at ?? updatedAt;
+    }
+    catch {
+        /* keep the PUT's timestamp */
+    }
+    if (sameEnv) {
+        writeState(root, { ...state, env, last_pulled_hash: configHash(local.config), last_pulled_updated_at: updatedAt });
+        writePulled(root, local.config);
+    }
+    return { env, version, diff, lint, dry_run: false, draft_updated_at: updatedAt };
+}
+export function register(program) {
+    program
+        .command('push')
+        .description('Validate, save the draft and publish a new version')
+        .option('--env <env>', 'preview or production (default: the linked environment)')
+        .option('--note <text>', 'version note')
+        .option('--material', 'mark the change as material (re-asks consent)')
+        .option('--dry-run', 'lint and show the diff without writing anything')
+        .action(async (opts) => {
+        human.intro('push');
+        const root = findProjectRoot(ctx().cwd);
+        const state = requireState(root);
+        const env = envOf(opts.env, state.env);
+        const r = await pushProject(root, { env, note: opts.note, material: opts.material, dryRun: opts.dryRun });
+        finish({
+            env: r.env,
+            dry_run: r.dry_run,
+            version: r.version ? { id: r.version.id, number: r.version.number, environment: r.version.environment, note: r.version.note, created_at: r.version.created_at ?? r.version.published_at ?? null } : null,
+            diff: r.diff,
+            lint: r.lint,
+        }, () => {
+            if (r.dry_run)
+                human.outro(dim('Dry run — nothing was sent.'));
+            else
+                human.outro(`Version ${bold(String(r.version.number))} is live on ${r.env}.`);
+        });
+    });
+}

package/dist/cli/src/commands/scan.js

@@ -0,0 +1,94 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { CliError, usage } from "../errors.js";
+import { waitForScan } from "../jobs.js";
+import { ctx, human, bold, dim, red, green, spinner } from "../output.js";
+import { findProjectRoot, requireState } from "../project.js";
+import { parseCsvList, parseIntOpt } from "../util.js";
+import { api, envOf, finish } from "./_shared.js";
+const num = (v) => (typeof v === 'number' ? v : Number(v ?? 0) || 0);
+export function register(program) {
+    program
+        .command('scan')
+        .description('Run a hosted scan of the linked site (use --wait in CI)')
+        .option('--env <env>', 'environment to scan (default: the linked environment)')
+        .option('--states <list>', 'consent states, comma separated (no_interaction,reject_all,accept_all)')
+        .option('--pages <n>', 'page cap', parseIntOpt('--pages'))
+        .option('--wait', 'wait for the scan to finish and print the summary')
+        .option('--timeout <minutes>', 'give up waiting after this many minutes', parseIntOpt('--timeout'), 30)
+        .option('--fail-on-unknown', 'exit 1 when the scan found unclassified trackers')
+        .option('--fail-on-preconsent', 'exit 1 when trackers loaded before consent')
+        .option('--sarif <file>', 'write the findings as SARIF 2.1.0 to this file (implies --wait)')
+        .option('--scan-id <id>', 're-attach to an existing scan instead of starting one (extension)')
+        .option('--local', 'local scan (not yet available)')
+        .action(async (opts) => {
+        if (opts.local)
+            throw usage('Local scanning is not yet available — run the hosted scan (`cookiecrumbs scan --wait`).', 'not_available');
+        human.intro('scan');
+        const root = findProjectRoot(ctx().cwd);
+        const state = requireState(root);
+        const a = api();
+        const env = envOf(opts.env, state.env);
+        const wait = Boolean(opts.wait || opts.sarif || opts.failOnUnknown || opts.failOnPreconsent);
+        let scan;
+        if (opts.scanId) {
+            scan = await a.scan(opts.scanId);
+            human.info(`Attached to scan ${scan.id} (${scan.status})`);
+        }
+        else {
+            const s = spinner(`Requesting a scan of ${env}`);
+            scan = await a.createScan(state.site_id, { env, states: parseCsvList(opts.states), page_cap: opts.pages });
+            s.stop(`Scan ${bold(scan.id)} ${scan.status}`);
+        }
+        if (!wait) {
+            finish({ scan_id: scan.id, status: scan.status, env: scan.environment ?? env, waited: false }, () => {
+                human.print(scan.id);
+                human.outro(`Follow it with ${dim(`cookiecrumbs scan --scan-id ${scan.id} --wait`)} or in the dashboard.`);
+            });
+            return;
+        }
+        const done = await waitForScan(a, scan.id, { timeoutMs: opts.timeout * 60 * 1000 });
+        const summary = (done.summary ?? {});
+        const unclassified = num(summary.unclassified);
+        const preconsent = num(summary.preconsent_violations);
+        let sarifFile = null;
+        if (opts.sarif && done.status === 'completed') {
+            const text = await a.findings(done.id, 'sarif');
+            sarifFile = resolve(ctx().cwd, opts.sarif);
+            mkdirSync(dirname(sarifFile), { recursive: true });
+            writeFileSync(sarifFile, text.endsWith('\n') ? text : text + '\n');
+            human.step(`Wrote SARIF to ${sarifFile}`);
+        }
+        const failedOn = [];
+        if (done.status !== 'completed')
+            failedOn.push(done.status);
+        if (opts.failOnUnknown && unclassified > 0)
+            failedOn.push('unknown');
+        if (opts.failOnPreconsent && preconsent > 0)
+            failedOn.push('preconsent');
+        const json = { scan_id: done.id, status: done.status, env: done.environment ?? env, waited: true, pages_crawled: done.pages_crawled ?? null, summary, sarif_file: sarifFile, failed_on: failedOn, error: done.error ?? null };
+        const lines = [
+            `${bold('Status')}      ${done.status === 'completed' ? green(done.status) : red(done.status)}${done.error ? ` — ${done.error}` : ''}`,
+            `${bold('Pages')}       ${done.pages_crawled ?? summary.pages ?? '—'}`,
+            `${bold('Findings')}    ${summary.findings ?? '—'}`,
+            `${bold('Pre-consent')} ${preconsent}${preconsent && opts.failOnPreconsent ? red('  ← fails --fail-on-preconsent') : ''}`,
+            `${bold('Unknown')}     ${unclassified}${unclassified && opts.failOnUnknown ? red('  ← fails --fail-on-unknown') : ''}`,
+            summary.new != null ? `${bold('New')}         ${summary.new}` : '',
+            summary.removed != null ? `${bold('Removed')}     ${summary.removed}` : '',
+            summary.blocked_by_bot_protection ? red('Bot protection blocked the crawler; results are partial.') : '',
+        ].filter(Boolean);
+        if (failedOn.length) {
+            human.message(lines.join('\n'));
+            const reason = failedOn.includes('unknown')
+                ? `${unclassified} unclassified tracker${unclassified === 1 ? '' : 's'}`
+                : failedOn.includes('preconsent')
+                    ? `${preconsent} tracker${preconsent === 1 ? '' : 's'} loaded before consent`
+                    : `scan ${done.status}`;
+            throw new CliError('scan_failed', `Scan ${done.id}: ${reason}.`, 1, { extra: json });
+        }
+        finish(json, () => {
+            human.message(lines.join('\n'));
+            human.outro(`Scan ${done.id} passed.`);
+        });
+    });
+}