simtap 0.0.0-stage → 0.6.0

package/dist/cli.js

@@ -0,0 +1,123 @@
+/**
+ * The command line, built from the same tool list as the MCP server:
+ * `simtap look --find "Sign In"` calls ui_look with { find: "Sign In" }.
+ */
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { serve } from "./mcp.js";
+import { callTool, TOOLS, VERSION } from "./registry.js";
+const flag = (name) => `--${name.replace(/_/g, "-")}`;
+/** Parses `--name value` and `--switch` into arguments the tool's schema accepts. */
+export function parseArgs(tool, argv) {
+    const props = tool.inputSchema.properties;
+    const args = {};
+    const list = Object.entries(props).find(([, p]) => p.type === "array")?.[0];
+    const words = [...(tool.positional ?? [])];
+    for (let i = 0; i < argv.length; i++) {
+        const raw = argv[i];
+        if (!raw.startsWith("--")) {
+            // Bare words fill the tool's positional arguments in order, then a list argument takes the rest.
+            const next = words.find((w) => !(w in args));
+            if (next) {
+                args[next] = raw;
+                continue;
+            }
+            if (list) {
+                args[list] = [...(args[list] ?? []), raw];
+                continue;
+            }
+            return `Unexpected "${raw}". ${usage(tool)}`;
+        }
+        const [name, inline] = raw.startsWith("--") ? raw.slice(2).split(/=(.*)/s, 2) : [undefined, undefined];
+        const key = name?.replace(/-/g, "_");
+        const prop = key ? props[key] : undefined;
+        if (!key || !prop || prop.type === "array")
+            return `Unknown option ${raw}. ${usage(tool)}`;
+        if (prop.type === "boolean") {
+            args[key] = inline === undefined ? true : inline !== "false";
+            continue;
+        }
+        const value = inline ?? argv[++i];
+        if (value === undefined)
+            return `${flag(key)} needs a value.`;
+        args[key] = prop.type === "number" ? Number(value) : value;
+    }
+    return args;
+}
+export function usage(tool) {
+    const entries = Object.entries(tool.inputSchema.properties);
+    const bare = (tool.positional ?? []).map((key) => ` [${key}]`).join("");
+    const options = entries.filter(([key, p]) => p.type !== "array" && !tool.positional?.includes(key)).map(([key, p]) => `${flag(key)}${p.type === "boolean" ? "" : ` <${p.type}>`}`);
+    const words = entries.filter(([, p]) => p.type === "array").map(([key]) => ` <${key}...>`).join("");
+    return `Usage: simtap ${tool.command}${bare}${options.length ? ` [${options.join("] [")}]` : ""}${words}`;
+}
+/** The first sentence of a description, ending in one period. */
+const summary = (description) => `${description.split(/\.\s/)[0].replace(/\.$/, "")}.`;
+export function help() {
+    const width = Math.max(...TOOLS.map((t) => t.command.length), 3);
+    return [
+        `simtap ${VERSION}: give your agent a phone.`,
+        "",
+        "Commands:",
+        ...TOOLS.map((t) => `  ${t.command.padEnd(width)}  ${summary(t.description)}`),
+        `  ${"mcp".padEnd(width)}  Run the MCP server on stdio.`,
+        "",
+        "Examples:",
+        "  simtap run                      build, install and launch the Xcode project in this folder",
+        "  simtap look                     read the screen",
+        '  simtap act "fill #email a@b.co" "tap #signIn" \'wait "Welcome"\'',
+        "  simtap logs --crashes           why did it crash",
+        "",
+        "Run simtap <command> --help for its options.",
+    ].join("\n");
+}
+/** One command's help: what it does, its words and options with their choices. */
+export function commandHelp(tool) {
+    const lines = [tool.description, "", usage(tool)];
+    for (const [key, p] of Object.entries(tool.inputSchema.properties)) {
+        const choices = p.type !== "array" && p.enum ? ` (${p.enum.join(", ")})` : "";
+        const name = p.type === "array" ? `<${key}...>` : tool.positional?.includes(key) ? `[${key}] or ${flag(key)}` : flag(key);
+        lines.push(`  ${name}  ${p.description}${choices}`);
+    }
+    return lines.join("\n");
+}
+export async function main(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        console.log(help());
+        return 0;
+    }
+    if (command === "--version" || command === "-v") {
+        console.log(VERSION);
+        return 0;
+    }
+    if (command === "mcp") {
+        await serve();
+        // The client closed stdin: answer what was in flight, then go, even if a child process still holds a pipe.
+        process.exit(0);
+    }
+    const tool = TOOLS.find((t) => t.command === command || t.name === command);
+    if (!tool) {
+        console.error(`Unknown command "${command}".\n\n${help()}`);
+        return 2;
+    }
+    if (rest.includes("--help") || rest.includes("-h")) {
+        console.log(commandHelp(tool));
+        return 0;
+    }
+    const args = parseArgs(tool, rest);
+    if (typeof args === "string") {
+        console.error(args);
+        return 2;
+    }
+    const out = await callTool(tool.name, args, { waitForJobs: true });
+    let text = out.text;
+    if (out.image) {
+        const file = join(tmpdir(), `simtap-${Date.now()}.${out.image.mimeType === "image/png" ? "png" : "jpg"}`);
+        await writeFile(file, out.image.data);
+        text += `\nscreenshot: ${file}`;
+    }
+    (out.isError ? console.error : console.log)(text);
+    return out.isError ? 1 : 0;
+}

