@nocville/npc 0.0.0-stage → 0.2.1

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,549 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { parseArgs, resolveConfig, stringFlag, numberFlag, boolFlag } from './core/config.js';
+import { Logger } from './core/logger.js';
+import { ensureSessionFilterTemplate, loadSessionFilter, sessionPublishDecision, } from './core/session-filter.js';
+// NPC modules are imported lazily per command: `claude-code hook` / `codex hook`
+// run on every tool call, so they must not pay for loading every NPC (and pngjs).
+const USAGE = `
+nocville-npc <command> [options]
+
+Quick start (AI coworkers):
+  nocville-npc setup                        Paste your agent key (hidden prompt),
+                                            then hook up installed coding agents
+                                            (whichever are installed)
+  nocville-npc setup --api-key=<agent key>   Same, non-interactive
+  nocville-npc uninstall                    Remove all Nocville hooks
+
+Config:
+  init [--api-key=<key>] [--api-url=<url>] [--map=<name>]
+                          Save credentials (prompts for the key if omitted) to ~/.config/nocville/config.json (0600)
+                          so no other command needs --api-key
+  doctor                  Check API connectivity and a test status push
+  sessions [--project=<dir>] [--name=<session name>]
+                          Show which AI sessions publish to your office
+                          (allow/deny lists in ~/.config/nocville/sessions.json)
+                          and test a folder (default: current) or session name
+
+AI coding agents (one NPC per session, named "Claude · <project>"):
+  claude-code setup       Install hooks into ~/.claude/settings.json
+  claude-code uninstall   Remove them
+  codex setup             Install hooks into ~/.codex/hooks.json (then trust
+                          them once with /hooks inside Codex)
+  codex uninstall         Remove them
+  gemini setup            Install hooks into ~/.gemini/settings.json
+  gemini uninstall        Remove them
+  cursor setup            Install native hooks into ~/.cursor/hooks.json
+  cursor uninstall        Remove them
+  codex watch             No-hooks fallback: follow ~/.codex/sessions logs
+    --idle-timeout=<min>  Despawn a session after this long quiet (default 30)
+    --include-exec        Also show non-interactive \`codex exec\` runs
+
+Monitoring NPC types:
+  system-monitor          Monitor CPU, memory, and disk usage
+  internet-connectivity   Monitor network connectivity
+  process-watcher         Watch for running processes
+  log-watcher             Watch log files for errors
+  receptionist            Greeter showing time + local weather
+  github-watcher          Call out new commits on a repo
+  web-page-watcher        Render a watched web page as a pixel-art TV
+
+Common Options:
+  --api-key=<key>         Team API key (or NOCVILLE_API_KEY env)
+  --api-url=<url>         Nocville API URL (or NOCVILLE_API_URL env).
+                          Default: https://nocville.com. For local dev use
+                          --api-url=http://localhost:3601
+  --service-id=<id>       Service ID (or NOCVILLE_SERVICE_ID env)
+  --name=<display name>   Friendly NPC banner name (or NOCVILLE_NAME env).
+                          Default: a per-NPC name (e.g. "System Monitor").
+  --map=<id-or-name>      Target map by id or name (or NOCVILLE_MAP env).
+                          Default: the team's default map.
+  --debug                 Enable debug logging
+  --help                  Show this help message
+
+System Monitor Options:
+  --poll-interval=<ms>    Poll interval in ms (default: 15000)
+  --disk-path=<path>      Disk path to monitor (default: /)
+  --cpu-warn=<n>          CPU warning threshold % (default: 75)
+  --cpu-crit=<n>          CPU critical threshold % (default: 90)
+  --mem-warn=<n>          Memory warning threshold % (default: 75)
+  --mem-crit=<n>          Memory critical threshold % (default: 90)
+  --disk-warn=<n>         Disk warning threshold % (default: 75)
+  --disk-crit=<n>         Disk critical threshold % (default: 90)
+
+Internet Connectivity Options:
+  --poll-interval=<ms>    Poll interval in ms (default: 30000)
+  --dns-hosts=<list>      Comma-separated DNS hosts (default: google.com,cloudflare.com)
+  --http-urls=<list>      Comma-separated HTTP URLs to check
+  --latency-hosts=<list>  Comma-separated hosts for latency checks
+  --slow-threshold=<ms>   Slow response threshold in ms (default: 1000)
+
+Process Watcher Options:
+  --poll-interval=<ms>    Poll interval in ms (default: 15000)
+  --processes=<list>      Comma-separated process names to watch
+  --cpu-warn=<n>          CPU warning threshold % (default: 80)
+  --mem-warn=<n>          Memory warning threshold MB (default: 500)
+
+Log Watcher Options:
+  --files=<list>          Comma-separated log file paths
+  --error-pattern=<regex> Error pattern (default: ERROR|FATAL)
+  --warning-pattern=<regex> Warning pattern (default: WARN)
+  --window=<seconds>      Sliding window in seconds (default: 300)
+  --error-warn=<n>        Error count for warning status (default: 5)
+  --error-crit=<n>        Error count for critical status (default: 20)
+  --report-interval=<ms>  Report interval in ms (default: 15000)
+
+Receptionist Options:
+  --poll-interval=<ms>    Clock tick in ms (default: 60000)
+  --lat=<n> --lon=<n>     Explicit coordinates for weather
+  --location=<name>       Place name to geocode (else IP geo)
+  --fahrenheit            Show temperature in °F (default: °C)
+
+GitHub Watcher Options:
+  --repo=<owner/name>     Repository to watch (required)
+  --branch=<name>         Branch to watch (default: repo default branch)
+  --token=<token>         GitHub token (or GITHUB_TOKEN env)
+  --poll-interval=<ms>    Poll interval in ms (default: 60000)
+
+Web Page Watcher Options:
+  --url=<url>             Page to watch (required)
+  --mode=<auto|screenshot|basic>  Render mode (default: auto)
+  --interval=<ms>         Poll interval in ms (default: 60000, floor 15000)
+  --viewport=<WxH>        Browser viewport (default: screen x 8)
+  --screen=<WxH>          TV pixel resolution (default: 160x120; e.g. 160x100)
+  --wait-until=<event>    Puppeteer waitUntil (default: networkidle2)
+  --chrome-path=<path>    Chrome executable (or CHROME_PATH env)
+  (needs puppeteer-core + Chrome for the pixel-art TV; falls back to basic)
+`.trim();
+async function main() {
+    const parsed = parseArgs(process.argv);
+    if (parsed.flags['version']) {
+        console.log(JSON.parse(readFileSync(join(dirname(realpathSync(process.argv[1])), '..', 'package.json'), 'utf8')).version);
+        return;
+    }
+    if (parsed.flags['help'] || parsed.flags['h']) {
+        console.log(USAGE);
+        process.exit(0);
+    }
+    if (!parsed.command) {
+        console.error('Error: NPC type required\n');
+        console.log(USAGE);
+        process.exit(1);
+    }
+    const config = resolveConfig(parsed.flags);
+    const logger = new Logger('cli', config.debug);
+    // Setup-style commands resolve the key: --api-key > env > saved > hidden prompt.
+    const isAgentSetup = ['claude-code', 'codex', 'gemini', 'cursor'].includes(parsed.command) &&
+        parsed.subcommand === 'setup' &&
+        !parsed.flags['uninstall'];
+    if (isAgentSetup || parsed.command === 'setup') {
+        if (parsed.command === 'setup') {
+            const { codexHome } = await import('./npcs/codex/defaults.js');
+            if (!existsSync(join(homedir(), '.claude')) &&
+                !existsSync(codexHome()) &&
+                !existsSync(join(homedir(), '.gemini')) &&
+                !existsSync(join(homedir(), '.cursor'))) {
+                console.error('Nothing to set up: install Claude Code, Codex, Gemini CLI or Cursor first.');
+                process.exitCode = 1;
+                return;
+            }
+        }
+        const key = await resolveSetupKey(parsed.flags);
+        if (key === null)
+            return;
+        if (key !== undefined)
+            parsed.flags['api-key'] = key;
+    }
+    // AI-agent integrations have their own config handling (hooks read the saved config).
+    if (parsed.command === 'claude-code') {
+        const { handleClaudeCodeCommand } = await import('./npcs/claude-code/index.js');
+        await handleClaudeCodeCommand({
+            subcommand: parsed.subcommand ?? 'hook',
+            config,
+            flags: parsed.flags,
+            args: parsed.args,
+        });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
+        return;
+    }
+    if (parsed.command === 'codex') {
+        const { handleCodexCommand } = await import('./npcs/codex/index.js');
+        await handleCodexCommand({
+            subcommand: parsed.subcommand ?? 'hook',
+            config,
+            flags: parsed.flags,
+            args: parsed.args,
+        });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
+        return;
+    }
+    if (parsed.command === 'gemini') {
+        const { handleGeminiCommand } = await import('./npcs/gemini/index.js');
+        await handleGeminiCommand({
+            subcommand: parsed.subcommand ?? 'hook',
+            config,
+            flags: parsed.flags,
+            args: parsed.args,
+        });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
+        return;
+    }
+    if (parsed.command === 'cursor') {
+        const { handleCursorCommand } = await import('./npcs/cursor/index.js');
+        await handleCursorCommand({
+            subcommand: parsed.subcommand ?? 'hook',
+            config,
+            flags: parsed.flags,
+            args: parsed.args,
+        });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
+        return;
+    }
+    if (parsed.command === 'init') {
+        await runInit(parsed.flags, config);
+        return;
+    }
+    if (parsed.command === 'setup') {
+        await runSetupAll(parsed.flags);
+        if (!process.exitCode)
+            announceSessionFilter();
+        return;
+    }
+    if (parsed.command === 'sessions') {
+        runSessionsCommand(parsed.flags);
+        return;
+    }
+    if (parsed.command === 'uninstall') {
+        const { uninstallHooks } = await import('./npcs/claude-code/index.js');
+        const { uninstallCodexHooks } = await import('./npcs/codex/index.js');
+        uninstallHooks();
+        uninstallCodexHooks();
+        const { uninstallGeminiHooks } = await import('./npcs/gemini/index.js');
+        uninstallGeminiHooks();
+        const { uninstallCursorHooks } = await import('./npcs/cursor/index.js');
+        uninstallCursorHooks();
+        return;
+    }
+    // Doctor checks connectivity; it works without an API key (push step is skipped).
+    if (parsed.command === 'doctor') {
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor(config);
+        return;
+    }
+    // All other NPC types require api-url and token
+    if (!config.apiKey) {
+        console.error('Error: no API key — run `nocville-npc init --api-key=<key>`, or pass --api-key / NOCVILLE_API_KEY');
+        process.exit(1);
+    }
+    switch (parsed.command) {
+        case 'system-monitor': {
+            if (!config.serviceId) {
+                config.serviceId = 'system-monitor';
+            }
+            const { SystemMonitorNPC } = await import('./npcs/system-monitor/index.js');
+            const npc = new SystemMonitorNPC({
+                ...config,
+                pollInterval: numberFlag(parsed.flags, 'poll-interval'),
+                diskPath: stringFlag(parsed.flags, 'disk-path'),
+                cpuThreshold: {
+                    warning: numberFlag(parsed.flags, 'cpu-warn') ?? 75,
+                    critical: numberFlag(parsed.flags, 'cpu-crit') ?? 90,
+                    direction: 'above',
+                },
+                memThreshold: {
+                    warning: numberFlag(parsed.flags, 'mem-warn') ?? 75,
+                    critical: numberFlag(parsed.flags, 'mem-crit') ?? 90,
+                    direction: 'above',
+                },
+                diskThreshold: {
+                    warning: numberFlag(parsed.flags, 'disk-warn') ?? 75,
+                    critical: numberFlag(parsed.flags, 'disk-crit') ?? 90,
+                    direction: 'above',
+                },
+            });
+            logger.info('Starting system-monitor NPC');
+            await npc.start();
+            break;
+        }
+        case 'internet-connectivity': {
+            if (!config.serviceId) {
+                config.serviceId = 'internet-connectivity';
+            }
+            const dnsHosts = stringFlag(parsed.flags, 'dns-hosts')?.split(',');
+            const httpUrls = stringFlag(parsed.flags, 'http-urls')?.split(',');
+            const latencyHostsRaw = stringFlag(parsed.flags, 'latency-hosts')?.split(',');
+            const latencyHosts = latencyHostsRaw?.map((h) => ({ host: h.trim(), port: 80 }));
+            const { InternetConnectivityNPC } = await import('./npcs/internet-connectivity/index.js');
+            const npc = new InternetConnectivityNPC({
+                ...config,
+                pollInterval: numberFlag(parsed.flags, 'poll-interval'),
+                dnsHosts,
+                httpUrls,
+                latencyHosts,
+                slowThreshold: numberFlag(parsed.flags, 'slow-threshold'),
+            });
+            logger.info('Starting internet-connectivity NPC');
+            await npc.start();
+            break;
+        }
+        case 'process-watcher': {
+            if (!config.serviceId) {
+                config.serviceId = 'process-watcher';
+            }
+            const processesStr = stringFlag(parsed.flags, 'processes');
+            if (!processesStr) {
+                console.error('Error: --processes is required (comma-separated list)');
+                process.exit(1);
+            }
+            const { ProcessWatcherNPC } = await import('./npcs/process-watcher/index.js');
+            const npc = new ProcessWatcherNPC({
+                ...config,
+                pollInterval: numberFlag(parsed.flags, 'poll-interval'),
+                processes: processesStr.split(','),
+                cpuWarn: numberFlag(parsed.flags, 'cpu-warn'),
+                memWarn: numberFlag(parsed.flags, 'mem-warn'),
+            });
+            logger.info('Starting process-watcher NPC');
+            await npc.start();
+            break;
+        }
+        case 'log-watcher': {
+            const filesStr = stringFlag(parsed.flags, 'files');
+            if (!filesStr) {
+                console.error('Error: --files is required (comma-separated list)');
+                process.exit(1);
+            }
+            if (!config.serviceId) {
+                config.serviceId = 'log-watcher';
+            }
+            const { LogWatcherNPC } = await import('./npcs/log-watcher/index.js');
+            const npc = new LogWatcherNPC({
+                ...config,
+                files: filesStr.split(','),
+                errorPattern: stringFlag(parsed.flags, 'error-pattern'),
+                warningPattern: stringFlag(parsed.flags, 'warning-pattern'),
+                windowSeconds: numberFlag(parsed.flags, 'window'),
+                errorWarn: numberFlag(parsed.flags, 'error-warn'),
+                errorCrit: numberFlag(parsed.flags, 'error-crit'),
+                reportInterval: numberFlag(parsed.flags, 'report-interval'),
+            });
+            logger.info('Starting log-watcher NPC');
+            await npc.start();
+            break;
+        }
+        case 'receptionist': {
+            if (!config.serviceId) {
+                config.serviceId = 'receptionist';
+            }
+            const { ReceptionistNPC } = await import('./npcs/receptionist/index.js');
+            const npc = new ReceptionistNPC({
+                ...config,
+                pollInterval: numberFlag(parsed.flags, 'poll-interval'),
+                lat: numberFlag(parsed.flags, 'lat'),
+                lon: numberFlag(parsed.flags, 'lon'),
+                location: stringFlag(parsed.flags, 'location'),
+                fahrenheit: boolFlag(parsed.flags, 'fahrenheit') ?? false,
+            });
+            logger.info('Starting receptionist NPC');
+            await npc.start();
+            break;
+        }
+        case 'github-watcher': {
+            const repo = stringFlag(parsed.flags, 'repo');
+            if (!repo) {
+                console.error('Error: --repo=<owner/name> is required');
+                process.exit(1);
+            }
+            if (!config.serviceId) {
+                const shortName = repo.split('/').pop() || repo;
+                config.serviceId = `github-${shortName.replace(/[^a-zA-Z0-9_-]/g, '-')}`.slice(0, 100);
+            }
+            const { GitHubWatcherNPC } = await import('./npcs/github-watcher/index.js');
+            const npc = new GitHubWatcherNPC({
+                ...config,
+                repo,
+                branch: stringFlag(parsed.flags, 'branch'),
+                token: stringFlag(parsed.flags, 'token') ?? process.env['GITHUB_TOKEN'],
+                pollInterval: numberFlag(parsed.flags, 'poll-interval'),
+            });
+            logger.info('Starting github-watcher NPC');
+            await npc.start();
+            break;
+        }
+        case 'web-page-watcher': {
+            const url = stringFlag(parsed.flags, 'url');
+            if (!url) {
+                console.error('Error: --url=<url> is required');
+                process.exit(1);
+            }
+            const { hostnameOf } = await import('./npcs/web-page-watcher/basic-mode.js');
+            const { parseDimensions } = await import('./npcs/web-page-watcher/defaults.js');
+            const { WebPageWatcherNPC } = await import('./npcs/web-page-watcher/index.js');
+            const parseWxH = (v) => v ? (parseDimensions(v) ?? undefined) : undefined;
+            if (!config.serviceId) {
+                config.serviceId = `webpage-${hostnameOf(url)}`
+                    .replace(/[^a-zA-Z0-9_.-]/g, '-')
+                    .slice(0, 100);
+            }
+            const modeFlag = stringFlag(parsed.flags, 'mode');
+            const mode = modeFlag === 'auto' || modeFlag === 'screenshot' || modeFlag === 'basic'
+                ? modeFlag
+                : undefined;
+            const viewport = parseWxH(stringFlag(parsed.flags, 'viewport'));
+            const screen = parseWxH(stringFlag(parsed.flags, 'screen'));
+            const npc = new WebPageWatcherNPC({
+                ...config,
+                url,
+                mode,
+                chromePath: stringFlag(parsed.flags, 'chrome-path'),
+                waitUntil: stringFlag(parsed.flags, 'wait-until'),
+                viewportWidth: viewport?.width,
+                viewportHeight: viewport?.height,
+                screenWidth: screen?.width,
+                screenHeight: screen?.height,
+                pollInterval: numberFlag(parsed.flags, 'interval') ?? numberFlag(parsed.flags, 'poll-interval'),
+            });
+            logger.info('Starting web-page-watcher NPC');
+            await npc.start();
+            break;
+        }
+        default:
+            console.error(`Error: Unknown NPC type "${parsed.command}"\n`);
+            console.log(USAGE);
+            process.exit(1);
+    }
+}
+async function runInit(flags, config) {
+    const { saveUserConfig, loadUserConfig, maskKey } = await import('./core/user-config.js');
+    let apiKey = stringFlag(flags, 'api-key');
+    const apiUrl = stringFlag(flags, 'api-url');
+    const map = stringFlag(flags, 'map');
+    if (!apiKey && !apiUrl && !map) {
+        const saved = loadUserConfig();
+        if (saved.apiKey && !process.env['NOCVILLE_API_KEY']?.trim()) {
+            console.log('Usage: nocville-npc init --api-key=<key> [--api-url=<url>] [--map=<name>]');
+            console.log(`Current: api ${saved.apiUrl ?? config.apiUrl}  key ${maskKey(saved.apiKey)}`);
+            return;
+        }
+        const { resolveApiKey } = await import('./core/api-key.js');
+        const resolved = await resolveApiKey({ flags, savedKey: undefined });
+        if (!resolved.ok) {
+            console.error(resolved.error);
+            process.exitCode = 1;
+            return;
+        }
+        apiKey = resolved.key;
+    }
+    const path = saveUserConfig({ apiKey, apiUrl, map });
+    const saved = loadUserConfig();
+    console.log(`✓ Saved ${path} (mode 0600)`);
+    console.log(`  API: ${saved.apiUrl ?? 'https://nocville.com'}  key: ${maskKey(saved.apiKey)}`);
+    console.log('  Next: nocville-npc setup   (hooks up installed coding agents)');
+}
+/**
+ * Resolve the API key for a setup-style command. Returns the key to save, or
+ * `undefined` when the already-saved key should be kept, or `null` (after
+ * printing an actionable error and setting a non-zero exit code) when none.
+ */
+async function resolveSetupKey(flags) {
+    const { resolveApiKey } = await import('./core/api-key.js');
+    const resolved = await resolveApiKey({ flags });
+    if (!resolved.ok) {
+        console.error(resolved.error);
+        process.exitCode = 1;
+        return null;
+    }
+    return resolved.source === 'saved' ? undefined : resolved.key;
+}
+/** `setup`: save credentials, then install Claude Code + Codex hooks where present. */
+/** After setup: make sure sessions.json exists and tell the user how to filter sessions. */
+function announceSessionFilter() {
+    const { path, created } = ensureSessionFilterTemplate();
+    console.log(`\n  Choose which sessions appear in your office: ${created ? 'created' : 'edit'} ${tildify(path)}\n` +
+        '  (allow/deny by project folder or session name; empty = all sessions publish).\n' +
+        '  Check the result with: npx @nocville/npc sessions');
+}
+function tildify(p) {
+    const home = homedir();
+    return p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+/** `nocville-npc sessions`: show the allow/deny rules and test a folder / session name. */
+function runSessionsCommand(flags) {
+    const { path, created } = ensureSessionFilterTemplate();
+    const filter = loadSessionFilter(path);
+    console.log(`Session filter: ${tildify(path)}${created ? ' (created an empty template)' : ''}`);
+    if (filter.error) {
+        console.log(`  ✗ ${filter.error}\n  Nothing publishes until the file is fixed.`);
+        process.exitCode = 1;
+        return;
+    }
+    const show = (label, list) => console.log(`  ${label.padEnd(16)} ${list.length ? list.map((p) => JSON.stringify(p)).join(', ') : '(none)'}`);
+    show('allow projects:', filter.allow.projects);
+    show('allow sessions:', filter.allow.sessions);
+    show('deny projects:', filter.deny.projects);
+    show('deny sessions:', filter.deny.sessions);
+    const projectDir = stringFlag(flags, 'project') ?? process.cwd();
+    const name = stringFlag(flags, 'name');
+    const verdict = sessionPublishDecision(filter, { projectDir, name });
+    const subject = `Sessions in ${tildify(projectDir)}${name ? ` named "${name}"` : ''}`;
+    console.log(`\n${verdict.publish ? '✓' : '✗'} ${subject} ${verdict.publish ? 'publish' : 'do NOT publish'} — ${verdict.reason}.`);
+}
+async function runSetupAll(flags) {
+    const { setupHooks } = await import('./npcs/claude-code/index.js');
+    const { setupCodexHooks } = await import('./npcs/codex/index.js');
+    const { codexHome } = await import('./npcs/codex/defaults.js');
+    const opts = {
+        apiUrl: stringFlag(flags, 'api-url') ?? process.env['NOCVILLE_API_URL'],
+        apiKey: stringFlag(flags, 'api-key') ?? process.env['NOCVILLE_API_KEY'],
+        map: stringFlag(flags, 'map'),
+        cliPath: process.argv[1],
+    };
+    let any = false;
+    if (existsSync(join(homedir(), '.claude'))) {
+        any = setupHooks(opts) || any;
+    }
+    else {
+        console.log('· Claude Code not found (~/.claude missing) — skipped');
+    }
+    if (existsSync(codexHome())) {
+        any = setupCodexHooks(opts) || any;
+    }
+    else {
+        console.log('· Codex not found (~/.codex missing) — skipped');
+    }
+    if (existsSync(join(homedir(), '.gemini'))) {
+        const { setupGeminiHooks } = await import('./npcs/gemini/index.js');
+        any = setupGeminiHooks(opts) || any;
+    }
+    else {
+        console.log('· Gemini CLI not found (~/.gemini missing) — skipped');
+    }
+    if (existsSync(join(homedir(), '.cursor'))) {
+        const { setupCursorHooks } = await import('./npcs/cursor/index.js');
+        any = setupCursorHooks(opts) || any;
+    }
+    else {
+        console.log('· Cursor not found (~/.cursor missing) — skipped');
+    }
+    if (!any) {
+        console.error('Nothing to set up: install Claude Code, Codex, Gemini CLI or Cursor first.');
+        process.exitCode = 1;
+    }
+}
+main().catch((err) => {
+    const parsed = parseArgs(process.argv);
+    if (['gemini', 'cursor'].includes(parsed.command ?? '') &&
+        (!parsed.subcommand || parsed.subcommand === 'hook')) {
+        process.stdout.write('{}\n');
+        return;
+    }
+    console.error('Fatal error:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/core/api-key.d.ts

@@ -0,0 +1,34 @@
+/**
+ * API-key resolution for the setup-style commands (`setup`, `init`,
+ * `claude-code setup`, `codex setup`): `--api-key` > `NOCVILLE_API_KEY` >
+ * the already-saved config > a hidden interactive prompt (TTY only) > error.
+ * The prompt lets users paste the key without it landing in shell history.
+ */
+export type ApiKeySource = 'flag' | 'env' | 'saved' | 'prompt';
+export interface ResolveApiKeyOptions {
+    flags: Record<string, string | boolean>;
+    env?: NodeJS.ProcessEnv;
+    /** Key from ~/.config/nocville/config.json (default: read it). */
+    savedKey?: string;
+    /** Whether stdin is interactive (default: process.stdin.isTTY). */
+    isTTY?: boolean;
+    /** Prompt implementation (default: hidden readline prompt). Injectable for tests. */
+    prompt?: (question: string) => Promise<string>;
+}
+export type ResolveApiKeyResult = {
+    ok: true;
+    key: string;
+    source: ApiKeySource;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const API_KEY_PROMPT = "Paste your Nocville API key: ";
+export declare const MISSING_API_KEY_ERROR: string;
+export declare function resolveApiKey(opts: ResolveApiKeyOptions): Promise<ResolveApiKeyResult>;
+/**
+ * Ask a question on the terminal without echoing the answer. The question is
+ * written directly; readline's own echo goes to a muted stream.
+ */
+export declare function promptHidden(question: string, input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<string>;
+//# sourceMappingURL=api-key.d.ts.map

package/dist/core/api-key.js

@@ -0,0 +1,64 @@
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { stringFlag } from './config.js';
+import { loadUserConfig } from './user-config.js';
+export const API_KEY_PROMPT = 'Paste your Nocville API key: ';
+export const MISSING_API_KEY_ERROR = 'Error: no API key. Pass --api-key=<agent key>, set NOCVILLE_API_KEY, or run this ' +
+    'command in an interactive terminal to paste the key (input is hidden). ' +
+    'Your team admin can generate a key in Nocville team settings.';
+export async function resolveApiKey(opts) {
+    const fromFlag = stringFlag(opts.flags, 'api-key')?.trim();
+    if (fromFlag)
+        return { ok: true, key: fromFlag, source: 'flag' };
+    const fromEnv = (opts.env ?? process.env)['NOCVILLE_API_KEY']?.trim();
+    if (fromEnv)
+        return { ok: true, key: fromEnv, source: 'env' };
+    const saved = 'savedKey' in opts ? opts.savedKey : loadUserConfig().apiKey;
+    if (saved)
+        return { ok: true, key: saved, source: 'saved' };
+    const isTTY = opts.isTTY ?? Boolean(process.stdin.isTTY);
+    if (!isTTY)
+        return { ok: false, error: MISSING_API_KEY_ERROR };
+    let answer;
+    try {
+        answer = (await (opts.prompt ?? promptHidden)(API_KEY_PROMPT)).trim();
+    }
+    catch {
+        return { ok: false, error: 'Cancelled — no API key entered.' };
+    }
+    if (!answer)
+        return { ok: false, error: MISSING_API_KEY_ERROR };
+    return { ok: true, key: answer, source: 'prompt' };
+}
+/**
+ * Ask a question on the terminal without echoing the answer. The question is
+ * written directly; readline's own echo goes to a muted stream.
+ */
+export function promptHidden(question, input = process.stdin, output = process.stdout) {
+    return new Promise((resolve, reject) => {
+        const muted = new Writable({
+            write(_chunk, _enc, cb) {
+                cb();
+            },
+        });
+        output.write(question);
+        const rl = createInterface({ input, output: muted, terminal: true });
+        let done = false;
+        rl.on('line', (line) => {
+            done = true;
+            rl.close();
+            output.write('\n');
+            resolve(line);
+        });
+        rl.on('SIGINT', () => {
+            rl.close();
+        });
+        rl.on('close', () => {
+            if (!done) {
+                output.write('\n');
+                reject(new Error('cancelled'));
+            }
+        });
+    });
+}
+//# sourceMappingURL=api-key.js.map