rork-xcode 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -114,6 +114,22 @@ declare class PbxprojParseError extends Error {
    */
   constructor(message: string, source: string, offset: number);
 }
+/**
+ * Thrown by the object model when an operation cannot proceed: the
+ * document lacks the structure the operation needs (no objects dictionary,
+ * no root project object), a view's object was removed from the document,
+ * or a creation request names a product type the model cannot scaffold.
+ *
+ * Read paths in the model return `undefined` for merely malformed data;
+ * this error marks the cases where continuing would corrupt the document
+ * or hide a programming mistake.
+ */
+declare class XcodeModelError extends Error {
+  /**
+   * @param message Description of the failed operation.
+   */
+  constructor(message: string);
+}
 /**
  * Thrown when a value cannot be represented in a `project.pbxproj` document.
  *
@@ -135,6 +151,1083 @@ declare class PbxprojBuildError extends Error {
   constructor(message: string, path: string);
 }
 //#endregion
+//#region src/model/isa.d.ts
+/**
+ * Names and well-known values of the pbxproj object vocabulary.
+ *
+ * Everything here mirrors strings Xcode itself writes; nothing is invented.
+ * Centralizing them keeps the object model free of string literals and
+ * gives call sites one place to import from.
+ *
+ * @module
+ */
+/**
+ * The `isa` names the object model works with. The parser and serializer
+ * accept any isa; this list only covers the kinds the model creates or
+ * gives typed access to.
+ */
+declare const Isa: {
+  readonly aggregateTarget: "PBXAggregateTarget";
+  readonly buildFile: "PBXBuildFile";
+  readonly buildRule: "PBXBuildRule";
+  readonly containerItemProxy: "PBXContainerItemProxy";
+  readonly copyFilesBuildPhase: "PBXCopyFilesBuildPhase";
+  readonly fileReference: "PBXFileReference";
+  readonly fileSystemSynchronizedBuildFileExceptionSet: "PBXFileSystemSynchronizedBuildFileExceptionSet";
+  readonly fileSystemSynchronizedRootGroup: "PBXFileSystemSynchronizedRootGroup";
+  readonly frameworksBuildPhase: "PBXFrameworksBuildPhase";
+  readonly group: "PBXGroup";
+  readonly legacyTarget: "PBXLegacyTarget";
+  readonly nativeTarget: "PBXNativeTarget";
+  readonly project: "PBXProject";
+  readonly referenceProxy: "PBXReferenceProxy";
+  readonly resourcesBuildPhase: "PBXResourcesBuildPhase";
+  readonly sourcesBuildPhase: "PBXSourcesBuildPhase";
+  readonly targetDependency: "PBXTargetDependency";
+  readonly variantGroup: "PBXVariantGroup";
+  readonly buildConfiguration: "XCBuildConfiguration";
+  readonly configurationList: "XCConfigurationList";
+  readonly localSwiftPackageReference: "XCLocalSwiftPackageReference";
+  readonly remoteSwiftPackageReference: "XCRemoteSwiftPackageReference";
+  readonly swiftPackageProductDependency: "XCSwiftPackageProductDependency";
+  readonly versionGroup: "XCVersionGroup";
+};
+/**
+ * Product type identifiers of the targets the model creates or reasons
+ * about. Other product types pass through untouched.
+ */
+declare const ProductType: {
+  readonly application: "com.apple.product-type.application";
+  readonly messagesApplication: "com.apple.product-type.application.messages";
+  readonly appExtension: "com.apple.product-type.app-extension";
+  readonly messagesExtension: "com.apple.product-type.app-extension.messages";
+  readonly extensionKitExtension: "com.apple.product-type.extensionkit-extension";
+  readonly onDemandInstallCapableApplication: "com.apple.product-type.application.on-demand-install-capable";
+  readonly watchApp: "com.apple.product-type.application.watchapp2";
+};
+/**
+ * The Apple platforms the model can resolve a main application target for.
+ */
+type ApplePlatform = "ios" | "macos" | "tvos" | "watchos" | "visionos";
+/**
+ * `dstSubfolderSpec` values for copy-files build phases, named after the
+ * destination each selects.
+ */
+declare const CopyFilesDestination: {
+  readonly plugins: 13;
+  readonly productsDirectory: 16;
+};
+//#endregion
+//#region src/model/doctor.d.ts
+/**
+ * The kinds of problem {@link validateProject} reports.
+ *
+ * - `dangling-root`: the document's `rootObject` is missing or does not
+ *   resolve to a `PBXProject`.
+ * - `missing-isa`: an object carries no kind, which Xcode cannot read.
+ * - `dangling-reference`: a known reference property points at an id the
+ *   document does not contain.
+ * - `unreachable-object`: nothing on the path from the root references
+ *   the object. Xcode ignores such orphans, and
+ *   {@link pruneOrphanObjects} removes them.
+ */
+type ProjectIssueKind = "dangling-root" | "missing-isa" | "dangling-reference" | "unreachable-object";
+/**
+ * One problem found by {@link validateProject}.
+ */
+interface ProjectIssue {
+  /** The problem's kind, one of {@link ProjectIssueKind}. */
+  kind: ProjectIssueKind;
+  /** Human-readable description with the involved ids and properties. */
+  message: string;
+  /** The object the problem sits on, when it sits on one. */
+  objectId?: string;
+}
+//#endregion
+//#region src/model/properties.d.ts
+/**
+ * Build settings of one configuration. The named keys are the ones
+ * programmatic edits touch most. Projects carry many more, and all of
+ * them stay accessible through the index signature.
+ */
+interface BuildSettings extends PbxprojObject {
+  ASSETCATALOG_COMPILER_APPICON_NAME?: string;
+  CODE_SIGN_ENTITLEMENTS?: string;
+  CODE_SIGN_IDENTITY?: string;
+  CODE_SIGN_STYLE?: string;
+  CURRENT_PROJECT_VERSION?: number | string;
+  DEVELOPMENT_TEAM?: string;
+  GENERATE_INFOPLIST_FILE?: string;
+  INFOPLIST_FILE?: string;
+  IPHONEOS_DEPLOYMENT_TARGET?: string;
+  LD_RUNPATH_SEARCH_PATHS?: string;
+  MACOSX_DEPLOYMENT_TARGET?: string;
+  MARKETING_VERSION?: number | string;
+  PRODUCT_BUNDLE_IDENTIFIER?: string;
+  PRODUCT_NAME?: string;
+  PROVISIONING_PROFILE_SPECIFIER?: string;
+  SDKROOT?: string;
+  SKIP_INSTALL?: string;
+  SUPPORTED_PLATFORMS?: string;
+  SWIFT_VERSION?: string;
+  TARGETED_DEVICE_FAMILY?: number | string;
+  TVOS_DEPLOYMENT_TARGET?: string;
+  WATCHOS_DEPLOYMENT_TARGET?: string;
+  XROS_DEPLOYMENT_TARGET?: string;
+}
+/**
+ * Properties shared by every target kind. Native, aggregate, and legacy
+ * targets all carry a name, a configuration list, build phases, and
+ * dependencies.
+ */
+interface TargetProperties extends PbxprojObject {
+  buildConfigurationList?: string;
+  buildPhases?: string[];
+  dependencies?: string[];
+  name?: string;
+  productName?: string;
+}
+/**
+ * Properties of a `PBXNativeTarget`.
+ */
+interface NativeTargetProperties extends TargetProperties {
+  buildRules?: string[];
+  fileSystemSynchronizedGroups?: string[];
+  packageProductDependencies?: string[];
+  productReference?: string;
+  productType?: string;
+}
+/**
+ * Properties of a `PBXLegacyTarget`, a target that shells out to an
+ * external build tool such as make.
+ */
+interface LegacyTargetProperties extends TargetProperties {
+  buildArgumentsString?: string;
+  buildToolPath?: string;
+  buildWorkingDirectory?: string;
+  passBuildSettingsInEnvironment?: number;
+}
+/**
+ * Properties of a `PBXBuildRule`, a per-target rule mapping a file kind to
+ * the compiler or script that processes it.
+ */
+interface BuildRuleProperties extends PbxprojObject {
+  compilerSpec?: string;
+  filePatterns?: string;
+  fileType?: string;
+  inputFiles?: string[];
+  isEditable?: number;
+  name?: string;
+  outputFiles?: string[];
+  runOncePerArchitecture?: number;
+  script?: string;
+}
+/**
+ * Properties of the root `PBXProject` object.
+ */
+interface RootProjectProperties extends PbxprojObject {
+  attributes?: PbxprojObject;
+  buildConfigurationList?: string;
+  developmentRegion?: string;
+  knownRegions?: string[];
+  mainGroup?: string;
+  packageReferences?: string[];
+  productRefGroup?: string;
+  projectDirPath?: string;
+  projectRoot?: string;
+  targets?: string[];
+}
+/**
+ * Properties of a `PBXGroup` or `PBXVariantGroup`.
+ */
+interface GroupProperties extends PbxprojObject {
+  children?: string[];
+  name?: string;
+  path?: string;
+  sourceTree?: string;
+}
+/**
+ * Properties of an `XCVersionGroup`, the container of a versioned Core
+ * Data model (`.xcdatamodeld`). Its children are the model versions and
+ * `currentVersion` names the active one.
+ */
+interface VersionGroupProperties extends GroupProperties {
+  currentVersion?: string;
+  versionGroupType?: string;
+}
+/**
+ * Properties of a `PBXReferenceProxy`, the stand-in for a product built
+ * by a target of another project referenced from this one.
+ */
+interface ReferenceProxyProperties extends PbxprojObject {
+  fileType?: string;
+  name?: string;
+  path?: string;
+  remoteRef?: string;
+  sourceTree?: string;
+}
+/**
+ * Properties shared by the `PBX*BuildPhase` kinds. Copy-files and
+ * shell-script phases carry the destination and script keys. The standard
+ * phases leave them absent.
+ */
+interface BuildPhaseProperties extends PbxprojObject {
+  buildActionMask?: number;
+  dstPath?: string;
+  dstSubfolderSpec?: number;
+  files?: string[];
+  inputFileListPaths?: string[];
+  inputPaths?: string[];
+  name?: string;
+  outputFileListPaths?: string[];
+  outputPaths?: string[];
+  runOnlyForDeploymentPostprocessing?: number;
+  shellPath?: string;
+  shellScript?: string;
+}
+/**
+ * Properties of a `PBXFileSystemSynchronizedRootGroup`.
+ */
+interface SyncRootGroupProperties extends PbxprojObject {
+  exceptions?: string[];
+  explicitFileTypes?: PbxprojObject;
+  explicitFolders?: string[];
+  path?: string;
+  sourceTree?: string;
+}
+/**
+ * Properties of a `PBXFileReference`.
+ */
+interface FileReferenceProperties extends PbxprojObject {
+  explicitFileType?: string;
+  fileEncoding?: number;
+  includeInIndex?: number;
+  lastKnownFileType?: string;
+  name?: string;
+  path?: string;
+  sourceTree?: string;
+}
+/**
+ * Properties of a `PBXBuildFile`.
+ */
+interface BuildFileProperties extends PbxprojObject {
+  fileRef?: string;
+  productRef?: string;
+  settings?: PbxprojObject;
+}
+/**
+ * Properties of an `XCBuildConfiguration`.
+ */
+interface BuildConfigurationProperties extends PbxprojObject {
+  baseConfigurationReference?: string;
+  buildSettings?: BuildSettings;
+  name?: string;
+}
+/**
+ * Properties of an `XCConfigurationList`.
+ */
+interface ConfigurationListProperties extends PbxprojObject {
+  buildConfigurations?: string[];
+  defaultConfigurationIsVisible?: number;
+  defaultConfigurationName?: string;
+}
+/**
+ * Properties of a `PBXTargetDependency`.
+ */
+interface TargetDependencyProperties extends PbxprojObject {
+  name?: string;
+  target?: string;
+  targetProxy?: string;
+}
+/**
+ * Properties of a `PBXContainerItemProxy`.
+ */
+interface ContainerItemProxyProperties extends PbxprojObject {
+  containerPortal?: string;
+  proxyType?: number;
+  remoteGlobalIDString?: string;
+  remoteInfo?: string;
+}
+/**
+ * Properties of an `XCRemoteSwiftPackageReference` or
+ * `XCLocalSwiftPackageReference`. Remote references carry the repository
+ * and requirement. Local ones carry the relative path.
+ */
+interface SwiftPackageReferenceProperties extends PbxprojObject {
+  relativePath?: string;
+  repositoryURL?: string;
+  requirement?: PbxprojObject;
+}
+/**
+ * Properties of an `XCSwiftPackageProductDependency`.
+ */
+interface SwiftPackageProductDependencyProperties extends PbxprojObject {
+  package?: string;
+  productName?: string;
+}
+/**
+ * Properties of a `PBXFileSystemSynchronizedBuildFileExceptionSet` or its
+ * build-phase-membership variant.
+ */
+interface ExceptionSetProperties extends PbxprojObject {
+  buildPhase?: string;
+  membershipExceptions?: string[];
+  target?: string;
+}
+//#endregion
+//#region src/model/target.d.ts
+/**
+ * The behavior every target kind shares. A target of any kind carries
+ * build configurations and settings, build phases, and dependencies, and
+ * this class holds their accessors and mutations. `PBXNativeTarget`,
+ * `PBXAggregateTarget`, and `PBXLegacyTarget` all extend it, so code that
+ * walks or rewires targets can accept any of them.
+ */
+declare class Target<Properties extends TargetProperties = TargetProperties> extends XcodeObject<Properties> {
+  /**
+   * The target's name, when present.
+   */
+  get name(): string | undefined;
+  /**
+   * The views of the target's build configurations, in list order.
+   */
+  buildConfigurations(): XcodeObject[];
+  /**
+   * The settings dictionary of the target's default configuration: the one
+   * named by the list's `defaultConfigurationName`, falling back to the
+   * first configuration. Returns `undefined` when the target has no
+   * configurations or the default carries no settings dictionary.
+   */
+  defaultConfigurationSettings(): PbxprojObject | undefined;
+  /**
+   * Reads a build setting from the target's default configuration,
+   * inheriting from the project-level configuration when the target omits
+   * the key. This mirrors how Xcode resolves settings hierarchically;
+   * generated app templates set values like `SDKROOT` only at the project
+   * level.
+   *
+   * Only string values are returned; a list- or number-valued setting reads
+   * as `undefined`.
+   */
+  getBuildSetting(key: string): string | undefined;
+  /**
+   * Writes a build setting on every configuration of the target, so Debug
+   * and Release stay consistent.
+   */
+  setBuildSetting(key: string, value: string): void;
+  /**
+   * Removes a build setting from every configuration of the target.
+   */
+  removeBuildSetting(key: string): void;
+  /**
+   * The views of the target's dependency objects
+   * (`PBXTargetDependency`), in declaration order. Resolve a dependency's
+   * target through its `target` property.
+   */
+  dependencies(): XcodeObject[];
+  /**
+   * The views of the target's build phases, in build order.
+   */
+  buildPhases(): BuildPhase[];
+  /**
+   * Finds the target's first build phase with the given isa, and, when
+   * `name` is provided, the given display name.
+   */
+  findBuildPhase(isa: string, name?: string): BuildPhase | undefined;
+  /**
+   * Returns the target's build phase with the given isa and properties,
+   * creating and appending it when missing. The properties apply only on
+   * creation; an existing phase is returned as is.
+   *
+   * The match key is the isa plus the `name` property when one is given,
+   * so differently named copy-files phases coexist.
+   */
+  ensureBuildPhase(isa: string, properties?: PbxprojObject): BuildPhase;
+  /**
+   * The target's shell-script phase with the given name, created with the
+   * usual defaults (`/bin/sh`, empty input and output lists) when missing.
+   * The script and other properties apply only on creation.
+   *
+   * @param name Display name of the phase, which is also its match key.
+   * @param properties Phase properties, most usefully `shellScript`.
+   */
+  ensureShellScriptPhase(name: string, properties?: PbxprojObject): BuildPhase;
+  /**
+   * Adds a dependency on another target of the same project, wiring the
+   * `PBXContainerItemProxy` and `PBXTargetDependency` pair Xcode uses to
+   * express it. Adding an existing dependency is a no-op.
+   *
+   * @returns The view of the target dependency object.
+   */
+  addDependency(dependency: Target): XcodeObject;
+}
+/**
+ * A `PBXNativeTarget` is a product the project compiles and packages
+ * itself, such as an application or an app extension.
+ */
+declare class NativeTarget extends Target<NativeTargetProperties> {
+  /**
+   * The target's product type identifier, for example
+   * `com.apple.product-type.application`.
+   */
+  get productType(): string | undefined;
+  /**
+   * Rewrites the target's product type. Used by packaging repairs that
+   * convert foundation extensions into ExtensionKit extensions.
+   */
+  set productType(value: string);
+  /**
+   * The view of the target's product file reference, when the target has
+   * one.
+   */
+  get productReference(): XcodeObject | undefined;
+  /**
+   * Whether the target builds for watchOS, decided by its product type or
+   * its watchOS deployment-target setting.
+   */
+  isWatchOS(): boolean;
+  /**
+   * The views of the target's Swift package product dependencies, in
+   * declaration order.
+   */
+  packageProductDependencies(): XcodeObject[];
+  /**
+   * The views of the target's file-system-synchronized folders, in
+   * declaration order.
+   */
+  syncGroups(): SyncRootGroup[];
+  /**
+   * The views of the target's build rules, in evaluation order. Empty for
+   * targets without custom rules, which is nearly all of them.
+   */
+  buildRules(): BuildRule[];
+  /**
+   * The target's sources phase, created when missing.
+   */
+  ensureSourcesPhase(): BuildPhase;
+  /**
+   * The target's frameworks phase, created when missing.
+   */
+  ensureFrameworksPhase(): BuildPhase;
+  /**
+   * The target's resources phase, created when missing.
+   */
+  ensureResourcesPhase(): BuildPhase;
+  /**
+   * Embeds another target's product into this target through the
+   * copy-files phase its product type calls for ("Embed Foundation
+   * Extensions", "Embed App Clips", "Embed Watch Content", or "Embed
+   * ExtensionKit Extensions").
+   *
+   * An existing phase with the same name is reused, its destination is
+   * repaired to the type's canonical values, and the product's build file
+   * is deduplicated, so embedding is idempotent.
+   *
+   * @returns The view of the embed phase, or `undefined` when the embedded
+   *   target has no product reference to embed.
+   */
+  embed(extension: NativeTarget): BuildPhase | undefined;
+  /**
+   * The on-disk folder paths of the file-system-synchronized groups linked
+   * to this target. Empty for targets without synchronized folders
+   * (projects predating Xcode 16).
+   */
+  syncGroupPaths(): string[];
+  /**
+   * Creates a file-system-synchronized folder for an on-disk path, links it
+   * to this target, and registers it in the project's main group so Xcode
+   * shows it in the navigator. When the target already links a folder with
+   * the same path, that folder is returned instead, so re-running a
+   * scaffold step cannot duplicate groups.
+   *
+   * @param path Folder path relative to the project root, for example the
+   *   target's name.
+   * @returns The view of the target's synchronized folder for the path.
+   */
+  addSyncGroup(path: string): SyncRootGroup;
+  /**
+   * Links a Swift package product to this target. It creates the
+   * `XCSwiftPackageProductDependency`, registers it on the target, and
+   * ensures the frameworks phase carries its build file. Linking an
+   * already linked product is a no-op.
+   *
+   * @param options.productName The product to link, as the package
+   *   manifest names it.
+   * @param options.packageReference The package reference view returned by
+   *   {@link XcodeProject.addSwiftPackage} or
+   *   {@link XcodeProject.findSwiftPackage}.
+   * @returns The view of the product dependency.
+   */
+  addSwiftPackageProduct(options: {
+    productName: string;
+    packageReference: XcodeObject;
+  }): XcodeObject;
+  /**
+   * Links a system framework (for example `Messages`) to this target. It
+   * reuses or creates the file reference under the SDK's frameworks
+   * directory and makes sure the frameworks phase carries its build file.
+   * Linking an already linked framework is a no-op.
+   *
+   * @param name Framework name without the `.framework` suffix.
+   * @returns The view of the framework's file reference.
+   */
+  addSystemFramework(name: string): XcodeObject;
+}
+/**
+ * An aggregate target produces nothing itself. It exists to group other
+ * targets through its dependencies and to run script or copy-files
+ * phases, and the shared target surface covers everything it carries.
+ */
+declare class AggregateTarget extends Target {}
+/**
+ * A legacy target shells out to an external build tool such as make
+ * instead of using Xcode's build system.
+ */
+declare class LegacyTarget extends Target<LegacyTargetProperties> {
+  /**
+   * The build tool the target invokes, as an absolute path.
+   */
+  get buildToolPath(): string | undefined;
+  /**
+   * The arguments passed to the build tool, as one shell-style string.
+   */
+  get buildArgumentsString(): string | undefined;
+  /**
+   * The working directory the build tool runs in, when the target sets
+   * one.
+   */
+  get buildWorkingDirectory(): string | undefined;
+}
+//#endregion
+//#region src/model/objects.d.ts
+/**
+ * A `PBXGroup` is a folder in Xcode's navigator, holding references to
+ * files and other groups. Variant groups (`PBXVariantGroup`) share this
+ * view. The type parameter lets subclasses carry a more specific property
+ * shape.
+ */
+declare class Group<Properties extends GroupProperties = GroupProperties> extends XcodeObject<Properties> {
+  /**
+   * Ids of the group's children, in navigator order. Non-string entries of
+   * a malformed document are skipped.
+   */
+  get childIds(): string[];
+  /**
+   * The views of the group's children, in navigator order.
+   */
+  children(): XcodeObject[];
+  /**
+   * Adds an existing object (a file reference or another group) to the end
+   * of the group's children. Adding a child the group already lists is a
+   * no-op.
+   */
+  addChild(child: XcodeObject): void;
+  /**
+   * Returns the descendant group for a `/`-separated path, creating any
+   * missing groups along the way. Each component matches a child group by
+   * its `path`, falling back to its `name`; created groups carry the
+   * component as their `path` so they mirror folders on disk.
+   *
+   * ```ts
+   * const generated = mainGroup.ensureGroup("Sources/Generated");
+   * generated.createFile("Config.swift");
+   * ```
+   */
+  ensureGroup(path: string): Group;
+  /**
+   * Creates a `PBXFileReference` for a path relative to this group and adds
+   * it to the group's children.
+   *
+   * The reference's `lastKnownFileType` derives from the file extension
+   * when it is a known kind; otherwise the reference carries no type and
+   * Xcode re-derives one on open.
+   *
+   * @param path File path relative to the group, for example
+   *   `Demo/Config.swift`.
+   * @returns The view of the created file reference.
+   */
+  createFile(path: string): XcodeObject;
+}
+/**
+ * A build phase is an ordered list of build files processed by one step
+ * of a target's build. Every `PBX*BuildPhase` kind shares this view.
+ */
+declare class BuildPhase extends XcodeObject<BuildPhaseProperties> {
+  /**
+   * The phase's display name, when it carries an explicit one. Xcode names
+   * copy-files and shell-script phases; the standard phases derive their
+   * names from their isa.
+   */
+  get name(): string | undefined;
+  /**
+   * Ids of the phase's `PBXBuildFile` entries, in build order.
+   */
+  get buildFileIds(): string[];
+  /**
+   * Whether the phase already lists the build file.
+   */
+  containsBuildFile(buildFileId: string): boolean;
+  /**
+   * Appends an existing build file to the phase unless it is already
+   * listed.
+   */
+  appendBuildFile(buildFileId: string): void;
+  /**
+   * Removes a build file from the phase. Removing an id the phase does not
+   * list is a no-op.
+   */
+  removeBuildFile(buildFileId: string): void;
+  /**
+   * Ensures the phase carries a `PBXBuildFile` for the referenced object,
+   * creating one when no existing build file in this phase points at it.
+   *
+   * @param reference The file reference or package product the build file
+   *   should point at.
+   * @param options.referenceKey Which build-file field carries the
+   *   reference: `fileRef` for file references (the default) or
+   *   `productRef` for Swift package products.
+   * @param options.settings Optional per-file settings, for example
+   *   `{ ATTRIBUTES: ["RemoveHeadersOnCopy"] }`.
+   * @returns The view of the phase's build file for the reference.
+   */
+  ensureBuildFile(reference: XcodeObject, options?: {
+    referenceKey?: "fileRef" | "productRef";
+    settings?: Record<string, string[] | string>;
+  }): XcodeObject;
+}
+/**
+ * A `PBXFileSystemSynchronizedRootGroup` is an Xcode 16 folder whose
+ * members are synchronized from disk instead of listed individually.
+ */
+declare class SyncRootGroup extends XcodeObject<SyncRootGroupProperties> {
+  /**
+   * The group's on-disk folder path, when present.
+   */
+  get path(): string | undefined;
+  /**
+   * Excludes files from a target's membership in this synchronized folder
+   * through a `PBXFileSystemSynchronizedBuildFileExceptionSet` linked into
+   * the group's exceptions.
+   *
+   * Xcode keeps one exception set per target and folder, so when this
+   * group already carries a set for the target, the file names merge into
+   * it instead of creating a second set; names already excluded are not
+   * duplicated.
+   *
+   * The standard use is keeping a scaffolded `Info.plist` from being
+   * double-copied: the build already processes it through the target's
+   * `INFOPLIST_FILE` setting.
+   *
+   * @param target The target whose membership the exceptions restrict.
+   * @param membershipExceptions File names inside the folder to exclude.
+   * @returns The view of the target's exception set for this folder.
+   */
+  addMembershipExceptions(target: NativeTarget, membershipExceptions: string[]): XcodeObject;
+}
+/**
+ * A `PBXBuildRule` tells a target which compiler or script processes a
+ * kind of file.
+ */
+declare class BuildRule extends XcodeObject<BuildRuleProperties> {
+  /**
+   * The rule's script, when it is a script rule rather than a reference
+   * to a compiler specification.
+   */
+  get script(): string | undefined;
+}
+/**
+ * An `XCVersionGroup` contains a versioned Core Data model
+ * (`.xcdatamodeld`). Its children are the model versions and
+ * `currentVersion` names the active one.
+ */
+declare class VersionGroup extends Group<VersionGroupProperties> {
+  /**
+   * The view of the active model version's file reference, when the group
+   * names one.
+   */
+  currentVersion(): XcodeObject | undefined;
+  /**
+   * Makes a model version the active one, adding it to the group's
+   * children when it is not listed yet.
+   */
+  setCurrentVersion(reference: XcodeObject): void;
+}
+/**
+ * A `PBXReferenceProxy` stands in for a product built by a target of
+ * another project referenced from this one.
+ */
+declare class ReferenceProxy extends XcodeObject<ReferenceProxyProperties> {
+  /**
+   * The proxy's product path inside the other project's build directory,
+   * when present.
+   */
+  get path(): string | undefined;
+  /**
+   * The view of the container item proxy that names the remote target,
+   * when the reference resolves.
+   */
+  remoteReference(): XcodeObject | undefined;
+}
+//#endregion
+//#region src/model/project.d.ts
+/**
+ * The `PBXProject` object at the document root. It owns the target list,
+ * the main group, and the project-level configurations.
+ */
+declare class RootProject extends XcodeObject<RootProjectProperties> {
+  /**
+   * Ids of the project's targets, in project order.
+   */
+  targetIds(): string[];
+  /**
+   * The view of the project's main group, when the document has one. The
+   * main group is the root of Xcode's navigator tree.
+   */
+  mainGroup(): Group | undefined;
+  /**
+   * The settings dictionary of the project-level default configuration.
+   * Targets inherit from these settings; see
+   * {@link NativeTarget.getBuildSetting}.
+   */
+  defaultConfigurationSettings(): PbxprojObject | undefined;
+  /**
+   * The views of the project's Swift package references, remote and local,
+   * in declaration order.
+   */
+  packageReferences(): XcodeObject[];
+  /**
+   * The group product references live in, creating it (and registering it
+   * as the project's `productRefGroup`) when missing.
+   */
+  ensureProductsGroup(): Group;
+}
+/**
+ * Options for {@link XcodeProject.addNativeTarget}.
+ */
+interface AddNativeTargetOptions {
+  /** Target name, also used as the product name. */
+  name: string;
+  /**
+   * Product type identifier. Must be one of the creatable kinds:
+   * applications, app extensions, their Messages variants, watch
+   * applications, App Clips, and ExtensionKit extensions.
+   */
+  productType: string;
+  /**
+   * Build settings applied to every created configuration. Each
+   * configuration receives its own copy.
+   */
+  buildSettings?: Record<string, number | string>;
+  /**
+   * Names of the configurations to create. Defaults to `Debug` and
+   * `Release`, matching the pair Xcode scaffolds.
+   */
+  configurationNames?: string[];
+  /**
+   * The configuration name recorded as the list's default. Defaults to
+   * `Release`.
+   */
+  defaultConfigurationName?: string;
+}
+/**
+ * A parsed `project.pbxproj` with typed, mutable access to its objects.
+ *
+ * ```ts
+ * const project = XcodeProject.parse(pbxprojText);
+ * const app = project.findMainAppTarget("ios");
+ * app?.setBuildSetting("MARKETING_VERSION", "1.2.0");
+ * const text = project.build();
+ * ```
+ */
+declare class XcodeProject {
+  /** The parsed document this model wraps. */
+  readonly document: PbxprojObject;
+  /** The document's `objects` dictionary. */
+  private readonly objectsDictionary;
+  /**
+   * Identity map of object views, one view per id, created on first
+   * access, so views of the same object compare with `===`.
+   */
+  private readonly views;
+  private constructor();
+  /**
+   * Parses pbxproj text and wraps it in a model.
+   *
+   * @throws PbxprojParseError when the text is malformed.
+   * @throws XcodeModelError when the document has no objects dictionary.
+   */
+  static parse(text: string): XcodeProject;
+  /**
+   * Wraps an already parsed document in a model. The document is used in
+   * place, not copied; model mutations write into it.
+   */
+  static fromDocument(document: PbxprojObject): XcodeProject;
+  /**
+   * Serializes the current document state to pbxproj text in Xcode's
+   * canonical layout.
+   */
+  build(): string;
+  /**
+   * The raw properties dictionary of an object.
+   *
+   * @throws XcodeModelError when no object with the id exists; views use
+   *   this accessor, so a view of a deleted object fails loudly instead of
+   *   resurrecting the entry.
+   */
+  propertiesOf(id: string): PbxprojObject;
+  /**
+   * The raw properties dictionary of an object, or `undefined` when the id
+   * is absent, dangling, or not a dictionary.
+   */
+  propertiesOfOptional(id: string | undefined): PbxprojObject | undefined;
+  /**
+   * The view of an object by id, or `undefined` when the id is absent or
+   * its entry is not a dictionary. Repeated lookups return the same view
+   * instance.
+   */
+  get(id: string | undefined): XcodeObject | undefined;
+  /**
+   * Iterates `[id, view]` over every well-formed object in the document,
+   * in document order. Entries that are not dictionaries are skipped.
+   */
+  objects(): IterableIterator<[string, XcodeObject]>;
+  /**
+   * Generates a deterministic 24-character id from a seed, avoiding every
+   * id the document currently contains. The id is not reserved; adding an
+   * object with it (see {@link add}) is what claims it.
+   */
+  generateId(seed: string): string;
+  /**
+   * Adds an object to the document and returns its view.
+   *
+   * @param isa The object's kind; written as the `isa` property.
+   * @param properties The object's remaining properties. The dictionary is
+   *   stored as passed (not copied), with `isa` written first so the
+   *   serialized entry leads with it.
+   * @param seed Seed for the deterministic id; defaults to the isa, which
+   *   is only sensible for singleton objects.
+   * @returns The view of the created object.
+   */
+  add(isa: string, properties: PbxprojObject, seed?: string): XcodeObject;
+  /**
+   * The view of the document's root `PBXProject` object.
+   *
+   * @throws XcodeModelError when `rootObject` is missing or dangling,
+   *   since without it no project-level operation is meaningful.
+   */
+  get rootProject(): RootProject;
+  /**
+   * The views of the project's targets of every kind (native, aggregate,
+   * and legacy), in project order.
+   */
+  targets(): Target[];
+  /**
+   * The views of the project's native targets, in project order. Targets
+   * of other kinds (aggregate and legacy targets) are not included.
+   */
+  nativeTargets(): NativeTarget[];
+  /**
+   * Finds a native target by name.
+   */
+  findTarget(name: string): NativeTarget | undefined;
+  /**
+   * Finds the main application target for a platform. It prefers the
+   * application target whose own configurations carry the platform's
+   * deployment-target key, and falls back to the first application target
+   * in project order. Returns `undefined` when the project has no
+   * application target.
+   */
+  findMainAppTarget(platform?: ApplePlatform): NativeTarget | undefined;
+  /**
+   * Creates a native target with its build configurations, product file
+   * reference in the Products group, and the standard Sources, Frameworks,
+   * and Resources build phases, and registers it on the project.
+   *
+   * @throws XcodeModelError for product types the model cannot create a
+   *   product reference for; see {@link AddNativeTargetOptions.productType}.
+   */
+  addNativeTarget(options: AddNativeTargetOptions): NativeTarget;
+  /**
+   * Finds the remote Swift package reference for a repository URL.
+   */
+  findSwiftPackage(repositoryUrl: string): XcodeObject | undefined;
+  /**
+   * Adds a remote Swift package reference and registers it on the project.
+   * When the project already references the repository, the existing
+   * reference is returned unchanged, requirement included; adjust an
+   * existing requirement through the reference's properties. Link products
+   * to targets with {@link NativeTarget.addSwiftPackageProduct}.
+   *
+   * @param options.repositoryURL The package's git URL.
+   * @param options.requirement The version requirement dictionary as Xcode
+   *   stores it, for example
+   *   `{ kind: "upToNextMajorVersion", minimumVersion: "5.0.0" }`.
+   * @returns The view of the package reference for the repository.
+   */
+  addSwiftPackage(options: {
+    repositoryURL: string;
+    requirement: Record<string, string>;
+  }): XcodeObject;
+  /**
+   * Finds the local Swift package reference for a directory path.
+   */
+  findLocalSwiftPackage(relativePath: string): XcodeObject | undefined;
+  /**
+   * Adds a local (path-based) Swift package reference and registers it on
+   * the project, returning the existing reference when the path is already
+   * registered. Products link to targets the same way as remote packages,
+   * through {@link NativeTarget.addSwiftPackageProduct}.
+   *
+   * @param relativePath The package directory, relative to the project.
+   * @returns The view of the package reference for the path.
+   */
+  addLocalSwiftPackage(relativePath: string): XcodeObject;
+  /**
+   * The views of every `PBXBuildFile` that points at the referenced object
+   * through `fileRef` or `productRef`. Useful for relocating a product
+   * between copy phases.
+   */
+  buildFilesReferencing(reference: XcodeObject): XcodeObject[];
+  /**
+   * Validates the document's object graph and returns every problem
+   * found. An empty array means the graph is structurally sound. The
+   * checks cover the root object, object kinds, known references, and
+   * reachability.
+   */
+  validate(): ProjectIssue[];
+  /**
+   * Removes every object unreachable from the root object and returns the
+   * removed ids. Reachability is conservative. Any real reference keeps
+   * an object alive, even through properties outside the known schema.
+   */
+  pruneOrphans(): string[];
+  /**
+   * The views of every object that references the id anywhere in its
+   * properties. A reference is a string property naming the id, an id
+   * list containing it, or a nested dictionary carrying it as a key or
+   * string value.
+   *
+   * The scan is linear over the document; removal flows call it once per
+   * removed object, which keeps teardown proportional to what is actually
+   * removed.
+   */
+  referrersOf(id: string): XcodeObject[];
+  /**
+   * Removes an object from the document and strips every reference to it
+   * from the remaining objects. String properties naming the id are
+   * deleted, id lists drop it, and nested dictionaries keyed by object id
+   * (such as `TargetAttributes`) drop its entry.
+   *
+   * Removing an id the document does not contain is a no-op. This is the
+   * low-level removal; {@link removeTarget} composes it into a full
+   * teardown.
+   */
+  removeObject(id: string): void;
+  /**
+   * Removes a target and everything that exists only for its sake. That
+   * covers its build phases and their build files, its configuration list
+   * and configurations, its product reference and the build files
+   * embedding it, dependency objects and container proxies in both
+   * directions (other targets' dependencies on it, and its own
+   * dependencies on others), its membership exception sets, and
+   * synchronized folders no remaining target links.
+   *
+   * On-disk sources are untouched; the removal is document-only, like
+   * deleting a target in Xcode and keeping its folder.
+   *
+   * @throws XcodeModelError when the target belongs to another project,
+   *   since removing by another document's ids would tear down unrelated
+   *   objects that happen to share them.
+   */
+  removeTarget(target: Target): void;
+  /**
+   * Finds a file reference by its project-relative path, resolving each
+   * reference's location through the group tree from the main group
+   * (nested group `path` components join with `/`).
+   *
+   * Members of file-system-synchronized folders are not listed in the
+   * document and therefore cannot be found; check
+   * {@link NativeTarget.syncGroupPaths} for folder-level containment
+   * instead.
+   */
+  findFileReference(projectRelativePath: string): XcodeObject | undefined;
+  /**
+   * Creates the typed view for an object, dispatching on its isa. Objects
+   * outside the typed vocabulary get the generic base view.
+   */
+  private createView;
+}
+//#endregion
+//#region src/model/object.d.ts
+/**
+ * A typed handle on one object of the document.
+ *
+ * Two lookups of the same id return the same view instance (the project
+ * keeps an identity map), so views compare with `===`.
+ *
+ * The type parameter describes the properties of a well-formed object of
+ * this kind. Subclasses fix it to their kind's interface, which gives
+ * `properties` autocompletion. Treat the shape as a description rather
+ * than a guarantee. A malformed document can hold anything, so the model
+ * itself always reads through the narrowing accessors.
+ */
+declare class XcodeObject<Properties extends PbxprojObject = PbxprojObject> {
+  /** The project this object belongs to. */
+  readonly project: XcodeProject;
+  /** The object's 24-character identifier (its key in `objects`). */
+  readonly id: string;
+  /**
+   * Views are created by the project's identity map; use
+   * {@link XcodeProject.get} or a typed query instead of constructing
+   * views directly.
+   */
+  constructor(project: XcodeProject, id: string);
+  /**
+   * The object's raw dictionary inside the document. Mutations through the
+   * model write here, and direct writes are equally valid; the model adds
+   * no caching over these properties.
+   *
+   * The typed shape is asserted, not checked. It describes what a
+   * well-formed object of this kind carries (see `properties.ts`).
+   */
+  get properties(): Properties;
+  /**
+   * The object's `isa` kind name, or the empty string when the field is
+   * missing or malformed.
+   */
+  get isa(): string;
+  /**
+   * Reads a property expected to be a string. Returns `undefined` when the
+   * property is absent or holds another type.
+   */
+  getString(key: string): string | undefined;
+  /**
+   * Writes one property of the object.
+   *
+   * The write goes through the untyped document dictionary. TypeScript
+   * does not allow writes through a generic index, and the typed shape on
+   * `properties` is descriptive anyway.
+   */
+  set(key: string, value: PbxprojValue): void;
+  /**
+   * The views of the objects referenced by an id-list property, resolved in
+   * list order. Dangling ids and non-string entries of malformed documents
+   * are skipped.
+   */
+  protected referencedViews(key: string): XcodeObject[];
+  /**
+   * Removes the object from the document and strips every reference to it:
+   * string properties naming the id are deleted, id lists drop it, and
+   * nested dictionaries keyed by object id (such as the root project's
+   * `TargetAttributes`) drop its entry.
+   *
+   * This is the low-level removal; it does not cascade to objects that only
+   * made sense alongside this one. Higher-level operations like
+   * {@link XcodeProject.removeTarget} compose it into full teardowns.
+   */
+  removeFromProject(): void;
+}
+//#endregion
 //#region src/parse.d.ts
 /**
  * Parses a `project.pbxproj` document into JavaScript values.
@@ -152,4 +1245,31 @@ declare class PbxprojBuildError extends Error {
  */
 declare function parsePbxproj(text: string): PbxprojValue;
 //#endregion
