xcodebuild-axi 0.1.0

package/dist/src/commands/xcframework.js

@@ -0,0 +1,77 @@
+import { existsSync } from "node:fs";
+import { AxiError } from "../errors.js";
+import { runMetadata, stripPreamble } from "../xcodebuild.js";
+import { renderFields, renderHelp, renderOutput, tildePath } from "../toon.js";
+import { getListFlag, getFlag, rejectUnknownFlags } from "../args.js";
+export const XCFRAMEWORK_HELP = `usage: xcodebuild-axi xcframework --output <path.xcframework> [flags]
+Bundles prebuilt frameworks or libraries into one .xcframework.
+flags[4]:
+  --output <path>     the .xcframework to write (required)
+  --framework <path>  a built .framework to include; repeatable
+  --library <path>    a built static or dynamic library to include; repeatable
+  --headers <path>    headers for the library that precedes it; repeatable
+note:
+  --headers applies to the --library it follows, which is how xcodebuild pairs
+  them. Give them in matching order.
+examples:
+  xcodebuild-axi xcframework --output Out.xcframework --framework A.framework --framework B.framework
+  xcodebuild-axi xcframework --output Out.xcframework --library libA.a --headers include
+`;
+const FLAGS = ["--output", "--framework", "--library", "--headers"];
+export async function xcframeworkCommand(args) {
+    rejectUnknownFlags(args, "xcframework", FLAGS, FLAGS);
+    const output = getFlag(args, "--output");
+    if (output === undefined) {
+        throw new AxiError("xcframework needs --output", "VALIDATION_ERROR", [
+            "xcodebuild-axi xcframework --output Out.xcframework --framework A.framework",
+        ]);
+    }
+    const frameworks = getListFlag(args, "--framework");
+    const libraries = getListFlag(args, "--library");
+    const headers = getListFlag(args, "--headers");
+    if (frameworks.length === 0 && libraries.length === 0) {
+        throw new AxiError("xcframework needs at least one --framework or --library", "VALIDATION_ERROR", [
+            "xcodebuild-axi xcframework --output Out.xcframework --framework A.framework",
+        ]);
+    }
+    const missing = [...frameworks, ...libraries].filter((path) => !existsSync(path));
+    if (missing.length > 0) {
+        // xcodebuild reports this one input at a time; naming them all at once
+        // saves a round trip per missing path.
+        throw new AxiError(`Missing input: ${missing.join(", ")}`, "VALIDATION_ERROR", ["Build each slice first, then pass the built products here"]);
+    }
+    const { stdout, stderr, exitCode } = await runMetadata([
+        "-create-xcframework",
+        ...frameworks.flatMap((path) => ["-framework", path]),
+        ...libraries.flatMap((path, index) => [
+            "-library",
+            path,
+            ...(headers[index] !== undefined
+                ? ["-headers", headers[index]]
+                : []),
+        ]),
+        "-output",
+        output,
+    ]);
+    if (exitCode !== 0) {
+        throw new AxiError(firstMeaningfulLine(`${stderr}\n${stdout}`) ||
+            "Could not create the xcframework", "UNKNOWN");
+    }
+    return renderOutput([
+        renderFields({
+            xcframework: tildePath(output),
+            frameworks: frameworks.length,
+            libraries: libraries.length,
+        }),
+        renderHelp([
+            "Add the .xcframework to a target's Frameworks build phase to use it",
+        ]),
+    ]);
+}
+function firstMeaningfulLine(output) {
+    return (stripPreamble(output)
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line.length > 0) ?? "");
+}
+//# sourceMappingURL=xcframework.js.map

package/dist/src/commands/xcframework.js.map

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

package/dist/src/context.d.ts

