@cookiecrumbs-eu/mcp 0.7.0

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

@@ -0,0 +1,97 @@
+import { usage } from "../errors.js";
+import { human, bold, dim, yellow } from "../output.js";
+import { formatDate, parseCsvList, parseIntOpt } from "../util.js";
+import { api, finish, parseOnOff, siteIdOf } from "./_shared.js";
+const CADENCES = ['monthly', 'weekly', 'daily'];
+const STATES = ['no_interaction', 'reject_all', 'accept_all'];
+function describe(s) {
+    return [
+        `${bold('Cadence')}     ${s.cadence}${s.paused ? '  ' + yellow('(paused)') : ''}`,
+        `${bold('Next run')}    ${s.paused ? dim('while paused, none') : formatDate(s.next_run_at)}`,
+        `${bold('Page cap')}    ${s.page_cap}`,
+        `${bold('States')}      ${(s.states ?? []).join(', ')}`,
+        `${bold('Start URLs')}  ${(s.start_urls ?? []).join(', ') || dim('the home page')}`,
+        `${bold('Only paths')}  ${(s.include_patterns ?? []).join(', ') || dim('everything')}`,
+        `${bold('Never paths')} ${(s.exclude_patterns ?? []).join(', ') || dim('—')}`,
+        `${bold('robots.txt')}  ${s.respect_robots ? 'obeyed' : yellow('ignored')}`,
+        `${bold('Last run')}    ${s.last_run_scan_id ?? dim('no scheduled scan has run yet')}`,
+    ].join('\n');
+}
+/** A list option: "a,b" sets, "" (or "none") clears. */
+const listOpt = (v) => (v === undefined ? undefined : v.trim() === '' || v.trim().toLowerCase() === 'none' ? [] : (parseCsvList(v) ?? []));
+export function register(program) {
+    const schedule = program.command('schedule').description('Scheduled scans of the linked site');
+    schedule
+        .command('show', { isDefault: true })
+        .description('The schedule: cadence, next run, page cap, states, crawl scope')
+        .option('--site <id>', 'site id (default: the linked site)')
+        .action(async (opts) => {
+        const s = await api().scanSchedule(siteIdOf(opts.site));
+        finish({ schedule: s }, () => human.message(describe(s)));
+    });
+    schedule
+        .command('set')
+        .description('Change the schedule (only the options you pass change; the plan may cap cadence and pages)')
+        .option('--site <id>', 'site id (default: the linked site)')
+        .option('--cadence <cadence>', CADENCES.join(', '))
+        .option('--pages <n>', 'page cap per scan', parseIntOpt('--pages'))
+        .option('--states <list>', `comma-separated: ${STATES.join(', ')}`)
+        .option('--start-urls <list>', 'comma-separated start addresses ("none" = the home page)')
+        .option('--include <list>', 'comma-separated path patterns to crawl, e.g. /blog/** ("none" = everything)')
+        .option('--exclude <list>', 'comma-separated path patterns to skip ("none" clears)')
+        .option('--robots <on|off>', 'obey robots.txt (off only on a verified domain)')
+        .option('--pause', 'pause scheduled scans')
+        .option('--resume', 'resume scheduled scans')
+        .action(async (opts) => {
+        const patch = {};
+        if (opts.cadence !== undefined) {
+            if (!CADENCES.includes(opts.cadence))
+                throw usage(`--cadence must be one of ${CADENCES.join(', ')}`);
+            patch.cadence = opts.cadence;
+        }
+        if (opts.pages !== undefined) {
+            if (opts.pages < 1)
+                throw usage('--pages must be at least 1');
+            patch.page_cap = opts.pages;
+        }
+        if (opts.states !== undefined) {
+            const states = parseCsvList(opts.states) ?? [];
+            const bad = states.filter((s) => !STATES.includes(s));
+            if (!states.length || bad.length)
+                throw usage(`--states must be a comma-separated list of ${STATES.join(', ')}`);
+            patch.states = [...new Set(states)];
+        }
+        const start = listOpt(opts.startUrls);
+        if (start !== undefined)
+            patch.start_urls = start;
+        const include = listOpt(opts.include);
+        if (include !== undefined)
+            patch.include_patterns = include;
+        const exclude = listOpt(opts.exclude);
+        if (exclude !== undefined)
+            patch.exclude_patterns = exclude;
+        const robots = parseOnOff(opts.robots, '--robots');
+        if (robots !== undefined)
+            patch.respect_robots = robots;
+        if (opts.pause && opts.resume)
+            throw usage('Pass --pause or --resume, not both.');
+        if (opts.pause)
+            patch.paused = true;
+        if (opts.resume)
+            patch.paused = false;
+        if (!Object.keys(patch).length)
+            throw usage('Nothing to change: pass --cadence, --pages, --states, --start-urls, --include, --exclude, --robots, --pause or --resume.');
+        const s = await api().updateScanSchedule(siteIdOf(opts.site), patch);
+        const clamped = [];
+        if (patch.cadence && s.cadence !== patch.cadence)
+            clamped.push(`cadence ${patch.cadence} → ${s.cadence} (plan limit)`);
+        if (patch.page_cap && s.page_cap !== patch.page_cap)
+            clamped.push(`page cap ${patch.page_cap} → ${s.page_cap} (plan limit)`);
+        finish({ schedule: s, patch, clamped }, () => {
+            human.success('Schedule saved');
+            for (const c of clamped)
+                human.warn(c);
+            human.message(describe(s));
+        });
+    });
+}

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

