@dokebi/cli 0.2.4 → 0.4.0

package/dist/app-urls.d.ts

@@ -0,0 +1,21 @@
+/** What decides which Host names the app answers. */
+export interface AppHosts {
+    /** A plugin that hosts apps (@dokebi/app) is installed: the Host header picks the app. */
+    readonly hosted: boolean;
+    /** The configured domains of that plugin (`options.<host>.domains` keys), in order. */
+    readonly domains: readonly string[];
+    /** A key of domains answers unknown hosts (`unknownDomain`, not `reject`). */
+    readonly answersUnknown: boolean;
+}
+/** Whether a host name or IP resolves to this machine (loopback). */
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * The URLs to show for the listening addresses `listen` (from the web listening line or
+ * dokebi.yaml). Without an app host: the listening addresses (a wildcard shown as 127.0.0.1).
+ * With one: `<scheme>://<domain>:<port>` for each loopback domain, plus the listening addresses
+ * when unknown hosts are answered. Empty when only public domains are configured (they answer
+ * through DNS or a proxy, not on this machine by name).
+ */
+export declare function appUrls(listen: readonly string[], hosts: AppHosts): string[];
+/** The app host settings of a project; `hosted: false` when no plugin hosts apps. */
+export declare function readAppHosts(root: string): Promise<AppHosts>;

package/dist/app-urls.js

@@ -0,0 +1,94 @@
+// Addresses the app really answers (AI-M03). @dokebi/web listens on an IP (`http://127.0.0.1:3000`),
+// but with a plugin that hosts apps (@dokebi/app, D-0070) the Host header picks the app: a
+// request for `127.0.0.1` gets 404 unless that IP is a configured domain or `unknownDomain`
+// names an app. `start`, `verify` and `dev` therefore report `http://<domain>:<port>` for every
+// configured domain that resolves to this machine (`localhost`, `*.localhost`, `127.x.x.x`) and
+// keep the listening address apart (`listen`).
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONFIG_FILE, parseProjectConfig } from './configuration.js';
+import { debug, describeError, isMissing } from './diagnostics.js';
+import { parseObject } from './filesystem.js';
+import { findHost } from './manifest.js';
+import { readState } from './project-state.js';
+/** Listening addresses that accept connections from this machine on every loopback name. */
+const WILDCARD = new Set(['0.0.0.0', '::', '[::]']);
+/** Whether a host name or IP resolves to this machine (loopback). */
+export function isLoopbackHost(host) {
+    const name = host.toLowerCase().replace(/^\[|\]$/g, '');
+    return (name === 'localhost' ||
+        name.endsWith('.localhost') ||
+        name === '::1' ||
+        /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(name));
+}
+/** A listening URL with a wildcard address replaced by 127.0.0.1 (where this machine reaches it). */
+function reachable(url) {
+    const host = WILDCARD.has(url.hostname) ? '127.0.0.1' : url.hostname;
+    return `${url.protocol}//${host}${port(url)}`;
+}
+/** `:<port>`, or nothing for the scheme's default port (URL drops it). */
+const port = (url) => (url.port ? `:${url.port}` : '');
+/**
+ * The URLs to show for the listening addresses `listen` (from the web listening line or
+ * dokebi.yaml). Without an app host: the listening addresses (a wildcard shown as 127.0.0.1).
+ * With one: `<scheme>://<domain>:<port>` for each loopback domain, plus the listening addresses
+ * when unknown hosts are answered. Empty when only public domains are configured (they answer
+ * through DNS or a proxy, not on this machine by name).
+ */
+export function appUrls(listen, hosts) {
+    const parsed = [];
+    for (const item of listen) {
+        try {
+            parsed.push(new URL(item));
+        }
+        catch (error) {
+            // listeningUrls only keeps http(s) URLs; anything else is not an address to show.
+            debug('Skipped a listening address that is not a URL', {
+                url: item,
+                error: describeError(error),
+            });
+        }
+    }
+    const direct = [...new Set(parsed.map(reachable))];
+    if (!hosts.hosted)
+        return direct;
+    // Loopback names reach a server that listens on loopback or on every address.
+    const endpoints = new Map();
+    for (const url of parsed)
+        if (WILDCARD.has(url.hostname) || isLoopbackHost(url.hostname))
+            endpoints.set(`${url.protocol}${url.port}`, url);
+    const urls = [];
+    for (const domain of hosts.domains)
+        if (isLoopbackHost(domain))
+            for (const url of endpoints.values())
+                urls.push(`${url.protocol}//${domain}${port(url)}`);
+    if (hosts.answersUnknown)
+        urls.push(...direct);
+    return [...new Set(urls)];
+}
+/** The app host settings of a project; `hosted: false` when no plugin hosts apps. */
+export async function readAppHosts(root) {
+    const none = { hosted: false, domains: [], answersUnknown: false };
+    let stateText;
+    try {
+        stateText = await readFile(join(root, '.dokebi/state.json'), 'utf8');
+    }
+    catch (error) {
+        // Not a project (yet): there is no app host.
+        if (isMissing(error))
+            return none;
+        throw error;
+    }
+    const state = readState(parseObject(stateText, 'state'));
+    const host = findHost(state.plugins, 'apps');
+    if (!host)
+        return none;
+    const options = parseProjectConfig(await readFile(join(root, CONFIG_FILE), 'utf8')).options;
+    const settings = (options[host.id] ?? {});
+    const domains = Object.keys(settings.domains ?? {});
+    const answersUnknown = typeof settings.unknownDomain === 'string' &&
+        settings.unknownDomain !== 'reject' &&
+        domains.includes(settings.unknownDomain);
+    debug('App hosts read', { host: host.id, domains, answersUnknown });
+    return { hosted: true, domains, answersUnknown };
+}

