toggle-local-spm 2.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cf5e1291d028c334f9fd40a089700d1bba713a637b6def0a7b46fe9b970decc4
+  data.tar.gz: 6c8ee86f80b2a062f4949d07027781a5ce35f42ff7ad6c51e33f0a4a1efb86df
+SHA512:
+  metadata.gz: 2c5fd4f849cbdf6280e5bba06cd9839b64c6aa4b4ddb52eef40c43b7b1a41bc6328ce1f978152c814f3d35a9750a27ccc36b3ec118b48c53ac333e6832e90def
+  data.tar.gz: 14a34f2964b727573e5f45197d71cb62a94a2a6b00447f2e5eaf696fa9fabe25b03dc8e2bcf29a5575a26f30ab1838ee0d3c0abd5ae42f025d62426122f58a8e

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sushant Verma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,320 @@
+# toggle-local-spm
+
+[![Tests](https://github.com/squeaky-nose/toggle-local-spm/actions/workflows/tests.yml/badge.svg)](https://github.com/squeaky-nose/toggle-local-spm/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/squeaky-nose/toggle-local-spm/graph/badge.svg?token=0SUUH3UPIQ)](https://codecov.io/gh/squeaky-nose/toggle-local-spm)
+[![Gem Version](https://badge.fury.io/rb/toggle-local-spm.svg)](https://rubygems.org/gems/toggle-local-spm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A CLI that toggles Swift Package Manager dependencies in an Xcode project
+between their remote (git) reference and a local checkout in a sibling
+folder — useful when developing a package alongside the app that consumes
+it. This works both for packages the project depends on directly, and for
+packages only pulled in transitively (a dependency of one of the project's
+own dependencies) — see **Direct vs. indirect dependencies** below.
+
+Run it on a package and it swaps the remote reference for a local one. Run
+it again on the same package and it swaps back to the original remote
+reference. It edits `project.pbxproj` directly (via the [xcodeproj][xcodeproj]
+gem) and, for a direct dependency, reuses the existing package reference's
+object ID when swapping, so the diff it produces is minimal and easy to
+review — only the swapped reference's `isa`/attributes change, nothing else
+in the file churns.
+
+[xcodeproj]: https://github.com/CocoaPods/Xcodeproj
+
+## Requirements
+
+- Run from the root of the Xcode project's repo — the directory containing
+  the `.xcodeproj` (there must be exactly one there).
+- The first time you swap a package to local, its checkout is expected to be
+  an adjacent sibling directory, named to match the package's repo (e.g. if
+  the project depends on `git@github.com:org/some-package.git`, this tool
+  looks for `../some-package` containing a `Package.swift`). After that,
+  where it looks is whatever `spm-local-overrides.json` says — see below.
+- macOS with Xcode installed (`xcodebuild` is used to re-resolve
+  `Package.resolved` after swapping).
+- A `Package.resolved` that's already been generated at least once (needed to
+  discover indirect dependencies — see below). If there isn't one yet, only
+  direct dependencies are toggleable until one exists.
+
+## Installation
+
+Add this to the consuming project's `Gemfile`:
+
+```ruby
+gem "toggle-local-spm"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+(Pin a version range, e.g. `gem "toggle-local-spm", "~> 2.0"`, if you want
+more control over upgrades — see [Releasing a new version](#releasing-a-new-version)
+for how versions are cut.)
+
+## Usage
+
+From the root of the Xcode project's repo:
+
+```bash
+# Toggle one package by name (matched against its repo/folder name)
+bundle exec toggle-local-spm some-package
+
+# Toggle several packages in one go
+bundle exec toggle-local-spm some-package another-package
+
+# Or with no arguments, pick from an interactive menu of every package
+# dependency in the project (space/comma-separated numbers for more than one)
+bundle exec toggle-local-spm
+```
+
+The interactive menu lists every direct dependency (from the project itself)
+and every indirect one (from `Package.resolved`) as a table, each tagged with
+its type, current state, and whether it has a record in
+`spm-local-overrides.json` (see below), e.g.:
+
+```
+  #  Package                        Type        State     Managed
+  1  mob-bifrost-ios                🎯 direct    🌏 remote  ✅
+  2  DeviceKit                      🎯 direct    🌏 remote
+  3  mob-redtail-widgets-generator  🧩 indirect  🌏 remote
+```
+
+Each package toggles independently based on what's currently wired up in the
+project: a package currently on its remote reference (or, for an indirect
+dependency, not yet overridden at all) swaps to local; a package currently
+on a local reference swaps back to remote.
+
+Before touching `project.pbxproj`, if Xcode is currently running you'll be
+asked how to handle it — Xcode holding the project open can silently
+overwrite the file while this tool is editing it:
+
+```
+Xcode is currently running, which can overwrite project.pbxproj while it's being edited.
+  1) I'll close it myself
+  2) Do nothing, proceed anyway
+  3) Close Xcode for me
+```
+
+Option 1 waits for you to close it and press Enter; option 3 quits Xcode for
+you (a normal quit — Xcode will still prompt you to save anything unsaved).
+
+After the swap(s), you'll be prompted:
+
+```
+Resolve package dependencies now? [Y/n]
+```
+
+Press enter (or `y`) to run `xcodebuild -resolvePackageDependencies` and
+refresh `Package.resolved` immediately, or `n` to skip it and resolve later
+yourself (e.g. via Xcode's **File > Packages > Resolve Package Versions**).
+If resolution fails (no network, no SSH key for a private repo, etc.) it
+prints a warning — the `project.pbxproj` swap itself has already succeeded
+either way. Finally:
+
+```
+Open in Xcode now? [Y/n]
+```
+
+Press enter (or `y`) to open the project (the `.xcworkspace` if there is
+one, otherwise the `.xcodeproj`) — handy for picking up right where the
+"close Xcode for me" option above left off, with a freshly-resolved project.
+
+## Direct vs. indirect dependencies
+
+A **direct** dependency already has (or had) its own top-level entry in the
+project's "Package Dependencies" list (`project.pbxproj`'s
+`XCRemoteSwiftPackageReference`/`XCLocalSwiftPackageReference` entries).
+Toggling one off always leaves a reference behind — swapped back to remote —
+since the project genuinely, permanently depends on it.
+
+An **indirect** dependency has no such entry — it's only known because it
+shows up in `Package.resolved`, meaning some *other* dependency's own
+`Package.swift` depends on it (e.g. `mob-bifrost-ios` depending on
+`mob-redtail-widgets-generator`). Toggling one of these on doesn't edit that
+other package's `Package.swift` at all. Instead it adds a brand-new,
+*unlinked* local package reference directly to the project — not attached to
+any target — purely so Xcode/SwiftPM's identity-based dependency resolution
+overrides the transitive reference with the local checkout, wherever else in
+the graph it's declared. Toggling it back off removes that reference
+entirely, since it was never a real dependency of the project — it was only
+ever an override anchor.
+
+> [!NOTE]
+> This relies on SwiftPM allowing two different sources (a remote pin from a
+> transitive `Package.swift`, and a local override elsewhere in the same
+> graph) to share one package identity, silently preferring the local one.
+> This works today, but SwiftPM's own resolver logs it as a *"Conflicting
+> identity"* warning and states plainly that **this will be escalated to an
+> error in future versions of SwiftPM**. If a future Xcode/SwiftPM version
+> makes this a hard error, indirect-dependency overrides via this tool will
+> stop working and need a different approach (e.g. editing the declaring
+> package's `Package.swift` directly).
+
+## `spm-local-overrides.json`
+
+The first time you swap any package to local, this tool creates
+`spm-local-overrides.json` at the repo root. It's a permanent, per-developer
+record of every package it has ever touched — created once and never
+deleted, and entries are only ever added to or updated, never removed (even
+after a package is swapped back to remote, or an indirect override is
+removed). Whether a package is currently "on" (local) or "off" (remote) is
+**not** read from this file — it's determined by inspecting the project
+itself (is there a reference for it, and is it an
+`XCRemoteSwiftPackageReference` or an `XCLocalSwiftPackageReference`?). This
+file only ever supplies the *details* needed to perform a swap.
+
+Each entry looks like:
+
+```json
+{
+  "some-package": {
+    "repositoryURL": "git@github.com:org/some-package.git",
+    "requirement": { "kind": "exactVersion", "version": "1.2.3" },
+    "localPath": "/Users/you/code/some-package",
+    "type": "direct"
+  }
+}
+```
+
+- `repositoryURL` / `requirement` — the package's remote reference, captured
+  automatically the first time it's swapped to local (from the project
+  itself for a direct dependency, or from `Package.resolved` for an indirect
+  one). Used to restore the exact same remote reference when swapping a
+  direct dependency back; recorded for indirect dependencies too but not
+  strictly needed to turn one off (that just removes the reference).
+- `type` — `"direct"` or `"indirect"`, set automatically the first time a
+  package is toggled (see above). Missing `type` on an older entry is
+  treated as `"direct"`.
+- `localPath` — where the local checkout lives. Set automatically to the
+  default sibling folder the first time you swap a package to local. **Edit
+  this by hand** if your checkout lives somewhere else, or under a different
+  name — the next swap-to-local for that package will use whatever path is
+  here instead of guessing a sibling folder.
+
+This file is specific to your machine (it records absolute local paths), so
+it should stay out of version control — add `spm-local-overrides.json` to
+the consuming project's `.gitignore`.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can
+also run `bin/console` for an interactive prompt that will allow you to
+experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Tests and coverage
+
+`bundle exec rake test` runs the suite (also the default Rake task) and
+writes:
+
+- A coverage report to `coverage/` via [SimpleCov][simplecov] —
+  `coverage/index.html` for a local human-readable view,
+  `coverage/coverage.json` for Codecov's coverage reporting to ingest.
+- JUnit XML test results to `test/reports/` via [minitest-reporters][minitest-reporters].
+
+CI ([.github/workflows/tests.yml](.github/workflows/tests.yml)) runs the
+same suite on every push to `main` and every PR, then:
+
+- Uploads coverage to Codecov via `codecov/codecov-action`.
+- Publishes the JUnit XML as GitHub check annotations and a job summary
+  via [mikepenz/action-junit-report][action-junit-report] (with
+  `detailed_summary`/`include_passed` so every individual test case shows,
+  not just failures) — per-test pass/fail shows up directly on the
+  commit/PR's checks and in the workflow run's summary tab, no external
+  service needed. (We also tried reporting test results to Codecov's Test
+  Analytics via `report_type: test_results`; every upload consistently
+  logged success but never appeared anywhere in Codecov's UI even after
+  ruling out XML format, plan/visibility gating, and branch-config
+  mismatches — looks like a gap on their end, not something fixable from
+  this workflow. Filed with Codecov support; worth revisiting later.)
+- Uploads both reports as a downloadable build artifact
+  (`test-reports`), for whenever a run needs deeper debugging.
+
+Both the coverage upload and the check-annotations step run even if the
+test step itself fails (`if: ${{ !cancelled() }}`), since a failing run is
+exactly what you want visibility into.
+
+Codecov needs one manual, one-time setup step that isn't in this diff: add
+the repo at [codecov.io](https://codecov.io) (sign in with GitHub, enable
+the org/repo), then copy its **upload token** and add it as a repo secret
+named `CODECOV_TOKEN` (Settings → Secrets and variables → Actions).
+
+[simplecov]: https://github.com/simplecov-ruby/simplecov
+[minitest-reporters]: https://github.com/minitest-reporters/minitest-reporters
+[action-junit-report]: https://github.com/mikepenz/action-junit-report
+
+## Releasing a new version
+
+The [Release workflow](.github/workflows/release.yml) automates the whole
+process, including publishing to RubyGems.org:
+
+1. Go to the repo's **Actions** tab → **Release** → **Run workflow**.
+2. Enter the new version as bare `x.y.z` (no `v` prefix — the workflow adds
+   it when constructing the tag, e.g. entering `2.3.0` produces `v2.3.0`).
+3. Run it.
+
+On a fresh runner, the workflow then:
+
+- Validates the input matches `x.y.z` and that the tag doesn't already exist
+  (refusing to overwrite an existing release).
+- Bumps `lib/toggle_local_spm/version.rb`.
+- Regenerates `Gemfile.lock` (`bundle install`) so its `PATH` section
+  matches the new version — CI's `bundler-cache: true` step in
+  [tests.yml](.github/workflows/tests.yml) installs in frozen mode and will
+  hard-fail if this drifts.
+- Runs `bundle exec rake test` as a safety gate — nothing is committed,
+  tagged, published, or released if the suite fails.
+- Commits as "Bump version to X.Y.Z", tags it `vX.Y.Z`, and pushes both to
+  `main`.
+- Creates a GitHub Release for the tag via `gh release create --generate-notes`.
+- Publishes the gem to [RubyGems.org](https://rubygems.org/gems/toggle-local-spm)
+  via [Trusted Publishing][trusted-publishing] (OIDC — no stored API key).
+
+Consumers just run `bundle update toggle-local-spm` to pick up a new
+version.
+
+[trusted-publishing]: https://guides.rubygems.org/trusted-publishing/
+
+### One-time setup
+
+RubyGems.org Trusted Publishing needs a "pending trusted publisher"
+registered once, before the *first* release, at
+[rubygems.org/profile/oidc/pending_trusted_publishers](https://rubygems.org/profile/oidc/pending_trusted_publishers):
+
+- Gem name: `toggle-local-spm`
+- Repository owner / name: `squeaky-nose` / `toggle-local-spm`
+- Workflow filename: `release.yml`
+- Environment: `release`
+
+After the first successful publish, RubyGems.org converts this from
+"pending" to a normal trusted publisher automatically — no further setup
+needed for later releases.
+
+**Manual fallback** (e.g. the workflow is unavailable, or `main`'s branch
+protection blocks the workflow's token from pushing):
+
+1. Bump the version in `lib/toggle_local_spm/version.rb`.
+2. Run `bundle install` to regenerate `Gemfile.lock`.
+3. Run `bundle exec rake test`.
+4. Commit as "Bump version to X.Y.Z", then `git tag vX.Y.Z`.
+5. `git push origin main && git push origin vX.Y.Z`.
+6. Create a release from the pushed tag: `gh release create vX.Y.Z --generate-notes`
+   (or via the GitHub UI's Releases page).
+7. Publish the gem: `gem build toggle-local-spm.gemspec && gem push toggle-local-spm-X.Y.Z.gem`
+   (needs a RubyGems.org API key with push access on your machine, since
+   Trusted Publishing only works from the configured GitHub Actions workflow).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/squeaky-nose/toggle-local-spm.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+# minitest-reporters' JUnitReporter writes tests/failures/errors/time onto
+# each <testsuite>, but never onto the enclosing <testsuites> root — Codecov
+# Test Analytics requires those on the root element too, so copy them up.
+desc "Add root-level summary attributes to JUnit XML reports for Codecov Test Analytics"
+task :fix_junit_reports do
+  require "rexml/document"
+
+  Dir.glob("test/reports/TEST-*.xml").each do |path|
+    doc = REXML::Document.new(File.read(path))
+    suite = doc.root&.elements&.[]("testsuite")
+    next unless suite
+
+    %w[tests failures errors time].each do |attr|
+      doc.root.attributes[attr] = suite.attributes[attr]
+    end
+
+    File.write(path, doc.to_s)
+  end
+end
+
+Rake::Task["test"].enhance do
+  Rake::Task["fix_junit_reports"].invoke
+end
+
+task default: :test

data/exe/toggle-local-spm

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "toggle_local_spm"
+
+begin
+  ToggleLocalSpm::CLI.run(ARGV)
+rescue ToggleLocalSpm::Error => e
+  warn "error: #{e.message}"
+  exit 1
+end

data/lib/toggle_local_spm/cli.rb

@@ -0,0 +1,477 @@
+# frozen_string_literal: true
+
+require "xcodeproj"
+require "json"
+require "pathname"
+
+module ToggleLocalSpm
+  # Toggles one or more Swift Package Manager dependencies between their
+  # remote (git) reference and a local checkout. Run again on the same
+  # package to swap back to the original remote reference. Afterwards,
+  # optionally runs `xcodebuild -resolvePackageDependencies` so
+  # Package.resolved is updated to match (requires network access and, for
+  # private repos, a working SSH key).
+  #
+  # Run from the root of the Xcode project's repo (the directory containing
+  # the .xcodeproj). A `spm-local-overrides.json` file is kept at the repo
+  # root as a permanent record of each package's remote reference and local
+  # checkout path (see README).
+  #
+  # Packages come in two flavors:
+  # - "direct": already has (or had) a top-level XCRemoteSwiftPackageReference/
+  #   XCLocalSwiftPackageReference entry in project.pbxproj. Toggling off
+  #   always leaves a reference behind (swapped back to remote) since the
+  #   project genuinely depends on it.
+  # - "indirect": only known via Package.resolved — a transitive dependency
+  #   of one of the project's own direct dependencies (e.g. a package
+  #   declared in another package's own Package.swift), with no top-level
+  #   reference of its own. Toggling one of these on adds a brand-new,
+  #   unlinked local reference (no product/target linkage) purely so
+  #   SwiftPM's identity-based graph resolution overrides the transitive
+  #   pin with the local checkout; toggling off removes that reference
+  #   entirely, since it was never a real project dependency.
+  #
+  # Which of these two states a package is in is recorded as "type" in
+  # spm-local-overrides.json. Whether it's currently local or remote is
+  # always read from the live project (an existing ref's isa, or its
+  # absence for a not-yet-toggled indirect package) — never from the state
+  # file or from Package.resolved, which can lag behind.
+  class CLI
+    RemoteRef = Xcodeproj::Project::Object::XCRemoteSwiftPackageReference
+    LocalRef = Xcodeproj::Project::Object::XCLocalSwiftPackageReference
+    ProductDependency = Xcodeproj::Project::Object::XCSwiftPackageProductDependency
+
+    Candidate = Struct.new(:name, :ref, :type, :resolved_entry, :managed) do
+      def local?
+        ref.is_a?(LocalRef)
+      end
+    end
+
+    TYPE_LABELS = { "direct" => "🎯 direct", "indirect" => "🧩 indirect" }.freeze
+    STATE_LABELS = { local: "📁 local", remote: "🌏 remote" }.freeze
+
+    def self.run(argv)
+      new(argv).run
+    end
+
+    def initialize(argv, root: Dir.pwd)
+      @package_names = argv
+      @root = Pathname.new(root).expand_path
+      @state_file = @root + "spm-local-overrides.json"
+    end
+
+    def run
+      xcodeproj_path = find_xcodeproj_path
+      project = Xcodeproj::Project.open(xcodeproj_path)
+      state = load_state
+
+      candidates = build_candidates(project, xcodeproj_path, state)
+      abort_with("no Swift package dependencies found") if candidates.empty?
+
+      selected = select_candidates(candidates)
+
+      check_xcode_running
+
+      selected.each { |candidate| toggle(project, xcodeproj_path, candidate, state) }
+
+      save_state(state)
+      project.save
+
+      resolve_package_dependencies(xcodeproj_path) if prompt_resolve?
+      open_in_xcode(xcodeproj_path) if prompt_open_in_xcode?
+
+      puts "Done."
+    end
+
+    private
+
+    def abort_with(message)
+      raise Error, message
+    end
+
+    def find_xcodeproj_path
+      candidates = Dir.glob(@root + "*.xcodeproj")
+      abort_with("no .xcodeproj found in #{@root}") if candidates.empty?
+      abort_with("multiple .xcodeproj found in #{@root}, expected one: #{candidates.join(", ")}") if candidates.size > 1
+      Pathname.new(candidates.first)
+    end
+
+    def find_workspace_path
+      candidates = Dir.glob(@root + "*.xcworkspace")
+      candidates.first && Pathname.new(candidates.first)
+    end
+
+    def load_state
+      return {} unless @state_file.exist?
+
+      JSON.parse(@state_file.read)
+    rescue JSON::ParserError => e
+      abort_with("could not parse #{@state_file}: #{e.message}")
+    end
+
+    # The state file is a permanent record: it is created on first use and
+    # never deleted, and entries are only ever added to or updated, never
+    # removed — even after a package is swapped back to remote (or an
+    # indirect override is removed). This lets a developer hand-edit a
+    # package's "localPath" without losing the recorded repositoryURL/
+    # requirement, and preserves "type" so a package's direct/indirect
+    # classification is stable across runs.
+    def save_state(state)
+      @state_file.write(JSON.pretty_generate(state) + "\n")
+    end
+
+    def ref_name(ref)
+      case ref
+      when RemoteRef
+        File.basename(ref.repositoryURL.to_s, ".git")
+      when LocalRef
+        File.basename(ref.relative_path.to_s)
+      end
+    end
+
+    def product_dependencies_for(project, ref)
+      project.objects.select { |o| o.is_a?(ProductDependency) && o.package == ref }
+    end
+
+    # Replaces `old_ref` with a new package reference of `new_ref_class`, reusing
+    # old_ref's UUID and its position in packageReferences. This keeps every
+    # `package = <uuid>` line in XCSwiftPackageProductDependency untouched (only
+    # the referenced object's isa/attributes change), so toggling produces a
+    # minimal, easy-to-review diff instead of churning UUIDs.
+    def replace_ref(project, old_ref, new_ref_class)
+      deps = product_dependencies_for(project, old_ref)
+      package_references = project.root_object.package_references
+      index = package_references.index(old_ref)
+      uuid = old_ref.uuid
+
+      # Detach old_ref from every referrer first so its UUID is freed from
+      # objects_by_uuid before the new object claims that same UUID below.
+      deps.each { |dep| dep.package = nil }
+      package_references.delete(old_ref)
+
+      new_ref = new_ref_class.new(project, uuid)
+      new_ref.initialize_defaults
+      yield new_ref
+
+      package_references.insert(index, new_ref)
+      deps.each { |dep| dep.package = new_ref }
+
+      new_ref
+    end
+
+    # --- Candidate discovery ---------------------------------------------
+
+    def build_candidates(project, xcodeproj_path, state)
+      refs = project.root_object.package_references.select { |r| r.is_a?(RemoteRef) || r.is_a?(LocalRef) }
+      direct = refs.map do |ref|
+        name = ref_name(ref)
+        type = state.dig(name, "type") || "direct"
+        Candidate.new(name, ref, type, nil, state.key?(name))
+      end
+
+      resolved = load_resolved_packages(xcodeproj_path)
+      indirect = resolved.reject { |name, _| direct.any? { |c| c.name.casecmp(name).zero? } }
+                          .map { |name, info| Candidate.new(name, nil, "indirect", info, state.key?(name)) }
+
+      direct + indirect
+    end
+
+    def resolved_file_path(xcodeproj_path)
+      workspace = find_workspace_path
+      if workspace
+        workspace + "xcshareddata/swiftpm/Package.resolved"
+      else
+        xcodeproj_path + "project.xcworkspace/xcshareddata/swiftpm/Package.resolved"
+      end
+    end
+
+    def load_resolved_packages(xcodeproj_path)
+      path = resolved_file_path(xcodeproj_path)
+      return {} unless path.exist?
+
+      json = JSON.parse(path.read)
+      pins = json["pins"] || json.dig("object", "pins") || []
+      pins.each_with_object({}) do |pin, acc|
+        location = pin["location"] || pin["repositoryURL"]
+        next unless location
+
+        name = File.basename(location, ".git")
+        acc[name] = { "repositoryURL" => location, "requirement" => requirement_from_resolved_state(pin["state"] || {}) }
+      end
+    rescue JSON::ParserError
+      {}
+    end
+
+    def requirement_from_resolved_state(resolved_state)
+      if resolved_state["version"]
+        { "kind" => "exactVersion", "version" => resolved_state["version"] }
+      elsif resolved_state["branch"]
+        { "kind" => "branch", "branch" => resolved_state["branch"] }
+      elsif resolved_state["revision"]
+        { "kind" => "revision", "revision" => resolved_state["revision"] }
+      end
+    end
+
+    # --- Selection ----------------------------------------------------------
+
+    def find_candidate(candidates, wanted)
+      match = candidates.find { |c| c.name.casecmp(wanted).zero? }
+      return match if match
+
+      names = candidates.map(&:name).sort
+      abort_with("no package dependency named '#{wanted}'. Available: #{names.join(", ")}")
+    end
+
+    def select_candidates(candidates)
+      return @package_names.map { |wanted| find_candidate(candidates, wanted) }.uniq if @package_names.any?
+
+      select_candidates_interactively(candidates)
+    end
+
+    def select_candidates_interactively(candidates)
+      puts "Select package dependencies to toggle (e.g. 1, or 1 3):"
+      puts
+
+      index_width = candidates.size.to_s.length
+      name_width = candidates.map { |c| c.name.length }.max
+      type_width = TYPE_LABELS.values.map(&:length).max
+      state_width = STATE_LABELS.values.map(&:length).max
+
+      puts "  #{"#".rjust(index_width)}  #{"Package".ljust(name_width)}  #{"Type".ljust(type_width)}  " \
+           "#{"State".ljust(state_width)}  Managed"
+      candidates.each_with_index do |c, i|
+        type_label = TYPE_LABELS.fetch(c.type, c.type).ljust(type_width)
+        state_label = STATE_LABELS[c.local? ? :local : :remote].ljust(state_width)
+        managed_label = c.managed ? "✅" : ""
+        puts "  #{(i + 1).to_s.rjust(index_width)}  #{c.name.ljust(name_width)}  #{type_label}  #{state_label}  #{managed_label}"
+      end
+
+      print "\n> "
+      choice = $stdin.gets&.strip
+      abort_with("invalid selection") if choice.nil? || choice.empty?
+
+      tokens = choice.split(/[\s,]+/)
+      abort_with("invalid selection '#{choice}'") unless tokens.all? { |t| t.match?(/\A\d+\z/) }
+
+      tokens.map(&:to_i).map do |n|
+        index = n - 1
+        abort_with("invalid selection '#{n}'") unless index.between?(0, candidates.size - 1)
+        candidates[index]
+      end.uniq
+    end
+
+    # --- Toggling -------------------------------------------------------
+
+    def toggle(project, xcodeproj_path, candidate, state)
+      if candidate.local?
+        if candidate.type == "indirect"
+          remove_indirect_ref(project, candidate)
+        else
+          swap_local_to_remote(project, xcodeproj_path, candidate.ref, state)
+        end
+      elsif candidate.ref.nil?
+        add_indirect_local_ref(project, xcodeproj_path, candidate, state)
+      else
+        swap_remote_to_local(project, xcodeproj_path, candidate.ref, state)
+      end
+    end
+
+    def resolve_local_dir(entry, name)
+      local_dir = entry["localPath"] ? Pathname.new(entry["localPath"]).expand_path(@root) : (@root.parent + name)
+      unless local_dir.directory? && (local_dir + "Package.swift").file?
+        abort_with("expected a local checkout with a Package.swift at #{local_dir} " \
+                   "(set or fix \"localPath\" for '#{name}' in #{@state_file} if it lives elsewhere)")
+      end
+      local_dir
+    end
+
+    def swap_remote_to_local(project, xcodeproj_path, ref, state)
+      name = ref_name(ref)
+      entry = state[name] || {}
+      local_dir = resolve_local_dir(entry, name)
+      relative_path = local_dir.relative_path_from(xcodeproj_path.dirname).to_s
+
+      state[name] = entry.merge(
+        "repositoryURL" => ref.repositoryURL,
+        "requirement" => ref.requirement,
+        "localPath" => local_dir.to_s,
+        "type" => "direct"
+      )
+
+      replace_ref(project, ref, LocalRef) { |local_ref| local_ref.relative_path = relative_path }
+
+      puts "Swapped '#{name}' to local checkout at #{relative_path} (kept resource id #{ref.uuid})"
+    end
+
+    def swap_local_to_remote(project, xcodeproj_path, ref, state)
+      name = ref_name(ref)
+      entry = state[name]
+      unless entry && entry["repositoryURL"] && entry["requirement"]
+        abort_with("no recorded remote reference for '#{name}' in #{@state_file}. " \
+                    "Add \"repositoryURL\"/\"requirement\" for it manually, or restore project.pbxproj from git.")
+      end
+
+      # Backfill localPath in case this entry was created/edited by hand
+      # without one, so the record stays complete going forward.
+      entry["localPath"] ||= (xcodeproj_path.dirname + ref.relative_path).expand_path.to_s
+      entry["type"] = "direct"
+
+      replace_ref(project, ref, RemoteRef) do |remote_ref|
+        remote_ref.repositoryURL = entry["repositoryURL"]
+        remote_ref.requirement = entry["requirement"]
+      end
+
+      puts "Swapped '#{name}' back to remote reference #{entry["repositoryURL"]} (kept resource id #{ref.uuid})"
+    end
+
+    # Adds a brand-new, unlinked local reference for an indirect (transitive)
+    # dependency. New UUID, since there's no existing ref to reuse one from.
+    # Not wired into any target's product dependencies — its mere presence
+    # in packageReferences is enough for SwiftPM to unify the identity with
+    # the local checkout wherever else in the graph it's referenced
+    # (verified: it overrides the transitive pin even when the package that
+    # actually declares the dependency, e.g. mob-bifrost-ios, stays remote).
+    def add_indirect_local_ref(project, xcodeproj_path, candidate, state)
+      name = candidate.name
+      entry = state[name] || {}
+      local_dir = resolve_local_dir(entry, name)
+      relative_path = local_dir.relative_path_from(xcodeproj_path.dirname).to_s
+
+      repository_url = entry["repositoryURL"] || candidate.resolved_entry["repositoryURL"]
+      requirement = entry["requirement"] || candidate.resolved_entry["requirement"]
+
+      new_ref = LocalRef.new(project, project.generate_uuid)
+      new_ref.initialize_defaults
+      new_ref.relative_path = relative_path
+      project.root_object.package_references << new_ref
+
+      state[name] = entry.merge(
+        "repositoryURL" => repository_url,
+        "requirement" => requirement,
+        "localPath" => local_dir.to_s,
+        "type" => "indirect"
+      )
+
+      puts "Added local override for '#{name}' (indirect dependency) at #{relative_path} (new resource id #{new_ref.uuid})"
+    end
+
+    def remove_indirect_ref(project, candidate)
+      ref = candidate.ref
+      product_dependencies_for(project, ref).each { |dep| dep.package = nil }
+      project.root_object.package_references.delete(ref)
+
+      puts "Removed local override for '#{candidate.name}' (indirect dependency)"
+    end
+
+    # Xcode holding the project open can silently overwrite project.pbxproj
+    # out from under us (observed in practice: Xcode periodically re-saves
+    # its in-memory state to disk). Ask before we touch the file.
+    def check_xcode_running
+      return unless xcode_running?
+
+      puts "Xcode is currently running, which can overwrite project.pbxproj while it's being edited."
+      puts "  1) I'll close it myself"
+      puts "  2) Do nothing, proceed anyway"
+      puts "  3) Close Xcode for me"
+      print "> "
+      choice = $stdin.gets&.strip
+
+      case choice
+      when "1"
+        print "Close Xcode, then press Enter to continue... "
+        $stdin.gets
+        warn "warning: Xcode still appears to be running." if xcode_running?
+      when "3"
+        run_command("osascript", "-e", 'tell application "Xcode" to quit')
+        wait_for_xcode_to_quit
+      when "2"
+        nil
+      else
+        abort_with("invalid selection")
+      end
+    end
+
+    def xcode_running?
+      run_command("pgrep", "-x", "Xcode", out: File::NULL, err: File::NULL)
+    end
+
+    # Thin wrapper around Kernel#system so every shell-out point in this
+    # class can be stubbed from one place in tests, instead of each needing
+    # its own indirection.
+    def run_command(*args)
+      system(*args)
+    end
+
+    # Overridable so tests can shrink these without a real 10-second wait.
+    def xcode_quit_timeout
+      10
+    end
+
+    def xcode_quit_poll_interval
+      0.5
+    end
+
+    def wait_for_xcode_to_quit
+      deadline = Time.now + xcode_quit_timeout
+      sleep xcode_quit_poll_interval while xcode_running? && Time.now < deadline
+      warn "warning: Xcode still appears to be running (it may be waiting on an unsaved-changes prompt)." if xcode_running?
+    end
+
+    def prompt_resolve?
+      print "Resolve package dependencies now? [Y/n] "
+      answer = $stdin.gets&.strip
+      answer.nil? || answer.empty? || !answer.match?(/\An/i)
+    end
+
+    def prompt_open_in_xcode?
+      print "Open in Xcode now? [Y/n] "
+      answer = $stdin.gets&.strip
+      answer.nil? || answer.empty? || !answer.match?(/\An/i)
+    end
+
+    def open_in_xcode(xcodeproj_path)
+      target = find_workspace_path || xcodeproj_path
+      warn "warning: could not open #{target} in Xcode." unless run_command("open", target.to_s)
+    end
+
+    # Prefers `-workspace <workspace> -scheme <scheme>` over `-project` when a
+    # .xcworkspace exists, so resolution (and its Package.resolved output)
+    # targets the same file discovery reads from — some repos keep a
+    # separate top-level .xcworkspace whose Package.resolved is the one
+    # actually tracked in git, distinct from the .xcodeproj's own implicit
+    # workspace. Falls back to `-project` (no scheme needed) otherwise.
+    def resolve_target_args(xcodeproj_path)
+      workspace = find_workspace_path
+      return ["-project", xcodeproj_path.to_s] unless workspace
+
+      scheme = detect_scheme(xcodeproj_path, workspace)
+      return ["-project", xcodeproj_path.to_s] unless scheme
+
+      ["-workspace", workspace.to_s, "-scheme", scheme]
+    end
+
+    # Reads shared scheme files directly (no xcodebuild invocation, which
+    # would otherwise trigger its own package resolution just to answer
+    # "what schemes exist").
+    def detect_scheme(xcodeproj_path, workspace)
+      scheme_files = Dir.glob(xcodeproj_path + "xcshareddata/xcschemes/*.xcscheme").sort
+      return nil if scheme_files.empty?
+
+      preferred_name = workspace.basename(".xcworkspace").to_s
+      preferred = scheme_files.find { |f| File.basename(f, ".xcscheme").casecmp(preferred_name).zero? }
+      File.basename(preferred || scheme_files.first, ".xcscheme")
+    end
+
+    def resolve_package_dependencies(xcodeproj_path)
+      puts "Resolving package dependencies (xcodebuild -resolvePackageDependencies)..."
+      ok = run_command("xcodebuild", "-resolvePackageDependencies", *resolve_target_args(xcodeproj_path))
+      return if ok
+
+      warn "warning: automatic package resolution failed. Open the project in Xcode " \
+           "(File > Packages > Resolve Package Versions) to finish updating Package.resolved."
+    rescue Errno::ENOENT
+      warn "warning: xcodebuild not found on PATH; skipped automatic package resolution. " \
+           "Open the project in Xcode to resolve packages."
+    end
+  end
+end

data/lib/toggle_local_spm/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ToggleLocalSpm
+  VERSION = "2.2.2"
+end

data/lib/toggle_local_spm.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "toggle_local_spm/version"
+require_relative "toggle_local_spm/cli"
+
+module ToggleLocalSpm
+  class Error < StandardError; end
+end

data/sig/toggle_local_spm.rbs

@@ -0,0 +1,4 @@
+module ToggleLocalSpm
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: toggle-local-spm
+version: !ruby/object:Gem::Version
+  version: 2.2.2
+platform: ruby
+authors:
+- Sushant Verma
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-08-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: xcodeproj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A CLI that swaps a Swift Package Manager dependency in an .xcodeproj
+  between its remote (git) reference and a local checkout in an adjacent sibling folder,
+  and back again, without churning the underlying pbxproj object IDs.
+email:
+- sushant.40@gmail.com
+executables:
+- toggle-local-spm
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/toggle-local-spm
+- lib/toggle_local_spm.rb
+- lib/toggle_local_spm/cli.rb
+- lib/toggle_local_spm/version.rb
+- sig/toggle_local_spm.rbs
+homepage: https://github.com/squeaky-nose/toggle-local-spm
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/squeaky-nose/toggle-local-spm
+  source_code_uri: https://github.com/squeaky-nose/toggle-local-spm
+  changelog_uri: https://github.com/squeaky-nose/toggle-local-spm/releases
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Toggle an Xcode project's Swift Package dependency between its remote reference
+  and a local sibling checkout.
+test_files: []