@aitherium/shell-cli 1.11.1 → 1.12.1

package/dist/client.d.ts

@@ -96,6 +96,16 @@ export declare class GenesisClient {
         effort?: number;
     }): Promise<any>;
     getLogs(limit?: number, level?: string, service?: string): Promise<any>;
+    /** List all expeditions (unified chat jobs, promoted jobs, real expeditions). */
+    listExpeditions(): Promise<any>;
+    /** Get expedition status summary. */
+    getExpeditionStatus(id: string): Promise<any>;
+    /** Get expedition tasks. */
+    getExpeditionTasks(id: string): Promise<any>;
+    /** Steer an expedition with a message (append or hint). */
+    steerExpedition(id: string, message: string, action?: 'append' | 'hint'): Promise<any>;
+    /** Stream SSE events from an expedition. */
+    streamExpeditionEvents(id: string): AsyncGenerator<SSEEvent>;
     getLLMStatus(): Promise<any>;
     /** Resolve the MicroScheduler base URL the same way getLLMStatus does. */
     private _msCandidates;

package/dist/client.js

@@ -305,6 +305,49 @@ export class GenesisClient {
             params.set('service', service);
         return this.get(`/chronicle/logs?${params}`);
     }
+    /* ── Cloud Expeditions (durable jobs) ─────────────────────── */
+    // NOTE: use getDetailed (NOT get) — get() collapses any error to `null`, which
+    // is indistinguishable from "no expeditions". getDetailed preserves {error} so
+    // the REPL can show a real diagnostic (genesis down / 404) vs an empty list.
+    /** List all expeditions (unified chat jobs, promoted jobs, real expeditions). */
+    async listExpeditions() {
+        return this.getDetailed('/expedition/list');
+    }
+    /** Get expedition status summary. */
+    async getExpeditionStatus(id) {
+        return this.getDetailed(`/expedition/${id}/status`);
+    }
+    /** Get expedition tasks. */
+    async getExpeditionTasks(id) {
+        return this.getDetailed(`/expedition/${id}/tasks`);
+    }
+    /** Steer an expedition with a message (append or hint). */
+    async steerExpedition(id, message, action = 'append') {
+        return this.post(`/expedition/${id}/steer`, { message, action });
+    }
+    /** Stream SSE events from an expedition. */
+    async *streamExpeditionEvents(id) {
+        try {
+            const r = await fetch(`${this.baseUrl}/expedition/${id}/stream`, {
+                headers: { 'X-Caller-Type': 'PLATFORM', ...this.authHeaders() },
+                signal: AbortSignal.timeout(600_000), // 10 min timeout for watching
+            });
+            if (!r.ok) {
+                yield {
+                    type: 'error',
+                    data: { type: 'error', error: `HTTP ${r.status}` },
+                };
+                return;
+            }
+            yield* this.readSSE(r);
+        }
+        catch (err) {
+            yield {
+                type: 'error',
+                data: { type: 'error', error: err?.message || 'Stream failed' },
+            };
+        }
+    }
     async getLLMStatus() {
         try {
             const candidates = [process.env.AITHER_LLM_URL, 'https://localhost:8150', 'http://localhost:8150'].filter(Boolean);
@@ -541,11 +584,15 @@ export class GenesisClient {
         const WARN_TIMEOUT_MS = 60_000; // warn after 60s of silence
         let lastChunkAt = Date.now();
         let warningSent = false;
+        // Retain the in-flight read across a warning-yield so reader.read() is
+        // never called twice concurrently (that throws on a locked reader).
+        let pendingRead = null;
         try {
             while (true) {
                 // Race reader.read() against a timeout so the client never hangs
                 // if the backend stalls (e.g. reasoning model cold-start, 404 retry loop).
-                const readPromise = reader.read();
+                const readPromise = pendingRead ?? reader.read();
+                pendingRead = readPromise;
                 // IMPORTANT: keep a handle to the timeout timer and clear it once the
                 // chunk arrives. Otherwise every chunk (hundreds per streamed turn) leaks
                 // a live 120s timer; the swarm of late, post-settle rejections keeps the
@@ -555,16 +602,18 @@ export class GenesisClient {
                 const timeoutPromise = new Promise((_, reject) => {
                     chunkTimer = setTimeout(() => reject(new Error('SSE chunk timeout')), CHUNK_TIMEOUT_MS);
                 });
-                // Intermediate warning if no data for 60s
+                // Warn after 60s of silence WITHOUT consuming the read: race a sentinel
+                // alongside it so we can surface "still working" and keep waiting.
                 let warnTimer = null;
+                const racers = [readPromise, timeoutPromise];
                 if (!warningSent) {
-                    warnTimer = setTimeout(() => {
-                        warningSent = true;
-                    }, WARN_TIMEOUT_MS);
+                    racers.push(new Promise((res) => {
+                        warnTimer = setTimeout(() => res({ __warn: true }), WARN_TIMEOUT_MS);
+                    }));
                 }
                 let result;
                 try {
-                    result = await Promise.race([readPromise, timeoutPromise]);
+                    result = await Promise.race(racers);
                     if (chunkTimer)
                         clearTimeout(chunkTimer);
                     if (warnTimer)
@@ -601,6 +650,13 @@ export class GenesisClient {
                     }
                     break;
                 }
+                // Silence warning fired — surface it and keep waiting on the SAME read.
+                if (result.__warn) {
+                    warningSent = true;
+                    yield { type: 'stream_warning', data: { type: 'stream_warning', silent_ms: Date.now() - lastChunkAt, message: 'Still working — model may be warming up…' } };
+                    continue; // pendingRead retained → no second reader.read()
+                }
+                pendingRead = null; // real chunk consumed
                 lastChunkAt = Date.now();
                 const { done, value } = result;
                 if (done)

package/dist/commands.js

@@ -14,6 +14,7 @@ import { getRemoteMcpClient } from './mcp-client.js';
 import { formatTable, getSessionArtifacts, clearSessionArtifacts, resolveImagePath, osc8Link, addSessionArtifact } from './renderer.js';
 import { loadSession, saveSession, listSessions, deleteSession, transcriptMarkdown, sessionTokens, } from './session-store.js';
 import { loginWithPassword, verify2FA, register, logoutSession, validateToken, buildProfile, setProfile, clearProfile, getActiveProfile, getActiveUser, getActiveToken, requestEmailOTP, verifyEmailOTP, requestDeviceCode, pollDeviceToken, } from './auth.js';
+import { runWizard } from './install-wizard.js';
 const ONBOARD_CODE_EXTENSIONS = new Set([
     '.py', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.java', '.go', '.rs', '.cs',
     '.cpp', '.cc', '.c', '.h', '.hpp', '.rb', '.php', '.swift', '.kt', '.kts', '.scala',
@@ -279,6 +280,13 @@ const COMMANDS = {
             console.log();
         },
     },
+    // ── Installation & onboarding ──
+    install: {
+        description: 'One-click installer wizard (non-technical setup)',
+        handler: async (client, _args, config) => {
+            await runWizard(client, config);
+        },
+    },
     // ── Conversation QoL (transcript-backed) ──
     chats: {
         description: 'List, resume, or delete saved chat conversations',
@@ -761,6 +769,151 @@ const COMMANDS = {
             console.log();
         },
     },
+    spec: {
+        description: "Spec Ledger — list/inspect specs, ingest a PRD, publish issues, reasoner",
+        usage: '/spec [list | status <id> | ingest <path|url> [--pack x] | publish <id> [--repo o/n] [--new "Title"|--board o/n|--no-board] [--go] | reasoner [mode] | settings [--repo o/n] [--board o/n]]',
+        handler: async (client, args) => {
+            const parts = args.trim().split(/\s+/);
+            const sub = (parts[0] || 'list').toLowerCase();
+            const flag = (name) => {
+                const m = args.match(new RegExp(`--${name}\\s+("[^"]+"|\\S+)`));
+                return m ? m[1].replace(/^"|"$/g, '') : '';
+            };
+            if (sub === 'list' || sub === '') {
+                const spinner = ora('Loading specs...').start();
+                const r = await client.get('/spec/list?limit=100');
+                spinner.stop();
+                const specs = r?.specs || [];
+                if (!specs.length) {
+                    console.log(chalk.dim('  No specs ingested yet — /spec ingest <path|url>'));
+                    return;
+                }
+                console.log();
+                for (const s of specs) {
+                    console.log(`  ${chalk.cyan(s.id)}  ${chalk.bold(s.title)}`);
+                    console.log(chalk.dim(`     ${s.requirement_count} reqs · ${s.conformance_pct}% conformant${s.target_pack ? ` · pack ${s.target_pack}` : ''}`));
+                }
+                console.log();
+                return;
+            }
+            if (sub === 'status') {
+                const id = parts[1];
+                if (!id) {
+                    console.log(chalk.dim('  Usage: /spec status <spec_id>'));
+                    return;
+                }
+                const spinner = ora('Loading...').start();
+                const r = await client.get(`/spec/${encodeURIComponent(id)}/status`);
+                spinner.stop();
+                if (!r || r.error || r.detail) {
+                    console.log(chalk.red(`  ${r?.error || r?.detail || 'not found'}`));
+                    return;
+                }
+                const ov = r.coverage?.overall || {};
+                console.log();
+                console.log(`  ${chalk.bold(r.title)} ${chalk.dim(`(${r.target_pack || 'untriaged'})`)}`);
+                console.log(`  ${ov.pct ?? 0}% conformant — ${ov.satisfied ?? 0}/${ov.total ?? 0} satisfied, ${(r.gaps || []).length} gaps`);
+                for (const [cat, c] of Object.entries(r.coverage?.by_category || {})) {
+                    console.log(chalk.dim(`     ${cat}: ${c.satisfied}/${c.total} (${c.pct}%)`));
+                }
+                console.log();
+                return;
+            }
+            if (sub === 'ingest') {
+                const src = parts[1];
+                if (!src) {
+                    console.log(chalk.dim('  Usage: /spec ingest <path|url> [--pack x]'));
+                    return;
+                }
+                const body = { background: false };
+                body[src.startsWith('http') ? 'url' : 'path'] = src;
+                const pack = flag('pack');
+                if (pack)
+                    body.target_pack = pack;
+                const spinner = ora('Ingesting + extracting (reasoner)...').start();
+                const r = await client.post('/spec/ingest', body);
+                spinner.stop();
+                if (!r || r.error) {
+                    console.log(chalk.red(`  ${r?.error || 'ingest failed'}`));
+                    return;
+                }
+                console.log(chalk.green(`  Ingested ${chalk.cyan(r.spec_doc_id)} — ${r.requirement_count ?? 0} requirements`));
+                if (r.by_category)
+                    console.log(chalk.dim(`     ${Object.entries(r.by_category).map(([k, v]) => `${k}:${v}`).join(', ')}`));
+                return;
+            }
+            if (sub === 'reasoner') {
+                const mode = parts[1];
+                const r = mode
+                    ? await client.post('/spec/reasoner', { mode })
+                    : await client.get('/spec/reasoner');
+                if (!r || r.error) {
+                    console.log(chalk.red(`  ${r?.error || 'reasoner call failed'}`));
+                    return;
+                }
+                console.log(`  Reasoner: ${chalk.cyan(r.effective)}  ${chalk.dim(`(available: ${(r.available_modes || []).join(', ')})`)}`);
+                return;
+            }
+            if (sub === 'settings') {
+                const repo = flag('repo'), board = flag('board');
+                let r;
+                if (repo || board) {
+                    const body = {};
+                    if (repo)
+                        body.publish_repo = repo;
+                    if (board)
+                        body.publish_project = board;
+                    r = await client.post('/spec/settings', body);
+                }
+                else {
+                    r = await client.get('/spec/settings');
+                }
+                if (!r || r.error) {
+                    console.log(chalk.red(`  ${r?.error || 'settings failed'}`));
+                    return;
+                }
+                console.log(`  Reasoner: ${chalk.cyan(r.reasoner_mode)} · publish_repo: ${chalk.cyan(r.publish_repo || '(unset)')} · board: ${chalk.cyan(r.publish_project || '(unset)')}`);
+                return;
+            }
+            if (sub === 'publish') {
+                const id = parts[1];
+                if (!id) {
+                    console.log(chalk.dim('  Usage: /spec publish <id> [--repo o/n] [--new "Title"|--board o/n|--no-board] [--go]'));
+                    return;
+                }
+                const go = /--go\b/.test(args);
+                const body = { dry_run: !go };
+                const repo = flag('repo');
+                if (repo)
+                    body.repo = repo; // else server uses spec_settings default
+                const newTitle = flag('new');
+                const board = flag('board');
+                if (newTitle)
+                    body.create_project_title = newTitle;
+                else if (board)
+                    body.project = board;
+                // --no-board: leave both unset → issues only
+                const spinner = ora(go ? 'Publishing issues...' : 'Dry-run preview...').start();
+                const r = await client.post(`/spec/${encodeURIComponent(id)}/publish-issues`, body);
+                spinner.stop();
+                if (!r || (r.error && !r.created)) {
+                    console.log(chalk.red(`  ${r?.error || 'publish failed'}`));
+                    return;
+                }
+                const created = r.created?.length ?? 0, skipped = r.skipped_existing?.length ?? 0, errs = r.errors?.length ?? 0;
+                console.log();
+                console.log(`  ${go ? chalk.green(`Published ${created}`) : chalk.yellow(`Would create ${created}`)} issue(s) on ${chalk.cyan(r.repo)}` +
+                    (skipped ? `, skipped ${skipped}` : '') + (errs ? chalk.red(`, ${errs} errors`) : '') + (r.project ? ` → board ${chalk.cyan(r.project)}` : ''));
+                if (errs)
+                    console.log(chalk.red(`     ${r.errors[0]}`));
+                if (!go)
+                    console.log(chalk.dim('     (dry-run — add --go to actually publish)'));
+                console.log();
+                return;
+            }
+            console.log(chalk.dim('  Usage: /spec [list | status <id> | ingest <path|url> | publish <id> | reasoner [mode] | settings]'));
+        },
+    },
     atlas: {
         description: "Atlas PM board — latest cycle, in-flight items, or run a cycle",
         usage: '/atlas [board|tick] [--items N] [--sync]',

package/dist/doc-view.d.ts

@@ -0,0 +1,35 @@
+/**
+ * doc-view.ts — Load a file and render it into lines for the in-TUI document
+ * viewer (`/view <path>`): markdown gets the full terminal-markdown render,
+ * code/text get a line-numbered gutter, and images render inline as half-blocks
+ * (see image-preview.ts). The pure load/render logic lives here so it's testable
+ * and so both the viewer overlay and a future `/edit` share one classifier.
+ */
+export type DocKind = 'markdown' | 'code' | 'text' | 'image' | 'binary' | 'missing';
+export interface LoadedDoc {
+    kind: DocKind;
+    absPath: string;
+    title: string;
+    ext: string;
+    sizeBytes: number;
+    /** Raw text content (text/code/markdown only). */
+    text?: string;
+    /** Error/explanatory note for the header line. */
+    note?: string;
+}
+/** Resolve a user-supplied path against cwd + the known AitherOS roots. */
+export declare function resolveDocPath(input: string): string;
+/** Load + classify a file. Never throws. */
+export declare function loadDoc(input: string): LoadedDoc;
+export interface ViewRender {
+    lines: string[];
+    /** When the doc is an image the viewer couldn't render inline (non-PNG), the
+     *  caller should OS-open this path instead. */
+    fallbackOpenPath?: string;
+}
+/**
+ * Render a loaded doc into display lines for the viewer overlay, wrapped to
+ * `width` columns. Markdown → terminal markdown; code/text → line-numbered;
+ * image → inline half-blocks (PNG) or a note + OS-open fallback.
+ */
+export declare function renderDocLines(doc: LoadedDoc, width: number): ViewRender;

package/dist/doc-view.js

@@ -0,0 +1,144 @@
+/**
+ * doc-view.ts — Load a file and render it into lines for the in-TUI document
+ * viewer (`/view <path>`): markdown gets the full terminal-markdown render,
+ * code/text get a line-numbered gutter, and images render inline as half-blocks
+ * (see image-preview.ts). The pure load/render logic lives here so it's testable
+ * and so both the viewer overlay and a future `/edit` share one classifier.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, extname, isAbsolute, resolve } from 'node:path';
+import chalk from 'chalk';
+import { renderMarkdown, stripOsc8, resolveImagePath } from './renderer.js';
+import { imageToAnsi, imageDimensions } from './image-preview.js';
+const MARKDOWN_EXTS = new Set(['.md', '.markdown', '.mdx']);
+const IMAGE_EXTS = new Set(['.png', '.apng', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg', '.ico']);
+const CODE_EXTS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.rs', '.go', '.java',
+    '.c', '.h', '.cpp', '.hpp', '.cs', '.rb', '.php', '.sh', '.ps1', '.psm1',
+    '.sql', '.css', '.scss', '.html', '.xml', '.toml', '.ini', '.dockerfile',
+]);
+const DATA_EXTS = new Set(['.json', '.yaml', '.yml', '.csv', '.log', '.txt', '.env', '.conf', '.cfg']);
+/** Map a file extension to a markdown fence language for syntax highlighting. */
+function fenceLang(ext) {
+    const e = ext.replace(/^\./, '');
+    const map = {
+        ts: 'typescript', tsx: 'tsx', js: 'javascript', jsx: 'jsx', mjs: 'javascript',
+        py: 'python', rs: 'rust', go: 'go', rb: 'ruby', ps1: 'powershell', psm1: 'powershell',
+        yml: 'yaml', sh: 'bash',
+    };
+    return map[e] || e || '';
+}
+/** Resolve a user-supplied path against cwd + the known AitherOS roots. */
+export function resolveDocPath(input) {
+    const raw = input.replace(/^["']|["']$/g, '').trim();
+    if (isAbsolute(raw) && existsSync(raw))
+        return raw;
+    const cwdTry = resolve(process.cwd(), raw);
+    if (existsSync(cwdTry))
+        return cwdTry;
+    // Reuse the renderer's AitherOS-root resolver (handles Library/ paths etc.).
+    try {
+        const r = resolveImagePath(raw);
+        if (existsSync(r))
+            return r;
+    }
+    catch { /* */ }
+    return cwdTry; // best-effort; caller checks existsSync via kind === 'missing'
+}
+/** Load + classify a file. Never throws. */
+export function loadDoc(input) {
+    const absPath = resolveDocPath(input);
+    const ext = extname(absPath).toLowerCase();
+    const title = basename(absPath);
+    if (!existsSync(absPath)) {
+        return { kind: 'missing', absPath, title, ext, sizeBytes: 0, note: 'file not found' };
+    }
+    let sizeBytes = 0;
+    try {
+        const st = statSync(absPath);
+        sizeBytes = st.size;
+        if (st.isDirectory()) {
+            return { kind: 'missing', absPath, title, ext, sizeBytes: 0, note: 'is a directory (pass a file)' };
+        }
+    }
+    catch { /* */ }
+    if (IMAGE_EXTS.has(ext)) {
+        return { kind: 'image', absPath, title, ext, sizeBytes };
+    }
+    // Read as text (cap at 2 MB so a huge log doesn't stall the render).
+    const CAP = 2 * 1024 * 1024;
+    let text;
+    try {
+        const buf = readFileSync(absPath);
+        if (buf.includes(0)) {
+            return { kind: 'binary', absPath, title, ext, sizeBytes, note: 'binary file' };
+        }
+        text = buf.length > CAP
+            ? buf.subarray(0, CAP).toString('utf-8') + '\n…(truncated)…'
+            : buf.toString('utf-8');
+    }
+    catch (e) {
+        return { kind: 'binary', absPath, title, ext, sizeBytes, note: e?.message || 'unreadable' };
+    }
+    if (MARKDOWN_EXTS.has(ext))
+        return { kind: 'markdown', absPath, title, ext, sizeBytes, text };
+    if (CODE_EXTS.has(ext) || DATA_EXTS.has(ext))
+        return { kind: 'code', absPath, title, ext, sizeBytes, text };
+    return { kind: 'text', absPath, title, ext, sizeBytes, text };
+}
+function humanSize(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+/**
+ * Render a loaded doc into display lines for the viewer overlay, wrapped to
+ * `width` columns. Markdown → terminal markdown; code/text → line-numbered;
+ * image → inline half-blocks (PNG) or a note + OS-open fallback.
+ */
+export function renderDocLines(doc, width) {
+    const innerW = Math.max(20, width - 2);
+    if (doc.kind === 'missing' || doc.kind === 'binary') {
+        return { lines: [chalk.red(`  ${doc.note || doc.kind}`), chalk.dim(`  ${doc.absPath}`)] };
+    }
+    if (doc.kind === 'image') {
+        const dims = imageDimensions(doc.absPath);
+        const header = [
+            chalk.dim(`  ${humanSize(doc.sizeBytes)}${dims ? ` · ${dims.width}×${dims.height}` : ''}`),
+            '',
+        ];
+        const ansi = imageToAnsi(doc.absPath, Math.min(innerW, 100), 44);
+        if (ansi)
+            return { lines: [...header, ...ansi.map(l => ' ' + l)] };
+        // Non-PNG (JPEG/WEBP/…): can't decode without a dep — OS-open instead.
+        return {
+            lines: [
+                ...header,
+                chalk.yellow(`  ${doc.ext.replace('.', '').toUpperCase()} preview not supported inline — opening in your OS viewer.`),
+                chalk.dim('  (PNG renders inline; other formats open externally.)'),
+            ],
+            fallbackOpenPath: doc.absPath,
+        };
+    }
+    if (doc.kind === 'markdown' && doc.text != null) {
+        const rendered = stripOsc8(renderMarkdown(doc.text));
+        return { lines: rendered.replace(/\n$/, '').split('\n') };
+    }
+    // code / text → line-numbered gutter.
+    const text = doc.text ?? '';
+    const rawLines = text.split('\n');
+    const gutterW = String(rawLines.length).length;
+    const lang = doc.kind === 'code' ? fenceLang(doc.ext) : '';
+    const out = [];
+    rawLines.forEach((ln, i) => {
+        const num = chalk.dim(String(i + 1).padStart(gutterW, ' ') + ' │ ');
+        // Light, dependency-free emphasis for code: comments dimmed.
+        let body = ln;
+        if (lang && /^\s*(#|\/\/|--|;)/.test(ln))
+            body = chalk.dim(ln);
+        out.push(num + body);
+    });
+    return { lines: out };
+}

package/dist/image-preview.d.ts

@@ -0,0 +1,45 @@
+/**
+ * image-preview.ts — Render raster images INLINE in the terminal as Unicode
+ * half-blocks (▀) with 24-bit colour.
+ *
+ * Why half-blocks instead of sixel / iTerm2 / kitty graphics: those protocols
+ * each work in only SOME terminals (sixel needs Windows Terminal ≥1.22, iTerm2's
+ * OSC-1337 needs iTerm2/WezTerm, kitty needs kitty) and several need the image
+ * re-encoded. The half-block trick — print '▀' with the FOREGROUND set to the top
+ * pixel and the BACKGROUND to the bottom pixel, so one character cell shows TWO
+ * vertical pixels — works in EVERY 24-bit-colour terminal, including the Windows
+ * Terminal the fleet runs on. Decoding uses node's built-in zlib (no new deps),
+ * so PNG (the format ComfyUI/AitherCanvas emit) renders for real; other formats
+ * fall back to the OS viewer at the call site.
+ */
+export interface DecodedImage {
+    width: number;
+    height: number;
+    /** RGBA, 4 bytes per pixel, row-major. */
+    rgba: Uint8Array;
+}
+/**
+ * Minimal PNG decoder — enough for the 8-bit images the fleet produces:
+ * colour types 0 (grey), 2 (RGB), 3 (palette), 6 (RGBA), and all 5 scanline
+ * filters. Returns null for anything it can't handle (interlaced, 16-bit, etc.)
+ * so the caller can fall back to the OS viewer.
+ */
+export declare function decodePNG(buf: Buffer): DecodedImage | null;
+/**
+ * Render a decoded image as half-block ANSI lines scaled to fit `cols` columns
+ * (each line is one terminal row = two image rows). Preserves aspect ratio;
+ * terminal cells are ~2× tall as wide, which the half-block already accounts for
+ * (2 pixels per cell vertically).
+ */
+export declare function renderHalfBlock(img: DecodedImage, cols: number, maxRows?: number): string[];
+/**
+ * Read an image file and render it inline as half-block ANSI lines, scaled to
+ * `cols`. Returns null when the format isn't decodable here (JPEG/GIF/WEBP/…),
+ * so the caller can fall back to the OS viewer. Never throws.
+ */
+export declare function imageToAnsi(absPath: string, cols: number, maxRows?: number): string[] | null;
+/** Cheap dimensions probe for the metadata header (PNG only; null otherwise). */
+export declare function imageDimensions(absPath: string): {
+    width: number;
+    height: number;
+} | null;