@trillboards/cli 0.1.0 → 0.1.3

package/dist/capability.js

@@ -0,0 +1,67 @@
+/**
+ * Terminal surface-capability detection for the `trillboards code` wrapper.
+ *
+ * The render surface available during the agent's dead-time depends on the host
+ * terminal. We map the environment to four capabilities and hand them to the
+ * server as `?surface_capabilities=…` so it returns the richest creative the
+ * surface can actually show (the server's `selectCreativeFormat`).
+ *
+ *   text    — every TTY (an OSC-8 sponsor line)
+ *   image   — inline graphics (Kitty / iTerm2 / Sixel; incl. VS Code's terminal for STATIC images)
+ *   video   — real in-terminal video via `mpv --vo=kitty` (Kitty/Ghostty/iTerm2/WezTerm) — NOT VS Code/Cursor
+ *   webview — we can open an external browser/PiP for an IMA/AdX video (the Leg-A fallback)
+ *
+ * Pure + env-injectable so it is fully unit-tested.
+ */
+/** Terminals where `mpv --vo=kitty` (or iTerm2 inline) plays real video well. */
+const VIDEO_TERM_PROGRAMS = new Set(['iterm.app', 'wezterm', 'ghostty', 'rio', 'konsole']);
+/** Terminals that show inline images but NOT smooth video (static only). */
+const IMAGE_ONLY_TERM_PROGRAMS = new Set(['vscode', 'cursor']);
+function lower(v) {
+    return (v ?? '').trim().toLowerCase();
+}
+/**
+ * Detect what the host terminal can render, from the environment alone (no
+ * round-trip probe — that lives in the wrapper which can do the Kitty `a=q` query
+ * for a runtime confirm). `env` is injected so tests cover the matrix.
+ */
+export function detectSurfaceCapabilities(env = process.env) {
+    const termProgram = lower(env.TERM_PROGRAM);
+    const term = lower(env.TERM);
+    // Kitty advertises itself via TERM=xterm-kitty (not TERM_PROGRAM); Ghostty/cmux
+    // set TERM_PROGRAM=ghostty. iTerm2/WezTerm set TERM_PROGRAM.
+    const isKitty = term.includes('kitty') || Boolean(env.KITTY_WINDOW_ID);
+    const isVideoTerm = isKitty || VIDEO_TERM_PROGRAMS.has(termProgram);
+    const isImageOnlyTerm = IMAGE_ONLY_TERM_PROGRAMS.has(termProgram);
+    // Sixel-capable hosts (xterm/mlterm/foot/Windows Terminal) → static images.
+    const isSixel = term.includes('sixel') || term.includes('foot') || term.includes('mlterm');
+    const imageCapableTerm = isVideoTerm || isImageOnlyTerm || isSixel;
+    // The wrapper's in-terminal render surface is a tmux split pane. Without tmux it
+    // can only spawn an mpv window (video) or open a browser (webview) — there is no
+    // clean way to draw text/an image beside the agent's TUI. So we only advertise
+    // text/image when we actually have a renderer (a tmux split); outside tmux the
+    // shipped `ads hook` covers in-place text.
+    const inTmux = Boolean(env.TMUX);
+    return {
+        text: inTmux,
+        image: imageCapableTerm && inTmux,
+        // video renders either in a tmux split (in-terminal) or a spawned mpv window.
+        video: isVideoTerm,
+        // A browser is essentially always reachable (open/xdg-open/start) — this is the
+        // surface AdX video uses where the terminal can't render it natively.
+        webview: true,
+    };
+}
+/** Serialize for the `?surface_capabilities=` query param the server's selector reads. */
+export function capabilitiesToParam(caps) {
+    const out = [];
+    if (caps.text)
+        out.push('text');
+    if (caps.image)
+        out.push('image');
+    if (caps.video)
+        out.push('video');
+    if (caps.webview)
+        out.push('webview');
+    return out.join(',');
+}