@@ -0,0 +1,23 @@
+export type ProjectKind = "workspace" | "project" | "package";
+export interface ProjectContext {
+    kind: ProjectKind;
+    /** Absolute path to the container (or the directory, for a package). */
+    path: string;
+    /** Display name: "MyApps" for MyApps.xcworkspace. */
+    name: string;
+    /** The `-workspace X` / `-project X` pair to pass xcodebuild, if any. */
+    flags: string[];
+}
+/**
+ * Find the thing xcodebuild should be pointed at, in the directory the agent
+ * is standing in.
+ *
+ * A workspace wins over a bare project because that is the container Xcode
+ * itself opens when both are present, and because a project inside a workspace
+ * usually cannot resolve the workspace's package graph on its own.
+ *
+ * `project.xcworkspace` is skipped: every `.xcodeproj` contains one, and it is
+ * an implementation detail rather than something a user ever builds.
+ */
+export declare function resolveProject(dir?: string): ProjectContext | undefined;
+export declare function requireProject(dir?: string): ProjectContext;

package/dist/src/context.js

@@ -0,0 +1,72 @@
+import { existsSync, readdirSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { AxiError } from "./errors.js";
+/**
+ * Find the thing xcodebuild should be pointed at, in the directory the agent
+ * is standing in.
+ *
+ * A workspace wins over a bare project because that is the container Xcode
+ * itself opens when both are present, and because a project inside a workspace
+ * usually cannot resolve the workspace's package graph on its own.
+ *
+ * `project.xcworkspace` is skipped: every `.xcodeproj` contains one, and it is
+ * an implementation detail rather than something a user ever builds.
+ */
+export function resolveProject(dir = process.cwd()) {
+    const root = resolve(dir);
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return undefined;
+    }
+    const workspaces = entries.filter((entry) => entry.endsWith(".xcworkspace") && entry !== "project.xcworkspace");
+    if (workspaces.length > 0) {
+        const chosen = pickOne(workspaces, "workspace", root);
+        return {
+            kind: "workspace",
+            path: join(root, chosen),
+            name: basename(chosen, ".xcworkspace"),
+            flags: ["-workspace", join(root, chosen)],
+        };
+    }
+    const projects = entries.filter((entry) => entry.endsWith(".xcodeproj"));
+    if (projects.length > 0) {
+        const chosen = pickOne(projects, "project", root);
+        return {
+            kind: "project",
+            path: join(root, chosen),
+            name: basename(chosen, ".xcodeproj"),
+            flags: ["-project", join(root, chosen)],
+        };
+    }
+    // A Swift package has no container to pass: xcodebuild synthesizes an
+    // implicit workspace from Package.swift in the working directory, which is
+    // why the runner must never cd away from it.
+    if (existsSync(join(root, "Package.swift"))) {
+        return { kind: "package", path: root, name: basename(root), flags: [] };
+    }
+    return undefined;
+}
+export function requireProject(dir = process.cwd()) {
+    const project = resolveProject(dir);
+    if (!project) {
+        throw new AxiError(`No .xcworkspace, .xcodeproj, or Package.swift in ${dir}`, "NO_PROJECT", ["cd to the directory holding the workspace or project, then re-run"]);
+    }
+    return project;
+}
+function pickOne(candidates, label, root) {
+    const sorted = [...candidates].sort();
+    const first = sorted[0];
+    if (first === undefined) {
+        throw new AxiError(`No ${label} found in ${root}`, "NO_PROJECT");
+    }
+    if (sorted.length > 1) {
+        // Ambiguity an agent cannot resolve by guessing: say which ones, so the
+        // next call can cd into the right place rather than re-run blind.
+        throw new AxiError(`${sorted.length} ${label}s in ${root}: ${sorted.join(", ")}`, "NO_PROJECT", ["cd into the directory holding the one you want, then re-run"]);
+    }
+    return first;
+}
+//# sourceMappingURL=context.js.map

package/dist/src/context.js.map

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

package/dist/src/destination.d.ts

