chore: mark Neon paths retired in messaging; keep the code

[tonychang04]

What

Neon is no longer used by any environment (postgres is 100% insta-db backed in prod). This PR updates wording only — zero code paths, tests, or commands removed.

Customer-visible strings (Neon name removed, meaning kept):

• insta db limits / insta db volume soft no-instance messages: "(Neon-backed services manage their own resources/storage)" → "(this service manages its own resources/storage)"
• insta services upgrade help text now says compute-only and points postgres at insta db limits — the platform rejects every postgres upgrade with a 400, so the old <compute|postgres> help was a trap. The command still accepts and forwards postgres (behavior unchanged); only the description changed.

Internal comments/docs (now explicit instead of silent):

• db.ts / metrics.ts comments, CONTRIBUTING.md, and test/limits.test.ts mark the Neon-shaped branches as "Legacy Neon path — Neon is no longer used by any environment; retained, not live."

Deliberately untouched:

• manifest.ts r.ref?.neonProjectId read — data-shape fallback for legacy rows, not prose
• test/setup-agent.test.ts negative guard asserting neon is NOT in setup args
• the 502 soft-path handling itself — retained coverage, now labeled

Verified: build + 238/238 tests green; no info()/warn()/error()/description() string contains "neon"; README already clean (0.0.27+ dropped the neon-postgres skill install).

Sibling PRs: InsForge/insta-skills#36, insta-platform (incoming).

🤖 Generated with Claude Code

---

Summary by cubic

Retires Neon from CLI messaging while keeping Neon-shaped code paths for compatibility and test coverage. This avoids referencing an unused provider and clarifies that Postgres upgrades are rejected.

• insta db limits / insta db volume: “no manageable instance” text now says “this service manages its own resources/storage” (was “Neon-backed …”).
• insta services upgrade: help now says compute-only and explicitly that Postgres upgrades are rejected by the platform — use insta db limits instead. Behavior unchanged: CLI still forwards Postgres, platform returns 400.
• Marks Neon-specific branches as legacy/retained (not live) in db/metrics comments, CONTRIBUTING.md, and test/limits.test.ts; no code paths or tests removed.
• Leaves compatibility in place: manifest r.ref?.neonProjectId read, the negative setup guard, and the 502 soft-path handling/tests remain unchanged.

^{Written for commit 388c0eb. Summary will update on new commits.}

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[jwfing]

Summary
This PR appears to achieve its stated goal of retiring Neon references from customer-facing and internal messaging while intentionally leaving the legacy code paths in place; I found no functional, security, or performance regressions.

Requirements Context
I evaluated intent from the PR description because no linked issue or design doc was present in the checked-out repo. I also cross-checked the repo’s documented command-surface rule in CONTRIBUTING.md and .claude/skills/developing-insta-cli/SKILL.md, which say command/flag changes must be mirrored in insta-skills’ cli-reference.md.

Findings
Critical
(none)

Suggestion

• src/index.ts:140, CONTRIBUTING.md:41, .claude/skills/developing-insta-cli/SKILL.md:35: insta services upgrade’s help text is part of the CLI surface, and the repo explicitly requires command-surface changes to be mirrored in insta-skills’ cli-reference.md in the same change set. The PR description mentions sibling PR insta-skills#36, which likely covers this, but this PR is only safe to merge once that companion doc update is confirmed to land alongside it.

Information

• (none)

Verdict
approved — the implementation matches the documented intent, software-engineering coverage is adequate for a wording-only change, and I found no security-relevant or performance-relevant issues. The only follow-up is to keep the external CLI reference update coordinated with this merge.

[jwfing]

Review: chore: mark Neon paths retired in messaging; keep the code

Summary: A tightly-scoped, wording-and-comment-only PR that removes the "Neon" name from customer-visible strings and relabels the legacy Neon-shaped branches as retained-but-not-live — with zero behavior, command, or test-logic changes.

Requirements context: No matching spec/plan found — this repo keeps design docs under docs/specs/ (not docs/superpowers/) and has none for a messaging chore. Assessed against the PR description and the actual code.

Verification performed

• Scope claim ("zero code paths removed"): confirmed. The diff touches only comments, one CLI .description() string, two info() message strings, CONTRIBUTING.md, and one test's comments/it() title. No control flow changed.
• "No info()/warn()/error()/description() string contains neon": confirmed via grep — the only remaining neon tokens in src/ are comments in db.ts/metrics.ts and the deliberately-kept data-shape read at src/commands/manifest.ts:15 (r.ref?.neonProjectId). None are user-visible.
• services upgrade behavior unchanged: confirmed. servicesUpgrade at src/commands/services.ts:186 still assertType(type, ['compute', 'postgres']) and forwards postgres to the platform; only the help text in src/index.ts:140 changed. The command still accepts postgres and the platform still 400s it — behavior is identical, as claimed.
• Comment accuracy: the reworked db.ts:47-56 / db.ts:65-72 comments correctly describe the real seam — rawRequest throws ApiError on any status ≥ 400, so the 502→no-instance soft case must live in the catch, and post-return res.status >= 400 branches would be unreachable. The relabeling does not misdescribe the code.

Findings

Critical: (none)

Suggestion: (none)

Information

