@alfe.ai/integrations

Integration lifecycle management for Alfe — registry, resolution, installation, state, and hook execution.

What It Does

Provides the complete integration lifecycle:

• Registry — fetches the integration index from GET /integrations/registry on the integrations service, with search and lookup
• Resolver — maps an integration name + optional version to a git clone target (repo URL, tag, or pinned commit SHA)
• Installer — git clones integration repos to ~/.alfe/integrations/{name}/, with install/update/remove/list operations
• IntegrationManager — full lifecycle orchestration: install → configure → activate → deactivate → uninstall
• StateManager — persistent state at ~/.alfe/integrations.json with in-memory secret storage
• Hooks — runs integration lifecycle scripts (pre_install, post_install, health_check, etc.) as child processes with env var injection
• Adapter — IntegrationManagerAdapter bridges IntegrationManager to the IIntegrationManager interface used by the gateway's ReconciliationEngine

Used by packages/gateway (daemon owns integration lifecycle directly) and packages/cli for the integration commands.

Key Files

src/
├── index.ts                    # Public re-exports
├── registry.ts                 # Registry client (fetches from integrations service API)
├── resolver.ts                 # Version resolution (name + version → git target)
├── installer.ts                # Git clone/update/remove to ~/.alfe/integrations/
├── integration-manager.ts      # Full lifecycle manager (install/configure/activate/health/uninstall)
├── state.ts                    # State file manager (~/.alfe/integrations.json)
├── hooks.ts                    # Hook script runner with env var injection
├── adapter.ts                  # IIntegrationManager adapter for ReconciliationEngine
├── types.ts                    # Integration command param types
├── resolver.test.ts            # Registry + resolver tests
├── installer.test.ts           # Installer tests
├── integration-manager.test.ts # Lifecycle tests
└── state.test.ts               # State manager tests

Usage

import {
  Registry, Resolver, Installer,
  IntegrationManager,
  IntegrationManagerAdapter,
} from '@alfe.ai/integrations';

// ── Registry + Resolution ──────────────────────────────────
const registry = new Registry();
const results = await registry.search('discord');

const resolver = new Resolver(registry);
const resolved = await resolver.resolve('discord', '1.0.0');

const installer = new Installer();
const installPath = await installer.install(resolved);

// ── Lifecycle Management ───────────────────────────────────
const manager = new IntegrationManager({
  logger,
  skillsDir: '~/.alfe/skills/',  // default
});

await manager.install({ name: 'discord', version: '1.0.0' });
await manager.configure({ name: 'discord', config: { guild_id: '123' } });
await manager.activate('discord');
await manager.health({ name: 'discord' });

// ── Gateway Adapter ────────────────────────────────────────
// Bridges IntegrationManager to ReconciliationEngine's interface
const adapter = new IntegrationManagerAdapter(manager);
cloudClient.setIntegrationManager(adapter);

Configuration

The Registry class resolves the API URL in this order:

1. Explicit apiUrl constructor argument
2. ALFE_API_URL environment variable
3. https://api.alfe.ai (production default)

The IntegrationManager accepts an options object:

interface IntegrationManagerOptions {
  logger?: Logger;
  statePath?: string;       // default: ~/.alfe/integrations.json
  integrationsDir?: string;  // default: ~/.alfe/integrations/
  skillsDir?: string;        // default: ~/.alfe/skills/
}

Development

pnpm install
pnpm --filter @alfe.ai/integrations build
pnpm --filter @alfe.ai/integrations test

Dependencies

• @alfe.ai/integration-manifest — manifest parsing, config validation, state types