@flashlearnai/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,1840 @@
+#!/usr/bin/env node
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+
+// packages/cli/src/paths.ts
+import { join, resolve } from "node:path";
+function projectRoot(input) {
+  return resolve(input);
+}
+function flashlearnRoot(input) {
+  return join(projectRoot(input), ".flashlearn");
+}
+var init_paths = __esm({
+  "packages/cli/src/paths.ts"() {
+    "use strict";
+  }
+});
+
+// packages/cli/src/yaml.ts
+function toYaml(value, indent = 0) {
+  const space = " ".repeat(indent);
+  if (Array.isArray(value)) {
+    if (!value.length) return `${space}[]`;
+    return value.map((item) => {
+      if (isScalar(item)) return `${space}- ${yamlScalar(item)}`;
+      const nested = toYaml(item, indent + 2).split("\n");
+      return `${space}-${nested.map((line, index) => index === 0 ? ` ${line.trimStart()}` : `
+${line}`).join("")}`;
+    }).join("\n");
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value);
+    if (!entries.length) return `${space}{}`;
+    return entries.map(([key, item]) => isScalar(item) ? `${space}${key}: ${yamlScalar(item)}` : `${space}${key}:
+${toYaml(item, indent + 2)}`).join("\n");
+  }
+  return `${space}${yamlScalar(value)}`;
+}
+function isScalar(value) {
+  return value === null || typeof value !== "object";
+}
+function yamlScalar(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === void 0) return "null";
+  return String(value);
+}
+var init_yaml = __esm({
+  "packages/cli/src/yaml.ts"() {
+    "use strict";
+  }
+});
+
+// packages/cli/src/cli.ts
+import { isAbsolute, resolve as resolve2, sep } from "node:path";
+async function runCli(args2, service2, io) {
+  try {
+    const parsed = parseProjectFlag(args2);
+    args2 = parsed.args;
+    const project = resolve2(io.cwd, parsed.directory ?? ".");
+    const help = helpFor(args2);
+    if (help) {
+      io.stdout(help);
+      return 0;
+    }
+    if (args2[0] === "--version" || args2[0] === "-v") {
+      if (args2.length !== 1) throw new UsageError("--version does not accept arguments");
+      io.stdout(CLI_VERSION);
+      return 0;
+    }
+    const [command, ...commandArgs] = args2;
+    if (command === "project") {
+      const [subcommand, ...subcommandArgs] = commandArgs;
+      if (subcommand === "set") {
+        throw new UsageError("project set was removed. Use --project <directory> on each command; the default is the working directory.");
+      }
+      if (subcommand === "show" || subcommand === "status") {
+        const { positional, format } = parseQuery(subcommandArgs);
+        if (positional.length) throw new UsageError(`project ${subcommand} does not accept arguments`);
+        io.stderr(`Project: ${project}`);
+        if (subcommand === "show") {
+          await service2.resolveProject(project);
+          io.stdout(formatValue({ project }, format, ({ project: path }) => path));
+        } else {
+          const status = await service2.status(project);
+          io.stdout(formatValue(status, format, formatStatus));
+        }
+        return 0;
+      }
+      throw new UsageError(`Unknown project command: ${subcommand ?? "(missing)"}`);
+    }
+    if (command === "question") {
+      const [subcommand, ...subcommandArgs] = commandArgs;
+      const { positional, format } = parseQuery(subcommandArgs);
+      if (subcommand === "get") {
+        if (positional.length !== 1) throw new UsageError("question get requires one card ID");
+        io.stderr(`Project: ${project}`);
+        const card = await service2.getCard(positional[0], project);
+        if (!card) throw new Error(`Card not found: ${positional[0]}`);
+        io.stdout(formatValue(card, format, formatCard));
+      } else if (subcommand === "list") {
+        if (positional.length) throw new UsageError("question list does not accept arguments");
+        io.stderr(`Project: ${project}`);
+        const cards = await service2.listCards(project);
+        io.stdout(formatValue(cards, format, formatCardList));
+      } else {
+        throw new UsageError(`Unknown question command: ${subcommand ?? "(missing)"}`);
+      }
+      return 0;
+    }
+    if (command === "init" || command === "generate") {
+      const { directory: directoryArgument, options } = command === "generate" ? parseGenerate(commandArgs) : { directory: parseDirectoryOnly(commandArgs), options: void 0 };
+      const directory = workflowDirectory(directoryArgument, parsed.directory, io.cwd);
+      io.stderr(`Project: ${directory}`);
+      if (command === "init") {
+        await service2.initialize(directory);
+        io.stdout(`Initialized ${flashlearnRoot(directory)}`);
+        io.stdout("");
+        io.stdout("Next:");
+        io.stdout("  # Generate study cards from this repository");
+        io.stdout(`  flashlearn generate --project ${quoteArgument(directory)}`);
+      } else {
+        if (!await generateForStudy(service2, io, directory, options)) return 1;
+        io.stdout("");
+        io.stdout("Next:");
+        io.stdout("  # Start the local learning experience");
+        io.stdout(`  flashlearn start --project ${quoteArgument(directory)}`);
+      }
+      return 0;
+    }
+    if (command === "start") {
+      const { directory: directoryArgument, options, yes } = parseStart(commandArgs);
+      const directory = workflowDirectory(directoryArgument, parsed.directory, io.cwd);
+      io.stderr(`Project: ${directory}`);
+      if (!(await service2.listCards(directory)).length) {
+        const generateCommand = `flashlearn generate --project ${quoteArgument(directory)}`;
+        io.stderr(`No study cards found in ${flashlearnRoot(directory)}.`);
+        const approved = yes || await io.confirm?.(`Run ${generateCommand} first? This initializes storage and may use the configured AI endpoint. [y/N] `);
+        if (!approved) {
+          io.stderr(`Required first step:
+  ${generateCommand}
+Then:
+  flashlearn start --project ${quoteArgument(directory)}
+Or approve empty-deck generation with start --yes.`);
+          return 1;
+        }
+        if (!await generateForStudy(service2, io, directory)) return 1;
+      }
+      await service2.start(directory, options);
+      const url = `http://${options.host ?? "localhost"}:${options.port ?? 4173}`;
+      io.stdout(`FlashLearn running at ${url}`);
+      io.stdout("");
+      io.stdout("Next:");
+      io.stdout("  # Open this URL in your browser to begin reviewing");
+      io.stdout(`  ${url}`);
+      return 0;
+    }
+    throw new UsageError(`Unknown command: ${command}`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    io.stderr(`Error: ${message}`);
+    if (error instanceof UsageError) {
+      io.stderr("Run `flashlearn --help` for usage.");
+      return 2;
+    }
+    return 1;
+  }
+}
+async function generateForStudy(service2, io, directory, options) {
+  io.stderr("Generating study cards (may use the configured AI endpoint)...");
+  const cards = await service2.generate(directory, options);
+  io.stdout(`Generated and stored ${cards.length} card${cards.length === 1 ? "" : "s"} (new or updated).`);
+  const available = (await service2.listCards(directory)).length;
+  if (!available) {
+    io.stderr("No study cards are available. Add supported source/docs or check extraction configuration, then run generate again.");
+    return false;
+  }
+  io.stdout(`Study deck: ${available} card${available === 1 ? "" : "s"} available.`);
+  return true;
+}
+function workflowDirectory(positional, flag, cwd) {
+  if (positional !== void 0 && flag !== void 0) throw new UsageError("Use either a positional directory or --project, not both");
+  return resolve2(cwd, flag ?? positional ?? ".");
+}
+function parseProjectFlag(args2) {
+  const rest = [];
+  let directory;
+  for (let index = 0; index < args2.length; index += 1) {
+    const arg = args2[index];
+    if (arg === "--project" || arg === "-p" || arg.startsWith("--project=")) {
+      if (directory !== void 0) throw new UsageError("Specify --project only once");
+      directory = arg.startsWith("--project=") ? arg.slice("--project=".length) : requireValue(args2, ++index, arg);
+      if (!directory.trim()) throw new UsageError("--project requires a directory");
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { args: rest, directory };
+}
+function helpFor(args2) {
+  if (args2.length === 0 || args2[0] === "--help" || args2[0] === "-h") return HELP;
+  const helpArgs = args2[0] === "help" ? args2.slice(1) : args2;
+  if (args2[0] === "help" && helpArgs.length === 0) return HELP;
+  const command = helpArgs[0];
+  if (!command) return null;
+  const subcommand = helpArgs[1];
+  const requested = args2[0] === "help" || helpArgs.includes("--help") || helpArgs.includes("-h");
+  const bareGroup = (command === "project" || command === "question") && helpArgs.length === 1;
+  if (!requested && !bareGroup) return null;
+  const key = subcommand && subcommand !== "--help" && subcommand !== "-h" ? `${command} ${subcommand}` : command;
+  const help = COMMAND_HELP[key] ?? COMMAND_HELP[command];
+  return help ? `${help}
+
+Project option:
+  -p, --project <directory>  Project directory (default: working directory)` : HELP;
+}
+function parseQuery(args2) {
+  const positional = [];
+  let format = "text";
+  for (let index = 0; index < args2.length; index += 1) {
+    const argument = args2[index];
+    if (argument === "-o" || argument === "--output") {
+      const value = requireValue(args2, ++index, argument);
+      if (value !== "text" && value !== "json" && value !== "yaml") {
+        throw new UsageError("--output must be text, json, or yaml");
+      }
+      format = value;
+    } else if (argument?.startsWith("-")) {
+      throw new UsageError(`Unknown option: ${argument}`);
+    } else if (argument) {
+      positional.push(argument);
+    }
+  }
+  return { positional, format };
+}
+function formatValue(value, format, text) {
+  if (format === "json") return JSON.stringify(value, null, 2);
+  if (format === "yaml") return toYaml(value);
+  return text(value);
+}
+function formatCard(card) {
+  const tags = card.tags?.length ? `
+Tags: ${card.tags.join(", ")}` : "";
+  return `ID: ${card.id}
+Question: ${card.question}
+Answer: ${card.answer}
+Source: ${card.source.path} @ ${card.source.sha}${tags}`;
+}
+function formatCardList(cards) {
+  return cards.length ? cards.map(({ id, question }) => `${id}	${question}`).join("\n") : "No cards found.";
+}
+function formatStatus(status) {
+  return `Project: ${status.project}
+Cards: ${status.cards}
+Reviewed: ${status.reviewed}
+Unreviewed: ${status.unreviewed}
+Due: ${status.due}`;
+}
+function quoteArgument(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function parseDirectoryOnly(args2) {
+  if (args2.some((arg) => arg.startsWith("-"))) throw new UsageError(`Unknown option: ${args2.find((arg) => arg.startsWith("-"))}`);
+  if (args2.length > 1) throw new UsageError("Expected at most one directory");
+  return args2[0];
+}
+function parseGenerate(args2) {
+  const positional = [];
+  const options = {};
+  for (let index = 0; index < args2.length; index += 1) {
+    const arg = args2[index];
+    if (arg === "--subpath") {
+      if (options.subpath !== void 0) throw new UsageError("Specify --subpath only once");
+      options.subpath = requireValue(args2, ++index, arg);
+      if (!options.subpath.trim()) throw new UsageError("--subpath requires a path");
+      if (isAbsolute(options.subpath) || options.subpath.split(sep).includes("..")) {
+        throw new UsageError("--subpath must be a repository-relative directory without '..'");
+      }
+    } else if (arg === "--max-files") {
+      if (options.maxFiles !== void 0) throw new UsageError("Specify --max-files only once");
+      const value = requireValue(args2, ++index, arg);
+      options.maxFiles = Number(value);
+      if (!/^\d+$/.test(value) || !Number.isSafeInteger(options.maxFiles) || options.maxFiles < 1) {
+        throw new UsageError("--max-files must be a positive integer");
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { directory: parseDirectoryOnly(positional), options };
+}
+function parseStart(args2) {
+  let directory;
+  let yes = false;
+  let host;
+  let port;
+  for (let index = 0; index < args2.length; index += 1) {
+    const argument = args2[index];
+    if (argument === "--yes" || argument === "-y") {
+      yes = true;
+    } else if (argument === "--host") {
+      host = requireValue(args2, ++index, "--host");
+      if (!host.trim()) throw new UsageError("--host cannot be empty");
+      if (host === "0.0.0.0" || host === "::") throw new UsageError("--host must not use a wildcard address");
+    } else if (argument === "--port") {
+      const value = requireValue(args2, ++index, "--port");
+      port = Number(value);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) throw new UsageError("--port must be an integer from 1 to 65535");
+    } else if (argument?.startsWith("-")) {
+      throw new UsageError(`Unknown option: ${argument}`);
+    } else if (argument) {
+      if (directory) throw new UsageError("Expected at most one directory");
+      directory = argument;
+    }
+  }
+  return { directory, options: { host, port }, yes };
+}
+function requireValue(args2, index, option) {
+  const value = args2[index];
+  if (!value || value.startsWith("-")) throw new UsageError(`${option} requires a value`);
+  return value;
+}
+var CLI_VERSION, HELP, COMMAND_HELP, UsageError;
+var init_cli = __esm({
+  "packages/cli/src/cli.ts"() {
+    "use strict";
+    init_paths();
+    init_yaml();
+    CLI_VERSION = "0.0.0";
+    HELP = `Usage: flashlearn <command> [directory] [options]
+
+Commands:
+  init [directory]       Create empty storage (optional)
+  generate [directory]   Initialize storage and generate cards
+  start [directory]      Start the local learning server
+  project show            Show this invocation's project directory
+  project status          Show project learning status
+  question list           List generated questions
+  question get <card-id>  Get one question and answer
+
+Start options:
+  --host <host>           Host to bind (default: localhost)
+  --port <port>           Port to bind (default: 4173)
+  -y, --yes               Generate cards for an empty deck without prompting
+
+Generate options:
+  --subpath <path>        Scan a repository-relative directory
+  --max-files <number>    Scan at most this many supported files
+
+Query options:
+  -o, --output <format>   Output as text, json, or yaml (default: text)
+
+General options:
+  -p, --project <directory>  Project directory (default: working directory)
+  -h, --help              Show help
+  -v, --version           Show version`;
+    COMMAND_HELP = {
+      init: `Usage: flashlearn init [directory] [options]
+
+Optional: create empty .flashlearn storage. Generate performs this step automatically.`,
+      generate: `Usage: flashlearn generate [directory] [options]
+
+Initialize missing storage and generate questions. No separate init is needed.
+
+Options:
+  --subpath <path>      Scan a repository-relative directory
+  --max-files <number>  Positive integer limit on scanned supported files`,
+      start: `Usage: flashlearn start [directory] [options]
+
+Start the local learning server. Offer generation if the deck is empty.
+
+Options:
+  --host <host>  Host to bind (default: localhost)
+  --port <port>  Port to bind (default: 4173)
+  -y, --yes     Approve empty-deck generation (may use the configured AI endpoint)`,
+      project: `Usage: flashlearn project <command> [options]
+
+Commands:
+  show    Show this invocation's project directory
+  status  Show project learning status
+
+Options:
+  -o, --output <format>  text, json, or yaml`,
+      "project show": `Usage: flashlearn project show [options]
+
+Show this invocation's project directory.
+
+Options:
+  -o, --output <format>  text, json, or yaml`,
+      "project status": `Usage: flashlearn project status [options]
+
+Show card and review counts for this invocation's project.
+
+Options:
+  -o, --output <format>  text, json, or yaml`,
+      question: `Usage: flashlearn question <command> [options]
+
+Commands:
+  list           List generated questions
+  get <card-id>  Get one question, answer, and source
+
+Options:
+  -o, --output <format>  text, json, or yaml`,
+      "question list": `Usage: flashlearn question list [options]
+
+List questions from this invocation's project.
+
+Options:
+  -o, --output <format>  text, json, or yaml`,
+      "question get": `Usage: flashlearn question get <card-id> [options]
+
+Get one question, answer, and source from this invocation's project.
+
+Options:
+  -o, --output <format>  text, json, or yaml`
+    };
+    UsageError = class extends Error {
+    };
+  }
+});
+
+// packages/extraction/dist/extractor.js
+import { execFile } from "node:child_process";
+import { open, readdir } from "node:fs/promises";
+import { extname, join as join2, relative, sep as sep2 } from "node:path";
+import { promisify } from "node:util";
+function isGoTestPath(path) {
+  return /_test\.go$/i.test(path);
+}
+function isGeneratedPath(path) {
+  return GENERATED_NAME.test(path) || CHANGELOG_NAME.test(path);
+}
+function isGeneratedContent(head) {
+  return GENERATED_MARKER.test(head);
+}
+async function sniff(path) {
+  const handle = await open(path, "r");
+  try {
+    const buffer = Buffer.alloc(SNIFF_BYTES);
+    const { bytesRead } = await handle.read(buffer, 0, SNIFF_BYTES, 0);
+    return buffer.subarray(0, bytesRead).toString("utf8");
+  } finally {
+    await handle.close();
+  }
+}
+async function isSkipped(path) {
+  if (isGoTestPath(path) || isGeneratedPath(path))
+    return true;
+  if (extname(path).toLowerCase() !== ".go")
+    return false;
+  try {
+    return isGeneratedContent(await sniff(path));
+  } catch {
+    return false;
+  }
+}
+async function sourceFiles(root, directory = root) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const paths = await Promise.all(entries.map(async (entry) => {
+    const path = join2(directory, entry.name);
+    if (entry.isDirectory())
+      return IGNORED_DIRECTORIES.has(entry.name) ? [] : sourceFiles(root, path);
+    if (!entry.isFile() || !SOURCE_EXTENSIONS.has(extname(entry.name)))
+      return [];
+    return await isSkipped(path) ? [] : [path];
+  }));
+  return paths.flat();
+}
+function toRepositoryPath(root, absolutePath) {
+  return relative(root, absolutePath).split(sep2).join("/");
+}
+async function headSha(root) {
+  try {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: root });
+    return stdout.trim();
+  } catch {
+    return "unknown";
+  }
+}
+async function fileSha(root, repositoryPath, fallback) {
+  try {
+    const { stdout } = await execFileAsync("git", ["rev-parse", `HEAD:${repositoryPath}`], { cwd: root });
+    const sha = stdout.trim();
+    return sha.length > 0 ? sha : fallback;
+  } catch {
+    return fallback;
+  }
+}
+var execFileAsync, SOURCE_EXTENSIONS, IGNORED_DIRECTORIES, GENERATED_NAME, CHANGELOG_NAME, GENERATED_MARKER, SNIFF_BYTES;
+var init_extractor = __esm({
+  "packages/extraction/dist/extractor.js"() {
+    "use strict";
+    execFileAsync = promisify(execFile);
+    SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".go", ".js", ".jsx", ".md", ".ts", ".tsx"]);
+    IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
+      ".git",
+      ".flashlearn",
+      "_output",
+      "build",
+      "coverage",
+      "dist",
+      "node_modules",
+      "testdata",
+      "third_party",
+      "vendor"
+    ]);
+    GENERATED_NAME = /(^|[./_-])(zz_generated|bindata)|\.pb\.go$|_generated\.go$|(^|\/)generated\.go$/i;
+    CHANGELOG_NAME = /(^|\/)changelog[^/]*\.md$/i;
+    GENERATED_MARKER = /^\/\/ Code generated .* DO NOT EDIT\.$/m;
+    SNIFF_BYTES = 2048;
+  }
+});
+
+// packages/extraction/dist/extractors.js
+function isMetaDocument(path) {
+  const lower = path.toLowerCase();
+  if (META_DIRECTORIES.some((directory) => `/${lower}`.includes(directory)))
+    return true;
+  const name = lower.split("/").pop() ?? "";
+  return META_DOCUMENTS.has(name) || name.startsWith("claude") || name.startsWith("pull_request_template") || name.startsWith("issue_template");
+}
+function clamp(text) {
+  if (text.length <= MAX_ANSWER_LENGTH)
+    return text;
+  const window = text.slice(0, MAX_ANSWER_LENGTH);
+  const sentenceEnd = Math.max(window.lastIndexOf(". "), window.lastIndexOf("! "), window.lastIndexOf("? "));
+  if (sentenceEnd > MAX_ANSWER_LENGTH * 0.5)
+    return window.slice(0, sentenceEnd + 1);
+  const wordEnd = window.lastIndexOf(" ");
+  return `${(wordEnd > 0 ? window.slice(0, wordEnd) : window).trimEnd()}\u2026`;
+}
+function normalizeAnswer(text) {
+  return clamp(text.replace(/\s+/g, " ").trim());
+}
+function joinBody(lines) {
+  const parts = [];
+  for (const line of lines) {
+    const isItem = /^\s*(?:[-*+]|\d+\.)\s+/.test(line);
+    if (isItem || parts.length === 0) {
+      parts.push(line.trim());
+    } else if (/^\s*(?:[-*+]|\d+\.)\s+/.test(parts[parts.length - 1] ?? "")) {
+      parts.push(line.trim());
+    } else {
+      parts[parts.length - 1] = `${parts[parts.length - 1]} ${line.trim()}`;
+    }
+  }
+  return clamp(parts.map((part) => part.replace(/\s+/g, " ").trim()).join("\n"));
+}
+function plainHeading(text) {
+  return text.replace(/\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/[*_`#]/g, "").trim();
+}
+function isGoSource(path) {
+  const lower = path.toLowerCase();
+  return lower.endsWith(".go") && !lower.endsWith("_test.go");
+}
+function goDeclaration(line) {
+  const match = /^(func|type|const|var)\s+([A-Z][\w]*)/.exec(line);
+  if (!match?.[1] || !match[2])
+    return null;
+  return { kind: match[1], name: match[2] };
+}
+function goSubject(declaration) {
+  return declaration.kind === "func" ? `${declaration.name}()` : declaration.name;
+}
+var MAX_ANSWER_LENGTH, META_DOCUMENTS, META_DIRECTORIES, MarkdownExtractor, JsDocExtractor, GoDocExtractor, ExportSignatureExtractor, CompositeExtractor;
+var init_extractors = __esm({
+  "packages/extraction/dist/extractors.js"() {
+    "use strict";
+    MAX_ANSWER_LENGTH = 700;
+    META_DOCUMENTS = /* @__PURE__ */ new Set([
+      "agents.md",
+      "changelog.md",
+      "code_of_conduct.md",
+      "contributing.md",
+      "license.md",
+      "security.md"
+    ]);
+    META_DIRECTORIES = ["/.github/", "/docs/devel/"];
+    MarkdownExtractor = class {
+      async extract(input) {
+        if (!input.path.toLowerCase().endsWith(".md"))
+          return [];
+        if (isMetaDocument(input.path))
+          return [];
+        const cards = [];
+        const lines = input.content.split(/\r?\n/);
+        let heading = null;
+        let body = [];
+        let inFence = false;
+        const flush = () => {
+          const answer = joinBody(body);
+          if (heading && answer.length > 0) {
+            cards.push({
+              question: `What does "${heading}" cover?`,
+              answer,
+              source: { path: input.path, sha: input.sha }
+            });
+          }
+          body = [];
+        };
+        for (const line of lines) {
+          if (/^\s*```/.test(line)) {
+            inFence = !inFence;
+            continue;
+          }
+          if (inFence)
+            continue;
+          const match = /^(#{1,6})\s+(.*\S)\s*$/.exec(line);
+          if (match?.[2]) {
+            flush();
+            heading = plainHeading(match[2]);
+            continue;
+          }
+          if (heading && line.trim().length > 0 && !/^\s*\|/.test(line)) {
+            body.push(line.trim());
+          }
+        }
+        flush();
+        return cards;
+      }
+    };
+    JsDocExtractor = class {
+      async extract(input) {
+        if (!/\.(ts|tsx|js|jsx)$/i.test(input.path))
+          return [];
+        const cards = [];
+        const pattern = /\/\*\*([\s\S]*?)\*\/\s*export\s+(?:default\s+)?(?:abstract\s+)?(?:async\s+)?(function|class|const|let|interface|type|enum)\s+([A-Za-z_$][\w$]*)/g;
+        for (const match of input.content.matchAll(pattern)) {
+          const [, rawDoc, kind, name] = match;
+          if (!rawDoc || !kind || !name)
+            continue;
+          const summary = rawDoc.split(/\r?\n/).map((line) => line.replace(/^\s*\*+/, "").trim()).filter((line) => line.length > 0 && !line.startsWith("@")).join(" ");
+          const answer = normalizeAnswer(summary);
+          if (answer.length === 0)
+            continue;
+          const subject = kind === "function" ? `${name}()` : name;
+          cards.push({
+            question: `What does \`${subject}\` do?`,
+            answer,
+            source: { path: input.path, sha: input.sha }
+          });
+        }
+        return cards;
+      }
+    };
+    GoDocExtractor = class {
+      async extract(input) {
+        if (!isGoSource(input.path))
+          return [];
+        const cards = [];
+        const lines = input.content.split(/\r?\n/);
+        let comment = [];
+        for (const line of lines) {
+          const commentMatch = /^\s*\/\/\s?(.*)$/.exec(line);
+          if (commentMatch) {
+            comment.push((commentMatch[1] ?? "").trim());
+            continue;
+          }
+          const declaration = goDeclaration(line);
+          if (declaration && comment.length > 0) {
+            const answer = normalizeAnswer(comment.join(" "));
+            if (answer.length > 0) {
+              cards.push({
+                question: `What does \`${goSubject(declaration)}\` do?`,
+                answer,
+                source: { path: input.path, sha: input.sha }
+              });
+            }
+          }
+          comment = [];
+        }
+        return cards;
+      }
+    };
+    ExportSignatureExtractor = class {
+      async extract(input) {
+        if (isGoSource(input.path))
+          return this.extractGo(input);
+        if (!/\.(ts|tsx|js|jsx)$/i.test(input.path))
+          return [];
+        const documented = /* @__PURE__ */ new Set();
+        const documentedPattern = /\/\*\*[\s\S]*?\*\/\s*export\s+(?:default\s+)?(?:abstract\s+)?(?:async\s+)?(?:function|class|const|let|interface|type|enum)\s+([A-Za-z_$][\w$]*)/g;
+        for (const match of input.content.matchAll(documentedPattern)) {
+          if (match[1])
+            documented.add(match[1]);
+        }
+        const cards = [];
+        const pattern = /^export\s+(?:default\s+)?(?:abstract\s+)?(?:async\s+)?(function|class|interface|type|enum)\s+([A-Za-z_$][\w$]*)/gm;
+        for (const match of input.content.matchAll(pattern)) {
+          const [, kind, name] = match;
+          if (!kind || !name || documented.has(name))
+            continue;
+          cards.push({
+            question: `Which file defines the \`${name}\` ${kind}?`,
+            answer: `\`${name}\` is an exported ${kind} defined in \`${input.path}\`.`,
+            source: { path: input.path, sha: input.sha }
+          });
+        }
+        return cards;
+      }
+      /** Exported Go declarations with no preceding doc comment become locator cards. */
+      async extractGo(input) {
+        const cards = [];
+        const lines = input.content.split(/\r?\n/);
+        let documented = false;
+        for (const line of lines) {
+          if (/^\s*\/\//.test(line)) {
+            documented = true;
+            continue;
+          }
+          const declaration = goDeclaration(line);
+          if (declaration && !documented) {
+            cards.push({
+              question: `Which file defines the \`${declaration.name}\` ${declaration.kind}?`,
+              answer: `\`${declaration.name}\` is an exported ${declaration.kind} defined in \`${input.path}\`.`,
+              source: { path: input.path, sha: input.sha }
+            });
+          }
+          documented = false;
+        }
+        return cards;
+      }
+    };
+    CompositeExtractor = class {
+      extractors;
+      constructor(...extractors) {
+        this.extractors = extractors;
+      }
+      async extract(input) {
+        const results = await Promise.all(this.extractors.map(async (extractor) => extractor.extract(input)));
+        return results.flat();
+      }
+    };
+  }
+});
+
+// packages/extraction/dist/endpoint.js
+function endpointConfigFromEnv(env = process.env) {
+  const url = env[ENDPOINT_ENV.url]?.trim();
+  const model = env[ENDPOINT_ENV.model]?.trim();
+  if (!url || !model)
+    return null;
+  const apiKey = env[ENDPOINT_ENV.apiKey]?.trim();
+  const authHeader = env[ENDPOINT_ENV.authHeader]?.trim();
+  return {
+    url,
+    model,
+    ...apiKey ? { apiKey } : {},
+    ...authHeader ? { authHeader } : {}
+  };
+}
+function buildPrompt(input, maxCards) {
+  const content = input.content.length > MAX_CONTENT_CHARS ? `${input.content.slice(0, MAX_CONTENT_CHARS)}
+\u2026 file truncated \u2026` : input.content;
+  return `File: ${input.path}
+Write at most ${maxCards} cards.
+
+${content}`;
+}
+function parseCards(reply) {
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(reply);
+  const candidate = fenced?.[1]?.trim() ?? reply.trim();
+  const start = candidate.indexOf("{");
+  const end = candidate.lastIndexOf("}");
+  if (start === -1 || end <= start)
+    return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(candidate.slice(start, end + 1));
+  } catch {
+    return [];
+  }
+  const cards = parsed.cards;
+  if (!Array.isArray(cards))
+    return [];
+  return cards.flatMap((entry) => {
+    if (typeof entry !== "object" || entry === null)
+      return [];
+    const { question, answer } = entry;
+    if (typeof question !== "string" || typeof answer !== "string")
+      return [];
+    if (question.trim().length === 0 || answer.trim().length === 0)
+      return [];
+    return [{ question: question.trim(), answer: answer.trim() }];
+  });
+}
+var CODE_EXTENSIONS, MAX_CONTENT_CHARS, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_CARDS, ENDPOINT_ENV, SYSTEM_PROMPT, EndpointExtractor;
+var init_endpoint = __esm({
+  "packages/extraction/dist/endpoint.js"() {
+    "use strict";
+    CODE_EXTENSIONS = /\.(go|js|jsx|ts|tsx)$/i;
+    MAX_CONTENT_CHARS = 24e3;
+    DEFAULT_TIMEOUT_MS = 3e4;
+    DEFAULT_MAX_CARDS = 5;
+    ENDPOINT_ENV = {
+      url: "FLASHLEARN_ENDPOINT_URL",
+      model: "FLASHLEARN_ENDPOINT_MODEL",
+      apiKey: "FLASHLEARN_ENDPOINT_API_KEY",
+      authHeader: "FLASHLEARN_ENDPOINT_AUTH_HEADER"
+    };
+    SYSTEM_PROMPT = [
+      "You write flashcards that help an engineer onboard to an unfamiliar codebase.",
+      "Given one source file, produce questions a newcomer would genuinely ask and answers grounded only in the file.",
+      "Prefer questions about behavior, control flow, and intent over restating names.",
+      "Never invent APIs, file paths, or behavior that is not present in the file.",
+      'Reply with JSON only: {"cards":[{"question":"...","answer":"..."}]}.',
+      "Return an empty cards array when the file has nothing worth asking about."
+    ].join(" ");
+    EndpointExtractor = class {
+      config;
+      fetchImpl;
+      constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+      }
+      async extract(input) {
+        if (!CODE_EXTENSIONS.test(input.path))
+          return [];
+        if (input.content.trim().length === 0)
+          return [];
+        const maxCards = this.config.maxCardsPerFile ?? DEFAULT_MAX_CARDS;
+        const reply = await this.requestReply(buildPrompt(input, maxCards));
+        if (reply === null)
+          return [];
+        return parseCards(reply).slice(0, maxCards).map((card) => ({
+          question: card.question,
+          answer: card.answer,
+          source: { path: input.path, sha: input.sha }
+        }));
+      }
+      /** Returns the assistant message, or null when the call fails for any reason. */
+      async requestReply(prompt) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        try {
+          const response = await this.fetchImpl(this.config.url, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({
+              model: this.config.model,
+              messages: [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: prompt }
+              ],
+              temperature: 0
+            }),
+            signal: controller.signal
+          });
+          if (!response.ok)
+            return null;
+          const payload = await response.json();
+          const content = payload.choices?.[0]?.message?.content;
+          return typeof content === "string" ? content : null;
+        } catch {
+          return null;
+        } finally {
+          clearTimeout(timeout);
+        }
+      }
+      headers() {
+        const headers = { "content-type": "application/json" };
+        if (!this.config.apiKey)
+          return headers;
+        const header = this.config.authHeader ?? "authorization";
+        headers[header] = header.toLowerCase() === "authorization" ? `Bearer ${this.config.apiKey}` : this.config.apiKey;
+        return headers;
+      }
+    };
+  }
+});
+
+// packages/extraction/dist/validator.js
+function contentWords(text) {
+  return text.replace(/[`*_]/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((word) => word.length > 1 && !STOP_WORDS.has(word)).map(stem);
+}
+function stem(word) {
+  for (const suffix of ["ements", "ement", "ations", "ation", "ings", "ing", "ers", "er", "es", "s"]) {
+    if (word.length > suffix.length + 2 && word.endsWith(suffix)) {
+      return word.slice(0, word.length - suffix.length);
+    }
+  }
+  return word;
+}
+function questionOverlap(question, answer) {
+  const answerWords = contentWords(answer);
+  if (answerWords.length === 0)
+    return 1;
+  const asked = new Set(contentWords(question));
+  const shared = answerWords.filter((word) => asked.has(word)).length;
+  return shared / answerWords.length;
+}
+function repairVagueQuestion(card) {
+  const askedAbout = QUESTION_SUBJECT.exec(card.question.trim());
+  if (!askedAbout)
+    return card;
+  const [, subject, call = ""] = askedAbout;
+  const answered = ANSWER_SUBJECT.exec(card.answer.trim());
+  if (!subject || !answered?.[1])
+    return card;
+  const fuller = answered[1];
+  const extendsSubject = fuller.length > subject.length && fuller.toLowerCase().endsWith(subject.toLowerCase());
+  if (!extendsSubject)
+    return card;
+  return { ...card, question: `What does \`${fuller}${call}\` do?` };
+}
+function validateCards(input) {
+  const kept = [];
+  const rejected = [];
+  const seenQuestions = /* @__PURE__ */ new Set();
+  for (const original of input) {
+    const card = repairVagueQuestion(original);
+    const reason = Object.values(CARD_RULES).reduce((found, rule) => found ?? rule(card), null);
+    if (reason) {
+      rejected.push({ card, reason });
+      continue;
+    }
+    const key = card.question.trim().toLowerCase().replace(/\s+/g, " ");
+    if (seenQuestions.has(key)) {
+      rejected.push({ card, reason: "duplicate question across files" });
+      continue;
+    }
+    seenQuestions.add(key);
+    kept.push(card);
+  }
+  return { cards: kept, rejected };
+}
+function rejectionSummary(rejected) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const entry of rejected)
+    counts.set(entry.reason, (counts.get(entry.reason) ?? 0) + 1);
+  return [...counts.entries()].map(([reason, cards]) => ({ reason, cards })).sort((left, right) => right.cards - left.cards || left.reason.localeCompare(right.reason));
+}
+var MIN_ANSWER_LENGTH, MAX_QUESTION_OVERLAP, LOCATOR_QUESTION, DANGLING_OPENER, STOP_WORDS, CARD_RULES, QUESTION_SUBJECT, ANSWER_SUBJECT;
+var init_validator = __esm({
+  "packages/extraction/dist/validator.js"() {
+    "use strict";
+    MIN_ANSWER_LENGTH = 25;
+    MAX_QUESTION_OVERLAP = 0.6;
+    LOCATOR_QUESTION = /^which file defines the /i;
+    DANGLING_OPENER = /^(this|it|its|these|those|that|they|the above|the below|the following|see above|see below|as described above|here|such)\b/i;
+    STOP_WORDS = /* @__PURE__ */ new Set([
+      "a",
+      "an",
+      "and",
+      "are",
+      "as",
+      "at",
+      "be",
+      "by",
+      "do",
+      "does",
+      "for",
+      "from",
+      "has",
+      "in",
+      "is",
+      "of",
+      "on",
+      "or",
+      "that",
+      "the",
+      "to",
+      "what",
+      "when",
+      "which",
+      "with"
+    ]);
+    CARD_RULES = {
+      locator: (card) => LOCATOR_QUESTION.test(card.question.trim()) ? "locator question" : null,
+      shortAnswer: (card) => card.answer.trim().length < MIN_ANSWER_LENGTH ? "answer too short to teach anything" : null,
+      restatement: (card) => questionOverlap(card.question, card.answer) > MAX_QUESTION_OVERLAP ? "answer restates the question" : null,
+      danglingContext: (card) => DANGLING_OPENER.test(card.answer.trim()) ? "answer depends on context the card omits" : null
+    };
+    QUESTION_SUBJECT = /^What does `([A-Za-z_][A-Za-z0-9_]*)(\(\))?` do\?$/;
+    ANSWER_SUBJECT = /^([A-Za-z_][A-Za-z0-9_]*)\b/;
+  }
+});
+
+// packages/extraction/dist/workstream.js
+import { readFile } from "node:fs/promises";
+import { join as join3, sep as sep3 } from "node:path";
+function deterministicExtractor() {
+  return new CompositeExtractor(new JsDocExtractor(), new GoDocExtractor(), new ExportSignatureExtractor(), new MarkdownExtractor());
+}
+function defaultExtractor() {
+  const config = endpointConfigFromEnv();
+  if (!config)
+    return deterministicExtractor();
+  return new CompositeExtractor(new EndpointExtractor(config), new MarkdownExtractor());
+}
+function normalizeSubpath(subpath) {
+  const cleaned = subpath.split(sep3).join("/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, "");
+  if (cleaned.length === 0)
+    return "";
+  if (cleaned === ".." || cleaned.startsWith("../") || cleaned.includes("/../")) {
+    throw new Error(`Subpath must stay inside the repository: ${subpath}`);
+  }
+  return cleaned;
+}
+function usableCards(cards) {
+  const seen = /* @__PURE__ */ new Set();
+  return cards.filter((card) => {
+    if (card.question.trim().length === 0 || card.answer.trim().length === 0)
+      return false;
+    const key = `${card.source.path}::${card.question.trim()}`;
+    if (seen.has(key))
+      return false;
+    seen.add(key);
+    return true;
+  });
+}
+async function mapWithConcurrency(items, limit, task) {
+  const results = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      const item = items[index];
+      if (item !== void 0)
+        results[index] = await task(item);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+async function generateCards(root, extractor = defaultExtractor(), options = {}) {
+  return new ExtractionService(extractor).generateFromRepository(root, options);
+}
+var DEFAULT_CONCURRENCY, ExtractionService;
+var init_workstream = __esm({
+  "packages/extraction/dist/workstream.js"() {
+    "use strict";
+    init_extractor();
+    init_extractors();
+    init_endpoint();
+    init_validator();
+    DEFAULT_CONCURRENCY = 8;
+    ExtractionService = class {
+      extractor;
+      concurrency;
+      constructor(extractor = defaultExtractor(), concurrency = DEFAULT_CONCURRENCY) {
+        this.extractor = extractor;
+        this.concurrency = concurrency;
+      }
+      /**
+       * Scans the repository, optionally restricted to a subpath. The root stays
+       * the repository root even when scoped, so Git attribution keeps resolving
+       * and `source.path` remains repository-relative.
+       */
+      async scanRepository(root, options = {}) {
+        const commitSha = await headSha(root);
+        const subpath = options.subpath ? normalizeSubpath(options.subpath) : "";
+        let files = await sourceFiles(root, subpath ? join3(root, subpath) : root);
+        files.sort((left, right) => left.localeCompare(right));
+        if (options.maxFiles !== void 0)
+          files = files.slice(0, Math.max(0, options.maxFiles));
+        const documents = await Promise.all(files.map(async (absolutePath) => {
+          const path = toRepositoryPath(root, absolutePath);
+          const [content, sha] = await Promise.all([
+            readFile(absolutePath, "utf8"),
+            fileSha(root, path, commitSha)
+          ]);
+          return { path, content, sha };
+        }));
+        return documents.sort((left, right) => left.path.localeCompare(right.path));
+      }
+      /**
+       * Generates cards for one document. Per-document validation cannot see
+       * repeats across files, so cross-file deduplication happens in
+       * `generateFromRepository`.
+       */
+      async generateFromDocument(document) {
+        const cards = await this.extractor.extract(document);
+        return validateCards(usableCards(cards)).cards;
+      }
+      async generateFromRepository(root, options = {}) {
+        return (await this.generateWithRejections(root, options)).cards;
+      }
+      /**
+       * Repository-wide generation that also reports what validation filtered.
+       * The corpus report uses this to show why a run shrank.
+       */
+      async generateWithRejections(root, options = {}) {
+        const documents = await this.scanRepository(root, options);
+        const generated = await mapWithConcurrency(documents, this.concurrency, async (document) => usableCards(await this.extractor.extract(document)));
+        return validateCards(generated.flat());
+      }
+    };
+  }
+});
+
+// packages/extraction/dist/report.js
+import { extname as extname2 } from "node:path";
+function median(sorted) {
+  if (sorted.length === 0)
+    return 0;
+  const middle = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 1)
+    return sorted[middle] ?? 0;
+  return Math.round(((sorted[middle - 1] ?? 0) + (sorted[middle] ?? 0)) / 2);
+}
+function summarizeCards(cards) {
+  const perFile = /* @__PURE__ */ new Map();
+  const perExtension = /* @__PURE__ */ new Map();
+  const questionCounts = /* @__PURE__ */ new Map();
+  const lengths = [];
+  for (const card of cards) {
+    const path = card.source.path;
+    perFile.set(path, (perFile.get(path) ?? 0) + 1);
+    const extension = extname2(path).toLowerCase() || "(none)";
+    const bucket = perExtension.get(extension) ?? { cards: 0, files: /* @__PURE__ */ new Set() };
+    bucket.cards += 1;
+    bucket.files.add(path);
+    perExtension.set(extension, bucket);
+    const key = `${path}::${card.question}`;
+    questionCounts.set(key, (questionCounts.get(key) ?? 0) + 1);
+    lengths.push(card.answer.length);
+  }
+  lengths.sort((a, b) => a - b);
+  const total = lengths.reduce((sum, length) => sum + length, 0);
+  return {
+    cards: cards.length,
+    files: perFile.size,
+    byExtension: [...perExtension.entries()].map(([extension, bucket]) => ({ extension, cards: bucket.cards, files: bucket.files.size })).sort((a, b) => b.cards - a.cards || a.extension.localeCompare(b.extension)),
+    topFiles: [...perFile.entries()].map(([path, count]) => ({ path, cards: count })).sort((a, b) => b.cards - a.cards || a.path.localeCompare(b.path)).slice(0, 10),
+    answerLength: {
+      min: lengths[0] ?? 0,
+      median: median(lengths),
+      max: lengths[lengths.length - 1] ?? 0,
+      mean: lengths.length > 0 ? Math.round(total / lengths.length) : 0
+    },
+    duplicateQuestions: [...questionCounts.values()].filter((count) => count > 1).length
+  };
+}
+function formatReport(report) {
+  const lines = [
+    `Cards: ${report.cards}`,
+    `Files with cards: ${report.files}`,
+    "",
+    "By extension:",
+    ...report.byExtension.map((row) => `  ${row.extension.padEnd(8)} ${String(row.cards).padStart(6)} cards  ${String(row.files).padStart(5)} files`),
+    "",
+    "Answer length:",
+    `  min ${report.answerLength.min}  median ${report.answerLength.median}  mean ${report.answerLength.mean}  max ${report.answerLength.max}`,
+    "",
+    "Top files:",
+    ...report.topFiles.map((row) => `  ${String(row.cards).padStart(4)}  ${row.path}`)
+  ];
+  if (report.duplicateQuestions > 0) {
+    lines.push("", `Duplicate questions within a file: ${report.duplicateQuestions}`);
+  }
+  return lines.join("\n");
+}
+var init_report = __esm({
+  "packages/extraction/dist/report.js"() {
+    "use strict";
+  }
+});
+
+// packages/extraction/dist/corpus.js
+async function reportOnRepository(root, options = {}) {
+  const { cards, rejected } = await new ExtractionService().generateWithRejections(root, options);
+  const lines = [formatReport(summarizeCards(cards))];
+  if (rejected.length > 0) {
+    lines.push("", `Filtered by validation: ${rejected.length}`);
+    for (const row of rejectionSummary(rejected)) {
+      lines.push(`  ${String(row.cards).padStart(6)}  ${row.reason}`);
+    }
+  }
+  return lines.join("\n");
+}
+var invokedDirectly;
+var init_corpus = __esm({
+  "packages/extraction/dist/corpus.js"() {
+    "use strict";
+    init_report();
+    init_validator();
+    init_workstream();
+    invokedDirectly = process.argv[1]?.endsWith("corpus.ts") || process.argv[1]?.endsWith("corpus.js");
+    if (invokedDirectly) {
+      const root = process.argv[2];
+      const subpath = process.argv[3];
+      if (!root) {
+        console.error("Usage: npm run report --workspace @flashlearn/extraction -- <repository> [subpath]");
+        process.exit(2);
+      }
+      reportOnRepository(root, subpath ? { subpath } : {}).then((output) => console.log(output), (error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+      });
+    }
+  }
+});
+
+// packages/extraction/dist/index.js
+var init_dist = __esm({
+  "packages/extraction/dist/index.js"() {
+    "use strict";
+    init_workstream();
+    init_endpoint();
+    init_report();
+    init_validator();
+    init_corpus();
+    init_extractor();
+    init_extractors();
+  }
+});
+
+// packages/frontend/dist/workstream.js
+var init_workstream2 = __esm({
+  "packages/frontend/dist/workstream.js"() {
+    "use strict";
+  }
+});
+
+// packages/frontend/dist/index.js
+import { createServer } from "node:http";
+import { readFile as readFile2, realpath } from "node:fs/promises";
+import { readFileSync, statSync } from "node:fs";
+import { extname as extname3, join as join4, normalize, sep as sep4 } from "node:path";
+import { fileURLToPath } from "node:url";
+function renderPage() {
+  const path = join4(CLIENT, "index.html");
+  try {
+    const { mtimeMs } = statSync(path);
+    if (shell?.mtimeMs !== mtimeMs)
+      shell = { mtimeMs, html: readFileSync(path, "utf8") };
+    return shell.html;
+  } catch {
+    return MISSING;
+  }
+}
+function json(response, status, value, body = true) {
+  response.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+  response.end(body ? JSON.stringify(value) : void 0);
+}
+async function readJson(request) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > MAX_BODY)
+      return void 0;
+    chunks.push(Buffer.from(chunk));
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function serveClient(response, pathname, body) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    decoded = pathname;
+  }
+  const relative2 = normalize(decoded).replace(/^([/\\]|\.\.)+/, "");
+  const extension = extname3(relative2);
+  if (relative2 && relative2 !== "index.html") {
+    const file = await readContained(relative2);
+    if (file) {
+      response.writeHead(200, { "content-type": TYPES[extension] ?? "application/octet-stream" });
+      return void response.end(body ? file : void 0);
+    }
+    if (extension)
+      return json(response, 404, { error: "Not found" }, body);
+  }
+  const html = renderPage();
+  response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+  response.end(body ? html : void 0);
+}
+async function readContained(relative2) {
+  try {
+    const target = await realpath(join4(CLIENT, relative2));
+    const root = await realpath(CLIENT);
+    if (target !== root && !target.startsWith(root + sep4))
+      return null;
+    return await readFile2(target);
+  } catch {
+    return null;
+  }
+}
+function createFlashLearnServer(services) {
+  return createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url ?? "/", "http://localhost");
+      const body = request.method !== "HEAD";
+      const method = request.method === "HEAD" ? "GET" : request.method;
+      if (method === "GET" && url.pathname === "/api/cards")
+        return json(response, 200, await services.listCards(), body);
+      if (method === "GET" && url.pathname === "/api/cards/next") {
+        const card = await services.nextCard();
+        if (!card)
+          return json(response, 404, { error: "No card is due" }, body);
+        const preview = { id: card.id, question: card.question, source: card.source };
+        return json(response, 200, preview, body);
+      }
+      const cardMatch = url.pathname.match(/^\/api\/cards\/([^/]+)$/);
+      if (method === "GET" && cardMatch?.[1]) {
+        const card = await services.getCard(decodeURIComponent(cardMatch[1]));
+        return card ? json(response, 200, card, body) : json(response, 404, { error: "Card not found" }, body);
+      }
+      if (method === "POST" && url.pathname === "/api/review") {
+        const input = await readJson(request);
+        const review = input;
+        const cardId = typeof review?.cardId === "string" ? review.cardId : null;
+        const result = RESULTS.find((value) => value === review?.result);
+        if (!cardId || !result)
+          return json(response, 400, { error: "Invalid review" }, body);
+        if (!await services.getCard(cardId))
+          return json(response, 404, { error: "Card not found" }, body);
+        return json(response, 200, await services.submitReview(cardId, result), body);
+      }
+      if (url.pathname === "/api" || url.pathname.startsWith("/api/"))
+        return json(response, 404, { error: "Not found" }, body);
+      if (method !== "GET")
+        return json(response, 405, { error: "Method not allowed" }, body);
+      return await serveClient(response, url.pathname, body);
+    } catch (error) {
+      return json(response, 500, { error: error instanceof Error ? error.message : "Unknown error" });
+    }
+  });
+}
+var CLIENT, TYPES, MISSING, shell, MAX_BODY, RESULTS;
+var init_dist2 = __esm({
+  "packages/frontend/dist/index.js"() {
+    "use strict";
+    init_workstream2();
+    CLIENT = fileURLToPath(new URL("../client/dist/", import.meta.url));
+    TYPES = {
+      ".css": "text/css; charset=utf-8",
+      ".html": "text/html; charset=utf-8",
+      ".js": "text/javascript; charset=utf-8",
+      ".json": "application/json",
+      ".png": "image/png",
+      ".svg": "image/svg+xml"
+    };
+    MISSING = `<!doctype html><meta charset="utf-8"><title>FlashLearn</title>
+<body style="font:16px system-ui;max-width:34rem;margin:14vh auto;padding:1rem;background:#f4f1e8;color:#17251d">
+<h1>Client not built</h1><p>Run <code>npm run build --workspace @flashlearn/frontend</code>, then reload.</p>`;
+    MAX_BODY = 64 * 1024;
+    RESULTS = ["easy", "hard", "correct", "incorrect"];
+  }
+});
+
+// packages/learning/dist/workstream.js
+function compareTimestamps(left, right) {
+  return new Date(left).getTime() - new Date(right).getTime();
+}
+var MINIMUM_EASE_FACTOR, INITIAL_EASE_FACTOR, LearningService;
+var init_workstream3 = __esm({
+  "packages/learning/dist/workstream.js"() {
+    "use strict";
+    MINIMUM_EASE_FACTOR = 1.3;
+    INITIAL_EASE_FACTOR = 2.5;
+    LearningService = class {
+      createReviewState(cardId) {
+        return {
+          cardId,
+          easeFactor: INITIAL_EASE_FACTOR,
+          intervalDays: 0,
+          reviewCount: 0,
+          correctCount: 0
+        };
+      }
+      scheduleReview(state, result, now = /* @__PURE__ */ new Date()) {
+        const successful = result !== "incorrect";
+        const multipliers = {
+          incorrect: 0,
+          hard: 1.2,
+          correct: state.correctCount === 0 ? 1 : state.easeFactor,
+          easy: state.correctCount === 0 ? 4 : state.easeFactor + 0.5
+        };
+        const intervalDays = successful ? Math.max(1, Math.round(Math.max(1, state.intervalDays) * multipliers[result])) : 0;
+        const easeDelta = result === "easy" ? 0.15 : result === "hard" ? -0.15 : result === "incorrect" ? -0.2 : 0;
+        const nextReview = new Date(now);
+        nextReview.setUTCDate(nextReview.getUTCDate() + intervalDays);
+        return {
+          ...state,
+          easeFactor: Math.max(MINIMUM_EASE_FACTOR, state.easeFactor + easeDelta),
+          intervalDays,
+          lastReviewed: now.toISOString(),
+          nextReview: nextReview.toISOString(),
+          reviewCount: state.reviewCount + 1,
+          correctCount: state.correctCount + (successful ? 1 : 0)
+        };
+      }
+      selectNextCard(cards, states, now = /* @__PURE__ */ new Date()) {
+        const byCard = new Map(states.map((state) => [state.cardId, state]));
+        return cards.filter((card) => {
+          const nextReview = byCard.get(card.id)?.nextReview;
+          return !nextReview || new Date(nextReview) <= now;
+        }).sort((left, right) => {
+          const leftDue = byCard.get(left.id)?.nextReview;
+          const rightDue = byCard.get(right.id)?.nextReview;
+          if (leftDue && rightDue) {
+            return compareTimestamps(leftDue, rightDue) || compareTimestamps(left.createdAt, right.createdAt);
+          }
+          if (leftDue)
+            return -1;
+          if (rightDue)
+            return 1;
+          return compareTimestamps(left.createdAt, right.createdAt);
+        })[0] ?? null;
+      }
+    };
+  }
+});
+
+// packages/learning/dist/index.js
+function scheduleReview(state, result, now = /* @__PURE__ */ new Date()) {
+  return learningService.scheduleReview(state, result, now);
+}
+function selectNextCard(cards, states, now = /* @__PURE__ */ new Date()) {
+  return learningService.selectNextCard(cards, states, now);
+}
+var learningService;
+var init_dist3 = __esm({
+  "packages/learning/dist/index.js"() {
+    "use strict";
+    init_workstream3();
+    init_workstream3();
+    learningService = new LearningService();
+  }
+});
+
+// packages/storage/dist/paths.js
+import { join as join5, resolve as resolve3 } from "node:path";
+function storeRoot(root) {
+  return join5(resolve3(root), ".flashlearn");
+}
+function cardsPath(root) {
+  return join5(storeRoot(root), "cards.json");
+}
+function reviewPath(root) {
+  return join5(storeRoot(root), "review.json");
+}
+function settingsPath(root) {
+  return join5(storeRoot(root), "settings.json");
+}
+var init_paths2 = __esm({
+  "packages/storage/dist/paths.js"() {
+    "use strict";
+  }
+});
+
+// packages/storage/dist/json.js
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile as readFile3, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+function serialize(path, task) {
+  const next = (chains.get(path) ?? Promise.resolve()).then(task, task);
+  chains.set(path, next.catch(() => {
+  }));
+  return next;
+}
+async function readJson2(path, fallback) {
+  let raw;
+  try {
+    raw = await readFile3(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return fallback;
+    throw error;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error(`Corrupt JSON in ${path}`);
+  }
+}
+function updateJson(path, mutate) {
+  return serialize(path, async () => {
+    const current = await readJson2(path, void 0);
+    await atomicWrite(path, mutate(current));
+  });
+}
+async function atomicWrite(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporaryPath = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}
+`);
+  await rename(temporaryPath, path);
+}
+var chains;
+var init_json = __esm({
+  "packages/storage/dist/json.js"() {
+    "use strict";
+    chains = /* @__PURE__ */ new Map();
+  }
+});
+
+// packages/storage/dist/validate.js
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isCard(value) {
+  if (!isRecord(value))
+    return false;
+  const source = value.source;
+  return typeof value.id === "string" && typeof value.question === "string" && typeof value.answer === "string" && typeof value.createdAt === "string" && typeof value.updatedAt === "string" && isRecord(source) && typeof source.path === "string" && typeof source.sha === "string" && (value.tags === void 0 || isStringArray(value.tags));
+}
+function isReviewState(value) {
+  if (!isRecord(value))
+    return false;
+  return typeof value.cardId === "string" && typeof value.easeFactor === "number" && typeof value.intervalDays === "number" && typeof value.reviewCount === "number" && typeof value.correctCount === "number" && (value.lastReviewed === void 0 || typeof value.lastReviewed === "string") && (value.nextReview === void 0 || typeof value.nextReview === "string");
+}
+function isSafeKey(key) {
+  return key !== "__proto__" && key !== "constructor" && key !== "prototype";
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+var init_validate = __esm({
+  "packages/storage/dist/validate.js"() {
+    "use strict";
+  }
+});
+
+// packages/storage/dist/repositories.js
+function parseCards2(value) {
+  return Array.isArray(value) ? value.filter(isCard) : [];
+}
+function parseStates(value) {
+  const states = /* @__PURE__ */ Object.create(null);
+  if (typeof value === "object" && value !== null) {
+    for (const [key, state] of Object.entries(value)) {
+      if (isSafeKey(key) && isReviewState(state))
+        states[key] = state;
+    }
+  }
+  return states;
+}
+var DEFAULT_REVIEW_STATE, JsonCardRepository, JsonReviewRepository;
+var init_repositories = __esm({
+  "packages/storage/dist/repositories.js"() {
+    "use strict";
+    init_json();
+    init_validate();
+    DEFAULT_REVIEW_STATE = (cardId) => ({
+      cardId,
+      easeFactor: 2.5,
+      intervalDays: 0,
+      reviewCount: 0,
+      correctCount: 0
+    });
+    JsonCardRepository = class {
+      path;
+      constructor(path) {
+        this.path = path;
+      }
+      async save(card) {
+        await updateJson(this.path, (current) => {
+          const cards = parseCards2(current);
+          const index = cards.findIndex(({ id }) => id === card.id);
+          if (index === -1)
+            cards.push(card);
+          else
+            cards[index] = card;
+          return cards;
+        });
+      }
+      async get(id) {
+        return (await this.list()).find((card) => card.id === id) ?? null;
+      }
+      async list() {
+        return parseCards2(await readJson2(this.path, []));
+      }
+      async delete(id) {
+        await updateJson(this.path, (current) => parseCards2(current).filter((card) => card.id !== id));
+      }
+    };
+    JsonReviewRepository = class {
+      path;
+      constructor(path) {
+        this.path = path;
+      }
+      async get(cardId) {
+        const states = parseStates(await readJson2(this.path, {}));
+        return states[cardId] ?? DEFAULT_REVIEW_STATE(cardId);
+      }
+      async save(state) {
+        if (!isSafeKey(state.cardId))
+          throw new Error(`Unsafe card ID: ${state.cardId}`);
+        await updateJson(this.path, (current) => {
+          const states = parseStates(current);
+          states[state.cardId] = state;
+          return states;
+        });
+      }
+    };
+  }
+});
+
+// packages/storage/dist/workstream.js
+var init_workstream4 = __esm({
+  "packages/storage/dist/workstream.js"() {
+    "use strict";
+    init_dist4();
+    init_paths2();
+    init_repositories();
+  }
+});
+
+// packages/storage/dist/index.js
+import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
+async function initializeStore(root) {
+  await mkdir2(storeRoot(root), { recursive: true });
+  const files = [
+    [cardsPath(root), []],
+    [reviewPath(root), {}],
+    [settingsPath(root), { version: 1 }]
+  ];
+  await Promise.all(files.map(async ([path, initial]) => {
+    try {
+      await writeFile2(path, `${JSON.stringify(initial, null, 2)}
+`, { flag: "wx" });
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
+    }
+  }));
+}
+var init_dist4 = __esm({
+  "packages/storage/dist/index.js"() {
+    "use strict";
+    init_paths2();
+    init_repositories();
+    init_paths2();
+    init_json();
+    init_validate();
+    init_workstream4();
+  }
+});
+
+// packages/cli/src/production.ts
+import { stat } from "node:fs/promises";
+import { join as join6 } from "node:path";
+function createProductionDependencies() {
+  return {
+    initializeStore,
+    generateCards: (root, options) => generateCards(root, void 0, options),
+    createCardRepository: (root) => new JsonCardRepository(join6(flashlearnRoot(root), "cards.json")),
+    createReviewRepository: (root) => new JsonReviewRepository(join6(flashlearnRoot(root), "review.json")),
+    scheduleReview,
+    selectNextCard,
+    createServer: createFlashLearnServer,
+    listenServer: async (handle, host, port) => {
+      const server = handle;
+      await new Promise((resolveListen, reject) => {
+        const onError = (error) => reject(error);
+        server.once("error", onError);
+        server.listen(port, host, () => {
+          server.off("error", onError);
+          resolveListen();
+        });
+      });
+    },
+    isDirectory: async (path) => {
+      try {
+        return (await stat(path)).isDirectory();
+      } catch (error) {
+        if (error.code === "ENOENT") return false;
+        throw error;
+      }
+    },
+    now: () => /* @__PURE__ */ new Date()
+  };
+}
+var init_production = __esm({
+  "packages/cli/src/production.ts"() {
+    "use strict";
+    init_dist();
+    init_dist2();
+    init_dist3();
+    init_dist4();
+    init_paths();
+  }
+});
+
+// packages/cli/src/workstream.ts
+import { createHash } from "node:crypto";
+var pendingReviews, CliService;
+var init_workstream5 = __esm({
+  "packages/cli/src/workstream.ts"() {
+    "use strict";
+    init_paths();
+    pendingReviews = /* @__PURE__ */ new Map();
+    CliService = class {
+      constructor(dependencies2) {
+        this.dependencies = dependencies2;
+      }
+      async initialize(root) {
+        const rootPath = projectRoot(root);
+        await this.dependencies.initializeStore(rootPath);
+      }
+      async generate(directory, options) {
+        const root = projectRoot(directory);
+        await this.dependencies.initializeStore(root);
+        const repository = this.dependencies.createCardRepository(root);
+        const generatedCards = await this.dependencies.generateCards(root, options);
+        const updatedAt = this.dependencies.now().toISOString();
+        const cards = [];
+        for (const generated of generatedCards) {
+          this.validateGeneratedCard(generated);
+          const id = createHash("sha256").update(`${generated.source.path}\0${generated.question}`).digest("hex").slice(0, 16);
+          const existing = await repository.get(id);
+          const card = {
+            ...generated,
+            id,
+            createdAt: existing?.createdAt ?? updatedAt,
+            updatedAt
+          };
+          await repository.save(card);
+          cards.push(card);
+        }
+        return cards;
+      }
+      async start(root, options = {}) {
+        const rootPath = projectRoot(root);
+        await this.dependencies.initializeStore(rootPath);
+        const cards = this.dependencies.createCardRepository(rootPath);
+        const reviews = this.dependencies.createReviewRepository(rootPath);
+        const services = {
+          listCards: () => cards.list(),
+          getCard: (id) => cards.get(id),
+          nextCard: async () => {
+            const allCards = await cards.list();
+            const states = await Promise.all(allCards.map(({ id }) => reviews.get(id)));
+            return this.dependencies.selectNextCard(allCards, states, this.dependencies.now());
+          },
+          submitReview: (cardId, result) => this.serializeReview(rootPath, cardId, async () => {
+            if (!await cards.get(cardId)) throw new Error(`Card not found: ${cardId}`);
+            const state = this.dependencies.scheduleReview(
+              await reviews.get(cardId),
+              result,
+              this.dependencies.now()
+            );
+            await reviews.save(state);
+            return state;
+          })
+        };
+        const server = this.dependencies.createServer(services);
+        await this.dependencies.listenServer(server, options.host ?? "localhost", options.port ?? 4173);
+      }
+      async resolveProject(directory = ".") {
+        const root = projectRoot(directory);
+        if (!await this.dependencies.isDirectory(root)) throw new Error(`Project directory not found: ${root}`);
+        return root;
+      }
+      async getCard(id, directory) {
+        const root = await this.resolveProject(directory);
+        return this.dependencies.createCardRepository(root).get(id);
+      }
+      async listCards(directory) {
+        const root = await this.resolveProject(directory);
+        return this.dependencies.createCardRepository(root).list();
+      }
+      async status(directory) {
+        const root = await this.resolveProject(directory);
+        const cards = await this.dependencies.createCardRepository(root).list();
+        const reviews = this.dependencies.createReviewRepository(root);
+        const states = await Promise.all(cards.map(({ id }) => reviews.get(id)));
+        const now = this.dependencies.now();
+        const reviewed = states.filter(({ reviewCount }) => reviewCount > 0).length;
+        const due = states.filter(({ nextReview }) => !nextReview || new Date(nextReview) <= now).length;
+        return { project: root, cards: cards.length, reviewed, unreviewed: cards.length - reviewed, due };
+      }
+      validateGeneratedCard(card) {
+        if (typeof card.question !== "string" || typeof card.answer !== "string" || typeof card.source?.path !== "string" || typeof card.source.sha !== "string") {
+          throw new Error("Extraction returned an invalid GeneratedCard");
+        }
+      }
+      serializeReview(root, cardId, operation) {
+        const key = JSON.stringify([root, cardId]);
+        const result = (pendingReviews.get(key) ?? Promise.resolve()).then(operation);
+        const settled = result.then(() => {
+        }, () => {
+        });
+        pendingReviews.set(key, settled);
+        void settled.then(() => {
+          if (pendingReviews.get(key) === settled) pendingReviews.delete(key);
+        });
+        return result;
+      }
+    };
+  }
+});
+
+// packages/cli/src/confirm.ts
+import { createInterface } from "node:readline/promises";
+async function confirm(message) {
+  if (!process.stdin.isTTY || !process.stderr.isTTY) return false;
+  const reader = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await reader.question(message);
+    return /^(y|yes)$/i.test(answer.trim());
+  } finally {
+    reader.close();
+  }
+}
+var init_confirm = __esm({
+  "packages/cli/src/confirm.ts"() {
+    "use strict";
+  }
+});
+
+// packages/cli/src/index.ts
+var src_exports = {};
+var dependencies, service;
+var init_src = __esm({
+  async "packages/cli/src/index.ts"() {
+    "use strict";
+    init_cli();
+    init_production();
+    init_workstream5();
+    init_confirm();
+    dependencies = createProductionDependencies();
+    service = new CliService(dependencies);
+    process.exitCode = await runCli(process.argv.slice(2), service, {
+      cwd: process.cwd(),
+      stdout: (message) => console.log(message),
+      stderr: (message) => console.error(message),
+      confirm
+    });
+  }
+});
+
+// release/index.mjs
+import { readFileSync as readFileSync2 } from "node:fs";
+var args = process.argv.slice(2);
+if (args.length === 1 && ["--version", "-v"].includes(args[0])) {
+  console.log(JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8")).version);
+} else {
+  await init_src().then(() => src_exports);
+}