feat(setup): self-install the CLI — `npx -y insta setup agent` becomes a complete one-liner

Merged
TO
3mo ago
+425-19

Why

We want ONE command that installs CLI + agent skill + MCP server and works identically on macOS, Linux, and Windows (bash/zsh/PowerShell 5.1/7/cmd). curl … | sh can't be that command (PowerShell's curl alias + WSL bash shim — see InsForge/insta-landing#29). npx -y insta setup agent almost is — except npx runs from cache and leaves no insta on PATH, so the skill it installs points agents at a binary that doesn't exist.

What

setup agent now self-installs the CLI first when needed, then proceeds with the skill + MCP steps unchanged:

  • Trigger: detectChannel() === 'npm' (reused from upgrade.ts) and no durable insta on PATH. The PATH scan ignores entries under node_modules — npx prepends its cache's .bin (where this very process's shim lives); durable installs (npm -g bin, nvm/volta, ~/.insta/bin) never sit under one.
  • Install: npm install -g insta@<running version> (pinned — the one-liner installs exactly what it ran), re-entering the spawning npm via npm_execpath (npx-cli.js → npm-cli.js) rather than trusting npm on PATH — which also sidesteps Windows' no-shell .cmd spawn failure.
  • Windows: shim resolution via PATHEXT plus npm's extensionless sh shim.
  • No-ops: binary channel (native install), source checkouts (dev/vitest), and already-installed machines — idempotent, safe to re-run.
  • Best-effort: a failed global install prints the one-line manual fallback (EACCES gets a targeted hint) and continues with the skill install — never blocks onboarding.

6 new tests (test/self-install.test.ts): durable-PATH scan incl. npx-cache exclusion and Windows shims, npm re-entry + version pinning, channel gating, failure path.

Verification

  • npm run typecheck clean; new tests 6/6 green; setup agent --help smoke-tested from a build. (5 pre-existing failures on main and this branch alike come from the dev machine's ~/.insta/config.json pointing at staging — tests read real HOME; clean-HOME CI is unaffected.)
  • True npx e2e needs a published version: after the next release, npx -y insta@latest setup agent on a machine without insta should print ✓ insta CLI — installed globally and leave insta status working in a fresh shell. Happy to run that check post-publish.

Companion PRs (the cross-repo surfaces this change touches)

  • cli-reference.md mirror (AGENTS.md rule 4): SHIPPED as InsForge/insta-skills#46 — the reference lives in the separate insta-skills repo (the superproject skills submodule), so it cannot be part of this repo's change-set by construction; it merges together with this PR's release.
  • Landing docs already updated in InsForge/insta-landing#29; they collapse to the single npx one-liner once this ships as 0.0.37.

🤖 Generated with Claude Code

Summary by cubic

Makes npx -y insta setup agent a true one‑liner on macOS, Linux, and Windows by self‑installing the CLI when missing and making npm/npx spawns Windows‑safe. Previously npx ran insta from a cache and left no durable CLI; now it installs insta globally first, then installs the agent skill and registers the MCP server.

  • Self‑install runs only on the npm channel when no durable insta is on PATH; the scan ignores node_modules case‑insensitively, requires an executable regular file on POSIX, and resolves Windows shims via PATHEXT or npm’s extensionless shim. After npm install -g insta@<running version>, it rechecks PATH and prints add‑to‑PATH guidance on miss; on failure it continues and prints the pinned npm install -g insta@<version> with an EACCES hint.
  • Windows‑safe spawning resolves once in the default runner: re‑enter npm/npx as node <…>/npm‑cli.js|npx‑cli.js when and only when process.execPath is Node; otherwise, non‑npm .cmd tools resolve to an absolute PATH location and run via cmd.exe /d /s /c. Absolute paths and .exe targets never wrap; args with cmd metacharacters skip the wrapper.
  • Ensures npx auto‑installs skills by prepending -y; scrubs npm_config_package/npm_config_call so nested npx -y skills … resolves correctly; applies the same spawn logic to project skill installs.
  • README clarifies one‑liner requirements and Windows behavior; tests cover PATH executability, case‑insensitive node_modules exclusion, node‑only re‑entry, absolute‑path shim resolution, install‑then‑skills ordering, PATH recheck, the EACCES hint, and npx -y invariants.

No migration required; binary/source channels and already‑installed hosts are no‑ops.