feat(runtime): add centralized runtime registration system

[feloy]

Created pkg/runtimesetup package to abstract runtime registration from individual commands. Commands now call RegisterAll() instead of manually registering each runtime, making it easier to add new runtime implementations without modifying existing commands.

Added /add-runtime skill with step-by-step documentation for creating new runtime implementations. Updated command creation skills to include guidance on when runtime registration is needed.

Fixes #76

[codecov-commenter]

Codecov Report

❌ Patch coverage is 44.44444% with 10 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pkg/cmd/init.go	0.00%	1 Missing and 1 partial ⚠️
pkg/cmd/workspace_remove.go	0.00%	1 Missing and 1 partial ⚠️
pkg/cmd/workspace_start.go	0.00%	1 Missing and 1 partial ⚠️
pkg/cmd/workspace_stop.go	0.00%	1 Missing and 1 partial ⚠️
pkg/runtimesetup/register.go	80.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces a pluggable runtime registration system with interfaces and a RegisterAll() function to replace hardcoded fake runtime registration. Updates multiple command files to use the new registration framework, adds comprehensive tests, and provides documentation and skill guides for implementing new runtimes.

Changes

Cohort / File(s)	Summary
Runtime Registration Framework pkg/runtimesetup/register.go, pkg/runtimesetup/register_test.go	Introduces RegisterAll() function, Registrar and Available interfaces, and internal registration logic to support pluggable and conditionally available runtimes. Includes comprehensive test coverage for registration flow, availability filtering, and error handling.
Command Runtime Registration pkg/cmd/init.go, pkg/cmd/workspace_remove.go, pkg/cmd/workspace_start.go, pkg/cmd/workspace_stop.go	Replaces hardcoded fake runtime registration with runtimesetup.RegisterAll() calls, updates imports from pkg/runtime/fake to pkg/runtimesetup, and harmonizes error messages.
Documentation and Guides AGENTS.md, skills/add-command-simple/SKILL.md, skills/add-command-with-json/SKILL.md, skills/add-runtime/SKILL.md, .claude/skills/add-runtime	Adds Runtime System documentation describing pluggable runtimes and registration flow, updates command skill templates with runtime registration examples, and introduces comprehensive guide for implementing new runtimes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: add runtime interface and fake implementation #59: Introduces the foundational runtime.Runtime interface and fake runtime package that the new registration framework builds upon.
• feat(instances): integrate runtime management with instance manager #64: Introduces Manager.RegisterRuntime() API and initial fake runtime registration; main PR extends this with the generic RegisterAll() registration mechanism.
• feat(cmd): add --runtime flag to init command #73: Modifies pkg/cmd/init.go to introduce a configurable --runtime flag; main PR addresses the same file with the registration refactor.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: introducing a centralized runtime registration system, which aligns with the primary objective.
Description check	✅ Passed	The description is relevant and detailed, explaining the new runtimesetup package, centralized registration approach, and the /add-runtime skill documentation.
Linked Issues check	✅ Passed	The PR fully addresses #76 requirements: replaces hardcoded fake runtime registration with a generic mechanism, introduces Registrar and Available interfaces for conditional registration, and updates all command files accordingly.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the centralized runtime registration system and supporting documentation; no out-of-scope modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

pkg/runtimesetup/register_test.go (1)

72-163: Tests are comprehensive, consider adding a case for runtimes without Available interface.

The current tests cover the main scenarios well. One edge case not explicitly tested: a runtime that doesn't implement the Available interface should always be registered. The current testRuntime always implements Available, so this path isn't directly tested.

💡 Optional test case for runtimes without Available interface

// simpleRuntime doesn't implement Available interface
type simpleRuntime struct {
	runtimeType string
}

func (s *simpleRuntime) Type() string { return s.runtimeType }
func (s *simpleRuntime) Create(ctx context.Context, params runtime.CreateParams) (runtime.RuntimeInfo, error) {
	return runtime.RuntimeInfo{}, fmt.Errorf("not implemented")
}
// ... other required methods

t.Run("registers runtimes without Available interface", func(t *testing.T) {
	t.Parallel()
	
	registrar := &fakeRegistrar{}
	testFactories := []runtimeFactory{
		func() runtime.Runtime { return &simpleRuntime{runtimeType: "simple"} },
	}
	
	err := registerAllWithAvailable(registrar, testFactories)
	if err != nil {
		t.Fatalf("registerAllWithAvailable() failed: %v", err)
	}
	
	if len(registrar.registered) != 1 {
		t.Errorf("Expected 1 runtime to be registered, got %d", len(registrar.registered))
	}
})

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkg/runtimesetup/register_test.go` around lines 72 - 163, Add a test case to
assert that runtimes which do not implement the Available interface are always
registered: create a minimal simpleRuntime type (implementing only
runtime.Runtime methods like Type and Create but not Available), add a t.Run
block similar to the other table tests that uses fakeRegistrar and a factory
returning &simpleRuntime{runtimeType: "simple"}, call
registerAllWithAvailable(registrar, testFactories) and assert no error and that
fakeRegistrar.registered length is 1 and contains "simple"; reference test
symbols testRuntime, simpleRuntime, fakeRegistrar, and registerAllWithAvailable
when locating where to add the new test.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@pkg/runtimesetup/register.go`:
- Around line 55-59: availableRuntimes currently includes fake.New which is a
test-only runtime and because fakeRuntime doesn't implement the Available
interface it will always be registered via RegisterAll(); fix by either removing
fake.New from the availableRuntimes slice or implementing the
Available(interface) method on the fake runtime type (e.g., fakeRuntime) to
return false so RegisterAll() skips it—locate the availableRuntimes declaration
and the fake package (fake.New / fakeRuntime) and apply one of these two
changes.

In `@skills/add-runtime/SKILL.md`:
- Around line 34-37: The runtime template import block is missing the os/exec
package used by exec.LookPath, so add the import "os/exec" to the import list in
the SKILL.md runtime snippet where the imports include "context" and
"github.com/kortex-hub/kortex-cli/pkg/runtime"; also apply the same import
addition to the other snippet around lines 66–72 that uses exec.LookPath so the
examples compile.

---

Nitpick comments:
In `@pkg/runtimesetup/register_test.go`:
- Around line 72-163: Add a test case to assert that runtimes which do not
implement the Available interface are always registered: create a minimal
simpleRuntime type (implementing only runtime.Runtime methods like Type and
Create but not Available), add a t.Run block similar to the other table tests
that uses fakeRegistrar and a factory returning &simpleRuntime{runtimeType:
"simple"}, call registerAllWithAvailable(registrar, testFactories) and assert no
error and that fakeRegistrar.registered length is 1 and contains "simple";
reference test symbols testRuntime, simpleRuntime, fakeRegistrar, and
registerAllWithAvailable when locating where to add the new test.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 44927e3e-cb0e-401a-8190-e20142190d4c

📥 Commits

Reviewing files that changed from the base of the PR and between 06f2ee5 and ec1abbd.

📒 Files selected for processing (11)

• .claude/skills/add-runtime
• AGENTS.md
• pkg/cmd/init.go
• pkg/cmd/workspace_remove.go
• pkg/cmd/workspace_start.go
• pkg/cmd/workspace_stop.go
• pkg/runtimesetup/register.go
• pkg/runtimesetup/register_test.go
• skills/add-command-simple/SKILL.md
• skills/add-command-with-json/SKILL.md
• skills/add-runtime/SKILL.md