package/dist/banner-art.d.ts

@@ -0,0 +1,4 @@
+/** Symbol pixels, 20×20: one row per pixel row, 'rrggbb' per pixel, '------' transparent. */
+export declare const SYMBOL_PIXELS: readonly string[];
+/** Wordmark gradient stops, left to right, sampled from the symbol. */
+export declare const GRADIENT: readonly (readonly [number, number, number])[];

package/dist/banner-art.js

@@ -0,0 +1,31 @@
+// GENERATED by scripts/brand/render-logo.mjs from packages/cli/brand/symbol.png. Do not edit.
+// Regenerate: node scripts/brand/render-logo.mjs (npm run check fails when this file is stale).
+/** Symbol pixels, 20×20: one row per pixel row, 'rrggbb' per pixel, '------' transparent. */
+export const SYMBOL_PIXELS = [
+    '------ ------ ------ ------ ------ ------ 0074fc ------ ------ ------ ------ ------ ------ ------ b912fc ------ ------ ------ ------ ------',
+    '------ ------ ------ ------ ------ 00a3fc 006dfc ------ ------ ------ ------ ------ ------ ------ 9728fb b121fb aa00fc ------ ------ ------',
+    '------ ------ ------ ------ 00a9fc 0087fc 005afc ------ ------ ------ ------ ------ ------ 3810fa 5a1bfa 6f17fb 7e00fb ------ ------ ------',
+    '------ ------ ------ 00a0fb 0088fb 0060fc 0037fc 0009fc ------ ------ ------ ------ ------ 0900fa 1600fb 2900fb 4000fb ------ ------ ------',
+    '------ ------ ------ 0088fb 005dfb 0030fc ------ ------ ------ 1845fb 535bfb 8271fb ad8bfb c99cfb 603bfb 0000fb 0a00fb ------ ------ ------',
+    '------ ------ ------ 0052fb 002afb ------ 005dfc 0048fc 003ffb 214cfb 495bfa 716cfa 9e87fa cda7fb e4acfb be6efc ------ ------ ------ ------',
+    '------ ------ ------ ------ 0073fc 0074fc 0052fc 003bfc 0046fb 184ffa 3858fa 5a64fa 8478fa b295fb cda0fb b778fb 903cfb ------ ------ ------',
+    '------ ------ ------ 008dfc 008cfc 0078fc 0033fc 003dfb 0047fb 0e4efa 2955fa 475dfa 6f6dfb 9e88fb ba95fb a873fa 8745fb 641bfb ------ ------',
+    '------ ------ 00a1fc 00a2fc 0097fc 005afc 0032fc 003bfb 0042fb 2863fb 88a1fc fafafc fafafc fafafc 1806fc 310ffc 4c18fb 561bfc 4007fc ------',
+    '------ ------ 00b5fc 00a9fc 0098fc 0043fc 002ffc 0045fc fafafc fafafc fafafc fafafc fafafc fafafc 6250fc 1000fc 2800fc 4000fc 4b00fc ------',
+    '------ 00c2fc 00bbfc 00a8fc 0094fc 003cfc 003efc fafafc fafafc fafafc fafafc fafafc fafafc fafafc fafafc 3300fb 5000fb 6f01fb 8500fc ------',
+    '------ 00cffc 00bbfc 00a7fc 0090fc 0044fc fafafc fafafc 012fc3 fafafc fafafc 012fc6 fafafc fafafc fafafc 4a02fb 6707fb 840afb 9807fb ------',
+    '------ 00d4fc 00bcfc 00a7fc 0091fc 1195fc fafafc fafafc 012fc3 fafafc fafafc 012fc6 fafafc fafafc 4a26fb 4707fa 640bfa 7e0dfa 9108fb ------',
+    '------ 00d6fc 00c0fc 00abfc 0096fc 73cdfc fafafc fafafc fafafc fafafc fafafc fafafc fafafc 3330fc 2105fb 3b07fa 5608fa 6f09fa 7d00fb ------',
+    '------ 00d8fc 00c5fc 00b3fc 009efc b1e7fc fafafc fafafc fafafc 0044fc 000bfc 000afc 0008fc 0007fc 1506fb 2d05fb 4405fa 5700fa ------ ------',
+    '------ 00d5fc 00cafc 00b7fc 00b5fc c2effc fafafc fafafc 0c50fc 000dfc 000afc 0009fc 0009fc 0008fb 0804fb 1d00fb 2e00fb 3b00fb ------ ------',
+    '------ ------ 00c3fc 00b4fc 63d2fc bdeafc fafafc bed1fc 003afc 000dfc 000afc 000afc 0009fc 0007fc 0000fb 0a00fb 1600fb ------ ------ ------',
+    '------ ------ ------ 3dc6fc 74ccfc a8d9fc c0dbfc abc5fc 4579fc 001cfc 000bfc 0009fc 0007fc 0000fc 0000fb ------ ------ ------ ------ ------',
+    '------ ------ ------ ------ 80d7fc 95ccfc a3c4fc 97affc 6e88fc 3557fc ------ ------ ------ ------ ------ ------ ------ ------ ------ ------',
+    '------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ ------',
+];
+/** Wordmark gradient stops, left to right, sampled from the symbol. */
+export const GRADIENT = [
+    [1, 212, 251],
+    [38, 91, 251],
+    [140, 58, 251],
+];