package/dist/claude-settings.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Claude Code settings.json hook merge — install/remove the Trillboards dead-time
+ * hook without clobbering the developer's own hooks.
+ *
+ * Claude Code reads `$CLAUDE_CONFIG_DIR/settings.json` (default `~/.claude`) and
+ * hot-reloads it (no restart). A hook lives under
+ *   settings.hooks.<EventName> = [ { matcher?, hooks: [ {type:"command", command} ] } ]
+ * We install ONE entry on `UserPromptSubmit` (fires when the dev submits a prompt,
+ * i.e. the agent's thinking/dead-time begins) whose command is `trillboards ads hook`.
+ * Detection is by the command substring marker so add/remove stay idempotent and
+ * never touch the developer's other entries.
+ */
+/** Lifecycle event we attach to — prompt submit == agent dead-time begins. */
+export declare const CLAUDE_HOOK_EVENT = "UserPromptSubmit";
+/** The command Claude Code invokes for each dead-time tick. */
+export declare const HOOK_COMMAND = "trillboards ads hook";
+/** Substring that uniquely identifies OUR hook entries (for idempotent add/remove). */
+export declare const HOOK_COMMAND_MARKER = "ads hook";
+/** Per-tick timeout (s). The hook fails open well under this; on timeout the prompt proceeds. */
+export declare const HOOK_TIMEOUT_SECONDS = 5;
+export interface ClaudeHookCommand {
+    type: 'command';
+    command: string;
+    timeout?: number;
+    [k: string]: unknown;
+}
+export interface ClaudeHookMatcher {
+    matcher?: string;
+    hooks: ClaudeHookCommand[];
+    [k: string]: unknown;
+}
+export interface ClaudeSettings {
+    hooks?: Record<string, ClaudeHookMatcher[]>;
+    [k: string]: unknown;
+}
+/** Directory Claude Code reads settings from (CLAUDE_CONFIG_DIR override, else ~/.claude). */
+export declare function claudeSettingsDir(): string;
+export declare function claudeSettingsPath(): string;
+export declare function readClaudeSettings(): ClaudeSettings;
+export interface ClaudeSettingsLoad {
+    settings: ClaudeSettings;
+    /** True when the file EXISTS but is not valid JSON — callers must NOT overwrite it. */
+    malformed: boolean;
+}
+/**
+ * Load settings for an EDIT (enable/disable). Unlike readClaudeSettings (best-effort,
+ * returns {} for both missing and malformed), this distinguishes a missing file
+ * (safe to create) from a malformed one (must NOT be clobbered — overwriting it would
+ * delete the developer's real settings).
+ */
+export declare function loadClaudeSettingsForEdit(): ClaudeSettingsLoad;
+export declare function writeClaudeSettings(settings: ClaudeSettings): void;
+export declare function hasTrillboardsHook(settings: ClaudeSettings): boolean;
+/**
+ * Return NEW settings with our `UserPromptSubmit` hook present exactly once.
+ * Preserves every other event AND any developer-owned UserPromptSubmit matchers.
+ * Does not mutate the input.
+ */
+export declare function addTrillboardsHook(settings: ClaudeSettings, command?: string): ClaudeSettings;
+/**
+ * Return NEW settings with our hook removed from every event, pruning any matcher
+ * or event that becomes empty. Leaves developer-owned entries untouched.
+ */
+export declare function removeTrillboardsHook(settings: ClaudeSettings): ClaudeSettings;

package/dist/claude-settings.js

@@ -0,0 +1,126 @@
+/**
+ * Claude Code settings.json hook merge — install/remove the Trillboards dead-time
+ * hook without clobbering the developer's own hooks.
+ *
+ * Claude Code reads `$CLAUDE_CONFIG_DIR/settings.json` (default `~/.claude`) and
+ * hot-reloads it (no restart). A hook lives under
+ *   settings.hooks.<EventName> = [ { matcher?, hooks: [ {type:"command", command} ] } ]
+ * We install ONE entry on `UserPromptSubmit` (fires when the dev submits a prompt,
+ * i.e. the agent's thinking/dead-time begins) whose command is `trillboards ads hook`.
+ * Detection is by the command substring marker so add/remove stay idempotent and
+ * never touch the developer's other entries.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Lifecycle event we attach to — prompt submit == agent dead-time begins. */
+export const CLAUDE_HOOK_EVENT = 'UserPromptSubmit';
+/** The command Claude Code invokes for each dead-time tick. */
+export const HOOK_COMMAND = 'trillboards ads hook';
+/** Substring that uniquely identifies OUR hook entries (for idempotent add/remove). */
+export const HOOK_COMMAND_MARKER = 'ads hook';
+/** Per-tick timeout (s). The hook fails open well under this; on timeout the prompt proceeds. */
+export const HOOK_TIMEOUT_SECONDS = 5;
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/** Directory Claude Code reads settings from (CLAUDE_CONFIG_DIR override, else ~/.claude). */
+export function claudeSettingsDir() {
+    const override = process.env.CLAUDE_CONFIG_DIR;
+    if (override && override.trim())
+        return override;
+    return join(homedir(), '.claude');
+}
+export function claudeSettingsPath() {
+    return join(claudeSettingsDir(), 'settings.json');
+}
+export function readClaudeSettings() {
+    try {
+        const file = claudeSettingsPath();
+        if (!existsSync(file))
+            return {};
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        // A malformed settings.json is the dev's file — never overwrite blindly.
+        return {};
+    }
+}
+/**
+ * Load settings for an EDIT (enable/disable). Unlike readClaudeSettings (best-effort,
+ * returns {} for both missing and malformed), this distinguishes a missing file
+ * (safe to create) from a malformed one (must NOT be clobbered — overwriting it would
+ * delete the developer's real settings).
+ */
+export function loadClaudeSettingsForEdit() {
+    const file = claudeSettingsPath();
+    if (!existsSync(file))
+        return { settings: {}, malformed: false };
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        return { settings: parsed && typeof parsed === 'object' ? parsed : {}, malformed: false };
+    }
+    catch {
+        return { settings: {}, malformed: true };
+    }
+}
+export function writeClaudeSettings(settings) {
+    const file = claudeSettingsPath();
+    const dir = dirname(file);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(file, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
+function isOurCommand(h) {
+    return typeof h.command === 'string' && h.command.includes(HOOK_COMMAND_MARKER);
+}
+function isOurMatcher(m) {
+    return Array.isArray(m.hooks) && m.hooks.some(isOurCommand);
+}
+export function hasTrillboardsHook(settings) {
+    const events = settings.hooks;
+    if (!events)
+        return false;
+    return Object.values(events).some((list) => Array.isArray(list) && list.some(isOurMatcher));
+}
+/**
+ * Return NEW settings with our `UserPromptSubmit` hook present exactly once.
+ * Preserves every other event AND any developer-owned UserPromptSubmit matchers.
+ * Does not mutate the input.
+ */
+export function addTrillboardsHook(settings, command = HOOK_COMMAND) {
+    const next = clone(settings);
+    if (!next.hooks || typeof next.hooks !== 'object')
+        next.hooks = {};
+    const list = Array.isArray(next.hooks[CLAUDE_HOOK_EVENT]) ? next.hooks[CLAUDE_HOOK_EVENT] : [];
+    next.hooks[CLAUDE_HOOK_EVENT] = list;
+    if (list.some(isOurMatcher))
+        return next; // already installed — idempotent
+    list.push({ hooks: [{ type: 'command', command, timeout: HOOK_TIMEOUT_SECONDS }] });
+    return next;
+}
+/**
+ * Return NEW settings with our hook removed from every event, pruning any matcher
+ * or event that becomes empty. Leaves developer-owned entries untouched.
+ */
+export function removeTrillboardsHook(settings) {
+    const next = clone(settings);
+    if (!next.hooks || typeof next.hooks !== 'object')
+        return next;
+    for (const event of Object.keys(next.hooks)) {
+        const list = next.hooks[event];
+        if (!Array.isArray(list))
+            continue;
+        const pruned = list
+            .map((m) => (Array.isArray(m.hooks) ? { ...m, hooks: m.hooks.filter((h) => !isOurCommand(h)) } : m))
+            .filter((m) => !Array.isArray(m.hooks) || m.hooks.length > 0);
+        if (pruned.length > 0)
+            next.hooks[event] = pruned;
+        else
+            delete next.hooks[event];
+    }
+    if (Object.keys(next.hooks).length === 0)
+        delete next.hooks;
+    return next;
+}

package/dist/commands/ads/disable.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../../base-command.js';
+/**
+ * Opt-out: remove the Claude Code dead-time hook. Leaves the developer's other
+ * hooks untouched. Idempotent.
+ */
+export default class AdsDisable extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/ads/disable.js

@@ -0,0 +1,25 @@
+import { BaseCommand } from '../../base-command.js';
+import { claudeSettingsPath, hasTrillboardsHook, loadClaudeSettingsForEdit, removeTrillboardsHook, writeClaudeSettings, } from '../../claude-settings.js';
+import { colorize } from '../../format-helpers.js';
+/**
+ * Opt-out: remove the Claude Code dead-time hook. Leaves the developer's other
+ * hooks untouched. Idempotent.
+ */
+export default class AdsDisable extends BaseCommand {
+    static description = 'Turn off the in-place sponsored lines (removes the Claude Code dead-time hook).';
+    static examples = ['<%= config.bin %> ads disable'];
+    async run() {
+        const { flags } = await this.parse(AdsDisable);
+        this.setParsedFlags(flags);
+        const { settings, malformed } = loadClaudeSettingsForEdit();
+        if (malformed) {
+            this.error(`${claudeSettingsPath()} is not valid JSON — fix it first. Refusing to modify your Claude Code settings.`, { exit: 1 });
+        }
+        if (!hasTrillboardsHook(settings)) {
+            this.log(`Not enabled — no Trillboards hook found in ${claudeSettingsPath()}.`);
+            return;
+        }
+        writeClaudeSettings(removeTrillboardsHook(settings));
+        this.log(`${colorize('In-place agent ads disabled.', 'green')} The Claude Code dead-time hook was removed.`);
+    }
+}

package/dist/commands/ads/enable.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../base-command.js';
+/**
+ * Opt-in: install the Claude Code dead-time hook so a single sponsored line shows
+ * in-place while the agent thinks — no browser, no video player. Idempotent;
+ * preserves the developer's other hooks. Reverse with `ads disable`.
+ */
+export default class AdsEnable extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/ads/enable.js

@@ -0,0 +1,32 @@
+import { BaseCommand } from '../../base-command.js';
+import { HOOK_COMMAND, addTrillboardsHook, claudeSettingsPath, hasTrillboardsHook, loadClaudeSettingsForEdit, writeClaudeSettings, } from '../../claude-settings.js';
+import { colorize } from '../../format-helpers.js';
+/**
+ * Opt-in: install the Claude Code dead-time hook so a single sponsored line shows
+ * in-place while the agent thinks — no browser, no video player. Idempotent;
+ * preserves the developer's other hooks. Reverse with `ads disable`.
+ */
+export default class AdsEnable extends BaseCommand {
+    static description = 'Turn on in-place sponsored lines in Claude Code (installs the dead-time hook). Opt-in; undo with `ads disable`.';
+    static examples = ['<%= config.bin %> ads enable'];
+    async run() {
+        const { flags } = await this.parse(AdsEnable);
+        this.setParsedFlags(flags);
+        const { settings, malformed } = loadClaudeSettingsForEdit();
+        if (malformed) {
+            this.error(`${claudeSettingsPath()} is not valid JSON — fix it first. Refusing to overwrite your Claude Code settings.`, { exit: 1 });
+        }
+        if (hasTrillboardsHook(settings)) {
+            this.log(`${colorize('Already enabled', 'green')} — the Trillboards dead-time hook is installed in ${claudeSettingsPath()}.`);
+            return;
+        }
+        writeClaudeSettings(addTrillboardsHook(settings, HOOK_COMMAND));
+        this.log(colorize('In-place agent ads enabled.', 'green'));
+        this.log('');
+        this.log(`Added a Claude Code UserPromptSubmit hook to ${claudeSettingsPath()} (hot-reloads, no restart).`);
+        this.log('While your agent is thinking, a single sponsored line now appears in-place — no browser, no player.');
+        this.log('');
+        this.log(colorize('First register this machine to earn:  trillboards ads start --once', 'dim'));
+        this.log(colorize('Turn it off anytime:                  trillboards ads disable', 'dim'));
+    }
+}

package/dist/commands/ads/hook.d.ts

@@ -0,0 +1,16 @@
+import { Command } from '@oclif/core';
+/**
+ * Internal handler invoked by Claude Code's `UserPromptSubmit` hook (NOT by humans
+ * — hidden from help). On each prompt submit (the agent's dead-time begins) it may
+ * print `{"systemMessage": "<sponsor line>"}` to stdout, which Claude Code renders
+ * to the developer in-place. Prints nothing when there's no ad to show.
+ *
+ * Contract: this must NEVER block or break the prompt. It always exits 0, never
+ * throws, and only emits JSON when there is genuinely something to show.
+ */
+export default class AdsHook extends Command {
+    static description: string;
+    static hidden: boolean;
+    static strict: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/ads/hook.js

@@ -0,0 +1,90 @@
+import { Command } from '@oclif/core';
+import { fetchVirtualScreenTextAd, reportTextAdEvent } from '../../ads-client.js';
+import { agentAdIntervalMs, runAgentHook } from '../../agent-hook.js';
+import { readConfig, updateConfig } from '../../config.js';
+/** Tight bound on the post-render telemetry so it never delays the hook near Claude's timeout. */
+const TELEMETRY_TIMEOUT_MS = 1200;
+/**
+ * Internal handler invoked by Claude Code's `UserPromptSubmit` hook (NOT by humans
+ * — hidden from help). On each prompt submit (the agent's dead-time begins) it may
+ * print `{"systemMessage": "<sponsor line>"}` to stdout, which Claude Code renders
+ * to the developer in-place. Prints nothing when there's no ad to show.
+ *
+ * Contract: this must NEVER block or break the prompt. It always exits 0, never
+ * throws, and only emits JSON when there is genuinely something to show.
+ */
+export default class AdsHook extends Command {
+    static description = 'Internal: Claude Code dead-time hook handler (renders an in-place sponsor line).';
+    static hidden = true;
+    // Tolerate any args/flags Claude Code might pass; the event payload is on stdin.
+    static strict = false;
+    async run() {
+        // Drain stdin (Claude Code pipes the hook event JSON). We don't need its
+        // contents, but reading prevents a broken pipe on the caller's side.
+        await drainStdin(500);
+        let result = {};
+        let baseUrl = 'https://api.trillboards.com';
+        try {
+            const cfg = readConfig();
+            baseUrl = process.env.TRILLBOARDS_BASE_URL || cfg.base_url || 'https://api.trillboards.com';
+            result = await runAgentHook({
+                now: Date.now(),
+                screenId: cfg.screen_id ?? null,
+                deviceId: cfg.device_id ?? null,
+                baseUrl,
+                lastShownAt: cfg.agent_hook_last_shown_at,
+                intervalMs: agentAdIntervalMs(),
+                fetchTextAd: (b, s) => fetchVirtualScreenTextAd(b, s),
+                markShown: (now) => updateConfig({ agent_hook_last_shown_at: now }),
+            });
+        }
+        catch {
+            result = {}; // fail open
+        }
+        // Render FIRST: emit the sponsor line before any telemetry so a slow event
+        // endpoint can never hold it past Claude Code's hook timeout. Empty stdout =
+        // no-op for the hook.
+        if (result.systemMessage) {
+            process.stdout.write(JSON.stringify({ systemMessage: result.systemMessage }));
+        }
+        // Best-effort, tightly-bounded, non-billable telemetry. Never throws/blocks.
+        if (result.report) {
+            try {
+                await reportTextAdEvent(baseUrl, result.report, TELEMETRY_TIMEOUT_MS);
+            }
+            catch {
+                // ignore — telemetry must never affect the prompt
+            }
+        }
+    }
+}
+/** Read+discard stdin, resolving on end/error or after a short fallback timeout. */
+function drainStdin(timeoutMs) {
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            resolve();
+        };
+        try {
+            const stdin = process.stdin;
+            if (stdin.isTTY) {
+                finish();
+                return;
+            }
+            stdin.on('data', () => {
+                /* discard */
+            });
+            stdin.on('end', finish);
+            stdin.on('error', finish);
+            stdin.resume();
+        }
+        catch {
+            finish();
+            return;
+        }
+        setTimeout(finish, timeoutMs);
+    });
+}

