@xcodekit/xcode 0.1.0 → 0.3.0

package/README.md

@@ -42,10 +42,18 @@ writeFileSync("project.pbxproj", output);
 
 Parse a `.pbxproj` string into a JSON-compatible object. Matches the output of `@bacons/xcode/json`'s `parse()`.
 
+```js
+const project = parse(readFileSync("project.pbxproj", "utf8"));
+```
+
 #### `build(project: object): string`
 
 Serialize a JSON object back to `.pbxproj` format. Produces byte-identical output to `@bacons/xcode/json`'s `build()`.
 
+```js
+writeFileSync("project.pbxproj", build(project));
+```
+
 #### `buildFromJSON(json: string): string`
 
 Same as `build()` but accepts `JSON.stringify(project)` directly. Faster because it avoids napi's recursive JS-to-Rust object marshalling.
@@ -64,32 +72,74 @@ const output = parseAndBuild(readFileSync("project.pbxproj", "utf8"));
 
 ### High-Level (XcodeProject)
 
-#### `XcodeProject.open(filePath: string): XcodeProject`
+#### `XcodeProject.open(filePath)` / `XcodeProject.fromString(content)`
 
-Open and parse a `.pbxproj` file from disk.
+Open from disk or parse from a string (e.g. content fetched over the network).
 
 ```js
 import { XcodeProject } from "@xcodekit/xcode";
 
+// From disk
 const project = XcodeProject.open("ios/MyApp.xcodeproj/project.pbxproj");
 
+// From string (no file on disk needed)
+const project = XcodeProject.fromString(pbxprojContent);
+
 // Properties
 project.archiveVersion; // 1
-project.objectVersion;  // 46
-project.filePath;       // the path it was opened from
+project.objectVersion; // 46
+project.filePath; // path if opened from disk, null if fromString
+project.mainGroupUuid; // root group UUID
 
 // Targets
 const targets = project.getNativeTargets(); // UUID[]
 const mainApp = project.findMainAppTarget("ios"); // UUID | null
+project.getTargetName(mainApp); // "MyApp"
+project.setTargetName(mainApp, "NewName");
 
 // Build settings
 project.getBuildSetting(targetUuid, "PRODUCT_BUNDLE_IDENTIFIER");
 project.setBuildSetting(targetUuid, "SWIFT_VERSION", "5.0");
 project.removeBuildSetting(targetUuid, "CODE_SIGN_IDENTITY");
 
+// Files & groups
+const fileUuid = project.addFile(project.mainGroupUuid, "Sources/App.swift");
+const groupUuid = project.addGroup(project.mainGroupUuid, "Features");
+const children = project.getGroupChildren(groupUuid);
+
+// Build phases
+const phase = project.ensureBuildPhase(targetUuid, "PBXSourcesBuildPhase");
+project.addBuildFile(phase, fileUuid);
+
+// Frameworks
+project.addFramework(targetUuid, "SwiftUI");
+
+// Create targets
+const widgetTarget = project.createNativeTarget(
+  "MyWidget",
+  "com.apple.product-type.app-extension",
+  "com.example.mywidget",
+);
+
+// Embed extension into host app
+project.addDependency(mainApp, widgetTarget);
+project.embedExtension(mainApp, widgetTarget);
+
+// Xcode 16+ file system sync groups
+project.addFileSystemSyncGroup(widgetTarget, "MyWidget");
+
+// Generic object access
+project.getObjectProperty(uuid, "path");
+project.setObjectProperty(uuid, "path", "new/path");
+const proxies = project.findObjectsByIsa("PBXContainerItemProxy");
+
+// Validation
+const orphans = project.findOrphanedReferences();
+// [{ referrerUuid, referrerIsa, property, orphanUuid }]
+
 // Serialize
 const pbxproj = project.toBuild(); // string
-const json = project.toJSON();     // object
+const json = project.toJSON(); // object
 
 // Write back to disk
 project.save();
@@ -98,46 +148,48 @@ project.save();
 const uuid = project.getUniqueId("my-seed-string"); // 24-char hex
 ```
 
+All `XcodeProject` methods operate in Rust — only primitive strings cross the JS/Rust boundary. This is the fastest path for project manipulation.
+
 ## Performance
 
 Benchmarked on Apple M4 Pro, Node.js v24. Median of 200 iterations.
 
 ### Parse
 
-| Fixture | Rust | TypeScript | Speedup |
-|---------|------|-----------|---------|
-| swift-protobuf (257 KB) | 3.7 ms | 43.5 ms | **11.6x** |
-| Cocoa-Application (166 KB) | 3.2 ms | 17.3 ms | **5.5x** |
-| AFNetworking (99 KB) | 1.8 ms | 6.6 ms | **3.8x** |
-| watch (48 KB) | 0.9 ms | 2.1 ms | **2.2x** |
-| project (19 KB) | 0.4 ms | 0.8 ms | **2.2x** |
+| Fixture                    | Rust   | TypeScript | Speedup   |
+| -------------------------- | ------ | ---------- | --------- |
+| swift-protobuf (257 KB)    | 3.7 ms | 43.5 ms    | **11.6x** |
+| Cocoa-Application (166 KB) | 3.2 ms | 17.3 ms    | **5.5x**  |
+| AFNetworking (99 KB)       | 1.8 ms | 6.6 ms     | **3.8x**  |
+| watch (48 KB)              | 0.9 ms | 2.1 ms     | **2.2x**  |
+| project (19 KB)            | 0.4 ms | 0.8 ms     | **2.2x**  |
 
 ### Round-Trip (parse + build)
 
