xcodebuild-axi 0.1.0

package/dist/src/action.js

@@ -0,0 +1,373 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { AxiError, mapXcodebuildError } from "./errors.js";
+import { requireProject } from "./context.js";
+import { requireScheme } from "./scheme.js";
+import { destinationSlug, resolveDestination } from "./destination.js";
+import { runBuild } from "./xcodebuild.js";
+import { readBuildResults, toDiagnostics } from "./xcresult.js";
+import { diagnosticsBlock, transcriptTail } from "./report.js";
+import { duration, renderFields, renderHelp, renderOutput, tildePath, } from "./toon.js";
+import { getFlag, getIntFlag, getListFlag, hasFlag } from "./args.js";
+import { packageArgs, PACKAGE_FLAG_HELP, PACKAGE_FLAGS, PACKAGE_VALUE_FLAGS, } from "./packages.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 const SHARED_BUILD_FLAGS = [
+    "--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",
+    ...PACKAGE_FLAGS,
+];
+export const SHARED_BUILD_VALUE_FLAGS = [
+    "--scheme",
+    "--target",
+    "--device",
+    "--destination",
+    "--configuration",
+    "--sdk",
+    "--arch",
+    "--toolchain",
+    "--xcconfig",
+    "--derived-data",
+    "--jobs",
+    "--setting",
+    "--sanitizer",
+    "--destination-timeout",
+    "--max-errors",
+    "--codesize",
+    "--log-level",
+    "--bundle-version",
+    "--stream",
+    ...PACKAGE_VALUE_FLAGS,
+];
+/** The shared flag block, so each command's `--help` stays consistent. */
+export const BUILD_FLAG_HELP = `  --scheme <name>         scheme to act on (required only when the project has more than one)
+  --target <name>         build a target instead of a scheme; repeatable (project only)
+  --all-targets           build every target in the project (project only)
+  --device <name>         simulator or device name, e.g. "iPhone 17 Pro" (default: newest simulator)
+  --destination <spec>    raw xcodebuild destination specifier, passed through untouched
+  --configuration <name>  build configuration (default: the scheme's own)
+  --sdk <name>            base SDK, e.g. iphonesimulator
+  --arch <arch>           architecture to build; repeatable or comma-separated
+  --toolchain <name>      toolchain identifier or name
+  --xcconfig <path>       apply build settings from this file as overrides
+  --derived-data <path>   derived data directory
+  --jobs <n>              maximum concurrent build operations
+  --setting KEY=VALUE     build setting override; repeatable or comma-separated
+  --sign                  allow code signing (off by default, so simulator builds need no team)
+  --allow-provisioning    let xcodebuild talk to the developer portal for profiles
+  --sanitizer <name>      address, thread, or undefined; repeatable or comma-separated
+  --timing                report per-command build timings
+  --destination-timeout <secs>  how long to wait for the destination device
+  --parallelize-targets   build independent targets in parallel
+  --hide-script-env       omit shell script environment variables from the log
+  --skip-unavailable-actions  skip scheme actions that cannot run instead of failing
+  --max-errors <n>        errors to list before summarizing the rest (default: 20)
+  --full                  list every warning instead of the first 10
+  --codesize <dir>        write a code size profile to this directory
+  --log-level <level>     quiet, normal, or verbose — how much lands in the log file
+  --bundle-version <n>    result bundle format version (default: xcodebuild's own)
+  --stream <path>         also write xcodebuild's live result stream here
+${PACKAGE_FLAG_HELP}`;
+/**
+ * The flags that map straight onto an xcodebuild switch with no interpretation
+ * beyond validation. Grouped so they can be tested without a project.
+ */
+export function buildPassthroughArgs(args, command) {
+    return [
+        ...codesizeArgs(args),
+        ...logLevelArgs(args, command),
+        ...streamArgs(args),
+        ...bundleVersionArgs(args),
+    ];
+}
+function bundleVersionArgs(args) {
+    const version = getIntFlag(args, "--bundle-version");
+    return version === undefined ? [] : ["-resultBundleVersion", String(version)];
+}
+const LOG_LEVELS = {
+    quiet: ["-quiet"],
+    normal: [],
+    verbose: ["-verbose"],
+};
+/**
+ * The log file is a real artifact with a real size, even though the report
+ * never comes from it. `--log-level quiet` shrinks it; `verbose` is for the
+ * failures the result bundle cannot explain on its own.
+ */
+function logLevelArgs(args, command) {
+    const level = getFlag(args, "--log-level");
+    if (level === undefined)
+        return [];
+    const mapped = LOG_LEVELS[level];
+    if (mapped === undefined) {
+        throw new AxiError(`Unknown log level '${level}'`, "VALIDATION_ERROR", [
+            "valid levels are quiet, normal, verbose",
+            `xcodebuild-axi ${command} --log-level verbose`,
+        ]);
+    }
+    return mapped;
+}
+/**
+ * `-resultStreamPath` refuses a path that does not already exist, which is an
+ * odd contract to pass on to a caller — so create the file first.
+ */
+function streamArgs(args) {
+    const path = getFlag(args, "--stream");
+    if (path === undefined)
+        return [];
+    const full = resolve(path);
+    mkdirSync(dirname(full), { recursive: true });
+    if (!existsSync(full))
+        writeFileSync(full, "");
+    return ["-resultStreamPath", full];
+}
+/** `-enableCodesizeProfile` is inert without an output directory, so one flag
+ * sets both rather than letting a build run and produce nothing. */
+function codesizeArgs(args) {
+    const dir = getFlag(args, "--codesize");
+    return dir
+        ? ["-enableCodesizeProfile", "YES", "-codesizeProfileOutputDir", dir]
+        : [];
+}
+const SANITIZER_FLAGS = {
+    address: "-enableAddressSanitizer",
+    thread: "-enableThreadSanitizer",
+    undefined: "-enableUndefinedBehaviorSanitizer",
+};
+export async function resolveBuildContext(options) {
+    const { args, command } = options;
+    const project = requireProject();
+    const targets = getListFlag(args, "--target");
+    const allTargets = hasFlag(args, "--all-targets");
+    const targetMode = targets.length > 0 || allTargets;
+    if (targetMode && project.kind === "workspace") {
+        // xcodebuild's own refusal here is "-target is not supported with
+        // -workspace", issued only after it has resolved the package graph.
+        throw new AxiError("--target and --all-targets work against a project, not a workspace", "VALIDATION_ERROR", [
+            "Pass `--scheme <name>` instead, or cd to the directory holding the .xcodeproj",
+        ]);
+    }
+    if (targetMode && getFlag(args, "--scheme") !== undefined) {
+        throw new AxiError("--scheme and --target select different things to build, so only one can be used", "VALIDATION_ERROR", ["Drop one — a scheme already names the targets it builds"]);
+    }
+    const scheme = targetMode
+        ? allTargets
+            ? "all targets"
+            : targets.join(",")
+        : await requireScheme(project, getFlag(args, "--scheme"), command);
+    const rawDestination = getFlag(args, "--destination");
+    const device = getFlag(args, "--device");
+    const needsDestination = options.needsDestination !== false;
+    const destination = !targetMode &&
+        (needsDestination || rawDestination !== undefined || device !== undefined)
+        ? await resolveDestination({
+            project,
+            scheme,
+            ...(device !== undefined ? { device } : {}),
+            ...(rawDestination !== undefined ? { raw: rawDestination } : {}),
+        })
+        : undefined;
+    const sanitizers = getListFlag(args, "--sanitizer");
+    for (const sanitizer of sanitizers) {
+        if (!(sanitizer in SANITIZER_FLAGS)) {
+            throw new AxiError(`Unknown sanitizer '${sanitizer}'`, "VALIDATION_ERROR", ["valid sanitizers are address, thread, undefined"]);
+        }
+    }
+    const settings = getListFlag(args, "--setting");
+    for (const setting of settings) {
+        if (!setting.includes("=")) {
+            throw new AxiError(`--setting expects KEY=VALUE, got '${setting}'`, "VALIDATION_ERROR", [
+                "xcodebuild-axi " +
+                    command +
+                    " --setting SWIFT_STRICT_CONCURRENCY=complete",
+            ]);
+        }
+    }
+    const configuration = getFlag(args, "--configuration");
+    const sdk = getFlag(args, "--sdk");
+    const toolchain = getFlag(args, "--toolchain");
+    const xcconfig = getFlag(args, "--xcconfig");
+    const derivedData = getFlag(args, "--derived-data");
+    const jobs = getIntFlag(args, "--jobs");
+    const destinationTimeout = getIntFlag(args, "--destination-timeout");
+    const xcodebuildArgs = [
+        ...project.flags,
+        ...(targetMode
+            ? allTargets
+                ? ["-alltargets"]
+                : targets.flatMap((target) => ["-target", target])
+            : ["-scheme", scheme]),
+        ...(destination ? ["-destination", destination.specifier] : []),
+        ...(destinationTimeout !== undefined
+            ? ["-destination-timeout", String(destinationTimeout)]
+            : []),
+        ...(configuration ? ["-configuration", configuration] : []),
+        ...(sdk ? ["-sdk", sdk] : []),
+        ...getListFlag(args, "--arch").flatMap((arch) => ["-arch", arch]),
+        ...(toolchain ? ["-toolchain", toolchain] : []),
+        ...(xcconfig ? ["-xcconfig", xcconfig] : []),
+        ...(derivedData ? ["-derivedDataPath", derivedData] : []),
+        ...(jobs !== undefined ? ["-jobs", String(jobs)] : []),
+        ...sanitizers.flatMap((sanitizer) => [
+            SANITIZER_FLAGS[sanitizer],
+            "YES",
+        ]),
+        ...(hasFlag(args, "--timing") ? ["-showBuildTimingSummary"] : []),
+        ...(hasFlag(args, "--parallelize-targets") ? ["-parallelizeTargets"] : []),
+        ...(hasFlag(args, "--hide-script-env")
+            ? ["-hideShellScriptEnvironment"]
+            : []),
+        ...(hasFlag(args, "--skip-unavailable-actions")
+            ? ["-skipUnavailableActions"]
+            : []),
+        // Macro validation is an interactive trust prompt in disguise: unattended
+        // it fails the build outright on any package using macros.
+        "-skipMacroValidation",
+        ...(hasFlag(args, "--allow-provisioning")
+            ? ["-allowProvisioningUpdates"]
+            : []),
+        ...buildPassthroughArgs(args, command),
+        ...packageArgs(args),
+        ...(hasFlag(args, "--sign") ? [] : ["CODE_SIGNING_ALLOWED=NO"]),
+        ...settings,
+    ];
+    return {
+        project,
+        scheme,
+        destination: destination?.described,
+        xcodebuildArgs,
+        maxErrors: getIntFlag(args, "--max-errors") ?? 20,
+        full: hasFlag(args, "--full"),
+    };
+}
+/** A filesystem stem that distinguishes runs of different commands and devices. */
+export function runLabel(context, command) {
+    const device = context.destination
+        ? `-${destinationSlug(context.destination)}`
+        : "";
+    return `${context.scheme}${device}-${command}`;
+}
+export function runAction(options) {
+    return runBuild({
+        args: [
+            ...options.context.xcodebuildArgs,
+            ...(options.extraArgs ?? []),
+            ...options.actions,
+        ],
+        label: runLabel(options.context, options.command),
+        project: options.context.project,
+    });
+}
+/**
+ * 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 async function reportAction(options) {
+    const { run, context } = options;
+    const results = await readBuildResults(run.resultPath).catch(() => undefined);
+    const errors = toDiagnostics(results?.errors);
+    const analyzerWarnings = toDiagnostics(results?.analyzerWarnings);
+    const warnings = toDiagnostics([
+        ...(results?.warnings ?? []),
+        ...(options.analyzer ? [] : (results?.analyzerWarnings ?? [])),
+    ]);
+    const succeeded = run.exitCode === 0;
+    // A bundle that records no error for a nonzero exit means xcodebuild died
+    // before it built anything — a bad scheme, an unmatched destination, a
+    // missing signing team. The transcript is the only witness.
+    if (!succeeded && errors.length === 0) {
+        const mapped = mapXcodebuildError(run.tail);
+        if (mapped) {
+            throw new AxiError(mapped.message, mapped.code, [
+                ...mapped.suggestions,
+                `full transcript: ${tildePath(run.logPath)}`,
+            ]);
+        }
+    }
+    const blocks = [
+        renderFields({
+            [options.key]: succeeded ? options.ok : "failed",
+            scheme: context.scheme,
+            ...(context.destination ? { destination: context.destination } : {}),
+            duration: duration(run.seconds),
+            ...(options.extra ?? {}),
+        }),
+    ];
+    const errorBlock = diagnosticsBlock("errors", errors, context.maxErrors);
+    if (errorBlock.block)
+        blocks.push(errorBlock.block);
+    if (options.analyzer) {
+        if (analyzerWarnings.length > 0) {
+            blocks.push(diagnosticsBlock("issues", analyzerWarnings, context.full ? analyzerWarnings.length : 20).block);
+        }
+        else if (succeeded) {
+            blocks.push(renderFields({ issues: "0 analyzer issues found" }));
+        }
+    }
+    if (warnings.length > 0) {
+        blocks.push(diagnosticsBlock("warnings", warnings, context.full ? warnings.length : 10).block);
+    }
+    else if (succeeded && !options.analyzer) {
+        blocks.push(renderFields({ warnings: 0 }));
+    }
+    if (!succeeded && errors.length === 0) {
+        const tail = transcriptTail(run.tail);
+        if (tail)
+            blocks.push(tail);
+    }
+    blocks.push(renderFields({
+        log: tildePath(run.logPath),
+        result: tildePath(run.resultPath),
+    }));
+    const hints = [];
+    if (errorBlock.hidden > 0) {
+        hints.push(`Run \`xcodebuild-axi ${options.command} --max-errors ${errors.length}\` to list all ${errors.length} errors`);
+    }
+    if (!context.full && warnings.length > 10) {
+        hints.push(`Run \`xcodebuild-axi ${options.command} --full\` to list all ${warnings.length} warnings`);
+    }
+    if (!succeeded) {
+        hints.push(`Run \`xcodebuild-axi result ${tildePath(run.resultPath)}\` to re-read this run without rebuilding`);
+    }
+    blocks.push(renderHelp(hints));
+    // The agent asked for a build and did not get one. Exit non-zero so `&&`
+    // chains and CI stop, while the report itself still reaches stdout.
+    if (!succeeded)
+        process.exitCode = 1;
+    return renderOutput(blocks);
+}
+//# sourceMappingURL=action.js.map

package/dist/src/action.js.map

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

package/dist/src/archive.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Read the summary Xcode writes into an .xcarchive's Info.plist.
+ *
+ * The interesting part is `ApplicationProperties` — the bundle identifier,
+ * marketing version, and build number of the thing that was archived. An
+ * agent that just produced an archive almost always wants those next, and
+ * getting them otherwise means a second command against a plist inside a
+ * bundle (AXI principle 4).
+ */
+export interface ArchiveInfo {
+    bundleIdentifier?: string;
+    marketingVersion?: string;
+    buildNumber?: string;
+    applicationPath?: string;
+    name?: string;
+    createdAt?: string;
+}
+export declare function readArchiveInfo(archivePath: string): Promise<ArchiveInfo | undefined>;
+/** The `method` values Xcode 27 accepts in an export options plist. */
+export declare const EXPORT_METHODS: readonly ["app-store-connect", "release-testing", "enterprise", "debugging", "developer-id", "mac-application", "validation"];
+/**
+ * Build a minimal export options plist.
+ *
+ * `-exportArchive` requires one, and authoring XML by hand is exactly the kind
+ * of unguessable side quest an agent fails at. Given a method (and optionally
+ * a team), the plist is derivable, so derive it.
+ */
+export declare function exportOptionsPlist(options: {
+    method: string;
+    teamID?: string;
+    signingStyle?: string;
+    uploadSymbols?: boolean;
+}): string;

