@complior/engine 0.9.0

package/src/services/framework-service.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect } from 'vitest';
+import { createFrameworkService } from './framework-service.js';
+import { createFrameworkRegistry } from '../domain/frameworks/framework-registry.js';
+import type { ComplianceFramework, FoundationMetrics, FrameworkScoreResult } from '../types/framework.types.js';
+import type { FoundationMetricsDeps } from '../domain/frameworks/collect-foundation-metrics.js';
+
+const mockFw = (id: string): ComplianceFramework => ({
+  id,
+  name: `Test ${id}`,
+  version: '1.0',
+  checks: [],
+  categories: [],
+  gradeMapping: { type: 'letter', thresholds: [{ minScore: 0, grade: 'F' }] },
+});
+
+const mockScorer = (score: number) => (fw: ComplianceFramework, _m: FoundationMetrics): FrameworkScoreResult => ({
+  frameworkId: fw.id,
+  frameworkName: fw.name,
+  score,
+  grade: score >= 90 ? 'A' : 'B',
+  gradeType: 'letter',
+  gaps: 0,
+  totalChecks: 10,
+  passedChecks: Math.round(score / 10),
+  categories: [],
+});
+
+const mockDeps: FoundationMetricsDeps = {
+  getLastScanResult: () => null,
+  getPassport: async () => null,
+  getPassportCompleteness: async () => 0,
+  getEvidenceSummary: async () => ({
+    totalEntries: 0,
+    scanCount: 0,
+    firstEntry: '',
+    lastEntry: '',
+    chainValid: false,
+    uniqueFindings: 0,
+  }),
+  getDocuments: async () => new Set<string>(),
+};
+
+describe('FrameworkService', () => {
+  it('lists available frameworks', () => {
+    const reg = createFrameworkRegistry();
+    reg.register(mockFw('a'), mockScorer(80));
+    reg.register(mockFw('b'), mockScorer(60));
+
+    const svc = createFrameworkService({
+      registry: reg,
+      getSelectedFrameworks: () => ['a'],
+      foundationDeps: mockDeps,
+    });
+    expect(svc.listAvailable()).toEqual(['a', 'b']);
+  });
+
+  it('lists selected frameworks', () => {
+    const reg = createFrameworkRegistry();
+    reg.register(mockFw('a'), mockScorer(80));
+
+    const svc = createFrameworkService({
+      registry: reg,
+      getSelectedFrameworks: () => ['a'],
+      foundationDeps: mockDeps,
+    });
+    expect(svc.listSelected()).toEqual(['a']);
+  });
+
+  it('returns scores for selected frameworks', async () => {
+    const reg = createFrameworkRegistry();
+    reg.register(mockFw('x'), mockScorer(85));
+    reg.register(mockFw('y'), mockScorer(55));
+
+    const svc = createFrameworkService({
+      registry: reg,
+      getSelectedFrameworks: () => ['x', 'y'],
+      foundationDeps: mockDeps,
+    });
+
+    const result = await svc.getScores();
+    expect(result.frameworks).toHaveLength(2);
+    expect(result.frameworks[0].frameworkId).toBe('x');
+    expect(result.frameworks[0].score).toBe(85);
+    expect(result.frameworks[1].frameworkId).toBe('y');
+    expect(result.selectedFrameworkIds).toEqual(['x', 'y']);
+    expect(result.computedAt).toBeDefined();
+  });
+
+  it('skips unregistered frameworks', async () => {
+    const reg = createFrameworkRegistry();
+    reg.register(mockFw('real'), mockScorer(70));
+
+    const svc = createFrameworkService({
+      registry: reg,
+      getSelectedFrameworks: () => ['real', 'missing'],
+      foundationDeps: mockDeps,
+    });
+
+    const result = await svc.getScores();
+    expect(result.frameworks).toHaveLength(1);
+    expect(result.frameworks[0].frameworkId).toBe('real');
+  });
+
+  it('getScore returns single framework score', async () => {
+    const reg = createFrameworkRegistry();
+    reg.register(mockFw('solo'), mockScorer(92));
+
+    const svc = createFrameworkService({
+      registry: reg,
+      getSelectedFrameworks: () => ['solo'],
+      foundationDeps: mockDeps,
+    });
+
+    const result = await svc.getScore('solo');
+    expect(result).not.toBeNull();
+    expect(result!.score).toBe(92);
+    expect(result!.grade).toBe('A');
+  });
+
+  it('getScore returns null for unknown framework', async () => {
+    const reg = createFrameworkRegistry();
+    const svc = createFrameworkService({
+      registry: reg,
+      getSelectedFrameworks: () => [],
+      foundationDeps: mockDeps,
+    });
+    const result = await svc.getScore('unknown');
+    expect(result).toBeNull();
+  });
+
+  it('returns empty frameworks when none selected', async () => {
+    const reg = createFrameworkRegistry();
+    reg.register(mockFw('avail'), mockScorer(50));
+
+    const svc = createFrameworkService({
+      registry: reg,
+      getSelectedFrameworks: () => [],
+      foundationDeps: mockDeps,
+    });
+
+    const result = await svc.getScores();
+    expect(result.frameworks).toHaveLength(0);
+  });
+
+  it('computedAt is ISO string', async () => {
+    const reg = createFrameworkRegistry();
+    reg.register(mockFw('ts'), mockScorer(70));
+
+    const svc = createFrameworkService({
+      registry: reg,
+      getSelectedFrameworks: () => ['ts'],
+      foundationDeps: mockDeps,
+    });
+
+    const result = await svc.getScores();
+    expect(() => new Date(result.computedAt)).not.toThrow();
+    expect(result.computedAt).toMatch(/\d{4}-\d{2}-\d{2}/);
+  });
+});