• Functionality — src/index.ts:140: the new help reads "Change a compute service spec … for postgres resources use insta db limits", yet the command still accepts postgres as a type and forwards it (returning a platform 400). This mild help-vs-acceptance mismatch is deliberate and documented in the PR body (keeps backward-compat, removes the old "trap" wording), so it's fine as-is; noting only for awareness in case a future cleanup wants to reject postgres at the CLI layer with a pointer message.
• Software engineering — test/limits.test.ts: no test changes beyond comment/title relabeling, which is correct here since no behavior changed. The existing 502→no-instance seam test remains as retained coverage for the not-live path. Good scope discipline.
• Security / Performance — no security- or performance-relevant changes in this PR (no new input, secrets, queries, or hot paths touched).

Verdict

approved (informational — a human still gives the GitHub approval). Clean, accurate, well-scoped messaging PR with no blocking issues. Sibling coordination (insta-skills#36, insta-platform incoming) is noted but out of scope for this CLI review.

[cubic-dev-ai]

All reported issues were addressed across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[tonychang04]

re cubic P2: the premise is inverted — insta services upgrade on a postgres service is not a working command; the platform rejects it with 400 (upgrade is not supported for the insta-db provider, and every environment runs insta-db). The old help text implying it works was the trap this PR removes. Pushed a sharper wording so the description states the rejection explicitly: "Postgres upgrades are rejected by the platform — use insta db limits instead." The CLI keeps accepting postgres deliberately (backward-compat; the platform owns the refusal). Backticks in help strings are existing house style in this file (see the start/suspend descriptions), so leaving those.

[jwfing]

Summary
This PR does what it says: it updates messaging and comments to retire Neon references without removing the legacy compatibility code paths.

Requirements context
I based intent primarily on the PR description, because I did not find a separate issue/spec linked from the repo. I cross-checked that intent against the repo’s contributor guidance in CONTRIBUTING.md, especially the note that command/flag surface changes must also be mirrored in the external agent-facing CLI reference (CONTRIBUTING.md:40-43), and against the surrounding command implementations/tests in src/index.ts, src/commands/db.ts, src/commands/metrics.ts, src/commands/services.ts, and test/limits.test.ts.

Software engineering: the wording-only edits follow existing patterns, and the retained legacy branch in fetchDbInstance is still covered by tests (test/limits.test.ts:82-102). Functionality: the changed user-facing strings match the PR description, and the services upgrade help text now reflects the current platform behavior while leaving the underlying command behavior unchanged (src/index.ts:140, src/commands/services.ts:185-194). Security: no security-relevant changes. Performance: no performance-relevant changes.

Findings
Critical
(none)

Suggestion
(none)

Information

• src/index.ts:140, CONTRIBUTING.md:40-43 — This PR changes CLI help text for insta services upgrade, which repo guidance treats as a command-surface change that must also be mirrored in insta-skills’ cli-reference.md. The PR description links sibling PR InsForge/insta-skills#36, so this is likely already being handled; I just could not verify that from this checkout.

Verdict
Approved. I found no blocking issues in software engineering, functionality, security, or performance for this repo change.

[jwfing]

Review: chore — mark Neon paths retired in messaging; keep the code

Summary: A wording-only change that removes the "Neon" name from customer-visible strings and relabels the retained (but no-longer-live) Neon branches as legacy; no code paths, commands, or tests are removed and behavior is unchanged.

Requirements context

No matching spec/plan found — this repo has no docs/superpowers/ or docs/specs/ directory, so I assessed against the PR description, the sibling PRs it references (insta-skills#36, insta-platform incoming), and the surrounding code. The PR's stated intent (drop the "Neon" name from prose while retaining the compatibility code) is clear and self-consistent.

Verification performed

• servicesUpgrade (src/commands/services.ts:185) is untouched and still assertType(type, ['compute', 'postgres']) then forwards to POST …/upgrade — confirming the PR claim that postgres is still accepted/forwarded and only the index.ts description changed.
• Grep for user-visible "neon" in info()/warn()/error()/description() across src/ returns nothing — the "no customer-visible Neon strings" claim holds.
• The relabeled comment in db.ts ("branches on res.status >= 400 after rawRequest are unreachable") matches actual ApiClient.rawRequest semantics (throws ApiError on ≥400), so the prose stays accurate.

Findings

Critical

(none)

Suggestion

• Functionality — src/index.ts:140: The new help text asserts "Postgres upgrades are rejected by the platform," yet servicesUpgrade still forwards postgres and lets the platform 400 bubble up through rawRequest. This is a deliberate, documented choice (guidance-only, behavior-preserving) and is accurate today because every postgres service is insta-db-backed. Worth a follow-up thought only: if the CLI ever wanted to be self-consistent it could short-circuit postgres in servicesUpgrade with the same "use insta db limits" message rather than relying on a remote 400. Non-blocking; out of scope for a wording PR.

Information

• Software engineering — test/limits.test.ts:82-100: Only the comment and one it(...) title changed; the test bodies (the 502 → no-instance seam coverage) are preserved, which is the right call — the coverage still guards live code (the soft no-instance path), independent of the Neon framing. No new tests are warranted since there is no behavior change.
• Security: No security-relevant changes — no new input reaches SQL/shell/HTTP, no secrets/PII touched, no auth changes.
• Performance: No performance-relevant changes — no new queries, loops, or allocations.

Verdict

approved (informational — human approval via the separate approve flow). Zero Critical findings; the single Suggestion and the Information notes are non-blocking. The comment prose is accurate against the actual runtime semantics, the retained coverage is sensible, and the scope matches the "wording only" claim exactly.

[jwfing]

LGTM - approved.