diff --git a/.github/workflows/real-codex-binary.yml b/.github/workflows/real-codex-binary.yml index 1cfb2ce..af9b53f 100644 --- a/.github/workflows/real-codex-binary.yml +++ b/.github/workflows/real-codex-binary.yml @@ -1,10 +1,14 @@ name: Real Codex Binary on: - push: - branches: [master] - pull_request: - branches: [master] + workflow_call: + inputs: + codex_version: + type: string + default: '0.154.0' + mcp_codex_version: + type: string + default: '0.139.0' workflow_dispatch: inputs: codex_version: diff --git a/.github/workflows/swift-package.yml b/.github/workflows/swift-package.yml index 0321b07..6d0bb4b 100644 --- a/.github/workflows/swift-package.yml +++ b/.github/workflows/swift-package.yml @@ -11,6 +11,37 @@ permissions: contents: read jobs: + policy: + if: github.event_name == 'pull_request' || github.event_name == 'push' + uses: swift-library/.github/.github/workflows/policy.yml@7badcc53166c6afcb265b39c789b8240d9a30233 + with: + allow-terms: Codex + + integration: + uses: ./.github/workflows/real-codex-binary.yml + + result: + needs: [policy, windows, windows-runtime, quality, build-and-test, integration] + if: always() + runs-on: ubuntu-24.04 + steps: + - name: Require all package checks to succeed + env: + RESULTS: ${{ toJSON(needs) }} + EVENT: ${{ github.event_name }} + run: | + python3 - <<'PY' + import json, os + jobs = json.loads(os.environ['RESULTS']) + failed = [] + for name, job in jobs.items(): + expected = 'skipped' if name == 'policy' and os.environ['EVENT'] == 'workflow_dispatch' else 'success' + if job['result'] != expected: + failed.append(name) + if failed: + raise SystemExit('Validation did not succeed: ' + ', '.join(failed)) + PY + windows: name: Windows products runs-on: windows-2022 diff --git a/AGENTS.md b/AGENTS.md index e8e250a..f2b352f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,3 +49,31 @@ Scripts/verify-documentation.sh Use the pinned Codex CLI version for opt-in App Server and MCP integration tests before a release. + +## Code Review Rules + +### Compatibility and versioning + +- Flag a change to public API or observable behavior, including a raised + minimum platform or Swift version, without a `CHANGELOG.md` entry or a release version + consistent with `RELEASING.md`. Safe path: record the change under the next + version and follow that compatibility policy. + +### Claims + +- Flag README, DocC, or release-note statements that the code and tests do + not support: capabilities that do not exist, existing behavior described as + new, or platforms CI does not build. Safe path: describe what the code + shows. + +### Public documentation + +- Flag a new public symbol without a documentation comment, and public prose + that compares the package with other projects or describes internal + process. Safe path: document the symbol, and describe only this package's + own behavior. + +### Tests + +- Flag a behavior change without a test that would fail before the change. + Safe path: add the test beside the existing suite for that behavior. diff --git a/CHANGELOG.md b/CHANGELOG.md index 628375a..75d840c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -157,7 +157,8 @@ follows [Semantic Versioning](https://semver.org/) beginning with `0.1.0`. - Deterministic Swift Testing coverage, API inventory, schema verification, and opt-in real Codex binary validation. -[Unreleased]: https://github.com/swift-library/swift-codex/compare/v0.4.1...HEAD +[Unreleased]: https://github.com/swift-library/swift-codex/compare/v0.5.0...HEAD +[0.5.0]: https://github.com/swift-library/swift-codex/compare/v0.4.1...v0.5.0 [0.4.1]: https://github.com/swift-library/swift-codex/compare/v0.4.0...v0.4.1 [0.4.0]: https://github.com/swift-library/swift-codex/compare/v0.3.0...v0.4.0 [0.3.0]: https://github.com/swift-library/swift-codex/compare/v0.2.2...v0.3.0 diff --git a/Documentation/Assets/Logo.png b/Documentation/Assets/Logo.png index 62b0b02..027b6ce 100644 Binary files a/Documentation/Assets/Logo.png and b/Documentation/Assets/Logo.png differ diff --git a/Documentation/Assets/Logo.svg b/Documentation/Assets/Logo.svg index d820924..04f9f60 100644 --- a/Documentation/Assets/Logo.svg +++ b/Documentation/Assets/Logo.svg @@ -1 +1 @@ - + diff --git a/RELEASING.md b/RELEASING.md index c46fef6..226a0d7 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -67,14 +67,20 @@ Before tagging: machine-local paths are not tracked. 6. Resolve and build a fresh consumer without this repository's `.build` or a sibling checkout. -7. Confirm the worktree is clean and all required checks are green. +7. Open a pull request for the release preparation branch. Address or answer + review findings and confirm all required checks pass before squash-merging + the reviewed head. Follow the organization's + [PR workflow](https://github.com/swift-library/.github/blob/master/MAINTENANCE.md). +8. Fetch the merged default branch and verify the clean merged candidate and + its required checks before tagging. Use that accepted commit for the tag. -Create and push the release only after review: +Set `release_tag` to the intended immutable `vMAJOR.MINOR.PATCH` tag and +`accepted_commit` to the validated merged commit. Create a signed annotated +tag only after the above acceptance: ```sh -git push origin master -git tag -s -a v0.1.0 -m "swift-codex 0.1.0" -git push origin v0.1.0 +git tag -s -a "$release_tag" "$accepted_commit" -m "swift-codex $release_tag" +git push origin "$release_tag" ``` After publishing, check out the remote tag in an empty directory and repeat diff --git a/Scripts/verify-public-repository.sh b/Scripts/verify-public-repository.sh index 76dc24f..84681ca 100755 --- a/Scripts/verify-public-repository.sh +++ b/Scripts/verify-public-repository.sh @@ -133,8 +133,15 @@ if repository_content_files_null ':(exclude)Vendor/**' | xargs -0 rg -n --no-mes fi while IFS= read -r use_line; do - [[ "$use_line" =~ uses:[[:space:]]+[^[:space:]@]+@[0-9a-fA-F]{40}([[:space:]]|$) ]] \ - || fail "GitHub Actions must be pinned to a full commit SHA: $use_line" + # Local reusable workflows execute from the caller's commit. + if [[ "$use_line" =~ uses:[[:space:]]+\./(\.github/workflows/[A-Za-z0-9_.-]+\.ya?ml)[[:space:]]*$ ]]; then + local_workflow="${BASH_REMATCH[1]}" + [[ -f "$local_workflow" ]] && git ls-files --error-unmatch "$local_workflow" >/dev/null \ + || fail "Local reusable workflow must be tracked: $use_line" + else + [[ "$use_line" =~ uses:[[:space:]]+[^[:space:]@]+@[0-9a-fA-F]{40}([[:space:]]|$) ]] \ + || fail "External GitHub Actions must be pinned to a full commit SHA: $use_line" + fi done < <(rg --no-filename '^\s*-?\s*uses:' .github/workflows || true) if [[ "$(find Sources -type d -name '*.docc' | wc -l | tr -d ' ')" != "11" ]]; then diff --git a/Sources/Codex/Documentation.docc/Codex.md b/Sources/Codex/Documentation.docc/Codex.md index 27d7c7e..66cfb30 100644 --- a/Sources/Codex/Documentation.docc/Codex.md +++ b/Sources/Codex/Documentation.docc/Codex.md @@ -1,5 +1,10 @@ # ``Codex`` +@Metadata { + @PageImage(purpose: icon, source: "codex-icon", alt: "swift-codex logo") + @PageColor(purple) +} + Use Codex through SDK-style Swift threads and streamed or buffered turns. ## Overview diff --git a/Sources/Codex/Documentation.docc/Resources/codex-icon.png b/Sources/Codex/Documentation.docc/Resources/codex-icon.png new file mode 100644 index 0000000..027b6ce Binary files /dev/null and b/Sources/Codex/Documentation.docc/Resources/codex-icon.png differ diff --git a/Sources/CodexAppServerClient/Documentation.docc/CodexAppServerClient.md b/Sources/CodexAppServerClient/Documentation.docc/CodexAppServerClient.md index c32e6b7..3fa7db0 100644 --- a/Sources/CodexAppServerClient/Documentation.docc/CodexAppServerClient.md +++ b/Sources/CodexAppServerClient/Documentation.docc/CodexAppServerClient.md @@ -1,5 +1,10 @@ # ``CodexAppServerClient`` +@Metadata { + @PageImage(purpose: icon, source: "codexappserverclient-icon", alt: "swift-codex logo") + @PageColor(purple) +} + Call an upstream Codex AppServer through typed bindings or complete JSON messages. ## Overview diff --git a/Sources/CodexAppServerClient/Documentation.docc/Resources/codexappserverclient-icon.png b/Sources/CodexAppServerClient/Documentation.docc/Resources/codexappserverclient-icon.png new file mode 100644 index 0000000..027b6ce Binary files /dev/null and b/Sources/CodexAppServerClient/Documentation.docc/Resources/codexappserverclient-icon.png differ diff --git a/Sources/CodexAppServerHummingbird/Documentation.docc/CodexAppServerHummingbird.md b/Sources/CodexAppServerHummingbird/Documentation.docc/CodexAppServerHummingbird.md index 0db7388..a656e60 100644 --- a/Sources/CodexAppServerHummingbird/Documentation.docc/CodexAppServerHummingbird.md +++ b/Sources/CodexAppServerHummingbird/Documentation.docc/CodexAppServerHummingbird.md @@ -1,5 +1,10 @@ # ``CodexAppServerHummingbird`` +@Metadata { + @PageImage(purpose: icon, source: "codexappserverhummingbird-icon", alt: "swift-codex logo") + @PageColor(purple) +} + Expose a downstream AppServer-compatible WebSocket route through Hummingbird. ## Overview diff --git a/Sources/CodexAppServerHummingbird/Documentation.docc/Resources/codexappserverhummingbird-icon.png b/Sources/CodexAppServerHummingbird/Documentation.docc/Resources/codexappserverhummingbird-icon.png new file mode 100644 index 0000000..027b6ce Binary files /dev/null and b/Sources/CodexAppServerHummingbird/Documentation.docc/Resources/codexappserverhummingbird-icon.png differ diff --git a/Sources/CodexAppServerNIO/Documentation.docc/CodexAppServerNIO.md b/Sources/CodexAppServerNIO/Documentation.docc/CodexAppServerNIO.md index e1825a3..a0a5041 100644 --- a/Sources/CodexAppServerNIO/Documentation.docc/CodexAppServerNIO.md +++ b/Sources/CodexAppServerNIO/Documentation.docc/CodexAppServerNIO.md @@ -1,5 +1,10 @@ # ``CodexAppServerNIO`` +@Metadata { + @PageImage(purpose: icon, source: "codexappservernio-icon", alt: "swift-codex logo") + @PageColor(purple) +} + Connect to a Codex AppServer WebSocket endpoint with SwiftNIO. ## Overview diff --git a/Sources/CodexAppServerNIO/Documentation.docc/Resources/codexappservernio-icon.png b/Sources/CodexAppServerNIO/Documentation.docc/Resources/codexappservernio-icon.png new file mode 100644 index 0000000..027b6ce Binary files /dev/null and b/Sources/CodexAppServerNIO/Documentation.docc/Resources/codexappservernio-icon.png differ diff --git a/Sources/CodexAppServerProtocol/Documentation.docc/CodexAppServerProtocol.md b/Sources/CodexAppServerProtocol/Documentation.docc/CodexAppServerProtocol.md index 06d522f..a525b82 100644 --- a/Sources/CodexAppServerProtocol/Documentation.docc/CodexAppServerProtocol.md +++ b/Sources/CodexAppServerProtocol/Documentation.docc/CodexAppServerProtocol.md @@ -1,5 +1,10 @@ # ``CodexAppServerProtocol`` +@Metadata { + @PageImage(purpose: icon, source: "codexappserverprotocol-icon", alt: "swift-codex logo") + @PageColor(purple) +} + Use generated stable and experimental Codex AppServer protocol models. ## Overview diff --git a/Sources/CodexAppServerProtocol/Documentation.docc/Resources/codexappserverprotocol-icon.png b/Sources/CodexAppServerProtocol/Documentation.docc/Resources/codexappserverprotocol-icon.png new file mode 100644 index 0000000..027b6ce Binary files /dev/null and b/Sources/CodexAppServerProtocol/Documentation.docc/Resources/codexappserverprotocol-icon.png differ diff --git a/Sources/CodexAppServerRuntime/Documentation.docc/CodexAppServerRuntime.md b/Sources/CodexAppServerRuntime/Documentation.docc/CodexAppServerRuntime.md index 6119000..2fd3a1f 100644 --- a/Sources/CodexAppServerRuntime/Documentation.docc/CodexAppServerRuntime.md +++ b/Sources/CodexAppServerRuntime/Documentation.docc/CodexAppServerRuntime.md @@ -1,5 +1,10 @@ # ``CodexAppServerRuntime`` +@Metadata { + @PageImage(purpose: icon, source: "codexappserverruntime-icon", alt: "swift-codex logo") + @PageColor(purple) +} + Build schema-independent Codex AppServer sessions and transports. ## Overview diff --git a/Sources/CodexAppServerRuntime/Documentation.docc/Resources/codexappserverruntime-icon.png b/Sources/CodexAppServerRuntime/Documentation.docc/Resources/codexappserverruntime-icon.png new file mode 100644 index 0000000..027b6ce Binary files /dev/null and b/Sources/CodexAppServerRuntime/Documentation.docc/Resources/codexappserverruntime-icon.png differ diff --git a/Sources/CodexAppServerStdio/Documentation.docc/CodexAppServerStdio.md b/Sources/CodexAppServerStdio/Documentation.docc/CodexAppServerStdio.md index 59f9219..fe44fbc 100644 --- a/Sources/CodexAppServerStdio/Documentation.docc/CodexAppServerStdio.md +++ b/Sources/CodexAppServerStdio/Documentation.docc/CodexAppServerStdio.md @@ -1,5 +1,10 @@ # ``CodexAppServerStdio`` +@Metadata { + @PageImage(purpose: icon, source: "codexappserverstdio-icon", alt: "swift-codex logo") + @PageColor(purple) +} + Launch and connect to a local `codex app-server` process over stdio. ## Overview diff --git a/Sources/CodexAppServerStdio/Documentation.docc/Resources/codexappserverstdio-icon.png b/Sources/CodexAppServerStdio/Documentation.docc/Resources/codexappserverstdio-icon.png new file mode 100644 index 0000000..027b6ce Binary files /dev/null and b/Sources/CodexAppServerStdio/Documentation.docc/Resources/codexappserverstdio-icon.png differ diff --git a/Sources/CodexAppServerURLSession/Documentation.docc/CodexAppServerURLSession.md b/Sources/CodexAppServerURLSession/Documentation.docc/CodexAppServerURLSession.md index 0bb2ca1..d617b32 100644 --- a/Sources/CodexAppServerURLSession/Documentation.docc/CodexAppServerURLSession.md +++ b/Sources/CodexAppServerURLSession/Documentation.docc/CodexAppServerURLSession.md @@ -1,5 +1,10 @@ # ``CodexAppServerURLSession`` +@Metadata { + @PageImage(purpose: icon, source: "codexappserverurlsession-icon", alt: "swift-codex logo") + @PageColor(purple) +} + Connect to a Codex AppServer WebSocket endpoint with Foundation URLSession. ## Overview diff --git a/Sources/CodexAppServerURLSession/Documentation.docc/Resources/codexappserverurlsession-icon.png b/Sources/CodexAppServerURLSession/Documentation.docc/Resources/codexappserverurlsession-icon.png new file mode 100644 index 0000000..027b6ce Binary files /dev/null and b/Sources/CodexAppServerURLSession/Documentation.docc/Resources/codexappserverurlsession-icon.png differ diff --git a/Sources/CodexAppServerVapor/Documentation.docc/CodexAppServerVapor.md b/Sources/CodexAppServerVapor/Documentation.docc/CodexAppServerVapor.md index d941ce4..4b15ff8 100644 --- a/Sources/CodexAppServerVapor/Documentation.docc/CodexAppServerVapor.md +++ b/Sources/CodexAppServerVapor/Documentation.docc/CodexAppServerVapor.md @@ -1,5 +1,10 @@ # ``CodexAppServerVapor`` +@Metadata { + @PageImage(purpose: icon, source: "codexappservervapor-icon", alt: "swift-codex logo") + @PageColor(purple) +} + Expose a downstream AppServer-compatible WebSocket route through Vapor. ## Overview diff --git a/Sources/CodexAppServerVapor/Documentation.docc/Resources/codexappservervapor-icon.png b/Sources/CodexAppServerVapor/Documentation.docc/Resources/codexappservervapor-icon.png new file mode 100644 index 0000000..027b6ce Binary files /dev/null and b/Sources/CodexAppServerVapor/Documentation.docc/Resources/codexappservervapor-icon.png differ diff --git a/Sources/CodexExec/Documentation.docc/CodexExec.md b/Sources/CodexExec/Documentation.docc/CodexExec.md index 2ff5f4a..198d07e 100644 --- a/Sources/CodexExec/Documentation.docc/CodexExec.md +++ b/Sources/CodexExec/Documentation.docc/CodexExec.md @@ -1,5 +1,10 @@ # ``CodexExec`` +@Metadata { + @PageImage(purpose: icon, source: "codexexec-icon", alt: "swift-codex logo") + @PageColor(purple) +} + Run `codex exec` and `codex exec resume` through a typed Swift process boundary. ## Overview diff --git a/Sources/CodexExec/Documentation.docc/Resources/codexexec-icon.png b/Sources/CodexExec/Documentation.docc/Resources/codexexec-icon.png new file mode 100644 index 0000000..027b6ce Binary files /dev/null and b/Sources/CodexExec/Documentation.docc/Resources/codexexec-icon.png differ diff --git a/Sources/CodexMCP/Documentation.docc/CodexMCP.md b/Sources/CodexMCP/Documentation.docc/CodexMCP.md index 95ba47e..c6cab03 100644 --- a/Sources/CodexMCP/Documentation.docc/CodexMCP.md +++ b/Sources/CodexMCP/Documentation.docc/CodexMCP.md @@ -1,5 +1,10 @@ # ``CodexMCP`` +@Metadata { + @PageImage(purpose: icon, source: "codexmcp-icon", alt: "swift-codex logo") + @PageColor(purple) +} + Integrate with the upstream `codex mcp-server` process. ## Overview diff --git a/Sources/CodexMCP/Documentation.docc/Resources/codexmcp-icon.png b/Sources/CodexMCP/Documentation.docc/Resources/codexmcp-icon.png new file mode 100644 index 0000000..027b6ce Binary files /dev/null and b/Sources/CodexMCP/Documentation.docc/Resources/codexmcp-icon.png differ