# macOS Project Discovery 与 Run Loop

仅在任务涉及 Xcode/SwiftPM project discovery、build、launch、debug、Codex Run action 或 failure classification 时读取。

## 1. 发现顺序

先确认 workspace root 和已有约定：

```bash
git rev-parse --show-toplevel
git status --short
find . \( -name '*.xcworkspace' -o -name '*.xcodeproj' -o -name Package.swift \) -print
find . -maxdepth 3 -type f \( -name '*build*.sh' -o -name '*run*.sh' -o -name Makefile \) -print
```

规则：

1. 忽略 DerivedData、`.build`、vendor dependency 和 nested checkout 中的候选。
2. `.xcworkspace` 通常优先于其内部 `.xcodeproj`；项目文档、CI 和 shared scheme 是更强证据。
3. 若当前目录不在 Git 中，不自动 `git init`。只有 Codex Git-backed Run action 明确需要且用户确认时，才在正确 root 初始化。
4. 现有 script/Make target 能稳定完成任务时直接复用，不建立第二套入口。

## 2. Xcode 分支

### 2.1 列出并选择 Scheme

```bash
xcodebuild -list -workspace '<App>.xcworkspace'
xcodebuild -list -project '<App>.xcodeproj'
```

优先 shared、能产出目标 macOS app 的 scheme。多个候选时，从 CI、README、scheme container 和 product type 解释选择；不能唯一确定时询问。

### 2.2 最小 Build/Test

```bash
xcodebuild \
  -workspace '<App>.xcworkspace' \
  -scheme '<Scheme>' \
  -configuration Debug \
  -destination 'platform=macOS' \
  build

xcodebuild \
  -workspace '<App>.xcworkspace' \
  -scheme '<Scheme>' \
  -destination 'platform=macOS' \
  test
```

project-only 时将 `-workspace` 换成 `-project`。不要猜 DerivedData 里的 app 路径；优先使用项目已有确定路径，或从 Xcode build settings/build output 取得 `TARGET_BUILD_DIR` 与 `FULL_PRODUCT_NAME`。

## 3. SwiftPM 分支

读取 `Package.swift`，确认 product 类型和名称：

```bash
swift package describe
swift build
swift build --show-bin-path
swift test
```

- library-only：只能 build/test，不报告“可运行”。
- CLI executable：可用 `swift run <product>`，稳定 script 中也可直接运行 `$(swift build --show-bin-path)/<product>`。
- AppKit/SwiftUI GUI executable：不要把 raw executable launch 作为正常路径；使用 `swiftpm-gui-app-bundle.md` 的 `.app` staging。
- Release mode 只在用户、benchmark 或 distribution 任务明确要求时使用。

## 4. 什么时候创建 `script/build_and_run.sh`

满足以下任一条件且项目没有稳定等价入口时才创建：

- 用户明确要求 Codex Run button；
- 需要反复执行 kill→build→launch；
- artifact discovery 和 launch 命令复杂到一次性命令容易漂移。

默认接口：

```text
./script/build_and_run.sh             # kill → build → launch
./script/build_and_run.sh --debug     # 仅在需要 LLDB 时
./script/build_and_run.sh --logs      # 仅在需要 process logs 时
./script/build_and_run.sh --telemetry # 仅在已有 subsystem/category 事件时
./script/build_and_run.sh --verify    # 仅证明目标 process 存在
```

脚本规则：

1. `#!/usr/bin/env bash` + `set -euo pipefail`。
2. 用真实 executable/process name 停止旧实例；`pkill` 的“没有旧实例”可以忽略，build/launch error 不能吞掉。
3. build failure 必须阻止 launch。
4. run script 放在 `script/` 或项目已有 scripts 目录，不放入 app source hierarchy。
5. 只实现本任务需要的 mode；usage 和 exit code 清楚。
6. `--verify` 的 `pgrep` 只验证进程，不验证窗口和 UI。

## 5. Codex Run Action

脚本存在、可执行且已手工验证后，才写项目根目录 `.codex/environments/environment.toml`：

```toml
# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
version = 1
name = "<project-name>"

[setup]
script = ""

[[actions]]
name = "Run"
icon = "run"
command = "./script/build_and_run.sh"
```

若文件已有 `Run` action，更新 command，不新增 duplicate。不要让 action 指向 stale/non-executable path。

## 6. Failure Classification

| 类别 | 典型证据 | 下一步 |
| --- | --- | --- |
| Compiler | Swift/C/ObjC diagnostic、source location | 修首个 source error，重跑同一 build。 |
| Linker | undefined symbol、duplicate symbol、missing library | 检查 target membership、product dependency、architecture/runpath。 |
| Build settings | destination、deployment target、module map、configuration | 对比实际 scheme/configuration/build settings。 |
| SDK/toolchain | missing SDK、Swift version、Xcode selection | 检查 `xcode-select`、Xcode version 和 package requirement。 |
| Script | permission、path、quoting、stale artifact | 单独运行失败 step，修入口而非 app source。 |
| Signing/trust | codesign、sandbox、Hardened Runtime、Gatekeeper | 切换 `macos-signing-entitlements`。 |
| Startup | bundle metadata、dynamic loader、immediate exit、activation | 检查 app bundle、console/crash、process 与 activation。 |
| Runtime logic | app 已启动后的 exception、incorrect state | 用 LLDB、targeted logging 或最小 reproducer。 |

只引用第一个真实 blocker 及其必要上下文；不要用最后一个 cascading error 作为根因。

## 7. 来源

- https://github.com/openai/plugins/blob/11c74d6ba24d3a6d48f54a194cd00ef3beea18f9/plugins/build-macos-apps/skills/build-run-debug/SKILL.md
- https://github.com/openai/plugins/blob/11c74d6ba24d3a6d48f54a194cd00ef3beea18f9/plugins/build-macos-apps/skills/swiftpm-macos/SKILL.md
- https://developer.apple.com/library/archive/technotes/tn2339/_index.html