rpc-agent 0.0.0-stage → 0.3.1

package/dist/mcp.js

@@ -0,0 +1,245 @@
+import { readFileSync } from 'node:fs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { capture, launchBrowser } from './capture.js';
+import { renderPreview } from './composite.js';
+import { CATEGORY_LABELS, CATEGORY_ORDER, DEFAULT_DEVICES, DEVICE_ALIASES, DEVICES, resolveDevices, } from './devices.js';
+import { COLOR_SCHEMES, DEFAULT_MAX_SLICES, DEFAULT_OUT_DIR, DEFAULT_SLICE_WIDTH, DEFAULT_TIMEOUT_MS, normalizeUrl, } from './options.js';
+import { DEFAULT_MAX_HEIGHT } from './slices.js';
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const screenshotInput = {
+    url: z
+        .string()
+        .describe('Page to capture. http(s)://, file://, a bare host like localhost:3000, or a path to a local .html file.'),
+    devices: z
+        .array(z.string())
+        .min(1)
+        .max(8)
+        .optional()
+        .describe(`Device ids or aliases (see list_devices). Default: ${DEFAULT_DEVICES.join(', ')}. ` +
+        `Aliases: ${Object.keys(DEVICE_ALIASES).join(', ')}.`),
+    bezels: z.boolean().optional().describe('Also write a copy framed in the device bezel (above-the-fold only). Default false.'),
+    fullPage: z
+        .boolean()
+        .optional()
+        .describe('Capture the full scroll height (any height, stitched; capped by maxHeight). The result then shows the whole page ' +
+        'as top-to-bottom JPEG slices, one viewport tall each, after the framed first screen when bezels is on. Default false.'),
+    maxSlices: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe(`Full page: most slices returned inline per device. Default ${DEFAULT_MAX_SLICES}. ` +
+        'When a page has more, every slice is also saved as a JPEG and the paths are listed so you can Read the rest.'),
+    saveSlices: z
+        .boolean()
+        .optional()
+        .describe('Full page: always (true) or never (false) write slice JPEGs next to the PNGs. Default: only when slices were cut by maxSlices.'),
+    sliceWidth: z
+        .number()
+        .int()
+        .min(256)
+        .max(1568)
+        .optional()
+        .describe(`Full page: max slice width in px. Default ${DEFAULT_SLICE_WIDTH}; raise it (e.g. 1200) to read small text on desktop widths.`),
+    maxHeight: z
+        .number()
+        .int()
+        .min(500)
+        .max(200_000)
+        .optional()
+        .describe(`Full page: capture at most this many CSS px; taller pages are marked clipped. Default ${DEFAULT_MAX_HEIGHT}.`),
+    reducedMotion: z
+        .boolean()
+        .optional()
+        .describe('Emulate prefers-reduced-motion: reduce. Helps when scroll-triggered entrance animations (GSAP, Framer Motion) leave sections blank.'),
+    waitFor: z.string().optional().describe('CSS selector to wait for (visible) before capturing.'),
+    waitMs: z.number().int().min(0).max(30_000).optional().describe('Extra settle delay after load, in ms.'),
+    colorScheme: z.enum(COLOR_SCHEMES).optional().describe('Emulate prefers-color-scheme.'),
+    outDir: z.string().optional().describe(`Output directory, relative to the server's cwd. Default ${DEFAULT_OUT_DIR}.`),
+    timeoutMs: z.number().int().min(1000).max(120_000).optional().describe(`Navigation timeout. Default ${DEFAULT_TIMEOUT_MS}.`),
+    inline: z
+        .boolean()
+        .optional()
+        .describe('Return JPEG previews inline: one per device, or the full-page slices when fullPage. Default true.'),
+};
+export function createServer() {
+    const server = new McpServer({ name: 'rpc', version: pkg.version });
+    server.registerTool('screenshot', {
+        title: 'Screenshot at device viewports',
+        description: 'Load a URL in headless Chromium at one or more device viewports (with device pixel ratio, mobile user agent and touch) ' +
+            'and save PNG screenshots, optionally framed in a device bezel. Use it to check responsive layout of a page you are building, ' +
+            'including local dev servers. Returns file paths, page title, HTTP status and console errors, plus inline previews.',
+        inputSchema: screenshotInput,
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (args) => {
+        let options;
+        try {
+            options = {
+                url: normalizeUrl(args.url),
+                devices: resolveDevices(args.devices ?? DEFAULT_DEVICES).map(d => d.id),
+                bezels: args.bezels ?? false,
+                fullPage: args.fullPage ?? false,
+                outDir: args.outDir ?? DEFAULT_OUT_DIR,
+                waitFor: args.waitFor,
+                waitMs: args.waitMs ?? 0,
+                colorScheme: args.colorScheme,
+                timeoutMs: args.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                emulate: true,
+                reducedMotion: args.reducedMotion ?? false,
+                maxHeight: args.maxHeight ?? DEFAULT_MAX_HEIGHT,
+                saveSlices: args.saveSlices,
+                maxSlices: args.maxSlices ?? DEFAULT_MAX_SLICES,
+                sliceWidth: args.sliceWidth ?? DEFAULT_SLICE_WIDTH,
+            };
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: 'text', text: err.message }] };
+        }
+        const inline = args.inline ?? true;
+        let browser;
+        try {
+            browser = await launchBrowser();
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: 'text', text: `Could not start the browser: ${err.message}` }] };
+        }
+        try {
+            const result = await capture(options, { browser, keepBuffers: true, inlineSlices: inline && options.fullPage });
+            const content = [
+                {
+                    type: 'text',
+                    text: headline(result.shots, options) +
+                        '\n\n' +
+                        JSON.stringify(summarise(result.url, result.outDir, result.shots), null, 2),
+                },
+            ];
+            if (inline) {
+                for (const s of result.shots) {
+                    if (s.error)
+                        continue;
+                    if (options.fullPage) {
+                        content.push(...(await fullPageImages(browser, s, options.maxSlices)));
+                        continue;
+                    }
+                    const src = s.framed && s.buffers?.framed ? { buf: s.buffers.framed, size: s.framed } : s.shot && s.buffers?.shot ? { buf: s.buffers.shot, size: s.shot } : undefined;
+                    if (!src)
+                        continue;
+                    const p = await renderPreview(browser, src.buf, src.size);
+                    content.push({
+                        type: 'text',
+                        text: `${s.device}${s.framed ? ' (framed)' : ''}: preview ${p.width}x${p.height}${p.cropped ? ', cropped to top of page' : ''}`,
+                    });
+                    content.push({ type: 'image', data: p.data.toString('base64'), mimeType: 'image/jpeg' });
+                }
+            }
+            const allFailed = result.shots.every(s => s.error);
+            return allFailed ? { isError: true, content } : { content };
+        }
+        finally {
+            await browser.close();
+        }
+    });
+    server.registerTool('list_devices', {
+        title: 'List device presets',
+        description: 'List device ids, CSS viewport sizes and pixel ratios usable in screenshot.devices, plus short aliases.',
+        inputSchema: {
+            category: z
+                .enum(CATEGORY_ORDER)
+                .optional()
+                .describe('Filter to one category.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ category }) => {
+        const lines = [];
+        for (const cat of CATEGORY_ORDER) {
+            if (category && cat !== category)
+                continue;
+            lines.push(`## ${CATEGORY_LABELS[cat]}`);
+            for (const d of DEVICES.filter(x => x.category === cat)) {
+                lines.push(`${d.id}: ${d.width}x${d.height} @${d.dpr}x (${d.name})`);
+            }
+            lines.push('');
+        }
+        lines.push('## Aliases');
+        for (const [a, id] of Object.entries(DEVICE_ALIASES))
+            lines.push(`${a} -> ${id}`);
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    });
+    return server;
+}
+/** Framed first screen (the hero), then the first maxSlices slices, each with a label. */
+async function fullPageImages(browser, s, maxSlices) {
+    const out = [];
+    if (s.framed && s.buffers?.framed) {
+        const p = await renderPreview(browser, s.buffers.framed, s.framed);
+        out.push({ type: 'text', text: `${s.device} · first screen in bezel` });
+        out.push({ type: 'image', data: p.data.toString('base64'), mimeType: 'image/jpeg' });
+    }
+    const items = s.slices?.items ?? [];
+    const bufs = s.buffers?.slices ?? [];
+    for (let i = 0; i < Math.min(items.length, maxSlices); i++) {
+        out.push({ type: 'text', text: items[i].label });
+        out.push({ type: 'image', data: bufs[i].toString('base64'), mimeType: 'image/jpeg' });
+    }
+    return out;
+}
+/** Plain-language first lines: failures with hints, and what full-page output covers. */
+export function headline(shots, options) {
+    const lines = [];
+    const failed = shots.filter(s => s.error);
+    if (failed.length === shots.length)
+        lines.push(`All ${shots.length} device(s) failed.`);
+    for (const s of shots) {
+        if (s.error) {
+            lines.push(`FAILED ${s.device}: ${s.error}${s.hint ? `\n  hint: ${s.hint}` : ''}`);
+            continue;
+        }
+        const size = s.shot ? `${s.shot.width}x${s.shot.height}px` : '';
+        if (!options.fullPage) {
+            lines.push(`ok ${s.device}: ${size}${s.shot ? ` ${s.shot.path}` : ''}`);
+            continue;
+        }
+        const parts = [
+            `ok ${s.device}: full page ${s.capturedHeight} css px tall (${size}` +
+                `${s.segments && s.segments > 1 ? `, ${s.segments} segments stitched` : ''}) ${s.shot ? s.shot.path : ''}`,
+        ];
+        if (s.clipped) {
+            parts.push(`  clipped: the page is ${s.scrollHeight} css px; only the top ${options.maxHeight} were captured (raise maxHeight).`);
+        }
+        const sl = s.slices;
+        if (sl) {
+            const shown = Math.min(sl.items.length, options.maxSlices);
+            if (sl.total > shown) {
+                const firstSkipped = sl.items[shown] ?? undefined;
+                const from = firstSkipped ? firstSkipped.y : shown * sl.sliceHeight;
+                parts.push(`  inline: slices 1-${shown} of ${sl.total}; slices ${shown + 1}-${sl.total} (y=${from}-${s.capturedHeight} css px) skipped inline.`);
+            }
+            else {
+                parts.push(`  inline: all ${sl.total} slice(s), top to bottom.`);
+            }
+            if (sl.saved) {
+                const first = sl.items[0]?.path;
+                parts.push(`  slice files: ${first ? first.replace(/-slice-\d+\.jpg$/, '-slice-NN.jpg') : '(none)'} (01-${String(sl.total).padStart(2, '0')}); full PNG: ${s.shot ? s.shot.path : ''}`);
+            }
+            else if (sl.total > shown) {
+                parts.push(`  full PNG: ${s.shot ? s.shot.path : ''}`);
+            }
+        }
+        lines.push(parts.join('\n'));
+    }
+    return lines.join('\n');
+}
+function summarise(url, outDir, shots) {
+    return {
+        url,
+        outDir,
+        shots: shots.map(({ buffers: _b, ...s }) => s),
+    };
+}
+export async function runMcpServer() {
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+}

package/dist/options.js

@@ -0,0 +1,51 @@
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { existsSync } from 'node:fs';
+import { DEFAULT_DEVICES } from './devices.js';
+import { DEFAULT_MAX_HEIGHT } from './slices.js';
+export const COLOR_SCHEMES = ['light', 'dark', 'no-preference'];
+export const DEFAULT_MAX_SLICES = 10;
+export const DEFAULT_SLICE_WIDTH = 768;
+export const DEFAULT_OUT_DIR = '.rpc-shots';
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export function defaultShotOptions(url) {
+    return {
+        url: normalizeUrl(url),
+        devices: [...DEFAULT_DEVICES],
+        bezels: false,
+        fullPage: false,
+        outDir: DEFAULT_OUT_DIR,
+        waitMs: 0,
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        emulate: true,
+        reducedMotion: false,
+        maxHeight: DEFAULT_MAX_HEIGHT,
+        maxSlices: DEFAULT_MAX_SLICES,
+        sliceWidth: DEFAULT_SLICE_WIDTH,
+    };
+}
+/**
+ * Accept what an agent is likely to type:
+ *   http(s)://…, file://…  -> unchanged
+ *   localhost:3000/x, 127.0.0.1:8080, [::1]:3000 -> http://
+ *   ./page.html, /abs/page.html (existing file) -> file://
+ *   example.com -> https://
+ */
+export function normalizeUrl(input, cwd = process.cwd()) {
+    const raw = input.trim();
+    if (!raw)
+        throw new Error('URL is required');
+    if (/^(https?|file):\/\//i.test(raw))
+        return new URL(raw).href;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+        throw new Error(`Unsupported URL scheme in "${raw}" (use http, https or file)`);
+    }
+    if (/^(localhost|127\.\d+\.\d+\.\d+|0\.0\.0\.0|\[::1\])(:\d+)?(\/|$)/i.test(raw)) {
+        return new URL(`http://${raw}`).href;
+    }
+    const asPath = isAbsolute(raw) ? raw : resolve(cwd, raw);
+    if ((raw.startsWith('.') || raw.startsWith('/') || /\.html?$/i.test(raw)) && existsSync(asPath)) {
+        return pathToFileURL(asPath).href;
+    }
+    return new URL(`https://${raw}`).href;
+}

package/dist/png.js

@@ -0,0 +1,183 @@
+import { createDeflate, inflateSync } from 'node:zlib';
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** Read width/height from a PNG's IHDR chunk without decoding it. */
+export function pngSize(buf) {
+    if (buf.length < 24 || SIGNATURE.some((b, i) => buf[i] !== b)) {
+        throw new Error('Not a PNG');
+    }
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    return { width: view.getUint32(16), height: view.getUint32(20) };
+}
+/**
+ * Decode an 8-bit RGB/RGBA non-interlaced PNG, which is what Chromium
+ * screenshots are. Anything else throws: this is not a general decoder.
+ */
+export function decodePng(buf) {
+    const { width, height } = pngSize(buf);
+    let pos = 8;
+    const idat = [];
+    let channels;
+    while (pos + 8 <= buf.length) {
+        const len = buf.readUInt32BE(pos);
+        const type = buf.toString('latin1', pos + 4, pos + 8);
+        const body = buf.subarray(pos + 8, pos + 8 + len);
+        if (type === 'IHDR') {
+            const [depth, color, , , interlace] = body.subarray(8, 13);
+            if (depth !== 8 || (color !== 2 && color !== 6) || interlace !== 0) {
+                throw new Error(`Unsupported PNG (bit depth ${depth}, colour type ${color}, interlace ${interlace})`);
+            }
+            channels = color === 6 ? 4 : 3;
+        }
+        else if (type === 'IDAT') {
+            idat.push(body);
+        }
+        else if (type === 'IEND') {
+            break;
+        }
+        pos += 12 + len;
+    }
+    if (!channels)
+        throw new Error('PNG has no IHDR');
+    const filtered = inflateSync(Buffer.concat(idat));
+    const stride = width * channels;
+    if (filtered.length < height * (stride + 1))
+        throw new Error('Truncated PNG data');
+    const out = Buffer.alloc(height * stride);
+    const bpp = channels;
+    for (let y = 0; y < height; y++) {
+        const f = filtered[y * (stride + 1)];
+        const src = y * (stride + 1) + 1;
+        const dst = y * stride;
+        const up = dst - stride;
+        for (let i = 0; i < stride; i++) {
+            const x = filtered[src + i];
+            const a = i >= bpp ? out[dst + i - bpp] : 0;
+            const b = y > 0 ? out[up + i] : 0;
+            let v;
+            switch (f) {
+                case 0:
+                    v = x;
+                    break;
+                case 1:
+                    v = x + a;
+                    break;
+                case 2:
+                    v = x + b;
+                    break;
+                case 3:
+                    v = x + ((a + b) >> 1);
+                    break;
+                case 4: {
+                    const c = y > 0 && i >= bpp ? out[up + i - bpp] : 0;
+                    const p = a + b - c;
+                    const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+                    v = x + (pa <= pb && pa <= pc ? a : pb <= pc ? b : c);
+                    break;
+                }
+                default: throw new Error(`Bad PNG filter type ${f}`);
+            }
+            out[dst + i] = v & 0xff;
+        }
+    }
+    return { width, height, channels, data: out };
+}
+function toChannels(img, channels) {
+    if (img.channels === channels)
+        return img.data;
+    const n = img.width * img.height;
+    const out = Buffer.alloc(n * channels, 0xff);
+    for (let p = 0; p < n; p++) {
+        for (let c = 0; c < 3; c++)
+            out[p * channels + c] = img.data[p * img.channels + c];
+    }
+    return out;
+}
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(parts) {
+    let c = 0xffffffff;
+    for (const buf of parts)
+        for (let i = 0; i < buf.length; i++)
+            c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, body) {
+    const head = Buffer.alloc(8);
+    head.writeUInt32BE(body.length, 0);
+    head.write(type, 4, 'latin1');
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32([head.subarray(4), body]));
+    return Buffer.concat([head, body, crc]);
+}
+/**
+ * Stack PNGs of equal width top to bottom into one PNG. Each input is decoded,
+ * filtered (Up) and streamed into a single deflate stream, so peak memory is
+ * about one input's raw pixels plus the compressed output: the result can be
+ * far taller than any canvas or Chromium capture allows.
+ */
+export async function stitchPngs(pngs) {
+    if (pngs.length === 0)
+        throw new Error('Nothing to stitch');
+    if (pngs.length === 1)
+        return pngs[0];
+    const sizes = pngs.map(pngSize);
+    const width = sizes[0].width;
+    if (sizes.some(s => s.width !== width))
+        throw new Error('stitchPngs: inputs differ in width');
+    const height = sizes.reduce((h, s) => h + s.height, 0);
+    // Peek each IHDR colour type so mixed RGB/RGBA inputs share one format.
+    const channels = pngs.some(p => p[25] === 6) ? 4 : 3;
+    const stride = width * channels;
+    const deflate = createDeflate({ level: 6, memLevel: 9 });
+    const compressed = [];
+    deflate.on('data', (d) => compressed.push(d));
+    const done = new Promise((res, rej) => {
+        deflate.on('end', res);
+        deflate.on('error', rej);
+    });
+    let prev;
+    for (const png of pngs) {
+        const img = decodePng(png);
+        const raw = toChannels(img, channels);
+        const out = Buffer.alloc(img.height * (stride + 1));
+        for (let y = 0; y < img.height; y++) {
+            const row = raw.subarray(y * stride, (y + 1) * stride);
+            const o = y * (stride + 1);
+            if (!prev) {
+                out[o] = 0;
+                row.copy(out, o + 1);
+            }
+            else {
+                out[o] = 2; // Up
+                for (let i = 0; i < stride; i++)
+                    out[o + 1 + i] = (row[i] - prev[i]) & 0xff;
+            }
+            prev = row;
+        }
+        // Keep the last row alive past this iteration for the next input's Up filter.
+        prev = Buffer.from(prev);
+        if (!deflate.write(out))
+            await new Promise(r => deflate.once('drain', r));
+    }
+    deflate.end();
+    await done;
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8;
+    ihdr[9] = channels === 4 ? 6 : 2;
+    const data = Buffer.concat(compressed);
+    const idats = [];
+    const MAX_IDAT = 8 * 1024 * 1024;
+    for (let i = 0; i < data.length; i += MAX_IDAT)
+        idats.push(chunk('IDAT', data.subarray(i, i + MAX_IDAT)));
+    return Buffer.concat([SIGNATURE, chunk('IHDR', ihdr), ...idats, chunk('IEND', Buffer.alloc(0))]);
+}

