From d4612fb21eee39d1f75cfecbb6fb3f11891d3dcf Mon Sep 17 00:00:00 2001 From: Sertac Ozercan Date: Wed, 15 Jul 2026 21:16:47 -0700 Subject: [PATCH] docs: add repository agent guidance Signed-off-by: Sertac Ozercan --- AGENTS.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d335f34 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,79 @@ +# Repository instructions + +## Project at a glance + +OpenInCode is a small macOS Finder toolbar utility written in Objective-C. It reads the selected Finder item, or the front Finder window when nothing is selected, and opens the corresponding folder in Visual Studio Code. + +- Deployment target: macOS 12 or newer. +- Build system: `Open in Code.xcodeproj`; Xcode 26 or newer is required for the current Icon Composer asset. +- Memory model: manual reference counting; ARC is disabled. +- Dependencies: Apple frameworks only; there is no package manager or dependency-install step. + +## Repository map + +- `main.m`: Finder automation, user-facing errors, application lookup, and launch flow. +- `OpenInCodeCore.h` / `OpenInCodeCore.m`: testable editor-priority and Finder-path logic. +- `Tests/OpenInCodeCoreTests.m`: standalone Foundation test executable used by the test script. +- `scripts/test.sh`: canonical focused test command; also validates Homebrew cask rendering. +- `scripts/render-homebrew-cask.sh`: release cask template generator. +- `Info.plist` and `Open in Code.entitlements`: app metadata and Finder Apple Events permission. +- `Open in Code.xcodeproj`: target membership, build settings, signing, and the build rule that generates `Finder.h` from Finder's scripting definition. +- `.github/workflows/release.yml`: tag-driven universal build, signing, notarization, GitHub release, and Homebrew cask update. + +## Working rules + +1. Check `git status --short` before editing and preserve unrelated user changes. +2. Inspect only the files relevant to the task; do not search generated `build/` or `DerivedData/` content. +3. Keep changes focused. Avoid adding dependencies, new abstractions, or project files unless the task requires them. +4. Put deterministic, UI-independent behavior in `OpenInCodeCore.*` and cover it in `Tests/OpenInCodeCoreTests.m`. +5. When adding or removing source or resource files, keep the Xcode project references and target membership in sync. +6. Do not add a generated `Finder.h` to the repository; Xcode creates it during the build. + +## Behavioral invariants + +Preserve these unless the requested change explicitly replaces them: + +- Prefer stable VS Code (`com.microsoft.VSCode`), then VS Code Insiders (`com.microsoft.VSCodeInsiders`). +- Use the first selected Finder item; fall back to the front Finder window's target. +- Open directories directly. Open a regular file or Finder package by opening its parent directory. +- Resolve Finder aliases without UI, reject broken aliases and inaccessible or non-file URLs, and preserve directory-symlink behavior. +- Present actionable errors for Finder permission failures and missing or failed VS Code launches. +- Keep compatibility with macOS 12; guard any newer API before use. + +## Objective-C conventions + +- Match the existing Objective-C style and naming (`OIC` prefix for shared symbols). +- ARC is disabled. Balance ownership with `retain`, `release`, `autorelease`, or `copy`, and keep `dealloc` implementations correct. +- Treat compiler warnings as errors in testable core code. +- Prefer small functions with explicit failure handling over silent fallback behavior. + +## Validation + +Run the smallest relevant checks: + +- Documentation-only changes: inspect the diff; no build is required. +- Core logic, tests, or scripts: + + ```sh + ./scripts/test.sh + ``` + +- Application code, plist, entitlements, icon, or Xcode project changes: run the focused tests, then an unsigned Release build: + + ```sh + xcodebuild \ + -project "Open in Code.xcodeproj" \ + -scheme "Open in Code" \ + -configuration Release \ + CODE_SIGNING_ALLOWED=NO \ + clean build + ``` + +Do not create tags, publish releases, notarize artifacts, update the Homebrew tap, or alter signing identities, team IDs, bundle identifiers, or release secrets unless explicitly requested. + +## Git and GitHub + +- Do not add `[codex]` to pull request titles. +- Use Conventional Commit format for pull request titles, for example `feat: add task timeline` or `fix(api): handle empty filters`. +- Do not open pull requests as drafts unless explicitly requested. +- Sign commits with `git commit -s`.