shippilot 0.0.1

package/docs/personal-chatgpt-subscription.md

@@ -0,0 +1,31 @@
+# Personal ChatGPT Subscription
+
+The clean hosted-CI path is `OPENAI_API_KEY`. Personal ChatGPT subscription auth is browser/session based and is not a first-class hosted CI credential.
+
+ShipPilot supports one experimental hosted-runner path:
+
+1. Log in locally:
+   ```bash
+   codex login
+   codex login status
+   ```
+2. Archive your Codex home:
+   ```bash
+   tar -czf codex-home.tgz ~/.codex
+   base64 -i codex-home.tgz | pbcopy
+   ```
+3. Store the result as `CODEX_HOME_TGZ_BASE64` in GitHub Secrets.
+4. Enable:
+   ```yaml
+   codex:
+     auth: chatgpt_hosted_experimental
+     allow_experimental_personal_hosted_auth: true
+   ```
+
+Warnings:
+
+- The login can expire.
+- The auth storage format can change.
+- Treat `CODEX_HOME_TGZ_BASE64` like a highly sensitive credential.
+- Never use this on untrusted fork PRs.
+- Never upload `.codex`, `auth.json`, restored auth folders, or temporary archives.

package/docs/plan.md

@@ -0,0 +1,55 @@
+# ShipPilot Full Project Plan
+
+ShipPilot is an SDK-first agentic iOS QA runner. Teams write Markdown QA cases, configure an iOS project and simulator, choose a Codex auth mode, and run the tool from GitHub Actions, Bitrise, or local CI. Codex drives the app through an iOS simulator, verifies expected outcomes, captures screenshots/logs, writes reports, and fails CI when a case fails.
+
+## Core Design
+
+- TypeScript/Node CLI published as `shippilot`.
+- Product name: ShipPilot.
+- GitHub repo: `mahmoudashraf93/ShipPilot`.
+- Primary engine: `@openai/codex-sdk`.
+- iOS automation backend: XcodeBuildMCP CLI.
+- v1 is test-and-report only: no edits, commits, patches, pushes, or PR creation.
+- `codex app-server` is reserved for future advanced integrations.
+
+## CLI
+
+```bash
+npx shippilot init
+npx shippilot doctor
+npx shippilot run --case qa/login.md
+npx shippilot run --cases qa/
+npx shippilot report --run .shippilot/run.json
+```
+
+## Auth Modes
+
+- `api_key`: uses `OPENAI_API_KEY`, recommended for hosted CI.
+- `access_token`: uses `CODEX_ACCESS_TOKEN`, recommended for trusted Business/Enterprise automation.
+- `chatgpt_hosted_experimental`: restores a pre-authenticated Codex home from `CODEX_HOME_TGZ_BASE64`; fragile and not recommended for fork PRs.
+
+## CI Semantics
+
+- `passed` exits `0`.
+- `failed` exits `1`.
+- setup/auth/config/simulator errors exit `2`.
+- `blocked` exits `3`.
+
+`codex.fail_on: never` enables report-only mode.
+
+`codex.verbose: true` or `shippilot run --verbose` streams build output and Codex SDK events for CI debugging. It shows reasoning summaries and tool activity, not private chain-of-thought.
+
+For simulator UI automation, `codex.sandbox: danger-full-access` is required because XcodeBuildMCP must communicate with CoreSimulator services outside the repository workspace.
+
+## Milestones
+
+1. Create public repo and initial docs.
+2. Scaffold TypeScript CLI.
+3. Implement config and QA case parsing.
+4. Implement auth validation and redaction.
+5. Implement XcodeBuildMCP doctor checks.
+6. Implement Codex SDK execution.
+7. Implement reports and exit codes.
+8. Add GitHub Actions and Bitrise examples.
+9. Add sample iOS app and smoke cases.
+10. Publish initial npm package as `shippilot`.

package/docs/release.md

@@ -0,0 +1,87 @@
+# Release Process
+
+This document describes how to release ShipPilot to npm.
+
+## Versioning
+
+ShipPilot uses npm semantic versions and git tags prefixed with `v`.
+
+For a release, keep these values in sync:
+
+- `package.json`
+- `package-lock.json`
+- `src/cli.ts`
+
+For example, `0.0.1` is released from git tag `v0.0.1`.
+
+## First npm Publish
+
+The first release of an unscoped package must create the package on npm before trusted publishing can be configured.
+
+For `v0.0.1`, publish once manually from a clean checkout with an npm account that has 2FA enabled:
+
+```bash
+npm login
+npm whoami
+npm ci
+npm run typecheck
+npm test
+npm pack --dry-run
+npm publish --access public
+```
+
+If `npm whoami` fails with `ENEEDAUTH`, complete `npm login` first and rerun `npm whoami` before publishing.
+
+If `npm publish` fails with `E403` saying two-factor authentication or a granular access token with bypass 2FA is required, enable 2FA on the npm account and rerun `npm publish --access public`. Alternatively, create a granular npm access token with publish access to `shippilot` and bypass 2FA enabled, then publish with `NODE_AUTH_TOKEN` set for that command.
+
+After npm publishes `shippilot@0.0.1`, confirm:
+
+```bash
+npm view shippilot version
+npx shippilot --version
+```
+
+Both commands should report `0.0.1`.
+
+## Configure Trusted Publishing
+
+After the first package exists on npm, configure trusted publishing for future releases.
+
+On npmjs.com, configure:
+
+- Package: `shippilot`
+- Publisher: GitHub Actions
+- Organization or user: `mahmoudashraf93`
+- Repository: `ShipPilot`
+- Workflow filename: `release.yml`
+- Allowed action: `npm publish`
+
+The release workflow uses GitHub OIDC with `id-token: write`, so no long-lived `NPM_TOKEN` is required for future publishes.
+
+## Future Releases
+
+For each future release:
+
+1. Update the package version, lockfile version, CLI version, and changelog.
+2. Run local checks:
+
+   ```bash
+   npm run typecheck
+   npm test
+   npm pack --dry-run --json
+   npm run build
+   node dist/cli.js --version
+   ```
+
+3. Commit the release prep.
+4. Push `main`.
+5. Create and publish a GitHub Release with a tag matching the package version, for example `v0.0.2`.
+6. Confirm the `Release` workflow completed and published the npm package.
+7. Verify:
+
+   ```bash
+   npm view shippilot version
+   npx shippilot --version
+   ```
+
+The GitHub Release must be published, not saved as a draft, because `.github/workflows/release.yml` runs on `release.published`.