package/dist/slices.js

@@ -0,0 +1,59 @@
+/** Chromium can't produce a bitmap taller than this in one capture. */
+export const MAX_CAPTURE_PX = 16_384;
+/** Device px per stitched segment: well under the limit, a few MB raw each. */
+export const SEGMENT_PX = 8_192;
+/** Default absolute cap on full-page height, in CSS px. */
+export const DEFAULT_MAX_HEIGHT = 60_000;
+const isWhole = (n) => Math.abs(n - Math.round(n)) < 1e-6;
+/**
+ * Split `totalCss` into capture segments of at most `maxDevicePx` device px.
+ * Every segment but the last is a CSS height whose device height is a whole
+ * number of pixels (e.g. multiples of 8 at DPR 2.625), so stitched seams
+ * land exactly on pixel rows.
+ */
+export function planSegments(totalCss, dpr, maxDevicePx = SEGMENT_PX) {
+    const total = Math.max(1, Math.ceil(totalCss));
+    let seg = Math.max(1, Math.floor(maxDevicePx / dpr));
+    while (seg > 1 && !isWhole(seg * dpr))
+        seg--;
+    const out = [];
+    for (let y = 0; y < total; y += seg)
+        out.push({ y, height: Math.min(seg, total - y) });
+    return out;
+}
+/** True when a page this tall fits a single Chromium capture. */
+export function fitsOneCapture(totalCss, dpr) {
+    return Math.ceil(totalCss) * dpr <= MAX_CAPTURE_PX;
+}
+/**
+ * Cut a page into top-to-bottom review slices of `sliceHeight` CSS px (one
+ * viewport by default). A last slice shorter than a fifth of `sliceHeight` is
+ * folded into the one before it rather than shown as a sliver.
+ */
+export function planSlices(device, totalCss, sliceHeight) {
+    const total = Math.max(1, Math.round(totalCss));
+    const step = Math.max(1, Math.round(sliceHeight));
+    const bands = [];
+    for (let y = 0; y < total; y += step)
+        bands.push({ y, height: Math.min(step, total - y) });
+    if (bands.length > 1 && bands[bands.length - 1].height < step / 5) {
+        const last = bands.pop();
+        bands[bands.length - 1].height += last.height;
+    }
+    return bands.map((b, i) => ({
+        ...b,
+        index: i + 1,
+        total: bands.length,
+        label: sliceLabel(device, i + 1, bands.length, b),
+    }));
+}
+export function sliceLabel(device, index, total, b) {
+    return `${device} · slice ${index}/${total} · y=${b.y}–${b.y + b.height} css px`;
+}
+/**
+ * Preview scale (output px per CSS px) for slices: as sharp as the capture
+ * allows (never above the DPR) but no wider than `maxWidth`.
+ */
+export function sliceScale(cssWidth, dpr, maxWidth) {
+    return Math.min(dpr, maxWidth / cssWidth);
+}

