nativeapptemplate-agent 0.1.0

package/CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+Project-wide Claude Code instructions. Keep this file short — it's loaded into context every session. For deep context, read the linked docs on demand.
+
+## What this project is
+
+`nativeapptemplate-agent` — a Claude Code agent that turns a natural-language SaaS spec (e.g. "a walk-in queue for a barbershop") into a working three-platform implementation: Rails 8.1 API + native SwiftUI iOS + native Jetpack Compose Android. Built during the Built with Opus 4.7 Claude Code Hackathon, April 21–27, 2026.
+
+**Read `docs/SPEC.md` before making non-trivial changes.** It's the source of truth for architecture, three-layer validation, operation paths (adapt vs. replace), and hackathon success criteria.
+
+## Model
+
+- Use `claude-opus-4-7` for all agent invocations.
+- Requires Claude Agent SDK `>= 0.2.111`.
+- Do not set `thinking.type.enabled` — use `thinking: {type: "adaptive"}` instead (Opus 4.7 uses adaptive thinking).
+
+## Stack
+
+- **Host language:** TypeScript (Claude Agent SDK `@anthropic-ai/claude-agent-sdk`)
+- **Ruby subprocesses** for Rails AST / ERB / migration work (called from TypeScript)
+- **External MCP:** [`mobile-next/mobile-mcp`](https://github.com/mobile-next/mobile-mcp) for iOS Simulator + Android Emulator UI automation (`npx -y @mobilenext/mobile-mcp@latest`)
+- **Node 22+ required.**
+
+## Coding conventions
+
+- TypeScript `strict: true`; no implicit `any`.
+- Prefer functions over classes — introduce a class only when state + lifecycle justify it (e.g. a long-lived MCP client wrapper). Stateless transforms are functions.
+- Ruby subprocesses: shell out via `execFile("ruby", ["scripts/ruby/<script>.rb", ...])` from a thin wrapper in `src/ruby.ts`. Pass structured data as JSON on stdin/stdout, not positional CLI args. Each script must be self-contained and re-entrant.
+- No comments explaining *what* the code does — name things well instead. Reserve comments for non-obvious *why*.
+
+## Substrate (what the agent operates on)
+
+The agent works on either the free (MIT-licensed) edition or the paid edition — the same code path handles both, validated end-to-end. Pick which substrate to use by pointing the env vars at the corresponding repos:
+
+- `$NATIVEAPPTEMPLATE_API` — Rails 8.1 API repo (`nativeapptemplateapi`, single repo serves both editions; multi-tenancy + invitations are conditional features)
+- `$NATIVEAPPTEMPLATE_IOS` — SwiftUI iOS repo. Free: `NativeAppTemplate-Free-iOS` (Swift 15,311 LOC). Paid: `NativeAppTemplate` (Swift 23,003 LOC, adds org switching, invitations, role permissions).
+- `$NATIVEAPPTEMPLATE_ANDROID` — Jetpack Compose Android repo. Free: `NativeAppTemplate-Free-Android` (Kotlin 19,521 LOC). Paid: `NativeAppTemplate` (Kotlin 28,401 LOC).
+
+The renamer's substitution rules (Shop / Shopkeeper / ItemTag / NativeAppTemplate) apply identically to both editions. Paid-only concepts (Account, Member, Invitation) aren't in the rename plan, so paid features survive the generation intact. Both editions hit the same Rails OpenAPI server, so the reviewer's three-way diff works against either.
+
+**Substrate repos are read-only from the agent's perspective.** The agent never commits, pushes, edits, or runs destructive commands inside the substrate directories. To customize, the agent copies the substrate into `./out/<spec-slug>/{rails,ios,android}/` as fresh git-initialized project directories, and works exclusively inside `./out/` thereafter. Treat the substrate paths the same way you'd treat a read-only mount.
+
+## Domain model (do not misread)
+
+- `Shop` → per-tenant primary resource (not "store", not "shop" in e-commerce sense — a physical location with a walk-in queue)
+- `Shopkeeper` → the authenticated user/owner of a Shop
+- `ItemTag` (aka Number Tag) → a queue entry, attached to a Shop
+- **ItemTag has TWO states: `Idled` ↔ `Completed`.** It's a toggle, not a three-state machine. If a user's spec wants three states (e.g. "in-service"), extend the machine rather than assume it.
+- Free edition is single-organization (personal account is transparent). Paid-edition features (multi-tenancy, invitations, roles, org switching) are out of scope for the hackathon.
+
+## Repository state
+
+Pre-implementation as of this writing: `src/` and `scripts/ruby/` are empty, and there is no `package.json`. The npm commands below are the target interface — don't try to run them until the scaffolding lands. Check `src/` before assuming.
+
+## Commands
+
+```bash
+# Build & test the agent (run from this repo root — once package.json exists)
+npm run build
+npm run test
+npm run dev -- "your spec here"
+
+# Substrate commands — run from the matching generated project dir in ./out/<slug>/
+bin/dev                                        # Rails API
+xcodebuild -scheme NativeAppTemplate -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.2' build   # iOS
+./gradlew assembleDebug && ./gradlew installDebug                                                          # Android
+
+# Validation (run from this repo root)
+rg -n "Shop|Shopkeeper|ItemTag" ./out/<slug>/    # Layer 1 rename completeness check
+cloc --vcs=git "$NATIVEAPPTEMPLATE_API"                  # LOC measurement for a specific substrate repo
+
+# mobile-mcp — invoked via natural language through Claude Code
+# "Take a screenshot", "Tap on Sign Up", "List elements on screen", etc.
+```
+
+## Operations the agent performs
+
+Three clean operations on the substrate (details in `docs/SPEC.md` section 4):
+
+1. **Rename the skeleton** — Shop → Clinic, Shopkeeper → Staff, propagated coherently across Rails + Swift + Kotlin.
+2. **Adapt or replace the domain module** — keep ItemTag for queue variants; strip and insert a new resource for non-queue SaaS.
+3. **Drive the build green** — Rails tests + xcodebuild + gradlew must all pass.
+
+## Validation (three layers, gated)
+
+1. **Structural** — ripgrep for leftover domain tokens + OpenAPI contract parity (Rails ↔ iOS ↔ Android).
+2. **Runtime** — Rails boots, iOS builds & launches, Android builds & launches (Stage 1); UI-driven CRUD scenario via mobile-mcp (Stage 2).
+3. **Semantic** — Opus 4.7 as judge (text + vision) scoring against a structured rubric. Three runs per screenshot, take the median.
+
+## Guardrails
+
+- **Self-repair loop hard-capped at 5 iterations** per generated project. On exceed, surface residuals and exit.
+- Known-cryptic failure modes: Jetpack Compose compilation, Hilt DI. Slow down and verify rather than pattern-match on those.
+- **Do not invent tests for the generated code.** The substrate already has tests; use them.
+- **Never modify the substrate repos** — clone them fresh into `./out/<slug>/{rails,ios,android}` before editing.
+- Token budget: keep per-sub-agent context under 500k tokens to leave headroom for self-repair loops.
+
+## Output layout
+
+```
+./out/<spec-slug>/
+├── rails/           # customized Rails API (git-initialized)
+├── ios/             # customized iOS project (git-initialized)
+└── android/         # customized Android project (git-initialized)
+```
+
+Each is an independent, buildable git repo.
+
+## Packaging
+
+Ships as:
+- `npx nativeapptemplate-agent "your spec"` — standalone CLI
+- A Claude Code plugin (slash commands + skills)
+
+## Hackathon success criteria (quick reminder — details in docs/SPEC.md section 11)
+
+**Must-have for the demo video:**
+- Clinic queue spec produces 3 projects passing Layer 1 + Layer 2 Stage 1
+- Layer 3 rubric scores above threshold for captured home-screen shots
+- 90s demo video of end-to-end run with validation report
+
+**Stretch:** restaurant waitlist + task tracker also pass; self-repair loop fixes at least one real failure in the video.
+
+## Sibling docs
+
+- `docs/SPEC.md` — full technical specification (read first for any non-trivial change)
+- `ROADMAP.md` — post-hackathon direction, OSS vs hosted tracks, durable scope boundaries
+- `docs-private/GTM.md` — business strategy (relevant when discussing product surface, pricing, or Phase A/B transitions). Gitignored, not for publication.
+- `docs-private/PREP-CHECKLIST.md` — pre-hackathon setup (should already be all-green by the time development starts). Gitignored.
+
+## Anti-patterns to avoid
+
+- **Don't reimplement mobile UI automation.** Use mobile-mcp. The hackathon is not about inventing device automation.
+- **Don't extend scope beyond the queue / simple-CRUD-SaaS family** during the hackathon week. See `docs/SPEC.md` section 9 for the full non-goals list.
+- **Don't target the paid edition.** The deliverable operates only on the MIT-licensed free edition so judges can reproduce it end-to-end.
+- **Don't skip the validation layers to save time.** They are the demo story. A run that green-builds without passing Layer 3 is a failed run.
+- **Don't edit, commit, push, or run `git clean` / `rm` inside `$NATIVEAPPTEMPLATE_API`, `$NATIVEAPPTEMPLATE_IOS`, or `$NATIVEAPPTEMPLATE_ANDROID`.** Those are the developer's working copies of the free-edition substrate, possibly shared with other projects on the same machine. Copy them into `./out/<slug>/` first; change nothing in place. If unsure whether a command is safe, ask.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daisuke Adachi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# NativeAppTemplate Agent
+
+A Claude Code agent that turns a natural-language spec — something as informal as `"a walk-in queue for a barbershop"` — into a working three-platform implementation:
+
+- **Rails 8.1 API**
+- **native SwiftUI iOS**
+- **native Jetpack Compose Android**
+
+Coherent across all three, in under an hour.
+
+> **Status:** Hackathon build. Developed during [Built with Opus 4.7: a Claude Code Hackathon](https://cerebralvalley.ai/e/built-with-4-7-hackathon) (April 21–27, 2026). Active development in progress — expect breaking changes through the end of April.
+
+---
+
+## Why this exists
+
+Most "AI builds an app" tools stop at a single web frontend. The real pain for anyone shipping a mobile product is that the *same* domain has to be implemented three times — multi-tenant Rails API, native iOS, native Android — each with its own idioms, and keeping them consistent is where weeks disappear.
+
+Classic mobile boilerplates sell "save 12–16 weeks of setup." AI coding tools have compressed that value to 2–3 weeks of AI-assisted work. The durable problem that remains — even with AI — is **cross-platform coherence**: keeping a Rails API, a native iOS client, and a native Android client all consistent under iteration, with no contract drift, no forgotten rename, no divergent localized copy.
+
+This agent is an answer to that: turn a boilerplate into a generator that produces coherent three-platform implementations on demand, with structural and semantic validation built in.
+
+## What it does
+
+Point the agent at a natural-language spec:
+
+```
+a walk-in clinic queue for small veterinary practices
+```
+
+It will:
+
+1. **Parse the spec** into a structured domain (entities, fields, relationships, state machines).
+2. **Copy the free-edition substrate** (three MIT-licensed repos covering Rails + iOS + Android) into `./out/<spec-slug>/{rails,ios,android}/`.
+3. **Rename the skeleton** — `Shop → Clinic`, `Shopkeeper → Vet`, etc. — consistently across Ruby migrations, Swift models, Kotlin data classes, policies, tests, and localized copy.
+4. **Adapt or replace the domain module** — keep `ItemTag` for walk-in queue variants; strip and insert a new resource for non-queue SaaS.
+5. **Drive the build green** — `bin/rails test`, `xcodebuild test`, `./gradlew test` must all pass before the agent exits.
+6. **Validate the output** across three layers (structural, runtime, semantic). Details in [`docs/SPEC.md`](./docs/SPEC.md) section 6.
+
+## Demo
+
+Three demo specs, both adapt and replace paths, all four validation layers green end-to-end:
+
+| Spec | Domain entity (post-rename) | Path | Result |
+|---|---|---|---|
+| `"a walk-in clinic queue for small veterinary practices"` | `ItemTag → Patient`, `Shop → Clinic`, `Shopkeeper → Vet` | adapt | Layer 1 3/3 · Layer 2 3/3 · Layer 3 2/2 · Reviewer PASS |
+| `"a restaurant waitlist for casual dining"` | `Shop → Restaurant`, `Shopkeeper → Host` | adapt | Layer 1 3/3 · Layer 2 3/3 · Layer 3 2/2 · Reviewer PASS |
+| `"a personal task tracker with due dates"` | `ItemTag → Todo` (replaces queue entry entirely) | replace | Layer 1 3/3 · Layer 2 3/3 · Layer 3 2/2 · Reviewer PASS |
+
+Layer 2 ran in build mode — real `xcodebuild build` and `./gradlew assembleDebug`, full app builds installed on iPhone 17 simulator and Android emulator. Layer 3 captured the home-screen via `xcrun simctl io booted screenshot` / `adb exec-out screencap` and judged against the rubric using Opus 4.7 vision (median of 3 samples per criterion).
+
+The agent works on either the **free (MIT) edition** or the **paid edition** without code changes — the same pipeline handles both substrates; multi-tenant features (org switching, invitations, role permissions) survive the rename pipeline when targeting paid.
+
+<table>
+  <tr>
+    <td align="center"><img src="docs/images/demo-ios-vet-clinic-queue.png" width="300"><br><sub>iOS — Vet Clinic Queue welcome screen</sub></td>
+    <td align="center"><img src="docs/images/demo-android-vet-clinic-queue.png" width="300"><br><sub>Android — Vet Clinic Queue welcome screen</sub></td>
+  </tr>
+</table>
+
+Both screenshots are real captures from the booted iOS Simulator and Android emulator post-`./gradlew assembleDebug` / `xcodebuild build`, after the agent installed and launched the generated app.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    Spec["Natural-language spec<br/>(e.g. walk-in clinic queue)"] --> Agent
+    subgraph Agent["Claude Code Agent · Opus 4.7"]
+      Planner --> Workers
+      Workers --> Reviewer
+      Reviewer --> Judge
+    end
+    Substrate[("Free-edition substrate<br/>Rails · iOS · Android<br/>READ-ONLY")] -. copy .-> Out
+    Agent --> Out["./out/[slug]/<br/>rails / ios / android"]
+    Out --> L1["Layer 1 — Structural"]
+    L1 --> L2["Layer 2 — Runtime + mobile-mcp"]
+    L2 --> L3["Layer 3 — Vision judge"]
+```
+
+## Substrate
+
+The agent operates on the free, MIT-licensed edition of NativeAppTemplate — three public repos:
+
+| Repo | Stack | LOC |
+|---|---|---|
+| [`nativeapptemplateapi`](https://github.com/nativeapptemplate/nativeapptemplateapi) | Rails 8.1, PostgreSQL, `devise_token_auth`, `pundit`, `acts_as_tenant` | 7,687 (Ruby) |
+| [`NativeAppTemplate-Free-iOS`](https://github.com/nativeapptemplate/NativeAppTemplate-Free-iOS) | 100% SwiftUI, `@Observable`, MVVM, Liquid Glass design, iOS 26.2+ | 15,311 (Swift) |
+| [`NativeAppTemplate-Free-Android`](https://github.com/nativeapptemplate/NativeAppTemplate-Free-Android) | 100% Kotlin, 100% Jetpack Compose, Hilt, Retrofit2, API 26+ | 19,521 (Kotlin) |
+
+Combined ~42.5k LOC. Extracted from [MyTurnTag Creator](https://myturntag.com), a walk-in queue-management SaaS live on both app stores since 2024.
+
+## Usage (target interface)
+
+> **Not yet functional — hackathon build in progress.** The interface below is the target; `npx` won't work until v0.1 ships at the end of hackathon week.
+
+```bash
+# Standalone CLI — must-have for the hackathon demo
+npx nativeapptemplate-agent "a walk-in clinic queue for small veterinary practices"
+
+# Stretch specs the agent is also designed to handle
+npx nativeapptemplate-agent "a restaurant waitlist for casual dining"
+npx nativeapptemplate-agent "a personal task tracker with due dates"
+
+# Generated output appears under ./out/<slug>/
+tree ./out/clinic-queue/
+# ├── rails/      ← Rails 8.1 API, git-initialized, buildable
+# ├── ios/        ← SwiftUI iOS project, buildable
+# └── android/    ← Jetpack Compose Android project, buildable
+```
+
+The agent will also be available as a Claude Code plugin.
+
+## Requirements
+
+- [Node.js](https://nodejs.org) 22+
+- [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-typescript) v0.2.111 or later (needed for Opus 4.7)
+- An [Anthropic API key](https://console.anthropic.com/settings/keys) with access to `claude-opus-4-7`, exported as `ANTHROPIC_API_KEY`:
+  ```bash
+  export ANTHROPIC_API_KEY="sk-ant-..."
+  ```
+  The Anthropic SDK reads this env var automatically; no other config is required. See [Security](#security) below for storage recommendations.
+- Local checkouts of the three substrate repos, referenced via environment variables:
+  ```bash
+  export NATIVEAPPTEMPLATE_API="/path/to/nativeapptemplateapi"
+  export NATIVEAPPTEMPLATE_IOS="/path/to/NativeAppTemplate-Free-iOS"
+  export NATIVEAPPTEMPLATE_ANDROID="/path/to/NativeAppTemplate-Free-Android"
+  ```
+  A starter [`/.env.example`](./.env.example) lists all the variables in one place.
+- For runtime validation (Layer 2 onwards): Xcode 26.3+ with iOS 26.2+ simulator, Android SDK with API 26+ emulator
+- For UI automation: [`mobile-next/mobile-mcp`](https://github.com/mobile-next/mobile-mcp) (installed automatically as a Claude Code MCP server)
+
+### Optional flags
+
+- `NATIVEAPPTEMPLATE_VISUAL=1` — opts the run into Stage 1 visual judging (Layer 3). When set, Layer 2 runs in **build mode** instead of fast mode (full `xcodebuild build` + `./gradlew assembleDebug`), then for each platform the agent installs the app on the booted sim/emulator, captures the home screen, and judges it with Opus 4.7 vision against `DEFAULT_STAGE1_RUBRIC`. Adds 60-180s per platform depending on cold-build time. Requires a sim/emulator booted for each platform you want judged. Off by default — `npm run dev` keeps the existing fast path.
+- `NATIVEAPPTEMPLATE_AGENT_ANTHROPIC_KEY` — dedicated workspace key, see [Security](#security).
+- `ANDROID_SERIAL` — when more than one Android device/emulator is attached (e.g. a physical device plus a running emulator), `adb` standard practice is to set `ANDROID_SERIAL=<serial>` to disambiguate. The agent honors this transparently because it runs `adb` directly. Run `adb devices` to list serials. Visual-judge runs with multiple Android targets attached will error with `more than one device/emulator` if this isn't set.
+
+The agent resolves `adb` to a known-good binary in this priority order: `$ANDROID_HOME/platform-tools/adb`, `$ANDROID_SDK_ROOT/platform-tools/adb`, `~/Library/Android/sdk/platform-tools/adb` (Android Studio default), `/Applications/android-sdk-macosx/platform-tools/adb`, `/opt/homebrew/bin/adb`, `/usr/local/bin/adb`, then PATH. This avoids surprises like a stale `~/.apportable/SDK/bin/adb` (i386, won't exec on Apple Silicon) shadowing a working `adb` on PATH.
+
+## Validation (three layers)
+
+The agent doesn't just generate code and exit — it validates the output.
+
+1. **Structural.** `ripgrep` for leftover domain tokens; OpenAPI contract parity check between Rails, iOS networking, and Android repository layers. A silent rename inconsistency fails the run before any tests execute.
+2. **Runtime.** Boot the generated Rails server; build and launch iOS and Android apps; drive a scripted CRUD scenario via [`mobile-next/mobile-mcp`](https://github.com/mobile-next/mobile-mcp). Any 4xx/5xx or unhandled client error fails the run.
+3. **Semantic.** Opus 4.7 as judge — scores whether the generated code and rendered UI actually express the intended domain. Vision judges read simulator/emulator screenshots directly.
+
+See [`docs/SPEC.md`](./docs/SPEC.md) for the full design.
+
+## Security
+
+`ANTHROPIC_API_KEY` is the only sensitive secret the agent needs.
+
+**Workspace isolation (optional but recommended).** If you also use Claude Code or other Anthropic SDK apps, create a [dedicated workspace](https://console.anthropic.com/settings/workspaces) with its own key + spend cap and export it as `NATIVEAPPTEMPLATE_AGENT_ANTHROPIC_KEY`. The agent prefers that var over `ANTHROPIC_API_KEY` when set, so a runaway loop hits the workspace cap instead of your overall tier limit, and revoking it doesn't break Claude Code login.
+
+**Recommended storage** (best to most convenient):
+
+- **macOS Keychain via 1Password CLI** — `op read "op://Personal/Anthropic/key"` resolved at session start; no key on disk in plaintext.
+- **[`direnv`](https://direnv.net/)** — per-project `.envrc`, loaded only when you `cd` in. Keep `.envrc` outside any git-tracked dotfiles repo, or `.gitignore` it.
+- **A gitignored secrets file sourced from your shell rc** — e.g. `[ -r ~/.config/zsh/secrets.zsh ] && source ~/.config/zsh/secrets.zsh`. Set `chmod 600` on the file.
+- **`.env` next to the project** — copy [`.env.example`](./.env.example) to `.env` (already gitignored along with `.env*.local`) and the agent loads it on startup. Shell exports take precedence over `.env`, so you can override per-run with `FOO=x npm run dev`. Lowest friction; easiest to leak — avoid in shared repos. `chmod 600 .env` on shared machines.
+
+**Don't** paste a real key into shell history (`HISTFILE` captures it), commit a `.env`, or echo the key into a non-private channel.
+
+The agent strips `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, and `NATIVEAPPTEMPLATE_AGENT_ANTHROPIC_KEY` from the environment of every subprocess it spawns — Ruby scripts, `git`, `psql`, `xcodebuild`, `gradlew`, the future mobile-mcp client. Keys are only seen by the Anthropic SDK in the Node process. Set spend limits on your API workspace as a backstop, and rotate the key if you suspect leak.
+
+## Project docs
+
+- [`docs/SPEC.md`](./docs/SPEC.md) — full technical specification
+- [`ROADMAP.md`](./ROADMAP.md) — where this project is headed, OSS vs hosted, what stays out of scope
+- [`CLAUDE.md`](./CLAUDE.md) — Claude Code project instructions (read if you're running Claude Code against this repo)
+
+## Contributing
+
+During hackathon week (April 21–27, 2026) the repository moves quickly and breaking changes are expected. After that, contributions are welcome via standard GitHub issues and PRs. A `CONTRIBUTING.md` with detailed guidelines will land once the hackathon dust settles.
+
+If you spot something broken before then, feel free to open an issue — just don't be surprised if the fix lands as part of a larger rewrite.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).
+
+## Acknowledgments
+
+- [Anthropic](https://www.anthropic.com) for Claude Opus 4.7 and Claude Code
+- [Cerebral Valley](https://cerebralvalley.ai) for running the hackathon
+- [`mobile-next/mobile-mcp`](https://github.com/mobile-next/mobile-mcp) for making mobile UI automation actually workable from an agent
+- [MyTurnTag Creator](https://myturntag.com) users, whose real-world queue management taught me which abstractions survive and which don't
+
+---
+
+*Built solo in Tokyo.*

package/dist/adb.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveAdbPath(): string;
+//# sourceMappingURL=adb.d.ts.map

package/dist/adb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adb.d.ts","sourceRoot":"","sources":["../src/adb.ts"],"names":[],"mappings":"AAgBA,wBAAgB,cAAc,IAAI,MAAM,CAavC"}

package/dist/adb.js

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// Some dev machines have a stale `adb` shadowing the modern one on PATH —
+// the canonical case is /Users/<u>/.apportable/SDK/bin/adb, an i386 binary
+// from 2014 that fails to exec on Apple Silicon with "Unknown system error
+// -86". Resolve to a known-good adb instead of trusting PATH order:
+//
+//   1. $ANDROID_HOME/platform-tools/adb           (canonical env var)
+//   2. $ANDROID_SDK_ROOT/platform-tools/adb       (legacy spelling)
+//   3. ~/Library/Android/sdk/platform-tools/adb   (Android Studio default on macOS)
+//   4. /Applications/android-sdk-macosx/platform-tools/adb  (older macOS standalone install)
+//   5. /opt/homebrew/bin/adb                      (Homebrew on Apple Silicon)
+//   6. /usr/local/bin/adb                         (Homebrew on Intel)
+//   7. "adb"                                      (fall back to PATH lookup)
+export function resolveAdbPath() {
+    const candidates = [
+        process.env['ANDROID_HOME'] ? join(process.env['ANDROID_HOME'], "platform-tools", "adb") : null,
+        process.env['ANDROID_SDK_ROOT'] ? join(process.env['ANDROID_SDK_ROOT'], "platform-tools", "adb") : null,
+        join(homedir(), "Library", "Android", "sdk", "platform-tools", "adb"),
+        "/Applications/android-sdk-macosx/platform-tools/adb",
+        "/opt/homebrew/bin/adb",
+        "/usr/local/bin/adb",
+    ];
+    for (const candidate of candidates) {
+        if (candidate && existsSync(candidate))
+            return candidate;
+    }
+    return "adb";
+}
+//# sourceMappingURL=adb.js.map

package/dist/adb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adb.js","sourceRoot":"","sources":["../src/adb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,0EAA0E;AAC1E,2EAA2E;AAC3E,2EAA2E;AAC3E,oEAAoE;AACpE,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,oFAAoF;AACpF,6FAA6F;AAC7F,8EAA8E;AAC9E,sEAAsE;AACtE,6EAA6E;AAC7E,MAAM,UAAU,cAAc;IAC5B,MAAM,UAAU,GAAG;QACjB,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;QAC/F,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;QACvG,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,CAAC;QACrE,qDAAqD;QACrD,uBAAuB;QACvB,oBAAoB;KACrB,CAAC;IACF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,SAAS,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/agents/contract-extract.d.ts

@@ -0,0 +1,26 @@
+export type Endpoint = {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+};
+export type ContractDiff = {
+    railsOnly: Endpoint[];
+    iosOrphan: Endpoint[];
+    androidOrphan: Endpoint[];
+    iosOnly: Endpoint[];
+    androidOnly: Endpoint[];
+};
+export type CanonicalizationContext = {
+    role: string;
+};
+export declare function canonicalizeEndpoint(endpoint: Endpoint, ctx: CanonicalizationContext): Endpoint;
+export declare function diffContracts(rails: readonly Endpoint[], ios: readonly Endpoint[], android: readonly Endpoint[], ctx: CanonicalizationContext): ContractDiff;
+export type RailsContract = {
+    openapiVersion: string;
+    title: string;
+    endpoints: Endpoint[];
+    schemaCount: number;
+};
+export declare function extractRailsContract(railsDir: string): Promise<RailsContract | null>;
+export declare function extractAndroidEndpoints(androidDir: string): Promise<Endpoint[]>;
+export declare function extractIosEndpoints(iosDir: string): Promise<Endpoint[]>;
+//# sourceMappingURL=contract-extract.d.ts.map

package/dist/agents/contract-extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-extract.d.ts","sourceRoot":"","sources":["../../src/agents/contract-extract.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IAIzB,SAAS,EAAE,QAAQ,EAAE,CAAC;IAGtB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,aAAa,EAAE,QAAQ,EAAE,CAAC;IAG1B,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,WAAW,EAAE,QAAQ,EAAE,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IAIpC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAYF,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,uBAAuB,GAC3B,QAAQ,CAsBV;AAID,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,GAAG,EAAE,SAAS,QAAQ,EAAE,EACxB,OAAO,EAAE,SAAS,QAAQ,EAAE,EAC5B,GAAG,EAAE,uBAAuB,GAC3B,YAAY,CA8Bd;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAMF,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAsC1F;AAMD,wBAAsB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAmBrF;AAKD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAgB7E"}

package/dist/agents/contract-extract.js

@@ -0,0 +1,205 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+const TENANT_PLACEHOLDER = "{account_id}";
+const UUID_RE = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const OPENAPI_PARAM_RE = /^\{[^}]+\}$/;
+const SWIFT_INTERPOLATION_RE = /^\\\([^)]+\)$/;
+// Strip tenant prefix, /api/v1, role segment, and normalize path parameter
+// names to {*} so the three platforms' encodings reduce to the same
+// comparable string. Rails OpenAPI server URLs (e.g. `/api/v1/vet`) are
+// already factored out by extractRailsContract, so Rails endpoints arrive
+// here with just the per-operation path.
+export function canonicalizeEndpoint(endpoint, ctx) {
+    const role = ctx.role.toLowerCase();
+    const segments = endpoint.path.split("/").filter(Boolean);
+    // Drop tenant segment (literal placeholder or runtime UUID).
+    if (segments[0] === TENANT_PLACEHOLDER || (segments[0] && UUID_RE.test(segments[0]))) {
+        segments.shift();
+    }
+    // Drop /api/v<N>/.
+    if (segments[0] === "api") {
+        segments.shift();
+        if (segments[0] && /^v\d+$/.test(segments[0]))
+            segments.shift();
+    }
+    // Drop role segment.
+    if (segments[0] === role)
+        segments.shift();
+    // Normalize path-param names to {*} so {shopId} === {id} === \(id).
+    const normalized = segments.map((s) => OPENAPI_PARAM_RE.test(s) || SWIFT_INTERPOLATION_RE.test(s) ? "{*}" : s);
+    return { method: endpoint.method, path: "/" + normalized.join("/") };
+}
+// Three-way diff. Endpoints are first canonicalized so cross-platform
+// encoding differences don't show up as drift.
+export function diffContracts(rails, ios, android, ctx) {
+    const canon = (e) => canonicalizeEndpoint(e, ctx);
+    const key = (e) => `${e.method} ${e.path}`;
+    const railsSet = new Map(rails.map(canon).map((e) => [key(e), e]));
+    const iosSet = new Map(ios.map(canon).map((e) => [key(e), e]));
+    const androidSet = new Map(android.map(canon).map((e) => [key(e), e]));
+    const railsOnly = [];
+    for (const [k, e] of railsSet) {
+        if (!iosSet.has(k) && !androidSet.has(k))
+            railsOnly.push(e);
+    }
+    const iosOrphan = [];
+    for (const [k, e] of iosSet) {
+        if (!railsSet.has(k))
+            iosOrphan.push(e);
+    }
+    const androidOrphan = [];
+    for (const [k, e] of androidSet) {
+        if (!railsSet.has(k))
+            androidOrphan.push(e);
+    }
+    const iosOnly = [];
+    for (const [k, e] of iosSet) {
+        if (railsSet.has(k) && !androidSet.has(k))
+            iosOnly.push(e);
+    }
+    const androidOnly = [];
+    for (const [k, e] of androidSet) {
+        if (railsSet.has(k) && !iosSet.has(k))
+            androidOnly.push(e);
+    }
+    return { railsOnly, iosOrphan, androidOrphan, iosOnly, androidOnly };
+}
+const HTTP_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+// Rails: parse out/<slug>/rails/docs/openapi.yaml. Returns null if the file
+// is missing or doesn't have the canonical OpenAPI 3.x shape.
+export async function extractRailsContract(railsDir) {
+    const specPath = join(railsDir, "docs", "openapi.yaml");
+    let raw;
+    try {
+        raw = await readFile(specPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let doc;
+    try {
+        doc = parseYaml(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(doc))
+        return null;
+    const openapiVersion = typeof doc["openapi"] === "string" ? doc["openapi"] : null;
+    if (!openapiVersion)
+        return null;
+    const info = isRecord(doc["info"]) ? doc["info"] : {};
+    const title = typeof info["title"] === "string" ? info["title"] : "";
+    const paths = isRecord(doc["paths"]) ? doc["paths"] : {};
+    const endpoints = [];
+    for (const [path, value] of Object.entries(paths)) {
+        if (!isRecord(value))
+            continue;
+        for (const verb of Object.keys(value)) {
+            const upper = verb.toUpperCase();
+            if (HTTP_METHODS.has(upper)) {
+                endpoints.push({ method: upper, path });
+            }
+        }
+    }
+    const components = isRecord(doc["components"]) ? doc["components"] : {};
+    const schemas = isRecord(components["schemas"]) ? components["schemas"] : {};
+    const schemaCount = Object.keys(schemas).length;
+    return { openapiVersion, title, endpoints, schemaCount };
+}
+// Android: walk app/src/main/kotlin/**/data/**/*Api.kt, extract Retrofit
+// annotations (@GET("path"), @POST("path"), etc.). The substrate's auth
+// data layer also lives under data/login/, so capture all *Api.kt under
+// data/.
+export async function extractAndroidEndpoints(androidDir) {
+    const dataDir = join(androidDir, "app", "src", "main", "kotlin");
+    const apiFiles = await collectFiles(dataDir, (path) => /\/data\/.*Api\.kt$/.test(path));
+    const endpoints = [];
+    const re = /@(GET|POST|PUT|PATCH|DELETE)\(\s*"([^"]+)"\s*\)/g;
+    for (const file of apiFiles) {
+        let raw;
+        try {
+            raw = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        let match;
+        while ((match = re.exec(raw)) !== null) {
+            endpoints.push({ method: match[1], path: match[2] });
+        }
+    }
+    return endpoints;
+}
+// iOS: walk **/Networking/**/*Request.swift and Login/*Request.swift, where
+// each struct has matched `var method: HTTPMethod { .METHOD }` and
+// `var path: String { "..." }` getters. Pair them by struct order.
+export async function extractIosEndpoints(iosDir) {
+    const appDir = await findAppRoot(iosDir);
+    if (!appDir)
+        return [];
+    const requestFiles = await collectFiles(appDir, (path) => /Request\.swift$/.test(path));
+    const endpoints = [];
+    for (const file of requestFiles) {
+        let raw;
+        try {
+            raw = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        endpoints.push(...parseSwiftRequests(raw));
+    }
+    return endpoints;
+}
+function parseSwiftRequests(raw) {
+    // Split on `struct ... {` boundaries; within each chunk, find the first
+    // `.METHOD` enum reference and the first `"..."` string literal that follows
+    // a `var path` declaration. Crude but robust for the substrate's layout.
+    const structs = raw.split(/\nstruct\s+\w+\b/).slice(1);
+    const out = [];
+    for (const chunk of structs) {
+        const methodMatch = chunk.match(/var\s+method:\s*HTTPMethod\s*\{\s*\.(GET|POST|PUT|PATCH|DELETE)\s*\}/);
+        const pathMatch = chunk.match(/var\s+path:\s*String\s*\{\s*"([^"]+)"\s*\}/);
+        if (methodMatch && pathMatch) {
+            out.push({ method: methodMatch[1], path: pathMatch[1] });
+        }
+    }
+    return out;
+}
+async function findAppRoot(iosDir) {
+    const entries = await readdir(iosDir, { withFileTypes: true }).catch(() => []);
+    for (const e of entries) {
+        if (e.isDirectory() && !e.name.endsWith(".xcodeproj") && !e.name.endsWith("Tests") && !e.name.startsWith(".")) {
+            const candidate = join(iosDir, e.name);
+            const sub = await readdir(candidate).catch(() => []);
+            if (sub.some((n) => n === "Networking" || n === "Login"))
+                return candidate;
+        }
+    }
+    return null;
+}
+async function collectFiles(root, predicate) {
+    const out = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const e of entries) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (e.name === ".git" || e.name === "build" || e.name === ".gradle" || e.name === "Pods")
+                    continue;
+                await walk(full);
+            }
+            else if (predicate(full)) {
+                out.push(full);
+            }
+        }
+    }
+    await walk(root);
+    return out;
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+//# sourceMappingURL=contract-extract.js.map