xcodebuild-axi 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+Notable changes to `xcodebuild-axi`. Versions follow
+[semver](https://semver.org/); the format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-21
+
+First release.
+
+### Added
+
+- **`build`, `test`, `tests`, `clean`, `analyze`, `archive`, `export`** — run an
+  action and report from the `.xcresult` bundle rather than the transcript.
+  Diagnostics carry `file,line,col`; the full log is streamed to a file and
+  never read into memory.
+- **`schemes`, `destinations`, `testplans`, `settings`, `packages`, `info`** —
+  read-only queries that answer one question each.
+- **`result`, `coverage`** — re-read a previous run's bundle without rebuilding.
+- **`sim`, `platforms`** — inspect and boot simulators, list runtimes, and drive
+  platform downloads.
+- **`localize`, `xcframework`, `find`, `migrate`** — XLIFF import/export,
+  `.xcframework` assembly, toolchain lookup, and project-format conversion.
+- **`setup hooks`** — session-start hooks for Claude Code, Codex, and OpenCode,
+  plus a bundled skill for agents that read the skill format.
+- Destinations resolve to a simulator **udid** before the run, so a duplicated
+  device name cannot silently send a run to the wrong runtime, and the reported
+  destination is read back out of the result bundle.
+- 100% of the 117 options `xcodebuild -help` lists are covered, declared in
+  `src/surface.ts` and checked against the installed Xcode in CI.
+
+[unreleased]: https://github.com/alexrrouse/xcodebuild-axi/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/alexrrouse/xcodebuild-axi/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Rouse
+
+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,304 @@
+<h1 align="center">xcodebuild-axi</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/xcodebuild-axi"><img alt="npm" src="https://img.shields.io/npm/v/xcodebuild-axi?style=flat-square" /></a>
+  <a href="https://axi.md/"><img alt="AXI" src="https://img.shields.io/badge/AXI-compliant-blue?style=flat-square" /></a>
+  <img alt="Platform" src="https://img.shields.io/badge/platform-macOS-lightgrey?style=flat-square" />
+  <!-- coverage-badge:start --><img alt="xcodebuild coverage" src="https://img.shields.io/badge/xcodebuild_coverage-100%25-brightgreen?style=flat-square" /><!-- coverage-badge:end -->
+  <img alt="License" src="https://img.shields.io/badge/license-MIT-green?style=flat-square" />
+</p>
+
+<h3 align="center">A passing test run should not cost 549 KB of context.</h3>
+
+`xcodebuild` tells an agent everything and therefore nothing. One passing test
+run of a single app in a real iOS workspace prints **549,290 bytes across 6,595
+lines** — 767 of which say a test passed, and none of which say anything went
+wrong. A full verify run of the same repo prints 2.5 MB. An agent that has to
+read that to learn one number pays for it on every change, several times over.
+
+`xcodebuild-axi` runs the same build and reports the answer.
+
+```sh
+$ xcodebuild-axi test --scheme MyApp --device "iPhone 17 Pro"
+test: passed
+scheme: MyApp
+destination: iPhone 17 Pro · iOS Simulator 26.5
+tests: 767 passed / 0 failed / 0 skipped
+duration: 15m34s
+log: ~/Library/Caches/xcodebuild-axi/MyApps-1a2b3c4d/MyApp-iPhone-17-Pro-test.log
+result: ~/Library/Caches/xcodebuild-axi/MyApps-1a2b3c4d/MyApp-iPhone-17-Pro-test.xcresult
+```
+
+The whole transcript still lands in `log`, so nothing is lost — it just stops
+being the default answer.
+
+## Why it can be this small
+
+The transcript is not the best record of a build. The `.xcresult` bundle
+xcodebuild writes alongside it is: a few KB of JSON carrying pass/fail counts,
+the device the run actually landed on, and every diagnostic with a precise
+source location. `xcodebuild-axi` streams the transcript straight to a log file
+it never reads into memory, then reports from the bundle.
+
+That also makes it more accurate than grepping. A failed build reports the real
+error with the real line:
+
+```sh
+$ xcodebuild-axi build --scheme Probe
+build: failed
+scheme: Probe
+destination: My Mac · macOS 26.6.1
+duration: 4.6s
+errors[1]{file,line,col,type,message}:
+  Sources/Probe/Probe.swift,2,25,swift,Cannot convert value of type 'String' to specified type 'Int'
+log: ~/Library/Caches/xcodebuild-axi/Probe-9f8e7d6c/Probe-My-Mac-build.log
+```
+
+21,636 bytes of transcript, one line of answer.
+
+## Measured
+
+Every number below is produced by `npm run benchmark`, which asks raw
+`xcodebuild` and `xcodebuild-axi` the same question against a real 12-scheme
+iOS workspace with 16 local Swift packages, and tokenizes both answers.
+
+<!-- benchmark:start -->
+
+| Question                                | `xcodebuild`   | `xcodebuild-axi` | Saved      |
+| --------------------------------------- | -------------- | ---------------- | ---------- |
+| what can I build?                       | 498 tok        | 97 tok           | **80.52%** |
+| what can I run it on?                   | 1,720 tok      | 339 tok          | **80.29%** |
+| what is the bundle id?                  | 12,221 tok     | 21 tok           | **99.83%** |
+| which targets have index settings?      | 61,850 tok     | 42 tok           | **99.93%** |
+| which SDKs are installed?               | 244 tok        | 70 tok           | **71.31%** |
+| which test plans does this scheme have? | 445 tok        | 42 tok           | **90.56%** |
+| **all 6 together**                      | **76,978 tok** | **611 tok**      | **99.21%** |
+
+Token counts are GPT-4o BPE via `gpt-tokenizer` — Anthropic's tokenizer is not public, so this is a stand-in, and the ratios are what matter rather than the absolute numbers. Both stdout and stderr are counted, because that is what an agent running the command in a shell actually reads. Measured by `npm run benchmark` against one app of a real multi-scheme iOS workspace on 2026-09-21.
+
+<!-- benchmark:end -->
+
+Those are the read-only commands, and they win anyway, because xcodebuild
+reprints its invocation, `Resolve Package Graph`, and the full resolved package
+list on _every_ call — about 1.2 KB of identical preamble in front of a
+349-byte answer.
+
+The `build` and `test` rows are where the margin is widest and are not in the
+table above: they drive a cold build per side and want a quiet machine. Add
+them with
+
+```sh
+npm run benchmark -- --project ~/YourApp --scheme YourScheme --only build --resume --write
+npm run benchmark -- --project ~/YourApp --scheme YourScheme --only test  --resume --write
+```
+
+For scale in the meantime: one `build` of the scheme above wrote a **4.7 MB**
+transcript to its log, and a `test` run of another app in the same workspace
+wrote **432 KB**. Both are reported in well under 400 bytes.
+
+Reproduce any of it yourself:
+
+```sh
+npm run benchmark -- --project ~/YourApp --scheme YourScheme          # everything
+npm run benchmark -- --project ~/YourApp --scheme YourScheme --quick  # skip build and test
+```
+
+Builds and tests get a separate derived-data directory per side, wiped before
+each run, so neither side gets an incremental-build advantage over the other.
+Every scenario is checkpointed as it finishes, so `--resume` picks up whatever
+already ran.
+
+## Install
+
+```sh
+npm install -g xcodebuild-axi
+```
+
+Or run it without installing:
+
+```sh
+npx -y xcodebuild-axi
+```
+
+Requires macOS with Xcode installed, and Node 20+.
+
+## Commands
+
+Running it with no arguments shows the project in front of you, not a manual:
+
+```sh
+$ xcodebuild-axi
+bin: ~/.local/bin/xcodebuild-axi
+description: Agent-ergonomic wrapper around xcodebuild.
+workspace: MyApps
+scheme_count: 12
+schemes[12]: Analytics,Checkout,DesignSystem,Feed,MyApp,MyApp-Widget,...
+last: Test - Checkout on iPhone 17 Pro · iOS Simulator 26.5 — 89 passed (4m ago)
+help[2]:
+  Run `xcodebuild-axi build --scheme <name>` to build
+  Run `xcodebuild-axi test --scheme <name>` to run tests
+```
+
+| Command        | What it does                                                      |
+| -------------- | ----------------------------------------------------------------- |
+| _(none)_       | Dashboard: what is here, what can be built, how the last run went |
+| `build`        | Build a scheme; report only errors, with `file,line,col`          |
+| `test`         | Run tests; report counts and only the failures                    |
+| `tests`        | Enumerate the tests a scheme defines, without running them        |
+| `clean`        | Clean a scheme's build products                                   |
+| `analyze`      | Run the static analyzer; report only what it found                |
+| `archive`      | Archive a scheme and report the archive's bundle id and version   |
+| `export`       | Export an archive, writing the export options plist for you       |
+| `schemes`      | List the schemes in the workspace or project                      |
+| `destinations` | List the destinations a scheme can actually run on                |
+| `testplans`    | List a scheme's test plans                                        |
+| `settings`     | Read named build settings instead of dumping all 400              |
+| `packages`     | Read the pinned Swift package versions; resolve them on request   |
+| `info`         | Xcode version, SDKs, and what this tool is pointed at             |
+| `result`       | Re-read a previous run's `.xcresult` without rebuilding           |
+| `coverage`     | Code coverage from a result bundle, per target or per file        |
+| `sim`          | Boot, shut down, and inspect simulators                           |
+| `platforms`    | Installed runtimes, and the downloads that add more               |
+| `localize`     | Export and import XLIFF localization catalogs                     |
+| `xcframework`  | Bundle built frameworks or libraries into an `.xcframework`       |
+| `find`         | Resolve an executable or library to its toolchain path            |
+| `migrate`      | Report the project file format, and convert it to a newer one     |
+| `setup`        | Install session-start hooks for Claude Code, Codex, and OpenCode  |
+
+Every command takes `--help`.
+
+## How much of xcodebuild
+
+<!-- coverage:start -->
+
+**Coverage: 100% — every one of the 117 options `xcodebuild -help` lists, and 9 of its 10 build actions.**
+
+107 options map to an `xcodebuild-axi` flag. The other 10 are reachable without one:
+
+| Option                          | How                                                                                            |
+| ------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `-json`                         | every read-only query asks for JSON, then reports TOON                                         |
+| `-project`                      | set from the .xcodeproj found in the working directory                                         |
+| `-resultBundlePath`             | every action writes a bundle to the tool's cache — that bundle is what the report is read from |
+| `-skipMacroValidation`          | macro trust is an interactive prompt in disguise, and an agent cannot answer it                |
+| `-test-enumeration-format`      | always json, so `tests` can parse it                                                           |
+| `-test-enumeration-output-path` | written to the tool's cache and read back, never printed                                       |
+| `-test-enumeration-style`       | always flat; `tests` does its own grouping by target and suite                                 |
+| `-workspace`                    | set from the .xcworkspace found in the working directory                                       |
+| `-help`                         | `xcodebuild-axi --help`, which answers it in a fraction of the tokens                          |
+| `-usage`                        | `xcodebuild-axi <command> --help`, per command rather than all 117 at once                     |
+
+The one action left out is `installsrc` — it copies sources into `SRCROOT` as root, which is a packaging step rather than anything an agent loop needs.
+
+The denominator is read from `xcodebuild -help` rather than hand-maintained, and this table is written against **Xcode 27.0** — the option list moves between releases. `npm run coverage:check` fails on that Xcode if an option here is unclassified or has been dropped, and reports the difference without failing on any other.
+
+<!-- coverage:end -->
+
+### Destinations you do not have to spell
+
+The `-destination` specifier is the thing agents most reliably get wrong
+against raw `xcodebuild`, and a miss costs a whole failed invocation. Pass a
+name, or pass nothing:
+
+```sh
+xcodebuild-axi test --scheme MyApp --device "iPhone 17 Pro"   # matched for you
+xcodebuild-axi test --scheme MyApp                            # newest simulator
+xcodebuild-axi test --scheme MyApp --destination "platform=iOS Simulator,id=…"
+```
+
+Names are resolved to a simulator **udid** before the run, because two runtimes
+routinely publish the same device name and a name-based specifier silently
+picks whichever xcodebuild sees first. The reported destination is the one the
+run actually landed on, read back out of the result bundle.
+
+### Reading a run again
+
+`build` and `test` both print the bundle they wrote, so nothing needs re-running
+to be re-read:
+
+```sh
+xcodebuild-axi result ~/Library/Caches/xcodebuild-axi/MyApps-1a2b3c4d/MyApp-test.xcresult --failures --full
+```
+
+## Ambient context
+
+Two ways to get this in front of an agent before it reaches for raw
+`xcodebuild`. You only need one.
+
+**Session hooks** — the project's schemes and last run become context at the
+start of every session:
+
+```sh
+xcodebuild-axi setup hooks              # your home directory
+xcodebuild-axi setup hooks --project    # just this repository
+xcodebuild-axi setup hooks --status     # report, writing nothing
+```
+
+Covers Claude Code, Codex, and OpenCode. Installs are idempotent and repair a
+stale path.
+
+**A skill** — loads on demand instead of on every session, and works in any
+agent that reads the skill format:
+
+```sh
+npx skills add alexrrouse/xcodebuild-axi --skill xcodebuild-axi
+```
+
+## Conventions
+
+- **Output is [TOON](https://toonformat.dev/)** on stdout, ~40% cheaper than the
+  equivalent JSON.
+- **Errors are data.** They go to stdout in the same shape as an answer, with a
+  `code` and a `help[]` that names the command that fixes it.
+- **Exit codes**: `0` success, `1` the build or tests failed, `2` usage error.
+  A failed build still prints its full report — the exit code is for your `&&`,
+  the report is for the agent.
+- **Unknown flags fail loudly**, by name, with the valid set listed inline. A
+  silently dropped filter is worse than an error.
+- **Nothing is written to your repository.** Logs and result bundles live under
+  `~/Library/Caches/xcodebuild-axi/`, keyed by project path.
+- **No interactive prompts, ever.** Code signing is off by default so simulator
+  builds need no team; pass `--sign` when you mean it.
+
+## Environment
+
+| Variable         | Effect                                           |
+| ---------------- | ------------------------------------------------ |
+| `XCODEBUILD_BIN` | Override the wrapped `xcodebuild` binary         |
+| `DEVELOPER_DIR`  | Select an Xcode, as `xcodebuild` itself reads it |
+
+## Development
+
+```sh
+npm install
+npm run dev -- destinations --scheme MyApp   # run from source
+npm test
+```
+
+Everything CI checks, in order:
+
+```sh
+npm run format:check && npm run lint && npx tsc --noEmit && npm test
+npm run build && npm run build:skill -- --check && npm run coverage:check
+```
+
+Three committed files are generated and fail CI when stale: the skill
+(`npm run build:skill`, from the CLI's own help text), the coverage table
+(`npm run coverage`, from `src/surface.ts`), and the benchmark table
+(`npm run benchmark -- --write`). Regenerate rather than editing them.
+
+Adding a flag means three edits — the command, `src/surface.ts`, and
+`npm run coverage` — and the `flags[N]:` count in a help block is asserted by
+`test/help.test.ts`, so a forgotten count fails the suite.
+
+Examples in help text, tests, and this README use a fictional project
+vocabulary (`MyApp`, `MyApps`, `MyApps-1a2b3c4d`); see `AGENTS.md`.
+
+## Built on
+
+[AXI](https://axi.md/) — the design standard for agent-facing CLIs — via
+[`axi-sdk-js`](https://www.npmjs.com/package/axi-sdk-js).
+
+## License
+
+MIT

package/dist/bin/xcodebuild-axi.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/xcodebuild-axi.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { tryFastPath } from "axi-sdk-js/fast-path";
+import { VERSION } from "../src/version.js";
+if (!tryFastPath(process.argv.slice(2), { version: VERSION })) {
+    const { main } = await import("../src/cli.js");
+    await main();
+}
+//# sourceMappingURL=xcodebuild-axi.js.map

package/dist/bin/xcodebuild-axi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xcodebuild-axi.js","sourceRoot":"","sources":["../../bin/xcodebuild-axi.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAC9D,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;IAC/C,MAAM,IAAI,EAAE,CAAC;AACf,CAAC"}

package/dist/src/action.d.ts

@@ -0,0 +1,68 @@
+import { type ProjectContext } from "./context.js";
+import { type BuildRun } from "./xcodebuild.js";
+/**
+ * The machinery shared by every command that runs an xcodebuild *action* —
+ * build, analyze, archive, clean, and the test family. They differ in which
+ * action word they pass and what they say afterwards; everything before that
+ * (finding the project, resolving the scheme and destination, assembling
+ * flags, streaming to a log, reading the bundle back) is identical, and was
+ * worth extracting the first time a second command needed it.
+ */
+/** Flags every build-family command accepts. Keep in sync with `BUILD_FLAG_HELP`. */
+export declare const SHARED_BUILD_FLAGS: readonly ["--scheme", "--target", "--all-targets", "--device", "--destination", "--configuration", "--sdk", "--arch", "--toolchain", "--xcconfig", "--derived-data", "--jobs", "--setting", "--sign", "--allow-provisioning", "--sanitizer", "--timing", "--destination-timeout", "--parallelize-targets", "--hide-script-env", "--skip-unavailable-actions", "--max-errors", "--full", "--codesize", "--log-level", "--bundle-version", "--stream", "--offline", "--cache", "--package-cache", "--no-auto-resolve", "--skip-package-updates", "--no-package-cache", "--skip-plugin-validation", "--skip-signature-validation", "--package-auth", "--registry-url", "--scm-to-registry", "--fingerprint-policy", "--signing-entity-policy", "--scm-provider"];
+export declare const SHARED_BUILD_VALUE_FLAGS: readonly ["--scheme", "--target", "--device", "--destination", "--configuration", "--sdk", "--arch", "--toolchain", "--xcconfig", "--derived-data", "--jobs", "--setting", "--sanitizer", "--destination-timeout", "--max-errors", "--codesize", "--log-level", "--bundle-version", "--stream", "--cache", "--package-cache", "--package-auth", "--registry-url", "--scm-to-registry", "--fingerprint-policy", "--signing-entity-policy", "--scm-provider"];
+/** The shared flag block, so each command's `--help` stays consistent. */
+export declare const BUILD_FLAG_HELP = "  --scheme <name>         scheme to act on (required only when the project has more than one)\n  --target <name>         build a target instead of a scheme; repeatable (project only)\n  --all-targets           build every target in the project (project only)\n  --device <name>         simulator or device name, e.g. \"iPhone 17 Pro\" (default: newest simulator)\n  --destination <spec>    raw xcodebuild destination specifier, passed through untouched\n  --configuration <name>  build configuration (default: the scheme's own)\n  --sdk <name>            base SDK, e.g. iphonesimulator\n  --arch <arch>           architecture to build; repeatable or comma-separated\n  --toolchain <name>      toolchain identifier or name\n  --xcconfig <path>       apply build settings from this file as overrides\n  --derived-data <path>   derived data directory\n  --jobs <n>              maximum concurrent build operations\n  --setting KEY=VALUE     build setting override; repeatable or comma-separated\n  --sign                  allow code signing (off by default, so simulator builds need no team)\n  --allow-provisioning    let xcodebuild talk to the developer portal for profiles\n  --sanitizer <name>      address, thread, or undefined; repeatable or comma-separated\n  --timing                report per-command build timings\n  --destination-timeout <secs>  how long to wait for the destination device\n  --parallelize-targets   build independent targets in parallel\n  --hide-script-env       omit shell script environment variables from the log\n  --skip-unavailable-actions  skip scheme actions that cannot run instead of failing\n  --max-errors <n>        errors to list before summarizing the rest (default: 20)\n  --full                  list every warning instead of the first 10\n  --codesize <dir>        write a code size profile to this directory\n  --log-level <level>     quiet, normal, or verbose \u2014 how much lands in the log file\n  --bundle-version <n>    result bundle format version (default: xcodebuild's own)\n  --stream <path>         also write xcodebuild's live result stream here\n  --offline               resolve using only the versions already in Package.resolved\n  --cache <path>          clone remote packages into this directory\n  --package-cache <path>  shared package cache directory (across projects)\n  --no-auto-resolve       never resolve automatically; fail if Package.resolved is stale\n  --skip-package-updates  use the packages already cloned, without checking for updates\n  --no-package-cache      ignore the shared package repository cache\n  --skip-plugin-validation      trust build plugins without prompting\n  --skip-signature-validation   do not verify package signatures\n  --package-auth <kind>   keychain or netrc\n  --registry-url <url>    default package registry\n  --scm-to-registry <kind>      none, identity, or swift-package-registry\n  --fingerprint-policy <kind>   strict or warn\n  --signing-entity-policy <kind>  strict or warn\n  --scm-provider <kind>   system or xcode";
+/**
+ * The flags that map straight onto an xcodebuild switch with no interpretation
+ * beyond validation. Grouped so they can be tested without a project.
+ */
+export declare function buildPassthroughArgs(args: string[], command: string): string[];
+export interface BuildContext {
+    project: ProjectContext;
+    /** The scheme, or a description of the targets when in target mode. */
+    scheme: string;
+    /** Human-readable destination, or undefined when the command skipped one. */
+    destination: string | undefined;
+    /** Everything before the action word. */
+    xcodebuildArgs: string[];
+    maxErrors: number;
+    full: boolean;
+}
+export interface ResolveBuildContextOptions {
+    args: string[];
+    command: string;
+    /** Skip destination resolution — `clean` does not need one, and it costs a subprocess. */
+    needsDestination?: boolean;
+}
+export declare function resolveBuildContext(options: ResolveBuildContextOptions): Promise<BuildContext>;
+/** A filesystem stem that distinguishes runs of different commands and devices. */
+export declare function runLabel(context: BuildContext, command: string): string;
+export interface RunActionOptions {
+    context: BuildContext;
+    command: string;
+    /** xcodebuild action words, in order, e.g. `["clean", "build"]`. */
+    actions: string[];
+    /** Extra arguments appended after the shared ones. */
+    extraArgs?: string[];
+}
+export declare function runAction(options: RunActionOptions): Promise<BuildRun>;
+export interface ReportActionOptions {
+    context: BuildContext;
+    run: BuildRun;
+    /** Field name and success wording, e.g. `{ key: "build", ok: "succeeded" }`. */
+    key: string;
+    ok: string;
+    command: string;
+    /** Extra fields rendered after the destination, e.g. an archive path. */
+    extra?: Record<string, unknown>;
+    /** Report analyzer warnings as the payload rather than as a count. */
+    analyzer?: boolean;
+}
+/**
+ * The shared report for any action that compiles something.
+ *
+ * Errors are the payload on failure, warnings on success, and the full
+ * transcript is always a path away.
+ */
+export declare function reportAction(options: ReportActionOptions): Promise<string>;