@jungjaehoon/mama-os 0.26.0 → 0.27.1

package/dist/tools/browser-tool.js

@@ -8,6 +8,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BrowserTool = void 0;
 exports.getBrowserTool = getBrowserTool;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
 const DEFAULT_CONFIG = {
     headless: true,
     viewportWidth: 1280,
@@ -69,6 +72,29 @@ class BrowserTool {
         }
         return this.page;
     }
+    screenshotPaths(filename, prefix) {
+        const configuredRoot = (0, node_path_1.resolve)(this.config.screenshotDir);
+        (0, node_fs_1.mkdirSync)(configuredRoot, { recursive: true });
+        const root = (0, node_fs_1.realpathSync)(configuredRoot);
+        const name = filename?.trim() || `${prefix}-${Date.now()}-${(0, node_crypto_1.randomUUID)()}.png`;
+        if (name !== (0, node_path_1.basename)(name)) {
+            throw new Error('Screenshot filename must not contain directory components');
+        }
+        const outputPath = (0, node_path_1.resolve)(root, name);
+        const relativePath = (0, node_path_1.relative)(root, outputPath);
+        if (!relativePath || relativePath.startsWith('..') || (0, node_path_1.isAbsolute)(relativePath)) {
+            throw new Error('Screenshot filename must resolve inside the configured screenshot directory');
+        }
+        return {
+            outputPath,
+            temporaryPath: (0, node_path_1.resolve)(root, `.mama-screenshot-${(0, node_crypto_1.randomUUID)()}.tmp.png`),
+        };
+    }
+    removeOwnedArtifact(path) {
+        if ((0, node_fs_1.existsSync)(path)) {
+            (0, node_fs_1.unlinkSync)(path);
+        }
+    }
     /**
      * Navigate to URL
      */