package/dist/banner.d.ts

@@ -0,0 +1,25 @@
+export type ColourDepth = 'truecolor' | '256' | 'none';
+/** The stream facts the banner needs (a tty.WriteStream has all of them). */
+export interface BannerStream {
+    isTTY?: boolean;
+    columns?: number;
+    getColorDepth?: (env?: NodeJS.ProcessEnv) => number;
+    write(text: string): unknown;
+}
+/** Below this many columns only the symbol and the title line; below NARROW only the title. */
+export declare const FULL_WIDTH = 70;
+export declare const NARROW_WIDTH = 30;
+/** Why the banner is off for this stream, or undefined when it shows. */
+export declare function bannerBlocked(stream: BannerStream, json: boolean, env?: NodeJS.ProcessEnv): string | undefined;
+/** truecolor with COLORTERM=truecolor/24bit (or Node's own detection), 256 colours, or none. */
+export declare function colourDepth(stream: BannerStream, env?: NodeJS.ProcessEnv): ColourDepth;
+/**
+ * The banner text for a colour depth and terminal width (ends with a blank line). Without
+ * colour it is the one plain title line.
+ */
+export declare function renderBanner(depth: ColourDepth, columns: number, version?: string): string;
+/**
+ * Writes the banner to `stream` (stderr: stdout carries results) when it may show there.
+ * Returns whether it was written.
+ */
+export declare function writeBanner(stream: BannerStream, json: boolean, env?: NodeJS.ProcessEnv): boolean;

package/dist/banner.js

