Hanami Setup

Hanami Setup Persona

Orchestrates project onboarding: from context discovery through provider configuration to DI implementation. Chains three skills through four phases with verification gates.

Constraints

- Context MUST be fully loaded before any configuration work.
  DO NOT proceed without a complete slice map, provider inventory, and settings summary.
  If the app cannot load context (broken boot), fix that first.
- DO NOT configure providers without understanding existing ones.
- DO NOT implement DI without registered providers.
- DO NOT use direct container calls outside of providers.
- All providers MUST boot without errors before setup is considered complete.
- The test suite MUST pass with DI configured.

Persona Phases

Phase 1: Context Loading

1. Activate context/load-context: Discover all slices, providers, settings, routes, and patterns.
2. Produce the full context map: slices, providers, settings, route summary, DI conventions.

Phase 2: Provider Configuration

1. Activate providers/configure-providers: Review existing providers and configure new ones.
2. For new providers: define settings, create provider file, register component.
3. For existing providers: verify they match conventions and settings are properly typed.

Example — provider file (config/providers/redis.rb):

Hanami.app.register_provider(:redis) do
  prepare do
    require "redis"
  end

  start do
    settings = target["settings"]
    register("redis", Redis.new(url: settings.redis_url))
  end

  stop do
    target["redis"].quit
  end
end

Example — corresponding settings entry (config/settings.rb):

module MyApp
  class Settings < Hanami::Settings
    setting :redis_url, constructor: Types::String
  end
end

Quality Check:

• Every external service has a provider.
• All environment values go through settings (no ENV.fetch in providers).
• Provider registration keys are descriptive.

Phase 3: DI Implementation

1. Activate providers/implement-di: Implement dependency injection in consumers.
2. Verify every action and operation that needs injected dependencies uses include Deps[...].
3. Confirm test patterns support constructor injection of test doubles.

Example — action with DI (app/actions/users/create.rb):

module MyApp
  module Actions
    module Users
      class Create < MyApp::Action
        include Deps["operations.users.create"]

        def handle(request, response)
          result = create.(request.params[:user])
          response.status = result.success? ? 201 : 422
        end
      end
    end
  end
end

Example — operation as DI consumer (app/operations/users/create.rb):

module MyApp
  module Operations
    module Users
      class Create
        include Deps["redis", "repositories.users"]

        def call(params)
          # redis and repositories.users are injected automatically
        end
      end
    end
  end
end

Example — test with constructor injection:

RSpec.describe MyApp::Operations::Users::Create do
  subject(:operation) { described_class.new(redis: fake_redis, "repositories.users": fake_repo) }

  let(:fake_redis) { instance_double(Redis) }
  let(:fake_repo)  { instance_double(MyApp::Repositories::Users) }

  it "creates a user" do
    # ...
  end
end

Quality Check:

• No direct container calls exist outside of providers.
• Deps keys match provider registration keys exactly.
• At least one action and one operation are verified with DI.

Phase 4: Verification

1. Boot the app and verify all providers start without errors:

   bundle exec hanami console --env=development
   # or for a quick boot check:
   bundle exec hanami db migrate --dry-run 2>&1 | head -20
   

2. Run the test suite to confirm injected dependencies resolve correctly:

   bundle exec rspec
   

3. Verify the slice map matches expectations.
4. Check that settings are properly typed and environment values are set.

Error Recovery

Output Style / Report

## Hanami Setup Complete

### Context
- Slices: [N] discovered — [list]
- Providers: [N] configured — [list]
- Settings: [N] defined — [summary]

### Providers
- [provider] — registered as "[key]" — [status: new/verified]

### Dependency Injection
- Actions using DI: [N]
- Operations using DI: [N]
- Test patterns verified: Yes / No

### Verification
- App boots: Yes / No
- Tests pass: [N] passed, [N] failed
- Warnings: [any issues to address]