package/src/services/framework-service.ts

@@ -0,0 +1,67 @@
+/**
+ * Framework Service — orchestrates multi-framework scoring.
+ * Selected frameworks → registry lookup → metrics collection → per-framework scoring.
+ */
+
+import type { FrameworkRegistry } from '../domain/frameworks/framework-registry.js';
+import type { FoundationMetricsDeps } from '../domain/frameworks/collect-foundation-metrics.js';
+import { collectFoundationMetrics } from '../domain/frameworks/collect-foundation-metrics.js';
+import type {
+  FrameworkScoreResult,
+  MultiFrameworkScoreResult,
+} from '../types/framework.types.js';
+
+export interface FrameworkService {
+  readonly getScores: () => Promise<MultiFrameworkScoreResult>;
+  readonly getScore: (frameworkId: string) => Promise<FrameworkScoreResult | null>;
+  readonly listAvailable: () => readonly string[];
+  readonly listSelected: () => readonly string[];
+}
+
+export interface FrameworkServiceDeps {
+  readonly registry: FrameworkRegistry;
+  readonly getSelectedFrameworks: () => readonly string[];
+  readonly foundationDeps: FoundationMetricsDeps;
+}
+
+export const createFrameworkService = (deps: FrameworkServiceDeps): FrameworkService => {
+  const scoreOne = async (frameworkId: string): Promise<FrameworkScoreResult | null> => {
+    const entry = deps.registry.get(frameworkId);
+    if (!entry) return null;
+    const metrics = await collectFoundationMetrics(deps.foundationDeps);
+    return entry.score(entry.definition, metrics);
+  };
+
+  return Object.freeze({
+    async getScores(): Promise<MultiFrameworkScoreResult> {
+      const selectedIds = deps.getSelectedFrameworks();
+      const metrics = await collectFoundationMetrics(deps.foundationDeps);
+
+      const frameworks: FrameworkScoreResult[] = [];
+      for (const id of selectedIds) {
+        const entry = deps.registry.get(id);
+        if (entry) {
+          frameworks.push(entry.score(entry.definition, metrics));
+        }
+      }
+
+      return Object.freeze({
+        frameworks,
+        selectedFrameworkIds: selectedIds,
+        computedAt: new Date().toISOString(),
+      });
+    },
+
+    async getScore(frameworkId: string): Promise<FrameworkScoreResult | null> {
+      return scoreOne(frameworkId);
+    },
+
+    listAvailable(): readonly string[] {
+      return deps.registry.ids();
+    },
+
+    listSelected(): readonly string[] {
+      return deps.getSelectedFrameworks();
+    },
+  });
+};