@@ -0,0 +1,50 @@
+import type { ProjectContext } from "./context.js";
+export interface Destination {
+    platform: string;
+    name: string;
+    id: string;
+    os: string;
+    arch: string;
+    /** xcodebuild listed it under "Ineligible destinations". */
+    eligible: boolean;
+}
+/**
+ * Parse one `-showdestinations` row.
+ *
+ * Rows look like
+ *   { platform:iOS Simulator, arch:arm64, id:55D8…, OS:26.5, name:iPad (A16) }
+ * Values are unquoted and can contain spaces and parentheses, so the split is
+ * driven by the next `key:` rather than by commas.
+ */
+export declare function parseDestinationLine(line: string): Destination | undefined;
+export declare function listDestinations(project: ProjectContext, scheme: string): Promise<Destination[]>;
+export interface ResolveDestinationOptions {
+    project: ProjectContext;
+    scheme: string;
+    /** A simulator or device name, e.g. "iPhone 17 Pro". */
+    device?: string;
+    /** A full xcodebuild destination specifier, passed through untouched. */
+    raw?: string;
+}
+/**
+ * Work out what to pass `-destination`.
+ *
+ * Choosing a destination is the single most common thing an agent gets wrong
+ * against raw xcodebuild — the specifier syntax is unguessable and a miss
+ * costs a full failed invocation. So: an explicit `--destination` passes
+ * through, a `--device` name is matched against what the scheme actually
+ * supports, and with neither we pick the newest eligible simulator rather than
+ * making the agent ask first (AXI principle 4).
+ */
+export declare function resolveDestination(options: ResolveDestinationOptions): Promise<{
+    specifier: string;
+    described: string;
+}>;
+/**
+ * Prefer a simulator over hardware — a device build needs signing an agent
+ * cannot supply — then iOS over the other platforms, then the newest OS, which
+ * is what Xcode's own scheme selector lands on.
+ */
+export declare function pickDefault(destinations: Destination[]): Destination;
+/** A filesystem-safe stem for the log and result bundle of this run. */
+export declare function destinationSlug(described: string): string;

package/dist/src/destination.js