package/docs/security.md

@@ -0,0 +1,39 @@
+# Security
+
+ShipPilot is designed for open-source CI, so secret handling is strict by default.
+
+## Defaults
+
+- Do not run secret-backed workflows on arbitrary fork PRs.
+- Use `actions/checkout` with `persist-credentials: false`.
+- Do not cache Codex auth by default.
+- Keep auth material in temporary directories.
+- Upload reports with `if: always()`, but never upload auth folders.
+
+## Redaction
+
+Values declared in QA case `required_env` are redacted from:
+
+- generated prompts
+- SDK output
+- logs
+- Markdown reports
+- JSON reports
+- JUnit reports
+
+## Never Upload
+
+- restored `CODEX_HOME`
+- `.codex`
+- `auth.json`
+- API keys
+- access tokens
+- restored auth archives
+
+## Test Scope
+
+v1 is test-and-report only. It instructs Codex not to edit source files, create patches, commit, push, or open pull requests.
+
+## Simulator Sandbox
+
+XcodeBuildMCP needs access to CoreSimulator services outside the repository workspace. For iOS simulator UI automation, set `codex.sandbox: danger-full-access` and run only in trusted CI contexts such as `workflow_dispatch`, release, schedule, or maintainer-approved workflows.

package/examples/bitrise/shippilot.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+npm install -g shippilot
+shippilot doctor
+shippilot run --case qa/login.md

package/examples/github-actions/shippilot.yml

@@ -0,0 +1,39 @@
+name: ShipPilot QA
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  shippilot:
+    runs-on: macos-15
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Run ShipPilot
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          CODEX_ACCESS_TOKEN: ${{ secrets.CODEX_ACCESS_TOKEN }}
+          CODEX_HOME_TGZ_BASE64: ${{ secrets.CODEX_HOME_TGZ_BASE64 }}
+          TEST_EMAIL: ${{ secrets.TEST_EMAIL }}
+          TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
+        run: |
+          npx shippilot doctor
+          npx shippilot run --case qa/login.md
+
+      - name: Upload ShipPilot report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: shippilot-report
+          path: .shippilot/

package/examples/qa/login.md

@@ -0,0 +1,15 @@
+---
+id: login-happy-path
+title: Login happy path
+required_env:
+  - TEST_EMAIL
+  - TEST_PASSWORD
+tags:
+  - release
+  - smoke
+---
+
+Launch the app.
+Enter `${TEST_EMAIL}` and `${TEST_PASSWORD}`.
+Tap Log In.
+Expect the Home screen to be visible.

package/examples/shippilot.yml

@@ -0,0 +1,24 @@
+codex:
+  engine: sdk
+  auth: api_key
+  model: default
+  sandbox: danger-full-access
+  fail_on: failed_or_blocked
+  verbose: false
+  allow_experimental_personal_hosted_auth: false
+
+ios:
+  project: MyApp.xcodeproj
+  bundle_id:
+  scheme: MyApp
+  simulator: iPhone 17 Pro
+  backend: xcodebuildmcp
+  configuration: Debug
+
+reports:
+  output_dir: .shippilot
+  markdown: true
+  json: true
+  junit: true
+  screenshots: true
+  logs: true

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "shippilot",
+  "version": "0.0.1",
+  "description": "Agentic iOS QA runner for Codex, GitHub Actions, and Bitrise",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mahmoud Ashraf",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mahmoudashraf93/ShipPilot.git"
+  },
+  "homepage": "https://github.com/mahmoudashraf93/ShipPilot#readme",
+  "bugs": {
+    "url": "https://github.com/mahmoudashraf93/ShipPilot/issues"
+  },
+  "bin": {
+    "shippilot": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "docs",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@openai/codex-sdk": "^0.135.0",
+    "commander": "^14.0.2",
+    "fast-glob": "^3.3.3",
+    "gray-matter": "^4.0.3",
+    "xcodebuildmcp": "^2.5.2",
+    "yaml": "^2.8.1",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.14"
+  }
+}