fsq-mac 0.1.1__tar.gz

fsq_mac-0.1.1/.claude/skills/mac-automation.md

@@ -0,0 +1,206 @@
+# macOS Automation with fsq-mac
+
+Use when the user asks to automate, interact with, test, or control a macOS native application. Triggers: mac automation, click button, UI testing, accessibility, element inspect, screenshot, app launch, macOS app, native app automation.
+
+## Prerequisites
+
+- Appium server running (`appium` in a terminal)
+- Mac2 driver installed (`appium driver install mac2`)
+- macOS Accessibility permissions granted
+- Run `mac doctor` to verify setup
+
+## Core Workflow
+
+Every automation session follows this pattern:
+
+1. **Start session** — `mac session start`
+2. **Launch/activate app** — `mac app launch <bundle_id>`
+3. **Inspect UI** — `mac element inspect` to discover elements
+4. **Act** — click, type, scroll, etc. using element refs (e0, e1, ...)
+5. **Verify** — `mac capture screenshot` or re-inspect to confirm result
+6. **End session** — `mac session end`
+
+## Command Reference
+
+### Session
+| Command | Description |
+|---------|-------------|
+| `mac session start` | Start a new automation session |
+| `mac session get` | Get current session info |
+| `mac session list` | List all sessions |
+| `mac session end` | End current session |
+
+### Application
+| Command | Description |
+|---------|-------------|
+| `mac app launch <bundle_id>` | Launch app (e.g. `com.apple.calculator`) |
+| `mac app activate <bundle_id>` | Bring app to front |
+| `mac app current` | Get frontmost app info |
+| `mac app list` | List running apps |
+| `mac app terminate <bundle_id>` | Terminate app (requires `--allow-dangerous`) |
+
+### Element
+| Command | Description |
+|---------|-------------|
+| `mac element inspect` | List all visible UI elements with refs (e0, e1, ...) |
+| `mac element find <locator>` | Find element by locator value |
+| `mac element click <ref>` | Click element (e.g. `e5`) |
+| `mac element right-click <ref>` | Right-click element |
+| `mac element double-click <ref>` | Double-click element |
+| `mac element type <ref> <text>` | Type text into element |
+| `mac element scroll <ref> [up|down|left|right]` | Scroll element |
+| `mac element hover <ref>` | Hover over element |
+| `mac element drag <source> <target>` | Drag from source to target element |
+
+### Input (no element target)
+| Command | Description |
+|---------|-------------|
+| `mac input key <key>` | Press key (return, space, tab, escape, etc.) |
+| `mac input hotkey <combo>` | Key combo (e.g. `command+c`, `command+shift+s`) |
+| `mac input text <text>` | Type text to focused element |
+
+### Capture
+| Command | Description |
+|---------|-------------|
+| `mac capture screenshot [path]` | Take screenshot (default: ./screenshot.png) |
+| `mac capture screenshot --element <ref> [path]` | Screenshot a specific element |
+| `mac capture screenshot --rect x,y,w,h [path]` | Screenshot a region |
+| `mac capture ui-tree` | Get raw UI element tree (XML) |
+
+### Window
+| Command | Description |
+|---------|-------------|
+| `mac window current` | Get frontmost window info |
+| `mac window list` | List windows of managed app |
+| `mac window focus <index>` | Focus window by index |
+
+### Wait
+| Command | Description |
+|---------|-------------|
+| `mac wait element <locator>` | Wait for element to appear |
+| `mac wait window <title>` | Wait for window to appear |
+| `mac wait app <bundle_id>` | Wait for app to start |
+
+### Doctor
+| Command | Description |
+|---------|-------------|
+| `mac doctor` | Run all diagnostics |
+| `mac doctor permissions` | Check Accessibility permissions |
+| `mac doctor backend` | Check Appium server and Mac2 driver |
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--session <id>` | Target a specific session (default: most recent) |
+| `--strategy <strategy>` | Locator strategy: accessibility_id, name, xpath, class_name, ios_predicate |
+| `--timeout <ms>` | Timeout in milliseconds (default: 120000) |
+| `--pretty` | Human-friendly output (default: compact JSON for agents) |
+| `--allow-dangerous` | Allow dangerous operations (e.g. app terminate) |
+| `--version` | Show version |
+
+## Response Format
+
+Every command returns a JSON envelope:
+
+```json
+{
+  "ok": true,
+  "command": "element.click",
+  "session_id": "s1",
+  "data": {},
+  "error": null,
+  "meta": {
+    "backend": "appium_mac2",
+    "duration_ms": 1234,
+    "timestamp": "2026-04-03T10:00:00Z",
+    "frontmost_app": "com.apple.calculator",
+    "frontmost_window": "Calculator"
+  }
+}
+```
+
+On error:
+
+```json
+{
+  "ok": false,
+  "command": "element.click",
+  "error": {
+    "code": "ELEMENT_NOT_FOUND",
+    "message": "Element 'e5' not found",
+    "retryable": true,
+    "suggested_next_action": "mac element inspect",
+    "doctor_hint": null
+  }
+}
+```
+
+## Error Recovery
+
+When a command fails, check `error.code` and follow this recovery strategy:
+
+| Error Code | Recovery |
+|------------|----------|
+| `SESSION_NOT_FOUND` | Run `mac session start` |
+| `BACKEND_UNAVAILABLE` | Run `mac doctor backend`, ensure Appium is running |
+| `ELEMENT_NOT_FOUND` | Run `mac element inspect` to refresh elements, find correct ref |
+| `ELEMENT_REFERENCE_STALE` | Run `mac element inspect` — refs are invalidated after mutations |
+| `ELEMENT_AMBIGUOUS` | Use `--first-match` or refine the locator strategy |
+| `TYPE_VERIFICATION_FAILED` | Typed value didn't match; re-type or verify the target field |
+| `ACTION_BLOCKED` | Add `--allow-dangerous` flag for dangerous operations |
+| `TIMEOUT` | Increase `--timeout` or check if the target exists |
+| `PERMISSION_DENIED` | Run `mac doctor permissions` and grant Accessibility access |
+
+## Element References
+
+- `mac element inspect` assigns refs: `e0`, `e1`, `e2`, ...
+- Refs are **scoped to the last inspect/find** — a new inspect invalidates all previous refs
+- After any mutation (click, type, etc.), refs may become stale
+- Pattern: **inspect -> act -> re-inspect** for multi-step flows
+
+## Safety Model
+
+Commands are classified into three safety levels:
+
+- **SAFE** — read-only operations (inspect, screenshot, list, wait, doctor)
+- **GUARDED** — operations that modify state (click, type, launch, activate)
+- **DANGEROUS** — destructive operations (terminate) — requires `--allow-dangerous`
+
+## Common Patterns
+
+### Calculator: 5 + 3
+
+```bash
+mac session start
+mac app launch com.apple.calculator
+mac element inspect                  # discover elements
+mac element click e5                 # click "5"
+mac element inspect                  # re-inspect after mutation
+mac element click e2                 # click "+"
+mac element inspect
+mac element click e3                 # click "3"
+mac element inspect
+mac element click e8                 # click "="
+mac capture screenshot ./result.png  # verify result
+mac session end
+```
+
+### Type text into a search field
+
+```bash
+mac session start
+mac app activate com.apple.safari
+mac element inspect                      # find the search field
+mac element type e12 "hello world"       # type into it
+mac input hotkey command+a               # select all
+mac capture screenshot ./typed.png
+```
+
+### Tips
+
+- Always run `mac element inspect` before interacting with elements
+- After any click/type, run `mac element inspect` again — refs are invalidated
+- Use `mac capture screenshot` to visually verify results between steps
+- Use `--pretty` when debugging interactively, omit for agent consumption
+- Common bundle IDs: `com.apple.calculator`, `com.apple.Safari`, `com.apple.finder`, `com.apple.TextEdit`, `com.apple.systempreferences`

fsq_mac-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest tests/ --junitxml=test-results/junit.xml --cov=fsq_mac --cov-report=xml:test-results/coverage.xml --cov-report=term-missing
+
+      - name: Upload JUnit XML
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-results-py${{ matrix.python-version }}
+          path: test-results/junit.xml
+          if-no-files-found: error
+
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-py${{ matrix.python-version }}
+          path: test-results/coverage.xml
+          if-no-files-found: ignore
+
+      - name: Upload runtime artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: runtime-artifacts-py${{ matrix.python-version }}
+          path: artifacts/
+          if-no-files-found: ignore

fsq_mac-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest tests/ --junitxml=test-results/junit.xml --cov=fsq_mac --cov-report=xml:test-results/coverage.xml --cov-report=term-missing
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: pypi
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fsq_mac-0.1.1/.gitignore

@@ -0,0 +1,39 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# State directory (local)
+.fsq-mac/
+
+# Config (user-specific)
+src/fsq_mac/conf/appium_conf.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test artifacts
+.pytest_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Runtime artifacts
+artifacts/

fsq_mac-0.1.1/CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md
+
+## Project Overview
+
+fsq-mac is an agent-first macOS native application automation CLI. It uses a daemon/client architecture where the CLI communicates over HTTP with a Starlette/Uvicorn daemon that drives Appium Mac2.
+
+## Build & Run
+
+```bash
+# Install dependencies
+uv sync
+
+# Install with dev dependencies
+uv sync --group dev
+
+# Run tests
+uv run pytest tests/ -v
+
+# Run the CLI
+uv run mac session start
+```
+
+## Architecture
+
+```
+src/fsq_mac/
+├── cli.py              # CLI entry point (argparse)
+├── client.py           # HTTP client → daemon
+├── daemon.py           # Starlette HTTP daemon
+├── core.py             # Product semantics layer
+├── session.py          # Multi-session management
+├── models.py           # Data models, ErrorCode enum, response helpers
+├── formatters.py       # Output formatters (JSON, pretty, table)
+├── doctor.py           # Environment diagnostics
+└── adapters/
+    └── appium_mac2.py  # Appium Mac2 WebDriver adapter
+```
+
+- `cli.py` → `client.py` → HTTP → `daemon.py` → `core.py` → `session.py` → `adapters/appium_mac2.py`
+- State directory: `~/.fsq-mac/`
+- Daemon auto-starts on first CLI call, auto-exits after 30 min idle
+
+## Key Conventions
+
+- **Python 3.10+**, managed with `uv`
+- **src layout**: all source under `src/fsq_mac/`, imports use `from fsq_mac.module import ...`
+- **Response envelope**: Every command returns `{"ok": bool, "data": {...}, "error": {"code": "...", "message": "...", "retryable": bool, "suggested_next_action": "..."}, "meta": {...}}`
+- **Safety classification**: SAFE / GUARDED / DANGEROUS — dangerous commands require `--allow-dangerous`
+- **Element refs**: Static refs (`e0`, `e1`, ...) bound during `element inspect`, invalidated on mutation
+- **AppleScript**: Used for frontmost app/window queries; use `_safe_applescript_str()` to prevent injection
+- **Commit messages**: Present-tense verb, first line under 50 chars

fsq_mac-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Microsoft Corporation
+
+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.

fsq_mac-0.1.1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: fsq-mac
+Version: 0.1.1
+Summary: Agent-first macOS automation CLI
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: appium-python-client>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: selenium>=4.0.0
+Requires-Dist: starlette>=0.38.0
+Requires-Dist: uvicorn>=0.30.0

fsq_mac-0.1.1/README.md

@@ -0,0 +1,124 @@
+# fsq-mac
+
+Agent-first macOS native application automation CLI.
+
+## Overview
+
+`fsq-mac` is a daemon/client CLI tool that drives macOS native applications via Appium Mac2. It is designed for AI agent consumption — every command returns a structured JSON envelope with `ok`, `error.code`, `retryable`, and `suggested_next_action` fields.
+
+## Architecture
+
+```
+CLI (cli.py) → HTTP Client → Daemon (Starlette/Uvicorn) → Core → Adapter (Appium Mac2)
+```
+
+- **Daemon auto-lifecycle**: Starts on first CLI call, auto-exits after 30 min idle
+- **Session management**: Monotonic IDs, stale cleanup on restart
+- **Safety classification**: Commands are SAFE / GUARDED / DANGEROUS (gated by `--allow-dangerous`)
+
+## Prerequisites
+
+- Python 3.10+
+- [Appium](https://appium.io/) with [mac2 driver](https://github.com/nicedoc/appium-mac2-driver)
+- macOS Accessibility permissions granted to the terminal
+
+## Install
+
+```bash
+uv sync
+```
+
+## Usage
+
+```bash
+# Start a session (daemon auto-starts)
+mac session start
+
+# Inspect the frontmost app UI tree
+mac element inspect --pretty
+
+# Click an element by ref
+mac element click e3
+
+# Type text into an element
+mac element type e5 "hello world"
+
+# Get frontmost application info
+mac app current --pretty
+
+# Get frontmost window info (title, position, size)
+mac window current --pretty
+
+# Wait for an element
+mac element wait "Submit" accessibility_id --timeout 5000
+
+# End session
+mac session end s1
+
+# Check environment
+mac doctor
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `session start` | Start automation session |
+| `session end <id>` | End a session |
+| `session list` | List active sessions |
+| `element inspect` | Inspect UI tree, bind element refs |
+| `element find <query> <by>` | Find elements by locator |
+| `element click <ref>` | Click an element |
+| `element type <ref> <text>` | Type text into an element (with verification) |
+| `element attr <ref> <name>` | Get element attribute |
+| `element scroll <ref> <dir>` | Scroll an element |
+| `element wait <query> <by>` | Wait for element to appear |
+| `app current` | Get frontmost application info |
+| `app list` | List running applications |
+| `app launch <bundle_id>` | Launch an application |
+| `app terminate <bundle_id>` | Terminate an application |
+| `app activate <bundle_id>` | Activate (bring to front) an application |
+| `window current` | Get frontmost window info (title, position, size) |
+| `window list` | List windows of frontmost app |
+| `window switch <index>` | Switch to a window by index |
+| `screenshot` | Take a screenshot |
+| `doctor` | Check environment and dependencies |
+
+
+## CI
+
+GitHub Actions runs the repository test suite from `.github/workflows/ci.yml`.
+The CI test command is `uv run pytest tests/ --junitxml=test-results/junit.xml`.
+CI uploads `test-results/junit.xml` and any generated `artifacts/` directory as workflow artifacts.
+
+## Release
+
+Package publishing is handled by `.github/workflows/publish.yml`.
+Pushing a tag matching `v*` runs the full test matrix first, then builds the wheel and sdist, and finally publishes to PyPI via Trusted Publishing if all tests pass.
+
+See [docs/releasing.md](docs/releasing.md) for the full release procedure and PyPI Trusted Publishing setup.
+
+Example:
+
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv sync --group dev
+
+# Run tests
+uv run pytest tests/ -v
+```
+
+## State Directory
+
+Session state is stored in `~/.fsq-mac/`. The daemon writes PID and port files there for lifecycle management.
+
+## License
+
+MIT