xcodebuild-axi 0.1.0

package/dist/src/xcodebuild.d.ts

@@ -0,0 +1,65 @@
+import type { ProjectContext } from "./context.js";
+/** Override the wrapped binary. Unset keeps the PATH lookup. */
+export declare function xcodebuildBin(): string;
+export interface MetadataResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Run a short, read-only xcodebuild invocation and buffer its output.
+ *
+ * Only for the `-list`/`-showdestinations`/`-showBuildSettings` family, whose
+ * output is measured in kilobytes. Builds and tests go through `runBuild`,
+ * which never holds a transcript in memory.
+ */
+export declare function runMetadata(args: string[]): Promise<MetadataResult>;
+export interface BuildRun {
+    exitCode: number;
+    logPath: string;
+    resultPath: string;
+    /** Wall-clock seconds the invocation took. */
+    seconds: number;
+    /** The tail of the transcript, for failures no result bundle explains. */
+    tail: string;
+}
+export interface BuildRunOptions {
+    args: string[];
+    /** Filename stem for the log and result bundle, e.g. "MyApp-iPhone-17-Pro". */
+    label: string;
+    /** Omit for invocations that act on the toolchain rather than a project. */
+    project?: ProjectContext;
+    /** Overrides the cache location for both artifacts. */
+    outDir?: string;
+}
+/**
+ * Run a build or test, streaming the transcript straight to disk.
+ *
+ * The transcript is the thing this tool exists to keep out of the agent's
+ * context, so it is never buffered: a single passing test run of one app in a
+ * real repo measured 549 KB, and a full verify run 2.5 MB. Only the last few
+ * KB are kept in memory, for the failures that produce no result bundle.
+ */
+export declare function runBuild(options: BuildRunOptions): Promise<BuildRun>;
+/**
+ * Where toolchain-level runs land — platform downloads and the like, which
+ * belong to the machine rather than to any one project.
+ */
+export declare function globalArtifactDir(): string;
+/**
+ * Where logs and result bundles land.
+ *
+ * Under the user's cache directory rather than the repo, so running this tool
+ * never dirties a working tree or a `.gitignore`. The project path is hashed
+ * into the name so two checkouts of the same repo do not collide.
+ */
+export declare function artifactDir(project: ProjectContext): string;
+/**
+ * Strip xcodebuild's fixed preamble.
+ *
+ * Every invocation — including the read-only ones — reprints the command line,
+ * "Resolve Package Graph", and the full resolved package list. In a workspace
+ * with 16 local packages that is ~1.2 KB of identical text in front of a 349-byte
+ * answer, paid on every call.
+ */
+export declare function stripPreamble(output: string): string;

package/dist/src/xcodebuild.js

