@bitmagic/cli 0.1.53-dev.1 → 0.1.53-dev.11

package/dist/render/qr-terminal.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Drawing a QR code into the terminal, so the URL `bitmagic publish` just printed can be scanned
+ * off the screen instead of retyped into a phone. The Creator has had this since it shipped — the
+ * publish dialog ends on a QR — and the CLI's publish is the same moment: `--visibility private`
+ * puts a real, phone-reachable URL on a game nobody else can find, which is exactly a "try it on
+ * my phone" build.
+ *
+ * The contract is `inline-image.ts`'s, deliberately: the code is strictly ADDITIONAL. The caller
+ * prints the URL first, unconditionally; this either draws underneath it or does nothing at all. It
+ * never replaces a line and it never reports failure as an error, because an agent tool is usually
+ * what reads this output.
+ *
+ * That last clause is also why nothing should call this module directly. Refusing to DRAW into a
+ * pipe is right; having nothing to offer when there is one is not, and since an agent drives most
+ * publishes, the pipe is the common case rather than the edge. `qr-output.ts` owns that decision —
+ * it asks this module first and falls back to a PNG file — and `bitmagic publish` goes through it.
+ *
+ * Where it DIVERGES from that file is the gate. `supportsInlineImage` is an allowlist of terminals
+ * known to implement the iTerm2 protocol, because the ones that do not print a screenful of raw
+ * base64. Nothing here is exotic: half-block characters and SGR colour are universal, and tmux
+ * passes both through rather than swallowing them. So the gate below asks what the terminal can do
+ * — is it a terminal at all, is it wide enough — and never who it is.
+ */
+export interface TerminalQrEnv {
+    TERM?: string | undefined;
+    BITMAGIC_NO_QR?: string | undefined;
+}
+/**
+ * Whether this terminal can show a scannable code at all.
+ *
+ * Not an allowlist — see the file header. `TERM=dumb` is the one terminal that answers no on its
+ * own behalf, and a non-TTY means something is reading this rather than looking at it — which is a
+ * reason not to paint escape sequences, NOT a reason to withhold the code. `qr-output.ts` writes an
+ * image for every case this function turns down.
+ */
+export declare function supportsTerminalQr(env: TerminalQrEnv, isTTY: boolean): boolean;
+/** How many columns the drawn code occupies, quiet zone included. */
+export declare function terminalQrWidth(matrix: boolean[][]): number;
+/**
+ * The code as terminal lines, quiet zone included and each line self-contained.
+ *
+ * Exported so a test can read the output without a TTY. The padded symbol has an odd number of
+ * module rows — the module count is always odd and the quiet zone adds an even number — so the
+ * final terminal row pairs its top half against a light row that is not in the symbol. That is
+ * correct rather than a rounding artefact: it reads as one more row of quiet zone.
+ */
+export declare function terminalQrLines(matrix: boolean[][]): string[];
+export interface RenderTerminalQrOptions {
+    env?: TerminalQrEnv;
+    isTTY?: boolean;
+    /** Terminal width. Undefined means unknown, which is treated as wide enough. */
+    columns?: number | undefined;
+    write?: (chunk: string) => void;
+    caption?: string;
+}
+/**
+ * Draw `text` as a QR code if this terminal can show one. Returns whether anything was drawn, so a
+ * caller can decide what else to say — never throws, and never writes when unsupported.
+ *
+ * The caption and the code go out in a single write, so the creator never sees an invitation to
+ * scan with nothing under it.
+ */
+export declare function renderTerminalQr(text: string, options?: RenderTerminalQrOptions): boolean;

package/dist/render/qr-terminal.js