package/dist/term.js

@@ -0,0 +1,46 @@
+import { spawn } from 'node:child_process';
+function set(v) {
+    return v !== undefined && v !== '';
+}
+/**
+ * Rich output needs a real terminal: stdout is a TTY, not CI, TERM isn't
+ * `dumb`, and no --json. NO_COLOR turns colour off; FORCE_COLOR (except `0`)
+ * turns it on, even for the plain layout, and wins over NO_COLOR.
+ */
+export function outputMode({ isTTY, env, json = false }) {
+    if (json)
+        return { rich: false, color: false };
+    const rich = isTTY && !set(env.CI) && env.TERM !== 'dumb';
+    // Same precedence as Node's own util.styleText, which clack uses for its
+    // symbols: FORCE_COLOR beats NO_COLOR, NO_COLOR beats the TTY check.
+    let color = rich;
+    if (set(env.NO_COLOR))
+        color = false;
+    if (set(env.FORCE_COLOR))
+        color = env.FORCE_COLOR !== '0';
+    return { rich, color };
+}
+export function currentMode(json = false) {
+    return outputMode({ isTTY: Boolean(process.stdout.isTTY), env: process.env, json });
+}
+/** Command that opens a folder or file in the desktop shell. */
+export function openCommand(platform = process.platform) {
+    if (platform === 'darwin')
+        return { cmd: 'open', args: [] };
+    if (platform === 'win32')
+        return { cmd: 'explorer', args: [] };
+    return { cmd: 'xdg-open', args: [] };
+}
+/** Open a folder or file in the desktop shell, detached and silent. */
+export function openPath(path) {
+    const { cmd, args } = openCommand();
+    try {
+        const child = spawn(cmd, [...args, path], { detached: true, stdio: 'ignore' });
+        child.on('error', () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}