@@ -0,0 +1,174 @@
+import { AxiError } from "./errors.js";
+import { runMetadata } from "./xcodebuild.js";
+/**
+ * Parse one `-showdestinations` row.
+ *
+ * Rows look like
+ *   { platform:iOS Simulator, arch:arm64, id:55D8…, OS:26.5, name:iPad (A16) }
+ * Values are unquoted and can contain spaces and parentheses, so the split is
+ * driven by the next `key:` rather than by commas.
+ */
+export function parseDestinationLine(line) {
+    const inner = line.trim().match(/^\{(.*)\}$/)?.[1];
+    if (inner === undefined)
+        return undefined;
+    const fields = {};
+    for (const match of inner.matchAll(/(\w+):(.*?)(?=,\s*\w+:|$)/g)) {
+        const key = match[1];
+        const value = match[2];
+        if (key !== undefined && value !== undefined)
+            fields[key] = value.trim();
+    }
+    const platform = fields["platform"] ?? "";
+    if (platform.length === 0)
+        return undefined;
+    return {
+        platform,
+        name: fields["name"] ?? "",
+        id: fields["id"] ?? "",
+        os: fields["OS"] ?? "",
+        arch: fields["arch"] ?? "",
+        eligible: true,
+    };
+}
+/** Placeholders ("Any iOS Device") are not runnable and only add rows. */
+function isPlaceholder(destination) {
+    return destination.id.includes("placeholder");
+}
+export async function listDestinations(project, scheme) {
+    const { stdout, stderr } = await runMetadata([
+        ...project.flags,
+        "-scheme",
+        scheme,
+        "-showdestinations",
+    ]);
+    const out = [];
+    let eligible = true;
+    for (const line of `${stdout}\n${stderr}`.split("\n")) {
+        if (/Ineligible destinations/i.test(line)) {
+            eligible = false;
+            continue;
+        }
+        if (/Available destinations|Destinations compatible/i.test(line)) {
+            eligible = true;
+            continue;
+        }
+        const parsed = parseDestinationLine(line);
+        if (parsed && !isPlaceholder(parsed))
+            out.push({ ...parsed, eligible });
+    }
+    return out;
+}
+/** Compare two "26.5"-style versions; newest first. */
+function compareOS(a, b) {
+    const partsA = a.split(".").map(Number);
+    const partsB = b.split(".").map(Number);
+    for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+        const diff = (partsB[i] ?? 0) - (partsA[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * Work out what to pass `-destination`.
+ *
+ * Choosing a destination is the single most common thing an agent gets wrong
+ * against raw xcodebuild — the specifier syntax is unguessable and a miss
+ * costs a full failed invocation. So: an explicit `--destination` passes
+ * through, a `--device` name is matched against what the scheme actually
+ * supports, and with neither we pick the newest eligible simulator rather than
+ * making the agent ask first (AXI principle 4).
+ */
+export async function resolveDestination(options) {
+    if (options.raw) {
+        return { specifier: options.raw, described: options.raw };
+    }
+    const destinations = (await listDestinations(options.project, options.scheme)).filter((destination) => destination.eligible);
+    if (destinations.length === 0) {
+        throw new AxiError(`Scheme '${options.scheme}' has no runnable destinations`, "DESTINATION_NOT_FOUND", [
+            "Run `xcodebuild-axi destinations --scheme " +
+                options.scheme +
+                "` to see everything xcodebuild reported",
+        ]);
+    }
+    if (options.device) {
+        const wanted = options.device.toLowerCase();
+        const match = destinations.find((d) => d.name.toLowerCase() === wanted) ??
+            destinations.find((d) => d.id.toLowerCase() === wanted) ??
+            destinations.find((d) => d.name.toLowerCase().includes(wanted));
+        if (!match) {
+            const names = [...new Set(destinations.map((d) => d.name))].slice(0, 12);
+            throw new AxiError(`Scheme '${options.scheme}' has no destination named '${options.device}'`, "DESTINATION_NOT_FOUND", [`available: ${names.join(", ")}`]);
+        }
+        return { specifier: specifierFor(match), described: describe(match) };
+    }
+    const preferred = pickDefault(destinations);
+    return { specifier: specifierFor(preferred), described: describe(preferred) };
+}
+/**
+ * When several platforms are eligible, iOS is the one meant.
+ *
+ * A cross-platform Swift package reports simulators for every platform it
+ * supports, and sorting those by OS version alone lands on whichever happens
+ * to carry the highest number — a watchOS build for a package nobody was
+ * thinking about watchOS for. Anything unlisted sorts after these.
+ */
+const PLATFORM_ORDER = [
+    "iOS Simulator",
+    "tvOS Simulator",
+    "visionOS Simulator",
+    "watchOS Simulator",
+];
+function platformRank(platform) {
+    const index = PLATFORM_ORDER.indexOf(platform);
+    return index === -1 ? PLATFORM_ORDER.length : index;
+}
+/**
+ * Within one platform and OS the tie would otherwise fall to whatever
+ * xcodebuild listed first, which is an iPad as often as an iPhone. Xcode's own
+ * default is a phone, and so is almost every agent's intent.
+ */
+function deviceRank(name) {
+    return /^iPhone/.test(name) ? 0 : 1;
+}
+/**
+ * Prefer a simulator over hardware — a device build needs signing an agent
+ * cannot supply — then iOS over the other platforms, then the newest OS, which
+ * is what Xcode's own scheme selector lands on.
+ */
+export function pickDefault(destinations) {
+    const simulators = destinations.filter((d) => d.platform.includes("Simulator"));
+    const pool = simulators.length > 0 ? simulators : destinations;
+    const sorted = [...pool].sort((a, b) => platformRank(a.platform) - platformRank(b.platform) ||
+        compareOS(a.os, b.os) ||
+        deviceRank(a.name) - deviceRank(b.name));
+    const first = sorted[0];
+    if (first === undefined) {
+        throw new AxiError("No destination to choose from", "DESTINATION_NOT_FOUND");
+    }
+    return first;
+}
+/**
+ * Address a simulator by id, not by name.
+ *
+ * Two runtimes routinely publish the same device name ("iPhone 17 Pro" on both
+ * iOS 26.4 and 26.5), and a name-based specifier silently resolves to whichever
+ * xcodebuild sees first — so a run can land on a different OS than the one
+ * reported here. The udid is unambiguous.
+ */
+function specifierFor(destination) {
+    if (destination.id.length > 0) {
+        return `platform=${destination.platform},id=${destination.id}`;
+    }
+    return `platform=${destination.platform},name=${destination.name}`;
+}
+function describe(destination) {
+    const os = destination.os.length > 0 ? ` · ${destination.os}` : "";
+    return `${destination.name}${os}`;
+}
+/** A filesystem-safe stem for the log and result bundle of this run. */
+export function destinationSlug(described) {
+    return described.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+//# sourceMappingURL=destination.js.map

package/dist/src/destination.js.map

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

package/dist/src/errors.d.ts

@@ -0,0 +1,6 @@
+import { AxiError, exitCodeForError } from "axi-sdk-js";
+export type ErrorCode = "XCODE_NOT_INSTALLED" | "NO_PROJECT" | "SCHEME_NOT_FOUND" | "DESTINATION_NOT_FOUND" | "RESULT_NOT_FOUND" | "SIMULATOR_NOT_FOUND" | "NOT_FOUND" | "VALIDATION_ERROR" | "BUILD_FAILED" | "TEST_FAILED" | "UNKNOWN";
+export { AxiError, exitCodeForError };
+/** Translate an xcodebuild transcript into a structured error, or undefined. */
+export declare function mapXcodebuildError(transcript: string): AxiError | undefined;
+export declare function xcodeNotInstalledError(): AxiError;

package/dist/src/errors.js

@@ -0,0 +1,55 @@
+import { AxiError, exitCodeForError } from "axi-sdk-js";
+export { AxiError, exitCodeForError };
+const patterns = [
+    {
+        pattern: /does not contain a scheme named "([^"]+)"|The (?:project|workspace) named "[^"]+" does not contain a scheme named "([^"]+)"/,
+        code: "SCHEME_NOT_FOUND",
+        message: (m) => `No scheme named '${m[1] ?? m[2]}' in this project`,
+        suggestions: () => ["Run `xcodebuild-axi schemes` to list the real names"],
+    },
+    {
+        pattern: /Unable to find a destination matching the provided destination specifier/,
+        code: "DESTINATION_NOT_FOUND",
+        message: () => "No destination matched the requested device",
+        suggestions: () => [
+            "Run `xcodebuild-axi destinations --scheme <scheme>` to see what this scheme supports",
+            'Pass a simulator by name: `--device "iPhone 17 Pro"`',
+        ],
+    },
+    {
+        pattern: /Existing file at -resultBundlePath/,
+        code: "VALIDATION_ERROR",
+        message: () => "A result bundle already exists at that path and xcodebuild will not overwrite it",
+        suggestions: () => [
+            "Re-run without `--result`, or delete the existing bundle first",
+        ],
+    },
+    {
+        pattern: /Signing for "([^"]+)" requires a development team/,
+        code: "VALIDATION_ERROR",
+        message: (m) => `Target '${m[1]}' needs a development team to sign`,
+        suggestions: () => [
+            "For a simulator build, signing is not needed — `xcodebuild-axi build` disables it by default",
+            "For a device build, pass `--sign` and set DEVELOPMENT_TEAM in the project",
+        ],
+    },
+    {
+        pattern: /xcodebuild: error: (.+)/,
+        code: "UNKNOWN",
+        message: (m) => (m[1] ?? "").trim(),
+    },
+];
+/** Translate an xcodebuild transcript into a structured error, or undefined. */
+export function mapXcodebuildError(transcript) {
+    for (const { pattern, code, message, suggestions } of patterns) {
+        const match = transcript.match(pattern);
+        if (match) {
+            return new AxiError(message(match), code, suggestions?.(match) ?? []);
+        }
+    }
+    return undefined;
+}
+export function xcodeNotInstalledError() {
+    return new AxiError("Xcode command line tools are not available — `xcodebuild` is not on PATH", "XCODE_NOT_INSTALLED", ["Install Xcode, then run `xcode-select --switch /Applications/Xcode.app`"]);
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAexD,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;AAiBtC,MAAM,QAAQ,GAAmB;IAC/B;QACE,OAAO,EACL,6HAA6H;QAC/H,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,mBAAmB;QACnE,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC,qDAAqD,CAAC;KAC3E;IACD;QACE,OAAO,EACL,0EAA0E;QAC5E,IAAI,EAAE,uBAAuB;QAC7B,OAAO,EAAE,GAAG,EAAE,CAAC,6CAA6C;QAC5D,WAAW,EAAE,GAAG,EAAE,CAAC;YACjB,sFAAsF;YACtF,sDAAsD;SACvD;KACF;IACD;QACE,OAAO,EAAE,oCAAoC;QAC7C,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,GAAG,EAAE,CACZ,kFAAkF;QACpF,WAAW,EAAE,GAAG,EAAE,CAAC;YACjB,gEAAgE;SACjE;KACF;IACD;QACE,OAAO,EAAE,mDAAmD;QAC5D,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,oCAAoC;QACnE,WAAW,EAAE,GAAG,EAAE,CAAC;YACjB,8FAA8F;YAC9F,2EAA2E;SAC5E;KACF;IACD;QACE,OAAO,EAAE,yBAAyB;QAClC,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;KACpC;CACF,CAAC;AAEF,gFAAgF;AAChF,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC/D,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,IAAI,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,IAAI,QAAQ,CACjB,0EAA0E,EAC1E,qBAAqB,EACrB,CAAC,yEAAyE,CAAC,CAC5E,CAAC;AACJ,CAAC"}

package/dist/src/packages.d.ts

@@ -0,0 +1,31 @@
+import type { ProjectContext } from "./context.js";
+/**
+ * Read the pinned package versions out of `Package.resolved`.
+ *
+ * Xcode hides this file in a different place depending on the container, and
+ * an agent asking "what version of X am I on?" otherwise has to know all of
+ * them. Reading it needs no subprocess at all, which makes this the cheapest
+ * useful answer in the whole tool.
+ */
+export interface Pin {
+    identity: string;
+    version: string;
+    kind: string;
+    location: string;
+    revision: string;
+}
+/** Every place Xcode and SwiftPM keep the file, most specific first. */
+export declare function resolvedFileCandidates(project: ProjectContext): string[];
+export declare function findResolvedFile(project: ProjectContext): string | undefined;
+export declare function readPins(path: string): Pin[];
+/**
+ * Package-resolution behavior, shared by the build family and `packages`.
+ *
+ * These are the flags that decide whether xcodebuild is allowed to reach the
+ * network mid-build. An agent on a flaky or offline runner needs them, and
+ * they are otherwise eleven long camelCase names to remember.
+ */
+export declare const PACKAGE_FLAGS: readonly ["--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 PACKAGE_VALUE_FLAGS: readonly ["--cache", "--package-cache", "--package-auth", "--registry-url", "--scm-to-registry", "--fingerprint-policy", "--signing-entity-policy", "--scm-provider"];
+export declare const PACKAGE_FLAG_HELP = "  --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";
+export declare function packageArgs(args: string[]): string[];

package/dist/src/packages.js

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getFlag, hasFlag } from "./args.js";
+/** Every place Xcode and SwiftPM keep the file, most specific first. */
+export function resolvedFileCandidates(project) {
+    const root = project.kind === "package" ? project.path : dirname(project.path);
+    return [
+        // Workspace- and project-scoped copies, which win when both exist.
+        join(project.path, "xcshareddata", "swiftpm", "Package.resolved"),
+        join(project.path, "project.xcworkspace", "xcshareddata", "swiftpm", "Package.resolved"),
+        join(root, "Package.resolved"),
+        // Tuist keeps the workspace's graph here rather than inside the generated
+        // workspace, which is regenerated and so cannot hold source of truth.
+        join(root, "Tuist", "Package.resolved"),
+    ];
+}
+export function findResolvedFile(project) {
+    return resolvedFileCandidates(project).find((candidate) => existsSync(candidate));
+}
+export function readPins(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+    return (parsed.pins ?? [])
+        .map((pin) => ({
+        identity: pin.identity ?? "unknown",
+        // A branch pin has no version; reporting an empty cell would read as
+        // "unpinned" when it is in fact pinned to a moving target.
+        version: pin.state?.version ??
+            (pin.state?.branch ? `branch ${pin.state.branch}` : "revision"),
+        kind: (pin.kind ?? "")
+            .replace("remoteSourceControl", "remote")
+            .replace("localSourceControl", "local"),
+        location: pin.location ?? "",
+        revision: (pin.state?.revision ?? "").slice(0, 7),
+    }))
+        .sort((a, b) => a.identity.localeCompare(b.identity));
+}
+/**
+ * Package-resolution behavior, shared by the build family and `packages`.
+ *
+ * These are the flags that decide whether xcodebuild is allowed to reach the
+ * network mid-build. An agent on a flaky or offline runner needs them, and
+ * they are otherwise eleven long camelCase names to remember.
+ */
+export const PACKAGE_FLAGS = [
+    "--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 const PACKAGE_VALUE_FLAGS = [
+    "--cache",
+    "--package-cache",
+    "--package-auth",
+    "--registry-url",
+    "--scm-to-registry",
+    "--fingerprint-policy",
+    "--signing-entity-policy",
+    "--scm-provider",
+];
+export const PACKAGE_FLAG_HELP = `  --offline               resolve using only the versions already in Package.resolved
+  --cache <path>          clone remote packages into this directory
+  --package-cache <path>  shared package cache directory (across projects)
+  --no-auto-resolve       never resolve automatically; fail if Package.resolved is stale
+  --skip-package-updates  use the packages already cloned, without checking for updates
+  --no-package-cache      ignore the shared package repository cache
+  --skip-plugin-validation      trust build plugins without prompting
+  --skip-signature-validation   do not verify package signatures
+  --package-auth <kind>   keychain or netrc
+  --registry-url <url>    default package registry
+  --scm-to-registry <kind>      none, identity, or swift-package-registry
+  --fingerprint-policy <kind>   strict or warn
+  --signing-entity-policy <kind>  strict or warn
+  --scm-provider <kind>   system or xcode`;
+const SWITCHES = [
+    ["--offline", "-onlyUsePackageVersionsFromResolvedFile"],
+    ["--no-auto-resolve", "-disableAutomaticPackageResolution"],
+    ["--skip-package-updates", "-skipPackageUpdates"],
+    ["--no-package-cache", "-disablePackageRepositoryCache"],
+    ["--skip-plugin-validation", "-skipPackagePluginValidation"],
+    ["--skip-signature-validation", "-skipPackageSignatureValidation"],
+];
+const VALUES = [
+    ["--cache", "-clonedSourcePackagesDirPath"],
+    ["--package-cache", "-packageCachePath"],
+    ["--package-auth", "-packageAuthorizationProvider"],
+    ["--registry-url", "-defaultPackageRegistryURL"],
+    ["--scm-to-registry", "-packageDependencySCMToRegistryTransformation"],
+    ["--fingerprint-policy", "-packageFingerprintPolicy"],
+    ["--signing-entity-policy", "-packageSigningEntityPolicy"],
+    ["--scm-provider", "-scmProvider"],
+];
+export function packageArgs(args) {
+    return [
+        ...SWITCHES.filter(([flag]) => hasFlag(args, flag)).map(([, name]) => name),
+        ...VALUES.flatMap(([flag, name]) => {
+            const value = getFlag(args, flag);
+            return value === undefined ? [] : [name, value];
+        }),
+    ];
+}
+//# sourceMappingURL=packages.js.map

package/dist/src/packages.js.map

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