# Plan 5 Platform API + Remaining Commands Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Unblock skill `bugfix-gitlab-mr-qax` on host-agent by replacing mock/fixture platform I/O with real GitHub/GitLab HTTP (injectable `fetch`), then close remaining §4 commands (`schema print`, `my-pull-request list`) and switch the skill. Comment/approve/merge posting, batch-review, and `report generate` stay deferred if they block the skill path.

**Architecture:** Port CLI platform HTTP as host-agent-local modules (no shared package; no LLM HTTP). Review/create keep existing host-agent turns. Tests mock `globalThis.fetch` (same pattern as CLI). `--fixture-pr` becomes optional override for offline tests; production path uses `pullRequest.authToken`.

**Tech Stack:** TypeScript 5.6, Node 20+, `node:test`, existing HostAgentClient / SessionStore / review + PR content modules.

**Spec:** `docs/superpowers/specs/2026-08-10-host-agent-design.md`  
**Roadmap:** `docs/superpowers/plans/2026-08-10-host-agent-roadmap.md`  
**Reference CLI (read-only):** `/Users/nietao/VSCode-plugins/smart-commit-cli` @ `0.1.21`

**Plan 5 YAGNI (this slice):**
- No comment / approve / merge HTTP posting (actions remain `skipped` / not performed)
- No `my-pull-request batch-review`
- No `report generate` / passHistory
- No hybrid / correction repair turns
- No shared npm package with CLI

**Deferred follow-ups:** completed in [Plan 6](./2026-08-12-host-agent-plan6-deferred-parity.md) (batch-review, report, review comment/approve/merge).

---

## File structure

| Path | Responsibility |
|------|----------------|
| `src/pullRequest/platform.ts` | Extract/align `detectPullRequestPlatform` / `buildPullRequestPlatform` (from CLI `platform.ts`) |
| `src/pullRequest/urlParser.ts` | Import shared platform builders (stop duplicating) |
| `src/pullRequest/redact.ts` | Port CLI redact helper |
| `src/pullRequest/http.ts` | `requestJson` / `requestText` / headers / encode helpers / `PullRequestApiError` |
| `src/pullRequest/reviewFetch.ts` | `getPullRequestDetails` + `getPullRequestDiff` (+ `getCurrentUser` if needed) |
| `src/pullRequest/createApi.ts` | `findExistingPullRequests` + `createPullRequest` (GitHub + GitLab) |
| `src/commands/pullRequestReview.ts` | Prefer API; optional `--fixture-pr` |
| `src/commands/pullRequestCreate.ts` | Real create via API; require authToken |
| `src/commands/bridge.ts` | Replace mock create with real create when auth present |
| `src/commands/schemaPrint.ts` + `src/contracts.ts` | `schema print --target` |
| `src/commands/myPullRequestList.ts` + list helpers | `my-pull-request list` |
| `src/cliApp.ts` | Wire new commands |
| Skill `bugfix-gitlab-mr-qax` | Switch to host-agent |
| Tests | `platformHttp.test.ts`, review/create e2e with mocked fetch |

---

### Task 1: Platform + HTTP foundation

**Files:**
- Create: `src/pullRequest/platform.ts`, `redact.ts`, `http.ts`
- Modify: `src/pullRequest/urlParser.ts` (use `platform.ts`)
- Test: `src/test/platformHttp.test.ts`

- [ ] **Step 1: Failing tests** for `buildGitHubHeaders` / `buildGitLabHeaders`, `requestJson` success + HTTP error → `PullRequestApiError`, `detectPullRequestPlatform` for github.com / gitlab.com / private host requiring provider.

- [ ] **Step 2: Port** CLI `platform.ts`, `redact.ts`, and HTTP helpers from `api.ts` (`requestJson`, `requestText`, headers, encode, error builders). Do not port create/compare yet.

- [ ] **Step 3: Refactor urlParser** to import `buildPullRequestPlatform` / kind helpers from `platform.ts` (behavior unchanged; existing urlParser tests stay green).

- [ ] **Step 4: `npm test` green; commit** `feat: add pull-request HTTP foundation`

---

### Task 2: Review fetch API + wire `pull-request review`

**Files:**
- Create: `src/pullRequest/reviewFetch.ts`
- Modify: `src/commands/pullRequestReview.ts`
- Test: `src/test/reviewFetch.test.ts`, update `src/test/pullRequestReview.test.ts`

**Flow:**
1. Parse URL
2. If `--fixture-pr` → load fixture (unchanged offline path)
3. Else require non-empty `config.pullRequest.authToken` → `getPullRequestDetails` + `getPullRequestDiff`
4. Reject merged / not open (same as Plan 4)
5. Session + `runHostAgentReview`; platform actions still skipped

- [ ] **Step 1: Unit tests** with `withMockedFetch` for GitLab MR details+diff and GitHub PR details+diff.

