feat: neon-init v2 agent-driven state machine#151
Open
jeff-at-neon wants to merge 2 commits into
Open
Conversation
Adds a --json flag that outputs structured JSON and suppresses interactive UI, making it suitable for agent consumption. Refactors init to return result objects and adds tests. Co-authored-by: Isaac
Redesigns neon-init as a stateless state machine where each CLI invocation
returns a typed JSON response with a `nextAction` that tells the agent
exactly what to do next. Key changes:
- Orchestrator inspects filesystem (MCP config, skills, DATABASE_URL) to
skip phases that are already satisfied — no unnecessary round-trips
- Phase handlers for auth, setup, getting-started, db, neon-auth,
migrations, mcp, skills, and status as composable subcommands
- `responseMapping` supports inline `{ action: NextAction }` to eliminate
CLI round-trips (e.g. auth OAuth launches directly after user confirms)
- Auth verified responses use `run_neon_init` instead of `complete` to
prevent agents from getting distracted by neonctl output
- `ensureSkillsUpToDate()` with 12-hour freshness window — called from
phase handlers, skips if skills-lock.json or global skills dir is recent
- Agent detection via TTY: IDE env vars + non-TTY stdin = agent invocation,
IDE env vars + TTY stdin = human in terminal → interactive mode
- Interactive mode with clack prompts, Neon green branding via picocolors
patch, org/project selection, .neon context file
- Extension install fallback chain: marketplace → VSIX download (corporate
proxy or Open VSX) → manual instructions
- Input validation (assertSafeId) for org/project IDs in shell commands
- Filesystem inspection module (inspect.ts) shared by orchestrator, setup,
and status phases
- 95 tests across 11 test files
Co-authored-by: Isaac
jeff-at-neon
force-pushed
the
neon-init-v2-plan
branch
from
9ba442a to
ca9e89a
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Redesigns neon-init as a stateless state machine where each CLI invocation returns a typed JSON response with a
nextActionthat tells the agent exactly what to do next.responseMappingsupports inline{ action: NextAction }to eliminate CLI round-trips (e.g. auth OAuth launches directly after user confirms)ensureSkillsUpToDate()with 12-hour freshness window — verifies actual SKILL.md exists on disk, not just lock file.neoncontext resolution — when a Neon connection string exists but.neonis missing, the CLI resolves the org/project by searching via neonctlassertSafeId) for org/project IDs in shell commandsKey design decisions
run_neon_init(notcomplete) to prevent agents from getting distractedcompleteaction (no CLI round-trip needed)ensureSkillsUpToDateregardless of agent-reported state — CLI verifies independentlyTest plan
neon-initin Cursor terminal (human) — should show interactive modeneon-init— should get JSON modeneon-initwith MCP+skills already installed — should skip to getting-started.neonfile with existing connection string, runneon-init— should resolve and recreateneon-initfrom Claude Code — should detect via CLAUDECODE env varThis pull request and its description were written by Isaac.