|
| 1 | +--- |
| 2 | +name: developing-insta-cli |
| 3 | +description: Use when working in the insta-cli repo — changing code, adding commands, opening PRs, getting them approved, or shipping a release (binaries and npm). Covers the review flow, the tag-triggered release workflow, and the manual npm publish. |
| 4 | +--- |
| 5 | + |
| 6 | +# Developing & shipping insta-cli |
| 7 | + |
| 8 | +## Dev loop |
| 9 | + |
| 10 | +```bash |
| 11 | +npm install |
| 12 | +npm test # vitest — all tests in test/, DI fakes (no docker/network needed) |
| 13 | +npm run typecheck # tsc --noEmit |
| 14 | +npx tsx src/index.ts --help # run the CLI from source |
| 15 | +``` |
| 16 | + |
| 17 | +- One command per file in `src/commands/`, registered in `src/index.ts` (commander). |
| 18 | +- Side-effectful modules take injected runners/fetch for tests (see `ensure-skills.ts`, `commands/setup.ts`, `test/deploy-port.test.ts`) — follow that pattern; don't mock globals. |
| 19 | +- `project create|link` has side effects in cwd (`.insta/`, observe hook, agent skills) — exercise them only in scratch dirs. |
| 20 | +- End-to-end without the cloud: run the insta-oss daemon and point the CLI at it with `INSTA_API_URL` (env wins over persisted config since v0.0.7). |
| 21 | + |
| 22 | +## Getting a PR merged (main is protected — this exact flow, no other works) |
| 23 | + |
| 24 | +1. Branch from `origin/main`: `feat/*` or `fix/*`. PRs target `main`. **Squash merge.** |
| 25 | +2. Checks that must pass: `ci` (typecheck + vitest) and `cubic` (AI review — it comments; a comment is NOT the required approval). |
| 26 | +3. **Branch protection requires 1 approving review, and you cannot approve your own PR.** Team flow: post in the `#insforge-approval-bot` Slack channel asking John-bot to approve, **one PR link per message** — multi-link messages get partially processed. Approval lands as a GitHub review from the maintainer bot within ~2 min. |
| 27 | +4. Arm `gh pr merge --auto --squash` while checks run; if the PR sat long enough to conflict, merge `origin/main` into your branch, resolve, re-push (approval survives unless dismissed). |
| 28 | + |
| 29 | +## Shipping a release (two halves — the second is manual) |
| 30 | + |
| 31 | +1. **Bump**: PR changing `package.json` version (main is protected — never commit the bump directly). Merge it via the flow above. |
| 32 | +2. **Tag**: `git checkout main && git pull && git tag vX.Y.Z && git push origin vX.Y.Z`. |
| 33 | +3. **Binaries (automatic)**: the `release` workflow builds 5 platform binaries + SHA256SUMS and publishes a GitHub Release. `install.sh`, `agents.sh`, and `insta upgrade` serve users from it immediately. |
| 34 | +4. **npm (MANUAL — do not assume CI does it)**: from a clean checkout at the tag, repo root: |
| 35 | + ```bash |
| 36 | + npm publish --otp=<2FA code> # prepublishOnly builds dist/; EOTP error = missing/expired code |
| 37 | + ``` |
| 38 | + Needs an npm account with publish rights on `insta` (2FA enforced). Verify with `npm view insta version`. |
| 39 | +5. Users on the binary channel update via `insta upgrade`; npm users via `npx insta@latest` / `npm update -g insta`. |
| 40 | + |
| 41 | +## Gotchas |
| 42 | + |
| 43 | +| Symptom | Cause / fix | |
| 44 | +|---|---| |
| 45 | +| PR green but unmergeable, `REVIEW_REQUIRED` | You can't self-approve — John-bot flow above | |
| 46 | +| John-bot ignored the request | Batched links — resend ONE link per message | |
| 47 | +| `npm error code EOTP` | Publish needs `--otp=<fresh 2FA code>` | |
| 48 | +| `npm publish` ENOENT package.json | Ran outside the repo root | |
| 49 | +| `npx insta@latest` behind the GH release | npm half not published — step 4 | |
| 50 | +| CLI hits the wrong server in tests | Persisted `~/.insta/config.json` apiUrl; set `INSTA_API_URL` (≥0.0.7) or move the config aside | |
| 51 | + |
| 52 | +## Keep this skill true |
| 53 | + |
| 54 | +Before you finish work in this repo: if anything you did or discovered changed the flows above — |
| 55 | +new required checks, a different review path, release steps added/automated (e.g. npm publish |
| 56 | +moving into CI), new command conventions — update this SKILL.md **in the same PR** as the change. |
| 57 | +A stale process skill is worse than none: the next agent will confidently follow it. |
0 commit comments