Skip to content

docs: enforce strict XcodeGen roots#111

Merged
gaelic-ghost merged 2 commits into
mainfrom
fix/strict-xcodegen-roots
Jul 8, 2026
Merged

docs: enforce strict XcodeGen roots#111
gaelic-ghost merged 2 commits into
mainfrom
fix/strict-xcodegen-roots

Conversation

@gaelic-ghost

@gaelic-ghost gaelic-ghost commented Jul 8, 2026

Copy link
Copy Markdown
Owner

Summary

  • Collapse the XcodeGen app template to one broad Sources synced folder and one broad Tests synced folder
  • Add strict guidance against source-root fragmentation and multiple app lifecycle entry points across Xcode project skills and generated AGENTS assets
  • Extend XcodeGen migration audits to flag fragmented source entries and multiple app entry points
  • Bump Socket to 8.5.2 for a patch release

Verification

  • uv run pytest plugins/apple-dev-skills/tests/test_xcode_app_bootstrap_workflow.py plugins/apple-dev-skills/tests/test_xcodegen_migration_workflow.py
  • uv run plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/scripts/run_workflow.py --name StrictRootsProbe --destination /private/tmp/strict-roots-probe.fBHCKv --platform macos --project-generator xcodegen
  • xcodebuild -project /private/tmp/strict-roots-probe.fBHCKv/StrictRootsProbe/StrictRootsProbe.xcodeproj -scheme StrictRootsProbe -configuration Debug -derivedDataPath /private/tmp/strict-roots-probe.fBHCKv/DerivedData build
  • uv run pytest plugins/apple-dev-skills/tests
  • uv run scripts/validate_socket_metadata.py
  • uv run pytest tests
  • bash .github/scripts/sync_shared_snippets.sh --check
  • git diff --check

Summary by CodeRabbit

  • Chores
    • Bumped the overall release version to 8.5.2 across project and plugin manifests.
  • Documentation
    • Expanded Apple Xcode guidance with clearer rules for app launch structure and project source-folder layout.
    • Updated migration and workflow references to reflect the latest project organization expectations.
  • Tests
    • Adjusted validation coverage to match the new project layout and app-entry-point guidance.

@gaelic-ghost gaelic-ghost added the bug Something isn't working label Jul 8, 2026
@coderabbitai

coderabbitai Bot commented Jul 8, 2026

Copy link
Copy Markdown

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7f9abfc3-f3f0-42d0-8a35-605dcef10007

📥 Commits

Reviewing files that changed from the base of the PR and between 469d092 and 33dfe0a.

⛔ Files ignored due to path filters (8)
  • plugins/agent-portability-skills/uv.lock is excluded by !**/*.lock
  • plugins/apple-dev-skills/uv.lock is excluded by !**/*.lock
  • plugins/cardhop-app/mcp/uv.lock is excluded by !**/*.lock
  • plugins/productivity-skills/uv.lock is excluded by !**/*.lock
  • plugins/python-skills/uv.lock is excluded by !**/*.lock
  • plugins/things-app/mcp/uv.lock is excluded by !**/*.lock
  • plugins/things-app/uv.lock is excluded by !**/*.lock
  • uv.lock is excluded by !**/*.lock
