@complior/engine 0.9.0

package/src/domain/import/promptfoo-importer.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect } from 'vitest';
+import { importFromPromptfoo } from './promptfoo-importer.js';
+
+const validInput = {
+  version: 2,
+  timestamp: '2026-03-17T10:00:00.000Z',
+  results: {
+    results: [
+      {
+        success: true,
+        score: 1.0,
+        metadata: { pluginId: 'prompt-extraction' },
+        namedScores: {},
+      },
+      {
+        success: false,
+        score: 0.0,
+        metadata: { pluginId: 'harmful:privacy' },
+        namedScores: {},
+      },
+      {
+        success: true,
+        score: 1.0,
+        metadata: { pluginId: 'shell-injection' },
+        namedScores: {},
+      },
+    ],
+    stats: {
+      successes: 2,
+      failures: 1,
+    },
+  },
+};
+
+describe('importFromPromptfoo', () => {
+  it('imports valid Promptfoo JSON', () => {
+    const result = importFromPromptfoo(validInput);
+    expect(result.probesRun).toBe(3);
+    expect(result.probesPassed).toBe(2);
+    expect(result.probesFailed).toBe(1);
+    expect(result.testResults).toHaveLength(3);
+    expect(result.securityScore.score).toBeGreaterThan(0);
+    expect(result.timestamp).toBe('2026-03-17T10:00:00.000Z');
+  });
+
+  it('calculates security score from results', () => {
+    const result = importFromPromptfoo(validInput);
+    expect(result.securityScore.grade).toBeTruthy();
+    expect(result.securityScore.categories.length).toBeGreaterThan(0);
+  });
+
+  it('throws VALIDATION_ERROR on invalid input', () => {
+    expect(() => importFromPromptfoo({ invalid: true })).toThrow('VALIDATION_ERROR');
+  });
+
+  it('throws VALIDATION_ERROR on non-object', () => {
+    expect(() => importFromPromptfoo('not json')).toThrow('VALIDATION_ERROR');
+  });
+
+  it('throws VALIDATION_ERROR on null', () => {
+    expect(() => importFromPromptfoo(null)).toThrow('VALIDATION_ERROR');
+  });
+
+  it('handles results with no metadata gracefully', () => {
+    const input = {
+      results: {
+        results: [
+          { success: true, score: 1.0 },
+          { success: false, score: 0.0 },
+        ],
+      },
+    };
+    const result = importFromPromptfoo(input);
+    expect(result.probesRun).toBe(2);
+    expect(result.probesPassed).toBe(1);
+    expect(result.probesFailed).toBe(1);
+  });
+
+  it('handles empty results array', () => {
+    const input = {
+      results: {
+        results: [],
+      },
+    };
+    const result = importFromPromptfoo(input);
+    expect(result.probesRun).toBe(0);
+    expect(result.securityScore.score).toBe(0);
+    expect(result.securityScore.grade).toBe('F');
+  });
+
+  it('maps plugin IDs to OWASP categories', () => {
+    const input = {
+      results: {
+        results: [
+          { success: false, metadata: { pluginId: 'prompt-extraction' } },
+        ],
+      },
+    };
+    const result = importFromPromptfoo(input);
+    // prompt-extraction maps to LLM01 (Prompt Injection)
+    expect(result.testResults[0]!.owaspCategory).toBe('LLM01');
+  });
+});

package/src/domain/import/promptfoo-importer.ts

