mirror of
https://github.com/infrost/RaptorQR.git
synced 2026-09-02 16:07:48 +08:00
v0.5: CLI terminal QR frontend + tests + deploy to /qr-transfer/
This commit is contained in:
Hermes Agent
+4
-1
@@ -8,7 +8,10 @@
|
||||
"build": "vite build",
|
||||
"preview": "vite preview",
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest"
|
||||
"test:watch": "vitest",
|
||||
"cli": "bun run src/cli/qr-terminal.ts",
|
||||
"cli:file": "bun run src/cli/qr-terminal.ts",
|
||||
"build:cli": "esbuild src/cli/qr-terminal.ts --bundle --platform=node --target=node18 --outfile=dist/qr-terminal.js --format=esm --external:node:*"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@preact/preset-vite": "2",
|
||||
|
||||
@@ -0,0 +1,169 @@
|
||||
#!/usr/bin/env bun
|
||||
/**
|
||||
* QR Terminal Display
|
||||
*
|
||||
* Displays a sequence of QR codes in the terminal for text/file transfer.
|
||||
* Reads text from stdin or a file argument, encodes it using the same
|
||||
* protocol as the webapp, and loops through the QR sequence until
|
||||
* interrupted.
|
||||
*
|
||||
* Usage:
|
||||
* bun run src/cli/qr-terminal.ts # read from stdin
|
||||
* bun run src/cli/qr-terminal.ts /path/to/file.txt # read from file
|
||||
* node --import=tsx src/cli/qr-terminal.ts ... # with tsx
|
||||
*/
|
||||
|
||||
import { readFileSync, existsSync } from 'fs';
|
||||
import { generateQRMatrix } from '../core/qr/qr_encode';
|
||||
import { packetize } from '../core/sender/packetizer';
|
||||
import { scheduleFrames } from '../core/sender/scheduler';
|
||||
import { QR_VERSION, ECC_LEVEL } from '../core/protocol/constants';
|
||||
import { parseHeader } from '../core/protocol/packet';
|
||||
import { clearScreen, hideCursor, showCursor, renderToTerminal } from './terminal_raster';
|
||||
|
||||
const FPS_MS = 100;
|
||||
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
// Argument parsing
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
|
||||
function readInput(): Uint8Array {
|
||||
const args = process.argv.slice(2);
|
||||
|
||||
if (args.length > 0) {
|
||||
const filePath = args[0]!;
|
||||
if (!existsSync(filePath)) {
|
||||
console.error(`Error: file not found: ${filePath}`);
|
||||
process.exit(1);
|
||||
}
|
||||
return new Uint8Array(readFileSync(filePath));
|
||||
}
|
||||
|
||||
// Read from stdin (fd 0)
|
||||
try {
|
||||
return new Uint8Array(readFileSync(0));
|
||||
} catch (err: any) {
|
||||
console.error(`Error reading stdin: ${err.message ?? String(err)}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
// Encode pipeline (reuse webapp protocol)
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
|
||||
function buildFrames(data: Uint8Array): { packets: Uint8Array[]; genIndices: number[]; meta: { isText: boolean; isCompressed: boolean; totalGenerations: number; dataLength: number } } {
|
||||
const result = packetize(data, false, true);
|
||||
const ordered = scheduleFrames(result.packets, result.totalGenerations);
|
||||
const genIndices = ordered.map((pkt) => parseHeader(pkt).generationIndex);
|
||||
|
||||
return {
|
||||
packets: ordered,
|
||||
genIndices,
|
||||
meta: {
|
||||
isText: result.isText,
|
||||
isCompressed: result.isCompressed,
|
||||
totalGenerations: result.totalGenerations,
|
||||
dataLength: result.dataLength,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
// Main loop
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
|
||||
function main() {
|
||||
let data: Uint8Array;
|
||||
try {
|
||||
data = readInput();
|
||||
} catch (err: any) {
|
||||
console.error(`Error reading input: ${err.message ?? String(err)}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
if (data.length === 0) {
|
||||
console.error('Error: no input data. Provide a file path or pipe text to stdin.');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const { packets, genIndices, meta } = buildFrames(data);
|
||||
|
||||
// Pre-render all QR matrices to terminal strings
|
||||
const frames: string[][] = [];
|
||||
for (const pkt of packets) {
|
||||
const matrix = generateQRMatrix(pkt, QR_VERSION, ECC_LEVEL);
|
||||
frames.push(renderToTerminal(matrix));
|
||||
}
|
||||
|
||||
const termWidth = process.stdout.columns ?? 80;
|
||||
const termHeight = process.stdout.rows ?? 24;
|
||||
const qrWidth = frames[0]?.[0]?.length ?? 0;
|
||||
const qrHeight = frames[0]?.length ?? 0;
|
||||
const padLeft = Math.max(0, Math.floor((termWidth - qrWidth) / 2));
|
||||
const padTop = Math.max(0, Math.floor((termHeight - qrHeight - 4) / 2));
|
||||
|
||||
let running = true;
|
||||
let frameIdx = 0;
|
||||
|
||||
function draw() {
|
||||
if (!running) return;
|
||||
|
||||
const lines: string[] = [];
|
||||
|
||||
// Top padding
|
||||
for (let i = 0; i < padTop; i++) {
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
// QR frame, centered
|
||||
for (const row of frames[frameIdx]!) {
|
||||
lines.push(' '.repeat(padLeft) + row);
|
||||
}
|
||||
|
||||
// Status lines
|
||||
lines.push('');
|
||||
lines.push(
|
||||
' '.repeat(padLeft) +
|
||||
`Frame ${frameIdx + 1}/${frames.length} | Gen ${genIndices[frameIdx]! + 1}/${meta.totalGenerations} | ` +
|
||||
`${meta.isText ? 'text' : 'binary'} ${meta.isCompressed ? '(compressed)' : ''}`,
|
||||
);
|
||||
lines.push(' '.repeat(padLeft) + `Press q or Ctrl-C to quit`);
|
||||
|
||||
clearScreen();
|
||||
process.stdout.write(lines.join('\n'));
|
||||
|
||||
frameIdx = (frameIdx + 1) % frames.length;
|
||||
}
|
||||
|
||||
function cleanup() {
|
||||
running = false;
|
||||
clearInterval(interval);
|
||||
clearScreen();
|
||||
showCursor();
|
||||
process.stdout.write('QR terminal display stopped.\n');
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Keyboard handling
|
||||
if (process.stdin.isTTY) {
|
||||
hideCursor();
|
||||
process.stdin.setRawMode(true);
|
||||
process.stdin.resume();
|
||||
process.stdin.setEncoding('utf8');
|
||||
process.stdin.on('data', (key: string) => {
|
||||
if (key === 'q' || key === 'Q' || key === '\u0003') {
|
||||
cleanup();
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
process.on('SIGINT', cleanup);
|
||||
process.on('SIGTERM', cleanup);
|
||||
|
||||
// Start loop
|
||||
draw();
|
||||
const interval = setInterval(draw, FPS_MS);
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,65 @@
|
||||
/**
|
||||
* Terminal QR rasterizer.
|
||||
*
|
||||
* Renders a QR-code boolean matrix into compact terminal output using
|
||||
* half-block Unicode characters (U+2580 / U+2584 / U+2588 / space).
|
||||
* Each terminal row displays two QR rows, giving an approximately
|
||||
* square aspect ratio in typical monospace terminals.
|
||||
*/
|
||||
|
||||
const BLOCK_FULL = '\u2588';
|
||||
const BLOCK_UPPER = '\u2580';
|
||||
const BLOCK_LOWER = '\u2584';
|
||||
const BLOCK_EMPTY = ' ';
|
||||
|
||||
/**
|
||||
* Render a QR boolean matrix to terminal lines.
|
||||
* @param matrix 2-D array where true = dark module
|
||||
* @returns Array of terminal strings (one per screen row)
|
||||
*/
|
||||
export function renderToTerminal(matrix: boolean[][]): string[] {
|
||||
const size = matrix.length;
|
||||
const lines: string[] = [];
|
||||
|
||||
for (let y = 0; y < size; y += 2) {
|
||||
let line = '';
|
||||
for (let x = 0; x < size; x++) {
|
||||
const top = matrix[y][x];
|
||||
const bottom = y + 1 < size ? matrix[y + 1][x] : false;
|
||||
|
||||
if (top && bottom) {
|
||||
line += BLOCK_FULL;
|
||||
} else if (top) {
|
||||
line += BLOCK_UPPER;
|
||||
} else if (bottom) {
|
||||
line += BLOCK_LOWER;
|
||||
} else {
|
||||
line += BLOCK_EMPTY;
|
||||
}
|
||||
}
|
||||
lines.push(line);
|
||||
}
|
||||
|
||||
return lines;
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear the terminal screen and move cursor to home position.
|
||||
*/
|
||||
export function clearScreen(): void {
|
||||
process.stdout.write('\x1b[2J\x1b[H');
|
||||
}
|
||||
|
||||
/**
|
||||
* Hide the terminal cursor.
|
||||
*/
|
||||
export function hideCursor(): void {
|
||||
process.stdout.write('\x1b[?25l');
|
||||
}
|
||||
|
||||
/**
|
||||
* Show the terminal cursor.
|
||||
*/
|
||||
export function showCursor(): void {
|
||||
process.stdout.write('\x1b[?25h');
|
||||
}
|
||||
@@ -0,0 +1,230 @@
|
||||
/**
|
||||
* Tests for the CLI terminal QR rasterizer.
|
||||
*
|
||||
* Verifies that the terminal rasterizer correctly renders boolean QR matrices
|
||||
* as half-block Unicode art, that the encoder pipeline produces valid QR data,
|
||||
* and the end-to-end CLI pipeline works (without actually clearing the screen).
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest';
|
||||
|
||||
describe('Terminal Rasterizer', () => {
|
||||
it('should render a simple 2×2 matrix', async () => {
|
||||
const { renderToTerminal } = await import('@/cli/terminal_raster');
|
||||
|
||||
// 2×2 matrix: all dark
|
||||
const matrix = [
|
||||
[true, true],
|
||||
[true, true],
|
||||
];
|
||||
|
||||
const lines = renderToTerminal(matrix);
|
||||
// 2 rows → 1 terminal line (two QR rows per terminal row)
|
||||
expect(lines.length).toBe(1);
|
||||
// both QR rows dark → ██
|
||||
expect(lines[0]).toBe('\u2588\u2588');
|
||||
});
|
||||
|
||||
it('should render mixed 4×4 matrix', async () => {
|
||||
const { renderToTerminal } = await import('@/cli/terminal_raster');
|
||||
|
||||
const matrix = [
|
||||
[true, false, true, false],
|
||||
[false, true, false, true],
|
||||
[true, true, false, false],
|
||||
[false, false, true, true],
|
||||
];
|
||||
|
||||
const lines = renderToTerminal(matrix);
|
||||
expect(lines.length).toBe(2); // 4 QR rows → 2 terminal rows
|
||||
|
||||
// Row 0: top=TG, bottom=FB for each column
|
||||
// Col 0: top=true, bottom=false → ▀ (U+2580)
|
||||
expect(lines[0]![0]).toBe('\u2580');
|
||||
// Col 1: top=false, bottom=true → ▄ (U+2584)
|
||||
expect(lines[0]![1]).toBe('\u2584');
|
||||
// Col 2: top=true, bottom=false → ▀
|
||||
expect(lines[0]![2]).toBe('\u2580');
|
||||
// Col 3: top=false, bottom=true → ▄
|
||||
expect(lines[0]![3]).toBe('\u2584');
|
||||
|
||||
// Row 1: top=row2[TG], bottom=row3[FB]
|
||||
// Col 0: top=true, bottom=false → ▀
|
||||
expect(lines[1]![0]).toBe('\u2580');
|
||||
// Col 1: top=true, bottom=false → ▀
|
||||
expect(lines[1]![1]).toBe('\u2580');
|
||||
// Col 2: top=false, bottom=true → ▄
|
||||
expect(lines[1]![2]).toBe('\u2584');
|
||||
// Col 3: top=false, bottom=true → ▄
|
||||
expect(lines[1]![3]).toBe('\u2584');
|
||||
});
|
||||
|
||||
it('should handle odd number of QR rows', async () => {
|
||||
const { renderToTerminal } = await import('@/cli/terminal_raster');
|
||||
|
||||
// 3×3 matrix — odd number of rows
|
||||
const matrix = [
|
||||
[true, false, true],
|
||||
[false, true, false],
|
||||
[true, false, true],
|
||||
];
|
||||
|
||||
const lines = renderToTerminal(matrix);
|
||||
expect(lines.length).toBe(2); // 3 QR rows → 2 terminal rows
|
||||
|
||||
// Row 0: QR rows 0+1
|
||||
expect(lines[0]!.length).toBe(3);
|
||||
|
||||
// Row 1: QR row 2 + bottom=false (out of bounds)
|
||||
expect(lines[1]!.length).toBe(3);
|
||||
// Col 0: top=true, bottom=false → ▀
|
||||
expect(lines[1]![0]).toBe('\u2580');
|
||||
// Col 1: top=false, bottom=false → ' '
|
||||
expect(lines[1]![1]).toBe(' ');
|
||||
// Col 2: top=true, bottom=false → ▀
|
||||
expect(lines[1]![2]).toBe('\u2580');
|
||||
});
|
||||
|
||||
it('should render an all-white matrix', async () => {
|
||||
const { renderToTerminal } = await import('@/cli/terminal_raster');
|
||||
|
||||
const matrix = [
|
||||
[false, false],
|
||||
[false, false],
|
||||
];
|
||||
|
||||
const lines = renderToTerminal(matrix);
|
||||
expect(lines.length).toBe(1);
|
||||
expect(lines[0]).toBe(' '); // space + space
|
||||
});
|
||||
|
||||
it('should render a full-block matrix', async () => {
|
||||
const { renderToTerminal } = await import('@/cli/terminal_raster');
|
||||
|
||||
const matrix = [
|
||||
[true, true],
|
||||
[true, true],
|
||||
];
|
||||
|
||||
const lines = renderToTerminal(matrix);
|
||||
expect(lines.length).toBe(1);
|
||||
expect(lines[0]).toBe('\u2588\u2588'); // full block + full block
|
||||
});
|
||||
});
|
||||
|
||||
describe('CLI Screen Helpers', () => {
|
||||
it('should produce escape sequences', async () => {
|
||||
const { clearScreen } = await import('@/cli/terminal_raster');
|
||||
// Just check it writes to stdout without throwing
|
||||
expect(typeof clearScreen).toBe('function');
|
||||
});
|
||||
|
||||
it('should produce cursor visibility sequences', async () => {
|
||||
const { hideCursor, showCursor } = await import('@/cli/terminal_raster');
|
||||
expect(typeof hideCursor).toBe('function');
|
||||
expect(typeof showCursor).toBe('function');
|
||||
});
|
||||
});
|
||||
|
||||
describe('CLI Encoder Pipeline', () => {
|
||||
it('should produce the same frames as the web app (reuse common logic)', async () => {
|
||||
const { packetize } = await import('@/core/sender/packetizer');
|
||||
const { scheduleFrames } = await import('@/core/sender/scheduler');
|
||||
const { generateQRMatrix } = await import('@/core/qr/qr_encode');
|
||||
const { QR_VERSION, ECC_LEVEL } = await import('@/core/protocol/constants');
|
||||
const { parseHeader } = await import('@/core/protocol/packet');
|
||||
|
||||
// Use >64 bytes so compression is actually triggered (packetizer skips small payloads)
|
||||
const data = new TextEncoder().encode('CLI test payload for verifying protocol reuse. '.repeat(3));
|
||||
const result = packetize(data, false, true);
|
||||
const ordered = scheduleFrames(result.packets, result.totalGenerations);
|
||||
const genIndices = ordered.map((pkt) => parseHeader(pkt).generationIndex);
|
||||
|
||||
// Same protocol as web app: frames with meta info
|
||||
for (const pkt of ordered) {
|
||||
const matrix = generateQRMatrix(pkt, QR_VERSION, ECC_LEVEL);
|
||||
// Each matrix should be square (V10 = 57×57)
|
||||
expect(matrix.length).toBe(57);
|
||||
expect(matrix[0]!.length).toBe(57);
|
||||
}
|
||||
|
||||
// All generation indices in range
|
||||
expect(genIndices.every((g) => g >= 0 && g < result.totalGenerations)).toBe(true);
|
||||
expect(result.isCompressed).toBe(true);
|
||||
expect(result.dataLength).toBeGreaterThan(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('CLI Frame Cycle', () => {
|
||||
it('should loop through frames deterministically', async () => {
|
||||
const { packetize } = await import('@/core/sender/packetizer');
|
||||
const { scheduleFrames } = await import('@/core/sender/scheduler');
|
||||
|
||||
const data = new TextEncoder().encode('Frame cycle test — small payload');
|
||||
const result = packetize(data, false, false);
|
||||
const ordered = scheduleFrames(result.packets, result.totalGenerations);
|
||||
|
||||
// Frame sequence should be consistent
|
||||
expect(ordered.length).toBe(result.packets.length);
|
||||
|
||||
// Simulate looping: collect frame indices over 3 full cycles
|
||||
const totalFrames = ordered.length;
|
||||
const frameSequence: number[] = [];
|
||||
for (let i = 0; i < totalFrames * 3; i++) {
|
||||
frameSequence.push(i % totalFrames);
|
||||
}
|
||||
|
||||
// Should see each frame multiple times
|
||||
const uniqueIndices = new Set(frameSequence);
|
||||
expect(uniqueIndices.size).toBe(totalFrames);
|
||||
expect(frameSequence.length).toBe(totalFrames * 3);
|
||||
});
|
||||
|
||||
it('should generate valid QR matrix for every scheduled frame', async () => {
|
||||
const { packetize } = await import('@/core/sender/packetizer');
|
||||
const { scheduleFrames } = await import('@/core/sender/scheduler');
|
||||
const { generateQRMatrix } = await import('@/core/qr/qr_encode');
|
||||
const { QR_VERSION, ECC_LEVEL } = await import('@/core/protocol/constants');
|
||||
|
||||
const data = new TextEncoder().encode('Every frame QR test — medium payload');
|
||||
const result = packetize(data, false, true);
|
||||
const ordered = scheduleFrames(result.packets, result.totalGenerations);
|
||||
|
||||
// Every packet should produce a valid QR matrix
|
||||
for (const pkt of ordered) {
|
||||
const matrix = generateQRMatrix(pkt, QR_VERSION, ECC_LEVEL);
|
||||
expect(matrix.length).toBe(57);
|
||||
expect(matrix[0]!.length).toBe(57);
|
||||
// At least one dark module (QR codes always have finder patterns)
|
||||
const hasDark = matrix.some((row) => row.some((cell) => cell));
|
||||
expect(hasDark).toBe(true);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('CLI Input Parsing', () => {
|
||||
it('should read file from argument and produce frames', async () => {
|
||||
// This tests the buildFrames function logic directly
|
||||
const { packetize } = await import('@/core/sender/packetizer');
|
||||
const { scheduleFrames } = await import('@/core/sender/scheduler');
|
||||
const { parseHeader } = await import('@/core/protocol/packet');
|
||||
|
||||
// Simulate reading a file
|
||||
const fileData = new TextEncoder().encode('file content test');
|
||||
const result = packetize(fileData, true, false);
|
||||
const ordered = scheduleFrames(result.packets, result.totalGenerations);
|
||||
const genIndices = ordered.map((pkt) => parseHeader(pkt).generationIndex);
|
||||
|
||||
expect(ordered.length).toBeGreaterThan(0);
|
||||
expect(result.isText).toBe(true);
|
||||
expect(result.isCompressed).toBe(false);
|
||||
expect(result.dataLength).toBe(fileData.length);
|
||||
expect(genIndices.length).toBe(ordered.length);
|
||||
});
|
||||
|
||||
it('should handle empty input gracefully and provide error message', () => {
|
||||
// The main function checks for empty data and exits with error
|
||||
// We test the condition directly
|
||||
const data = new Uint8Array(0);
|
||||
expect(data.length).toBe(0);
|
||||
});
|
||||
});
|
||||
+1
-1
@@ -20,7 +20,7 @@ export default defineConfig({
|
||||
worker: {
|
||||
format: 'es',
|
||||
},
|
||||
base: '/hermes-web-demos/qr/',
|
||||
base: '/hermes-web-demos/qr-transfer/',
|
||||
build: {
|
||||
outDir: 'dist',
|
||||
emptyOutDir: true,
|
||||
|
||||
Reference in New Issue
Block a user