package/src/services/onboarding-service.ts

@@ -0,0 +1,165 @@
+/**
+ * US-S05-33: Onboarding Service
+ *
+ * Orchestrates the 5-step guided onboarding wizard by coordinating
+ * the pure FSM domain functions with state persistence.
+ */
+
+import type { GuidedOnboardingState } from '../domain/onboarding/guided-onboarding.js';
+import {
+  createInitialState,
+  startOnboarding,
+  completeStep,
+  canRunStep,
+  TOTAL_STEPS,
+} from '../domain/onboarding/guided-onboarding.js';
+
+export interface OnboardingServiceDeps {
+  readonly getProjectPath: () => string;
+  readonly loadState: (projectPath: string) => Promise<GuidedOnboardingState>;
+  readonly saveState: (projectPath: string, state: GuidedOnboardingState) => Promise<void>;
+  readonly executeStep: (stepNum: number, projectPath: string) => Promise<Record<string, unknown>>;
+}
+
+export interface OnboardingStatus {
+  readonly currentStep: number;
+  readonly totalSteps: number;
+  readonly stepName: string;
+  readonly completed: boolean;
+  readonly steps: readonly OnboardingStepSummary[];
+}
+
+export interface OnboardingStepSummary {
+  readonly number: number;
+  readonly name: string;
+  readonly status: 'pending' | 'active' | 'completed' | 'skipped';
+}
+
+export interface OnboardingStepResult {
+  readonly step: number;
+  readonly name: string;
+  readonly success: boolean;
+  readonly message: string;
+  readonly data: Record<string, unknown>;
+  readonly nextStep: number | null;
+}
+
+export interface OnboardingService {
+  readonly getStatus: () => Promise<OnboardingStatus>;
+  readonly start: () => Promise<OnboardingStatus>;
+  readonly advanceStep: (stepNumber: number) => Promise<OnboardingStepResult>;
+  readonly reset: () => Promise<OnboardingStatus>;
+}
+
+const toStatus = (state: GuidedOnboardingState): OnboardingStatus => {
+  const steps: OnboardingStepSummary[] = state.steps.map((s, i) => ({
+    number: i + 1,
+    name: s.label,
+    status: s.status === 'completed' ? 'completed' as const
+      : s.status === 'skipped' ? 'skipped' as const
+      : s.status === 'in_progress' ? 'active' as const
+      : 'pending' as const,
+  }));
+
+  // Use step labels from state (sourced from domain STEP_DEFINITIONS)
+  const currentLabel = state.currentStep >= 1 && state.currentStep <= state.steps.length
+    ? (state.steps[state.currentStep - 1]?.label ?? 'unknown')
+    : state.status === 'completed' ? 'completed' : 'not started';
+
+  return Object.freeze({
+    currentStep: state.currentStep,
+    totalSteps: TOTAL_STEPS,
+    stepName: currentLabel,
+    completed: state.status === 'completed',
+    steps,
+  });
+};
+
+export const createOnboardingService = (deps: OnboardingServiceDeps): OnboardingService => {
+  const getStatus = async (): Promise<OnboardingStatus> => {
+    const state = await deps.loadState(deps.getProjectPath());
+    return toStatus(state);
+  };
+
+  const start = async (): Promise<OnboardingStatus> => {
+    const projectPath = deps.getProjectPath();
+    let state = await deps.loadState(projectPath);
+
+    if (state.status === 'completed') {
+      return toStatus(state);
+    }
+
+    if (state.status === 'not_started') {
+      state = startOnboarding(state);
+      // Auto-execute step 1 (detect)
+      const stepData = await deps.executeStep(1, projectPath);
+      state = completeStep(state, 1, stepData);
+      await deps.saveState(projectPath, state);
+    }
+
+    return toStatus(state);
+  };
+
+  const advanceStep = async (stepNumber: number): Promise<OnboardingStepResult> => {
+    const projectPath = deps.getProjectPath();
+    let state = await deps.loadState(projectPath);
+
+    if (stepNumber < 1 || stepNumber > TOTAL_STEPS) {
+      return Object.freeze({
+        step: stepNumber,
+        name: 'unknown',
+        success: false,
+        message: `Invalid step number: ${stepNumber}. Valid range: 1-${TOTAL_STEPS}`,
+        data: {},
+        nextStep: null,
+      });
+    }
+
+    const stepLabel = state.steps[stepNumber - 1]?.label ?? 'unknown';
+
+    if (!canRunStep(state, stepNumber)) {
+      return Object.freeze({
+        step: stepNumber,
+        name: stepLabel,
+        success: false,
+        message: `Cannot run step ${stepNumber}. Current step: ${state.currentStep}, status: ${state.status}`,
+        data: {},
+        nextStep: null,
+      });
+    }
+
+    try {
+      const stepData = await deps.executeStep(stepNumber, projectPath);
+      state = completeStep(state, stepNumber, stepData);
+      await deps.saveState(projectPath, state);
+
+      const nextStep = stepNumber < TOTAL_STEPS ? stepNumber + 1 : null;
+      return Object.freeze({
+        step: stepNumber,
+        name: stepLabel,
+        success: true,
+        message: `Step ${stepNumber} completed`,
+        data: stepData,
+        nextStep,
+      });
+    } catch (err) {
+      return Object.freeze({
+        step: stepNumber,
+        name: stepLabel,
+        success: false,
+        message: err instanceof Error ? err.message : 'Step failed',
+        data: {},
+        nextStep: null,
+      });
+    }
+  };
+
+  const reset = async (): Promise<OnboardingStatus> => {
+    const projectPath = deps.getProjectPath();
+    const freshState = createInitialState();
+    await deps.saveState(projectPath, freshState);
+    return toStatus(freshState);
+  };
+
+  return Object.freeze({ getStatus, start, advanceStep, reset });
+};