📒 Files selected for processing (69)
  • plugins/agent-portability-skills/.codex-plugin/plugin.json
  • plugins/agent-portability-skills/pyproject.toml
  • plugins/agentdeck/.codex-plugin/plugin.json
  • plugins/android-dev-skills/.codex-plugin/plugin.json
  • plugins/apple-dev-skills/.codex-plugin/plugin.json
  • plugins/apple-dev-skills/.github/scripts/sync_shared_snippets.sh
  • plugins/apple-dev-skills/pyproject.toml
  • plugins/apple-dev-skills/shared/agents-snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/appkit-app-architecture-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/apple-typography-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/apple-ui-accessibility-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/avaudio-engine-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/avfaudio-session-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/avfoundation-media-pipeline-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/SKILL.md
  • plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/assets/AGENTS.md
  • plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/references/project-generators.md
  • plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/references/xcodegen-synced-folder-and-config-notes.md
  • plugins/apple-dev-skills/skills/core-animation-layer-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/coreaudio-modernization-repair-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/coremedia-timing-samplebuffer-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/devicecheck-app-attest-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/explore-apple-swift-docs/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/format-swift-sources/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/migrate-xcode-project-to-xcodegen/SKILL.md
  • plugins/apple-dev-skills/skills/migrate-xcode-project-to-xcodegen/references/migration-audit-and-promotion.md
  • plugins/apple-dev-skills/skills/migrate-xcode-project-to-xcodegen/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/migrate-xcode-project-to-xcodegen/scripts/migrate_xcode_project_to_xcodegen.py
  • plugins/apple-dev-skills/skills/safari-extension-control-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/sf-symbols-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/swiftui-animation-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/swiftui-app-architecture-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/sync-xcode-project-guidance/assets/AGENTS.md
  • plugins/apple-dev-skills/skills/sync-xcode-project-guidance/assets/append-section.md
  • plugins/apple-dev-skills/skills/sync-xcode-project-guidance/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/xcode-app-project-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/xcode-app-project-workflow/references/xcodegen-project-maintenance.md
  • plugins/apple-dev-skills/skills/xcode-build-run-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/xcode-build-run-workflow/references/xcodegen-project-maintenance.md
  • plugins/apple-dev-skills/skills/xcode-coding-intelligence-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/xcode-testing-workflow/references/snippets/apple-xcode-project-core.md
  • plugins/apple-dev-skills/skills/xcode-testing-workflow/references/xcodegen-project-maintenance.md
  • plugins/apple-dev-skills/templates/xcodegen/swiftui-app/project.yml.tmpl
  • plugins/apple-dev-skills/tests/test_xcode_app_bootstrap_workflow.py
  • plugins/apple-dev-skills/tests/test_xcodegen_migration_workflow.py
  • plugins/cardhop-app/.codex-plugin/plugin.json
  • plugins/cardhop-app/mcp/pyproject.toml
  • plugins/cloud-deployment-skills/.codex-plugin/plugin.json
  • plugins/cloud-inference-skills/.codex-plugin/plugin.json
  • plugins/dotnet-skills/.codex-plugin/plugin.json
  • plugins/game-dev-skills/.codex-plugin/plugin.json
  • plugins/network-protocol-skills/.codex-plugin/plugin.json
  • plugins/productivity-skills/.codex-plugin/plugin.json
  • plugins/productivity-skills/pyproject.toml
  • plugins/python-skills/.codex-plugin/plugin.json
  • plugins/python-skills/pyproject.toml
  • plugins/reverse-engineering-skills/.codex-plugin/plugin.json
  • plugins/rust-skills/.codex-plugin/plugin.json
  • plugins/server-side-jvm/.codex-plugin/plugin.json
  • plugins/server-side-swift/.codex-plugin/plugin.json
  • plugins/spotify/.codex-plugin/plugin.json
  • plugins/swift-lang/.codex-plugin/plugin.json
  • plugins/swiftasb-skills/.codex-plugin/plugin.json
  • plugins/things-app/.codex-plugin/plugin.json
  • plugins/things-app/mcp/pyproject.toml
  • plugins/things-app/pyproject.toml
  • plugins/web-dev-skills/.codex-plugin/plugin.json
  • pyproject.toml

📝 Walkthrough

Walkthrough

This PR bumps the version string from 8.5.1 to 8.5.2 across numerous plugin.json and pyproject.toml files, and separately overhauls Apple Xcode/XcodeGen project-structure guidance: a single app lifecycle entry point rule and revised broad-top-level syncedFolder source-root rules are propagated across a shared snippet, per-skill snippet copies, workflow docs, a migration audit script, a project template, and tests.

Changes

Plugin/package version bumps