-| Fixture | Rust | TypeScript | Speedup |
-|---------|------|-----------|---------|
-| swift-protobuf (257 KB) | 9.1 ms | 63.1 ms | **6.9x** |
-| Cocoa-Application (166 KB) | 8.0 ms | 22.2 ms | **2.8x** |
-| AFNetworking (99 KB) | 4.2 ms | 9.3 ms | **2.2x** |
-| watch (48 KB) | 2.1 ms | 2.7 ms | **1.3x** |
-| project (19 KB) | 0.8 ms | 1.0 ms | **1.2x** |
+| Fixture                    | Rust   | TypeScript | Speedup  |
+| -------------------------- | ------ | ---------- | -------- |
+| swift-protobuf (257 KB)    | 9.1 ms | 63.1 ms    | **6.9x** |
+| Cocoa-Application (166 KB) | 8.0 ms | 22.2 ms    | **2.8x** |
+| AFNetworking (99 KB)       | 4.2 ms | 9.3 ms     | **2.2x** |
+| watch (48 KB)              | 2.1 ms | 2.7 ms     | **1.3x** |
+| project (19 KB)            | 0.8 ms | 1.0 ms     | **1.2x** |
 
 ### parseAndBuild (zero marshalling)
 
-| Fixture | Rust | TypeScript | Speedup |
-|---------|------|-----------|---------|
-| swift-protobuf (257 KB) | 4.6 ms | 62.9 ms | **13.6x** |
-| Cocoa-Application (166 KB) | 3.8 ms | 22.0 ms | **5.8x** |
-| AFNetworking (99 KB) | 1.9 ms | 9.1 ms | **4.9x** |
-| watch (48 KB) | 0.9 ms | 2.6 ms | **2.8x** |
-| project (19 KB) | 0.4 ms | 1.0 ms | **2.7x** |
+| Fixture                    | Rust   | TypeScript | Speedup   |
+| -------------------------- | ------ | ---------- | --------- |
+| swift-protobuf (257 KB)    | 4.6 ms | 62.9 ms    | **13.6x** |
+| Cocoa-Application (166 KB) | 3.8 ms | 22.0 ms    | **5.8x**  |
+| AFNetworking (99 KB)       | 1.9 ms | 9.1 ms     | **4.9x**  |
+| watch (48 KB)              | 0.9 ms | 2.6 ms     | **2.8x**  |
+| project (19 KB)            | 0.4 ms | 1.0 ms     | **2.7x**  |
 
 ### Package Size
 
-| | @bacons/xcode | @xcodekit/xcode |
-|-|--------------|-------------------|
-| Unpacked | 1.1 MB | 559 KB |
-| Gzipped | ~400 KB | ~270 KB |
+|          | @bacons/xcode | @xcodekit/xcode |
+| -------- | ------------- | --------------- |
+| Unpacked | 1.1 MB        | 559 KB          |
+| Gzipped  | ~400 KB       | ~270 KB         |
 
 Run benchmarks yourself:
 
@@ -149,13 +201,13 @@ make bench-js     # Rust vs TypeScript head-to-head
 
 ## Choosing the Right Function
 
-| Use case | Function | Notes |
-|----------|----------|-------|
-| Parse only | `parse(text)` | 2-12x faster than TS |
-| Build from JS object | `build(obj)` | Fastest on large files (>100 KB) |
-| Build from JSON string | `buildFromJSON(json)` | Faster than `build()` on all sizes |
-| Full round-trip | `parseAndBuild(text)` | Fastest path, zero JS/Rust overhead |
-| Project manipulation | `XcodeProject.open()` | Stays in Rust, use `.toBuild()` to serialize |
+| Use case               | Function              | Notes                                        |
+| ---------------------- | --------------------- | -------------------------------------------- |
+| Parse only             | `parse(text)`         | 2-12x faster than TS                         |
+| Build from JS object   | `build(obj)`          | Fastest on large files (>100 KB)             |
+| Build from JSON string | `buildFromJSON(json)` | Faster than `build()` on all sizes           |
+| Full round-trip        | `parseAndBuild(text)` | Fastest path, zero JS/Rust overhead          |
+| Project manipulation   | `XcodeProject.open()` | Stays in Rust, use `.toBuild()` to serialize |
 
 ## Compatibility
 
@@ -168,11 +220,11 @@ make bench-js     # Rust vs TypeScript head-to-head
 
 ## Supported Platforms
 