@@ -0,0 +1,143 @@
+import { CliError, usage } from "../errors.js";
+import { askConfirm, ctx, human, bold, dim, yellow } from "../output.js";
+import { parseCsvList, table } from "../util.js";
+import { api, finish, parseOnOff, siteIdOf } from "./_shared.js";
+const STATUSES = ['discovered', 'managed', 'ignored'];
+const BASES = ['consent', 'legitimate_interest', 'contract', 'legal_obligation'];
+/** Options → the partial service the API accepts; only what was passed ends up in the body. */
+function patchFrom(opts) {
+    const p = {};
+    if (opts.category !== undefined)
+        p.category_key = opts.category.trim();
+    if (opts.provider !== undefined)
+        p.provider_name = opts.provider;
+    if (opts.domain !== undefined)
+        p.provider_domain = opts.domain.trim().toLowerCase();
+    if (opts.hosts !== undefined)
+        p.host_patterns = parseCsvList(opts.hosts) ?? [];
+    if (opts.scripts !== undefined)
+        p.script_patterns = parseCsvList(opts.scripts) ?? [];
+    if (opts.cookies !== undefined)
+        p.cookie_patterns = parseCsvList(opts.cookies) ?? [];
+    if (opts.storage !== undefined)
+        p.storage_keys = parseCsvList(opts.storage) ?? [];
+    if (opts.iframes !== undefined)
+        p.iframe_patterns = parseCsvList(opts.iframes) ?? [];
+    if (opts.basis !== undefined) {
+        if (!BASES.includes(opts.basis))
+            throw usage(`--basis must be one of ${BASES.join(', ')}`);
+        p.legal_basis = opts.basis;
+    }
+    if (opts.justification !== undefined)
+        p.justification = opts.justification || null;
+    if (opts.privacyUrl !== undefined)
+        p.privacy_url = opts.privacyUrl || null;
+    const fp = parseOnOff(opts.firstParty, '--first-party');
+    if (fp !== undefined)
+        p.first_party = fp;
+    if (opts.status !== undefined) {
+        if (!STATUSES.includes(opts.status))
+            throw usage(`--status must be one of ${STATUSES.join(', ')}`);
+        p.status = opts.status;
+    }
+    if (opts.ignoreReason !== undefined)
+        p.ignore_reason = opts.ignoreReason || null;
+    if (opts.description !== undefined)
+        p.descriptions = { en: opts.description };
+    return p;
+}
+function addOptions(cmd) {
+    return cmd
+        .option('--provider <name>', 'provider name, e.g. "Google"')
+        .option('--domain <host>', 'provider domain, e.g. google.com')
+        .option('--hosts <list>', 'comma-separated host patterns the service loads from')
+        .option('--scripts <list>', 'comma-separated script URL patterns')
+        .option('--cookies <list>', 'comma-separated cookie name patterns')
+        .option('--storage <list>', 'comma-separated localStorage / sessionStorage keys')
+        .option('--iframes <list>', 'comma-separated iframe URL patterns')
+        .option('--basis <basis>', `legal basis: ${BASES.join(', ')}`)
+        .option('--justification <text>', 'why this basis applies (legitimate interest needs one)')
+        .option('--privacy-url <url>', "the provider's privacy policy")
+        .option('--first-party <on|off>', 'the service is first-party')
+        .option('--status <status>', `${STATUSES.join(', ')}`)
+        .option('--ignore-reason <text>', 'why an ignored service is ignored')
+        .option('--description <text>', 'what the visitor is told (English; other languages in the dashboard)');
+}
+function describe(s) {
+    return [
+        `${bold('Service')}   ${s.name} ${dim(s.id)}`,
+        `${bold('Category')}  ${s.category_key}  ${dim(String(s.status ?? ''))}`,
+        `${bold('Provider')}  ${s.provider_name ?? dim('—')} ${s.provider_domain ? dim(String(s.provider_domain)) : ''}`,
+        `${bold('Basis')}     ${s.legal_basis ?? dim('—')}${s.justification ? `  ${dim(String(s.justification))}` : ''}`,
+        `${bold('Matches')}   hosts ${(s.host_patterns ?? []).join(', ') || dim('—')}; scripts ${(s.script_patterns ?? []).join(', ') || dim('—')}; cookies ${(s.cookie_patterns ?? []).join(', ') || dim('—')}`,
+    ].join('\n');
+}
+export function register(program) {
+    const services = program.command('services').description('The trackers a site declares: list, add, update, remove');
+    services
+        .command('list', { isDefault: true })
+        .description('List the services of a site')
+        .option('--site <id>', 'site id (default: the linked site)')
+        .option('--status <status>', `only ${STATUSES.join(', ')}`)
+        .action(async (opts) => {
+        if (opts.status !== undefined && !STATUSES.includes(opts.status))
+            throw usage(`--status must be one of ${STATUSES.join(', ')}`);
+        const items = await api().services(siteIdOf(opts.site), opts.status);
+        finish({ services: items }, () => {
+            if (!items.length)
+                return human.print(dim('No services.'));
+            human.print(table(items.map((s) => [s.id, s.name, s.category_key, String(s.status ?? ''), String(s.legal_basis ?? ''), String(s.provider_domain ?? ''), (s.host_patterns ?? []).slice(0, 2).join(',')]), ['id', 'name', 'category', 'status', 'basis', 'provider', 'hosts']));
+        });
+    });
+    addOptions(services
+        .command('add <name>')
+        .description('Declare a service (status managed unless --status says otherwise)')
+        .option('--site <id>', 'site id (default: the linked site)')
+        .requiredOption('--category <key>', "one of the site's category keys, e.g. analytics")).action(async (name, opts) => {
+        const body = { ...patchFrom(opts), name: name.trim(), category_key: String(opts.category).trim() };
+        if (!body.name)
+            throw usage('The service needs a name.');
+        const service = await api().createService(siteIdOf(opts.site), body);
+        finish({ service }, () => {
+            human.success(`Added ${bold(service.name)} (${service.id})`);
+            human.message(describe(service));
+            human.outro(`It is part of the declaration and the block list from the next publish (${dim('cookiecrumbs push')}).`);
+        });
+    });
+    addOptions(services
+        .command('update <id>')
+        .description('Change a service: category, matching patterns, legal basis, status')
+        .option('--name <name>', 'new name')
+        .option('--category <key>', 'move it to another category')).action(async (id, opts) => {
+        const body = patchFrom(opts);
+        if (opts.name !== undefined) {
+            if (!opts.name.trim())
+                throw usage('--name must not be empty');
+            body.name = opts.name.trim();
+        }
+        if (!Object.keys(body).length)
+            throw usage('Nothing to change: pass at least one option.');
+        const service = await api().updateService(id, body);
+        finish({ service, patch: body }, () => {
+            human.success(`Updated ${bold(service.name)}`);
+            human.message(describe(service));
+        });
+    });
+    services
+        .command('remove <id>')
+        .alias('delete')
+        .description('Delete a service; its findings return to unclassified on the next scan')
+        .option('-y, --yes', 'do not ask for confirmation')
+        .action(async (id, opts) => {
+        if (!opts.yes && !ctx().json) {
+            const ok = await askConfirm(`Delete service ${id}? Its cookies leave the declaration.`, '--yes', false);
+            if (!ok)
+                throw new CliError('cancelled', 'Cancelled.', 2);
+        }
+        await api().deleteService(id);
+        finish({ deleted: id }, () => {
+            human.success(`Deleted service ${id}`);
+            human.print(yellow('Publish a new version so the declaration and the block list follow.'));
+        });
+    });
+}

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