Layer / File(s) Summary
Version bump across manifests
plugins/*/.codex-plugin/plugin.json, plugins/*/pyproject.toml, pyproject.toml
Bumps the version field from 8.5.1 to 8.5.2 across many plugin manifests and pyproject files, and the root pyproject.toml.

Apple Xcode/XcodeGen project-structure guidance overhaul

Layer / File(s) Summary
Shared snippet and sync script
plugins/apple-dev-skills/shared/agents-snippets/apple-xcode-project-core.md, plugins/apple-dev-skills/.github/scripts/sync_shared_snippets.sh
Adds the single app lifecycle entry-point rule and revised broad top-level syncedFolder guidance to the canonical snippet, and extends the sync script to propagate it to an additional skill.
Per-skill snippet copies
plugins/apple-dev-skills/skills/*/references/snippets/apple-xcode-project-core.md
Applies the same single-entry-point and syncedFolder/broad-root guidance updates to each skill's duplicated snippet copy.
Bootstrap and sync workflow docs
plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/*, plugins/apple-dev-skills/skills/sync-xcode-project-guidance/*, plugins/apple-dev-skills/skills/xcode-*-workflow/references/xcodegen-project-maintenance.md
Updates SKILL.md, AGENTS.md, project-generators.md, xcodegen-synced-folder-and-config-notes.md, and maintenance references to require broad top-level Sources/Tests entries and a single app entry point.
Migration workflow docs and audit script
plugins/apple-dev-skills/skills/migrate-xcode-project-to-xcodegen/SKILL.md, .../references/migration-audit-and-promotion.md, .../scripts/migrate_xcode_project_to_xcodegen.py
Updates migration guidance and adds fragmented-source-entry detection, broad-source-entry checks, app entry point discovery, and new recommendations.
Templates and tests
plugins/apple-dev-skills/templates/xcodegen/swiftui-app/project.yml.tmpl, plugins/apple-dev-skills/tests/test_xcode_app_bootstrap_workflow.py, plugins/apple-dev-skills/tests/test_xcodegen_migration_workflow.py
Updates the app/test target templates to use broad Sources/Tests entries and updates tests to assert the new structure, AGENTS.md guidance text, fragmentation reporting, and entry-point detection.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

Not applicable — the changes are primarily documentation guidance edits and a script/audit logic update within a single tool, without multi-component request/response flows.

Possibly related PRs

  • gaelic-ghost/socket#51: Both PRs touch the apple-xcode-project-core.md snippet for the safari-extension-control-workflow skill.
  • gaelic-ghost/socket#92: Both PRs modify the shared apple-xcode-project-core.md guidance and its propagation into the core-animation-layer-workflow skill snippet.
  • gaelic-ghost/socket#109: Both PRs modify the migrate-xcode-project-to-xcodegen workflow's migrate_xcode_project_to_xcodegen.py audit logic and apple-xcode-project-core.md guidance.

Suggested labels: documentation

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/strict-xcodegen-roots

Warning

Tools execution failed with the following error:

Failed to run tools: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error)


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 33dfe0a466

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

+ ", ".join(project_yml_audit["fragmented_source_entries"])
+ ". Use one Sources entry for the app target, one Tests entry for the test target, and one entry per separate top-level logical root only."
)
if len(file_audit["app_entry_points"]) > 1:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Scope app entry-point checks per target

In projects with more than one native target under Sources (for example a main app plus a helper/widget app, each with its own @main), file_audit["app_entry_points"] is a repo-wide list, so this condition recommends collapsing valid per-target entry points into a single app target entry point. That audit output can lead the migration workflow to remove required launch boundaries; the check should use target/source membership, or at least only compare entry points within the same app target, before flagging.

Useful? React with 👍 / 👎.

@gaelic-ghost gaelic-ghost merged commit 3183dec into main Jul 8, 2026
1 of 2 checks passed
@gaelic-ghost gaelic-ghost deleted the fix/strict-xcodegen-roots branch July 8, 2026 17:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant