Code-quality pass: fix real defects, hoist shared helpers, harden tests

[yosriady]

Summary

Full-codebase review (three parallel reviewers: lib layer, command surface, tests/packaging/docs) followed by implementation of the confirmed findings.

Defect fixes

• --version had drifted — it reported 1.0.1 on the 1.1.0 release. Now read from package.json (src/index.ts); can't drift again.
• formo login saved server-rejected keys with the message "The API might be unreachable" even when the API had explicitly returned 401. Validation is now a discriminated result: rejected keys are refused with a clear error; only genuinely unreachable-API logins save with a warning. The validation fetch also gets a 10s timeout (previously it could hang forever).
• createClient() now throws the friendly "No API key configured" error itself — previously auth enforcement was opt-in via requireApiKey() at 40+ call sites, and a forgotten call shipped a confusing server-side 401.
• Client types no longer lie: the response interceptor unwraps every response to its body, but the returned AxiosInstance types still promised AxiosResponse<T>. New FormoClient interface states what actually comes back (this also let the test tree typecheck — see below).
• readConfig() no longer crashes every command when the config file contains null or other non-object JSON; clearConfig() no longer swallows real write failures (EACCES/EROFS), so formo logout can't claim success while the key remains on disk.
• Validation consistency: contracts get/update/pipeline/delete now validate the chain arg like create does; events ingest and import wallets reject mutually exclusive flags (--event+--events, --addresses+--rows) instead of silently preferring one; segments create --filter-sets and profiles labels create --labels validate entries; page/size flags are .int().positive().
• Cosmetics with teeth: NO_COLOR honored per spec (presence, not truthiness); color keyed to stderr (where all decorated output goes — previously 2>log captured raw ANSI); parseApiError renders nested detail values as JSON instead of [object Object]; formo -h shows the banner like --help.

Maintainability

• Pagination options/schema/params hoisted to src/lib/pagination.ts — was copy-pasted byte-identical in five commands; alerts create/update share one schema (were duplicated).
• Config path exported (getConfigFile()) and overridable via FORMO_CONFIG_DIR — the four hardcoded ~/.config/formo/config.json display strings now can't lie, and unit tests no longer rewrite the developer's real config file (they use a temp dir).
• Test suite now runs without TEST_TOKEN — live-API tests skip via the existing probe instead of process.exit(1). This fixes red CI on fork PRs where secrets are unavailable. The probe also honors FORMO_API_BASE_URL, and charts' offline validation tests no longer get skipped along with the live ones.
• tsconfig.test.json was dead config (referenced by nothing). It's now pnpm typecheck, runs in CI, and passes.
• engines: node >=22.12 declared — the published bin is CJS and require()s ESM incur, which only works unflagged on Node ≥22.12; older Node crashed at startup with no npm warning (root cause family of this week's CI saga).
• Dead override config removed (npm-style overrides + pnpm.overrides in package.json; the live copy is in pnpm-workspace.yaml); incur pinned exactly while patched (patch hunks shift on minor bumps); prepublishOnly builds before publish so a stale local dist/ can't ship; dev script uses tsx (ts-node dropped).
• +33 new unit tests (123 → 156 passing): direct coverage for lib/json, lib/pagination, chain validation, board title validation, and all the new flag guards.

Docs

• README: charts scopes corrected to boards:read/write (was documenting nonexistent charts:* scopes → guaranteed 403s), import-wallets flow corrected (main API + profiles:write, not "events API"), missing flags documented (--slack-property-keys, --search, --events, charts update typed flags, seven lifecycle tuning flags), alerts update full-replace semantics stated.
• SKILLS.md: formo query "<sql>" → formo query run "<sql>" (agent-facing file; the old form errors), funnel params list synced, logout/--logic added.
• CONTRIBUTING.md: rewritten to match reality — it described a monorepo layout, vitest, and mocked tests, none of which exist.

Deliberately not changed

• charts keeping --board-id as an option vs positional (internally consistent; changing is a breaking UX change).
• --recipient (takes a JSON array) not renamed to --recipients — worth doing with a deprecated alias in a dedicated PR.
• profiles search --conditions keeps its custom parse for the richer FilterCondition error message.
• alerts update full-replace and charts GET-merge-PUT semantics (API-driven; now documented instead).

Test plan

• pnpm build, pnpm lint, pnpm typecheck clean
• pnpm test: 156 passing, 18 pending — both with and without TEST_TOKEN
• Built CLI smoke-tested: --version → 1.1.0, status, no-key error path
• CI green on this PR

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.