@@ -0,0 +1,142 @@
+/**
+ * Drawing a QR code into the terminal, so the URL `bitmagic publish` just printed can be scanned
+ * off the screen instead of retyped into a phone. The Creator has had this since it shipped — the
+ * publish dialog ends on a QR — and the CLI's publish is the same moment: `--visibility private`
+ * puts a real, phone-reachable URL on a game nobody else can find, which is exactly a "try it on
+ * my phone" build.
+ *
+ * The contract is `inline-image.ts`'s, deliberately: the code is strictly ADDITIONAL. The caller
+ * prints the URL first, unconditionally; this either draws underneath it or does nothing at all. It
+ * never replaces a line and it never reports failure as an error, because an agent tool is usually
+ * what reads this output.
+ *
+ * That last clause is also why nothing should call this module directly. Refusing to DRAW into a
+ * pipe is right; having nothing to offer when there is one is not, and since an agent drives most
+ * publishes, the pipe is the common case rather than the edge. `qr-output.ts` owns that decision —
+ * it asks this module first and falls back to a PNG file — and `bitmagic publish` goes through it.
+ *
+ * Where it DIVERGES from that file is the gate. `supportsInlineImage` is an allowlist of terminals
+ * known to implement the iTerm2 protocol, because the ones that do not print a screenful of raw
+ * base64. Nothing here is exotic: half-block characters and SGR colour are universal, and tmux
+ * passes both through rather than swallowing them. So the gate below asks what the terminal can do
+ * — is it a terminal at all, is it wide enough — and never who it is.
+ */
+import { encodeQr } from './qr.js';
+/** Written as an escape rather than a literal control byte, so the source stays greppable. */
+const ESC = '\u001b';
+/**
+ * Black on bright white, and the reset that closes every line.
+ *
+ * Explicit on purpose. A scanner wants dark modules on a light field, and the creator's terminal is
+ * probably a dark theme — left to inherit, the code would come out inverted, which many scanners
+ * cope with and some do not. The reset ends each line so the colour cannot bleed into a wrapped
+ * line or the prompt. Bright white (107) rather than plain white (47) because the latter is a light
+ * grey in most palettes, and contrast is the one thing a scanner cannot make up for.
+ */
+const PAINT = `${ESC}[30;107m`;
+const RESET = `${ESC}[0m`;
+/**
+ * Quiet-zone width in modules, matching the `margin: 2` the Creator passes `QRCode.toDataURL` —
+ * a value already proven to scan in production. The spec asks for 4; if scans ever prove flaky,
+ * that is the knob, and it costs 4 columns and 1 line.
+ */
+const QUIET_ZONE = 2;
+/**
+ * Two module rows per terminal row, drawn with half-blocks.
+ *
+ * This is what makes the code square. Terminal cells are roughly twice as tall as they are wide, so
+ * one module per cell would stretch the symbol into a rectangle no scanner would read; half-blocks
+ * put two module rows in one cell and bring the aspect ratio back to 1:1.
+ */
+const BOTH_DARK = '█'; // full block
+const TOP_DARK = '▀'; // upper half block
+const BOTTOM_DARK = '▄'; // lower half block
+const BOTH_LIGHT = ' ';
+/**
+ * Whether this terminal can show a scannable code at all.
+ *
+ * Not an allowlist — see the file header. `TERM=dumb` is the one terminal that answers no on its
+ * own behalf, and a non-TTY means something is reading this rather than looking at it — which is a
+ * reason not to paint escape sequences, NOT a reason to withhold the code. `qr-output.ts` writes an
+ * image for every case this function turns down.
+ */
+export function supportsTerminalQr(env, isTTY) {
+    if (!isTTY)
+        return false;
+    if (env.BITMAGIC_NO_QR)
+        return false;
+    return env.TERM !== 'dumb';
+}
+/** How many columns the drawn code occupies, quiet zone included. */
+export function terminalQrWidth(matrix) {
+    return matrix.length + QUIET_ZONE * 2;
+}
+/**
+ * The code as terminal lines, quiet zone included and each line self-contained.
+ *
+ * Exported so a test can read the output without a TTY. The padded symbol has an odd number of
+ * module rows — the module count is always odd and the quiet zone adds an even number — so the
+ * final terminal row pairs its top half against a light row that is not in the symbol. That is
+ * correct rather than a rounding artefact: it reads as one more row of quiet zone.
+ */
+export function terminalQrLines(matrix) {
+    const width = terminalQrWidth(matrix);
+    const height = width;
+    const dark = (row, col) => {
+        const r = row - QUIET_ZONE;
+        const c = col - QUIET_ZONE;
+        if (r < 0 || c < 0 || r >= matrix.length || c >= matrix.length)
+            return false;
+        return matrix[r][c];
+    };
+    const lines = [];
+    for (let row = 0; row < height; row += 2) {
+        let line = '';
+        for (let col = 0; col < width; col += 1) {
+            const top = dark(row, col);
+            const bottom = row + 1 < height && dark(row + 1, col);
+            if (top && bottom)
+                line += BOTH_DARK;
+            else if (top)
+                line += TOP_DARK;
+            else if (bottom)
+                line += BOTTOM_DARK;
+            else
+                line += BOTH_LIGHT;
+        }
+        lines.push(`${PAINT}${line}${RESET}`);
+    }
+    return lines;
+}
+/**
+ * Draw `text` as a QR code if this terminal can show one. Returns whether anything was drawn, so a
+ * caller can decide what else to say — never throws, and never writes when unsupported.
+ *
+ * The caption and the code go out in a single write, so the creator never sees an invitation to
+ * scan with nothing under it.
+ */
+export function renderTerminalQr(text, options = {}) {
+    const env = options.env ?? process.env;
+    const isTTY = options.isTTY ?? process.stdout.isTTY === true;
+    if (!supportsTerminalQr(env, isTTY))
+        return false;
+    const matrix = encodeQr(text);
+    if (matrix === null)
+        return false;
+    // A code wider than the terminal wraps, and a wrapped code is not a code — it is noise that
+    // looks like output. Better to leave the plain URL standing on its own.
+    const columns = options.columns ?? process.stdout.columns;
+    if (typeof columns === 'number' && columns < terminalQrWidth(matrix))
+        return false;
+    const caption = options.caption ?? 'Scan to play on your phone:';
+    const write = options.write ?? ((chunk) => process.stdout.write(chunk));
+    try {
+        write(`\n${caption}\n\n${terminalQrLines(matrix).join('\n')}\n\n`);
+        return true;
+    }
+    catch {
+        // A closed or non-writable stdout is not worth failing a successful publish over.
+        return false;
+    }
+}
+//# sourceMappingURL=qr-terminal.js.map