package/dist/engine/apps.js

@@ -0,0 +1,153 @@
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ToolError } from "../errors.js";
+import { isOurs, run } from "./exec.js";
+import { deviceDir } from "./state.js";
+const simctl = (args, timeoutMs = 60_000) => run("xcrun", ["simctl", ...args], { timeoutMs });
+/** The value of a key in `simctl appinfo`'s old-style plist output. */
+export function plistValue(text, key) {
+    const match = new RegExp(`\\b${key} = "?([^";\\n]+)"?;`).exec(text);
+    return match?.[1]?.trim();
+}
+export async function appInfo(udid, bundleId) {
+    try {
+        const { stdout } = await simctl(["appinfo", udid, bundleId], 15_000);
+        if (!stdout.includes("CFBundleIdentifier"))
+            return undefined;
+        // simctl escapes non-ASCII names (Café as Caf\U00e9): the app's own Info.plist has them as written.
+        const path = plistValue(stdout, "Path");
+        const fromPlist = async (key) => path ? (await run("plutil", ["-extract", key, "raw", join(path, "Info.plist")], { timeoutMs: 10_000 }).catch(() => undefined))?.stdout.trim() || undefined : undefined;
+        const name = (await fromPlist("CFBundleDisplayName")) ?? (await fromPlist("CFBundleName")) ?? plistValue(stdout, "CFBundleDisplayName") ?? plistValue(stdout, "CFBundleName");
+        return { executable: (await fromPlist("CFBundleExecutable")) ?? plistValue(stdout, "CFBundleExecutable"), name };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A bundle id as Apple allows it, so it can name files safely. */
+export const BUNDLE_ID = /^[A-Za-z0-9.-]+$/;
+/** Reads the bundle id from a built .app, so `install` can name what it installed. */
+export async function bundleIdOf(appPath) {
+    const plist = join(appPath, "Info.plist");
+    if (!existsSync(plist))
+        throw new ToolError(`${appPath} is not an .app bundle (no Info.plist).`, "Pass the path to a Simulator build, such as build/Build/Products/Debug-iphonesimulator/MyApp.app.");
+    const { stdout } = await run("plutil", ["-extract", "CFBundleIdentifier", "raw", plist], { timeoutMs: 10_000 });
+    return stdout.trim();
+}
+export async function install(udid, appPath) {
+    try {
+        await simctl(["install", udid, appPath], 120_000);
+    }
+    catch (error) {
+        throw new ToolError(`Could not install ${appPath}: ${error.message}`, "Check it is built for the Simulator (iphonesimulator), not a device.");
+    }
+}
+/** The file a launched app's print() output goes to, kept while the app runs. */
+export async function consoleFile(udid, bundleId) {
+    return join(await deviceDir(udid), `${bundleId}.console.log`);
+}
+/**
+ * Launches fresh (any running copy is stopped) and keeps the app's print() output for app_logs.
+ * simctl's --stdout wrote nothing on iOS 26.5, so a detached `simctl launch --console-pty` holds the app's
+ * output instead, writing to a file until the app ends; NSUnbufferedIO is what Xcode sets so lines arrive at once.
+ */
+export async function launch(udid, bundleId) {
+    const file = await consoleFile(udid, bundleId);
+    const fd = openSync(file, "w");
+    const child = spawn("xcrun", ["simctl", "launch", "--console-pty", "--terminate-running-process", udid, bundleId], {
+        detached: true,
+        stdio: ["ignore", fd, fd],
+        env: { ...process.env, SIMCTL_CHILD_NSUnbufferedIO: "YES" },
+    });
+    closeSync(fd);
+    // A launch that fails ends the launcher within moments; a running app keeps it alive.
+    const code = await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(undefined), 2_000);
+        child.once("exit", (c) => (clearTimeout(timer), resolve(c)));
+        child.once("error", () => (clearTimeout(timer), resolve(-1)));
+    });
+    child.unref();
+    if (code !== undefined && code !== 0) {
+        const output = readFileSync(file, "utf8").trim();
+        if (/not installed|FBSOpenApplicationServiceErrorDomain|Unable to find|could not be found/i.test(output)) {
+            throw new ToolError(`${bundleId} is not installed on this Simulator.`, 'Install it first: app_control {action: "install", app: "path/to/App.app"}.');
+        }
+        throw new ToolError(`Could not launch ${bundleId}: ${output.split("\n").slice(-3).join(" ")}`);
+    }
+}
+/** The app's own system log lines, streamed to a file while simtap watches it. */
+export async function streamFile(udid, bundleId) {
+    return join(await deviceDir(udid), `${bundleId}.syslog.log`);
+}
+/**
+ * The system log predicate for what an app itself logged: its own sender or subsystem. Apple's frameworks
+ * also log faults from inside the app (on iOS 27, a keyboard queue timeout on every first focus); a grep
+ * reaches those, and a crash is in the crash report and the print output.
+ */
+export function ownLines(executable, bundleId) {
+    const name = executable.replace(/"/g, "");
+    return `process == "${name}" AND (sender == "${name}" OR subsystem BEGINSWITH "${bundleId.replace(/"/g, "")}")`;
+}
+/**
+ * Streams the app's own log lines to a file from before it launches. \`log show\` is not enough: macOS keeps
+ * info lines only in memory, and the Simulator's UIKit noise pushed the sample app's "signed in" line out
+ * within 30 s (October 19). One stream per app and device; a new launch replaces the old stream.
+ */
+export async function startLogStream(udid, bundleId, executable) {
+    await stopLogStream(udid, bundleId);
+    const file = await streamFile(udid, bundleId);
+    const fd = openSync(file, "w");
+    const child = spawn("xcrun", ["simctl", "spawn", udid, "log", "stream", "--style", "compact", "--level", "info", "--predicate", ownLines(executable, bundleId)], {
+        detached: true,
+        stdio: ["ignore", fd, "ignore"],
+    });
+    closeSync(fd);
+    child.unref();
+    if (child.pid)
+        writeFileSync(`${file}.pid`, String(child.pid));
+    // The stream needs a moment to attach before the app's first lines.
+    await new Promise((r) => setTimeout(r, 300));
+}
+export async function stopLogStream(udid, bundleId) {
+    const pidFile = `${await streamFile(udid, bundleId)}.pid`;
+    const pid = existsSync(pidFile) ? Number(readFileSync(pidFile, "utf8")) : 0;
+    if (await isOurs(pid, /simctl spawn .* log stream/)) {
+        try {
+            process.kill(pid);
+        }
+        catch {
+            // Gone between the check and the signal.
+        }
+    }
+    rmSync(pidFile, { force: true });
+}
+export async function simctlAction(args, what, timeoutMs = 30_000) {
+    try {
+        return (await simctl(args, timeoutMs)).stdout.trim();
+    }
+    catch (error) {
+        throw new ToolError(`Could not ${what}: ${error.message}`);
+    }
+}
+export async function pushPayload(udid, bundleId, payload) {
+    await new Promise((resolve, reject) => {
+        const child = spawn("xcrun", ["simctl", "push", udid, bundleId, "-"], { stdio: ["pipe", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve() : reject(new ToolError(`Could not send the push: ${stderr.trim()}`))));
+        child.stdin.end(payload);
+    });
+}
+/** Puts text on the Simulator's clipboard, for pasting what the keyboard can't type (é, 日本, emoji). */
+export async function setPasteboard(udid, text) {
+    await new Promise((resolve, reject) => {
+        const child = spawn("xcrun", ["simctl", "pbcopy", udid], { stdio: ["pipe", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve() : reject(new ToolError(`Could not set the Simulator's clipboard: ${stderr.trim()}`))));
+        child.stdin.end(text);
+    });
+}

package/dist/engine/axe.js

@@ -0,0 +1,107 @@
+import { existsSync } from "node:fs";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ToolError } from "../errors.js";
+import { run } from "./exec.js";
+/**
+ * AXe (MIT, github.com/cameroncooke/AXe) reads the Simulator's accessibility tree and sends touches and keys,
+ * with no test runner to build. The package carries a pinned copy in vendor/axe; SIMTAP_AXE overrides it.
+ */
+export function axePath() {
+    if (process.env.SIMTAP_AXE)
+        return process.env.SIMTAP_AXE;
+    // src/engine and dist/engine are both two levels below the package root.
+    const bundled = fileURLToPath(new URL("../../vendor/axe/axe", import.meta.url));
+    return existsSync(bundled) ? bundled : "axe";
+}
+/**
+ * After a Simulator's first boot, its accessibility service takes a while to accept a reader: on a fresh
+ * Xcode 27 Mac, describe-ui failed with this for about 75 s, then worked.
+ */
+export class AccessibilityStarting extends ToolError {
+}
+// Also right after a boot: "No translation object returned for simulator" (iPhone 17e, 5 s after booting).
+const STARTING = /remote automation session|No translation object returned/i;
+export async function describeUi(udid) {
+    try {
+        const { stdout } = await run(axePath(), ["describe-ui", "--udid", udid], { timeoutMs: 30_000 });
+        const parsed = JSON.parse(stdout);
+        return Array.isArray(parsed) ? parsed : [parsed];
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new ToolError("AXe is missing from this install.", "Reinstall simtap, or set SIMTAP_AXE to an axe binary.");
+        if (STARTING.test(error.message)) {
+            throw new AccessibilityStarting("The Simulator's accessibility service is still starting; after a first boot this can take a minute or two.", "Call again in 30 seconds.");
+        }
+        throw new ToolError(`Could not read the screen: ${error.message}`, "Wait a second and call ui_look again; if it keeps failing, check the Simulator is booted with devices.");
+    }
+}
+/** A JPEG of the screen sized to points, so a point in the picture is a point to tap (402x874 is about 470 image tokens). */
+export async function screenshot(udid, points) {
+    const dir = await mkdtemp(join(tmpdir(), "simtap-"));
+    try {
+        const png = join(dir, "screen.png");
+        const jpg = join(dir, "screen.jpg");
+        await run(axePath(), ["screenshot", "--output", png, "--udid", udid], { timeoutMs: 30_000 });
+        const size = points.width > 0 && points.height > 0 ? ["-z", String(Math.round(points.height)), String(Math.round(points.width))] : [];
+        await run("sips", [...size, "-s", "format", "jpeg", "-s", "formatOptions", "70", png, "--out", jpg], { timeoutMs: 30_000 });
+        return await readFile(jpg);
+    }
+    catch (error) {
+        throw new ToolError(`Could not take a screenshot: ${error.message}`);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+const axe = (udid, args, timeoutMs = 30_000) => run(axePath(), [...args, "--udid", udid], { timeoutMs });
+/** One AXe process for several input steps (tap, type, key, key-combo, swipe, sleep): about 0.2 s cheaper per step. */
+export async function batch(udid, steps) {
+    try {
+        await axe(udid, ["batch", "--ax-cache", "none", "--type-submission", "composite", ...steps.flatMap((s) => ["--step", s])], 60_000);
+    }
+    catch (error) {
+        throw new ToolError(`The Simulator did not take the input: ${error.message}`);
+    }
+}
+/** A drag or swipe on its own: AXe's batch takes swipe but not drag. */
+export async function gesture(udid, args) {
+    try {
+        await axe(udid, args, 30_000);
+    }
+    catch (error) {
+        throw new ToolError(`The Simulator did not take the gesture: ${error.message}`);
+    }
+}
+/** The single element at a point, for reading back a field right after typing (about 0.15 s). */
+export async function elementAt(udid, x, y) {
+    try {
+        // Normally 0.15 s; on a fresh Xcode 27 VM some hung for 8 to 11 s, so a slow one is abandoned for a full read.
+        const { stdout } = await axe(udid, ["describe-ui", "--point", `${Math.round(x)},${Math.round(y)}`], 3_000);
+        const parsed = JSON.parse(stdout);
+        return Array.isArray(parsed) ? parsed[0] : parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A step string for AXe batch: text goes in single quotes, with any single quote escaped the shell way. */
+export function typeStep(text) {
+    return `type '${text.replace(/'/g, `'\\''`)}'`;
+}
+export async function pressButton(udid, button) {
+    await axe(udid, ["button", button]);
+}
+/** Sets a slider by accessibility id or label to a percent; AXe drags it there. */
+export async function setSlider(udid, target, percent) {
+    const by = target.id ? ["--id", target.id] : ["--label", target.label ?? ""];
+    try {
+        await axe(udid, ["slider", ...by, "--value", String(percent)]);
+    }
+    catch (error) {
+        throw new ToolError(`Could not set the slider: ${error.message}`);
+    }
+}

package/dist/engine/exec.js

@@ -0,0 +1,36 @@
+import { execFile } from "node:child_process";
+/** Runs a program without a shell. Rejects with its stderr when it fails or runs past the timeout. */
+export function run(file, args, options = {}) {
+    const started = Date.now();
+    return new Promise((resolve, reject) => {
+        execFile(file, args, { timeout: options.timeoutMs ?? 30_000, maxBuffer: options.maxBytes ?? 64 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
+            // SIMTAP_DEBUG=1 prints every program run and how long it took, to find where time goes.
+            if (process.env.SIMTAP_DEBUG)
+                process.stderr.write(`simtap:   ${file.split("/").pop()} ${args.slice(0, 2).join(" ")} ${Date.now() - started} ms${error ? " (failed)" : ""}\n`);
+            if (!error)
+                return resolve({ stdout, stderr });
+            const code = error.code;
+            const reason = code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
+                ? "printed more output than can be read"
+                : error.killed
+                    ? `timed out after ${Math.round((options.timeoutMs ?? 30_000) / 1000)} s`
+                    : (stderr || error.message).trim();
+            reject(Object.assign(new Error(`${file.split("/").pop()} ${args[0] ?? ""}: ${reason}`), { stderr, code: error.code }));
+        });
+    });
+}
+/**
+ * Whether a pid still belongs to the process we started: a pid file can outlive its process (the Simulator shut
+ * down, the Mac restarted), and the number may by then belong to something else that must not be signalled.
+ */
+export async function isOurs(pid, pattern) {
+    if (!pid)
+        return false;
+    try {
+        const { stdout } = await run("ps", ["-o", "command=", "-p", String(pid)], { timeoutMs: 5_000 });
+        return pattern.test(stdout);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/engine/jobs.js

@@ -0,0 +1,95 @@
+import { randomBytes } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+const jobs = new Map();
+let latest;
+/** Stops every running job: the server is going away, and a build nobody can follow should not keep compiling. */
+export function cancelAllJobs() {
+    for (const job of jobs.values())
+        if (!job.result)
+            job.cancel?.();
+}
+// Node runs no exit handler when a signal ends the process, so the signals stop the jobs themselves.
+process.on("exit", cancelAllJobs);
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+    process.once(signal, () => {
+        cancelAllJobs();
+        process.exit(128 + { SIGHUP: 1, SIGINT: 2, SIGTERM: 15 }[signal]);
+    });
+}
+export function startJob(title, work) {
+    const id = `job_${randomBytes(4).toString("hex")}`;
+    const job = { id, title, started: Date.now(), step: "starting", tail: [] };
+    const progress = {
+        step: (step) => {
+            job.step = step;
+        },
+        line: (line) => {
+            job.tail.push(line);
+            if (job.tail.length > 20)
+                job.tail.shift();
+        },
+        // Cleared once the part that can be stopped (the build) is over, so a late cancel doesn't claim it stopped.
+        setCancel: (cancel) => {
+            job.cancel = cancel
+                ? () => {
+                    job.cancelled = true;
+                    cancel();
+                }
+                : undefined;
+        },
+        setLog: (file) => {
+            job.log = file;
+        },
+    };
+    job.done = work(progress)
+        .catch((error) => ({ text: error.toText?.() ?? `${title} failed: ${error.message}`, isError: true }))
+        .then((result) => {
+        // Whatever the stopped work reported (a build "fails" when killed), the truth is it was stopped.
+        if (job.cancelled)
+            result = { text: `${title} was stopped by job_cancel after ${elapsed(job)}.`, isError: true };
+        job.result = result;
+        job.cancel = undefined;
+        return result;
+    });
+    jobs.set(id, job);
+    latest = id;
+    return job;
+}
+export const getJob = (id) => jobs.get(id ?? latest ?? "");
+/** Waits for a job up to `ms`, so a caller can answer with the result when it comes soon, or with progress. */
+export async function waitFor(job, ms) {
+    if (job.result)
+        return job.result;
+    return Promise.race([job.done, delay(ms, undefined, { ref: false })]);
+}
+export const elapsed = (job) => {
+    const s = Math.round((Date.now() - job.started) / 1000);
+    return s >= 60 ? `${Math.floor(s / 60)} min ${s % 60} s` : `${s} s`;
+};
+/** A call answers within this (40 s); longer work goes on as a job. */
+export const ANSWER_WITHIN_MS = (Number(process.env.SIMTAP_JOB_AFTER_S) || 40) * 1000;
+/** The result if it comes within 40 s, else the job to follow; the CLI just waits. */
+export async function answer(job, waitForJobs) {
+    if (waitForJobs)
+        return job.done;
+    const done = await waitFor(job, ANSWER_WITHIN_MS);
+    if (done)
+        return done;
+    return { text: `${job.title} is still ${job.step} after ${elapsed(job)}: job ${job.id}.\nNext: job_status {job_id: "${job.id}"}; it waits up to 40 s for the result.` };
+}
+/** Which running job holds a project: xcodebuild runs in that project's DerivedData, which only one may use. */
+const projects = new Map();
+/** Claims a project for a job, or names the job already running there. Released when the job ends. */
+export function claimProject(projectPath, job) {
+    const holder = projects.get(projectPath);
+    if (holder && !holder.result && holder !== job)
+        return holder;
+    projects.set(projectPath, job);
+    void job.done.finally(() => {
+        if (projects.get(projectPath) === job)
+            projects.delete(projectPath);
+    });
+    return undefined;
+}
+/** The job this one is: for work that runs inside it and needs to claim things in its name. */
+export const currentJob = (id) => jobs.get(id);

package/dist/engine/logs.js

@@ -0,0 +1,115 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ownLines } from "./apps.js";
+import { run } from "./exec.js";
+const LEVELS = { Df: "", I: "info", Db: "debug", E: "error", F: "fault" };
+/** `2026-10-19 01:56:22.114 E  Demo[94957:88904] (Sender) [subsystem:category] message`; sender and subsystem are optional. */
+const COMPACT = /^\d{4}-\d\d-\d\d (\d\d:\d\d:\d\d\.\d+) (\w+)\s+\S+?\[\d+:\w+\] (?:\(([^)]+)\) )?(?:\[([^\]]+)\] )?(.*)$/;
+/** Parses `log show --style compact`. Activity lines (type A) are bookkeeping, never kept. */
+export function parseSystemLog(output, appSubsystem) {
+    const lines = [];
+    for (const raw of output.split("\n")) {
+        const m = COMPACT.exec(raw);
+        if (!m || m[2] === "A")
+            continue;
+        const [, time, type, sender, source = "", text = ""] = m;
+        const [subsystem = "", category = ""] = source.split(":");
+        const tag = subsystem && appSubsystem && subsystem.startsWith(appSubsystem) ? category : source || (sender ? `(${sender})` : "");
+        lines.push({ time: time, level: LEVELS[type] ?? type, text: `${tag ? `${tag}: ` : ""}${text}` });
+    }
+    return lines;
+}
+/**
+ * The app's lines from the Simulator's system log. Apple's frameworks log a great deal from inside the app's
+ * process (UIKit's event dispatch, several lines a tap; on the Simulator, a haptics error every key press), so
+ * by default only what the app itself logged is read, and faults from anywhere; `everything` reads it all.
+ */
+export async function systemLog(udid, executable, seconds, bundleId, everything = false) {
+    const predicate = everything ? `process == "${executable.replace(/"/g, "")}"` : ownLines(executable, bundleId);
+    const { stdout } = await run("xcrun", ["simctl", "spawn", udid, "log", "show", "--style", "compact", "--info", "--last", `${Math.max(1, Math.ceil(seconds))}s`, "--predicate", predicate], {
+        timeoutMs: 12_000,
+    });
+    return parseSystemLog(stdout, bundleId);
+}
+/** Lines from the app's own log stream (startLogStream) that are newer than `since` (ms since 1970). */
+export async function streamedLines(file, since, bundleId) {
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const lines = [];
+    for (const raw of text.split("\n")) {
+        // The stamp is the Mac's local time, as `2026-10-19 02:04:48.818`.
+        const stamp = /^(\d{4}-\d\d-\d\d) (\d\d:\d\d:\d\d\.\d+)/.exec(raw);
+        if (!stamp || new Date(`${stamp[1]}T${stamp[2]}`).getTime() < since)
+            continue;
+        lines.push(...parseSystemLog(raw, bundleId));
+    }
+    return lines;
+}
+/** The app's print() output, without the Simulator's own start-up noise. */
+export function cleanConsole(text) {
+    return text
+        .replace(/\r/g, "")
+        .split("\n")
+        .filter((line) => line.trim() && !/^objc\[\d+\]: Class .* is implemented in both/.test(line));
+}
+/**
+ * Crash reports of a Simulator app land on the Mac itself, in ~/Library/Logs/DiagnosticReports, named after
+ * the app's executable. An .ips file is one JSON header line, then the report as JSON.
+ */
+export async function crashReports(executable, since, limit = 3) {
+    const dir = join(homedir(), "Library", "Logs", "DiagnosticReports");
+    let names;
+    try {
+        names = (await readdir(dir)).filter((n) => n.startsWith(`${executable}-`) && n.endsWith(".ips"));
+    }
+    catch {
+        return [];
+    }
+    const files = await Promise.all(names.map(async (n) => ({ file: join(dir, n), at: (await stat(join(dir, n))).mtimeMs })));
+    const recent = files.filter((f) => f.at >= since).sort((a, b) => b.at - a.at).slice(0, limit);
+    return Promise.all(recent.map(async (f) => {
+        const text = await readFile(f.file, "utf8");
+        // When it crashed, not when macOS finished writing the report (up to a minute later).
+        const time = /"captureTime"\s*:\s*"([^"]+)"/.exec(text)?.[1] ?? new Date(f.at).toISOString();
+        return { file: f.file, time, summary: summarizeIps(text, executable) };
+    }));
+}
+/**
+ * What went wrong and where: the exception, the reason, and the crashing thread from the top down to just past
+ * the app's own last frame (the rest is the framework that called it).
+ */
+export function summarizeIps(text, executable) {
+    const body = text.slice(text.indexOf("\n") + 1);
+    let ips;
+    try {
+        ips = JSON.parse(body);
+    }
+    catch {
+        return ["(unreadable crash report)"];
+    }
+    const out = [];
+    if (ips.exception)
+        out.push(`exception: ${[ips.exception.type, ips.exception.signal].filter(Boolean).join(" ")}`);
+    const reasons = [...(ips.termination?.reasons ?? []), ...Object.values(ips.asi ?? {}).flat(), ips.termination?.indicator ?? ""].filter(Boolean);
+    for (const reason of reasons.slice(0, 3))
+        out.push(`reason: ${reason.replace(/\s+/g, " ").trim()}`);
+    const thread = ips.threads?.find((t) => t.triggered) ?? ips.threads?.[ips.faultingThread ?? 0];
+    const all = thread?.frames ?? [];
+    const imageOf = (f) => ips.usedImages?.[f.imageIndex ?? -1]?.name ?? "?";
+    const own = (f) => Boolean(executable) && (imageOf(f) === executable || imageOf(f).startsWith(`${executable}.`));
+    const lastOwn = all.reduce((last, f, i) => (own(f) ? i : last), -1);
+    const frames = all.slice(0, lastOwn >= 0 ? Math.min(lastOwn + 3, 12) : 8).map((f) => {
+        const image = imageOf(f);
+        const where = f.sourceFile ? ` (${f.sourceFile}:${f.sourceLine ?? "?"})` : "";
+        return `  ${image} ${f.symbol ?? `+${f.imageOffset ?? 0}`}${where}`;
+    });
+    if (frames.length)
+        out.push("crashed thread:", ...frames);
+    return out;
+}