@@ -0,0 +1,151 @@
+/**
+ * Promptfoo Result Importer.
+ * Parses Promptfoo red-team JSON output into our native format.
+ * Zero runtime dependency on Promptfoo.
+ */
+
+import { z } from 'zod';
+import { getOwaspCategoriesForPlugin } from '../../data/security/owasp-llm-top10.js';
+import { calculateSecurityScore } from '../scanner/security-score.js';
+import type { SecurityScoreResult, TestResultInput } from '../scanner/security-score.js';
+
+// ── Zod schema for Promptfoo JSON output ────────────────────────
+
+const PromptfooAssertionResultSchema = z.object({
+  pass: z.boolean(),
+  score: z.number().optional(),
+  reason: z.string().optional(),
+  metric: z.string().optional(),
+});
+
+const PromptfooResultSchema = z.object({
+  prompt: z.object({
+    raw: z.string().optional(),
+    label: z.string().optional(),
+  }).optional(),
+  response: z.object({
+    output: z.string().optional(),
+  }).optional(),
+  vars: z.record(z.unknown()).optional(),
+  success: z.boolean(),
+  score: z.number().optional(),
+  gradingResult: z.object({
+    pass: z.boolean(),
+    score: z.number().optional(),
+    reason: z.string().optional(),
+    componentResults: z.array(PromptfooAssertionResultSchema).optional(),
+  }).optional(),
+  namedScores: z.record(z.number()).optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+const PromptfooOutputSchema = z.object({
+  version: z.number().optional(),
+  timestamp: z.string().optional(),
+  results: z.object({
+    results: z.array(PromptfooResultSchema),
+    stats: z.object({
+      successes: z.number(),
+      failures: z.number(),
+      tokenUsage: z.object({
+        total: z.number().optional(),
+        prompt: z.number().optional(),
+        completion: z.number().optional(),
+      }).optional(),
+    }).optional(),
+  }),
+});
+
+// ── Types ────────────────────────────────────────────────────────
+
+export interface PromptfooImportResult {
+  readonly testResults: readonly TestResultInput[];
+  readonly securityScore: SecurityScoreResult;
+  readonly probesRun: number;
+  readonly probesPassed: number;
+  readonly probesFailed: number;
+  readonly timestamp: string;
+}
+
+// ── Importer ─────────────────────────────────────────────────────
+
+/**
+ * Import and transform Promptfoo JSON results into our native format.
+ * Validates input via Zod, maps results to OWASP categories, calculates security score.
+ *
+ * @throws {Error} with message starting with "VALIDATION_ERROR:" on invalid input.
+ */
+export const importFromPromptfoo = (data: unknown): PromptfooImportResult => {
+  const parsed = PromptfooOutputSchema.safeParse(data);
+
+  if (!parsed.success) {
+    throw new Error(`VALIDATION_ERROR: Invalid Promptfoo JSON: ${parsed.error.issues.map((i) => i.message).join(', ')}`);
+  }
+
+  const { results: resultWrapper, timestamp } = parsed.data;
+  const results = resultWrapper.results;
+
+  const testResults: TestResultInput[] = [];
+
+  for (const result of results) {
+    const pass = result.success;
+    const verdict: 'pass' | 'fail' = pass ? 'pass' : 'fail';
+
+    // Derive plugin from metadata or namedScores
+    const pluginId = extractPluginId(result);
+    const categories = pluginId ? getOwaspCategoriesForPlugin(pluginId) : [];
+    const category = categories[0];
+
+    testResults.push({
+      probeId: pluginId ?? 'unknown',
+      owaspCategory: category?.id ?? 'UNCATEGORIZED',
+      categoryName: category?.name ?? 'Uncategorized',
+      verdict,
+      severity: deriveSeverity(category?.severity ?? 'medium'),
+    });
+  }
+
+  const securityScore = calculateSecurityScore(testResults);
+
+  return Object.freeze({
+    testResults: Object.freeze(testResults),
+    securityScore,
+    probesRun: results.length,
+    probesPassed: testResults.filter((t) => t.verdict === 'pass').length,
+    probesFailed: testResults.filter((t) => t.verdict === 'fail').length,
+    timestamp: timestamp ?? new Date().toISOString(),
+  });
+};
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function extractPluginId(result: z.infer<typeof PromptfooResultSchema>): string | undefined {
+  // Try metadata.pluginId first
+  const meta = result.metadata;
+  if (meta && typeof meta['pluginId'] === 'string') {
+    return meta['pluginId'];
+  }
+
+  // Try namedScores keys (Promptfoo uses plugin names as metric keys)
+  if (result.namedScores) {
+    const keys = Object.keys(result.namedScores);
+    if (keys.length > 0) return keys[0];
+  }
+
+  // Try gradingResult metric
+  if (result.gradingResult?.componentResults) {
+    for (const cr of result.gradingResult.componentResults) {
+      if (cr.metric) return cr.metric;
+    }
+  }
+
+  return undefined;
+}
+
+function deriveSeverity(severity: string): string {
+  const normalized = severity.toLowerCase();
+  if (['critical', 'high', 'medium', 'low', 'info'].includes(normalized)) {
+    return normalized;
+  }
+  return 'medium';
+}

package/src/domain/onboarding/guided-onboarding.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createInitialState,
+  startOnboarding,
+  completeStep,
+  skipStep,
+  canRunStep,
+  getProgress,
+} from './guided-onboarding.js';
+
+describe('guided-onboarding state machine', () => {
+  it('creates initial state with 5 pending steps', () => {
+    const state = createInitialState();
+    expect(state.status).toBe('not_started');
+    expect(state.currentStep).toBe(0);
+    expect(state.steps).toHaveLength(5);
+    expect(state.steps.every((s) => s.status === 'pending')).toBe(true);
+  });
+
+  it('starts onboarding — step 1 becomes in_progress', () => {
+    const state = startOnboarding(createInitialState());
+    expect(state.status).toBe('in_progress');
+    expect(state.currentStep).toBe(1);
+    expect(state.steps[0].status).toBe('in_progress');
+    expect(state.startedAt).toBeTruthy();
+  });
+
+  it('does not restart a completed onboarding', () => {
+    let state = startOnboarding(createInitialState());
+    for (let i = 1; i <= 5; i++) {
+      state = completeStep(state, i);
+    }
+    expect(state.status).toBe('completed');
+
+    const restarted = startOnboarding(state);
+    expect(restarted.status).toBe('completed');
+  });
+
+  it('completes step 1 and advances to step 2', () => {
+    const state = startOnboarding(createInitialState());
+    const next = completeStep(state, 1, { language: 'TypeScript' });
+
+    expect(next.steps[0].status).toBe('completed');
+    expect(next.steps[0].data).toEqual({ language: 'TypeScript' });
+    expect(next.steps[0].completedAt).toBeTruthy();
+    expect(next.steps[1].status).toBe('in_progress');
+    expect(next.currentStep).toBe(2);
+    expect(next.status).toBe('in_progress');
+  });
+
+  it('completes step 5 and marks onboarding as completed', () => {
+    let state = startOnboarding(createInitialState());
+    for (let i = 1; i <= 5; i++) {
+      state = completeStep(state, i, { step: i });
+    }
+
+    expect(state.status).toBe('completed');
+    expect(state.completedAt).toBeTruthy();
+    expect(state.steps.every((s) => s.status === 'completed')).toBe(true);
+  });
+
+  it('skip step marks status as skipped and advances', () => {
+    const state = startOnboarding(createInitialState());
+    const next = skipStep(state, 1);
+
+    expect(next.steps[0].status).toBe('skipped');
+    expect(next.steps[0].completedAt).toBeTruthy();
+    expect(next.steps[1].status).toBe('in_progress');
+    expect(next.currentStep).toBe(2);
+  });
+
+  it('canRunStep returns true only for current step', () => {
+    const state = startOnboarding(createInitialState());
+    expect(canRunStep(state, 1)).toBe(true);
+    expect(canRunStep(state, 2)).toBe(false);
+    expect(canRunStep(state, 0)).toBe(false);
+    expect(canRunStep(state, 6)).toBe(false);
+  });
+
+  it('canRunStep returns false for not_started state', () => {
+    const state = createInitialState();
+    expect(canRunStep(state, 1)).toBe(false);
+  });
+
+  it('getProgress tracks completion', () => {
+    let state = startOnboarding(createInitialState());
+    expect(getProgress(state)).toEqual({ completedSteps: 0, totalSteps: 5, percentage: 0 });
+
+    state = completeStep(state, 1);
+    expect(getProgress(state)).toEqual({ completedSteps: 1, totalSteps: 5, percentage: 20 });
+
+    state = completeStep(state, 2);
+    state = completeStep(state, 3);
+    expect(getProgress(state)).toEqual({ completedSteps: 3, totalSteps: 5, percentage: 60 });
+  });
+
+  it('ignores invalid step numbers', () => {
+    const state = startOnboarding(createInitialState());
+    const same = completeStep(state, 0);
+    expect(same).toEqual(state);
+
+    const same2 = completeStep(state, 6);
+    expect(same2).toEqual(state);
+  });
+
+  it('returns frozen state objects', () => {
+    const initial = createInitialState();
+    expect(Object.isFrozen(initial)).toBe(true);
+
+    const started = startOnboarding(initial);
+    expect(Object.isFrozen(started)).toBe(true);
+
+    const completed = completeStep(started, 1);
+    expect(Object.isFrozen(completed)).toBe(true);
+  });
+
+  it('step names are correct', () => {
+    const state = createInitialState();
+    const names = state.steps.map((s) => s.name);
+    expect(names).toEqual(['detect', 'scan', 'passport', 'fix', 'document']);
+  });
+
+  it('step labels are human readable', () => {
+    const state = createInitialState();
+    expect(state.steps[0].label).toBe('Detect Project');
+    expect(state.steps[1].label).toBe('First Compliance Scan');
+    expect(state.steps[2].label).toBe('Generate Agent Passport');
+    expect(state.steps[3].label).toBe('Top-3 Quick Fixes');
+    expect(state.steps[4].label).toBe('Generate Compliance Document');
+  });
+
+  it('can resume from step 3 after restart', () => {
+    let state = startOnboarding(createInitialState());
+    state = completeStep(state, 1, { language: 'Python' });
+    state = completeStep(state, 2, { score: 45 });
+
+    // Simulate JSON persistence + reload
+    const serialized = JSON.parse(JSON.stringify(state));
+    expect(serialized.currentStep).toBe(3);
+    expect(serialized.status).toBe('in_progress');
+    expect(serialized.steps[2].status).toBe('in_progress');
+    expect(canRunStep(serialized, 3)).toBe(true);
+  });
+});

package/src/domain/onboarding/guided-onboarding.ts

@@ -0,0 +1,135 @@
+/**
+ * US-S05-33: Guided 5-step onboarding state machine.
+ * Pure domain logic — no I/O, no side effects.
+ */
+
+export type GuidedStepName =
+  | 'detect'
+  | 'scan'
+  | 'passport'
+  | 'fix'
+  | 'document';
+
+export type GuidedStepStatus = 'pending' | 'in_progress' | 'completed' | 'skipped';
+
+export interface GuidedStepState {
+  readonly step: number;
+  readonly name: GuidedStepName;
+  readonly label: string;
+  readonly status: GuidedStepStatus;
+  readonly data?: Record<string, unknown>;
+  readonly completedAt?: string;
+}
+
+export interface GuidedOnboardingState {
+  readonly currentStep: number;
+  readonly status: 'not_started' | 'in_progress' | 'completed';
+  readonly steps: readonly GuidedStepState[];
+  readonly startedAt?: string;
+  readonly completedAt?: string;
+}
+
+const STEP_DEFINITIONS: readonly { name: GuidedStepName; label: string }[] = [
+  { name: 'detect', label: 'Detect Project' },
+  { name: 'scan', label: 'First Compliance Scan' },
+  { name: 'passport', label: 'Generate Agent Passport' },
+  { name: 'fix', label: 'Top-3 Quick Fixes' },
+  { name: 'document', label: 'Generate Compliance Document' },
+];
+
+/** Total number of onboarding steps (derived from STEP_DEFINITIONS). */
+export const TOTAL_STEPS = STEP_DEFINITIONS.length;
+
+export const createInitialState = (): GuidedOnboardingState => {
+  const steps = STEP_DEFINITIONS.map((def, i) => ({
+    step: i + 1,
+    name: def.name,
+    label: def.label,
+    status: 'pending' as GuidedStepStatus,
+  }));
+
+  return Object.freeze({
+    currentStep: 0,
+    status: 'not_started',
+    steps,
+  });
+};
+
+export const startOnboarding = (state: GuidedOnboardingState): GuidedOnboardingState => {
+  if (state.status === 'completed') return state;
+
+  return Object.freeze({
+    ...state,
+    currentStep: 1,
+    status: 'in_progress',
+    startedAt: state.startedAt ?? new Date().toISOString(),
+    steps: state.steps.map((s, i) =>
+      i === 0 ? { ...s, status: 'in_progress' as GuidedStepStatus } : s,
+    ),
+  });
+};
+
+const advanceStep = (
+  state: GuidedOnboardingState,
+  stepNumber: number,
+  stepStatus: GuidedStepStatus,
+  data?: Record<string, unknown>,
+): GuidedOnboardingState => {
+  if (stepNumber < 1 || stepNumber > TOTAL_STEPS) return state;
+  if (state.status !== 'in_progress') return state;
+
+  const idx = stepNumber - 1;
+  const isLastStep = stepNumber === TOTAL_STEPS;
+  const nextStep = isLastStep ? TOTAL_STEPS : stepNumber + 1;
+
+  const newSteps = state.steps.map((s, i) => {
+    if (i === idx) {
+      return { ...s, status: stepStatus, data, completedAt: new Date().toISOString() };
+    }
+    if (i === idx + 1 && !isLastStep) {
+      return { ...s, status: 'in_progress' as GuidedStepStatus };
+    }
+    return s;
+  });
+
+  return Object.freeze({
+    ...state,
+    currentStep: nextStep,
+    status: isLastStep ? 'completed' : 'in_progress',
+    completedAt: isLastStep ? new Date().toISOString() : undefined,
+    steps: newSteps,
+  });
+};
+
+export const completeStep = (
+  state: GuidedOnboardingState,
+  stepNumber: number,
+  data?: Record<string, unknown>,
+): GuidedOnboardingState => advanceStep(state, stepNumber, 'completed', data);
+
+export const skipStep = (
+  state: GuidedOnboardingState,
+  stepNumber: number,
+): GuidedOnboardingState => advanceStep(state, stepNumber, 'skipped');
+
+export const canRunStep = (state: GuidedOnboardingState, stepNumber: number): boolean => {
+  if (stepNumber < 1 || stepNumber > TOTAL_STEPS) return false;
+  if (state.status !== 'in_progress') return false;
+  return state.currentStep === stepNumber;
+};
+
+export const getProgress = (state: GuidedOnboardingState): {
+  completedSteps: number;
+  totalSteps: number;
+  percentage: number;
+} => {
+  const completedSteps = state.steps.filter(
+    (s) => s.status === 'completed' || s.status === 'skipped',
+  ).length;
+
+  return {
+    completedSteps,
+    totalSteps: TOTAL_STEPS,
+    percentage: Math.round((completedSteps / TOTAL_STEPS) * 100),
+  };
+};

package/src/domain/passport/builder/domain-mapper.ts

@@ -0,0 +1,9 @@
+import type { AgentPassport } from '../../../types/passport.types.js';
+
+/** Map AgentPassport to a domain string (analytics, coding, other). */
+export const mapDomain = (manifest: AgentPassport): string => {
+  if (manifest.type === 'autonomous') return 'analytics';
+  const tools = manifest.permissions?.tools ?? [];
+  if (tools.some((t: string) => t.includes('code') || t.includes('file'))) return 'coding';
+  return 'other';
+};