agemu 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Illia Puzanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# agemu
+
+`agemu` builds, runs, inspects, and controls an iOS app in Simulator. Commands return JSON, so people and coding agents can use the same interface.
+
+> [!NOTE]
+> `agemu` is under active development. The command and configuration formats may change before 1.0.
+
+## Requirements
+
+- macOS with Xcode and an iOS Simulator runtime
+- Node.js 24 or later
+- pnpm
+
+## Install from source
+
+Clone this repository, then run:
+
+```sh
+cd agemu
+pnpm install
+pnpm build
+pnpm link --global
+```
+
+Run `agemu --version` to confirm the installation.
+
+## Install the agent skill
+
+Install the skill for Codex, Claude Code, OpenCode, or another supported agent:
+
+```sh
+npx skills add zoilorys/agemu --skill agemu
+```
+
+The installer prompts for the target agents and installation scope. Start a new agent session after installation. The skill activates for repositories that contain `.agemu.json`.
+
+Codex users can instead install the native plugin:
+
+```sh
+codex plugin marketplace add zoilorys/agemu
+codex plugin add agemu@agemu
+```
+
+Claude Code users can instead install its native plugin:
+
+```sh
+claude plugin marketplace add zoilorys/agemu
+claude plugin install agemu@agemu
+```
+
+## Configure an app
+
+Add `.agemu.json` to the root of the iOS app repository:
+
+```json
+{
+  "version": 1,
+  "project": "App.xcodeproj",
+  "scheme": "App",
+  "configuration": "Debug",
+  "bundleId": "com.example.App",
+  "simulator": {
+    "name": "iPhone 17",
+    "runtime": "iOS-26-0"
+  }
+}
+```
+
+Use `workspace` instead of `project` for an `.xcworkspace`. Select a simulator by `udid`, or by `name` with an optional `runtime`.
+
+Check the configuration and native tools:
+
+```sh
+agemu doctor --pretty
+```
+
+## Build and run an app
+
+```sh
+agemu simulator list --pretty
+agemu simulator boot
+agemu build
+agemu app install
+agemu app launch --arg=VALUE --env=NAME=VALUE
+agemu observe
+agemu logs show --last=1m --level=info --limit=200
+agemu diagnose --last=1m --level=info --limit=200
+agemu app terminate
+agemu simulator shutdown
+```
+
+`app launch`, `app restart`, and `app terminate` target the configured bundle ID. Only `app install` requires a prior build.
+
+`agemu` writes build state, logs, screenshots, and test results to `.agemu/`. Add that directory to the app repository's `.gitignore`.
+
+## Run a UI plan
+
+Build and install the app first. Then create `ui-plan.json`:
+
+```json
+{
+  "version": 1,
+  "actions": [
+    { "launch": { "arguments": ["--ui-testing"], "environment": { "RUN_ID": "example" } } },
+    { "wait": { "identifier": "email", "timeout": 5 } },
+    { "type": { "identifier": "email", "text": "agent@example.com" } },
+    { "tap": { "identifier": "save" } },
+    { "assertVisible": { "label": "Saved" } },
+    { "screenshot": { "name": "saved" } }
+  ]
+}
+```
+
+Run the plan:
+
+```sh
+agemu ui run --plan=ui-plan.json
+```
+
+Targets accept an accessibility `identifier` or an exact `label`. The `tap` action also accepts `x` and `y` screen coordinates. The `inspect` action returns the XCTest accessibility hierarchy in `runnerResult.trees`.
+
+The bundled XCTest runner needs no macOS Accessibility or Screen Recording permission. Each run saves an `.xcresult` bundle and `xcodebuild.log` under `.agemu/runs/`.
+
+## Develop
+
+```sh
+pnpm install
+pnpm test
+```
+
+The native integration test needs an available Simulator:
+
+```sh
+AGEMU_NATIVE_SIMULATOR_UDID=<udid> pnpm test:integration:native
+```
+
+## Contribute
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

package/dist/artifacts/runs.js