@@ -0,0 +1,163 @@
+import { execFile, spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createWriteStream, mkdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { AxiError, xcodeNotInstalledError } from "./errors.js";
+const MAX_METADATA_BYTES = 8 * 1024 * 1024;
+/** Override the wrapped binary. Unset keeps the PATH lookup. */
+export function xcodebuildBin() {
+    const fromEnv = process.env["XCODEBUILD_BIN"]?.trim();
+    return fromEnv && fromEnv.length > 0 ? fromEnv : "xcodebuild";
+}
+/**
+ * Run a short, read-only xcodebuild invocation and buffer its output.
+ *
+ * Only for the `-list`/`-showdestinations`/`-showBuildSettings` family, whose
+ * output is measured in kilobytes. Builds and tests go through `runBuild`,
+ * which never holds a transcript in memory.
+ */
+export function runMetadata(args) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        execFile(xcodebuildBin(), args, { maxBuffer: MAX_METADATA_BYTES, encoding: "utf-8" }, (error, stdout, stderr) => {
+            if (error && error.code === "ENOENT") {
+                rejectPromise(xcodeNotInstalledError());
+                return;
+            }
+            if (error &&
+                error.code ===
+                    "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+                rejectPromise(new AxiError("xcodebuild produced more output than this command buffers", "UNKNOWN", [
+                    "Use `xcodebuild-axi build` or `test`, which stream to a log instead",
+                ]));
+                return;
+            }
+            resolvePromise({
+                stdout,
+                stderr,
+                exitCode: typeof error?.code === "number" ? error.code : error ? 1 : 0,
+            });
+        });
+    });
+}
+/**
+ * Run a build or test, streaming the transcript straight to disk.
+ *
+ * The transcript is the thing this tool exists to keep out of the agent's
+ * context, so it is never buffered: a single passing test run of one app in a
+ * real repo measured 549 KB, and a full verify run 2.5 MB. Only the last few
+ * KB are kept in memory, for the failures that produce no result bundle.
+ */
+export function runBuild(options) {
+    const dir = options.outDir ??
+        (options.project ? artifactDir(options.project) : globalArtifactDir());
+    mkdirSync(dir, { recursive: true });
+    const logPath = join(dir, `${options.label}.log`);
+    const resultPath = join(dir, `${options.label}.xcresult`);
+    // xcodebuild refuses to write over an existing result bundle and dies before
+    // running anything — "error: Existing file at -resultBundlePath". The bundle
+    // is our artifact, not the user's, so clear it rather than make every caller
+    // remember to.
+    rmSync(resultPath, { recursive: true, force: true });
+    const args = [...options.args, "-resultBundlePath", resultPath];
+    const started = Date.now();
+    return new Promise((resolvePromise, rejectPromise) => {
+        const log = createWriteStream(logPath);
+        const child = spawn(xcodebuildBin(), args, {
+            cwd: process.cwd(),
+            // NSUnbufferedIO makes xcodebuild flush per line, so a wedged run leaves
+            // a usable log instead of an empty one.
+            env: { ...process.env, NSUnbufferedIO: "YES" },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const tail = [];
+        const keepTail = (chunk) => {
+            tail.push(chunk.toString("utf-8"));
+            while (tail.length > 40)
+                tail.shift();
+        };
+        child.stdout.pipe(log, { end: false });
+        child.stderr.pipe(log, { end: false });
+        child.stdout.on("data", keepTail);
+        child.stderr.on("data", keepTail);
+        child.on("error", (error) => {
+            log.end();
+            rejectPromise(error.code === "ENOENT"
+                ? xcodeNotInstalledError()
+                : error);
+        });
+        child.on("close", (code) => {
+            log.end(() => resolvePromise({
+                exitCode: code ?? 1,
+                logPath,
+                resultPath,
+                seconds: (Date.now() - started) / 1000,
+                tail: tail.join("").slice(-8000),
+            }));
+        });
+    });
+}
+/**
+ * Where toolchain-level runs land — platform downloads and the like, which
+ * belong to the machine rather than to any one project.
+ */
+export function globalArtifactDir() {
+    return join(homedir(), "Library", "Caches", "xcodebuild-axi", "toolchain");
+}
+/**
+ * Where logs and result bundles land.
+ *
+ * Under the user's cache directory rather than the repo, so running this tool
+ * never dirties a working tree or a `.gitignore`. The project path is hashed
+ * into the name so two checkouts of the same repo do not collide.
+ */
+export function artifactDir(project) {
+    const hash = createHash("sha256")
+        .update(project.path)
+        .digest("hex")
+        .slice(0, 8);
+    return join(homedir(), "Library", "Caches", "xcodebuild-axi", `${project.name}-${hash}`);
+}
+/**
+ * Strip xcodebuild's fixed preamble.
+ *
+ * Every invocation — including the read-only ones — reprints the command line,
+ * "Resolve Package Graph", and the full resolved package list. In a workspace
+ * with 16 local packages that is ~1.2 KB of identical text in front of a 349-byte
+ * answer, paid on every call.
+ */
+export function stripPreamble(output) {
+    const lines = output.split("\n");
+    const kept = [];
+    let skippingPackageList = false;
+    for (const line of lines) {
+        if (skippingPackageList) {
+            // The list is indented; the first unindented line ends it.
+            if (line.trim().length === 0 || /^\s/.test(line))
+                continue;
+            skippingPackageList = false;
+        }
+        if (/^Resolved source packages:/.test(line)) {
+            skippingPackageList = true;
+            continue;
+        }
+        if (NOISE.some((pattern) => pattern.test(line)))
+            continue;
+        kept.push(line);
+    }
+    return kept
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+const NOISE = [
+    /^Command line invocation:/,
+    /^\s+\/.*\/xcodebuild /,
+    /^Resolve Package Graph$/,
+    /^Prepare packages$/,
+    /^User defaults from command line:/,
+    /^Build settings from command line:/,
+    /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d+ xcodebuild\[\d+:\d+\]/,
+    /^note: /,
+];
+//# sourceMappingURL=xcodebuild.js.map

package/dist/src/xcodebuild.js.map

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

package/dist/src/xcresult.d.ts

@@ -0,0 +1,96 @@
+export interface TestDevice {
+    deviceName?: string;
+    modelName?: string;
+    platform?: string;
+    osVersion?: string;
+    architecture?: string;
+    deviceId?: string;
+}
+export interface TestFailure {
+    testName?: string;
+    targetName?: string;
+    failureText?: string;
+    testIdentifierString?: string;
+}
+export interface TestSummary {
+    title?: string;
+    result?: string;
+    totalTestCount?: number;
+    passedTests?: number;
+    failedTests?: number;
+    skippedTests?: number;
+    expectedFailures?: number;
+    startTime?: number;
+    finishTime?: number;
+    environmentDescription?: string;
+    testFailures?: TestFailure[];
+    runtimeWarnings?: RawIssue[];
+    devicesAndConfigurations?: {
+        device?: TestDevice;
+        passedTests?: number;
+        failedTests?: number;
+        skippedTests?: number;
+    }[];
+}
+export interface RawIssue {
+    issueType?: string;
+    message?: string;
+    targetName?: string;
+    sourceURL?: string;
+}
+export interface BuildResults {
+    actionTitle?: string;
+    status?: string;
+    errorCount?: number;
+    warningCount?: number;
+    analyzerWarningCount?: number;
+    errors?: RawIssue[];
+    warnings?: RawIssue[];
+    analyzerWarnings?: RawIssue[];
+    destination?: TestDevice;
+    startTime?: number;
+    endTime?: number;
+}
+/** A diagnostic, flattened to the shape a TOON row wants. */
+export interface Diagnostic {
+    file: string;
+    line: number | "";
+    col: number | "";
+    type: string;
+    message: string;
+}
+export declare function readTestSummary(path: string): Promise<TestSummary>;
+export declare function readBuildResults(path: string): Promise<BuildResults>;
+/**
+ * Pull `file`, `line` and `col` out of a diagnostic's sourceURL.
+ *
+ * The URL looks like
+ *   file:///path/To.swift#EndingColumnNumber=83&StartingLineNumber=165&...
+ * and the line and column in that fragment are **zero-based** — a diagnostic
+ * reported at `StartingLineNumber=165` is on line 166 as any editor counts it.
+ * Getting this wrong sends the agent to the wrong line, which is worse than
+ * sending it nowhere, so the offset is applied here and nowhere else.
+ */
+export declare function parseSourceURL(sourceURL: string | undefined): {
+    file: string;
+    line: number | "";
+    col: number | "";
+};
+/**
+ * Repo-relative when the file is under cwd, absolute otherwise.
+ *
+ * Both sides need the `/private` prefix stripped, not just the diagnostic's:
+ * on macOS `process.cwd()` in `/tmp` reports `/private/tmp`, so comparing the
+ * two raw would make every path look outside the tree and stay absolute.
+ */
+export declare function relativize(file: string, cwd?: string): string;
+/**
+ * Flatten issues to TOON rows, dropping exact duplicates.
+ *
+ * The same Swift diagnostic is reported once per target that compiles the
+ * file, so a warning in a shared package can appear a dozen times in one
+ * build. Only the first is information; the rest are paid-for repetition.
+ */
+export declare function toDiagnostics(issues: RawIssue[] | undefined): Diagnostic[];
+/** The device a run actually landed on, as one readable line. */
+export declare function describeDevice(device: TestDevice | undefined): string;

package/dist/src/xcresult.js

@@ -0,0 +1,156 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { relative } from "node:path";
+import { AxiError } from "./errors.js";
+/**
+ * Structured reads of an .xcresult bundle.
+ *
+ * This is the whole reason the tool can be small: xcodebuild's transcript is
+ * megabytes of noise, but the bundle it writes alongside carries the same
+ * answers as a few KB of JSON — pass/fail counts, per-device breakdown, and
+ * every diagnostic with a precise source location.
+ */
+const MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+function xcresulttool(args, path) {
+    if (!existsSync(path)) {
+        throw new AxiError(`No result bundle at ${path}`, "RESULT_NOT_FOUND", [
+            "Run `xcodebuild-axi build` or `test` first — each prints the bundle path it wrote",
+        ]);
+    }
+    return new Promise((resolvePromise, rejectPromise) => {
+        execFile("xcrun", ["xcresulttool", ...args, "--path", path, "--compact"], { maxBuffer: MAX_BUFFER_BYTES, encoding: "utf-8" }, (error, stdout) => {
+            if (error && stdout.trim().length === 0) {
+                rejectPromise(new AxiError(`Could not read result bundle at ${path}`, "RESULT_NOT_FOUND", [
+                    "The bundle may be from an incompatible Xcode version, or still being written",
+                ]));
+                return;
+            }
+            try {
+                resolvePromise(JSON.parse(stdout));
+            }
+            catch {
+                rejectPromise(new AxiError(`Result bundle at ${path} produced unreadable output`, "RESULT_NOT_FOUND"));
+            }
+        });
+    });
+}
+export function readTestSummary(path) {
+    return xcresulttool(["get", "test-results", "summary"], path);
+}
+export function readBuildResults(path) {
+    return xcresulttool(["get", "build-results"], path);
+}
+/**
+ * Pull `file`, `line` and `col` out of a diagnostic's sourceURL.
+ *
+ * The URL looks like
+ *   file:///path/To.swift#EndingColumnNumber=83&StartingLineNumber=165&...
+ * and the line and column in that fragment are **zero-based** — a diagnostic
+ * reported at `StartingLineNumber=165` is on line 166 as any editor counts it.
+ * Getting this wrong sends the agent to the wrong line, which is worse than
+ * sending it nowhere, so the offset is applied here and nowhere else.
+ */
+export function parseSourceURL(sourceURL) {
+    if (!sourceURL)
+        return { file: "", line: "", col: "" };
+    const hashIndex = sourceURL.indexOf("#");
+    const rawPath = hashIndex === -1 ? sourceURL : sourceURL.slice(0, hashIndex);
+    const fragment = hashIndex === -1 ? "" : sourceURL.slice(hashIndex + 1);
+    let file = rawPath.startsWith("file://")
+        ? rawPath.slice("file://".length)
+        : rawPath;
+    try {
+        file = decodeURIComponent(file);
+    }
+    catch {
+        // A malformed escape is not worth failing a whole build report over.
+    }
+    const params = new URLSearchParams(fragment);
+    const line = toZeroBasedNumber(params.get("StartingLineNumber"));
+    const col = toZeroBasedNumber(params.get("StartingColumnNumber"));
+    return { file: relativize(file), line, col };
+}
+function toZeroBasedNumber(raw) {
+    if (raw === null)
+        return "";
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed + 1 : "";
+}
+/**
+ * Repo-relative when the file is under cwd, absolute otherwise.
+ *
+ * Both sides need the `/private` prefix stripped, not just the diagnostic's:
+ * on macOS `process.cwd()` in `/tmp` reports `/private/tmp`, so comparing the
+ * two raw would make every path look outside the tree and stay absolute.
+ */
+export function relativize(file, cwd = process.cwd()) {
+    if (!file.startsWith("/"))
+        return file;
+    const normalized = stripPrivate(file);
+    const rel = relative(stripPrivate(cwd), normalized);
+    return rel.startsWith("..") ? normalized : rel;
+}
+function stripPrivate(path) {
+    return path.startsWith("/private/") ? path.slice("/private".length) : path;
+}
+/**
+ * Flatten issues to TOON rows, dropping exact duplicates.
+ *
+ * The same Swift diagnostic is reported once per target that compiles the
+ * file, so a warning in a shared package can appear a dozen times in one
+ * build. Only the first is information; the rest are paid-for repetition.
+ */
+export function toDiagnostics(issues) {
+    const seen = new Set();
+    const out = [];
+    for (const issue of issues ?? []) {
+        const { file, line, col } = parseSourceURL(issue.sourceURL);
+        const message = (issue.message ?? "").replace(/\s+/g, " ").trim();
+        const key = `${file}:${line}:${col}:${message}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({
+            file,
+            line,
+            col,
+            type: shortIssueType(issue.issueType),
+            message,
+        });
+    }
+    return out;
+}
+/** "Swift Compiler Error" is four tokens to say "swift". */
+function shortIssueType(issueType) {
+    if (!issueType)
+        return "error";
+    const lower = issueType.toLowerCase();
+    if (lower.includes("swift"))
+        return "swift";
+    if (lower.includes("clang") || lower.includes("c compiler"))
+        return "clang";
+    if (lower.includes("linker"))
+        return "linker";
+    if (lower.includes("script"))
+        return "script";
+    if (lower.includes("package"))
+        return "package";
+    if (lower.includes("uncategorized"))
+        return "xcodebuild";
+    return lower.replace(/ (error|warning)$/, "").replace(/\s+/g, "-");
+}
+/** The device a run actually landed on, as one readable line. */
+export function describeDevice(device) {
+    if (!device)
+        return "unknown";
+    const name = device.deviceName || device.modelName;
+    const parts = [
+        name,
+        device.osVersion
+            ? `${device.platform ?? "iOS"} ${device.osVersion}`
+            : device.platform,
+    ];
+    const described = parts.filter((part) => part && part.length > 0).join(" · ");
+    return described.length > 0 ? described : "unknown";
+}
+//# sourceMappingURL=xcresult.js.map

package/dist/src/xcresult.js.map

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

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "xcodebuild-axi",
+  "version": "0.1.0",
+  "description": "AXI-compliant xcodebuild wrapper — turns multi-megabyte Xcode build and test transcripts into a few lines of TOON",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexrrouse/xcodebuild-axi.git"
+  },
+  "homepage": "https://github.com/alexrrouse/xcodebuild-axi#readme",
+  "bugs": {
+    "url": "https://github.com/alexrrouse/xcodebuild-axi/issues"
+  },
+  "keywords": [
+    "xcodebuild",
+    "xcode",
+    "ios",
+    "swift",
+    "cli",
+    "agent",
+    "axi",
+    "toon"
+  ],
+  "bin": {
+    "xcodebuild-axi": "dist/bin/xcodebuild-axi.js"
+  },
+  "files": [
+    "dist",
+    "skills/xcodebuild-axi",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx bin/xcodebuild-axi.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "build:skill": "tsx scripts/build-skill.ts",
+    "prepublishOnly": "npm run build",
+    "coverage": "tsx scripts/coverage.ts",
+    "coverage:check": "tsx scripts/coverage.ts --check",
+    "benchmark": "tsx scripts/benchmark.ts"
+  },
+  "author": "Alex Rouse",
+  "license": "MIT",
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@toon-format/toon": "^4.1.1",
+    "axi-sdk-js": "^0.1.10"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.0.0",
+    "eslint": "^10.1.0",
+    "globals": "^17.4.0",
+    "gpt-tokenizer": "^4.0.0",
+    "prettier": "^3.8.1",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^5.0.1"
+  }
+}

package/skills/xcodebuild-axi/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: xcodebuild-axi
+description: >
+  Build, test, and inspect Xcode projects without reading xcodebuild's output.
+  Use for any iOS/macOS build, test run, scheme or destination lookup, build
+  setting read, or .xcresult inspection — raw xcodebuild prints hundreds of
+  kilobytes to say what this prints in a few lines.
+---
+
+# xcodebuild-axi
+
+Agent-ergonomic wrapper around xcodebuild. Prefer it over raw `xcodebuild` for any build / test / inspect of an Xcode project.
+
+Run it with no arguments first — it reports the project in front of you, its
+schemes, and how the last run went.
+
+```sh
+npx -y xcodebuild-axi
+```
+
+## Commands
+
+```
+usage: xcodebuild-axi [command] [flags]
+commands[23]:
+  (none)=dashboard
+  build, test, tests, clean, analyze, archive, export
+  schemes, destinations, testplans, settings, packages, info
+  result, coverage, sim, platforms, setup
+  localize, xcframework, find, migrate
+flags[2]:
+  --help, -v/-V/--version
+env[2]:
+  XCODEBUILD_BIN  override the wrapped xcodebuild binary
+  DEVELOPER_DIR   select an Xcode, as xcodebuild itself reads it
+exit:
+  0 success, 1 the build or tests failed, 2 usage error
+examples:
+  xcodebuild-axi
+  xcodebuild-axi build --scheme MyApp
+  xcodebuild-axi test --scheme MyApp --device "iPhone 17 Pro" --coverage
+  xcodebuild-axi settings --key PRODUCT_BUNDLE_IDENTIFIER
+  xcodebuild-axi setup hooks
+```
+
+Every command takes `--help` with its own flags and examples. The CLI's own
+output is the authority on everything below the top level; prefer asking it
+over guessing.
+
+## What to reach for
+
+- Building or testing: `build` and `test` report only what failed, with
+  `file,line,col`. The full transcript is written to a log whose path they
+  print, so detail is one read away and never the default.
+- Picking a device: pass `--device "iPhone 17 Pro"`, or nothing at all to get
+  the newest simulator. Do not hand-write a `-destination` specifier.
+- Reading a previous run: `result <path.xcresult>`, which re-reads without
+  rebuilding.
+- Build settings: `settings --key NAME`, not a full dump.
+
+## Exit codes
+
+`0` success, `1` the build or tests failed, `2` usage error. A failed build
+still prints its full report to stdout.