ios-app-review-plugin 1.0.0

package/docs/SECURITY.md

@@ -0,0 +1,89 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.0.x | Yes |
+| 0.4.x | Security fixes only |
+| < 0.4 | No |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in the iOS App Review Plugin, please report it responsibly.
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Instead, send a private report:
+
+1. Email: Send details to the repository maintainer via the email listed in the npm package or GitHub profile.
+2. GitHub Security Advisories: Use the [private vulnerability reporting feature](https://github.com/ahmetsina/ios-app-review-plugin/security/advisories/new) on the repository.
+
+### What to Include
+
+- Description of the vulnerability
+- Steps to reproduce
+- Affected versions
+- Potential impact
+- Suggested fix (if any)
+
+### Response Timeline
+
+- **Acknowledgment:** Within 48 hours
+- **Assessment:** Within 5 business days
+- **Fix timeline:** Depends on severity (critical: 7 days, high: 14 days, medium: 30 days)
+
+## Security Considerations
+
+### App Store Connect Credentials
+
+The plugin uses ASC API credentials (Key ID, Issuer ID, private key) for App Store Connect validation. These credentials:
+
+- Are read from environment variables (`ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_PRIVATE_KEY_PATH`)
+- Are never logged, stored, or transmitted outside the ASC API
+- Are used only to generate short-lived JWTs for ASC API calls
+- Should be stored in your CI platform's secrets management
+
+**Never commit `.p8` private key files to version control.**
+
+### File System Access
+
+The plugin reads files from the specified project path and its subdirectories. It:
+
+- Reads source files (`.swift`, `.m`, `.mm`, `.h`, `.c`, `.cpp`), plists, storyboards, asset catalogs
+- Does not modify any project files
+- Does not execute any project code
+- Does not download or install any dependencies from the project
+- Writes only to explicitly specified output paths (report files, badge SVG, history store)
+
+### Scan History Storage
+
+When `--save-history` is used, scan results are stored as JSON files in a `.ios-review-history` directory near the project. These files contain:
+
+- Issue IDs and titles
+- File paths and line numbers
+- Scores and timestamps
+- Git branch and commit info
+
+Review the history directory contents and add it to `.gitignore` if the data is sensitive.
+
+### Network Access
+
+The plugin makes network requests only when ASC validation is enabled (`--include-asc`). All requests go to Apple's App Store Connect API (`api.appstoreconnect.apple.com`) over HTTPS.
+
+No telemetry, analytics, or other network calls are made.
+
+### Dependencies
+
+The plugin uses a minimal dependency set:
+
+- `@modelcontextprotocol/sdk` -- MCP protocol
+- `fast-glob` -- File discovery
+- `plist` -- Plist parsing
+- `zod` -- Input validation
+
+All dependencies should be audited regularly:
+
+```bash
+npm audit
+```

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,227 @@
+# Troubleshooting
+
+## Installation Issues
+
+### "Cannot find module" errors after build
+
+```
+Error: Cannot find module '/path/to/dist/index.js'
+```
+
+Rebuild the project:
+
+```bash
+npm run clean && npm run build
+```
+
+### Node.js version error
+
+```
+SyntaxError: Unexpected token ...
+```
+
+The plugin requires Node.js >= 18. Check your version:
+
+```bash
+node --version
+```
+
+---
+
+## Project Parsing Errors
+
+### "No Xcode project found" or empty results
+
+The plugin looks for `.xcodeproj` or `.xcworkspace` at the specified path. Make sure you point to the right location:
+
+```bash
+# Point to the .xcodeproj file, not the directory containing it
+ios-app-review scan ./MyApp/MyApp.xcodeproj
+
+# Or the directory containing the .xcodeproj
+ios-app-review scan ./MyApp/
+```
+
+### "Failed to parse project.pbxproj"
+
+Complex `.pbxproj` files with unusual formatting may cause parse issues. Verify the file is valid:
+
+```bash
+plutil -lint ./MyApp.xcodeproj/project.pbxproj
+```
+
+If the project uses Xcode build settings variables like `$(SRCROOT)` in paths, the parser resolves these to the project's base directory.
+
+### No source files found
+
+The scanner excludes these directories by default:
+- `Pods/`
+- `Carthage/`
+- `build/`
+- `DerivedData/`
+- `Tests/`
+- `UITests/`
+- `*.generated.swift`
+
+If your source files are in an unexpected location, ensure they are referenced in the Xcode project's target or accessible under the base path.
+
+---
+
+## Info.plist Issues
+
+### "Info.plist not found at configured path"
+
+The path in the project's build settings (INFOPLIST_FILE) is relative to the project directory. The plugin resolves it automatically, but if the file was moved:
+
+1. Check the actual path: `find . -name "Info.plist"`
+2. Update the build setting in Xcode
+3. Or use `check_info_plist` directly with the absolute path
+
+### Plist parse errors
+
+Binary plists are supported. If parsing fails, convert to XML format:
+
+```bash
+plutil -convert xml1 ./MyApp/Info.plist
+```
+
+---
+
+## App Store Connect (ASC) Issues
+
+### "ASC_KEY_ID environment variable is required"
+
+Set all three required environment variables:
+
+```bash
+export ASC_KEY_ID="XXXXXXXXXX"
+export ASC_ISSUER_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+export ASC_PRIVATE_KEY_PATH="/path/to/AuthKey_XXXXXXXXXX.p8"
+```
+
+### "Unable to read private key"
+
+1. Verify the file exists and is readable:
+   ```bash
+   ls -la "$ASC_PRIVATE_KEY_PATH"
+   ```
+2. Check the file format. It should start with `-----BEGIN PRIVATE KEY-----`.
+3. Ensure no extra whitespace or characters were added during transfer.
+
+### "401 Unauthorized" from ASC API
+
+- **Key expired or revoked:** Regenerate the key in App Store Connect > Users and Access > Keys.
+- **Wrong Issuer ID:** The Issuer ID is shown at the top of the Keys page, not on individual key rows.
+- **Insufficient permissions:** The API key must have at least "App Manager" role.
+- **Clock skew:** JWT tokens include timestamps. Ensure your system clock is accurate.
+
+### "404 Not Found" for bundle ID
+
+The bundle ID must match an app that exists in your App Store Connect account. Check:
+
+```bash
+# List apps (requires ASC CLI or API)
+# The bundleId is case-sensitive
+```
+
+### Rate limiting
+
+The ASC API client includes built-in rate limiting. If you see rate limit errors, the client will automatically retry after the specified delay. For parallel CI builds, consider staggering ASC validation steps.
+
+---
+
+## Custom Rules Issues
+
+### "No .ios-review-rules.json found"
+
+The rule loader searches from the project directory upward. Place the file:
+- In the project root (next to `.xcodeproj`)
+- Or in any parent directory
+- Or specify explicitly: `--config ./path/to/rules.json`
+
+### "Custom rules validation FAILED"
+
+Common issues:
+- **Invalid JSON:** Run `jq . .ios-review-rules.json` to validate syntax.
+- **Missing required fields:** Every rule needs `id`, `title`, `description`, `severity`, and `pattern`.
+- **version must be 1:** The schema version must be the literal number `1`.
+- **Invalid severity:** Must be `"error"`, `"warning"`, or `"info"`.
+
+### Regex pattern not matching
+
+- Backslashes must be double-escaped in JSON: `\\b` for `\b`, `\\s` for `\s`.
+- Test patterns in JavaScript: `new RegExp("your-pattern", "g")`.
+- Ensure the `flags` field is set (default: `"g"`). Without `g`, only the first match per file is reported.
+
+---
+
+## Large Project Performance
+
+### Scan takes too long
+
+1. **Use incremental scanning:**
+   ```bash
+   ios-app-review scan ./MyApp.xcodeproj --changed-since main
+   ```
+
+2. **Run specific analyzers:**
+   ```bash
+   ios-app-review scan ./MyApp.xcodeproj --analyzers code,security
+   ```
+
+3. **Exclude unnecessary targets:** The plugin analyzes all application targets by default. If you have multiple targets, use the `targetName` parameter (MCP) to focus on one.
+
+### Memory issues on very large projects
+
+For projects with thousands of source files, Node.js may need more heap space:
+
+```bash
+NODE_OPTIONS="--max-old-space-size=4096" ios-app-review scan ./MyApp.xcodeproj
+```
+
+---
+
+## History and Comparison Issues
+
+### "No previous scan found"
+
+Run a scan with `--save-history` first to create the baseline:
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --save-history
+```
+
+History is stored in `.ios-review-history/` near the project directory.
+
+### History directory location
+
+The history store writes to a `.ios-review-history` directory in the parent directory of the resolved project path. For example, if your project is at `/code/MyApp/MyApp.xcodeproj`, history is stored in `/code/MyApp/.ios-review-history/`.
+
+---
+
+## MCP Server Issues
+
+### Server does not start
+
+When run without arguments, the binary starts as an MCP server on stdio. Ensure your MCP client configuration points to the correct path:
+
+```json
+{
+  "ios-app-review": {
+    "command": "node",
+    "args": ["/absolute/path/to/ios-app-review-plugin/dist/index.js"]
+  }
+}
+```
+
+### "Unknown tool" errors
+
+Verify you are calling tools with their exact names. Tool names use underscores, not hyphens: `analyze_ios_app`, not `analyze-ios-app`.
+
+### Server crashes silently
+
+Check stderr output. The server logs startup and fatal errors to stderr:
+
+```bash
+node dist/index.js 2>server.log
+```

package/docs/tutorials/ASC_SETUP.md

@@ -0,0 +1,188 @@
+# App Store Connect Setup Tutorial
+
+This tutorial walks through generating an API key, configuring environment variables, and using the ASC validation tools.
+
+## Overview
+
+The ASC validators check your app's metadata, screenshots, version info, and in-app purchases directly against the App Store Connect API. This catches issues that are only visible in ASC, like missing screenshot sizes, incomplete localizations, or version conflicts.
+
+**Requirements:**
+- An Apple Developer Program membership
+- Admin or App Manager access to App Store Connect
+- An app already created in App Store Connect
+
+## Step 1: Generate an API Key
+
+1. Open [App Store Connect](https://appstoreconnect.apple.com/).
+2. Navigate to **Users and Access** > **Integrations** > **App Store Connect API**.
+3. Click **Generate API Key** (or the "+" button).
+4. Name it something descriptive: `ios-app-review-ci`.
+5. Select the **App Manager** role (minimum required).
+6. Click **Generate**.
+
+You will see:
+- **Key ID**: A 10-character alphanumeric string (e.g., `ABC1234DEF`)
+- **Issuer ID**: A UUID shown at the top of the page (e.g., `12345678-abcd-efgh-ijkl-123456789012`)
+
+7. Click **Download API Key** to get the `.p8` file. You can only download this once.
+
+Save the `.p8` file securely. A typical location:
+
+```
+~/.appstoreconnect/AuthKey_ABC1234DEF.p8
+```
+
+## Step 2: Configure Environment Variables
+
+Set three environment variables:
+
+```bash
+export ASC_KEY_ID="ABC1234DEF"
+export ASC_ISSUER_ID="12345678-abcd-efgh-ijkl-123456789012"
+export ASC_PRIVATE_KEY_PATH="$HOME/.appstoreconnect/AuthKey_ABC1234DEF.p8"
+```
+
+For persistent configuration, add these to your shell profile (`~/.zshrc` or `~/.bashrc`).
+
+### For CI Systems
+
+| Platform | How to store |
+|----------|-------------|
+| GitHub Actions | Settings > Secrets > Add `ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_PRIVATE_KEY` (file contents) |
+| Fastlane | `.env` file or Fastlane Match |
+| Bitrise | Secrets tab in workflow editor |
+| Xcode Cloud | Workflow > Environment Variables |
+
+In CI, you typically store the `.p8` file contents as a secret and write it to a temp file:
+
+```bash
+echo "$ASC_PRIVATE_KEY" > /tmp/AuthKey.p8
+export ASC_PRIVATE_KEY_PATH=/tmp/AuthKey.p8
+```
+
+## Step 3: Verify the Connection
+
+### Using the CLI
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --include-asc --analyzers asc-metadata
+```
+
+If credentials are correct, you will see metadata validation results. If not, you will get an authentication error.
+
+### Using the MCP Tool
+
+In Claude Code:
+
+```
+Validate the App Store Connect metadata for bundle ID com.mycompany.myapp
+```
+
+This calls the `validate_asc_metadata` tool.
+
+## Step 4: Run ASC Validators
+
+### Individual Validators
+
+**Metadata check:**
+
+```bash
+# Via MCP
+validate_asc_metadata with bundleId "com.mycompany.myapp"
+```
+
+Checks: app name length, subtitle, description, keywords, privacy policy URL, support URL, marketing URL.
+
+**Screenshots check:**
+
+```bash
+# Via MCP
+validate_asc_screenshots with bundleId "com.mycompany.myapp"
+```
+
+Checks: required device sizes present, screenshot counts per locale, no failed uploads.
+
+**Version comparison:**
+
+```bash
+# Via MCP
+compare_versions with bundleId "com.mycompany.myapp", localVersion "2.1.0", localBuild "45"
+```
+
+Checks: version/build number increments, submission status, release notes presence.
+
+**IAP validation:**
+
+```bash
+# Via MCP
+validate_iap with bundleId "com.mycompany.myapp"
+```
+
+Checks: localized names/descriptions, review screenshots, submission readiness.
+
+### Full ASC Validation
+
+Run all four validators at once:
+
+```bash
+# Via MCP
+full_asc_validation with bundleId "com.mycompany.myapp"
+```
+
+Or via CLI:
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --include-asc
+```
+
+## Step 5: Understand ASC Results
+
+ASC issues use these categories:
+
+| Category | Validator |
+|----------|-----------|
+| `metadata` | asc-metadata |
+| `screenshots` | asc-screenshots |
+| `version` | asc-version |
+| `iap` | asc-iap |
+
+Common findings:
+
+- **Missing privacy policy URL** -- Required for all apps. Add in App Store Connect > App Information.
+- **App name too long** -- Must be 30 characters or fewer.
+- **Missing screenshots for device** -- iPhone 6.7" and 6.5" are required. iPad 12.9" if supporting iPad.
+- **Failed screenshot uploads** -- Re-upload screenshots that show "processing failed" status.
+- **Version not incremented** -- The new version must be higher than the current App Store version.
+- **IAP missing review screenshot** -- Each IAP needs a screenshot for Apple's review team.
+- **IAP missing localization** -- Name and description must be provided in at least one language.
+
+## Troubleshooting
+
+### "401 Unauthorized"
+
+- Verify the Key ID matches the downloaded key.
+- Verify the Issuer ID (shown at the top of the Keys page, not per-key).
+- Regenerate the key if it was revoked.
+- Check system clock accuracy (JWT tokens are time-sensitive).
+
+### "404 Not Found" for bundle ID
+
+- The bundle ID is case-sensitive.
+- The app must exist in your ASC account.
+- The API key must have access to the app (check team membership).
+
+### Rate Limiting
+
+The ASC API has rate limits. The client handles retries automatically. If running in parallel CI jobs, stagger ASC checks or use a shared rate limiter.
+
+### Permission Errors
+
+The API key needs at least **App Manager** role. **Developer** role is insufficient for reading all metadata.
+
+## Security Notes
+
+- Never commit `.p8` files to version control.
+- Add to `.gitignore`: `*.p8`, `AuthKey_*.p8`.
+- Use CI secrets for all three credential values.
+- The plugin generates short-lived JWT tokens (20-minute expiry) and does not persist credentials.
+- Delete temp key files after CI runs: `rm /tmp/AuthKey.p8`.