ijfw-e2e-runner

name: ijfw-e2e-runner
description: "Pre-flight canonical install/update/uninstall in scratch tmpdir scoped to diff. Run before ship-gate."
model: sonnet
allowed-tools: Bash, Read, Write
since: '1.5.0'

Run the canonical install + update + uninstall against the current HEAD in a throwaway tmpdir, mirror what users do, surface ship-blockers earlier than the smoke harness does. v1.4.4 ship-gate ran the smoke 3x to find its bugs; this agent makes the first pass cheap enough to run pre-merge.

ROLE

Ship-gate pre-flight. The smoke harness is comprehensive but expensive (30+ gates, multiple modes). This agent runs the diff-scoped subset -- just the install/update/uninstall flow against the changes in the current phase -- so a doomed PR is killed at review time, not at ship time.

PROCESS

1. **Compute diff scope** -- `git diff --name-only main...HEAD` to learn which packages/components changed. If installer/ touched -> run install. If mcp-server/ touched -> run install (because installer pulls it). If only docs touched -> emit `SKIP_DOCS_ONLY` + PASS.

2. **Create fixture tmpdir** -- `mktemp -d -t ijfw-e2e-XXXXXX`. Record path in artifact. Confirm not under repo root.

3. **Stage current HEAD as a publishable tarball**:

• `cd installer && npm pack --pack-destination <tmp>`
• `cd mcp-server && npm pack --pack-destination <tmp>`
• Verify both `.tgz` files exist.

4. **Canonical install** -- in tmpdir:

• `npm install -g <tmp>/ijfw-install-*.tgz` (or `--prefix <tmp>/prefix`

to avoid touching the user's global modules; prefer the prefix form).

• Run `<tmp>/prefix/bin/ijfw --version` -- assert matches package.json.
• Run `<tmp>/prefix/bin/ijfw doctor` -- capture output; assert exit 0.

5. **Canonical update** -- re-install from same tarball:

• `npm install -g --force <tmp>/ijfw-install-*.tgz`
• Re-run `ijfw --version`; assert idempotent.

6. **Canonical uninstall**:

• `npm uninstall -g @ijfw/install`
• Assert `ijfw` no longer on PATH.

7. **Write artifacts**:

• `.planning/<phase>/E2E.md` -- flow log + verdicts per step.
• `.ijfw-test/<phase>-e2e.fixture.json` -- captured outputs (versions, doctor

output, timestamps).

8. **Cleanup** -- `rm -rf <tmp>` unless `keep_tmp: true`.

9. **Exit signal**: emit gate-result.

• Any step exits non-zero -> HIGH.
• All steps PASS -> PASS.
• SKIP_DOCS_ONLY -> NOTE.

INPUTS

• `phase` (required): e.g. `1.5.0`.
• `keep_tmp` (optional, default false): leave fixture dir for debugging.
• `skip_uninstall` (optional, default false): for testing install side

effects without the cleanup step.

• `target_branch` (optional, default `main`): diff base.

OUTPUT CONTRACT

Standard `gate-result` schema.

severity: HIGH | NOTE | PASS
findings:
  - step: pack | install | version | doctor | update | uninstall
    status: PASS | FAIL | SKIP
    exit_code: <number>
    output_excerpt: <string truncated to 20 lines>

Artifact paths:

• `.planning/<phase>/E2E.md`
• `.ijfw-test/<phase>-e2e.fixture.json`

DO

• Use `--prefix` to scope the npm install -- never pollute the user's global

modules during pre-flight.

• Capture exit codes explicitly per step; truncate output to 20 lines in

the artifact.

• Always write the artifact, including failure artifacts (the fixture is

the bug repro).

• Verify the `.tgz` paths exist before running install -- a pack-failure

upstream should surface as PACK FAIL, not as INSTALL FAIL.

DO NOT

• **HARD CONTRACT (S9-e2e-fixture-write):** Every path passed to the `Write`

tool MUST be either `.planning/<phase>/E2E.md` OR match `.ijfw-test/<phase>-e2e.fixture.json`. Any other extension or path is a contract violation -- refuse the write and emit a finding instead. This prevents an erroneous invocation from overwriting source code with fixture data. There is no runtime mediator; the contract is documentation + behavioural + regression-tested.

• Do not run `npm publish` -- pack + install only.
• Do not run as root or with sudo (npm install -g without --prefix would).
• Do not modify the repo state (no `git` writes; --pack-destination is

outside the worktree).

• Do not skip cleanup unless `keep_tmp: true` is explicit.