package/dist/commands/ads/login.d.ts

@@ -0,0 +1,21 @@
+import { BaseCommand } from '../../base-command.js';
+/**
+ * `trillboards ads login` — authenticate as the DEVELOPER (Trillboards user) to
+ * rent agent dead-time. Stores a user JWT pair (user_token + user_refresh_token),
+ * which is distinct from the partner `api_key` used by the other commands.
+ */
+export default class AdsLogin extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        email: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        password: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    private promptLine;
+    /**
+     * Prompt for a secret without echoing it. Falls back to a plain prompt if the
+     * stream isn't a TTY. The token/password is never logged.
+     */
+    private promptHidden;
+}

package/dist/commands/ads/login.js

@@ -0,0 +1,108 @@
+import { Flags } from '@oclif/core';
+import * as readline from 'node:readline';
+import { BaseCommand } from '../../base-command.js';
+import { getConfigPath, updateConfig } from '../../config.js';
+import { colorize } from '../../format-helpers.js';
+import { TrillboardsApiError } from '../../http.js';
+import { loginUser, persistTokens } from '../../user-auth.js';
+/**
+ * `trillboards ads login` — authenticate as the DEVELOPER (Trillboards user) to
+ * rent agent dead-time. Stores a user JWT pair (user_token + user_refresh_token),
+ * which is distinct from the partner `api_key` used by the other commands.
+ */
+export default class AdsLogin extends BaseCommand {
+    static description = 'Log in to the agent-ads program with your Trillboards account (email + password)';
+    static examples = [
+        '<%= config.bin %> ads login',
+        '<%= config.bin %> ads login --email you@example.com',
+        'TRILLBOARDS_USER_TOKEN=<jwt> <%= config.bin %> ads login',
+    ];
+    static flags = {
+        email: Flags.string({
+            description: 'Account email (prompts if omitted)',
+        }),
+        password: Flags.string({
+            description: 'Account password (prompts hidden if omitted; avoid passing on the command line)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AdsLogin);
+        this.setParsedFlags(flags);
+        const baseUrl = this.getBaseUrl();
+        // Headless hatch: a pre-minted JWT pasted via env. We can't refresh it (no
+        // refresh token), but it lets CI / headless installs authenticate.
+        const envToken = process.env.TRILLBOARDS_USER_TOKEN;
+        if (envToken && envToken.trim()) {
+            updateConfig({ user_token: envToken.trim(), base_url: baseUrl });
+            this.log(`Saved user token from TRILLBOARDS_USER_TOKEN. Config: ${getConfigPath()}`);
+            this.log(colorize('Note: env tokens are not auto-refreshed. Run `ads login` with email+password for a renewable session.', 'dim'));
+            return;
+        }
+        const email = flags.email || (await this.promptLine('Email: '));
+        if (!email) {
+            this.error('No email provided. Pass --email or set TRILLBOARDS_USER_TOKEN.', { exit: 1 });
+        }
+        const password = flags.password || (await this.promptHidden('Password: '));
+        if (!password) {
+            this.error('No password provided.', { exit: 1 });
+        }
+        this.log('Signing in...');
+        let result;
+        try {
+            result = await loginUser(baseUrl, email, password);
+        }
+        catch (error) {
+            if (error instanceof TrillboardsApiError) {
+                if (error.statusCode === 401)
+                    this.error('Invalid email or password.', { exit: 1 });
+                if (error.statusCode === 404)
+                    this.error('No account found for that email.', { exit: 1 });
+                this.error(`Login failed: ${error.message}`, { exit: 1 });
+            }
+            throw error;
+        }
+        persistTokens(result);
+        updateConfig({ base_url: baseUrl, user_email: email });
+        this.log(colorize(`Logged in as ${email}.`, 'green'));
+        this.log(`Session saved to ${getConfigPath()}`);
+        this.log(colorize('Next: run `trillboards ads start` to rent your agent dead-time.', 'dim'));
+    }
+    promptLine(prompt) {
+        if (!process.stdin.isTTY)
+            return Promise.resolve('');
+        return new Promise((resolve) => {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+            rl.question(prompt, (answer) => {
+                rl.close();
+                resolve(answer.trim());
+            });
+        });
+    }
+    /**
+     * Prompt for a secret without echoing it. Falls back to a plain prompt if the
+     * stream isn't a TTY. The token/password is never logged.
+     */
+    promptHidden(prompt) {
+        if (!process.stdin.isTTY)
+            return Promise.resolve('');
+        return new Promise((resolve) => {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+            const rlAny = rl;
+            // Mask everything after the prompt is written.
+            rlAny._writeToOutput = (stringToWrite) => {
+                if (stringToWrite.includes(prompt)) {
+                    rlAny.output?.write(prompt);
+                }
+                else if (stringToWrite === '\n' || stringToWrite === '\r\n') {
+                    rlAny.output?.write(stringToWrite);
+                }
+                // swallow echoed characters
+            };
+            rl.question(prompt, (answer) => {
+                rl.close();
+                process.stderr.write('\n');
+                resolve(answer.trim());
+            });
+        });
+    }
+}

package/dist/commands/ads/start.d.ts

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../../base-command.js';
+export default class AdsStart extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        once: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        simulate: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        interval: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    private shuttingDown;
+    run(): Promise<void>;
+    static sleep(ms: number): Promise<void>;
+    private heartbeat;
+    /**
+     * One dead-time fill: fetch the web VAST tag, print the sanctioned text ad with
+     * an OSC-8 link to the billable hosted player, and fire the text-ad impression.
+     */
+    private serveOneAd;
+}