@@ -86,32 +112,44 @@ class BrowserTool {
     /**
      * Take screenshot
      */
-    async screenshot(filename) {
+    async screenshot(filename, signal) {
+        signal?.throwIfAborted();
         const page = await this.ensureBrowser();
-        const { mkdirSync, existsSync } = await import('fs');
-        if (!existsSync(this.config.screenshotDir)) {
-            mkdirSync(this.config.screenshotDir, { recursive: true });
+        signal?.throwIfAborted();
+        const { outputPath, temporaryPath } = this.screenshotPaths(filename, 'screenshot');
+        try {
+            await page.screenshot({ path: temporaryPath, fullPage: false });
+            signal?.throwIfAborted();
+            (0, node_fs_1.copyFileSync)(temporaryPath, outputPath, node_fs_1.constants.COPYFILE_EXCL);
+            this.removeOwnedArtifact(temporaryPath);
         }
-        const name = filename || `screenshot-${Date.now()}.png`;
-        const path = `${this.config.screenshotDir}/${name}`;
-        await page.screenshot({ path, fullPage: false });
-        console.log(`[Browser] Screenshot saved: ${path}`);
-        return { success: true, path };
+        catch (error) {
+            this.removeOwnedArtifact(temporaryPath);
+            throw error;
+        }
+        console.log(`[Browser] Screenshot saved: ${outputPath}`);
+        return { success: true, path: outputPath };
     }
     /**
      * Take full page screenshot
      */
-    async screenshotFullPage(filename) {
+    async screenshotFullPage(filename, signal) {
+        signal?.throwIfAborted();
         const page = await this.ensureBrowser();
-        const { mkdirSync, existsSync } = await import('fs');
-        if (!existsSync(this.config.screenshotDir)) {
-            mkdirSync(this.config.screenshotDir, { recursive: true });
+        signal?.throwIfAborted();
+        const { outputPath, temporaryPath } = this.screenshotPaths(filename, 'fullpage');
+        try {
+            await page.screenshot({ path: temporaryPath, fullPage: true });
+            signal?.throwIfAborted();
+            (0, node_fs_1.copyFileSync)(temporaryPath, outputPath, node_fs_1.constants.COPYFILE_EXCL);
+            this.removeOwnedArtifact(temporaryPath);
         }
-        const name = filename || `fullpage-${Date.now()}.png`;
-        const path = `${this.config.screenshotDir}/${name}`;
-        await page.screenshot({ path, fullPage: true });
-        console.log(`[Browser] Full page screenshot saved: ${path}`);
-        return { success: true, path };
+        catch (error) {
+            this.removeOwnedArtifact(temporaryPath);
+            throw error;
+        }
+        console.log(`[Browser] Full page screenshot saved: ${outputPath}`);
+        return { success: true, path: outputPath };
     }
     /**
      * Click element by selector

package/dist/tools/browser-tool.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungjaehoon/mama-os",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "MAMA OS - Local AI Runtime. Your scattered knowledge, organized by AI agents that never sleep.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,6 +11,8 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
+    "setup:ocr": "node scripts/setup-ocr.js",
+    "check:ocr": "node scripts/setup-ocr.js --check",
     "build": "tsc && pnpm exec tsx scripts/generate-gateway-tools.ts && rm -rf public/viewer/js && tsc -p public/viewer/tsconfig.viewer.json && pnpm run build:ui",
     "build:ui": "pnpm --dir ui run bundle",
     "dev:ui": "pnpm --dir ui run dev",

package/scripts/attachment/extract-office-text.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+const { readFileSync, statSync } = require('node:fs');
+const { inflateRawSync } = require('node:zlib');
+
+const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+const MAX_ARCHIVE_ENTRIES = 2_000;
+
+const [, , filePath, extension, maxOutputRaw] = process.argv;
+const maxOutputBytes = Number(maxOutputRaw);
+if (!filePath || !['.docx', '.xlsx'].includes(extension) || !Number.isSafeInteger(maxOutputBytes)) {
+  throw new Error('usage: extract-office-text.js <path> <.docx|.xlsx> <max-output-bytes>');
+}
+
+const prefixes =
+  extension === '.docx' ? ['word/document.xml'] : ['xl/sharedStrings.xml', 'xl/worksheets/'];
+const entries = readOfficeEntries(filePath, prefixes);
+const text = extension === '.docx' ? extractDocxText(entries) : extractXlsxText(entries);
+process.stdout.write(truncateUtf8(text, maxOutputBytes));
+
+function readOfficeEntries(path, wantedPrefixes) {
+  if (statSync(path).size > MAX_ARCHIVE_BYTES) {
+    throw new Error('Office attachment is too large');
+  }
+  const archive = readFileSync(path);
+  const endOffset = findEndOfCentralDirectory(archive);
+  const entryCount = archive.readUInt16LE(endOffset + 10);
+  const centralOffset = archive.readUInt32LE(endOffset + 16);
+  if (entryCount > MAX_ARCHIVE_ENTRIES) {
+    throw new Error('Office attachment has too many entries');
+  }
+  const result = new Map();
+  let cursor = centralOffset;
+  let extractedBytes = 0;
+  for (let index = 0; index < entryCount; index += 1) {
+    requireSignature(archive, cursor, 0x02014b50, 'central directory');
+    const flags = archive.readUInt16LE(cursor + 8);
+    const method = archive.readUInt16LE(cursor + 10);
+    const compressedSize = archive.readUInt32LE(cursor + 20);
+    const uncompressedSize = archive.readUInt32LE(cursor + 24);
+    const nameLength = archive.readUInt16LE(cursor + 28);
+    const extraLength = archive.readUInt16LE(cursor + 30);
+    const commentLength = archive.readUInt16LE(cursor + 32);
+    const localOffset = archive.readUInt32LE(cursor + 42);
+    const nameStart = cursor + 46;
+    const name = archive.subarray(nameStart, nameStart + nameLength).toString('utf8');
+    cursor = nameStart + nameLength + extraLength + commentLength;
+    if (!wantedPrefixes.some((prefix) => name === prefix || name.startsWith(prefix))) {
+      continue;
+    }
+    if ((flags & 0x1) !== 0) {
+      throw new Error('Encrypted Office attachments are not supported');
+    }
+    extractedBytes += uncompressedSize;
+    if (extractedBytes > MAX_ARCHIVE_BYTES) {
+      throw new Error('Office attachment expands too far');
+    }
+    requireSignature(archive, localOffset, 0x04034b50, 'local file header');
+    const nameSize = archive.readUInt16LE(localOffset + 26);
+    const extraSize = archive.readUInt16LE(localOffset + 28);
+    const dataStart = localOffset + 30 + nameSize + extraSize;
+    const compressed = archive.subarray(dataStart, dataStart + compressedSize);
+    const data =
+      method === 0
+        ? compressed
+        : method === 8
+          ? inflateRawSync(compressed, { maxOutputLength: MAX_ARCHIVE_BYTES })
+          : unsupportedCompression(method);
+    if (data.length !== uncompressedSize) {
+      throw new Error('Corrupt Office entry');
+    }
+    result.set(name, data.toString('utf8'));
+  }
+  return result;
+}
+
+function findEndOfCentralDirectory(archive) {
+  const minimumOffset = Math.max(0, archive.length - 65_557);
+  for (let cursor = archive.length - 22; cursor >= minimumOffset; cursor -= 1) {
+    if (archive.readUInt32LE(cursor) === 0x06054b50) {
+      return cursor;
+    }
+  }
+  throw new Error('Invalid Office attachment: ZIP directory not found');
+}
+
+function requireSignature(archive, offset, expected, label) {
+  if (offset < 0 || offset + 4 > archive.length || archive.readUInt32LE(offset) !== expected) {
+    throw new Error(`Invalid Office attachment ${label}`);
+  }
+}
+
+function unsupportedCompression(method) {
+  throw new Error(`Unsupported Office compression method: ${method}`);
+}
+
+function extractDocxText(entries) {
+  const xml = entries.get('word/document.xml');
+  if (!xml) {
+    throw new Error('Invalid DOCX attachment: word/document.xml is missing');
+  }
+  return [...xml.matchAll(/<w:p\b[^>]*>([\s\S]*?)<\/w:p>/g)]
+    .map((match) => extractXmlText(match[1], 'w:t'))
+    .filter(Boolean)
+    .join('\n');
+}
+
+function extractXlsxText(entries) {
+  const sharedXml = entries.get('xl/sharedStrings.xml') || '';
+  const shared = [...sharedXml.matchAll(/<si\b[^>]*>([\s\S]*?)<\/si>/g)].map((match) =>
+    extractXmlText(match[1], 't')
+  );
+  const sheets = [...entries.entries()]
+    .filter(([name]) => /^xl\/worksheets\/sheet[^/]*\.xml$/.test(name))
+    .sort(([left], [right]) => left.localeCompare(right));
+  if (sheets.length === 0) {
+    throw new Error('Invalid XLSX attachment: no worksheets found');
+  }
+  const lines = [];
+  for (const [name, xml] of sheets) {
+    lines.push(`[${name.slice(name.lastIndexOf('/') + 1, -4)}]`);
+    for (const cell of xml.matchAll(/<c\b([^>]*)>([\s\S]*?)<\/c>/g)) {
+      const reference = readXmlAttribute(cell[1], 'r') || '?';
+      const type = readXmlAttribute(cell[1], 't');
+      const raw = firstXmlTagText(cell[2], 'v');
+      const value =
+        type === 's'
+          ? shared[Number(raw)] || ''
+          : type === 'inlineStr'
+            ? extractXmlText(cell[2], 't')
+            : decodeXmlEntities(raw);
+      if (value) {
+        lines.push(`${reference}=${value}`);
+      }
+    }
+  }
+  return lines.join('\n');
+}
+
+function extractXmlText(xml, tagName) {
+  const tag = tagName.replace(':', '\\:');
+  return [...xml.matchAll(new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)<\\/${tag}>`, 'g'))]
+    .map((match) => decodeXmlEntities(match[1]))
+    .join('');
+}
+
+function firstXmlTagText(xml, tagName) {
+  const match = new RegExp(`<${tagName}\\b[^>]*>([\\s\\S]*?)<\\/${tagName}>`).exec(xml);
+  return match ? decodeXmlEntities(match[1]) : '';
+}
+
+function readXmlAttribute(attributes, name) {
+  const match = new RegExp(`(?:^|\\s)${name}=(?:"([^"]*)"|'([^']*)')`).exec(attributes);
+  return match ? match[1] || match[2] : undefined;
+}
+
+function decodeXmlEntities(value) {
+  return value
+    .replace(/<[^>]+>/g, '')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, '&')
+    .replace(/&#(\d+);/g, (_match, code) => String.fromCodePoint(Number(code)))
+    .replace(/&#x([0-9a-f]+);/gi, (_match, code) => String.fromCodePoint(parseInt(code, 16)));
+}
+
+function truncateUtf8(content, maxBytes) {
+  const bytes = Buffer.from(content);
+  if (bytes.length <= maxBytes) {
+    return content;
+  }
+  let end = maxBytes;
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) {
+    end -= 1;
+  }
+  return `${bytes.subarray(0, end).toString('utf8')}\n\n[Truncated at ${maxBytes} bytes]`;
+}

package/scripts/attachment/extract-pdf-text.swift

@@ -0,0 +1,36 @@
+import Foundation
+import PDFKit
+
+guard CommandLine.arguments.count == 3, let maxBytes = Int(CommandLine.arguments[2]), maxBytes > 0 else {
+  fputs("usage: extract-pdf-text.swift <pdf-path> <max-output-bytes>\n", stderr)
+  exit(2)
+}
+
+let url = URL(fileURLWithPath: CommandLine.arguments[1])
+guard let document = PDFDocument(url: url) else {
+  fputs("unable to open PDF\n", stderr)
+  exit(1)
+}
+
+var written = 0
+for index in 0..<document.pageCount {
+  if let text = document.page(at: index)?.string, !text.isEmpty {
+    let separator = written == 0 ? "" : "\n\n"
+    let data = (separator + text).data(using: .utf8) ?? Data()
+    let remaining = maxBytes - written
+    if remaining <= 0 { break }
+    var bounded = Data()
+    var prefixLength = min(remaining, data.count)
+    while prefixLength > 0 {
+      let candidate = Data(data.prefix(prefixLength))
+      if String(data: candidate, encoding: .utf8) != nil {
+        bounded = candidate
+        break
+      }
+      prefixLength -= 1
+    }
+    FileHandle.standardOutput.write(bounded)
+    written += bounded.count
+    if bounded.count < data.count { break }
+  }
+}

package/scripts/image/fb-overlay.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Render translated text over OCR regions and return the output path as JSON."""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+PADDING = 10
+MIN_FONT_SIZE = 18
+
+
+def font_candidates():
+    configured = os.environ.get("MAMA_KOREAN_FONT")
+    return [
+        configured,
+        "/System/Library/Fonts/AppleSDGothicNeo.ttc",
+        "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
+        "/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
+    ]
+
+
+def load_font(image_draw, text, max_width, start_size):
+    from PIL import ImageFont
+
+    for candidate in font_candidates():
+        if not candidate or not Path(candidate).exists():
+            continue
+        size = max(start_size, MIN_FONT_SIZE)
+        while size >= MIN_FONT_SIZE:
+            font = ImageFont.truetype(candidate, size)
+            bounds = image_draw.textbbox((0, 0), text, font=font)
+            if bounds[2] - bounds[0] <= max_width or size == MIN_FONT_SIZE:
+                return font
+            size -= 1
+    raise RuntimeError("Korean font not found; set MAMA_KOREAN_FONT")
+
+
+def sample_text_color(array, points):
+    import numpy
+
+    x1 = max(min(point[0] for point in points), 0)
+    y1 = max(min(point[1] for point in points), 0)
+    x2 = min(max(point[0] for point in points), array.shape[1])
+    y2 = min(max(point[1] for point in points), array.shape[0])
+    region = array[y1:y2, x1:x2]
+    if region.size == 0:
+        return (20, 20, 20)
+    dark_pixels = region.reshape(-1, 3)[region.mean(axis=2).flatten() < 80]
+    if len(dark_pixels) < 3:
+        return (20, 20, 20)
+    return tuple(int(channel) for channel in dark_pixels.mean(axis=0))
+
+
+def main():
+    if len(sys.argv) < 3:
+        raise ValueError("Usage: fb-overlay.py <image> <annotations.json> [output.png]")
+
+    from PIL import Image, ImageDraw
+    import numpy
+
+    image_path = sys.argv[1]
+    annotations_path = sys.argv[2]
+    output_path = (
+        sys.argv[3]
+        if len(sys.argv) > 3
+        else str(Path(image_path).with_name(f"{Path(image_path).stem}_KR.png"))
+    )
+    with open(annotations_path, encoding="utf-8") as handle:
+        annotations = json.load(handle)
+
+    original = Image.open(image_path).convert("RGB")
+    image = original.copy()
+    pixels = numpy.array(original)
+    draw = ImageDraw.Draw(image)
+    render_items = []
+
+    for annotation in annotations:
+        points = annotation["bbox"]
+        translated = annotation.get("translated", "")
+        if not translated:
+            continue
+        x1 = min(point[0] for point in points)
+        y1 = min(point[1] for point in points)
+        x2 = max(point[0] for point in points)
+        y2 = max(point[1] for point in points)
+        font = load_font(draw, translated, x2 - x1, int((y2 - y1) * 0.92))
+        bounds = draw.textbbox((0, 0), translated, font=font)
+        width = bounds[2] - bounds[0]
+        height = bounds[3] - bounds[1]
+        render_items.append(
+            {
+                "box": (
+                    x1 - PADDING,
+                    y1 - PADDING,
+                    max(x2, x1 + width) + PADDING,
+                    max(y2, y1 + height + 4) + PADDING,
+                ),
+                "text": translated,
+                "font": font,
+                "color": sample_text_color(pixels, points),
+                "height": height,
+            }
+        )
+
+    for item in render_items:
+        draw.rectangle(list(item["box"]), fill=(255, 255, 255))
+    for item in render_items:
+        x1, y1, _x2, y2 = item["box"]
+        text_y = y1 + ((y2 - y1) - item["height"]) // 2
+        draw.text(
+            (x1 + PADDING, text_y),
+            item["text"],
+            font=item["font"],
+            fill=item["color"],
+        )
+
+    image.save(output_path, quality=95)
+    print(json.dumps({"outputPath": output_path}, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as error:
+        print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)

package/scripts/image/ocr-image.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Extract OCR regions as JSON for MAMA image translation tools."""
+
+import json
+import sys
+
+
+def main():
+    if len(sys.argv) < 2:
+        raise ValueError("Usage: ocr-image.py <image_path> [--lang ja,en]")
+
+    image_path = sys.argv[1]
+    languages = ["ja", "en"]
+    for index, argument in enumerate(sys.argv[2:], 2):
+        if argument == "--lang" and index + 1 < len(sys.argv):
+            languages = sys.argv[index + 1].split(",")
+
+    import easyocr
+
+    reader = easyocr.Reader(languages, gpu=False, verbose=False)
+    output = []
+    for bbox, text, confidence in reader.readtext(image_path, detail=1):
+        output.append(
+            {
+                "bbox": [[int(point[0]), int(point[1])] for point in bbox],
+                "text": text,
+                "conf": round(confidence, 2),
+            }
+        )
+    print(json.dumps(output, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as error:
+        print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)

package/scripts/setup-ocr.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+const { existsSync, mkdirSync } = require('node:fs');
+const { homedir } = require('node:os');
+const { dirname, join, resolve } = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const REQUIREMENTS = ['easyocr==1.7.2', 'Pillow>=10,<13', 'numpy>=1.26,<3'];
+const FONT_GUIDANCE =
+  'Install a Korean/CJK font (Ubuntu/Debian: apt install fonts-noto-cjk) or set ' +
+  'MAMA_KOREAN_FONT to a readable .ttf/.ttc font file.';
+const RUNTIME_CHECK = String.raw`
+import os
+from pathlib import Path
+import easyocr, PIL, numpy
+from PIL import ImageFont
+
+candidates = [
+    os.environ.get("MAMA_KOREAN_FONT"),
+    "/System/Library/Fonts/AppleSDGothicNeo.ttc",
+    "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
+    "/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
+]
+for candidate in candidates:
+    if not candidate or not Path(candidate).is_file():
+        continue
+    try:
+        font = ImageFont.truetype(candidate, 18)
+        if font.getbbox("한글"):
+            print(easyocr.__version__)
+            raise SystemExit(0)
+    except OSError:
+        pass
+raise SystemExit("Korean/CJK font is unavailable")
+`;
+
+function runtimeRoot() {
+  return resolve(process.env.MAMA_OCR_ENV || join(homedir(), '.mama', 'ocr-env'));
+}
+
+function runtimePython(root) {
+  return process.platform === 'win32'
+    ? join(root, 'Scripts', 'python.exe')
+    : join(root, 'bin', 'python3');
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    stdio: options.capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+    encoding: 'utf8',
+    env: process.env,
+  });
+  if (result.error || result.status !== 0) {
+    const detail = result.error?.message || result.stderr?.trim() || `exit ${result.status}`;
+    throw new Error(`${command} ${args.join(' ')} failed: ${detail}`);
+  }
+  return result.stdout || '';
+}
+
+function check() {
+  const python = runtimePython(runtimeRoot());
+  if (!existsSync(python)) {
+    return false;
+  }
+  try {
+    run(python, ['-c', RUNTIME_CHECK], { capture: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function setup() {
+  const root = runtimeRoot();
+  const bootstrapPython = process.env.MAMA_OCR_BOOTSTRAP_PYTHON || 'python3';
+  mkdirSync(dirname(root), { recursive: true, mode: 0o700 });
+  if (!existsSync(runtimePython(root))) {
+    run(bootstrapPython, ['-m', 'venv', root]);
+  }
+  const python = runtimePython(root);
+  run(python, ['-m', 'pip', 'install', '--upgrade', 'pip']);
+  run(python, ['-m', 'pip', 'install', ...REQUIREMENTS]);
+  if (!check()) {
+    throw new Error(`MAMA OCR runtime failed its dependency/font check. ${FONT_GUIDANCE}`);
+  }
+  process.stdout.write(`MAMA OCR runtime ready: ${python}\n`);
+}
+
+function main() {
+  const command = process.argv[2];
+  if (command === '--print-requirements') {
+    process.stdout.write(`${REQUIREMENTS.join('\n')}\n`);
+    return;
+  }
+  if (command === '--print-font-guidance') {
+    process.stdout.write(`${FONT_GUIDANCE}\n`);
+    return;
+  }
+  if (command === '--check') {
+    if (check()) {
+      process.stdout.write(`MAMA OCR runtime ready: ${runtimePython(runtimeRoot())}\n`);
+      return;
+    }
+    process.stderr.write(
+      `MAMA OCR runtime is not ready at ${runtimeRoot()}. Run: pnpm setup:ocr\n${FONT_GUIDANCE}\n`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  setup();
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(
+    `MAMA OCR setup failed: ${error instanceof Error ? error.message : error}\n`
+  );
+  process.exitCode = 1;
+}