[Refactor] Split control-plane/internal/handlers/nodes.go (1684 LOC)

[santoshkumarradha]

Refactor: split control-plane/internal/handlers/nodes.go (1684 LOC)

Part of the refactor god-files epic.

Evidence

$ wc -l control-plane/internal/handlers/nodes.go
1684 control-plane/internal/handlers/nodes.go

$ grep -c "^func " control-plane/internal/handlers/nodes.go
22

Note: nodes_rest.go already exists as a separate file, and there's also handlers/admin/admin_handlers_test.go — the split is half-done. This issue finishes it.

Proposed split

1. nodes_register.go — node registration, version-aware upsert, approval gating
2. nodes_heartbeat.go — heartbeat + lease renewal helpers (not already in nodes_rest.go)
3. nodes_list.go — ListNodesHandler, query parsing, pagination
4. nodes_detail.go — NodeDetailHandler, per-node stats
5. nodes_tags.go — tag approval/proposal handlers (if present in this file)
6. nodes.go — tiny shared helpers only

Rules for the PR

1. Pure moves. No renames, no logic changes.
2. Existing nodes_discovery_test.go and nodes_rest_test.go must pass unchanged.

Why this matters

Node-registration, heartbeat, and approval are the most-touched handlers in the control plane. Their implementations should be findable in ≤30 seconds.

Size: M · Difficulty: intermediate · Language: Go

---

Part of epic #388 — parent tracker.

---

How to work on this

Setup

git clone https://github.com/Agent-Field/agentfield.git
cd agentfield
make install        # installs Go, Python (via uv), and Node deps
make build          # optional — builds the control plane binary

Run the baseline test suite

Before you change anything, run the tests for the language this issue targets so you know what "green" looks like:

• Go control plane: cd control-plane && go test ./... -count=1
• Go SDK: cd sdk/go && go test ./... -count=1
• Python SDK: cd sdk/python && uv run pytest -q
• TypeScript SDK: cd sdk/typescript && bun test

Package coverage baseline (so you can show improvement in the PR):

• go test -cover ./control-plane/internal/...
• uv run pytest --cov=agentfield sdk/python/tests
• bun test --coverage (TypeScript)

Using Claude Code or another AI coding agent

This repo has a CLAUDE.md at the root that Claude Code and compatible agents will read automatically. A working flow:

1. cd into the repo and run claude (or open in your IDE's agent).
2. Paste this issue URL and say: "Please implement this issue, following every acceptance-criteria checkbox. Do not change source files — only add tests under the target path in the issue. When you're done, run the test suite command from the issue and paste the result."
3. Let the agent read existing tests in the same package as a model for style / fixtures — we point to them in the issue.
4. Run make lint before opening the PR.

See the AI-Assisted Contributions guide for testing requirements. Tag your PR with ai-assisted if you used an AI agent.

Claiming this issue

Comment I'd like to work on this and a maintainer will assign it to you. If you're new to open source, issues labelled good first issue or first-timers-only are hand-picked for a smooth first PR — we'll guide you if you get stuck.

Opening the PR

• Branch name: tests/<short-description> or refactor/<short-description>
• Link this issue in the PR description with Closes #<number>
• Paste the before/after test output or coverage delta in the PR body
• Keep the diff to the scope in this issue — no drive-by cleanups

Help & questions

• Comment on this issue — we monitor all assigned issues.
• Join the community Discord: run /gsd-join-discord or check the README for the invite.
• For repo-wide questions, open a discussion with the help tag.

[kiranannadatha8]

I'd like to work on this — PR up at #481 with local verification (build + handlers tests green).

[santoshkumarradha]

@kiranannadatha8 all yours !

[github-actions]

Thanks for picking this up, @kiranannadatha8! 🎉

Here's what to expect:

• We'll check in after 7 days if we haven't heard an update
• After 14 days, we'll send a second reminder
• After 21 days without activity, we'll unassign to let others contribute

Tips for success:

• Drop a comment when you start working on it
• Share any blockers - we're here to help!
• Link your PR with Fixes #416 in the description

Happy coding! 🚀