@@ -0,0 +1,111 @@
+import { usage } from "../errors.js";
+import { human, bold, dim } from "../output.js";
+import { formatDate, parseCsvList, parseIntOpt, table } from "../util.js";
+import { api, finish, parseOnOff, siteIdOf } from "./_shared.js";
+const DOMAIN_RE = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+const RETENTION = [12, 24, 36, 48, 60, 72, 84, 96, 108, 120];
+function describe(s) {
+    const envs = (s.environments ?? []).map((e) => `${e.name} ${dim(String(e.public_key))}`).join('\n            ');
+    const settings = (s.settings ?? {});
+    return [
+        `${bold('Site')}      ${s.name} ${dim(s.id)}`,
+        `${bold('Domain')}    ${s.primary_domain}`,
+        `${bold('State')}     ${String(s.status ?? '—')}`,
+        `${bold('Retention')} ${s.retention_months != null ? `${s.retention_months} months` : '—'}`,
+        `${bold('Settings')}  ${Object.keys(settings).length ? Object.entries(settings).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join('  ') : dim('defaults')}`,
+        `${bold('Envs')}      ${envs || dim('—')}`,
+        `${bold('Added')}     ${formatDate(s.created_at)}`,
+    ].join('\n');
+}
+export function register(program) {
+    const sites = program.command('sites').description('Sites of the workspace: list, create, rename, retention and settings');
+    sites
+        .command('list', { isDefault: true })
+        .description('List the sites this token can see')
+        .action(async () => {
+        const items = await api().sites();
+        finish({ sites: items }, () => {
+            if (!items.length)
+                return human.print(dim('No sites.'));
+            human.print(table(items.map((s) => [s.id, s.name, s.primary_domain, String(s.status ?? ''), s.retention_months != null ? `${s.retention_months}m` : '—', (s.environments ?? []).map((e) => e.name).join(',')]), ['id', 'name', 'domain', 'state', 'retention', 'environments']));
+        });
+    });
+    sites
+        .command('show [id]')
+        .description('One site (default: the linked site)')
+        .action(async (id) => {
+        const site = await api().site(siteIdOf(id));
+        finish({ site }, () => human.message(describe(site)));
+    });
+    sites
+        .command('create')
+        .description('Create a site; it gets production and preview environments and a first draft')
+        .requiredOption('--name <name>', 'site name')
+        .requiredOption('--domain <domain>', 'primary domain, e.g. www.example.com')
+        .option('--languages <list>', 'comma-separated language tags (default: en)')
+        .action(async (opts) => {
+        const domain = opts.domain.trim().toLowerCase();
+        if (!DOMAIN_RE.test(domain))
+            throw usage(`--domain must be a hostname like www.example.com (got "${opts.domain}")`);
+        const site = await api().createSite({ name: opts.name.trim(), primary_domain: domain, languages: parseCsvList(opts.languages) });
+        finish({ site }, () => {
+            human.success(`Created ${bold(site.name)} (${site.id})`);
+            human.message(describe(site));
+            human.outro(`Link a folder to it with ${dim(`cookiecrumbs link --site ${site.id}`)}`);
+        });
+    });
+    sites
+        .command('update [id]')
+        .description('Rename a site, set how long consent records are kept, or change a setting')
+        .option('--name <name>', 'new name')
+        .option('--retention <months>', `months to keep consent records: ${RETENTION.join(', ')}`, parseIntOpt('--retention'))
+        .option('--public-versions-feed <on|off>', 'publish the version history feed')
+        .option('--consent-cookie-name <name>', 'name of the consent cookie ("none" resets to the default)')
+        .option('--reask-months <n>', 'months before visitors are asked again ("none" resets to the default)')
+        .action(async (id, opts) => {
+        const patch = {};
+        if (opts.name !== undefined) {
+            if (!opts.name.trim())
+                throw usage('--name must not be empty');
+            patch.name = opts.name.trim();
+        }
+        if (opts.retention !== undefined) {
+            if (!RETENTION.includes(opts.retention))
+                throw usage(`--retention must be one of ${RETENTION.join(', ')}`);
+            patch.retention_months = opts.retention;
+        }
+        const settings = {};
+        const feed = parseOnOff(opts.publicVersionsFeed, '--public-versions-feed');
+        if (feed !== undefined)
+            settings.public_versions_feed = feed;
+        if (opts.consentCookieName !== undefined) {
+            const v = opts.consentCookieName.trim();
+            if (v.toLowerCase() === 'none')
+                settings.consent_cookie_name = null;
+            else if (!/^[A-Za-z0-9_-]{1,64}$/.test(v))
+                throw usage('--consent-cookie-name must be 1..64 characters of letters, digits, _ or -');
+            else
+                settings.consent_cookie_name = v;
+        }
+        if (opts.reaskMonths !== undefined) {
+            const v = opts.reaskMonths.trim();
+            if (v.toLowerCase() === 'none')
+                settings.reask_months = null;
+            else {
+                const n = Number.parseInt(v, 10);
+                if (!Number.isInteger(n) || n < 1 || n > 13)
+                    throw usage('--reask-months must be an integer between 1 and 13, or none');
+                settings.reask_months = n;
+            }
+        }
+        if (Object.keys(settings).length)
+            patch.settings = settings;
+        if (!Object.keys(patch).length)
+            throw usage('Nothing to change: pass --name, --retention, --public-versions-feed, --consent-cookie-name or --reask-months.');
+        const site = await api().updateSite(siteIdOf(id), patch);
+        finish({ site, patch }, () => {
+            human.success(`Updated ${bold(site.name)}`);
+            human.message(describe(site));
+        });
+    });
+}

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