- [ ] **Step 2: Implement `reviewFetch.ts`** porting only `getPullRequestDetails` / `getPullRequestDiff` (+ private helpers / types needed). Skip comment/approve/merge exports.

- [ ] **Step 3: Wire command** — remove Plan 4 “fixture required” error; missing auth+fixture → CONFIG_ERROR mentioning `pullRequest.authToken` or `--fixture-pr`.

- [ ] **Step 4: E2E** — mocked fetch needs → response → passed; no fixture/no token → CONFIG_ERROR.

- [ ] **Step 5: Commit** `feat: fetch PR/MR details via GitHub/GitLab API`

---

### Task 3: Real PR/MR create API + wire create/bridge

**Files:**
- Create: `src/pullRequest/createApi.ts`
- Modify: `src/commands/pullRequestCreate.ts`, `src/commands/bridge.ts`
- Test: `src/test/createApi.test.ts`, update create/bridge tests

**Flow (create):**
1. Detect platform from `git remote get-url origin` + `pullRequest.provider` / `apiBaseUrl`
2. Require `authToken` unless dry-run with provided title+description only? **No** — dry-run still needs platform detect; create POST requires token. Dry-run without token OK if content already provided; auto content needs session as today.
3. `findExistingPullRequests` → if any, status `existing` (align CLI)
4. Else `createPullRequest` → status `created`
5. Keep local `getBranchDiffSnapshot` for content generation (no remote compare required in this slice)

- [ ] **Step 1: Mocked fetch tests** for GitLab create + GitHub create + find existing.

- [ ] **Step 2: Port create/find from CLI `api.ts`** (assignees/labels as warnings OK; match CLI collectWarning pattern).

- [ ] **Step 3: Wire `pull-request create` + `bridge`**; keep `mockCreate` only if explicitly `--mock-pr` **OR** remove mock and require token (prefer require token; update tests to mock fetch).

- [ ] **Step 4: Commit** `feat: create GitHub/GitLab PRs via real API`

---

### Task 4: `schema print`

**Files:**
- Create: `src/contracts.ts`, `src/commands/schemaPrint.ts` (or inline in cliApp)
- Modify: `src/cliApp.ts`, help text
- Test: `src/test/schemaPrint.test.ts`

- [ ] **Step 1: Failing test** — `schema print --target config-file` JSON has no `connection` / apiKey requirements; lists known targets.

- [ ] **Step 2: Implement** host-agent schema documents for: `config-file`, `config-resolve`, `bridge`, `commit-message-generate`, `pull-request-create`, `pull-request-review` (minimal JSON Schema objects; ids `smart-commit-host-agent.*`).

- [ ] **Step 3: Commit** `feat: add schema print command`

---

### Task 5: `my-pull-request list`

**Files:**
- Extend config: `myPullRequest.*` in schema/defaults/load
- Port/adapt: `listTypes`, `listPlatform`, `listApi` (subset), `listService`, command
- Test: mocked fetch list

- [x] **Step 1: Config fields** — `listScope`, `listKinds`, `remoteHost` (align CLI 0.1.21).

- [x] **Step 2: Port list HTTP + command**; workspace scope uses remotes; account scope uses `remoteHost`.

- [x] **Step 3: Commit** `feat: add my-pull-request list`

---

### Task 6: Skill switch + docs + roadmap

**Files:**
- Update: `/Users/nietao/.codex/skills/bugfix-gitlab-mr-qax/SKILL.md` (+ SETUP if needed)
- Update: `docs/parity-matrix.md`, roadmap, README
- Optional: colocated `smart-commit.qax-gitlab.json` remove connection if present in skill folder

- [ ] Remove `SMART_COMMIT_API_KEY` / CLI binary probes; use `smart-commit-host-agent` / `npx --yes smart-commit-host-agent`
- [ ] Document: review no longer needs `--fixture-pr`; needs `SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN`
- [ ] Roadmap: Plan 5 skill path complete; note deferred batch-review/report/comment posting
- [ ] Commit in host-agent repo for docs; skill file may live outside repo — still edit and note path in summary

---

## Acceptance

- `npm test` all green; no real network in CI
- `pull-request review <url>` works with mocked fetch (no required `--fixture-pr`)
- `pull-request create` / `bridge` create real mock-HTTP MR/PR URL
- `schema print` works for listed targets without connection
- `my-pull-request list` works with mocked fetch
- Skill docs point at host-agent; zero LLM env required for skill probe
- Zero LLM HTTP in host-agent; zero changes to `smart-commit-cli`

## Spec coverage

| Spec §4 / skill | Task |
|-----------------|------|
| Real platform HTTP for review/create | 1–3 |
| `schema print` | 4 |
| `my-pull-request list` | 5 |
| Skill switch | 6 |
| `report` / batch-review / comment posting | Deferred follow-up |