@vibe-interviewing/core 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,3 +1,18 @@
+import {
+  AIToolNotFoundError,
+  GitCloneError,
+  InvalidSessionCodeError,
+  ScenarioFetchError,
+  ScenarioNotFoundError,
+  ScenarioValidationError,
+  SessionNotFoundError,
+  SetupError,
+  VibeError,
+  decodeSessionCode,
+  encodeSessionCode,
+  isCloudSessionCode
+} from "./chunk-CI3BD2WQ.js";
+
 // src/scenario/types.ts
 import { z } from "zod";
 var AIRulesSchema = z.object({
@@ -14,6 +29,24 @@ var EvaluationSchema = z.object({
   /** Description of the expected fix */
   expected_fix: z.string().optional()
 });
+var KeySignalSchema = z.object({
+  /** What behavior or skill this signal measures */
+  signal: z.string(),
+  /** What a strong candidate does (green flag) */
+  positive: z.string(),
+  /** What a weak candidate does (red flag) */
+  negative: z.string()
+});
+var InterviewerGuideSchema = z.object({
+  /** High-level summary of what this scenario evaluates and why */
+  overview: z.string(),
+  /** Specific behaviors to watch for, with green/red flag indicators */
+  key_signals: z.array(KeySignalSchema).default([]),
+  /** Common mistakes candidates make */
+  common_pitfalls: z.array(z.string()).default([]),
+  /** Questions to ask the candidate after the session */
+  debrief_questions: z.array(z.string()).default([])
+});
 var PatchSchema = z.object({
   /** Path to the file relative to repo root */
   file: z.string(),
@@ -22,11 +55,14 @@ var PatchSchema = z.object({
   /** The replacement text (with the bug) */
   replace: z.string()
 });
+var ScenarioTypeSchema = z.enum(["debug", "feature", "refactor"]).default("debug");
 var ScenarioConfigSchema = z.object({
   /** Scenario display name */
   name: z.string(),
-  /** One-line description */
+  /** One-line description (candidate-visible — describe symptoms/task, never the root cause or solution) */
   description: z.string(),
+  /** Scenario type: debug (find a bug), feature (build something), refactor (improve code) */
+  type: ScenarioTypeSchema,
   /** Difficulty level */
   difficulty: z.enum(["easy", "medium", "hard"]),
   /** Estimated time (e.g., "30-45m") */
@@ -41,14 +77,20 @@ var ScenarioConfigSchema = z.object({
   setup: z.array(z.string()).default([]),
   /** Find-and-replace patches to inject the bug after cloning */
   patch: z.array(PatchSchema).default([]),
+  /** Files or directories to delete after cloning (globs relative to repo root) */
+  delete_files: z.array(z.string()).default([]),
   /** Briefing shown to the candidate (written like a team lead message) */
   briefing: z.string(),
   /** AI behavioral rules (injected via system prompt, hidden from candidate) */
   ai_rules: AIRulesSchema,
-  /** Interviewer reference — what the fix looks like */
-  solution: z.string(),
+  /** Interviewer reference — what the fix/implementation looks like */
+  solution: z.string().optional(),
+  /** Acceptance criteria for feature scenarios (concrete, testable requirements) */
+  acceptance_criteria: z.array(z.string()).optional(),
   /** Evaluation rubric */
   evaluation: EvaluationSchema.optional(),
+  /** Structured interviewer guide — what to watch for, common pitfalls, debrief questions */
+  interviewer_guide: InterviewerGuideSchema.optional(),
   /** License of the original project */
   license: z.string().optional()
 });
@@ -56,90 +98,76 @@ var ScenarioConfigSchema = z.object({
 // src/scenario/loader.ts
 import { readFile } from "fs/promises";
 import { parse as parseYaml } from "yaml";
-
-// src/errors.ts
-var VibeError = class extends Error {
-  constructor(message, code, hint) {
-    super(message);
-    this.code = code;
-    this.hint = hint;
-    this.name = "VibeError";
-  }
-};
-var ScenarioNotFoundError = class extends VibeError {
-  constructor(name) {
-    super(
-      `Scenario not found: ${name}`,
-      "SCENARIO_NOT_FOUND",
-      "Run `vibe-interviewing list` to see available scenarios"
-    );
-  }
-};
-var ScenarioValidationError = class extends VibeError {
-  constructor(message, issues) {
-    super(`Invalid scenario config: ${message}`, "SCENARIO_VALIDATION_ERROR", issues.join("\n"));
-    this.issues = issues;
-  }
-};
-var AIToolNotFoundError = class _AIToolNotFoundError extends VibeError {
-  static installHints = {
-    "claude-code": "Install Claude Code: npm install -g @anthropic-ai/claude-code"
-  };
-  constructor(tool) {
-    super(
-      `${tool} is not installed`,
-      "AI_TOOL_NOT_FOUND",
-      _AIToolNotFoundError.installHints[tool] ?? `Install ${tool} and try again`
-    );
+import { existsSync } from "fs";
+var MAX_RESPONSE_BYTES = 1048576;
+var FETCH_TIMEOUT_MS = 15e3;
+function isUrl(input) {
+  return input.startsWith("http://") || input.startsWith("https://");
+}
+function toGitHubRawUrl(url) {
+  const match = url.match(/^https?:\/\/github\.com\/([^/]+\/[^/]+)\/blob\/(.+)$/);
+  if (match) {
+    return `https://raw.githubusercontent.com/${match[1]}/${match[2]}`;
   }
-};
-var SessionNotFoundError = class extends VibeError {
-  constructor(id) {
-    super(
-      `Session not found: ${id}`,
-      "SESSION_NOT_FOUND",
-      "Run `vibe-interviewing list` to see active sessions"
-    );
+  return url;
+}
+async function fetchScenarioYaml(url) {
+  const rawUrl = toGitHubRawUrl(url);
+  let response;
+  try {
+    response = await fetch(rawUrl, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: { Accept: "text/plain, application/x-yaml, */*" }
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "unknown error";
+    throw new ScenarioFetchError(url, message);
   }
-};
-var GitCloneError = class extends VibeError {
-  constructor(repo, reason) {
-    super(
-      `Failed to clone repository: ${repo}${reason ? ` \u2014 ${reason}` : ""}`,
-      "GIT_CLONE_FAILED",
-      "Check the repo URL and your network connection"
-    );
+  if (!response.ok) {
+    throw new ScenarioFetchError(url, `HTTP ${response.status} ${response.statusText}`);
   }
-};
-var SetupError = class extends VibeError {
-  constructor(command, reason) {
-    super(
-      `Setup command failed: ${command}${reason ? ` \u2014 ${reason}` : ""}`,
-      "SETUP_FAILED",
-      "Check the scenario setup commands and try again"
-    );
+  const contentLength = response.headers.get("content-length");
+  if (contentLength && parseInt(contentLength, 10) > MAX_RESPONSE_BYTES) {
+    throw new ScenarioFetchError(url, "response too large (>1 MB)");
   }
-};
-
-// src/scenario/loader.ts
-import { existsSync } from "fs";
-async function loadScenarioConfig(configPath) {
-  if (!existsSync(configPath)) {
-    throw new ScenarioNotFoundError(configPath);
+  const text = await response.text();
+  if (text.length > MAX_RESPONSE_BYTES) {
+    throw new ScenarioFetchError(url, "response too large (>1 MB)");
   }
-  const raw = await readFile(configPath, "utf-8");
+  return text;
+}
+function parseScenarioYaml(raw, source) {
   const parsed = parseYaml(raw);
   const result = ScenarioConfigSchema.safeParse(parsed);
   if (!result.success) {
     const issues = result.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`);
-    throw new ScenarioValidationError("validation failed", issues);
+    throw new ScenarioValidationError(`validation failed (${source})`, issues);
   }
   return result.data;
 }
+async function loadScenarioConfig(pathOrUrl) {
+  if (isUrl(pathOrUrl)) {
+    const raw2 = await fetchScenarioYaml(pathOrUrl);
+    return parseScenarioYaml(raw2, pathOrUrl);
+  }
+  if (!existsSync(pathOrUrl)) {
+    throw new ScenarioNotFoundError(pathOrUrl);
+  }
+  const raw = await readFile(pathOrUrl, "utf-8");
+  return parseScenarioYaml(raw, pathOrUrl);
+}
 function generateSystemPrompt(config) {
   const lines = [];
   lines.push(`# Interview Scenario: ${config.name}`);
   lines.push("");
+  const typeDescriptions = {
+    debug: "The candidate is debugging a bug in this codebase. Guide them through the debugging process without revealing the answer.",
+    feature: "The candidate is building a new feature. Help them understand the requirements, plan their approach, and implement it. Offer architectural guidance but let them drive the implementation.",
+    refactor: "The candidate is improving existing code. Help them identify issues and plan improvements. Encourage them to explain their reasoning for changes."
+  };
+  lines.push("## Scenario Type");
+  lines.push(typeDescriptions[config.type] ?? typeDescriptions["debug"]);
+  lines.push("");
   lines.push("## Your Role");
   lines.push(config.ai_rules.role.trim());
   lines.push("");
@@ -148,13 +176,18 @@ function generateSystemPrompt(config) {
     lines.push(`- ${rule}`);
   }
   lines.push("");
-  lines.push("## Knowledge (DO NOT share directly with the candidate)");
+  const knowledgeHeaders = {
+    debug: "Knowledge (DO NOT share directly with the candidate)",
+    feature: "Implementation Context (DO NOT share directly with the candidate)",
+    refactor: "Improvement Context (DO NOT share directly with the candidate)"
+  };
+  lines.push(`## ${knowledgeHeaders[config.type] ?? knowledgeHeaders["debug"]}`);
   lines.push(config.ai_rules.knowledge.trim());
   return lines.join("\n");
 }
 
 // src/scenario/validator.ts
-async function validateScenario(config) {
+function validateScenario(config) {
   const warnings = [];
   const errors = [];
   if (!config.briefing.trim()) {
@@ -168,24 +201,46 @@ async function validateScenario(config) {
   }
   if (!config.commit.trim()) {
     errors.push("commit cannot be empty \u2014 pin to a specific commit SHA for reproducibility");
+  } else if (!/^[0-9a-f]{7,40}$/i.test(config.commit.trim())) {
+    errors.push(
+      "commit must be a hex SHA (7-40 characters) \u2014 branch/tag names are not allowed for reproducibility"
+    );
   }
   if (config.ai_rules.rules.length === 0) {
     warnings.push("ai_rules.rules is empty \u2014 the AI will have no behavioral constraints");
   }
-  if (!config.solution.trim()) {
-    warnings.push("solution is empty \u2014 interviewers will have no solution reference");
+  if (config.type === "debug") {
+    if (config.patch.length === 0) {
+      warnings.push("debug scenario has no patches \u2014 a bug must be injected via patch");
+    }
+    if (!config.solution?.trim()) {
+      warnings.push("solution is empty \u2014 interviewers will have no solution reference");
+    }
+  }
+  if (config.type === "feature") {
+    const hasCriteria = config.acceptance_criteria && config.acceptance_criteria.length > 0 || config.evaluation && config.evaluation.criteria && config.evaluation.criteria.length > 0;
+    if (!hasCriteria) {
+      warnings.push(
+        "feature scenario has no acceptance_criteria or evaluation.criteria \u2014 candidates need a definition of done"
+      );
+    }
   }
   if (!config.evaluation) {
     warnings.push("No evaluation criteria defined");
   }
+  if (!config.interviewer_guide) {
+    warnings.push(
+      "No interviewer_guide defined \u2014 interviewers will have limited context during the session"
+    );
+  }
   return {
     valid: errors.length === 0,
     warnings,
     errors
   };
 }
-async function validateScenarioOrThrow(config) {
-  const result = await validateScenario(config);
+function validateScenarioOrThrow(config) {
+  const result = validateScenario(config);
   if (!result.valid) {
     throw new ScenarioValidationError("scenario validation failed", result.errors);
   }
@@ -230,6 +285,10 @@ async function discoverBuiltInScenarios() {
         config,
         builtIn: true
       });
+    } else {
+      console.warn(
+        `Warning: scenario "${entry.name}" listed in registry but ${scenarioConfigPath} not found`
+      );
     }
   }
   return scenarios;
@@ -326,6 +385,9 @@ var SessionRecorder = class _SessionRecorder {
   static fromJSON(data) {
     const recorder = new _SessionRecorder();
     Object.defineProperty(recorder, "startedAt", { value: data.startedAt });
+    Object.defineProperty(recorder, "startTime", {
+      value: new Date(data.startedAt).getTime()
+    });
     for (const event of data.events) {
       recorder.events.push({ ...event });
     }
@@ -496,17 +558,7 @@ async function listActiveSessions() {
 
 // src/session/types.ts
 function toStoredSession(session) {
-  return {
-    id: session.id,
-    scenarioName: session.scenarioName,
-    status: session.status,
-    workdir: session.workdir,
-    systemPromptPath: session.systemPromptPath,
-    aiTool: session.aiTool,
-    createdAt: session.createdAt,
-    startedAt: session.startedAt,
-    completedAt: session.completedAt
-  };
+  return { ...session };
 }
 
 // src/session/manager.ts
@@ -520,12 +572,13 @@ var SessionManager = class {
    * Flow:
    * 1. Clone the repo at a pinned commit
    * 2. Apply bug patches (find/replace in source files)
-   * 3. Wipe git history so the candidate can't diff to find the bug
-   * 4. Remove scenario.yaml from workspace (interviewer-only)
-   * 5. Write BRIEFING.md and system prompt
-   * 6. Run setup commands (npm install, etc.)
+   * 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.)
    */
-  async createSession(config, workdir, onProgress) {
+  async createSession(config, workdir, onProgress, options) {
     const id = randomBytes(4).toString("hex");
     const sessionDir = workdir ?? join5(homedir3(), "vibe-sessions", `${config.name}-${id}`);
     const session = {
@@ -542,7 +595,7 @@ var SessionManager = class {
     for (const p of config.patch) {
       const filePath = join5(sessionDir, p.file);
       const content = await readFile6(filePath, "utf-8");
-      const patched = content.replace(p.find, p.replace);
+      const patched = content.replaceAll(p.find, p.replace);
       if (patched === content) {
         throw new SetupError(
           `patch ${p.file}`,
@@ -551,12 +604,18 @@ var SessionManager = class {
       }
       await writeFile3(filePath, patched);
     }
+    if (config.delete_files.length > 0) {
+      onProgress?.("Removing excluded files...");
+      for (const target of config.delete_files) {
+        await rm(join5(sessionDir, target), { recursive: true, force: true });
+      }
+    }
     onProgress?.("Preparing workspace...");
     await rm(join5(sessionDir, ".git"), { recursive: true, force: true });
-    execSync('git init && git add -A && git commit -m "initial"', {
-      cwd: sessionDir,
-      stdio: "ignore"
-    });
+    execSync(
+      'git init && git add -A && git -c user.name=vibe -c user.email=vibe@local commit -m "initial"',
+      { cwd: sessionDir, stdio: "ignore" }
+    );
     await rm(join5(sessionDir, "scenario.yaml"), { force: true });
     await writeFile3(join5(sessionDir, "BRIEFING.md"), `# Interview Briefing
 
@@ -566,13 +625,15 @@ ${config.briefing}`);
     const systemPromptPath = join5(promptDir, `${id}.md`);
     await writeFile3(systemPromptPath, generateSystemPrompt(config));
     session.systemPromptPath = systemPromptPath;
-    session.status = "setting-up";
-    for (const cmd of config.setup) {
-      onProgress?.(`Running: ${cmd}`);
-      try {
-        execSync(cmd, { cwd: sessionDir, stdio: "pipe", timeout: 3e5 });
-      } catch (err) {
-        throw new SetupError(cmd, err instanceof Error ? err.message : String(err));
+    if (!options?.skipSetup) {
+      session.status = "setting-up";
+      for (const cmd of config.setup) {
+        onProgress?.(`Running: ${cmd}`);
+        try {
+          execSync(cmd, { cwd: sessionDir, stdio: "pipe", timeout: 3e5 });
+        } catch (err) {
+          throw new SetupError(cmd, err instanceof Error ? err.message : String(err));
+        }
       }
     }
     session.status = "running";
@@ -614,7 +675,9 @@ export {
   AIToolNotFoundError,
   ClaudeCodeLauncher,
   GitCloneError,
+  InvalidSessionCodeError,
   ScenarioConfigSchema,
+  ScenarioFetchError,
   ScenarioNotFoundError,
   ScenarioValidationError,
   SessionManager,
@@ -622,14 +685,18 @@ export {
   SessionRecorder,
   SetupError,
   VibeError,
+  decodeSessionCode,
   deleteSession,
   detectInstalledTools,
   discoverAllScenarios,
   discoverBuiltInScenarios,
+  encodeSessionCode,
   generateSystemPrompt,
   getAllLaunchers,
   getLauncher,
   importRepo,
+  isCloudSessionCode,
+  isUrl,
   listActiveSessions,
   listSessions,
   loadScenarioConfig,