@@ -0,0 +1,46 @@
+import { appendFile, mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { redact } from '../core/redact.js';
+export async function createRun(root, now = new Date()) {
+    const id = `${now.toISOString().replaceAll(':', '-')}-${process.pid}-${Math.random().toString(16).slice(2, 10)}`;
+    const directory = path.join(root, '.agemu', 'runs', id);
+    await mkdir(directory, { recursive: true });
+    return { id, directory, relativeDirectory: path.relative(root, directory) };
+}
+export function redactValue(value, secrets) {
+    if (typeof value === 'string')
+        return redact(value, secrets);
+    if (Array.isArray(value))
+        return value.map((item) => redactValue(item, secrets));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [redact(key, secrets), redactValue(item, secrets)]));
+    }
+    return value;
+}
+async function acquireLock(directory) {
+    const lock = path.join(directory, 'events.lock');
+    const deadline = Date.now() + 10_000;
+    while (true) {
+        try {
+            await mkdir(lock);
+            return () => rm(lock, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST' || Date.now() >= deadline)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+    }
+}
+export async function appendEvent(root, event, secrets) {
+    const directory = path.join(root, '.agemu');
+    await mkdir(directory, { recursive: true });
+    const line = `${JSON.stringify(redactValue(event, secrets))}\n`;
+    const release = await acquireLock(directory);
+    try {
+        await appendFile(path.join(directory, 'events.jsonl'), line, { encoding: 'utf8', mode: 0o600, flag: 'a' });
+    }
+    finally {
+        await release();
+    }
+}

package/dist/cli/main.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { errorResult, writeResult } from '../core/output.js';
+import { CliError } from '../core/errors.js';
+import { loadConfig } from '../config/config.js';
+import { doctor } from '../doctor/doctor.js';
+import { bootDevice, listDevices, resolveDevice, shutdownDevice } from '../native/simctl.js';
+import { buildApp } from '../commands/build.js';
+import { controlApp } from '../commands/app.js';
+import { diagnose, observe, showLogs } from '../commands/diagnostics.js';
+import { buildUiRunner, runUiPlan } from '../commands/ui.js';
+const args = process.argv.slice(2);
+const packageVersion = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+const pretty = args.includes('--pretty');
+const debug = args.includes('--debug');
+const command = args.find((arg) => !arg.startsWith('--'));
+const option = (name) => {
+    const inline = args.find((arg) => arg.startsWith(`--${name}=`));
+    if (inline)
+        return inline.slice(name.length + 3);
+    const index = args.indexOf(`--${name}`);
+    return index >= 0 ? args[index + 1] : undefined;
+};
+const requiredString = (name) => {
+    const value = option(name);
+    if (value === undefined || value.length === 0 || (args.includes(`--${name}`) && value.startsWith('--'))) {
+        throw new CliError('UI_VALIDATION_FAILED', `--${name} requires a non-empty value`);
+    }
+    return value;
+};
+if (args.includes('--help')) {
+    writeResult({ ok: true, data: { help: 'agemu [--pretty] [--debug] <command>' } }, pretty);
+}
+else if (args.includes('--version')) {
+    writeResult({ ok: true, data: { version: packageVersion } }, pretty);
+}
+else if (!command) {
+    writeResult(errorResult(new CliError('COMMAND_INVALID', 'A command is required'), debug), pretty);
+    process.exitCode = 1;
+}
+else
+    try {
+        let data;
+        if (command === 'config' && args.includes('show')) {
+            const config = await loadConfig();
+            const { root: _, redactions: __, ...safe } = config;
+            data = safe;
+        }
+        else if (command === 'simulator' && args.includes('list')) {
+            data = { devices: await listDevices() };
+        }
+        else if (command === 'simulator' && (args.includes('boot') || args.includes('shutdown'))) {
+            const config = await loadConfig();
+            const explicitUdid = args.find((arg) => arg.startsWith('--udid='))?.slice('--udid='.length);
+            const explicitName = args.find((arg) => arg.startsWith('--name='))?.slice('--name='.length);
+            const explicitRuntime = args.find((arg) => arg.startsWith('--runtime='))?.slice('--runtime='.length);
+            const selector = explicitUdid
+                ? { udid: explicitUdid }
+                : config.simulator.udid
+                    ? { udid: config.simulator.udid }
+                    : explicitName
+                        ? { name: explicitName, ...(explicitRuntime ? { runtime: explicitRuntime } : {}) }
+                        : config.simulator;
+            const device = resolveDevice(await listDevices(), selector);
+            const action = args.includes('boot') ? 'boot' : 'shutdown';
+            const controlled = action === 'boot' ? await bootDevice(device) : await shutdownDevice(device);
+            data = { action, device: controlled };
+        }
+        else if (command === 'observe') {
+            data = await observe(await loadConfig());
+        }
+        else if (command === 'ui') {
+            const plan = args.includes('run') ? path.resolve(requiredString('plan')) : undefined;
+            const config = await loadConfig();
+            if (args.includes('build-runner'))
+                data = await buildUiRunner(config, {}, true);
+            else if (plan)
+                data = await runUiPlan(config, plan);
+            else
+                throw new CliError('COMMAND_INVALID', 'ui requires build-runner or run --plan=<file>');
+        }
+        else if (command === 'build') {
+            const config = await loadConfig();
+            data = await buildApp(config);
+        }
+        else if (command === 'app') {
+            const config = await loadConfig();
+            const action = ['install', 'launch', 'terminate', 'restart', 'open-url'].find((name) => args.includes(name));
+            if (!action)
+                throw new Error('app requires install, launch, terminate, or restart');
+            data = await controlApp(config, action, {
+                arguments: args.filter((arg) => arg.startsWith('--arg=')).map((arg) => arg.slice('--arg='.length)),
+                environment: args.filter((arg) => arg.startsWith('--env=')).map((arg) => arg.slice('--env='.length)),
+                url: args.find((arg) => arg.startsWith('--url='))?.slice('--url='.length),
+            });
+        }
+        else if (command === 'logs') {
+            const config = await loadConfig();
+            if (!args.includes('show'))
+                throw new CliError('COMMAND_INVALID', 'logs requires show');
+            data = await showLogs(config, {
+                last: option('last'), level: option('level'), limit: option('limit') === undefined ? undefined : Number(option('limit')),
+            });
+        }
+        else if (command === 'diagnose') {
+            const config = await loadConfig();
+            data = await diagnose(config, {
+                last: option('last'), level: option('level'), limit: option('limit') === undefined ? undefined : Number(option('limit')),
+            });
+        }
+        else if (command === 'doctor') {
+            data = await doctor();
+        }
+        else
+            throw new CliError('COMMAND_INVALID', `Unknown command: ${command}`);
+        writeResult({ ok: true, data }, pretty);
+    }
+    catch (error) {
+        writeResult(errorResult(error, debug), pretty);
+        process.exitCode = 1;
+    }

package/dist/commands/app.js

@@ -0,0 +1,78 @@
+import { access, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { CliError } from '../core/errors.js';
+import { redact } from '../core/redact.js';
+import { listDevices, resolveDevice, simctl } from '../native/simctl.js';
+const stopped = (value) => /not running|no such process|found nothing to terminate/i.test(value);
+async function checked(runner, args, secrets, allowStopped = false, options) {
+    const result = await runner(args, options);
+    if (result.exitCode !== 0 && !(allowStopped && stopped(result.stderr))) {
+        throw new CliError('PROCESS_FAILED', redact(result.stderr.trim() || `simctl ${args[0]} failed`, secrets), {
+            command: ['xcrun', 'simctl', ...args].map((value) => redact(value, secrets)), exitCode: result.exitCode, signal: result.signal,
+        });
+    }
+}
+function launchEnvironment(values) {
+    const environment = { ...process.env };
+    for (const value of values) {
+        const separator = value.indexOf('=');
+        const name = value.slice(0, separator);
+        if (separator < 1 || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+            throw new CliError('COMMAND_INVALID', '--env must use KEY=VALUE with a valid environment variable name');
+        }
+        environment[`SIMCTL_CHILD_${name}`] = value.slice(separator + 1);
+    }
+    return environment;
+}
+async function defaultState(file, secrets) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        throw new CliError('APP_NOT_BUILT', redact(`Cannot read app state: ${error instanceof Error ? error.message : String(error)}`, secrets));
+    }
+}
+export async function controlApp(config, action, options = {}, dependencies = {}) {
+    const runner = dependencies.runner ?? simctl;
+    const udid = await (dependencies.resolveUdid
+        ? dependencies.resolveUdid(config)
+        : config.simulator.udid ?? listDevices().then((devices) => resolveDevice(devices, config.simulator).udid));
+    const stateFile = path.join(config.root, '.agemu', 'state.json');
+    const secrets = config.redactions ?? [];
+    const bundleId = config.bundleId;
+    const terminate = () => checked(runner, ['terminate', udid, bundleId], secrets, true);
+    const launch = () => checked(runner, [
+        'launch', udid, bundleId, ...(options.arguments ?? []),
+    ], secrets, false, { env: launchEnvironment(options.environment ?? []) });
+    if (action === 'install') {
+        const state = dependencies.readState
+            ? await dependencies.readState(stateFile)
+            : await defaultState(stateFile, secrets);
+        if (state.bundleId !== bundleId || state.udid !== udid || state.configuration !== config.configuration) {
+            throw new CliError('APP_NOT_BUILT', 'Cached app state does not match the configured app, simulator, and configuration');
+        }
+        try {
+            await (dependencies.appExists ?? access)(state.appPath);
+        }
+        catch {
+            throw new CliError('APP_NOT_BUILT', redact(`Cached app product does not exist: ${state.appPath}`, secrets));
+        }
+        await checked(runner, ['install', udid, state.appPath], secrets);
+    }
+    else if (action === 'launch') {
+        await launch();
+    }
+    else if (action === 'terminate') {
+        await terminate();
+    }
+    else if (action === 'restart') {
+        await terminate();
+        await launch();
+    }
+    else {
+        if (!options.url)
+            throw new CliError('COMMAND_INVALID', 'app open-url requires --url=<url>');
+        await checked(runner, ['openurl', udid, options.url], secrets);
+    }
+    return { action, udid, bundleId };
+}

package/dist/commands/build.js

@@ -0,0 +1,100 @@
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { CliError } from '../core/errors.js';
+import { redact } from '../core/redact.js';
+import { buildArguments, selectBuildProduct } from '../native/xcodebuild.js';
+import { listDevices, resolveDevice } from '../native/simctl.js';
+import { runProcess } from '../process/run-process.js';
+function runId(date) {
+    return date.toISOString().replaceAll(':', '-');
+}
+async function writeAtomic(file, state) {
+    const temporary = `${file}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, file);
+}
+function logFromError(error, secrets) {
+    const result = error instanceof CliError ? error.details?.result : undefined;
+    const output = typeof result === 'object' && result !== null ? result : {};
+    return {
+        stdout: redact(typeof output.stdout === 'string' ? output.stdout : '', secrets),
+        stderr: redact(typeof output.stderr === 'string' ? output.stderr : '', secrets),
+        executionError: redact(error instanceof Error ? error.message : String(error), secrets),
+    };
+}
+async function writeLog(file, log) {
+    await writeFile(file, `${JSON.stringify(log, null, 2)}\n`, { mode: 0o600 });
+}
+export async function buildApp(config, dependencies = {}) {
+    const run = dependencies.run ?? runProcess;
+    const now = dependencies.now?.() ?? new Date();
+    const udid = await (dependencies.resolveUdid
+        ? dependencies.resolveUdid(config)
+        : config.simulator.udid ?? listDevices().then((devices) => resolveDevice(devices, config.simulator).udid));
+    const stateDirectory = path.join(config.root, '.agemu');
+    const runDirectory = path.join(stateDirectory, 'runs', runId(now));
+    await mkdir(runDirectory, { recursive: true });
+    const secrets = config.redactions ?? [];
+    const buildLog = path.join(runDirectory, 'xcodebuild.log');
+    let build;
+    try {
+        build = await run('xcodebuild', buildArguments(config, udid, 'build'));
+    }
+    catch (error) {
+        await writeLog(buildLog, logFromError(error, secrets));
+        throw new CliError('BUILD_FAILED', 'Unable to execute xcodebuild', { log: redact(path.relative(config.root, buildLog), secrets) });
+    }
+    await writeLog(buildLog, { stdout: redact(build.stdout, secrets), stderr: redact(build.stderr, secrets) });
+    if (build.exitCode !== 0) {
+        throw new CliError('BUILD_FAILED', 'xcodebuild failed', {
+            exitCode: build.exitCode,
+            signal: build.signal,
+            log: redact(path.relative(config.root, buildLog), secrets),
+        });
+    }
+    const settingsLog = path.join(runDirectory, 'build-settings.log');
+    let settings;
+    try {
+        settings = await run('xcodebuild', buildArguments(config, udid, 'settings'));
+    }
+    catch (error) {
+        await writeLog(settingsLog, logFromError(error, secrets));
+        throw new CliError('BUILD_FAILED', 'Unable to execute xcodebuild for build settings', { log: redact(path.relative(config.root, settingsLog), secrets) });
+    }
+    await writeLog(settingsLog, { stdout: redact(settings.stdout, secrets), stderr: redact(settings.stderr, secrets) });
+    if (settings.exitCode !== 0) {
+        throw new CliError('BUILD_FAILED', 'Unable to read build settings', {
+            exitCode: settings.exitCode,
+            signal: settings.signal,
+            log: redact(path.relative(config.root, settingsLog), secrets),
+        });
+    }
+    let product;
+    try {
+        product = selectBuildProduct(settings.stdout, config.bundleId);
+    }
+    catch (error) {
+        throw new CliError('BUILD_FAILED', redact(error instanceof Error ? error.message : String(error), secrets), {
+            log: redact(path.relative(config.root, settingsLog), secrets),
+        });
+    }
+    const state = {
+        appPath: product.appPath,
+        bundleId: product.bundleId,
+        executableName: product.executableName,
+        udid,
+        configuration: config.configuration,
+        updatedAt: now.toISOString(),
+    };
+    await writeAtomic(path.join(stateDirectory, 'state.json'), state);
+    return {
+        appPath: redact(product.appPath, secrets),
+        bundleId: redact(product.bundleId, secrets),
+        executableName: redact(product.executableName, secrets),
+        target: redact(product.target, secrets),
+        udid: redact(udid, secrets),
+        configuration: redact(config.configuration, secrets),
+        derivedData: redact(path.join(stateDirectory, 'DerivedData'), secrets),
+        logs: { build: redact(path.relative(config.root, buildLog), secrets), settings: redact(path.relative(config.root, settingsLog), secrets) },
+    };
+}

package/dist/commands/diagnostics.js

@@ -0,0 +1,166 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { appendEvent, createRun, redactValue } from '../artifacts/runs.js';
+import { CliError } from '../core/errors.js';
+import { redact } from '../core/redact.js';
+import { listDevices, resolveDevice, simctl } from '../native/simctl.js';
+const allowedLevels = new Set(['default', 'info', 'debug', 'error', 'fault']);
+async function configuredDevice(config) {
+    return resolveDevice(await listDevices(), config.simulator);
+}
+async function state(config, dependencies) {
+    const file = path.join(config.root, '.agemu', 'state.json');
+    try {
+        return dependencies.readState ? await dependencies.readState(file) : JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        throw new CliError('APP_NOT_BUILT', `Cannot read app state: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function safeRelative(root, file, secrets) {
+    return redact(path.relative(root, file), secrets);
+}
+async function runContext(config, dependencies) {
+    const now = dependencies.now?.() ?? new Date();
+    const [run, device] = await Promise.all([
+        createRun(config.root, now),
+        dependencies.resolveDevice ? dependencies.resolveDevice(config) : configuredDevice(config),
+    ]);
+    return { run, now, device };
+}
+function failure(error, secrets) {
+    const normalized = error instanceof CliError ? error : new CliError('PROCESS_FAILED', error instanceof Error ? error.message : String(error));
+    return { code: normalized.code, message: redact(normalized.message, secrets) };
+}
+export async function observe(config, dependencies = {}) {
+    const secrets = config.redactions ?? [];
+    const { run, now, device } = await runContext(config, dependencies);
+    const directory = path.join(run.directory, 'screenshots');
+    const screenshot = path.join(directory, 'screen.png');
+    await mkdir(directory, { recursive: true });
+    const args = ['io', device.udid, 'screenshot', screenshot];
+    try {
+        const result = await (dependencies.runner ?? simctl)(args);
+        if (result.exitCode !== 0)
+            throw new CliError('PROCESS_FAILED', result.stderr.trim() || 'Screenshot capture failed');
+        const data = {
+            run: run.relativeDirectory, screenshot: safeRelative(config.root, screenshot, secrets), capturedAt: now.toISOString(),
+            simulator: redactValue(device, secrets), bundleId: redact(config.bundleId, secrets),
+        };
+        await appendEvent(config.root, { at: now.toISOString(), command: 'observe', status: 'ok', data }, secrets);
+        return data;
+    }
+    catch (error) {
+        const details = { run: run.relativeDirectory, simulator: redactValue(device, secrets), bundleId: redact(config.bundleId, secrets) };
+        await appendEvent(config.root, { at: now.toISOString(), command: 'observe', status: 'error', error: failure(error, secrets), details }, secrets);
+        throw new CliError('PROCESS_FAILED', redact(error instanceof Error ? error.message : String(error), secrets), details);
+    }
+}
+function predicate(app) {
+    if (!app.executableName)
+        throw new CliError('APP_NOT_BUILT', 'Cached app state does not contain an executable name; rebuild the app');
+    const processName = app.executableName.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+    return `process == "${processName}"`;
+}
+function logArguments(level, app) {
+    const processPredicate = predicate(app);
+    if (level === 'info')
+        return ['--info', '--predicate', processPredicate];
+    if (level === 'debug')
+        return ['--debug', '--predicate', processPredicate];
+    if (level === 'error')
+        return ['--predicate', `${processPredicate} AND (messageType == error OR messageType == fault)`];
+    if (level === 'fault')
+        return ['--predicate', `${processPredicate} AND messageType == fault`];
+    return ['--predicate', processPredicate];
+}
+export async function showLogs(config, options = {}, dependencies = {}) {
+    const secrets = config.redactions ?? [];
+    const last = options.last ?? '30s';
+    const level = options.level ?? 'default';
+    const limit = options.limit ?? 100;
+    if (!/^\d+[smhd]$/.test(last))
+        throw new CliError('COMMAND_INVALID', '--last must be a number followed by s, m, h, or d');
+    if (!allowedLevels.has(level))
+        throw new CliError('COMMAND_INVALID', '--level must be default, info, debug, error, or fault');
+    if (!Number.isSafeInteger(limit) || limit < 0 || limit > 10_000)
+        throw new CliError('COMMAND_INVALID', '--limit must be an integer from 0 to 10000');
+    const { run, now, device } = await runContext(config, dependencies);
+    const app = await state(config, dependencies);
+    if (app.bundleId !== config.bundleId || app.udid !== device.udid)
+        throw new CliError('APP_NOT_BUILT', 'Cached app state does not match the configured app and simulator');
+    const artifact = path.join(run.directory, 'logs.txt');
+    const args = ['spawn', device.udid, 'log', 'show', '--last', last, ...logArguments(level, app), '--style', 'compact'];
+    let result;
+    try {
+        result = await (dependencies.runner ?? simctl)(args);
+    }
+    catch (error) {
+        const captured = error instanceof CliError && typeof error.details?.result === 'object' && error.details.result !== null
+            ? error.details.result
+            : {};
+        const full = redact(`${typeof captured.stdout === 'string' ? captured.stdout : ''}${typeof captured.stderr === 'string' ? captured.stderr : ''}`, secrets);
+        await writeFile(artifact, full, { mode: 0o600 });
+        const details = { artifact: safeRelative(config.root, artifact, secrets), run: run.relativeDirectory };
+        await appendEvent(config.root, { at: now.toISOString(), command: 'logs show', status: 'error', args, error: failure(error, secrets), details }, secrets);
+        throw new CliError(error instanceof CliError ? error.code : 'PROCESS_FAILED', redact(error instanceof Error ? error.message : String(error), secrets), details);
+    }
+    const full = redact(`${result.stdout}${result.stderr}`, secrets);
+    await writeFile(artifact, full, { mode: 0o600 });
+    if (result.exitCode !== 0) {
+        const details = { artifact: safeRelative(config.root, artifact, secrets), run: run.relativeDirectory };
+        const error = new CliError('PROCESS_FAILED', redact(result.stderr.trim() || 'Log collection failed', secrets), details);
+        await appendEvent(config.root, { at: now.toISOString(), command: 'logs show', status: 'error', args, error: failure(error, secrets), details }, secrets);
+        throw error;
+    }
+    const lines = full.split(/\r?\n/).filter((line, index, all) => line || index < all.length - 1);
+    const data = {
+        run: run.relativeDirectory, udid: redact(device.udid, secrets), bundleId: redact(config.bundleId, secrets), last, level,
+        logs: limit === 0 ? [] : lines.slice(-limit), truncated: lines.length > limit,
+        artifact: safeRelative(config.root, artifact, secrets), capturedAt: now.toISOString(),
+    };
+    await appendEvent(config.root, { at: now.toISOString(), command: 'logs show', status: 'ok', args, data }, secrets);
+    return data;
+}
+export async function diagnose(config, options = {}, dependencies = {}) {
+    const now = dependencies.now?.() ?? new Date();
+    const secrets = config.redactions ?? [];
+    const evidence = {};
+    const failures = {};
+    try {
+        evidence.simulator = redactValue(await (dependencies.resolveDevice ? dependencies.resolveDevice(config) : configuredDevice(config)), secrets);
+    }
+    catch (error) {
+        failures.simulator = failure(error, secrets);
+    }
+    try {
+        evidence.build = redactValue(await state(config, dependencies), secrets);
+    }
+    catch (error) {
+        failures.build = failure(error, secrets);
+    }
+    try {
+        evidence.observation = await observe(config, { ...dependencies, now: () => now });
+    }
+    catch (error) {
+        failures.observation = failure(error, secrets);
+    }
+    try {
+        evidence.logs = await showLogs(config, options, { ...dependencies, now: () => now });
+    }
+    catch (error) {
+        failures.logs = failure(error, secrets);
+    }
+    try {
+        const eventsFile = path.join(config.root, '.agemu', 'events.jsonl');
+        const contents = dependencies.readEvents ? await dependencies.readEvents(eventsFile) : await readFile(eventsFile, 'utf8');
+        evidence.recentErrors = redactValue(String(contents).split('\n').filter(Boolean).map((line) => JSON.parse(line))
+            .filter((event) => event.status === 'error').slice(-10), secrets);
+    }
+    catch {
+        evidence.recentErrors = [];
+    }
+    const data = { generatedAt: now.toISOString(), bundleId: redact(config.bundleId, secrets), partial: Object.keys(failures).length > 0, evidence, failures };
+    await appendEvent(config.root, { at: now.toISOString(), command: 'diagnose', status: data.partial ? 'partial' : 'ok', data }, secrets);
+    return data;
+}