-| Platform | Architecture |
-|----------|-------------|
-| macOS | arm64 (Apple Silicon), x64 (Intel) |
-| Linux | x64 (glibc), arm64 (glibc) |
-| Windows | x64 (MSVC) |
+| Platform | Architecture                       |
+| -------- | ---------------------------------- |
+| macOS    | arm64 (Apple Silicon), x64 (Intel) |
+| Linux    | x64 (glibc), arm64 (glibc)         |
+| Windows  | x64 (MSVC)                         |
 
 ## Development
 

package/index.d.ts

@@ -22,6 +22,8 @@ export declare function parseAndBuild(text: string): string
 export declare class XcodeProject {
   /** Open and parse a .pbxproj file from disk. */
   static open(filePath: string): XcodeProject
+  /** Parse a .pbxproj string into an XcodeProject (no file on disk needed). */
+  static fromString(content: string): XcodeProject
   /** Convert the project to a JSON-compatible object. */
   toJSON(): any
   /** Serialize the project back to .pbxproj format. */
@@ -51,4 +53,64 @@ export declare class XcodeProject {
   findMainAppTarget(platform?: string | undefined | null): string | null
   /** Generate a unique UUID. */
   getUniqueId(seed: string): string
+  /** Get the main group UUID. */
+  get mainGroupUuid(): string | null
+  /** Get children UUIDs of a group. */
+  getGroupChildren(groupUuid: string): Array<string>
+  /**
+   * Add a file reference to the project and a group.
+   * Returns the UUID of the new PBXFileReference.
+   */
+  addFile(groupUuid: string, path: string): string | null
+  /**
+   * Create a group and add it as a child of a parent group.
+   * Returns the UUID of the new PBXGroup.
+   */
+  addGroup(parentUuid: string, name: string): string | null
+  /**
+   * Add a build file to a build phase.
+   * Returns the UUID of the new PBXBuildFile.
+   */
+  addBuildFile(phaseUuid: string, fileRefUuid: string): string | null
+  /**
+   * Find or create a build phase for a target.
+   * Returns the UUID of the build phase.
+   */
+  ensureBuildPhase(targetUuid: string, phaseIsa: string): string | null
+  /**
+   * Add a framework to a target.
+   * Returns the UUID of the PBXBuildFile.
+   */
+  addFramework(targetUuid: string, frameworkName: string): string | null
+  /**
+   * Create a native target with Debug/Release configs, standard build phases, and product ref.
+   * Returns the UUID of the new PBXNativeTarget.
+   */
+  createNativeTarget(name: string, productType: string, bundleId: string): string | null
+  /**
+   * Add a dependency from one target to another.
+   * Returns the UUID of the PBXTargetDependency.
+   */
+  addDependency(targetUuid: string, dependsOnUuid: string): string | null
+  /**
+   * Embed an extension target into a host app target.
+   * Creates PBXCopyFilesBuildPhase with correct dstSubfolderSpec.
+   * Returns the UUID of the copy files build phase.
+   */
+  embedExtension(hostTargetUuid: string, extensionTargetUuid: string): string | null
+  /**
+   * Add a PBXFileSystemSynchronizedRootGroup to a target (Xcode 16+).
+   * Returns the UUID of the sync group.
+   */
+  addFileSystemSyncGroup(targetUuid: string, path: string): string | null
+  /** Get a string property from any object. */
+  getObjectProperty(uuid: string, key: string): string | null
+  /** Set a string property on any object. */
+  setObjectProperty(uuid: string, key: string, value: string): boolean
+  /** Find all object UUIDs matching a given ISA type. */
+  findObjectsByIsa(isa: string): Array<string>
+  /** Get the name of a target. */
+  getTargetName(targetUuid: string): string | null
+  /** Set the name and productName of a target. */
+  setTargetName(targetUuid: string, name: string): boolean
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcodekit/xcode",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Parse, manipulate, and serialize Xcode .pbxproj files — native Rust rewrite",
   "main": "index.js",
   "types": "index.d.ts",
@@ -16,11 +16,11 @@
   },
   "license": "MIT",
   "optionalDependencies": {
-    "@xcodekit/xcode-darwin-arm64": "0.1.0",
-    "@xcodekit/xcode-darwin-x64": "0.1.0",
-    "@xcodekit/xcode-linux-arm64-gnu": "0.1.0",
-    "@xcodekit/xcode-linux-x64-gnu": "0.1.0",
-    "@xcodekit/xcode-win32-x64-msvc": "0.1.0"
+    "@xcodekit/xcode-darwin-arm64": "0.3.0",
+    "@xcodekit/xcode-darwin-x64": "0.3.0",
+    "@xcodekit/xcode-linux-arm64-gnu": "0.3.0",
+    "@xcodekit/xcode-linux-x64-gnu": "0.3.0",
+    "@xcodekit/xcode-win32-x64-msvc": "0.3.0"
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.0",
@@ -44,7 +44,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/nickmozharovsky/xcode"
+    "url": "https://github.com/mozharovsky/xcode"
   },
   "keywords": [
     "xcode",