kelra 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+// kelra-connect: the MCP server Claude Code runs on the customer's Mac.
+// It does what needs the Mac (devices, screenshots, the clipboard, reading files, reading text, the app's live layout)
+// and sends measurements to the kelra service, which does the analysis.
+import { execFile } from "node:child_process";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { devicectl, screenshotPng, settledScreenshotPng } from "./devicectl.js";
+import { readPng, shapeWarning } from "./friendly.js";
+import { contrast, crop, decode, encode, hex, palette, parseHex, pixel, scanLine } from "./image.js";
+import { fetchTree } from "./live.js";
+import { readRawBuffer } from "./ocr.js";
+import { callService } from "./service.js";
+import { guide } from "./guide.js";
+// The guide for AI agents (usage and how to handle the helper) is sent to the model whenever this server is connected.
+const instructions = guide;
+const server = new McpServer({ name: "kelra", version: "0.1.0" }, { instructions });
+// the same guide, readable on demand
+server.resource("kelra-guide", "kelra://guide", { mimeType: "text/markdown", description: "How to use kelra and how to handle the helper and the license" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: guide }] }));
+const device = z.string().describe("Device name, UDID or ECID from list_devices");
+const text = (o) => ({ content: [{ type: "text", text: JSON.stringify(o, null, 2) }] });
+const wrap = (fn) => fn().catch((e) => ({ isError: true, content: [{ type: "text", text: e.message }] }));
+const run = promisify(execFile);
+const b64 = (buf) => buf.toString("base64");
+server.tool("kelra_guide", "The kelra guide for AI agents: how to use kelra, and the rules for handling the helper and the license. Read it if you are unsure what to do when a kelra tool fails.", {}, () => wrap(async () => ({ content: [{ type: "text", text: guide }] })));
+// ---- on the Mac: devices -------------------------------------------------------------------------------------
+server.tool("list_devices", "List simulated and physical devices known to devicectl (Xcode Device Hub).", {}, () => wrap(async () => {
+    const r = await devicectl(["list", "devices"]);
+    return text(r.devices.map((d) => ({
+        name: d.deviceProperties?.name, id: d.hardwareProperties?.udid ?? d.identifier,
+        state: d.connectionProperties?.tunnelState, model: d.hardwareProperties?.marketingName,
+        reality: d.hardwareProperties?.reality,
+    })));
+}));
+server.tool("device_state", "Displays (pixel size, pointScale, orientation) plus appearance (dark/light, increased contrast, large text, Liquid Glass) for a device. Use pointScale to convert screenshot pixels to points.", { device }, ({ device }) => wrap(async () => {
+    const [displays, appearance] = await Promise.all([
+        devicectl(["device", "info", "displays", "-d", device]),
+        devicectl(["device", "info", "appearance", "-d", device]),
+    ]);
+    return text({
+        displays: displays.displays.map((d) => ({
+            id: d.uniqueId, primary: d.primary, active: d.active, nativePixels: d.nativeSize,
+            pointScale: d.pointScale, orientation: d.currentOrientation,
+            sizeInPoints: d.nativeSize.map((v) => v / d.pointScale),
+        })),
+        appearance,
+    });
+}));
+server.tool("screenshot", "Capture the device screen. Multi-display devices (iPhone Duo) return one composite image; coordinates for the other tools are pixels in this image.", { device }, ({ device }) => wrap(async () => {
+    const buf = await screenshotPng(device);
+    const img = decode(buf);
+    return { content: [{ type: "text", text: `Screenshot ${img.width}x${img.height}px` }, { type: "image", data: b64(buf), mimeType: "image/png" }] };
+}));
+server.tool("set_status_bar", "Override a simulated device's status bar so it matches a reference (default: 9:41, full Wi-Fi and cellular, 100% battery). Use clear to restore the real one.", { device, clear: z.boolean().default(false), time: z.string().default("9:41"), batteryLevel: z.number().int().min(0).max(100).default(100) }, ({ device, clear, time, batteryLevel }) => wrap(async () => {
+    if (clear)
+        await devicectl(["device", "simulate", "statusBar", "clear", "-d", device]);
+    else
+        await devicectl(["device", "simulate", "statusBar", "override", "-d", device, "--time", time, "--wifi-mode", "active", "--wifi-strength", "3", "--cellular-mode", "active", "--cellular-strength", "4", "--battery-state", "draining", "--battery-level", String(batteryLevel)]);
+    return text({ ok: true, device, status: clear ? "cleared" : { time, wifi: 3, cellular: 4, batteryLevel } });
+}));
+// ---- on the Mac: simple pixel tools (no analysis, so they work offline) ----------------------------------------
+server.tool("sample_color", "Exact RGB/hex of one pixel in a fresh screenshot.", { device, x: z.number().int(), y: z.number().int() }, ({ device, x, y }) => wrap(async () => {
+    const c = pixel(decode(await screenshotPng(device)), x, y);
+    return text({ x, y, rgb: c, hex: hex(c) });
+}));
+server.tool("measure_region", "Dominant colors of a pixel rect plus an enlarged crop image, for inspecting one component precisely.", { device, x: z.number().int(), y: z.number().int(), w: z.number().int().positive(), h: z.number().int().positive() }, ({ device, ...r }) => wrap(async () => {
+    const img = decode(await screenshotPng(device));
+    if (r.x + r.w > img.width || r.y + r.h > img.height)
+        throw new Error(`Rect exceeds ${img.width}x${img.height}`);
+    return { content: [{ type: "text", text: JSON.stringify({ rect: r, palette: palette(img, r) }, null, 2) }, { type: "image", data: b64(encode(crop(img, r))), mimeType: "image/png" }] };
+}));
+server.tool("measure_spacing", "Scan a horizontal or vertical line in a fresh screenshot and return runs of uniform color with pixel lengths. Use it to measure padding, gaps, row heights and element widths; divide pixels by pointScale for points.", {
+    device,
+    axis: z.enum(["x", "y"]).describe("x = scan left→right along row `at`; y = scan top→bottom along column `at`"),
+    at: z.number().int().describe("The fixed coordinate: the row (axis x) or column (axis y)"),
+    from: z.number().int(), to: z.number().int(),
+    tolerance: z.number().min(0).default(12).describe("RGB distance that counts as a new run"),
+    pointScale: z.number().positive().optional().describe("If set, also report lengths in points"),
+}, ({ device, axis, at, from, to, tolerance, pointScale }) => wrap(async () => {
+    const img = decode(await screenshotPng(device));
+    const runs = scanLine(img, axis, at, from, to, tolerance).map((r) => ({ ...r, lengthPx: r.end - r.start + 1, ...(pointScale ? { lengthPt: +((r.end - r.start + 1) / pointScale).toFixed(2) } : {}) }));
+    return text({ image: `${img.width}x${img.height}`, runs });
+}));
+server.tool("contrast_check", "WCAG contrast ratio between two colors, given as hex or as screenshot points. Reports AA/AAA for normal and large text.", {
+    device: device.optional().describe("Required when using points"),
+    fg: z.union([z.string(), z.object({ x: z.number().int(), y: z.number().int() })]),
+    bg: z.union([z.string(), z.object({ x: z.number().int(), y: z.number().int() })]),
+}, ({ device, fg, bg }) => wrap(async () => {
+    let img;
+    const resolve = async (v) => {
+        if (typeof v === "string")
+            return parseHex(v);
+        if (!device)
+            throw new Error("device is required when fg/bg are points");
+        img ??= decode(await screenshotPng(device));
+        return pixel(img, v.x, v.y);
+    };
+    const [f, b] = [await resolve(fg), await resolve(bg)];
+    const ratio = contrast(f, b);
+    return text({ fg: hex(f), bg: hex(b), ratio: +ratio.toFixed(2), AA_normal: ratio >= 4.5, AA_large: ratio >= 3, AAA_normal: ratio >= 7, AAA_large: ratio >= 4.5 });
+}));
+// ---- on the Mac: finding images --------------------------------------------------------------------------------
+server.tool("clipboard_image", "Save the image currently on the macOS clipboard (a screenshot copied with Cmd+Ctrl+Shift+4, or an image copied from Preview/Safari) to a PNG file and return its path, so it can be given to analyze_reference or compare. Use this when the user says 'copy the UI in my clipboard'. If the user copied a file in Finder it returns that file's real path. For an image pasted into the prompt, try latest_pasted_image first.", {}, () => wrap(async () => {
+    // a file copied in Finder puts the file's icon on the clipboard as image data; use the real file instead
+    try {
+        const { stdout } = await run("osascript", ["-e", "POSIX path of (the clipboard as «class furl»)"]);
+        const path = stdout.trim();
+        if (/\.(png|jpe?g|heic|webp|tiff?)$/i.test(path) && (await stat(path).catch(() => null))) {
+            const png = path.toLowerCase().endsWith(".png") ? path : join(tmpdir(), "kelra-clipboard", `finder-${Date.now()}.png`);
+            if (png !== path) {
+                await mkdir(join(tmpdir(), "kelra-clipboard"), { recursive: true });
+                await run("sips", ["-s", "format", "png", path, "--out", png]);
+            }
+            const img = decode(await readFile(png));
+            return text({ file: png, source: "file copied in Finder", original: path, sizePx: [img.width, img.height] });
+        }
+    }
+    catch { /* no file on the clipboard: fall through to image data */ }
+    const dir = join(tmpdir(), "kelra-clipboard");
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, `clipboard-${Date.now()}.png`);
+    const write = (cls, target) => run("osascript", [
+        "-e", `set d to the clipboard as «class ${cls}»`,
+        "-e", `set f to open for access POSIX file "${target}" with write permission`,
+        "-e", "set eof of f to 0", "-e", "write d to f", "-e", "close access f",
+    ]);
+    try {
+        await write("PNGf", file);
+    }
+    catch {
+        const tiff = file.replace(/\.png$/, ".tiff");
+        try {
+            await write("TIFF", tiff);
+        }
+        catch {
+            throw new Error("The clipboard has no image. Copy a screenshot first (Cmd+Ctrl+Shift+4), or give a file path instead.");
+        }
+        await run("sips", ["-s", "format", "png", tiff, "--out", file]);
+    }
+    const img = decode(await readFile(file));
+    return text({ file, sizePx: [img.width, img.height], bytes: (await stat(file)).size });
+}));
+server.tool("latest_pasted_image", "Find the image the user most recently pasted into Claude Code (it is saved as a file even though the chat shows it inline) and return its path. Try this first when the user pasted a screenshot into the prompt; fall back to clipboard_image if nothing recent is found.", { maxAgeMinutes: z.number().positive().default(30) }, ({ maxAgeMinutes }) => wrap(async () => {
+    const uid = process.getuid?.() ?? 501;
+    const roots = [`/private/tmp/claude-${uid}`, `/tmp/claude-${uid}`];
+    const found = [];
+    for (const root of roots) {
+        const projects = await readdir(root).catch(() => []);
+        for (const proj of projects) {
+            const sessions = await readdir(join(root, proj)).catch(() => []);
+            for (const sess of sessions) {
+                const dir = join(root, proj, sess, "images");
+                for (const f of await readdir(dir).catch(() => []))
+                    if (/\.(png|jpe?g|webp)$/i.test(f))
+                        found.push({ file: join(dir, f), mtime: (await stat(join(dir, f))).mtimeMs });
+            }
+        }
+    }
+    const seen = new Set(); // /tmp is a link to /private/tmp, so the same file can be found twice
+    const unique = found.filter((f) => { const key = f.file.replace(/^\/private/, ""); if (seen.has(key))
+        return false; seen.add(key); return true; });
+    unique.sort((a, b) => b.mtime - a.mtime);
+    const newest = unique[0];
+    if (!newest || Date.now() - newest.mtime > maxAgeMinutes * 60_000)
+        throw new Error(`No image pasted in the last ${maxAgeMinutes} minutes. Use clipboard_image or ask for a file path.`);
+    let file = newest.file;
+    if (!/\.png$/i.test(file)) {
+        const out = join(tmpdir(), "kelra-clipboard", `pasted-${Date.now()}.png`);
+        await mkdir(join(tmpdir(), "kelra-clipboard"), { recursive: true });
+        await run("sips", ["-s", "format", "png", file, "--out", out]);
+        file = out;
+    }
+    const img = decode(await readFile(file));
+    return text({ file, pastedAt: new Date(newest.mtime).toISOString(), sizePx: [img.width, img.height], otherRecentImages: unique.slice(1, 4).map((f) => f.file) });
+}));
+// ---- analysis: read locally, measure text on the Mac, and ask the kelra service -------------------------------------
+const trimmed = (png, top, bottom) => {
+    if (!top && !bottom)
+        return png;
+    const img = decode(png);
+    const h = img.height - top - bottom;
+    if (h < 100)
+        throw new Error("Trim leaves less than 100px of the image");
+    return encode(crop(img, { x: 0, y: top, w: img.width, h }));
+};
+server.tool("analyze_reference", "Turn a reference UI screenshot (local PNG path) into a measured spec: background color, a nested tree of surfaces (cards, bars) and content (text/icons) with positions, sizes, fills, ink colors and corner radii in points. Use it as the build spec when asked to copy a UI. `textLines` has the exact words with position, font size and weight (Apple Vision OCR); the element tree is boxes without words. Sizes assume the iOS system font and are good to about 5%.", {
+    path: z.string().describe("Absolute path to the reference PNG"),
+    pointScale: z.number().positive().default(3).describe("Pixels per point of the reference (3 for most modern iPhones)"),
+    tolerance: z.number().min(1).default(16).describe("RGB distance that separates content from background (16 sees a white card on a near-white page; raise it for noisy or compressed screenshots)"),
+}, ({ path, pointScale, tolerance }) => wrap(async () => {
+    const png = await readPng(path, "reference image");
+    const ocr = await readRawBuffer(png, pointScale);
+    return text(await callService("/v1/analyze-reference", { image: b64(png), pointScale, tolerance, ocr }));
+}));
+server.tool("read_text", "Read the text in a screenshot with Apple Vision (OCR): the exact words, where each line sits (points), its color, and the system font size and weight that fit it, plus a ready-to-paste SwiftUI font modifier. Sizes assume the iOS system font and are good to about 5%; weight is a guess (adjacent weights are often confused, see weightConfidence); custom fonts only match by width. Lines flagged likelyIcon are glyphs read as letters. Use this instead of reading words by eye.", {
+    path: z.string().describe("Absolute path to the PNG"),
+    pointScale: z.number().positive().default(3).describe("Pixels per point of the screenshot"),
+    trimBottomPx: z.number().int().min(0).default(0),
+    minConfidence: z.number().min(0).max(1).default(0.4),
+    includeIcons: z.boolean().default(false),
+}, ({ path, pointScale, trimBottomPx, minConfidence, includeIcons }) => wrap(async () => {
+    const png = trimmed(await readPng(path), 0, trimBottomPx);
+    const ocr = await readRawBuffer(png, pointScale);
+    if (!ocr)
+        throw new Error("Reading text needs a Mac with Xcode installed (Apple Vision).");
+    return text(await callService("/v1/read-text", { image: b64(png), pointScale, minConfidence, includeIcons, ocr }));
+}));
+server.tool("compare", "Compare a reference screenshot against the current render and return `status` (done or not, and the next step: follow it), `critical` (e.g. text invisible in the render: fix these first), `textAdjustments` (per text line, matched by its words: exact font-size multiplier, move, weight), `adjustments` (move/resize/recolor for elements that matched, largest first), `missingInRender` and `extraInRender` (structure differences), a similarity score, the worst-differing screen areas, and a red diff overlay. Render comes from a live device screenshot, or renderPath for a saved PNG. The reference is scaled to the render's size; the aspect ratios should match.", {
+    referencePath: z.string().describe("Absolute path to the reference PNG"),
+    device: device.optional().describe("Device to capture as the render"),
+    renderPath: z.string().optional().describe("Saved PNG to use instead of a device capture"),
+    pointScale: z.number().positive().default(3).describe("Pixels per point of the render"),
+    tolerance: z.number().min(1).default(16),
+    referenceTrimTopPx: z.number().int().min(0).default(0).describe("Pixels to cut from the top of the reference first, e.g. a status bar or a watermark header"),
+    referenceTrimBottomPx: z.number().int().min(0).default(0).describe("Pixels to cut from the bottom of the reference first, e.g. the Mobbin 'curated by' footer strip"),
+    ignoreTopPt: z.number().min(0).default(0).describe("Ignore the top N points of the RENDER (e.g. the simulator status bar)"),
+    ignoreBottomPt: z.number().min(0).default(0).describe("Ignore the bottom N points of the RENDER (e.g. home indicator area)"),
+    ignoreRegions: z.array(z.object({ x: z.number(), y: z.number(), w: z.number(), h: z.number() })).default([]).describe("Rectangles in render points to leave out of the comparison (live content, glass effects, product photos)"),
+    inspectPort: z.number().int().optional().describe("Port of KelraInspector in the running app. With a device, port 8765 is tried automatically. Adds the app's current exact font size and the size to set to each text adjustment."),
+    align: z.enum(["auto", "stretch"]).default("auto").describe("auto: fit the reference to the render by scale and offset (handles crops, footers, other device sizes); stretch: force it to the render's exact size"),
+}, ({ referencePath, device, renderPath, pointScale, tolerance, align, inspectPort, referenceTrimTopPx, referenceTrimBottomPx, ignoreTopPt, ignoreBottomPt, ignoreRegions }) => wrap(async () => {
+    if (!device && !renderPath)
+        throw new Error("Provide device or renderPath");
+    const renderPng = renderPath ? await readPng(renderPath, "render image") : await settledScreenshotPng(device);
+    const refPng = trimmed(await readPng(referencePath, "reference image"), referenceTrimTopPx, referenceTrimBottomPx);
+    const render = decode(renderPng), ref = decode(refPng);
+    // the reference's text is read in its own pixels, assuming it is scaled to the render's width; the service corrects for the real alignment
+    const refPpp = (ref.width * pointScale) / render.width;
+    const [refOcr, renderOcr, live] = await Promise.all([
+        readRawBuffer(refPng, refPpp), readRawBuffer(renderPng, pointScale),
+        inspectPort || device ? fetchTree(inspectPort ?? 8765).catch(() => null) : Promise.resolve(null),
+    ]);
+    const r = await callService("/v1/compare", {
+        reference: b64(refPng), render: b64(renderPng), pointScale, tolerance, ignoreTopPt, ignoreBottomPt, ignoreRegions, align,
+        refOcr: refOcr && renderOcr ? refOcr : null, refOcrPixelsPerPoint: refPpp, renderOcr: refOcr && renderOcr ? renderOcr : null, live,
+    });
+    const shape = align === "stretch" ? null : shapeWarning(ref, render);
+    if (shape)
+        r.report.warnings = [shape, ...(Array.isArray(r.report.warnings) ? r.report.warnings : [])];
+    return { content: [{ type: "text", text: JSON.stringify(r.report, null, 2) }, { type: "image", data: r.overlay, mimeType: "image/png" }] };
+}));
+server.tool("extract_assets", "Crop image regions out of a reference screenshot into PNG files, so a build can use real pictures where the reference has photos. Regions default to the detected photo regions (see analyze_reference); pass `regions` (in points) to choose exact rectangles, e.g. a whole card's photo area. For local prototyping: the pictures belong to whoever made the reference, so do not ship them.", {
+    path: z.string().describe("Absolute path to the reference PNG"),
+    outDir: z.string().describe("Directory to write the PNG files into (created if missing)"),
+    pointScale: z.number().positive().default(3),
+    trimBottomPx: z.number().int().min(0).default(0).describe("Pixels to cut from the bottom first (e.g. a Mobbin footer); coordinates then refer to the trimmed image"),
+    regions: z.array(z.object({ name: z.string(), x: z.number(), y: z.number(), w: z.number(), h: z.number() })).optional().describe("Rectangles in points; omit to use detected photo regions"),
+}, ({ path, outDir, pointScale, trimBottomPx, regions }) => wrap(async () => {
+    const png = trimmed(await readPng(path), 0, trimBottomPx);
+    const img = decode(png);
+    const rects = regions
+        ? regions.map((r) => ({ name: r.name, x: Math.round(r.x * pointScale), y: Math.round(r.y * pointScale), w: Math.round(r.w * pointScale), h: Math.round(r.h * pointScale) }))
+        : (await callService("/v1/image-regions", { image: b64(png) })).regions.map((r, i) => ({ name: `photo-${i + 1}`, ...r }));
+    await mkdir(outDir, { recursive: true });
+    const out = [];
+    for (const r of rects) {
+        const x = Math.max(0, r.x), y = Math.max(0, r.y);
+        const w = Math.min(img.width - x, r.w), h = Math.min(img.height - y, r.h);
+        if (w < 2 || h < 2) {
+            out.push({ name: r.name, error: "outside the image" });
+            continue;
+        }
+        const file = join(outDir, `${r.name}.png`);
+        await writeFile(file, encode(crop(img, { x, y, w, h })));
+        out.push({ name: r.name, file, sizePx: [w, h], rectPt: { x: +(x / pointScale).toFixed(1), y: +(y / pointScale).toFixed(1), w: +(w / pointScale).toFixed(1), h: +(h / pointScale).toFixed(1) } });
+    }
+    return text(out);
+}));
+server.tool("inspect_app", "Read the running app's real layout from the KelraInspector Swift package (debug builds): every text, image and shape with its exact frame in points, shape fills and corner radii, UIKit label text/font/color, and for SwiftUI text the font size derived from the layer height (1.2 x size). Pass `device` (or `screenshotPath`) to also read the words, weight and color of SwiftUI text from a screenshot, and to get warnings for text layers that draw nothing readable (usually text colored like its background). Also returns layout facts: screen margins, alignment edges, vertical gaps between texts, and the padding inside each card. Needs the app running on a simulator with KelraInspector.start() called (see its README).", {
+    port: z.number().int().default(8765).describe("Port KelraInspector listens on"),
+    device: device.optional().describe("If given, take a screenshot and read SwiftUI text words/weight/color from it"),
+    screenshotPath: z.string().optional().describe("Alternative to device: a saved screenshot of the same screen"),
+    includeFacts: z.boolean().default(true),
+}, ({ port, device, screenshotPath, includeFacts }) => wrap(async () => {
+    const tree = await fetchTree(port).catch((e) => {
+        throw new Error(`Could not reach KelraInspector on port ${port} (${e.message}). Add the KelraInspector package to the app, call KelraInspector.start() in a DEBUG build, and run it on a simulator.`);
+    });
+    let screenshot = null, ocr = null;
+    if (device || screenshotPath) {
+        screenshot = device ? await settledScreenshotPng(device) : await readPng(screenshotPath, "screenshot");
+        ocr = await readRawBuffer(screenshot, decode(screenshot).width / tree.screen.w);
+    }
+    return text(await callService("/v1/inspect", { tree, screenshot: screenshot ? b64(screenshot) : null, ocr, includeFacts }));
+}));
+await server.connect(new StdioServerTransport());