package/dist/render/qr-terminal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr-terminal.js","sourceRoot":"","sources":["../../src/render/qr-terminal.ts"],"names":[],"mappings":"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"}

package/dist/render/qr.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A QR encoder, so `bitmagic publish` can hand the creator's phone the URL it just printed.
+ *
+ * The Creator does this server-side already — `PublishController.generateQRCode` calls the `qrcode`
+ * package and the publish dialog shows the PNG. The CLI cannot follow it there: `qrcode` drags in
+ * `dijkstrajs`, `pngjs` and `yargs@15`, and `@bitmagic/cli` is a published package with four
+ * deliberately-chosen runtime dependencies. So the encoder lives here instead, cut down to exactly
+ * what a published-game URL needs:
+ *
+ *   - **Byte mode only.** A URL is bytes. Numeric, alphanumeric and kanji modes would encode it
+ *     smaller in theory and never in practice, because `https://` alone rules out alphanumeric.
+ *   - **Error correction level M only**, matching the Creator's `errorCorrectionLevel: 'M'` — a code
+ *     scanned from this terminal and one scanned from the publish dialog then behave identically.
+ *   - **Versions 1-9 only.** The character-count indicator is 8 bits up to version 9 and 16 bits
+ *     from version 10, so stopping here removes a branch and four tables. Version 9 holds 180 bytes;
+ *     the longest URL this ever sees is the dev portal's, around 60. Anything longer returns null
+ *     rather than growing the tables — see `encodeQr`.
+ *
+ * Structure follows ISO/IEC 18004. Every table below is a literal with the spec's own name for it,
+ * and `__tests__/qr.test.ts` checks each one against fixtures generated by the `qrcode` package, so
+ * a transposed digit fails loudly instead of producing a code that scans as garbage.
+ */
+/**
+ * The spec's four penalty rules (8.8.2), summed. Lower is better.
+ *
+ * Scored over the entire symbol including function patterns, as the spec requires — the finders'
+ * own 1:1:3:1:1 ratio is exactly what rule 3 hunts for elsewhere, and excluding them would let a
+ * mask hide a false finder against a real one.
+ */
+export declare function maskPenalty(matrix: boolean[][]): number;
+/**
+ * Encode `text` with an explicitly chosen mask.
+ *
+ * Exported for the fixture tests, which pin the mask so they compare structure — codewords, ECC,
+ * interleaving, function patterns, format bits — rather than a mask heuristic. Callers outside the
+ * tests want `encodeQr`.
+ */
+export declare function encodeQrWithMask(text: string, mask: number): boolean[][] | null;
+/**
+ * Encode `text` as a matrix of modules, row-major, true meaning dark. Null when it does not fit.
+ *
+ * The mask is chosen by the spec's penalty rules. That choice is a legibility heuristic and not a
+ * correctness property — all eight masks produce a valid, scannable symbol, and a decoder reads the
+ * chosen one out of the format information either way.
+ *
+ * There is no quiet zone here: it belongs to whatever draws the symbol, which knows what it is
+ * drawing onto. `qr-terminal.ts` paints its own.
+ */
+export declare function encodeQr(text: string): boolean[][] | null;
+/** The longest text this encoder can hold, in bytes. Exported so a caller can explain a refusal. */
+export declare const MAX_BYTES: number;