-export { type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, buildPbxproj, parsePbxproj };
+//#region src/uuid.d.ts
+/**
+ * Deterministic object identifiers for generated pbxproj objects.
+ *
+ * Xcode identifies every object with 24 hexadecimal characters. Generated
+ * ids here are deterministic: the same seed always produces the same id, so
+ * programmatic edits are reproducible and diffs stay minimal across runs.
+ * The format is `XX` + the first 20 characters of `md5(seed)` + `XX`, which
+ * is a valid identifier that remains recognizable as generated.
+ *
+ * @module
+ */
+/**
+ * Generates a deterministic 24-character object id from a seed string.
+ *
+ * When the id already exists in `existing`, the seed is retried with a
+ * space appended until it is free, so ids stay deterministic (the same
+ * seeds in the same order produce the same ids) while never colliding
+ * within a document.
+ *
+ * @param seed Any text that identifies the object being created, for
+ *   example `PBXNativeTarget DemoWidget`.
+ * @param existing Ids already present in the document.
+ * @returns An id not contained in `existing`; the caller records it.
+ */
+declare function generateObjectId(seed: string, existing: ReadonlySet<string>): string;
+//#endregion
+export { type AddNativeTargetOptions, AggregateTarget, type ApplePlatform, type BuildConfigurationProperties, type BuildFileProperties, BuildPhase, type BuildPhaseProperties, BuildRule, type BuildRuleProperties, type BuildSettings, type ConfigurationListProperties, type ContainerItemProxyProperties, CopyFilesDestination, type ExceptionSetProperties, type FileReferenceProperties, Group, type GroupProperties, Isa, LegacyTarget, type LegacyTargetProperties, NativeTarget, type NativeTargetProperties, type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, ProductType, type ProjectIssue, type ProjectIssueKind, ReferenceProxy, type ReferenceProxyProperties, RootProject, type RootProjectProperties, type SwiftPackageProductDependencyProperties, type SwiftPackageReferenceProperties, SyncRootGroup, type SyncRootGroupProperties, Target, type TargetDependencyProperties, type TargetProperties, VersionGroup, type VersionGroupProperties, XcodeModelError, XcodeObject, XcodeProject, buildPbxproj, generateObjectId, parsePbxproj };