package/dist/license.d.ts

@@ -0,0 +1,15 @@
+export declare const licensePath: () => string;
+export interface Stored {
+    refreshToken?: string;
+    token?: string;
+    expiresAt?: number;
+    email?: string;
+}
+export declare function readStored(): Stored;
+/** Save with owner-only permissions (folder 0700, file 0600). Used by the login command. */
+export declare function writeStored(data: Stored): string;
+export declare function clearStored(): void;
+/** Kept for a license pasted in directly (KELRA_TOKEN-style). */
+export declare const saveToken: (token: string) => string;
+/** The license stored or provided directly, without any network. (`currentLicense` in login.ts also renews it.) */
+export declare function loadToken(): string | null;

package/dist/license.js

@@ -0,0 +1,29 @@
+// Where the customer's sign-in lives, and how it is written: readable only by its owner.
+// The file holds the machine's refresh token (from `kelra login`) and the short-lived license last fetched with it.
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const licensePath = () => join(process.env.KELRA_HOME ?? join(homedir(), ".kelra"), "license.json");
+export function readStored() {
+    try {
+        return JSON.parse(readFileSync(licensePath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Save with owner-only permissions (folder 0700, file 0600). Used by the login command. */
+export function writeStored(data) {
+    const file = licensePath();
+    mkdirSync(join(file, ".."), { recursive: true, mode: 0o700 });
+    writeFileSync(file, JSON.stringify(data), { mode: 0o600 });
+    chmodSync(file, 0o600); // also tightens a file that already existed with looser permissions
+    return file;
+}
+export function clearStored() { rmSync(licensePath(), { force: true }); }
+/** Kept for a license pasted in directly (KELRA_TOKEN-style). */
+export const saveToken = (token) => writeStored({ token });
+/** The license stored or provided directly, without any network. (`currentLicense` in login.ts also renews it.) */
+export function loadToken() {
+    return process.env.KELRA_TOKEN || readStored().token || null;
+}

package/dist/live.d.ts

@@ -0,0 +1,2 @@
+import type { LiveTree } from "@kelra/protocol";
+export declare function fetchTree(port?: number, host?: string): Promise<LiveTree>;

package/dist/live.js

@@ -0,0 +1,6 @@
+export async function fetchTree(port = 8765, host = "127.0.0.1") {
+    const res = await fetch(`http://${host}:${port}/tree`, { signal: AbortSignal.timeout(5000) });
+    if (!res.ok)
+        throw new Error(`inspector answered ${res.status}`);
+    return (await res.json());
+}

package/dist/login.d.ts

@@ -0,0 +1,22 @@
+export declare const accountApi: () => string;
+export declare class LoginError extends Error {
+}
+export interface LoginDeps {
+    fetchFn?: typeof fetch;
+    open?: (url: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (line: string) => void;
+}
+export declare function login(deps?: LoginDeps): Promise<{
+    email?: string;
+}>;
+export declare function logout(): void;
+export declare function whoami(): {
+    signedIn: boolean;
+    email?: string;
+};
+/**
+ * The license to send with requests. KELRA_TOKEN wins (CI, tests). Otherwise use the saved one while it has more than
+ * five minutes left, or trade the machine's refresh token for a fresh one (about every six hours).
+ */
+export declare function currentLicense(fetchFn?: typeof fetch): Promise<string | null>;

package/dist/login.js

@@ -0,0 +1,84 @@
+// `kelra login`: sign this Mac in through the browser (like the GitHub or Vercel command line tools).
+// 1. ask the account service for a code, 2. open the browser where the customer approves it, 3. wait, 4. save the result.
+import { hostname } from "node:os";
+import { apiBase } from "./config.js";
+import { clearStored, readStored, writeStored } from "./license.js";
+export const accountApi = () => (process.env.KELRA_ACCOUNT_API ?? apiBase()).replace(/\/$/, "");
+export class LoginError extends Error {
+}
+async function post(fetchFn, path, body) {
+    let res;
+    try {
+        res = await fetchFn(accountApi() + path, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000) });
+    }
+    catch (e) {
+        throw new LoginError(`Could not reach the kelra service (${e.message}). Check your internet connection.`);
+    }
+    return { status: res.status, json: (await res.json().catch(() => ({}))) };
+}
+export async function login(deps = {}) {
+    const fetchFn = deps.fetchFn ?? fetch, log = deps.log ?? console.log;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const start = await post(fetchFn, "/v1/device/start", { label: hostname().replace(/\.local$/, "") });
+    if (start.status !== 200)
+        throw new LoginError(start.json.error ?? `Could not start sign-in (${start.status}).`);
+    const { deviceCode, userCode, verificationUrl, expiresIn } = start.json;
+    let interval = Math.max(1, start.json.interval);
+    const link = `${verificationUrl}?code=${encodeURIComponent(userCode)}`;
+    log(`\nTo sign in, open:  ${link}\nYour code:         ${userCode}\n`);
+    try {
+        deps.open?.(link);
+    }
+    catch { /* the link above is enough */ }
+    log("Waiting for you to approve in the browser…");
+    const deadline = Date.now() + expiresIn * 1000;
+    while (Date.now() < deadline) {
+        await sleep(interval * 1000);
+        const r = await post(fetchFn, "/v1/device/poll", { deviceCode });
+        if (r.status !== 200)
+            throw new LoginError(r.json.error ?? `Sign-in failed (${r.status}). Run \`npx kelra login\` again.`);
+        switch (r.json.status) {
+            case "pending": break;
+            case "slow_down":
+                interval = Math.max(interval, r.json.interval ?? interval) + 1;
+                break;
+            case "denied": throw new LoginError("Sign-in was canceled in the browser.");
+            case "device_limit": throw new LoginError(r.json.message ?? "This account is signed in on too many machines. Remove one in your dashboard.");
+            case "approved":
+                if (!r.json.refreshToken)
+                    throw new LoginError("The service did not return a sign-in. Try again.");
+                writeStored({ refreshToken: r.json.refreshToken, email: r.json.email });
+                return { email: r.json.email };
+            default: throw new LoginError("Unexpected reply from the kelra service. Update with `npx kelra@latest`.");
+        }
+    }
+    throw new LoginError("The code expired. Run `npx kelra login` again.");
+}
+export function logout() { clearStored(); }
+export function whoami() {
+    const s = readStored();
+    return { signedIn: Boolean(s.refreshToken || s.token), email: s.email };
+}
+/**
+ * The license to send with requests. KELRA_TOKEN wins (CI, tests). Otherwise use the saved one while it has more than
+ * five minutes left, or trade the machine's refresh token for a fresh one (about every six hours).
+ */
+export async function currentLicense(fetchFn = fetch) {
+    if (process.env.KELRA_TOKEN)
+        return process.env.KELRA_TOKEN;
+    const s = readStored();
+    const now = Math.floor(Date.now() / 1000);
+    if (s.token && (s.expiresAt === undefined || s.expiresAt - now > 300))
+        return s.token;
+    if (!s.refreshToken)
+        return null;
+    const r = await post(fetchFn, "/v1/token", { refreshToken: s.refreshToken });
+    if (r.status === 401) {
+        writeStored({ email: s.email });
+        throw new LoginError("This machine was signed out (removed from your account). Run `npx kelra login`.");
+    }
+    if (r.status !== 200 || !r.json.token)
+        throw new LoginError(r.json.error ?? `Could not renew your license (${r.status}).`);
+    writeStored({ ...s, token: r.json.token, expiresAt: r.json.expiresAt });
+    return r.json.token;
+}

package/dist/ocr.d.ts

@@ -0,0 +1,6 @@
+import type { RawOcrLine } from "@kelra/protocol";
+/** Compile the reader with the Xcode toolchain if it is not built yet. */
+export declare function ensureOcr(): Promise<void>;
+export declare function readRaw(pngPath: string, pixelsPerPoint: number): Promise<RawOcrLine[]>;
+/** Raw readings of an in-memory PNG. Returns null where the reader cannot run (not a Mac, no Xcode), so the service still works without text. */
+export declare function readRawBuffer(png: Buffer, pixelsPerPoint: number): Promise<RawOcrLine[] | null>;

package/dist/ocr.js

@@ -0,0 +1,40 @@
+// Reads text lines from a screenshot with Apple Vision (macOS only) and returns raw measurements.
+// The program makes no decisions about fonts: the kelra service does that.
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { developerDir } from "./developer.js";
+const run = promisify(execFile);
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const BIN = join(root, "bin", "kelra-ocr");
+/** Compile the reader with the Xcode toolchain if it is not built yet. */
+export async function ensureOcr() {
+    if (existsSync(BIN))
+        return;
+    await mkdir(join(root, "bin"), { recursive: true });
+    await run(join(developerDir(), "Toolchains/XcodeDefault.xctoolchain/usr/bin/swiftc"), [
+        "-O", join(root, "swift/ocr.swift"), "-o", BIN, "-sdk", join(developerDir(), "Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk"),
+    ], { timeout: 180_000 });
+}
+export async function readRaw(pngPath, pixelsPerPoint) {
+    await ensureOcr();
+    const { stdout } = await run(BIN, [pngPath, String(pixelsPerPoint)], { timeout: 60_000, maxBuffer: 16 * 1024 * 1024 });
+    return JSON.parse(stdout);
+}
+/** Raw readings of an in-memory PNG. Returns null where the reader cannot run (not a Mac, no Xcode), so the service still works without text. */
+export async function readRawBuffer(png, pixelsPerPoint) {
+    try {
+        const dir = join(tmpdir(), "kelra-ocr");
+        await mkdir(dir, { recursive: true });
+        const file = join(dir, `img-${Date.now()}-${Math.random().toString(36).slice(2, 7)}.png`);
+        await writeFile(file, png);
+        return await readRaw(file, pixelsPerPoint);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/service.d.ts

@@ -0,0 +1,7 @@
+import type { ApiError } from "@kelra/protocol";
+export declare class ServiceError extends Error {
+    status: number;
+    code?: ApiError["code"] | undefined;
+    constructor(message: string, status: number, code?: ApiError["code"] | undefined);
+}
+export declare function callService<T>(path: string, body: unknown, attempt?: number): Promise<T>;

package/dist/service.js

@@ -0,0 +1,32 @@
+import { apiBase } from "./config.js";
+import { currentLicense } from "./login.js";
+const BASE = apiBase;
+export class ServiceError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+export async function callService(path, body, attempt = 1) {
+    const token = await currentLicense();
+    if (!token)
+        throw new ServiceError("No kelra license found. Sign in at kelra.net (run `npx kelra login`), or set KELRA_TOKEN.", 401, "unauthorized");
+    let res;
+    try {
+        res = await fetch(BASE() + path, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` }, body: JSON.stringify(body), signal: AbortSignal.timeout(120_000) });
+    }
+    catch (e) {
+        if (attempt < 2)
+            return callService(path, body, attempt + 1);
+        throw new ServiceError(`Could not reach the kelra service (${e.message}). Check your internet connection.`, 0);
+    }
+    if (res.status >= 502 && res.status <= 504 && attempt < 2)
+        return callService(path, body, attempt + 1);
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok)
+        throw new ServiceError(json.error ?? `kelra service error (${res.status})`, res.status, json.code);
+    return json;
+}

package/dist/settle.d.ts

@@ -0,0 +1,17 @@
+/** Fraction of pixels that differ noticeably between two same-size PNG screenshots (1 when the sizes differ). */
+export declare function diffRatio(a: Buffer, b: Buffer, tolerance?: number): number;
+export interface SettleOptions {
+    /** Most captures to take. */
+    maxTries?: number;
+    /** Pause between captures. */
+    gapMs?: number;
+    /** Two frames count as the same when at most this fraction of pixels differs. */
+    threshold?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Captures until two frames in a row match, and returns the last one. Gives up after `maxTries` and returns the latest frame. */
+export declare function captureSettled(capture: () => Promise<Buffer>, opts?: SettleOptions): Promise<{
+    png: Buffer;
+    captures: number;
+    settled: boolean;
+}>;

package/dist/settle.js

@@ -0,0 +1,27 @@
+// Waits for the screen to stop changing before it is measured, so a launch animation is never mistaken for the app.
+import { decode } from "./image.js";
+/** Fraction of pixels that differ noticeably between two same-size PNG screenshots (1 when the sizes differ). */
+export function diffRatio(a, b, tolerance = 8) {
+    const x = decode(a), y = decode(b);
+    if (x.width !== y.width || x.height !== y.height)
+        return 1;
+    let changed = 0;
+    for (let i = 0; i < x.data.length; i += 4) {
+        if (Math.abs(x.data[i] - y.data[i]) > tolerance || Math.abs(x.data[i + 1] - y.data[i + 1]) > tolerance || Math.abs(x.data[i + 2] - y.data[i + 2]) > tolerance)
+            changed++;
+    }
+    return changed / (x.width * x.height);
+}
+/** Captures until two frames in a row match, and returns the last one. Gives up after `maxTries` and returns the latest frame. */
+export async function captureSettled(capture, opts = {}) {
+    const { maxTries = 6, gapMs = 600, threshold = 0.002, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = opts;
+    let previous = await capture();
+    for (let n = 2; n <= maxTries; n++) {
+        await sleep(gapMs);
+        const next = await capture();
+        if (diffRatio(previous, next) <= threshold)
+            return { png: next, captures: n, settled: true };
+        previous = next;
+    }
+    return { png: previous, captures: maxTries, settled: false };
+}