hub-launch 1.23.0 → 1.25.0

package/dist/commands/errorWatcher.js

@@ -0,0 +1,1017 @@
+import axios from 'axios';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { logger } from '../utils/logger.js';
+import { resolveProject } from '../utils/project-resolver.js';
+import { loadGitHubToken } from './login.js';
+import { HULA_PROJECT_URL } from '../config/constants.js';
+import { resolveProviderCredentials } from '../utils/provider-credentials.js';
+// ── Tuning bounds (client-side convenience checks; the server is authoritative) ──
+const DEDUPE_WINDOW_MIN = 300;
+const DEDUPE_WINDOW_MAX = 604800;
+const OUTCOME_TYPES = ['pr', 'plan', 'feedback'];
+const PR_POLICIES = ['always', 'skip-if-open', 'close-previous'];
+const CONTAINER_BOUNDS = {
+    cpu: { min: 1, max: 32 },
+    memory: { min: 1, max: 128 },
+    disk: { min: 5, max: 200 },
+};
+// Server-side caps on the watcher fields that shape what the fix agent sees.
+// Mirrors WATCHER_INSTRUCTIONS_MAX_LEN / WATCHER_SECRET*_LEN /
+// WATCHER_SECRETS_MAX_COUNT / ERROR_ENV_VARS_MAX_COUNT in @hula/shared. The
+// server re-validates; these only save a round trip.
+const INSTRUCTIONS_MAX_LEN = 4000;
+const SECRET_MIN_LEN = 6;
+const SECRET_MAX_LEN = 512;
+const SECRETS_MAX_COUNT = 50;
+const ERROR_ENV_VARS_MAX_COUNT = 50;
+const ERROR_ENV_VAR_VALUE_MAX_LEN = 8192;
+/**
+ * Env var names the server refuses on `errorEnvVars` because the platform owns
+ * them inside the fix sandbox. Rejecting client-side turns a 400 into an
+ * immediate, specific message.
+ */
+const RESERVED_ENV_PREFIXES = ['HULA_', 'RALPH_'];
+const RESERVED_ENV_NAMES = ['GITHUB_TOKEN', 'PATH', 'HOME'];
+/**
+ * Fields the create endpoint accepts but `PATCH /api/v1/error-watchers/:id`
+ * does not. Sending them on `--update` used to succeed while silently changing
+ * nothing, so they are rejected up front instead.
+ */
+const CREATE_ONLY_FLAGS = [
+    ['containerCpu', '--container-cpu'],
+    ['containerMemory', '--container-memory'],
+    ['containerDisk', '--container-disk'],
+    ['updateNotificationUrl', '--update-notification-url'],
+    ['updateNotificationNameTag', '--update-notification-name-tag'],
+];
+/**
+ * Manage production Error Watchers — thin REST client over
+ * `/api/v1/error-watchers`, structured like `hula schedule`.
+ */
+export function errorWatcherCommand(program, config) {
+    program
+        .command('error-watcher')
+        .description('Manage production Error Watchers (inbound error webhooks that auto-launch fix PRs)')
+        .option('--create', 'Create a new error watcher for this project')
+        .option('--list', 'List error watchers for this project')
+        .option('--show <watcherId>', 'Show one watcher configuration')
+        .option('--events [watcherId]', 'List recent error events (all watchers if no id)')
+        .option('--update <watcherId>', 'Update watcher settings')
+        .option('--delete <watcherId>', 'Delete (soft) a watcher')
+        .option('--print-setup [watcherId]', 'Re-print the .env block and request snippet (no secret values)')
+        // Create/update tuning flags
+        .option('--name <name>', 'Watcher label, e.g. api-prod (default: "default")')
+        .option('--dedupe-window <seconds>', 'Dedupe window in seconds (300–604800, default 86400)', parseInt)
+        .option('--max-fixes-per-day <n>', 'Max fix launches per UTC day (default 5)', parseInt)
+        .option('--environments <list>', 'Comma-separated environments allowed to launch fixes (default: production)')
+        .option('--outcome-type <type>', 'pr (default) | plan | feedback')
+        .option('--pr-policy <policy>', 'always | skip-if-open (default) | close-previous')
+        .option('--enabled <bool>', 'Enable or disable the watcher (true|false)')
+        .option('--instructions <text>', `Trusted guidance for the fix agent (max ${INSTRUCTIONS_MAX_LEN} chars)`)
+        .option('--clear-instructions', 'Remove the stored instructions (--update only)')
+        .option('--error-env <KEY=VALUE>', 'Env var for the fix sandbox; repeatable. Replaces the whole map', collectRepeatable)
+        .option('--clear-error-env', 'Remove all errorEnvVars (--update only)')
+        .option('--secret <value>', 'Extra literal value to redact from payloads; repeatable. Replaces the whole list', collectRepeatable)
+        .option('--clear-secrets', 'Remove all extra redaction secrets (--update only)')
+        // Filters
+        .option('--status <status>', 'Filter --events by status')
+        .option('--limit <n>', 'Max rows for --list/--events (default 20)', parseInt)
+        // Standard overrides, identical to `hula schedule`
+        .option('--provider <type>', 'LLM provider: claude | openai | openrouter')
+        .option('--provider-key <key>', 'Provider credential')
+        .option('--container-cpu <n>', 'vCPU for fix sandboxes (1–32)', parseInt)
+        .option('--container-memory <n>', 'GiB RAM for fix sandboxes (1–128)', parseInt)
+        .option('--container-disk <n>', 'GiB disk for fix sandboxes (5–200)', parseInt)
+        .option('--update-notification-url <url>', 'Webhook for fix-run notifications')
+        .option('--update-notification-name-tag <tag>', 'Verbatim "initiated by" label for notifications')
+        .option('--project <owner/repo>', 'Override the target repository')
+        .option('--url <url>', 'Override hula-project server URL')
+        .option('--api-key <key>', 'Override hula API key')
+        .option('--yes', 'Skip the interactive confirmation on --delete')
+        .option('--json', 'Emit raw JSON instead of formatted output')
+        .addHelpText('after', `
+An Error Watcher is an inbound webhook: your production app reports an error to
+HubLaunch, and HubLaunch deduplicates it and auto-launches a fix (a PR, plan, or
+feedback run). This command creates and manages those watchers from the CLI.
+
+The watcher holds the CONFIGURATION (dedupe window, environments, PR policy,
+instructions, errorEnvVars, secrets). The CREDENTIAL your app presents is a
+separate project ingest key (hik_…) with its own signing secret (his_…), created
+in the dashboard under Projects → gear icon → Error reporting API keys. Both are
+required: a valid key whose project has no enabled watcher is rejected with 409.
+
+Examples:
+  hula error-watcher --create --name api-prod
+      Create a watcher, then print the .env block and a ready-to-paste
+      signed-request snippet.
+
+  hula error-watcher --events
+      Show recent error events across every watcher on this project, and why
+      each did or did not launch a fix (deduped / skipped_budget /
+      skipped_credits / skipped_environment / …).
+
+  hula error-watcher --update <id> --instructions "Never touch billing/"
+      Set the trusted guidance handed to the fix agent.
+
+Credentials resolve from flags, then .hublaunch/hublaunch.config.js, then env,
+exactly like "hula schedule". Run "hula login" first.
+
+Docs: https://github.com/NoStackApp/hub-launch/blob/main/docs/error-watcher.md
+`)
+        .action(async (options, command) => {
+        try {
+            await runErrorWatcher(config, options, () => command.help());
+        }
+        catch (error) {
+            logger.error('Error watcher command failed:');
+            logger.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+}
+/**
+ * Commander collector for a repeatable flag. `previous` is undefined on the
+ * first occurrence, which is what lets a caller distinguish "flag omitted"
+ * (undefined) from "flag given" — the distinction PATCH relies on to leave a
+ * field untouched rather than clearing it.
+ */
+export function collectRepeatable(value, previous) {
+    return [...(previous ?? []), value];
+}
+/**
+ * Which mode flags are active. `--events` and `--print-setup` count when
+ * present even without a value (`true`); every other flag counts when truthy.
+ */
+export function selectModes(options) {
+    const modes = [];
+    if (options.create)
+        modes.push('create');
+    if (options.list)
+        modes.push('list');
+    if (options.show)
+        modes.push('show');
+    if (options.events !== undefined)
+        modes.push('events');
+    if (options.update)
+        modes.push('update');
+    if (options.delete)
+        modes.push('delete');
+    if (options.printSetup !== undefined)
+        modes.push('print-setup');
+    return modes;
+}
+/**
+ * Dispatch a single mode. Enforces mutual exclusion BEFORE any network call, so
+ * two mode flags fail without issuing a request. With no mode flag, prints help.
+ */
+export async function runErrorWatcher(config, options, showHelp) {
+    const modes = selectModes(options);
+    if (modes.length > 1) {
+        logger.error(`Provide only one mode flag — got conflicting: ${modes
+            .map((m) => `--${m}`)
+            .join(', ')}.`);
+        process.exit(1);
+        return;
+    }
+    if (modes.length === 0) {
+        if (showHelp) {
+            showHelp();
+        }
+        else {
+            logger.info('No mode flag given. Run "hula error-watcher --help" for usage.');
+        }
+        return;
+    }
+    switch (modes[0]) {
+        case 'create':
+            return createWatcher(config, options);
+        case 'list':
+            return listWatchers(config, options);
+        case 'show':
+            return showWatcher(config, options.show, options);
+        case 'events':
+            return listEvents(config, options);
+        case 'update':
+            return updateWatcher(config, options.update, options);
+        case 'delete':
+            return deleteWatcher(config, options.delete, options);
+        case 'print-setup':
+            return printSetupOnly(config, options);
+    }
+}
+// ── Resolution helpers (parity with schedule.ts) ────────────────────────────
+function resolveServerUrl(config, options) {
+    const serverUrl = options.url || config.hulaProjectUrl || HULA_PROJECT_URL;
+    return serverUrl.replace(/\/$/, '');
+}
+function resolveApiKey(config, options) {
+    const apiKey = options.apiKey || config.hulaApiKey || process.env.HULA_API_KEY;
+    if (!apiKey) {
+        logger.error('No API key configured.');
+        logger.info('Set hulaApiKey in your config or use --api-key option.');
+        logger.info('You can also set HULA_API_KEY environment variable.');
+        logger.info("Run 'hula login' to authenticate with hula-project.");
+        process.exit(1);
+    }
+    return apiKey;
+}
+function authHeaders(apiKey) {
+    return {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+    };
+}
+/**
+ * The ingest webhook URL the customer's production app POSTs to. Defaults to
+ * `<serverUrl>/api/v1/webhooks/error`, overridable via `config.errorWebhookUrl`
+ * for self-hosted servers whose webhook host differs from `hulaProjectUrl`.
+ */
+export function resolveWebhookUrl(serverUrl, config) {
+    return config.errorWebhookUrl || `${serverUrl}/api/v1/webhooks/error`;
+}
+/**
+ * Where a project ingest key (`hik_…`) is minted. Key CRUD is exposed over
+ * tRPC only — there is no REST route for the CLI to call — so every setup path
+ * points the user at this page rather than pretending to issue a credential.
+ */
+export function resolveProjectSettingsUrl(serverUrl) {
+    return `${serverUrl}/dashboard/projects`;
+}
+/** The three lines that direct a user to mint an ingest key. */
+function printIngestKeyInstructions(serverUrl) {
+    logger.info(`  Open ${resolveProjectSettingsUrl(serverUrl)}`);
+    logger.info('  Click the gear icon on the project card → Error reporting API keys → Create key.');
+    logger.info('  Copy the hik_… key and his_… secret — both are shown exactly once.');
+}
+// ── Client-side validation ──────────────────────────────────────────────────
+/**
+ * Validate tuning flags client-side so the common mistakes are caught without a
+ * network round trip. Returns a list of error strings (empty when all valid).
+ * The server validates independently; this is a convenience, not the boundary.
+ */
+export function validateTuningOptions(options) {
+    const errors = [];
+    if (options.dedupeWindow !== undefined) {
+        const w = options.dedupeWindow;
+        if (!Number.isInteger(w) ||
+            w < DEDUPE_WINDOW_MIN ||
+            w > DEDUPE_WINDOW_MAX) {
+            errors.push(`--dedupe-window must be an integer between ${DEDUPE_WINDOW_MIN} and ${DEDUPE_WINDOW_MAX} seconds.`);
+        }
+    }
+    if (options.maxFixesPerDay !== undefined) {
+        const n = options.maxFixesPerDay;
+        if (!Number.isInteger(n) || n < 1) {
+            errors.push('--max-fixes-per-day must be an integer of at least 1.');
+        }
+    }
+    if (options.outcomeType !== undefined &&
+        !OUTCOME_TYPES.includes(options.outcomeType)) {
+        errors.push(`--outcome-type must be one of: ${OUTCOME_TYPES.join(', ')}.`);
+    }
+    if (options.prPolicy !== undefined &&
+        !PR_POLICIES.includes(options.prPolicy)) {
+        errors.push(`--pr-policy must be one of: ${PR_POLICIES.join(', ')}.`);
+    }
+    if (options.enabled !== undefined &&
+        options.enabled !== 'true' &&
+        options.enabled !== 'false') {
+        errors.push('--enabled must be "true" or "false".');
+    }
+    for (const [key, flag] of [
+        ['cpu', 'containerCpu'],
+        ['memory', 'containerMemory'],
+        ['disk', 'containerDisk'],
+    ]) {
+        const value = options[flag];
+        if (value === undefined)
+            continue;
+        const { min, max } = CONTAINER_BOUNDS[key];
+        if (!Number.isInteger(value) || value < min || value > max) {
+            errors.push(`--container-${key} must be an integer between ${min} and ${max}.`);
+        }
+    }
+    if (options.instructions !== undefined &&
+        options.instructions.length > INSTRUCTIONS_MAX_LEN) {
+        errors.push(`--instructions must be at most ${INSTRUCTIONS_MAX_LEN} characters (got ${options.instructions.length}).`);
+    }
+    if (options.instructions !== undefined && options.clearInstructions) {
+        errors.push('--instructions and --clear-instructions are mutually exclusive.');
+    }
+    if (options.errorEnv !== undefined && options.clearErrorEnv) {
+        errors.push('--error-env and --clear-error-env are mutually exclusive.');
+    }
+    if (options.secret !== undefined && options.clearSecrets) {
+        errors.push('--secret and --clear-secrets are mutually exclusive.');
+    }
+    errors.push(...validateErrorEnv(options.errorEnv));
+    errors.push(...validateSecrets(options.secret));
+    return errors;
+}
+/**
+ * Validate the repeatable `--error-env KEY=VALUE` pairs. Reserved names are
+ * rejected here because the server returns a 400 for them, and the platform
+ * owns those variables inside the fix sandbox.
+ */
+export function validateErrorEnv(entries) {
+    if (entries === undefined)
+        return [];
+    const errors = [];
+    if (entries.length > ERROR_ENV_VARS_MAX_COUNT) {
+        errors.push(`--error-env may be given at most ${ERROR_ENV_VARS_MAX_COUNT} times (got ${entries.length}).`);
+    }
+    const seen = new Set();
+    for (const entry of entries) {
+        const eq = entry.indexOf('=');
+        if (eq <= 0) {
+            errors.push(`--error-env "${entry}" must be in KEY=VALUE form.`);
+            continue;
+        }
+        const key = entry.slice(0, eq);
+        const value = entry.slice(eq + 1);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            errors.push(`--error-env key "${key}" is not a valid environment variable name.`);
+        }
+        if (seen.has(key)) {
+            errors.push(`--error-env key "${key}" was given more than once.`);
+        }
+        seen.add(key);
+        if (RESERVED_ENV_PREFIXES.some((p) => key.startsWith(p)) ||
+            RESERVED_ENV_NAMES.includes(key)) {
+            errors.push(`--error-env key "${key}" is reserved by the platform and will be rejected by the server.`);
+        }
+        if (value.length > ERROR_ENV_VAR_VALUE_MAX_LEN) {
+            errors.push(`--error-env value for "${key}" exceeds ${ERROR_ENV_VAR_VALUE_MAX_LEN} characters.`);
+        }
+    }
+    return errors;
+}
+/**
+ * Validate the repeatable `--secret` values. The minimum length is the server's
+ * floor: a very short literal would match everywhere and shred the very error
+ * text the fix agent needs.
+ */
+export function validateSecrets(entries) {
+    if (entries === undefined)
+        return [];
+    const errors = [];
+    if (entries.length > SECRETS_MAX_COUNT) {
+        errors.push(`--secret may be given at most ${SECRETS_MAX_COUNT} times (got ${entries.length}).`);
+    }
+    for (const value of entries) {
+        if (value.length < SECRET_MIN_LEN || value.length > SECRET_MAX_LEN) {
+            // The value itself is a credential — report its length, never its text.
+            errors.push(`--secret values must be between ${SECRET_MIN_LEN} and ${SECRET_MAX_LEN} characters (got one of length ${value.length}).`);
+        }
+    }
+    return errors;
+}
+/** Parse validated `KEY=VALUE` entries into the map the server expects. */
+export function parseErrorEnv(entries) {
+    const map = {};
+    for (const entry of entries) {
+        const eq = entry.indexOf('=');
+        if (eq <= 0)
+            continue;
+        map[entry.slice(0, eq)] = entry.slice(eq + 1);
+    }
+    return map;
+}
+/**
+ * Build the subset of tuning fields the user actually supplied. Used by both
+ * `--create` and `--update` so a PATCH never carries `undefined` keys.
+ *
+ * `mode` gates the fields the create endpoint accepts but PATCH ignores
+ * (container resources, notification overrides). Sending them on an update
+ * used to return 200 while changing nothing; `--update` now rejects them in
+ * `updateWatcher` before the request, and they are omitted here as a backstop.
+ */
+function collectTuningFields(options, mode = 'create') {
+    const body = {};
+    if (options.name !== undefined)
+        body.name = options.name;
+    if (options.dedupeWindow !== undefined) {
+        body.dedupeWindowSeconds = options.dedupeWindow;
+    }
+    if (options.maxFixesPerDay !== undefined) {
+        body.maxFixesPerDay = options.maxFixesPerDay;
+    }
+    if (options.environments !== undefined) {
+        body.environments = options.environments
+            .split(',')
+            .map((e) => e.trim())
+            .filter((e) => e.length > 0);
+    }
+    if (options.outcomeType !== undefined)
+        body.outcomeType = options.outcomeType;
+    if (options.prPolicy !== undefined)
+        body.prPolicy = options.prPolicy;
+    if (options.enabled !== undefined)
+        body.enabled = options.enabled === 'true';
+    // Trusted guidance for the fix agent. `null` clears it; omitting the key
+    // leaves the stored value untouched — the server distinguishes the two.
+    if (options.instructions !== undefined) {
+        body.instructions = options.instructions;
+    }
+    else if (options.clearInstructions) {
+        body.instructions = null;
+    }
+    // Both of these REPLACE the stored value wholesale on the server, so the CLI
+    // sends the complete set the user typed, never a delta.
+    if (options.errorEnv !== undefined) {
+        body.errorEnvVars = parseErrorEnv(options.errorEnv);
+    }
+    else if (options.clearErrorEnv) {
+        body.errorEnvVars = {};
+    }
+    if (options.secret !== undefined) {
+        body.secrets = options.secret;
+    }
+    else if (options.clearSecrets) {
+        body.secrets = [];
+    }
+    if (mode === 'create') {
+        const cpu = options.containerCpu;
+        const memory = options.containerMemory;
+        const disk = options.containerDisk;
+        if (cpu !== undefined || memory !== undefined || disk !== undefined) {
+            const resources = {};
+            if (cpu !== undefined)
+                resources.cpu = cpu;
+            if (memory !== undefined)
+                resources.memory = memory;
+            if (disk !== undefined)
+                resources.disk = disk;
+            body.containerResources = resources;
+        }
+        if (options.updateNotificationUrl !== undefined) {
+            body.updateNotificationUrl = options.updateNotificationUrl;
+        }
+        if (options.updateNotificationNameTag !== undefined) {
+            body.updateNotificationNameTag = options.updateNotificationNameTag;
+        }
+    }
+    return body;
+}
+// ── Setup output (the core value of this command) ───────────────────────────
+/**
+ * The signed-request snippet. HARD-CODED (never fetched) so `--print-setup`
+ * works with the server unreachable. Built line-by-line from single/double
+ * quoted strings so the literal `${timestamp}.${body}` signing payload survives
+ * verbatim into the printed output (it must NOT be interpolated here).
+ */
+export function buildSigningSnippet() {
+    return [
+        '// Report an error to HubLaunch. Call this from your error handler.',
+        "import { createHmac } from 'node:crypto';",
+        '',
+        'export async function reportErrorToHula(err, extra = {}) {',
+        '  const body = JSON.stringify({',
+        '    errorDescription: err?.message ?? String(err),',
+        '    // ── Dedupe identity. The fingerprint is built from these three fields',
+        '    //    and ONLY these three. Send none of them and every error on this',
+        '    //    watcher collapses into one bucket — one fix per dedupe window.',
+        '    key: extra.key,          // your own stable key; survives refactors',
+        '    errorName: err?.name,    // e.g. TypeError',
+        '    errorCode: err?.code,    // e.g. P2002',
+        '    stack: err?.stack,',
+        '    logs: extra.logs,',
+        "    environment: process.env.NODE_ENV ?? 'production',",
+        '    release: process.env.GIT_COMMIT_SHA,   // enables fixing the exact shipped code',
+        '    occurredAt: new Date().toISOString(),',
+        '    context: extra.context,',
+        '  });',
+        '',
+        '  const timestamp = Math.floor(Date.now() / 1000).toString();',
+        "  const signature = createHmac('sha256', process.env.HULA_INGEST_SECRET)",
+        '    .update(`${timestamp}.${body}`)   // NOTE: timestamp + "." + body',
+        "    .digest('hex');",
+        '',
+        '  try {',
+        '    await fetch(process.env.HULA_ERROR_WEBHOOK_URL, {',
+        "      method: 'POST',",
+        '      headers: {',
+        "        'Content-Type': 'application/json',",
+        "        'X-Hula-Api-Key': process.env.HULA_INGEST_KEY,",
+        "        'X-Hula-Timestamp': timestamp,",
+        "        'X-Hula-Signature': `sha256=${signature}`,",
+        '      },',
+        '      body,',
+        '    });',
+        '  } catch {',
+        '    // Never let error reporting break the request that was already failing.',
+        '  }',
+        '}',
+    ].join('\n');
+}
+/**
+ * The `.env` block for the customer's production environment.
+ *
+ * The credential is the PROJECT ingest key (`hik_…`) and its own signing secret
+ * (`his_…`), minted in the dashboard settings page — not the watcher. The CLI
+ * never holds either value, so both are always placeholders.
+ */
+export function buildEnvBlock(webhookUrl) {
+    return [
+        '# HubLaunch Error Watcher — add to your production environment',
+        `HULA_ERROR_WEBHOOK_URL=${webhookUrl}`,
+        'HULA_INGEST_KEY=hik_…',
+        'HULA_INGEST_SECRET=his_…',
+    ].join('\n');
+}
+/** The notes printed below the snippet. */
+function printSnippetNotes() {
+    logger.blank();
+    logger.info('Notes:');
+    logger.info('  • Send `key`, `errorName` or `errorCode`. The dedupe fingerprint is built');
+    logger.info('    from those three fields alone — with none of them, every error on this');
+    logger.info('    watcher shares one bucket and you get one fix per window.');
+    logger.info('  • Do not log credentials. The server best-effort redacts common secret');
+    logger.info('    shapes from stack/logs on arrival, but the real fix is not printing them.');
+    logger.info('    Use --secret to register literals the built-in matcher cannot know about.');
+    logger.info('  • Set `release` to your deployed commit SHA so the fix agent branches from');
+    logger.info('    the code that actually crashed, not your default branch.');
+    logger.info('  • A 409 means the key is valid but this project has no enabled watcher.');
+}
+/**
+ * Print the wiring steps for a watcher: mint the project ingest key, set the
+ * env vars, paste the signed-request snippet.
+ *
+ * The CLI deliberately prints no credential of its own. Ingest keys are created
+ * over tRPC from the dashboard and have no REST route, so the only honest thing
+ * the CLI can do is say where to get one. The watcher `hew_`/`hes_` values the
+ * create endpoint still returns authenticate nothing and are never shown.
+ */
+export function printSetupInstructions(serverUrl, webhookUrl) {
+    logger.blank();
+    logger.info('① Create a project ingest key (the credential your app presents):');
+    printIngestKeyInstructions(serverUrl);
+    logger.blank();
+    logger.info('② Add these to your production environment:');
+    logger.blank();
+    logger.log(buildEnvBlock(webhookUrl));
+    logger.blank();
+    logger.info('③ Report errors with this snippet (signing is not guessable):');
+    logger.blank();
+    logger.log(buildSigningSnippet());
+    printSnippetNotes();
+    logger.blank();
+}
+// ── Mode: create ────────────────────────────────────────────────────────────
+async function createWatcher(config, options) {
+    logger.section('Create Error Watcher');
+    const validationErrors = validateTuningOptions(options);
+    if (validationErrors.length > 0) {
+        validationErrors.forEach((msg) => logger.error(msg));
+        process.exit(1);
+        return;
+    }
+    const serverUrl = resolveServerUrl(config, options);
+    const apiKey = resolveApiKey(config, options);
+    const project = await resolveProject(config, options.project);
+    // A fix run cannot launch without a provider credential, so the server rejects
+    // a watcher created with none. Catch it client-side before the request.
+    const { providerType, authToken, errors } = resolveProviderCredentials(options, config);
+    if (errors.length > 0) {
+        errors.forEach((msg) => logger.error(msg));
+        process.exit(1);
+        return;
+    }
+    const requestBody = {
+        project,
+        provider: { type: providerType, authToken },
+        ...collectTuningFields(options),
+    };
+    // The server stores an encrypted GitHub token on the watcher for use at
+    // fix-launch time. Attach when present; if absent the server returns its own
+    // error (parity with `hula schedule`).
+    const tokenData = await loadGitHubToken();
+    const githubToken = tokenData?.access_token || process.env.GITHUB_TOKEN;
+    if (githubToken) {
+        requestBody.githubToken = githubToken;
+    }
+    logger.info(`Project: ${project}`);
+    logger.info(`Server:  ${serverUrl}`);
+    logger.blank();
+    try {
+        // The response also carries a `credentials` object holding the watcher's
+        // `hew_`/`hes_` pair. Nothing verifies those any more — ingest authenticates
+        // on the project key — so they are deliberately not destructured, not
+        // printed, and not stored.
+        const response = await axios.post(`${serverUrl}/api/v1/error-watchers`, requestBody, { headers: authHeaders(apiKey), timeout: 30000 });
+        const { watcher } = response.data;
+        if (options.json) {
+            logger.log(JSON.stringify({ watcher }, null, 2));
+            return;
+        }
+        logger.success(`Error watcher "${watcher.name}" created (id: ${watcher.id}).`);
+        printSetupInstructions(serverUrl, resolveWebhookUrl(serverUrl, config));
+    }
+    catch (error) {
+        handleWatcherApiError(error, serverUrl, { project });
+        process.exit(1);
+    }
+}
+// ── Mode: list ──────────────────────────────────────────────────────────────
+async function listWatchers(config, options) {
+    const serverUrl = resolveServerUrl(config, options);
+    const apiKey = resolveApiKey(config, options);
+    const project = await resolveProject(config, options.project);
+    try {
+        const response = await axios.get(`${serverUrl}/api/v1/error-watchers`, {
+            params: { project, limit: options.limit },
+            headers: authHeaders(apiKey),
+            timeout: 15000,
+        });
+        if (options.json) {
+            logger.log(JSON.stringify(response.data, null, 2));
+            return;
+        }
+        const watchers = response.data.watchers ?? [];
+        logger.section(`Error Watchers — ${project}`);
+        if (watchers.length === 0) {
+            logger.info('No error watchers found. Create one with --create.');
+            return;
+        }
+        for (const w of watchers) {
+            logger.log(`  ${w.id}  ${w.name.padEnd(16)}  ${w.environments
+                .join(',')
+                .padEnd(20)}  dedupe:${humanizeDuration(w.dedupeWindowSeconds).padEnd(5)}  max/day:${String(w.maxFixesPerDay).padEnd(3)}  ${w.enabled ? 'enabled ' : 'disabled'}  ${w.lastEventAt ? relativeTime(w.lastEventAt) : 'no events'}`);
+        }
+        logger.blank();
+    }
+    catch (error) {
+        handleWatcherApiError(error, serverUrl, { project });
+        process.exit(1);
+    }
+}
+// ── Mode: show ──────────────────────────────────────────────────────────────
+async function showWatcher(config, watcherId, options) {
+    const serverUrl = resolveServerUrl(config, options);
+    const apiKey = resolveApiKey(config, options);
+    const project = await resolveProject(config, options.project);
+    try {
+        const response = await axios.get(`${serverUrl}/api/v1/error-watchers/${encodeURIComponent(watcherId)}`, { headers: authHeaders(apiKey), timeout: 15000 });
+        if (options.json) {
+            logger.log(JSON.stringify(response.data, null, 2));
+            return;
+        }
+        const w = response.data.watcher;
+        logger.section(`Error Watcher: ${w.name}`);
+        logger.log(`  ID:            ${w.id}`);
+        logger.log(`  Project:       ${w.projectId}`);
+        logger.log(`  Dedupe window: ${humanizeDuration(w.dedupeWindowSeconds)} (${w.dedupeWindowSeconds}s)`);
+        logger.log(`  Max fixes/day: ${w.maxFixesPerDay}`);
+        logger.log(`  Environments:  ${w.environments.join(', ')}`);
+        logger.log(`  Outcome type:  ${w.outcomeType}`);
+        logger.log(`  PR policy:     ${w.prPolicy}`);
+        logger.log(`  Enabled:       ${w.enabled}`);
+        logger.log(`  Instructions:  ${summarizeInstructions(w.instructions)}`);
+        logger.log(`  Created:       ${w.createdAt}`);
+        logger.log(`  Last event:    ${w.lastEventAt ?? 'never'}`);
+        logger.blank();
+        // `errorEnvVars` and `secrets` are encrypted at rest and never echoed by
+        // the API, so there is nothing to display for them beyond that fact.
+        logger.info('errorEnvVars and secrets are never returned by the API. Replace them wholesale');
+        logger.info(`  hula error-watcher --update ${w.id} --error-env KEY=VALUE --secret <literal>`);
+        logger.blank();
+        logger.info('Signing secrets belong to the project ingest key, not the watcher. Rotate at:');
+        logger.info(`  ${resolveProjectSettingsUrl(serverUrl)} → gear icon → Error reporting API keys`);
+        logger.blank();
+    }
+    catch (error) {
+        handleWatcherApiError(error, serverUrl, { project, watcherId });
+        process.exit(1);
+    }
+}
+// ── Mode: events ────────────────────────────────────────────────────────────
+async function listEvents(config, options) {
+    const serverUrl = resolveServerUrl(config, options);
+    const apiKey = resolveApiKey(config, options);
+    const project = await resolveProject(config, options.project);
+    // `--events` with no value → every watcher on the project; with a value →
+    // that one watcher. There is no project-wide events endpoint on the server —
+    // `/api/v1/error-watchers/events` resolves to the `[watcherId]` route and
+    // 404s — so the no-id form lists the watchers and fans out over them.
+    const watcherId = typeof options.events === 'string' ? options.events : undefined;
+    try {
+        const targets = watcherId
+            ? [{ id: watcherId, name: watcherId }]
+            : (await axios.get(`${serverUrl}/api/v1/error-watchers`, {
+                params: { project },
+                headers: authHeaders(apiKey),
+                timeout: 15000,
+            })).data.watchers ?? [];
+        if (targets.length === 0) {
+            if (options.json) {
+                logger.log(JSON.stringify({ events: [] }, null, 2));
+                return;
+            }
+            logger.section('Recent Error Events');
+            logger.info(`No error watchers on ${project}. Create one with --create.`);
+            return;
+        }
+        const perWatcher = await Promise.all(targets.map(async (w) => {
+            const response = await axios.get(`${serverUrl}/api/v1/error-watchers/${encodeURIComponent(w.id)}/events`, {
+                params: { status: options.status, limit: options.limit },
+                headers: authHeaders(apiKey),
+                timeout: 15000,
+            });
+            return (response.data.events ?? []).map((e) => ({
+                ...e,
+                watcherName: w.name,
+            }));
+        }));
+        // Newest first across every watcher, then re-apply --limit so it caps the
+        // merged list rather than each watcher independently.
+        let events = perWatcher
+            .flat()
+            .sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt));
+        if (options.limit !== undefined) {
+            events = events.slice(0, options.limit);
+        }
+        if (options.json) {
+            logger.log(JSON.stringify({ events }, null, 2));
+            return;
+        }
+        logger.section(watcherId ? 'Recent Error Events' : `Recent Error Events — ${project}`);
+        if (events.length === 0) {
+            logger.info('No error events found.');
+            return;
+        }
+        const showWatcherColumn = !watcherId && targets.length > 1;
+        for (const e of events) {
+            logger.log(`  ${e.createdAt}  ${e.environment.padEnd(12)}  ${e.fingerprint
+                .slice(0, 12)
+                .padEnd(12)}  ×${String(e.occurrenceCount).padEnd(4)}  ${colorStatus(e.status)}${e.skipReason ? `  (${e.skipReason})` : ''}${showWatcherColumn ? `  [${e.watcherName}]` : ''}`);
+        }
+        logger.blank();
+        if (showWatcherColumn) {
+            logger.info(`(${targets.length} watchers queried)`);
+        }
+        logger.info('Legend: launched = a fix run started · deduped = same error within the window');
+        logger.info('        skipped_environment = env not in the allow-list · skipped_budget = daily cap hit');
+        logger.info('        skipped_credits = out of PR credits · skipped_open_pr = an open fix PR already exists');
+        logger.blank();
+    }
+    catch (error) {
+        handleWatcherApiError(error, serverUrl, { project, watcherId });
+        process.exit(1);
+    }
+}
+// ── Mode: update ────────────────────────────────────────────────────────────
+async function updateWatcher(config, watcherId, options) {
+    logger.section('Update Error Watcher');
+    const validationErrors = validateTuningOptions(options);
+    // PATCH silently ignores these, so accepting them would report success while
+    // changing nothing. Fail loudly instead.
+    const unsupported = CREATE_ONLY_FLAGS.filter(([key]) => options[key] !== undefined).map(([, flag]) => flag);
+    if (unsupported.length > 0) {
+        validationErrors.push(`${unsupported.join(', ')} can only be set at --create time; the update endpoint ignores them.`);
+    }
+    if (validationErrors.length > 0) {
+        validationErrors.forEach((msg) => logger.error(msg));
+        process.exit(1);
+        return;
+    }
+    const serverUrl = resolveServerUrl(config, options);
+    const apiKey = resolveApiKey(config, options);
+    const project = await resolveProject(config, options.project);
+    const body = collectTuningFields(options, 'update');
+    if (Object.keys(body).length === 0) {
+        logger.error('Nothing to update — provide at least one field to change.');
+        logger.info('e.g. --max-fixes-per-day 10, --enabled false, --environments production,staging,');
+        logger.info('     --instructions "…", --error-env KEY=VALUE, --secret <literal>');
+        process.exit(1);
+        return;
+    }
+    try {
+        const response = await axios.patch(`${serverUrl}/api/v1/error-watchers/${encodeURIComponent(watcherId)}`, body, { headers: authHeaders(apiKey), timeout: 15000 });
+        if (options.json) {
+            logger.log(JSON.stringify(response.data, null, 2));
+            return;
+        }
+        const w = response.data.watcher;
+        logger.success(`Error watcher "${w.name}" updated.`);
+        logger.log(`  Dedupe window: ${humanizeDuration(w.dedupeWindowSeconds)}`);
+        logger.log(`  Max fixes/day: ${w.maxFixesPerDay}`);
+        logger.log(`  Environments:  ${w.environments.join(', ')}`);
+        logger.log(`  Outcome type:  ${w.outcomeType}`);
+        logger.log(`  PR policy:     ${w.prPolicy}`);
+        logger.log(`  Enabled:       ${w.enabled}`);
+        logger.log(`  Instructions:  ${summarizeInstructions(w.instructions)}`);
+        // errorEnvVars/secrets are encrypted at rest and never echoed back, so the
+        // response cannot confirm them beyond the 200 itself.
+        if (body.errorEnvVars !== undefined) {
+            const count = Object.keys(body.errorEnvVars).length;
+            logger.log(`  errorEnvVars:  replaced (${count} ${count === 1 ? 'entry' : 'entries'}, not echoed back)`);
+        }
+        if (body.secrets !== undefined) {
+            const count = body.secrets.length;
+            logger.log(`  Secrets:       replaced (${count} ${count === 1 ? 'entry' : 'entries'}, not echoed back)`);
+        }
+        logger.blank();
+    }
+    catch (error) {
+        handleWatcherApiError(error, serverUrl, { project, watcherId });
+        process.exit(1);
+    }
+}
+// ── Mode: delete ────────────────────────────────────────────────────────────
+async function deleteWatcher(config, watcherId, options) {
+    const serverUrl = resolveServerUrl(config, options);
+    const apiKey = resolveApiKey(config, options);
+    const project = await resolveProject(config, options.project);
+    // Look up the name first, so the confirmation names what will break.
+    let watcherName = watcherId;
+    try {
+        const response = await axios.get(`${serverUrl}/api/v1/error-watchers/${encodeURIComponent(watcherId)}`, { headers: authHeaders(apiKey), timeout: 15000 });
+        watcherName = response.data.watcher.name;
+    }
+    catch (error) {
+        handleWatcherApiError(error, serverUrl, { project, watcherId });
+        process.exit(1);
+        return;
+    }
+    const isTty = Boolean(process.stdin.isTTY);
+    if (!options.yes) {
+        logger.warning(`Deleting "${watcherName}" (${watcherId}) — if it is the project's only enabled watcher, reports will start returning 409.`);
+        if (isTty) {
+            const { proceed } = await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'proceed',
+                    message: `Delete error watcher "${watcherName}"?`,
+                    default: false,
+                },
+            ]);
+            if (!proceed) {
+                logger.info('Cancelled — nothing deleted.');
+                return;
+            }
+        }
+        else {
+            logger.error('Refusing to delete without confirmation. Re-run with --yes in a non-interactive shell.');
+            process.exit(1);
+            return;
+        }
+    }
+    try {
+        await axios.delete(`${serverUrl}/api/v1/error-watchers/${encodeURIComponent(watcherId)}`, { headers: authHeaders(apiKey), timeout: 15000 });
+        logger.success(`Error watcher "${watcherName}" deleted.`);
+        // The credential is the project ingest key, which is untouched by this
+        // delete — it keeps authenticating. What breaks is watcher resolution.
+        logger.warning('Your ingest keys still authenticate. If this was the last enabled watcher on');
+        logger.warning('the project, reports now return 409 (no enabled error watcher configured).');
+    }
+    catch (error) {
+        handleWatcherApiError(error, serverUrl, { project, watcherId });
+        process.exit(1);
+    }
+}
+// ── Mode: print-setup ───────────────────────────────────────────────────────
+/**
+ * Re-print the `.env` block (with placeholders) and the signing snippet. Makes
+ * NO network call — the snippet is hard-coded and no secret is involved — so it
+ * works with the server unreachable and is safe to run and share.
+ */
+function printSetupOnly(config, options) {
+    const serverUrl = resolveServerUrl(config, options);
+    const webhookUrl = resolveWebhookUrl(serverUrl, config);
+    const watcherId = typeof options.printSetup === 'string' ? options.printSetup : undefined;
+    logger.section(watcherId ? `Error Watcher Setup: ${watcherId}` : 'Error Watcher Setup');
+    logger.info('No real credential values are shown — the CLI never holds one. The key and');
+    logger.info('secret below are placeholders; mint the real pair in the dashboard.');
+    printSetupInstructions(serverUrl, webhookUrl);
+}
+// ── Formatting helpers ──────────────────────────────────────────────────────
+/**
+ * One-line rendering of the watcher's `instructions`. Long guidance is elided
+ * rather than wrapped so the field stays one row in the detail block.
+ */
+export function summarizeInstructions(instructions, maxLen = 72) {
+    if (!instructions)
+        return '(none)';
+    const oneLine = instructions.replace(/\s+/g, ' ').trim();
+    if (oneLine.length <= maxLen)
+        return oneLine;
+    return `${oneLine.slice(0, maxLen - 1)}…`;
+}
+/** Humanize a duration in seconds: 300 → 5m, 3600 → 1h, 86400 → 24h, 604800 → 7d. */
+export function humanizeDuration(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return formatUnit(seconds / 60, 'm');
+    if (seconds < 604800)
+        return formatUnit(seconds / 3600, 'h');
+    return formatUnit(seconds / 86400, 'd');
+}
+function formatUnit(value, unit) {
+    return Number.isInteger(value) ? `${value}${unit}` : `${value.toFixed(1)}${unit}`;
+}
+/** Relative time such as "12m ago" for an ISO timestamp. */
+export function relativeTime(iso) {
+    const then = new Date(iso).getTime();
+    if (Number.isNaN(then))
+        return iso;
+    const diffSeconds = Math.max(0, Math.floor((Date.now() - then) / 1000));
+    if (diffSeconds < 60)
+        return `${diffSeconds}s ago`;
+    const minutes = Math.floor(diffSeconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
+/** Colour an event status: launched green, deduped dim, skipped_* yellow, failed red. */
+function colorStatus(status) {
+    if (status === 'launched')
+        return chalk.green(status);
+    if (status === 'deduped')
+        return chalk.dim(status);
+    if (status === 'failed')
+        return chalk.red(status);
+    if (status.startsWith('skipped_'))
+        return chalk.yellow(status);
+    return status;
+}
+// ── Error mapping ───────────────────────────────────────────────────────────
+/**
+ * Map server responses to actionable messages. NEVER echoes the Authorization
+ * header, the watcher token, or the secret — none of those are read from the
+ * error object, so no redaction pass is needed. Re-throws non-axios errors for
+ * the caller's outer handler.
+ */
+export function handleWatcherApiError(error, serverUrl, ctx = {}) {
+    if (!axios.isAxiosError(error)) {
+        throw error;
+    }
+    if (error.response) {
+        const status = error.response.status;
+        const data = (error.response.data ?? {});
+        switch (status) {
+            case 400:
+                logger.error(data.error || 'Bad request: invalid parameters.');
+                break;
+            case 401:
+                logger.error('Invalid or missing hula API key. Run "hula login".');
+                break;
+            case 402: {
+                logger.error(data.error ||
+                    'Error Watchers require Pro with PR credits — the same as every other launch path.');
+                const actionUrl = data.buyCreditsUrl || data.upgradeUrl;
+                if (actionUrl) {
+                    logger.info(`  Manage your plan or credits at ${actionUrl}.`);
+                }
+                break;
+            }
+            case 403:
+                logger.error(`You do not have access to ${ctx.project ?? 'this project'}.`);
+                break;
+            case 404:
+                if (ctx.watcherId) {
+                    logger.error(`Watcher ${ctx.watcherId} not found for ${ctx.project ?? 'this project'} (or this server may not support Error Watchers yet).`);
+                }
+                else {
+                    logger.error('No Error Watcher endpoint found — this server may not support Error Watchers yet.');
+                }
+                break;
+            case 409:
+                // The ingest webhook's 409. It means the credential authenticated but
+                // watcher resolution found nothing, so the fix is to create or enable a
+                // watcher — never to re-issue the key.
+                logger.error(data.error ||
+                    `No enabled Error Watcher is configured for ${ctx.project ?? 'this project'}.`);
+                logger.info('  Your ingest key is valid — the project just has no watcher to apply.');
+                logger.info('  Create one:  hula error-watcher --create --name api-prod');
+                logger.info('  Or re-enable an existing one:');
+                logger.info('               hula error-watcher --list');
+                logger.info('               hula error-watcher --update <id> --enabled true');
+                break;
+            case 500:
+                logger.error(`Server error: ${data.error || 'Internal server error'}`);
+                break;
+            default:
+                logger.error(`Request failed with status ${status}: ${data.error || 'unexpected error'}`);
+        }
+        return;
+    }
+    if (error.code === 'ECONNREFUSED') {
+        logger.error(`Cannot connect to server at ${serverUrl}`);
+        logger.info('Check --url or config.hulaProjectUrl.');
+    }
+    else if (error.code === 'ETIMEDOUT' || error.code === 'ECONNABORTED') {
+        logger.error(`Request to ${serverUrl} timed out.`);
+        logger.info('Check --url or config.hulaProjectUrl.');
+    }
+    else {
+        logger.error(`Network error contacting ${serverUrl}: ${error.message}`);
+        logger.info('Check --url or config.hulaProjectUrl.');
+    }
+}
+//# sourceMappingURL=errorWatcher.js.map