Add tests, CI, and open-source infrastructure

- Unit tests for HIDKeyMap (lookup, namedKey, parseModifier)
- GitHub Actions CI workflow (build + test on macOS 15)
- Track Package.resolved for reproducible builds
- Makefile with build/release/install/test/clean targets
- CLAUDE.md with project conventions for AI agents
- GitHub issue templates (bug report, feature request)
- CODE_OF_CONDUCT.md (Contributor Covenant v2.1)
- CONTRIBUTING.md with dev setup and code style guidelines

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: berkozero

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug Report
+about: Report something that isn't working correctly
+title: ''
+labels: bug
+assignees: ''
+---
+
+**What you ran**
+
+```
+iphonebase <command> <flags>
+```
+
+**What you expected**
+
+A clear description of the expected behavior.
+
+**What actually happened**
+
+What went wrong. Include error messages or unexpected output.
+
+**Environment**
+
+- macOS version:
+- iPhone model:
+- Karabiner-Elements version:
+- iphonebase version (`iphonebase --version`):
+
+**Additional context**
+
+Anything else — screenshots, `--verbose` output, etc.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Use case**
+
+Describe the problem or workflow this feature would help with.
+
+**Proposed solution**
+
+How you imagine this working (CLI interface, flags, output format).
+
+**Alternatives considered**
+
+Any workarounds you've tried or other approaches.
+
+**Additional context**
+
+Anything else — screenshots, links to related issues, etc.

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build
+        run: swift build
+
+      - name: Run tests
+        run: swift test

.gitignore

@@ -1,8 +1,22 @@
+# macOS
 .DS_Store
+
+# Swift Package Manager
 /.build
 /Packages
+
+# Xcode
 xcuserdata/
 DerivedData/
+*.xcodeproj
 .swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+
+# Credentials
 .netrc
-*.xcodeproj
+
+# Claude Code
+.claude/
+
+# Editor
+*.swp
+*~

CLAUDE.md

@@ -0,0 +1,54 @@
+# iphonebase
+
+Swift CLI to control iPhone via macOS iPhone Mirroring. Built for AI agents (OpenClaw, Claude Code, MCP) and standalone terminal use.
+
+## Tech Stack
+- Swift 5.9+, macOS 14+ (requires Sequoia 15.0+ at runtime)
+- ArgumentParser 1.3.0
+- Frameworks: ScreenCaptureKit, Vision, CoreGraphics, AppKit
+- Karabiner-Elements required (DriverKit virtual HID for input injection)
+
+## Build & Run
+swift build                                    # debug
+swift build -c release                         # release
+sudo cp .build/release/iphonebase /usr/local/bin/  # install
+
+## Project Structure
+- Sources/IPhoneBaseCore/ — library: WindowManager, ScreenCapture, OCREngine, InputInjector, HIDKeyMap
+- Sources/iphonebase/ — CLI entry point + Commands/
+- skills/iphonebase/ — OpenClaw skill definition (SKILL.md)
+
+## Adding a New Command
+1. Create Sources/iphonebase/Commands/XxxCommand.swift
+2. Implement AsyncParsableCommand (or ParsableCommand for sync-only)
+3. Add XxxCommand.self to subcommands array in IPhoneBase.swift
+4. Include --json flag for structured output
+
+## Code Conventions
+- Import order: ArgumentParser, IPhoneBaseCore, Foundation
+- All commands support --json (use JSONSerialization with .prettyPrinted)
+- Results to stdout, debug/verbose to stderr
+- InputInjector pattern: connect() then defer { disconnect() }
+- Call wm.bringToFront() before any input injection
+- Errors: typed enums with CustomStringConvertible; throw ExitCode.failure for user errors
+
+## Coordinate System (critical)
+- ScreenCapture captures at 2x retina resolution
+- OCR (Vision) returns normalized coords with bottom-left origin — must invert Y
+- tap --text handles conversion automatically; raw tap x y is relative to window (screen points)
+- All InputInjector operations use absolute screen coordinates (window.bounds.origin + offset)
+
+## Input Injection Gotchas
+- iPhone Mirroring blocks CGEvent clicks — only Karabiner virtual HID works
+- Tap sequence: CGWarp cursor → nudge-sync virtual pointer (3x 1px/-1px) → click via HID
+- Timing delays (usleep) throughout InputInjector are tuned values, not arbitrary
+- Karabiner daemon must be running (not just installed)
+
+## OpenClaw Skill
+- Skill at skills/iphonebase/SKILL.md follows AgentSkills spec (YAML frontmatter + markdown)
+- Requires bins: ["iphonebase"], os: ["darwin"]
+- Install to ~/.openclaw/skills/ for agent discovery
+
+## Commits
+- Imperative mood ("Add feature" not "Added feature")
+- First line under 72 characters

CODE_OF_CONDUCT.md

@@ -0,0 +1,12 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+By participating in this project, you agree to abide by its terms.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, please open an issue at
+https://github.com/berkozero/iphonebase/issues or contact the maintainers directly.
+
+All reports will be reviewed and handled with discretion.

CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to iphonebase
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Reporting Bugs
+
+Open a [GitHub issue](https://github.com/berkozero/iphonebase/issues/new?template=bug_report.md) with:
+
+- What you ran (command + flags)
+- What you expected
+- What actually happened
+- macOS version, iPhone model, and Karabiner-Elements version
+
+If a command fails silently, re-run with `--verbose` (where supported) and include the stderr output.
+
+## Suggesting Features
+
+Open a [feature request](https://github.com/berkozero/iphonebase/issues/new?template=feature_request.md). Describe the use case, not just the solution.
+
+## Development Setup
+
+```bash
+git clone https://github.com/berkozero/iphonebase.git
+cd iphonebase
+swift build
+```
+
+Requirements:
+- macOS 15.0+ (Sequoia)
+- Xcode 16+ or Swift 6.0+ toolchain
+- [Karabiner-Elements](https://karabiner-elements.pqrs.org/) installed
+- iPhone Mirroring active (for testing)
+
+## Submitting Changes
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Test against a real iPhone Mirroring session
+4. Run `swift build` to verify it compiles
+5. Open a pull request with a clear description of what and why
+
+### Code Style
+
+- Follow existing conventions in the codebase
+- Keep functions focused and small
+- Use `--json` output for any new commands
+- Write to stderr for debug/verbose output, stdout for results
+
+### Commit Messages
+
+- Use imperative mood ("Add feature" not "Added feature")
+- First line under 72 characters
+- Explain *why*, not just *what*, in the body if needed
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). Be kind and constructive.

Makefile

@@ -0,0 +1,16 @@
+.PHONY: build release install test clean
+
+build:
+	swift build
+
+release:
+	swift build -c release
+
+install: release
+	cp .build/release/iphonebase /usr/local/bin/
+
+test:
+	swift test
+
+clean:
+	swift package clean

Package.swift

@@ -28,5 +28,9 @@ let package = Package(
                 .product(name: "ArgumentParser", package: "swift-argument-parser"),
             ]
         ),
+        .testTarget(
+            name: "IPhoneBaseCoreTests",
+            dependencies: ["IPhoneBaseCore"]
+        ),
     ]
 )