package/dist/src/archive.js

@@ -0,0 +1,77 @@
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+export function readArchiveInfo(archivePath) {
+    return new Promise((resolvePromise) => {
+        execFile("plutil", ["-convert", "json", "-o", "-", join(archivePath, "Info.plist")], { encoding: "utf-8" }, (error, stdout) => {
+            if (error) {
+                resolvePromise(undefined);
+                return;
+            }
+            try {
+                const parsed = JSON.parse(stdout);
+                const app = parsed.ApplicationProperties ?? {};
+                resolvePromise({
+                    ...(parsed.Name !== undefined ? { name: parsed.Name } : {}),
+                    ...(parsed.CreationDate !== undefined
+                        ? { createdAt: parsed.CreationDate }
+                        : {}),
+                    ...(app.CFBundleIdentifier !== undefined
+                        ? { bundleIdentifier: app.CFBundleIdentifier }
+                        : {}),
+                    ...(app.CFBundleShortVersionString !== undefined
+                        ? { marketingVersion: app.CFBundleShortVersionString }
+                        : {}),
+                    ...(app.CFBundleVersion !== undefined
+                        ? { buildNumber: app.CFBundleVersion }
+                        : {}),
+                    ...(app.ApplicationPath !== undefined
+                        ? { applicationPath: app.ApplicationPath }
+                        : {}),
+                });
+            }
+            catch {
+                resolvePromise(undefined);
+            }
+        });
+    });
+}
+/** The `method` values Xcode 27 accepts in an export options plist. */
+export const EXPORT_METHODS = [
+    "app-store-connect",
+    "release-testing",
+    "enterprise",
+    "debugging",
+    "developer-id",
+    "mac-application",
+    "validation",
+];
+/**
+ * Build a minimal export options plist.
+ *
+ * `-exportArchive` requires one, and authoring XML by hand is exactly the kind
+ * of unguessable side quest an agent fails at. Given a method (and optionally
+ * a team), the plist is derivable, so derive it.
+ */
+export function exportOptionsPlist(options) {
+    const entries = [
+        `  <key>method</key>\n  <string>${options.method}</string>`,
+    ];
+    if (options.teamID) {
+        entries.push(`  <key>teamID</key>\n  <string>${options.teamID}</string>`);
+    }
+    if (options.signingStyle) {
+        entries.push(`  <key>signingStyle</key>\n  <string>${options.signingStyle}</string>`);
+    }
+    if (options.uploadSymbols !== undefined) {
+        entries.push(`  <key>uploadSymbols</key>\n  <${options.uploadSymbols}/>`);
+    }
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+${entries.join("\n")}
+</dict>
+</plist>
+`;
+}
+//# sourceMappingURL=archive.js.map

package/dist/src/archive.js.map

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

package/dist/src/args.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Flag parsing with AXI principle 6's "fail loud on unrecognized input".
+ *
+ * Every command declares the flags it knows; anything else is rejected by name
+ * with the valid set listed inline, so the agent self-corrects in one turn
+ * rather than spending a round trip on `--help`.
+ */
+/** Read `--flag value` or `--flag=value` without consuming it. */
+export declare function getFlag(args: string[], name: string): string | undefined;
+export declare function hasFlag(args: string[], name: string): boolean;
+/** Read a `--flag a,b,c` list, also accepting the flag repeated. */
+export declare function getListFlag(args: string[], name: string): string[];
+/** Read an integer flag, rejecting values that are not numbers. */
+export declare function getIntFlag(args: string[], name: string): number | undefined;
+/** Positional arguments — everything that is not a flag or a flag's value. */
+export declare function positionals(args: string[], valueFlags: readonly string[]): string[];
+/**
+ * Reject unknown flags by name and list the valid ones inline.
+ *
+ * `--help` always passes (AXI principle 6). `valueFlags` are the flags that
+ * take a value, so their values are not mistaken for flags themselves.
+ */
+export declare function rejectUnknownFlags(args: string[], command: string, known: readonly string[], valueFlags?: readonly string[]): void;

package/dist/src/args.js

@@ -0,0 +1,123 @@
+import { AxiError } from "./errors.js";
+/**
+ * Flag parsing with AXI principle 6's "fail loud on unrecognized input".
+ *
+ * Every command declares the flags it knows; anything else is rejected by name
+ * with the valid set listed inline, so the agent self-corrects in one turn
+ * rather than spending a round trip on `--help`.
+ */
+/** Read `--flag value` or `--flag=value` without consuming it. */
+export function getFlag(args, name) {
+    const prefix = `${name}=`;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === name)
+            return args[i + 1];
+        if (arg.startsWith(prefix))
+            return arg.slice(prefix.length);
+    }
+    return undefined;
+}
+export function hasFlag(args, name) {
+    return args.includes(name);
+}
+/** Read a `--flag a,b,c` list, also accepting the flag repeated. */
+export function getListFlag(args, name) {
+    const prefix = `${name}=`;
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === name) {
+            const value = args[i + 1];
+            if (value !== undefined)
+                out.push(value);
+            i++;
+        }
+        else if (arg.startsWith(prefix)) {
+            out.push(arg.slice(prefix.length));
+        }
+    }
+    return out.flatMap((v) => v.split(",")).filter((v) => v.length > 0);
+}
+/** Read an integer flag, rejecting values that are not numbers. */
+export function getIntFlag(args, name) {
+    const raw = getFlag(args, name);
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new AxiError(`${name} expects a non-negative integer, got "${raw}"`, "VALIDATION_ERROR");
+    }
+    return parsed;
+}
+/** Positional arguments — everything that is not a flag or a flag's value. */
+export function positionals(args, valueFlags) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === "--") {
+            out.push(...args.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith("-")) {
+            const bare = arg.split("=")[0] ?? arg;
+            if (valueFlags.includes(bare) && !arg.includes("="))
+                i++;
+            continue;
+        }
+        out.push(arg);
+    }
+    return out;
+}
+/**
+ * Reject unknown flags by name and list the valid ones inline.
+ *
+ * `--help` always passes (AXI principle 6). `valueFlags` are the flags that
+ * take a value, so their values are not mistaken for flags themselves.
+ */
+export function rejectUnknownFlags(args, command, known, valueFlags = []) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === "--")
+            break;
+        if (!arg.startsWith("-") || arg === "-")
+            continue;
+        const bare = arg.split("=")[0] ?? arg;
+        if (bare === "--help")
+            continue;
+        if (!known.includes(bare)) {
+            const renamed = RENAMED_FLAGS[bare];
+            throw new AxiError(`unknown flag ${bare} for \`${command}\``, "VALIDATION_ERROR", renamed
+                ? [renamed]
+                : [
+                    `valid flags for \`${command}\`: ${known.join(", ")} (--help always allowed)`,
+                ]);
+        }
+        if (valueFlags.includes(bare) && !arg.includes("=")) {
+            const value = args[i + 1];
+            if (value === undefined) {
+                throw new AxiError(`${bare} requires a value`, "VALIDATION_ERROR", [
+                    `valid flags for \`${command}\`: ${known.join(", ")}`,
+                ]);
+            }
+            i++;
+        }
+    }
+}
+/**
+ * Flags this CLI used to accept, pointed at their replacement so a stale call
+ * site self-corrects in one step instead of reading the whole valid-flag list.
+ */
+const RENAMED_FLAGS = {
+    "--simulator": "--simulator was renamed; use --device instead",
+    "--verbose": "--verbose was removed; the full transcript is always written to the log path in the output",
+};
+//# sourceMappingURL=args.js.map

package/dist/src/args.js.map

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