@@ -0,0 +1,202 @@
+/**
+ * The start-screen banner: the Dokebi symbol (pre-rendered half-block art, banner-art.ts) beside
+ * a gradient «DOKEBI» wordmark, then `Dokebi CLI v<version>` and one hint line. People only: it
+ * goes to stderr, and only on a TTY without --json, CI, NO_COLOR, TERM=dumb or
+ * DOKEBI_NO_BANNER, so stdout and every machine-readable output stay byte-identical.
+ */
+import { GRADIENT, SYMBOL_PIXELS } from './banner-art.js';
+import { debug } from './diagnostics.js';
+import { CLI_VERSION } from './output.js';
+/** «DOKEBI» in the ANSI Shadow block font: `█` is the letter, the box lines are its shadow. */
+const WORDMARK = [
+    '██████╗  ██████╗ ██╗  ██╗███████╗██████╗ ██╗',
+    '██╔══██╗██╔═══██╗██║ ██╔╝██╔════╝██╔══██╗██║',
+    '██║  ██║██║   ██║█████╔╝ █████╗  ██████╔╝██║',
+    '██║  ██║██║   ██║██╔═██╗ ██╔══╝  ██╔══██╗██║',
+    '██████╔╝╚██████╔╝██║  ██╗███████╗██████╔╝██║',
+    '╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═════╝ ╚═╝',
+];
+const HINT = 'New here? Run: dokebi guide · Help: dokebi --help';
+const GAP = 3;
+/** Below this many columns only the symbol and the title line; below NARROW only the title. */
+export const FULL_WIDTH = 70;
+export const NARROW_WIDTH = 30;
+const RESET = '\x1b[0m';
+const BOLD_WHITE = '\x1b[1;97m';
+const DIM = '\x1b[2m';
+/** A set environment flag: present, non-empty and not `0`/`false`. */
+function flag(value) {
+    return value !== undefined && value !== '' && value !== '0' && value.toLowerCase() !== 'false';
+}
+/** Why the banner is off for this stream, or undefined when it shows. */
+export function bannerBlocked(stream, json, env = process.env) {
+    if (json)
+        return '--json';
+    if (!stream.isTTY)
+        return 'not a TTY';
+    if (flag(env.DOKEBI_NO_BANNER))
+        return 'DOKEBI_NO_BANNER';
+    if (flag(env.CI))
+        return 'CI';
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+        return 'NO_COLOR';
+    if (env.TERM === 'dumb')
+        return 'TERM=dumb';
+    return undefined;
+}
+/** truecolor with COLORTERM=truecolor/24bit (or Node's own detection), 256 colours, or none. */
+export function colourDepth(stream, env = process.env) {
+    const colorterm = env.COLORTERM?.toLowerCase();
+    if (colorterm === 'truecolor' || colorterm === '24bit')
+        return 'truecolor';
+    const depth = stream.getColorDepth?.(env) ?? 1;
+    return depth >= 24 ? 'truecolor' : depth >= 8 ? '256' : 'none';
+}
+/** Nearest xterm-256 index: the 6×6×6 cube or the 24-step grey ramp. */
+function to256([r, g, b]) {
+    const levels = [0, 95, 135, 175, 215, 255];
+    const nearest = (value) => levels.reduce((best, level, index) => Math.abs(level - value) < Math.abs(levels[best] - value) ? index : best, 0);
+    const [ri, gi, bi] = [nearest(r), nearest(g), nearest(b)];
+    const cube = [levels[ri], levels[gi], levels[bi]];
+    const grey = Math.max(0, Math.min(23, Math.round(((r + g + b) / 3 - 8) / 10)));
+    const greyValue = 8 + grey * 10;
+    const error = (c) => (c[0] - r) ** 2 + (c[1] - g) ** 2 + (c[2] - b) ** 2;
+    return error([greyValue, greyValue, greyValue]) < error(cube)
+        ? 232 + grey
+        : 16 + 36 * ri + 6 * gi + bi;
+}
+function colour(rgb, depth, background = false) {
+    if (depth === 'truecolor')
+        return `\x1b[${background ? 48 : 38};2;${rgb.join(';')}m`;
+    return `\x1b[${background ? 48 : 38};5;${to256(rgb)}m`;
+}
+function parsePixel(value) {
+    if (value === '------')
+        return undefined;
+    const n = Number.parseInt(value, 16);
+    return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+}
+/**
+ * The symbol as text rows of equal width: each cell is two pixels (▀ top in the foreground,
+ * bottom in the background; ▄ or █ when one colour). Codes are written only when they change,
+ * and the transparent tail of a row comes after the reset (so it can be trimmed).
+ */
+function symbolRows(depth) {
+    const pixels = SYMBOL_PIXELS.map((row) => row.split(' ').map(parsePixel));
+    const rows = [];
+    for (let y = 0; y < pixels.length; y += 2) {
+        const top = pixels[y] ?? [];
+        const bottom = pixels[y + 1] ?? [];
+        let line = '';
+        let pending = 0;
+        let state = RESET;
+        let background = false;
+        for (let x = 0; x < top.length; x++) {
+            const upper = top[x];
+            const lower = bottom[x];
+            if (!upper && !lower) {
+                pending++;
+                continue;
+            }
+            let code;
+            let char;
+            if (upper && lower && upper.join() !== lower.join()) {
+                code = `${colour(upper, depth)}${colour(lower, depth, true)}`;
+                char = '▀';
+            }
+            else {
+                code = `${RESET}${colour((upper ?? lower), depth)}`;
+                char = !lower ? '▀' : !upper ? '▄' : '█';
+            }
+            if (pending) {
+                // Gaps must not carry the previous cell's background colour.
+                if (background) {
+                    line += RESET;
+                    state = RESET;
+                    background = false;
+                }
+                line += ' '.repeat(pending);
+                pending = 0;
+            }
+            if (code !== state)
+                line += code;
+            state = code;
+            background = char === '▀' && Boolean(upper && lower && upper.join() !== lower.join());
+            line += char;
+        }
+        rows.push(`${line}${RESET}${' '.repeat(pending)}`);
+    }
+    return rows;
+}
+/** Linear interpolation across the gradient stops, t in [0, 1]. */
+function gradientAt(t) {
+    const span = GRADIENT.length - 1;
+    const index = Math.min(span - 1, Math.floor(t * span));
+    const local = t * span - index;
+    const from = GRADIENT[index];
+    const to = GRADIENT[index + 1];
+    return [0, 1, 2].map((i) => Math.round(from[i] + (to[i] - from[i]) * local));
+}
+/** The wordmark with a horizontal gradient; shadow strokes are a darker shade of the same. */
+function wordmarkRows(depth) {
+    const width = Math.max(...WORDMARK.map((row) => [...row].length));
+    return WORDMARK.map((row) => {
+        let line = '';
+        let last = '';
+        [...row].forEach((char, x) => {
+            if (char === ' ') {
+                line += ' ';
+                return;
+            }
+            const base = gradientAt(x / (width - 1));
+            const rgb = char === '█' ? base : base.map((v) => Math.round(v * 0.5));
+            const code = colour(rgb, depth);
+            if (code !== last)
+                line += code;
+            last = code;
+            line += char;
+        });
+        return line.trimEnd() + RESET;
+    });
+}
+function titleLine(depth, version) {
+    return depth === 'none'
+        ? `Dokebi CLI v${version}`
+        : `${BOLD_WHITE}Dokebi CLI${RESET} ${colour([140, 140, 150], depth)}v${version}${RESET}`;
+}
+/**
+ * The banner text for a colour depth and terminal width (ends with a blank line). Without
+ * colour it is the one plain title line.
+ */
+export function renderBanner(depth, columns, version = CLI_VERSION) {
+    const title = titleLine(depth, version);
+    if (depth === 'none' || columns < NARROW_WIDTH)
+        return `${title}\n`;
+    const symbol = symbolRows(depth);
+    if (columns < FULL_WIDTH)
+        return `\n${symbol.map((line) => line.trimEnd()).join('\n')}\n\n${title}\n\n`;
+    const word = wordmarkRows(depth);
+    const offset = Math.floor((symbol.length - word.length) / 2);
+    const rows = symbol.map((line, index) => {
+        const mark = word[index - offset];
+        return mark ? `${line}${' '.repeat(GAP)}${mark}` : line;
+    });
+    return `\n${rows.join('\n')}\n\n${title}\n${DIM}${HINT}${RESET}\n\n`;
+}
+/**
+ * Writes the banner to `stream` (stderr: stdout carries results) when it may show there.
+ * Returns whether it was written.
+ */
+export function writeBanner(stream, json, env = process.env) {
+    const blocked = bannerBlocked(stream, json, env);
+    if (blocked) {
+        debug('Banner skipped', { reason: blocked });
+        return false;
+    }
+    const depth = colourDepth(stream, env);
+    // A pty with no window size reports 0 columns: treat it as unknown.
+    const columns = stream.columns || 80;
+    debug('Banner shown', { depth, columns });
+    stream.write(renderBanner(depth, columns));
+    return true;
+}

package/dist/bin.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export {};
+/** Close names for an unknown command: same prefix or at most 2 edits (up to 3, best first). */
+export declare function suggest(input: string, names: readonly string[]): string[];