@@ -0,0 +1,90 @@
+import { relative } from 'node:path';
+import { CliError } from "../errors.js";
+import { detectFramework, FRAMEWORK_LABEL } from "../frameworks.js";
+import { configHash } from "../merge.js";
+import { ctx, human, bold, dim, green, yellow } from "../output.js";
+import { configFile, findProjectRoot, loadLocalConfig, requireState, TEXTS_DIR } from "../project.js";
+import { formatDate } from "../util.js";
+import { api, finish } from "./_shared.js";
+export function register(program) {
+    program
+        .command('status')
+        .description('Local vs remote state of the linked site')
+        .action(async () => {
+        const root = findProjectRoot(ctx().cwd);
+        const state = requireState(root);
+        const a = api();
+        const file = configFile(root);
+        const framework = detectFramework(root);
+        let localHash = null;
+        let localError = null;
+        let langs = [];
+        if (file) {
+            try {
+                const l = await loadLocalConfig(root);
+                localHash = configHash(l.config);
+                langs = l.config.languages;
+            }
+            catch (e) {
+                localError = e instanceof CliError ? e.detail : String(e);
+            }
+        }
+        const [site, draft, versions] = await Promise.all([
+            a.site(state.site_id),
+            a.getDraft(state.site_id, state.env).catch((e) => {
+                if (e instanceof CliError && e.status === 404)
+                    return null;
+                throw e;
+            }),
+            a.versions(state.site_id).catch(() => []),
+        ]);
+        const remoteHash = draft ? configHash(draft.config) : null;
+        const localModified = localHash !== null && localHash !== state.last_pulled_hash;
+        const remoteModified = remoteHash !== null && remoteHash !== state.last_pulled_hash;
+        const byNumber = [...versions].sort((x, y) => y.number - x.number);
+        const latest = (env) => byNumber.find((v) => v.environment === env) ?? null;
+        const latestAny = byNumber[0] ?? null;
+        const latestPreview = latest('preview');
+        const latestProd = latest('production');
+        finish({
+            root,
+            site: { id: site.id, name: site.name, primary_domain: site.primary_domain },
+            env: state.env,
+            config_file: file ? relative(root, file.path) : null,
+            framework: framework.framework,
+            languages: langs,
+            local_hash: localHash,
+            local_error: localError,
+            remote_hash: remoteHash,
+            last_pulled_hash: state.last_pulled_hash,
+            last_pulled_updated_at: state.last_pulled_updated_at,
+            remote_updated_at: draft?.updated_at ?? null,
+            local_modified: localModified,
+            remote_modified: remoteModified,
+            in_sync: !localModified && !remoteModified && localHash === remoteHash,
+            latest_version: { any: latestAny?.number ?? null, preview: latestPreview?.number ?? null, production: latestProd?.number ?? null },
+        }, () => {
+            human.intro('status');
+            const sync = localError
+                ? yellow(`local config invalid: ${localError}`)
+                : localModified && remoteModified
+                    ? yellow('both local and remote changed since the last pull (pull will conflict)')
+                    : localModified
+                        ? yellow('local changes not pushed')
+                        : remoteModified
+                            ? yellow('remote draft changed — run pull')
+                            : green('in sync');
+            human.message([
+                `${bold('Site')}       ${site.name} ${dim(site.id)} · ${site.primary_domain}`,
+                `${bold('Env')}        ${state.env}`,
+                `${bold('Config')}     ${file ? relative(root, file.path) : dim('none')} ${dim(`+ ${TEXTS_DIR}/ (${langs.join(', ') || '—'})`)}`,
+                `${bold('Framework')}  ${FRAMEWORK_LABEL[framework.framework]}`,
+                `${bold('Sync')}       ${sync}`,
+                `${bold('Last pull')}  ${formatDate(state.last_pulled_updated_at)} ${dim(state.last_pulled_hash?.slice(0, 12) ?? '')}`,
+                `${bold('Remote')}     ${formatDate(draft?.updated_at)} ${dim(remoteHash?.slice(0, 12) ?? '')}`,
+                `${bold('Versions')}   latest v${latestAny?.number ?? '—'}${latestPreview || latestProd ? ` (preview v${latestPreview?.number ?? '—'} · production v${latestProd?.number ?? '—'})` : ''}`,
+            ].join('\n'));
+            human.outro('OK');
+        });
+    });
+}

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

