@vibe-interviewing/core 0.1.0 → 0.2.0

package/dist/session-code-BusTFalM.d.ts

@@ -0,0 +1,389 @@
+import { z } from 'zod';
+
+declare const AIRulesSchema: z.ZodObject<{
+    /** Role description for the AI assistant */
+    role: z.ZodString;
+    /** Behavioral rules (e.g., "don't reveal the answer") */
+    rules: z.ZodArray<z.ZodString, "many">;
+    /** Knowledge about the bug/solution (hidden from candidate) */
+    knowledge: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    rules: string[];
+    knowledge: string;
+}, {
+    role: string;
+    rules: string[];
+    knowledge: string;
+}>;
+declare const EvaluationSchema: z.ZodObject<{
+    /** Evaluation criteria for the interviewer */
+    criteria: z.ZodArray<z.ZodString, "many">;
+    /** Description of the expected fix */
+    expected_fix: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    criteria: string[];
+    expected_fix?: string | undefined;
+}, {
+    criteria: string[];
+    expected_fix?: string | undefined;
+}>;
+/** Scenario type — determines validation rules and system prompt context */
+declare const ScenarioTypeSchema: z.ZodDefault<z.ZodEnum<["debug", "feature", "refactor"]>>;
+/** Full scenario configuration schema */
+declare const ScenarioConfigSchema: z.ZodObject<{
+    /** Scenario display name */
+    name: z.ZodString;
+    /** One-line description (candidate-visible — describe symptoms/task, never the root cause or solution) */
+    description: z.ZodString;
+    /** Scenario type: debug (find a bug), feature (build something), refactor (improve code) */
+    type: z.ZodDefault<z.ZodEnum<["debug", "feature", "refactor"]>>;
+    /** Difficulty level */
+    difficulty: z.ZodEnum<["easy", "medium", "hard"]>;
+    /** Estimated time (e.g., "30-45m") */
+    estimated_time: z.ZodString;
+    /** Searchable tags */
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** GitHub repo URL or owner/repo shorthand */
+    repo: z.ZodString;
+    /** Commit SHA to pin the clone to (ensures reproducibility) */
+    commit: z.ZodString;
+    /** Shell commands to run after cloning (e.g., ["npm install"]) */
+    setup: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Find-and-replace patches to inject the bug after cloning */
+    patch: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /** Path to the file relative to repo root */
+        file: z.ZodString;
+        /** The original text to find */
+        find: z.ZodString;
+        /** The replacement text (with the bug) */
+        replace: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        find: string;
+        file: string;
+        replace: string;
+    }, {
+        find: string;
+        file: string;
+        replace: string;
+    }>, "many">>;
+    /** Files or directories to delete after cloning (globs relative to repo root) */
+    delete_files: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Briefing shown to the candidate (written like a team lead message) */
+    briefing: z.ZodString;
+    /** AI behavioral rules (injected via system prompt, hidden from candidate) */
+    ai_rules: z.ZodObject<{
+        /** Role description for the AI assistant */
+        role: z.ZodString;
+        /** Behavioral rules (e.g., "don't reveal the answer") */
+        rules: z.ZodArray<z.ZodString, "many">;
+        /** Knowledge about the bug/solution (hidden from candidate) */
+        knowledge: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        role: string;
+        rules: string[];
+        knowledge: string;
+    }, {
+        role: string;
+        rules: string[];
+        knowledge: string;
+    }>;
+    /** Interviewer reference — what the fix/implementation looks like */
+    solution: z.ZodOptional<z.ZodString>;
+    /** Acceptance criteria for feature scenarios (concrete, testable requirements) */
+    acceptance_criteria: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Evaluation rubric */
+    evaluation: z.ZodOptional<z.ZodObject<{
+        /** Evaluation criteria for the interviewer */
+        criteria: z.ZodArray<z.ZodString, "many">;
+        /** Description of the expected fix */
+        expected_fix: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        criteria: string[];
+        expected_fix?: string | undefined;
+    }, {
+        criteria: string[];
+        expected_fix?: string | undefined;
+    }>>;
+    /** License of the original project */
+    license: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "debug" | "feature" | "refactor";
+    name: string;
+    description: string;
+    difficulty: "easy" | "medium" | "hard";
+    estimated_time: string;
+    tags: string[];
+    repo: string;
+    commit: string;
+    setup: string[];
+    patch: {
+        find: string;
+        file: string;
+        replace: string;
+    }[];
+    delete_files: string[];
+    briefing: string;
+    ai_rules: {
+        role: string;
+        rules: string[];
+        knowledge: string;
+    };
+    solution?: string | undefined;
+    acceptance_criteria?: string[] | undefined;
+    evaluation?: {
+        criteria: string[];
+        expected_fix?: string | undefined;
+    } | undefined;
+    license?: string | undefined;
+}, {
+    name: string;
+    description: string;
+    difficulty: "easy" | "medium" | "hard";
+    estimated_time: string;
+    repo: string;
+    commit: string;
+    briefing: string;
+    ai_rules: {
+        role: string;
+        rules: string[];
+        knowledge: string;
+    };
+    type?: "debug" | "feature" | "refactor" | undefined;
+    tags?: string[] | undefined;
+    setup?: string[] | undefined;
+    patch?: {
+        find: string;
+        file: string;
+        replace: string;
+    }[] | undefined;
+    delete_files?: string[] | undefined;
+    solution?: string | undefined;
+    acceptance_criteria?: string[] | undefined;
+    evaluation?: {
+        criteria: string[];
+        expected_fix?: string | undefined;
+    } | undefined;
+    license?: string | undefined;
+}>;
+type ScenarioConfig = z.infer<typeof ScenarioConfigSchema>;
+type ScenarioType = z.infer<typeof ScenarioTypeSchema>;
+type AIRules = z.infer<typeof AIRulesSchema>;
+type Evaluation = z.infer<typeof EvaluationSchema>;
+/** Metadata about a discovered scenario */
+interface ScenarioInfo {
+    /** Scenario name */
+    name: string;
+    /** Parsed config */
+    config: ScenarioConfig;
+    /** Whether this is a built-in scenario */
+    builtIn: boolean;
+}
+
+/** Event types that can be captured during a session */
+type SessionEventType = 'stdout' | 'stderr' | 'command' | 'note';
+/** A single timestamped event captured during a session */
+interface SessionEvent {
+    /** Milliseconds since recording started */
+    timestamp: number;
+    /** The kind of event */
+    type: SessionEventType;
+    /** The captured data */
+    data: string;
+}
+/** Serialized recording format */
+interface RecordingData {
+    /** Session ID this recording belongs to */
+    sessionId: string;
+    /** ISO string of when recording started */
+    startedAt: string;
+    /** All captured events */
+    events: SessionEvent[];
+}
+/**
+ * Records timestamped events during an interview session.
+ *
+ * Captures stdout, stderr, commands, and notes with millisecond timestamps
+ * relative to when the recorder was created.
+ */
+declare class SessionRecorder {
+    private readonly events;
+    private readonly startTime;
+    private readonly startedAt;
+    constructor();
+    /** Record a timestamped event */
+    record(type: SessionEventType, data: string): void;
+    /** Get all recorded events */
+    getEvents(): ReadonlyArray<SessionEvent>;
+    /** Serialize the recording to a JSON-compatible object */
+    toJSON(sessionId: string): RecordingData;
+    /** Create a SessionRecorder pre-populated with events from serialized data */
+    static fromJSON(data: RecordingData): SessionRecorder;
+    /** Save the recording to disk */
+    save(sessionId: string): Promise<void>;
+    /** Load a recording from disk */
+    static load(sessionId: string): Promise<SessionRecorder>;
+    /** List all available recording session IDs */
+    static list(): Promise<string[]>;
+}
+
+/** Configuration for launching an AI coding tool */
+interface LaunchConfig {
+    /** Scenario name for display */
+    scenarioName: string;
+    /** Path to system prompt file (hidden from candidate) */
+    systemPromptPath: string;
+    /** Model to use */
+    model?: string;
+    /** Permission mode for the AI tool */
+    permissionMode?: 'default' | 'plan' | 'acceptEdits' | 'bypassPermissions';
+    /** Tools to disallow (e.g., WebSearch for fairness) */
+    disallowedTools?: string[];
+    /** Whether to record stdout/stderr during the session */
+    recording?: boolean;
+}
+/** A running AI tool process */
+interface LaunchedProcess {
+    /** Wait for the process to exit */
+    wait(): Promise<{
+        exitCode: number;
+    }>;
+    /** Kill the process */
+    kill(): Promise<void>;
+    /** Session recorder, present when recording is enabled */
+    recorder?: SessionRecorder;
+}
+/** Interface for AI coding tool launchers */
+interface AIToolLauncher {
+    /** Internal name identifier */
+    readonly name: string;
+    /** Human-readable display name */
+    readonly displayName: string;
+    /** Check if this tool is installed and accessible */
+    isInstalled(): Promise<boolean>;
+    /** Get the installed version string */
+    getVersion(): Promise<string | null>;
+    /** Launch the tool pointed at a working directory */
+    launch(workdir: string, config: LaunchConfig): Promise<LaunchedProcess>;
+}
+
+/** Status of an interview session */
+type SessionStatus = 'cloning' | 'setting-up' | 'running' | 'complete';
+/** Interview session — used both in-memory and for persistence */
+interface Session {
+    /** Unique session identifier */
+    id: string;
+    /** Name of the scenario being run */
+    scenarioName: string;
+    /** Local working directory for the candidate */
+    workdir: string;
+    /** Path to the system prompt file (outside workspace) */
+    systemPromptPath: string;
+    /** Current session status */
+    status: SessionStatus;
+    /** ISO timestamp of session creation */
+    createdAt: string;
+    /** ISO timestamp of when the AI tool was launched */
+    startedAt?: string;
+    /** ISO timestamp of session completion */
+    completedAt?: string;
+    /** Name of the AI tool used */
+    aiTool?: string;
+}
+/**
+ * Serializable session data for persistence.
+ * Identical to Session — kept as an alias for API clarity at persistence boundaries.
+ */
+type StoredSession = Session;
+/** Convert a Session to a StoredSession for persistence */
+declare function toStoredSession(session: Session): StoredSession;
+
+/** Callback for reporting session progress */
+type ProgressCallback = (stage: string) => void;
+/** Manages the lifecycle of an interview session */
+declare class SessionManager {
+    private launcher;
+    constructor(launcher: AIToolLauncher);
+    /**
+     * Create a new interview session.
+     *
+     * Flow:
+     * 1. Clone the repo at a pinned commit
+     * 2. Apply bug patches (find/replace in source files)
+     * 3. Delete files excluded by the scenario (e.g., tests that reveal the bug)
+     * 4. Wipe git history so the candidate can't diff to find the bug
+     * 5. Remove scenario.yaml from workspace (interviewer-only)
+     * 6. Write BRIEFING.md and system prompt
+     * 7. Run setup commands (npm install, etc.)
+     */
+    createSession(config: ScenarioConfig, workdir?: string, onProgress?: ProgressCallback, options?: {
+        skipSetup?: boolean;
+    }): Promise<{
+        session: Session;
+        config: ScenarioConfig;
+    }>;
+    /** Launch the AI coding tool for an active session */
+    launchAITool(session: Session, _config: ScenarioConfig, launchConfig?: Partial<LaunchConfig>): Promise<{
+        exitCode: number;
+    }>;
+    /** Destroy a session by removing its stored data */
+    destroySession(session: Session): Promise<void>;
+    /** Get elapsed time since the AI tool was launched, formatted as a human-readable string */
+    getElapsedTime(session: Session): string | null;
+}
+
+/** Base error class for all vibe-interviewing errors */
+declare class VibeError extends Error {
+    readonly code: string;
+    readonly hint?: string | undefined;
+    constructor(message: string, code: string, hint?: string | undefined);
+}
+declare class ScenarioNotFoundError extends VibeError {
+    constructor(name: string);
+}
+declare class ScenarioValidationError extends VibeError {
+    readonly issues: string[];
+    constructor(message: string, issues: string[]);
+}
+declare class AIToolNotFoundError extends VibeError {
+    static readonly installHints: Record<string, string>;
+    constructor(tool: string);
+}
+declare class SessionNotFoundError extends VibeError {
+    constructor(id: string);
+}
+declare class GitCloneError extends VibeError {
+    constructor(repo: string, reason?: string);
+}
+declare class SetupError extends VibeError {
+    constructor(command: string, reason?: string);
+}
+
+/**
+ * Encode a host:port pair into a human-typeable session code.
+ *
+ * Format: VIBE-XXXXXXXXXX (10 base36 chars encoding 6 bytes: 4 IP octets + 2 port bytes)
+ */
+declare function encodeSessionCode(host: string, port: number): string;
+/**
+ * Decode a session code back to host:port.
+ *
+ * Accepts formats: VIBE-XXXXXXXXXX, vibe-xxxxxxxxxx, or just XXXXXXXXXX
+ */
+declare function decodeSessionCode(code: string): {
+    host: string;
+    port: number;
+};
+/**
+ * Check if a session code is a cloud code (6 chars) vs LAN code (10 chars).
+ *
+ * Cloud codes are 6 alphanumeric characters: VIBE-A3X9K2
+ * LAN codes are 10 alphanumeric characters: VIBE-3R8KW1F0NX
+ */
+declare function isCloudSessionCode(code: string): boolean;
+/** Error for invalid session codes */
+declare class InvalidSessionCodeError extends VibeError {
+    constructor(message: string);
+}
+
+export { type AIToolLauncher as A, type Evaluation as E, GitCloneError as G, InvalidSessionCodeError as I, type LaunchConfig as L, type ProgressCallback as P, type RecordingData as R, type ScenarioConfig as S, VibeError as V, type ScenarioInfo as a, type LaunchedProcess as b, type StoredSession as c, type AIRules as d, AIToolNotFoundError as e, ScenarioConfigSchema as f, ScenarioNotFoundError as g, type ScenarioType as h, ScenarioValidationError as i, type Session as j, type SessionEvent as k, type SessionEventType as l, SessionManager as m, SessionNotFoundError as n, SessionRecorder as o, SetupError as p, decodeSessionCode as q, encodeSessionCode as r, isCloudSessionCode as s, toStoredSession as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-interviewing/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Core library for vibe-interviewing — scenario engine, session management, AI tool launchers",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,13 +9,17 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./network": {
+      "types": "./dist/network/index.d.ts",
+      "default": "./dist/network/index.js"
     }
   },
   "dependencies": {
     "simple-git": "^3.27.0",
     "yaml": "^2.7.0",
     "zod": "^3.24.0",
-    "@vibe-interviewing/scenarios": "0.1.0"
+    "@vibe-interviewing/scenarios": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.17.0",