adding-framework-support

Adding Framework Support

Architecture Overview

Every framework integration is a single FrameworkConfig object. The wizard has no switch statements or per-framework routing — everything is data-driven through:

1. FrameworkConfig (src/lib/framework-config.ts) — the interface each framework implements
2. FRAMEWORK_REGISTRY (src/lib/registry.ts) — maps Integration enum values to configs
3. Integration enum (src/lib/constants.ts) — enum order determines detection priority and menu display order

The universal runner (src/lib/agent-runner.ts) handles all shared behavior: debug logging, version checking, welcome message, beta notices, AI consent, credential flow, agent execution, error handling, and outro messaging.

Steps to Add a New Framework

1. Add to the Integration enum and labels

In src/lib/constants.ts, add the new value to Integration. Enum order matters — it controls both the detection priority (first match wins) and the display order in the CLI select menu. The display label comes from metadata.name in your FrameworkConfig.

export enum Integration {
  // ... existing entries
  rails = 'rails',  // insert at the desired detection/display position
}

2. Create the agent config file

Create src/<framework>/<framework>-wizard-agent.ts. This file exports:

• A context type for framework-specific data
• A FrameworkConfig<TContext> object (the full integration definition)
• A thin runner function that just calls runAgentWizard(CONFIG, options)

Define a context type for any data gathered before the agent runs, then pass it as the generic parameter. Use type (not interface) so it satisfies the Record<string, unknown> constraint:

type RailsContext = {
  projectType?: RailsProjectType;
  gemfilePath?: string;
};

export const RAILS_AGENT_CONFIG: FrameworkConfig<RailsContext> = {
  // All context-consuming callbacks (getTags, getOutroChanges, etc.)
  // are now fully typed — no `any` casts needed.
};