@@ -0,0 +1,133 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { BannerConfigSchema } from "../configpkg.js";
+import { CliError, usage } from "../errors.js";
+import { askConfirm, ctx, human, bold, dim, green, red } from "../output.js";
+import { formatDate, parseCsvList, table } from "../util.js";
+import { api, envOf, finish, formatLint, project, siteIdOf } from "./_shared.js";
+/** The config groups apply_template understands (contracts.md, phase 5). */
+const GROUPS = ['layout', 'theme', 'texts', 'regions', 'consent_mode', 'behaviour'];
+function describe(t) {
+    const cfg = t.config;
+    return [
+        `${bold('Template')}  ${t.name} ${dim(t.id)}`,
+        `${bold('Source')}    ${t.org_id ? 'workspace' : 'built-in'}`,
+        t.description ? `${bold('About')}     ${t.description}` : '',
+        cfg ? `${bold('Config')}    layout ${cfg.layout} · ${cfg.languages?.length ?? 0} language(s) · ${cfg.categories?.length ?? 0} categories · theme ${cfg.theme?.system ?? 'classic'}` : '',
+        `${bold('Updated')}   ${formatDate(t.updated_at ?? t.created_at)}`,
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+/** `--config <file>`: a JSON BannerConfig, validated locally before it is sent. */
+function readConfigFile(file) {
+    const path = resolve(ctx().cwd, file);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        throw usage(`Could not read ${file} as JSON: ${e.message}`);
+    }
+    const parsed = BannerConfigSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new CliError('schema', `${file} is not a valid BannerConfig: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`, 1);
+    return parsed.data;
+}
+export function register(program) {
+    const templates = program.command('templates').description('Banner templates (built-in and workspace)');
+    templates
+        .command('list', { isDefault: true })
+        .description('List the templates this token can apply')
+        .action(async () => {
+        const items = await api().templates();
+        finish({ templates: items }, () => {
+            if (!items.length)
+                return human.print(dim('No templates.'));
+            human.print(table(items.map((t) => [t.id, t.name, t.org_id ? 'workspace' : 'built-in', String(t.description ?? '').slice(0, 60), formatDate(t.updated_at ?? t.created_at)]), ['id', 'name', 'source', 'description', 'updated']));
+        });
+    });
+    templates
+        .command('show <id>')
+        .description('One template with its configuration')
+        .option('--config-only', 'print only the BannerConfig JSON (pipe it into a file)')
+        .action(async (id, opts) => {
+        const t = await api().template(id);
+        finish({ template: t }, () => {
+            if (opts.configOnly)
+                return human.print(JSON.stringify(t.config ?? null, null, 2));
+            human.message(describe(t));
+        });
+    });
+    templates
+        .command('save <name>')
+        .description("Save a workspace template from a site's draft or from a config file (feature shared_templates)")
+        .option('--from-site <id>', 'copy this site’s draft (default: the linked site, unless --config is given)')
+        .option('--env <env>', 'which draft to copy: production (default) or preview')
+        .option('--config <file>', 'a JSON BannerConfig file to save instead of a draft')
+        .option('--id <template>', 'update this workspace template instead of creating a new one')
+        .action(async (name, opts) => {
+        if (!name.trim())
+            throw usage('The template needs a name.');
+        const body = { name: name.trim() };
+        if (opts.config)
+            body.config = readConfigFile(opts.config);
+        else {
+            body.from_site = siteIdOf(opts.fromSite);
+            body.env = envOf(opts.env, 'production');
+        }
+        const t = opts.id ? await api().updateTemplate(opts.id, body) : await api().createTemplate(body);
+        finish({ template: t, updated: Boolean(opts.id) }, () => {
+            human.success(`${opts.id ? 'Updated' : 'Saved'} template ${bold(t.name)} (${t.id})`);
+            human.message(describe(t));
+            human.outro(`Apply it to a site with ${dim(`cookiecrumbs templates apply ${t.id} --site <id>`)}`);
+        });
+    });
+    templates
+        .command('delete <id>')
+        .description('Delete a workspace template (built-in templates cannot be deleted)')
+        .option('-y, --yes', 'do not ask for confirmation')
+        .action(async (id, opts) => {
+        if (!opts.yes && !ctx().json) {
+            const ok = await askConfirm(`Delete template ${id}?`, '--yes', false);
+            if (!ok)
+                throw new CliError('cancelled', 'Cancelled.', 2);
+        }
+        await api().deleteTemplate(id);
+        finish({ deleted: id }, () => human.success(`Deleted template ${id}`));
+    });
+    templates
+        .command('apply <template>')
+        .description('Apply a template to one or more site drafts (never publishes)')
+        .option('--site <ids>', 'comma-separated site ids (default: the linked site)')
+        .option('--groups <list>', `config groups to copy: ${GROUPS.join(', ')} (default: all)`)
+        .option('--env <env>', 'preview or production draft (default: preview)')
+        .action(async (template, opts) => {
+        const env = envOf(opts.env, 'preview');
+        const groups = parseCsvList(opts.groups);
+        const unknown = (groups ?? []).filter((g) => !GROUPS.includes(g));
+        if (unknown.length)
+            throw usage(`Unknown group(s): ${unknown.join(', ')}. Known groups: ${GROUPS.join(', ')}.`);
+        let siteIds = parseCsvList(opts.site);
+        if (!siteIds || !siteIds.length)
+            siteIds = [project().state.site_id];
+        const results = await api().applyTemplate(template, { site_ids: siteIds, groups, env });
+        const failed = results.filter((r) => !r.ok);
+        const payload = { template, env, groups: groups ?? GROUPS, results, applied: results.length - failed.length, failed: failed.length };
+        const render = () => {
+            for (const r of results) {
+                human.print(`${r.ok ? green('applied') : red('failed ')} ${r.site_id}${r.ok ? '' : `  ${r.error ?? ''}`}`);
+                if (r.ok && r.lint && r.lint.issues?.length)
+                    human.print(formatLint(r.lint.issues));
+            }
+            human.message(`${bold('Drafts updated')} ${payload.applied}/${results.length} (${env}). ${dim('Review and publish with `cookiecrumbs push` / `versions publish`.')}`);
+        };
+        // Never report success for a site the server refused: one JSON object either way.
+        if (failed.length) {
+            if (!ctx().json)
+                render();
+            throw new CliError('template_apply_failed', `${failed.length} of ${results.length} site(s) could not be updated.`, 1, { extra: payload });
+        }
+        finish(payload, render);
+    });
+}

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

@@ -0,0 +1,50 @@
+import { Api } from "../api.js";
+import { deviceFlow, writeCredentials, DEFAULT_SCOPES } from "../auth.js";
+import { usage } from "../errors.js";
+import { ctx, human, bold, dim } from "../output.js";
+import { cliVersion, formatDate, parseCsvList, table } from "../util.js";
+import { api, finish } from "./_shared.js";
+export function register(program) {
+    const tokens = program.command('tokens').description('API tokens of the workspace');
+    tokens
+        .command('list', { isDefault: true })
+        .description('List tokens (no secrets)')
+        .option('--all', 'include revoked tokens')
+        .action(async (opts) => {
+        let rows = await api().tokens();
+        if (!opts.all)
+            rows = rows.filter((t) => !t.revoked_at);
+        finish({ tokens: rows }, () => {
+            if (!rows.length)
+                return human.print(dim('No tokens.'));
+            human.print(table(rows.map((t) => [t.prefix ?? '', t.name, t.kind, (t.scopes ?? []).join(','), t.site_id ? `${t.site_id.slice(0, 8)}…${t.environment ? '/' + t.environment : ''}` : 'any', formatDate(t.expires_at), formatDate(t.last_used_at), t.revoked_at ? 'revoked' : 'active', t.id]), ['prefix', 'name', 'kind', 'scopes', 'site', 'expires', 'last used', 'state', 'id']));
+        });
+    });
+    tokens
+        .command('revoke <id>')
+        .description('Revoke a token by id')
+        .option('--note <text>', 'reason for the audit trail')
+        .action(async (id, opts) => {
+        const r = await api().revokeToken(id, opts.note);
+        finish({ revoked: id, result: r ?? null }, () => human.success(`Revoked token ${id}`));
+    });
+    tokens
+        .command('create')
+        .description('Create a token through the device flow (approve in the dashboard; the secret is printed once)')
+        .option('--scopes <list>', `scopes to request (default: ${DEFAULT_SCOPES.join(',')})`)
+        .option('--use', 'also store it as this machine\'s credentials')
+        .option('--no-open', 'do not open the browser; just print the URL')
+        .action(async (opts) => {
+        if (ctx().json)
+            throw usage('tokens create is interactive (device flow). Create tokens in the dashboard under Developers, or run it without --json.');
+        human.intro('tokens create');
+        const anon = new Api(ctx().api, null, cliVersion());
+        const { token } = await deviceFlow(anon, { scopes: parseCsvList(opts.scopes), open: opts.open });
+        human.note(`${token.token}\n\nThis is the only time the secret is shown.`, `Token "${token.name}" (${(token.scopes ?? []).join(', ')})`);
+        if (opts.use) {
+            const file = writeCredentials({ api: anon.base, token: token.token, org: token.org, name: token.name, token_id: token.token_id, scopes: token.scopes, expires_at: token.expires_at });
+            human.success(`Stored as credentials in ${file}`);
+        }
+        human.outro(`Use it with ${bold('COOKIECRUMBS_TOKEN')} in CI or ${bold('cookiecrumbs login --token')}.`);
+    });
+}