package/src/services/passport-audit.ts

@@ -0,0 +1,244 @@
+/**
+ * Passport audit & analysis sub-module.
+ * Handles: registry, evidence, permissions, readiness, audit trail, test gen, diff, import, audit pkg.
+ */
+import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { AppError } from '../types/errors.js';
+import type { AgentPassport } from '../types/passport.types.js';
+import { createEvidence } from '../domain/scanner/evidence.js';
+import { computeCompleteness } from '../domain/passport/passport-validator.js';
+import { loadOrCreateKeyPair, signPassport } from '../domain/passport/crypto-signer.js';
+import { computeAgentScore } from '../domain/registry/compute-agent-score.js';
+import type { AgentRegistryEntry } from '../domain/registry/compute-agent-score.js';
+import type { EvidenceChainSummary } from '../domain/scanner/evidence-store.js';
+import { computeReadiness } from '../domain/certification/aiuc1-readiness.js';
+import type { ReadinessResult } from '../domain/certification/aiuc1-readiness.js';
+import { buildPermissionsMatrix } from '../domain/audit/permissions-matrix.js';
+import type { PermissionsMatrix } from '../domain/audit/permissions-matrix.js';
+import { createAuditPackage } from '../domain/audit/audit-package.js';
+import type { AuditPackageResult } from '../domain/audit/audit-package.js';
+import type { AuditFilter, AuditEntry, AuditTrailSummary } from '../domain/audit/audit-trail.js';
+import { generateComplianceTests } from '../domain/passport/test-generator.js';
+import type { GeneratedTestSuite } from '../domain/passport/test-generator.js';
+import { computeManifestDiff } from '../domain/passport/builder/manifest-diff.js';
+import type { ManifestDiffResult } from '../domain/passport/builder/manifest-diff.js';
+import type { PassportServiceDeps } from './passport-service.js';
+
+export interface PassportAuditOps {
+  readonly showPassport: (name: string, projectPath?: string) => Promise<AgentPassport | null>;
+  readonly listPassports: (projectPath?: string) => Promise<readonly AgentPassport[]>;
+}
+
+export const createPassportAudit = (deps: PassportServiceDeps, ops: PassportAuditOps) => {
+  const { showPassport, listPassports } = ops;
+  const { getProjectPath, getLastScanResult, events } = deps;
+
+  const getEvidenceChainSummary = async (
+    _projectPath?: string,
+  ): Promise<EvidenceChainSummary> => {
+    if (!deps.evidenceStore) {
+      return { totalEntries: 0, scanCount: 0, firstEntry: '', lastEntry: '', chainValid: true, uniqueFindings: 0 };
+    }
+    return deps.evidenceStore.getSummary();
+  };
+
+  const verifyEvidenceChain = async (
+    _projectPath?: string,
+  ): Promise<{ valid: boolean; brokenAt?: number }> => {
+    if (!deps.evidenceStore) return { valid: true };
+    return deps.evidenceStore.verify();
+  };
+
+  const getAgentRegistry = async (projectPath?: string): Promise<readonly AgentRegistryEntry[]> => {
+    const path = projectPath ?? getProjectPath();
+    const passports = await listPassports(path);
+    if (passports.length === 0) return [];
+
+    const scanResult = getLastScanResult();
+    const evidenceSummary = await getEvidenceChainSummary();
+
+    const entries: AgentRegistryEntry[] = [];
+    for (const passport of passports) {
+      const completeness = computeCompleteness(passport);
+      entries.push(computeAgentScore({ passport, completeness, scanResult, evidenceSummary }));
+    }
+    return entries;
+  };
+
+  const getPermissionsMatrix = async (projectPath?: string): Promise<PermissionsMatrix> => {
+    const passports = await listPassports(projectPath);
+    return buildPermissionsMatrix(passports);
+  };
+
+  const getReadiness = async (
+    name: string,
+    projectPath?: string,
+  ): Promise<ReadinessResult | null> => {
+    const manifest = await showPassport(name, projectPath);
+    if (manifest === null) return null;
+
+    const scanResult = getLastScanResult();
+    const evidenceSummary = await getEvidenceChainSummary(projectPath);
+
+    const documents = new Set<string>();
+    const compliance = manifest.compliance;
+    if (compliance?.fria_completed) documents.add('fria');
+    if (compliance && 'policy_generated' in compliance && compliance.policy_generated) documents.add('policy');
+    if (compliance?.worker_notification_sent) documents.add('worker-notification');
+
+    const result = computeReadiness({ passport: manifest, scanResult, documents, evidenceSummary });
+
+    if (deps.auditStore) {
+      await deps.auditStore.append('readiness.computed', {
+        name, overallScore: result.overallScore, readinessLevel: result.readinessLevel,
+      }, name);
+    }
+
+    return result;
+  };
+
+  const getAuditTrail = async (filter: AuditFilter): Promise<readonly AuditEntry[]> => {
+    if (!deps.auditStore) return [];
+    return deps.auditStore.query(filter);
+  };
+
+  const getAuditSummary = async (): Promise<AuditTrailSummary> => {
+    if (!deps.auditStore) return { totalEntries: 0, eventCounts: {}, agentNames: [], firstEntry: '', lastEntry: '' };
+    return deps.auditStore.getSummary();
+  };
+
+  const generateTestSuite = async (
+    name: string,
+    projectPath?: string,
+  ): Promise<GeneratedTestSuite> => {
+    const pp = projectPath ?? getProjectPath();
+    const passport = await showPassport(name, pp);
+    if (!passport) throw new Error(`Passport not found: ${name}`);
+
+    const suite = generateComplianceTests({
+      name: passport.name,
+      permissions: passport.permissions ? {
+        tools: passport.permissions.tools as readonly string[],
+        denied: passport.permissions.denied as readonly string[],
+      } : undefined,
+      constraints: passport.constraints ? {
+        rate_limits: passport.constraints.rate_limits
+          ? [{ action: 'actions_per_minute', limit: passport.constraints.rate_limits.max_actions_per_minute, window: '1m' }]
+          : undefined,
+        prohibited_actions: passport.constraints.prohibited_actions as readonly string[],
+        escalation_rules: passport.constraints.escalation_rules?.map(r => ({
+          condition: r.condition,
+          escalate_to: r.description,
+        })),
+        budget: passport.constraints.budget
+          ? { max_cost: passport.constraints.budget.max_cost_per_session_usd, currency: 'USD' }
+          : undefined,
+      } : undefined,
+    });
+
+    const testDir = join(pp, '.complior', 'tests');
+    await mkdir(testDir, { recursive: true });
+    const testPath = join(testDir, suite.filename);
+    await writeFile(testPath, suite.content);
+
+    if (deps.auditStore) {
+      await deps.auditStore.append('test_suite.generated', { name, path: testPath, testCount: suite.testCount }, name);
+    }
+
+    return Object.freeze({ ...suite, filename: testPath });
+  };
+
+  const diffPassport = async (
+    name: string,
+    projectPath?: string,
+  ): Promise<ManifestDiffResult> => {
+    const pp = projectPath ?? getProjectPath();
+    const current = await showPassport(name, pp);
+    if (!current) throw new Error(`Passport not found: ${name}`);
+
+    let previous: Record<string, unknown> = {};
+    try {
+      const historyPath = join(pp, '.complior', 'agents', `${name}-history.json`);
+      const raw = await readFile(historyPath, 'utf-8');
+      const parsed = z.array(z.record(z.unknown())).safeParse(JSON.parse(raw));
+      if (parsed.success && parsed.data.length > 0) {
+        previous = parsed.data[parsed.data.length - 1]!;
+      }
+    } catch {
+      // No history — diff against empty
+    }
+
+    return computeManifestDiff(name, previous, current as Record<string, unknown>);
+  };
+
+  const importPassport = async (
+    format: string,
+    data: unknown,
+    projectPath?: string,
+  ): Promise<{ passport: AgentPassport; fieldsImported: string[]; fieldsMissing: string[] }> => {
+    const path = projectPath ?? getProjectPath();
+
+    if (format !== 'a2a') {
+      throw new AppError(`Unsupported import format: ${format}. Supported: a2a`, 'VALIDATION_ERROR', 400);
+    }
+
+    const { importFromA2A } = await import('../domain/passport/import/a2a-importer.js');
+    const result = importFromA2A(data);
+    const passport = result.passport as AgentPassport;
+
+    const agentsDir = join(path, '.complior', 'agents');
+    await mkdir(agentsDir, { recursive: true });
+
+    const keyPair = await loadOrCreateKeyPair();
+    const signature = signPassport(passport, keyPair.privateKey);
+    const signedPassport: AgentPassport = { ...passport, signature };
+
+    const filePath = join(agentsDir, `${signedPassport.name}-manifest.json`);
+    await writeFile(filePath, JSON.stringify(signedPassport, null, 2));
+
+    if (deps.evidenceStore) {
+      const evidence = createEvidence(signedPassport.name, 'passport', 'passport-import', { file: filePath, snippet: `format: ${format}` });
+      await deps.evidenceStore.append([evidence], randomUUID());
+    }
+
+    if (deps.auditStore) {
+      await deps.auditStore.append('passport.imported', {
+        name: signedPassport.name, format, fieldsImported: result.fieldsImported.length,
+      }, signedPassport.name);
+    }
+
+    events.emit('passport.imported', {
+      name: signedPassport.name, format, fieldsImported: result.fieldsImported.length,
+    });
+
+    return {
+      passport: signedPassport,
+      fieldsImported: [...result.fieldsImported],
+      fieldsMissing: [...result.fieldsMissing],
+    };
+  };
+
+  const generateAuditPackage = async (
+    projectPath?: string,
+  ): Promise<AuditPackageResult> => {
+    const path = projectPath ?? getProjectPath();
+    return createAuditPackage({ getProjectPath: () => path });
+  };
+
+  return Object.freeze({
+    getAgentRegistry,
+    getEvidenceChainSummary,
+    verifyEvidenceChain,
+    getPermissionsMatrix,
+    getReadiness,
+    getAuditTrail,
+    getAuditSummary,
+    generateTestSuite,
+    diffPassport,
+    importPassport,
+    generateAuditPackage,
+  });
+};