eklavya-mcp 1.0.0

package/README.md

@@ -0,0 +1,42 @@
+# eklavya-mcp
+
+The MCP server behind [Eklavya](../README.md): a local knowledge graph, SM-2 spaced repetition, and commit-gate state for agent-assisted learning.
+
+Runs standalone, so any MCP client can use it — this is what makes Eklavya editor-agnostic.
+
+```json
+{
+  "mcpServers": {
+    "eklavya": { "command": "npx", "args": ["-y", "eklavya-mcp"] }
+  }
+}
+```
+
+State lives in `~/.eklavya/knowledge.db` (SQLite, WAL). Override with `EKLAVYA_HOME` or `EKLAVYA_DB`.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `get_learner_profile` | what the developer already knows; call before teaching |
+| `log_session_concepts` | record what the current task exercises, with code context |
+| `get_session_quiz_plan` | what to ask, and at which difficulty tier |
+| `record_attempt` | grade 0–5, update mastery and the review schedule |
+| `get_gate_status` | whether this session's quiz gate has passed |
+| `upsert_concepts` | grow the graph, with slug normalization and dedupe |
+| `get_concept_graph` | a domain in prerequisite order |
+| `get_config` / `set_config` | global and per-repo settings |
+
+`session_id` is optional on every tool — the server resolves the current session itself.
+
+## CLI
+
+```bash
+eklavya doctor                      # check the install
+eklavya config get
+eklavya config set mode enforced [--repo]
+eklavya export-rules --out .cursor/rules/eklavya.md
+eklavya db-path
+```
+
+MIT.

package/bin/eklavya-mcp.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+# Launches the Eklavya MCP server, from wherever it actually exists.
+#
+# Two very different situations have to work:
+#
+#   1. Development from a checkout — use the local build, so edits take effect
+#      without republishing anything.
+#   2. Installed as a plugin from git — there is no local build, because dist/
+#      and node_modules/ are not tracked. Fall back to the published package,
+#      which npx fetches and whose native better-sqlite3 binding npm builds.
+#
+# Keep PINNED_VERSION in step with .claude-plugin/plugin.json and
+# mcp/package.json. A test asserts all three match.
+
+PINNED_VERSION="1.0.0"
+
+MCP_DIR=$(cd "$(dirname "$0")/.." && pwd)
+LOCAL_SERVER="$MCP_DIR/dist/server.js"
+
+if [ -f "$LOCAL_SERVER" ] && [ -d "$MCP_DIR/node_modules/better-sqlite3" ]; then
+  exec node "$LOCAL_SERVER" "$@"
+fi
+
+# stdout is the MCP transport, so npx's own chatter must not land there.
+exec npx --yes "eklavya-mcp@$PINNED_VERSION" "$@" 2>/dev/null

package/dist/assets/tutor-skill.md

@@ -0,0 +1,106 @@
+---
+name: tutor
+description: Teach the developer the concepts behind the code being written, using the Eklavya knowledge graph. Use while implementing any non-trivial task (to log the concepts it touches), and whenever quizzing, grading, or explaining a concept the developer is learning.
+---
+
+# Eklavya tutor
+
+You are teaching a real person, not generating a lesson. They are watching you build something; your job is to make sure they could have built it themselves next time.
+
+Everything you learn about them persists in the Eklavya MCP server. Use it — the whole point is never asking the same question twice.
+
+## Session id
+
+Every tool takes an optional `session_id`. **Omit it.** The server resolves the current session on its own. Only pass one if the user or a hook explicitly gave you an id to use.
+
+## While you work
+
+Call `log_session_concepts` as you implement, batched, once or twice per task. Log **3–8 concepts the work genuinely exercises** — not everything that appears in the file.
+
+Each concept needs a `context`: one line naming the actual decision, in the actual file.
+
+- Good: `"set httpOnly on the refresh cookie in auth.ts:42"`
+- Useless: `"used cookies"`
+
+If a concept has no slug yet, just log it — unknown slugs are created. Use kebab-case and check the response: `matched` tells you the concept already existed under a canonical slug, and you should use that slug from then on.
+
+Never interrupt the implementation to teach. Logging is silent. Teaching happens after the work is done, or when the developer asks.
+
+## When Eklavya asks you to quiz
+
+At the end of a task you may be told, mid-turn, to quiz the developer before
+finishing — with a list of concepts and the code context behind them. That is
+Eklavya's Stop hook, not the user. Treat it as a prompt to teach, not as an
+error, and do not mention hooks or exit codes. Just run the quiz below, then
+finish your turn normally.
+
+It fires at most once per batch of work, so this is your one chance to teach
+what the task covered. If the developer declines, record the skip and let it go.
+
+## Before you teach or quiz
+
+Call `get_learner_profile` first. Always. It tells you:
+
+- `mode` — how hard to push (see below)
+- what they already know, so you don't insult them by asking
+- `weak` — where they are actually struggling
+- `due_for_review` — what spaced repetition says is ready to resurface
+- `suggested_tier` — roughly where to pitch
+
+Then call `get_session_quiz_plan`. It returns the concepts worth asking about *and the tier to ask each one at*. Respect `tier_to_ask` — that number is how a concept gets harder as they get better.
+
+If `questions_needed` is 0, say nothing and move on. `reason: "cooldown"` means they were quizzed recently; `reason: "mode_off"` means Eklavya is dormant.
+
+## Asking
+
+**One question at a time.** Ask, wait for the answer, grade it, give a tight explanation, then the next. Never post a numbered list of five questions — that is a test, not teaching.
+
+**Ground every question in the diff you just wrote.** Reference the file, the line, the decision. The concept is abstract; the code in front of them is not.
+
+- Grounded: *"I set `httpOnly: true` on the refresh cookie in `auth.ts` but left the access token in memory. What attack is that split defending against, and what does it cost us?"*
+- Textbook, avoid: *"What is an httpOnly cookie?"*
+
+**Match the tier.** This is the difference between a quiz that teaches and one that annoys:
+
+| Tier | Asks for | Shape |
+|---|---|---|
+| 1 | recall | "What does this flag do?" |
+| 2 | mechanism | "Walk me through what the browser does with this." |
+| 3 | judgement | "Why this choice here rather than the obvious alternative?" |
+| 4 | failure modes | "What breaks this, and how would you notice in production?" |
+| 5 | design | "When is this the wrong architecture entirely, and what replaces it?" |
+
+Definitions are tier 1 **only**. If you find yourself asking "what is X" at tier 3, you have written a bad question.
+
+## Grading
+
+Call `record_attempt` for **every** answer, including skips. Grade honestly on SM-2's 0–5:
+
+| Grade | Means |
+|---|---|
+| 0 | skipped, or no attempt |
+| 1 | wrong, and the misconception is load-bearing |
+| 2 | wrong, but the shape of the idea is there |
+| 3 | correct, but hesitant or incomplete — got there slowly |
+| 4 | correct and clean |
+| 5 | correct, and explained *why*, or caught a nuance you didn't ask for |
+
+Before you pick a number, state to yourself what in their answer justifies it. A gate built on inflated grades teaches nothing and the developer knows it. Being generous here is not kindness — it is the one failure mode that makes this whole tool pointless.
+
+Then give feedback in **four sentences or fewer**. Correct the specific thing they got wrong; don't re-teach the whole topic.
+
+If they get it wrong, do not immediately give the answer. Ask one narrower question that isolates the gap. If they miss that too, then explain.
+
+## Growing the graph
+
+When work touches a concept with no slug and no near match, call `upsert_concepts` with a sensible `domain`, a `tier`, and at least one `prerequisite_of` edge to something that already exists. An isolated node teaches nothing about what to learn next.
+
+## Mode
+
+- **ambient** — offer. If they say skip, record it (grade 0, feedback `"skipped"`) and drop it immediately. Do not ask twice. Do not guilt them.
+- **enforced** — the quiz is required before committing. Say so plainly and once: the gate exists, here is what it needs, let's get through it. Supportive, not punitive. Never imply they are being punished.
+- **off** — do nothing at all.
+
+## The bar
+
+The developer should finish a quiz thinking *"I understand what we just built"* — not *"I passed."* If a question only proves they read the diff, it was the wrong question.

package/dist/cli.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * The `eklavya` CLI: the parts of Eklavya that make sense outside a Claude Code
+ * session. The commit gate has its own POSIX script (`cli/eklavya-gate`) because
+ * a git hook must not pay Node's startup cost.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { openDb } from './db.js';
+import { dbPath, eklavyaHome } from './paths.js';
+import { loadConfig, writeConfigFile, REPO_CONFIG_FILE, DEFAULT_CONFIG } from './config.js';
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const USAGE = `eklavya — local learning state for agent-assisted development
+
+Usage:
+  eklavya export-rules [--out <file>]   Write the tutor pedagogy as a Cursor rules file
+  eklavya config get                    Show the effective configuration
+  eklavya config set <key> <value>      Change a setting (add --repo to scope it to this repo)
+  eklavya doctor                        Check that everything is wired up
+  eklavya db-path                       Print the database location
+
+Config keys: mode, pass_threshold, max_questions_per_task,
+             min_minutes_between_quizzes, max_new_concepts_per_session, quiet
+`;
+function fail(message) {
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+}
+function exportRules(args) {
+    const skillPath = path.join(moduleDir, 'assets', 'tutor-skill.md');
+    if (!fs.existsSync(skillPath)) {
+        fail('The bundled tutor skill is missing. Run `npm run build` in the mcp/ directory.');
+    }
+    const skill = fs.readFileSync(skillPath, 'utf8').replace(/^---\n[\s\S]*?\n---\n/, '');
+    const rules = `---
+description: Eklavya tutor — teach the concepts behind the code being written
+alwaysApply: true
+---
+
+<!-- Generated by \`eklavya export-rules\`. Do not edit by hand; edit the plugin's
+     skills/tutor/SKILL.md and regenerate, so Claude Code and Cursor never drift. -->
+
+The Eklavya MCP server is available in this editor. Its tools are the source of
+truth for what this developer already knows.
+
+${skill.trim()}
+`;
+    const outIndex = args.indexOf('--out');
+    if (outIndex >= 0) {
+        const out = args[outIndex + 1];
+        if (!out)
+            fail('--out needs a file path.');
+        fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+        fs.writeFileSync(out, rules, 'utf8');
+        process.stdout.write(`Wrote ${out}\n`);
+        return;
+    }
+    process.stdout.write(rules);
+}
+function configCommand(args) {
+    const [action, key, value] = args;
+    const scopeRepo = args.includes('--repo');
+    const resolved = loadConfig();
+    if (!action || action === 'get') {
+        process.stdout.write(`${JSON.stringify(resolved.config, null, 2)}\n`);
+        process.stdout.write(`\nglobal: ${resolved.globalPath}\n`);
+        process.stdout.write(`repo:   ${resolved.repoPath ?? '(none)'}\n`);
+        return;
+    }
+    if (action !== 'set')
+        fail(`Unknown config action "${action}".`);
+    if (!key || value === undefined)
+        fail('Usage: eklavya config set <key> <value>');
+    if (!(key in DEFAULT_CONFIG)) {
+        fail(`Unknown setting "${key}". Known: ${Object.keys(DEFAULT_CONFIG).join(', ')}`);
+    }
+    let parsed = value;
+    if (value === 'true' || value === 'false')
+        parsed = value === 'true';
+    else if (value !== '' && !Number.isNaN(Number(value)))
+        parsed = Number(value);
+    let target;
+    if (scopeRepo) {
+        if (!resolved.repoRoot)
+            fail('Not inside a git repository, so there is nowhere to write .eklavya.json.');
+        target = resolved.repoPath ?? path.join(resolved.repoRoot, REPO_CONFIG_FILE);
+    }
+    else {
+        target = resolved.globalPath;
+    }
+    writeConfigFile(target, { [key]: parsed });
+    process.stdout.write(`${key} = ${JSON.stringify(parsed)}  ->  ${target}\n`);
+}
+function doctor() {
+    const file = dbPath();
+    const lines = [];
+    let ok = true;
+    lines.push(`home:     ${eklavyaHome()}`);
+    lines.push(`database: ${file}${fs.existsSync(file) ? '' : '   (not created yet)'}`);
+    try {
+        const db = openDb(file);
+        const concepts = db.prepare('SELECT count(*) n FROM concepts').get().n;
+        const attempts = db.prepare('SELECT count(*) n FROM attempts').get().n;
+        const known = db.prepare('SELECT count(*) n FROM mastery WHERE score >= 0.7 AND reps >= 2').get().n;
+        lines.push(`concepts: ${concepts}`);
+        lines.push(`attempts: ${attempts}`);
+        lines.push(`mastered: ${known}`);
+        lines.push(`journal:  ${String(db.pragma('journal_mode', { simple: true }))}`);
+        db.close();
+    }
+    catch (err) {
+        ok = false;
+        lines.push(`database error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const resolved = loadConfig();
+    lines.push(`mode:     ${resolved.config.mode}${resolved.repoPath ? ' (from this repo)' : ''}`);
+    process.stdout.write(`${lines.join('\n')}\n`);
+    if (!ok)
+        process.exit(1);
+}
+function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    switch (command) {
+        case 'export-rules':
+            return exportRules(rest);
+        case 'config':
+            return configCommand(rest);
+        case 'doctor':
+            return doctor();
+        case 'db-path':
+            process.stdout.write(`${dbPath()}\n`);
+            return;
+        case undefined:
+        case '-h':
+        case '--help':
+            process.stdout.write(USAGE);
+            return;
+        default:
+            process.stderr.write(USAGE);
+            process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/concurrency.js

@@ -0,0 +1,41 @@
+/**
+ * Several Claude Code sessions and the git pre-commit hook can hit the same
+ * SQLite file at once (PRD §8 "Concurrency"). WAL plus `busy_timeout` handles
+ * almost all of it; what remains is the case where two writers upgrade to a
+ * write transaction at the same moment and SQLite returns SQLITE_BUSY
+ * immediately rather than waiting.
+ *
+ * A busy transaction has already been rolled back, so retrying it is safe —
+ * that is what makes this wrapper correct for writes and not just for reads.
+ */
+const BUSY_CODES = new Set(['SQLITE_BUSY', 'SQLITE_BUSY_SNAPSHOT', 'SQLITE_LOCKED']);
+export const MAX_BUSY_ATTEMPTS = 5;
+function isBusy(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const code = err.code;
+    return typeof code === 'string' && BUSY_CODES.has(code);
+}
+/** Blocking backoff — better-sqlite3 is synchronous, so there is nothing to await. */
+function sleepSync(ms) {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        // busy-wait; only ever a few milliseconds, and only under real contention
+    }
+}
+export function retryOnBusy(fn, attempts = MAX_BUSY_ATTEMPTS) {
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            return fn();
+        }
+        catch (err) {
+            if (!isBusy(err))
+                throw err;
+            lastError = err;
+            sleepSync(10 * (attempt + 1));
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,sBAAsB,EAAE,eAAe,CAAC,CAAC,CAAC;AAErF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC,SAAS,MAAM,CAAC,GAAY;IAC1B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,IAAI,GAAI,GAAyB,CAAC,IAAI,CAAC;IAC7C,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED,sFAAsF;AACtF,SAAS,SAAS,CAAC,EAAU;IAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IAC9B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;QAC1B,0EAA0E;IAC5E,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAI,EAAW,EAAE,QAAQ,GAAG,iBAAiB;IACtE,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,EAAE,EAAE,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;gBAAE,MAAM,GAAG,CAAC;YAC5B,SAAS,GAAG,GAAG,CAAC;YAChB,SAAS,CAAC,EAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,MAAM,SAAS,CAAC;AAClB,CAAC"}

package/dist/config.js

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { globalConfigPath } from './paths.js';
+export const DEFAULT_CONFIG = {
+    mode: 'ambient',
+    pass_threshold: 0.7,
+    max_questions_per_task: 4,
+    min_minutes_between_quizzes: 20,
+    domains_enabled: ['*'],
+    quiet: false,
+    max_new_concepts_per_session: 8,
+};
+export const REPO_CONFIG_FILE = '.eklavya.json';
+function realPath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+function readJson(file) {
+    try {
+        const text = fs.readFileSync(file, 'utf8');
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        // A missing or malformed config must never take a session down; defaults win.
+        return null;
+    }
+}
+/**
+ * Walks up from `cwd` looking for a repo-level config, stopping at the git root
+ * or the filesystem root. Returns the directory holding it, plus the git root if
+ * one was passed on the way (Phase 3 stamps that onto gate rows).
+ */
+export function findRepoConfig(cwd = process.cwd()) {
+    // Resolve symlinks: `git rev-parse --show-toplevel` reports the real path, and
+    // the git pre-commit hook matches gate rows on it. On macOS /tmp is a symlink
+    // to /private/tmp, so without this the two sides silently never match.
+    let dir = realPath(path.resolve(cwd));
+    let repoPath = null;
+    let repoRoot = null;
+    for (;;) {
+        if (!repoPath && fs.existsSync(path.join(dir, REPO_CONFIG_FILE))) {
+            repoPath = path.join(dir, REPO_CONFIG_FILE);
+        }
+        if (!repoRoot && fs.existsSync(path.join(dir, '.git'))) {
+            repoRoot = dir;
+            // The git root is the boundary: a config above it belongs to another project.
+            break;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir || dir === os.homedir())
+            break;
+        dir = parent;
+    }
+    return { repoPath, repoRoot };
+}
+function coerce(raw, base) {
+    const out = { ...base };
+    if (raw.mode === 'ambient' || raw.mode === 'enforced' || raw.mode === 'off')
+        out.mode = raw.mode;
+    if (typeof raw.pass_threshold === 'number' && raw.pass_threshold >= 0 && raw.pass_threshold <= 1) {
+        out.pass_threshold = raw.pass_threshold;
+    }
+    if (typeof raw.max_questions_per_task === 'number' && raw.max_questions_per_task > 0) {
+        out.max_questions_per_task = Math.floor(raw.max_questions_per_task);
+    }
+    if (typeof raw.min_minutes_between_quizzes === 'number' && raw.min_minutes_between_quizzes >= 0) {
+        out.min_minutes_between_quizzes = Math.floor(raw.min_minutes_between_quizzes);
+    }
+    if (Array.isArray(raw.domains_enabled) && raw.domains_enabled.every((d) => typeof d === 'string')) {
+        out.domains_enabled = raw.domains_enabled;
+    }
+    if (typeof raw.quiet === 'boolean')
+        out.quiet = raw.quiet;
+    if (typeof raw.max_new_concepts_per_session === 'number' &&
+        raw.max_new_concepts_per_session >= 0) {
+        out.max_new_concepts_per_session = Math.floor(raw.max_new_concepts_per_session);
+    }
+    return out;
+}
+/** Global config merged with the repo's, repo winning (PRD §11). */
+export function loadConfig(cwd = process.cwd()) {
+    const globalPath = globalConfigPath();
+    const { repoPath, repoRoot } = findRepoConfig(cwd);
+    const globalRaw = readJson(globalPath) ?? {};
+    const repoRaw = repoPath ? (readJson(repoPath) ?? {}) : {};
+    const raw = { ...globalRaw, ...repoRaw };
+    return {
+        config: coerce(raw, DEFAULT_CONFIG),
+        raw,
+        globalPath,
+        repoPath,
+        repoRoot,
+    };
+}
+/** Writes via temp file + rename: the git hook may be reading mid-write. */
+export function writeConfigFile(file, patch) {
+    const existing = readJson(file) ?? {};
+    const merged = { ...existing, ...patch };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+    fs.renameSync(tmp, file);
+    return merged;
+}
+export function isDomainEnabled(config, domain) {
+    return config.domains_enabled.includes('*') || config.domains_enabled.includes(domain);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/db.js

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { dbPath } from './paths.js';
+import { runMigrations } from './migrate.js';
+import { seedIfNeeded } from './seed.js';
+/**
+ * Opens (creating if needed) the knowledge DB with the pragmas the design
+ * depends on: WAL so several Claude Code sessions and the git hook can share
+ * the file (PRD §8 "Concurrency"), and foreign keys so the graph stays honest.
+ */
+export function openDb(file = dbPath()) {
+    if (file !== ':memory:') {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+    }
+    const db = new Database(file);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    // Concurrent writers (two sessions, or a session plus the pre-commit hook)
+    // should wait briefly rather than fail with SQLITE_BUSY.
+    db.pragma('busy_timeout = 5000');
+    runMigrations(db);
+    seedIfNeeded(db);
+    return db;
+}
+//# sourceMappingURL=db.js.map

package/dist/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAIzC;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,OAAe,MAAM,EAAE;IAC5C,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9B,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAChC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAC/B,2EAA2E;IAC3E,yDAAyD;IACzD,EAAE,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;IAEjC,aAAa,CAAC,EAAE,CAAC,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,CAAC;IAEjB,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/migrate.js

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { migrationsDir } from './paths.js';
+const VERSION_KEY = 'schema_version';
+function readVersion(db) {
+    const row = db.prepare('SELECT value FROM meta WHERE key = ?').get(VERSION_KEY);
+    return row ? Number(row.value) : 0;
+}
+function writeVersion(db, version) {
+    db.prepare(`INSERT INTO meta (key, value) VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(VERSION_KEY, String(version));
+}
+/**
+ * Applies numbered SQL migrations in order, recording progress in `meta`.
+ * Idempotent: re-running applies nothing. Returns the filenames applied.
+ */
+export function runMigrations(db, dir = migrationsDir()) {
+    // Bootstrap `meta` itself so the version read below has somewhere to look.
+    db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
+    const current = readVersion(db);
+    const files = fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.sql'))
+        .sort();
+    const applied = [];
+    for (const file of files) {
+        const n = Number(file.slice(0, 3));
+        if (!Number.isFinite(n) || n === 0) {
+            throw new Error(`Migration filename must start with a number: ${file}`);
+        }
+        if (n <= current)
+            continue;
+        const sql = fs.readFileSync(path.join(dir, file), 'utf8');
+        db.transaction(() => {
+            db.exec(sql);
+            writeVersion(db, n);
+        })();
+        applied.push(file);
+    }
+    return applied;
+}
+export function schemaVersion(db) {
+    return readVersion(db);
+}
+//# sourceMappingURL=migrate.js.map

package/dist/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,GAAG,gBAAgB,CAAC;AAErC,SAAS,WAAW,CAAC,EAAY;IAC/B,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,sCAAsC,CAAC,CAAC,GAAG,CAAC,WAAW,CAEjE,CAAC;IACd,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,YAAY,CAAC,EAAY,EAAE,OAAe;IACjD,EAAE,CAAC,OAAO,CACR;2DACuD,CACxD,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,EAAY,EAAE,GAAG,GAAG,aAAa,EAAE;IAC/D,2EAA2E;IAC3E,EAAE,CAAC,IAAI,CAAC,6EAA6E,CAAC,CAAC;IAEvF,MAAM,OAAO,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,EAAE;SACb,WAAW,CAAC,GAAG,CAAC;SAChB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;SACjC,IAAI,EAAE,CAAC;IAEV,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,gDAAgD,IAAI,EAAE,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,CAAC,IAAI,OAAO;YAAE,SAAS;QAE3B,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QAC1D,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE;YAClB,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACb,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACtB,CAAC,CAAC,EAAE,CAAC;QACL,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAY;IACxC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC"}

package/dist/migrations/001_init.sql

@@ -0,0 +1,71 @@
+-- Eklavya schema v1 (PRD §7).
+-- Every statement is IF NOT EXISTS so the runner is safe to re-apply.
+
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS concepts (
+  id          INTEGER PRIMARY KEY,
+  slug        TEXT NOT NULL UNIQUE,        -- 'jwt-structure', 'httponly-cookies'
+  name        TEXT NOT NULL,
+  domain      TEXT NOT NULL,               -- 'web-auth', 'react', 'node-backend', ...
+  description TEXT,
+  tier        INTEGER NOT NULL DEFAULT 1,  -- 1 fundamentals … 5 expert
+  source      TEXT NOT NULL DEFAULT 'seed' -- 'seed' | 'llm'
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  from_concept INTEGER NOT NULL REFERENCES concepts(id),
+  to_concept   INTEGER NOT NULL REFERENCES concepts(id),
+  relation     TEXT NOT NULL CHECK (relation IN ('prerequisite_of','related_to','part_of')),
+  PRIMARY KEY (from_concept, to_concept, relation)
+);
+
+CREATE TABLE IF NOT EXISTS mastery (
+  concept_id   INTEGER PRIMARY KEY REFERENCES concepts(id),
+  score        REAL NOT NULL DEFAULT 0,    -- 0..1
+  ease         REAL NOT NULL DEFAULT 2.5,  -- SM-2 ease factor
+  interval_d   REAL NOT NULL DEFAULT 0,    -- current review interval, days
+  reps         INTEGER NOT NULL DEFAULT 0,
+  last_seen    TEXT,                       -- ISO timestamp
+  next_review  TEXT                        -- ISO timestamp
+);
+
+CREATE TABLE IF NOT EXISTS attempts (
+  id          INTEGER PRIMARY KEY,
+  concept_id  INTEGER NOT NULL REFERENCES concepts(id),
+  session_id  TEXT,
+  question    TEXT NOT NULL,
+  answer      TEXT,
+  grade       INTEGER NOT NULL,            -- 0..5 (SM-2 quality)
+  difficulty  INTEGER NOT NULL,            -- tier the question was asked at
+  feedback    TEXT,                        -- tutor's explanation
+  ts          TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS session_concepts (
+  session_id  TEXT NOT NULL,
+  concept_id  INTEGER NOT NULL REFERENCES concepts(id),
+  context     TEXT,                        -- e.g. 'set httpOnly on refresh cookie in auth.ts'
+  ts          TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (session_id, concept_id)
+);
+
+CREATE TABLE IF NOT EXISTS gates (
+  session_id   TEXT PRIMARY KEY,
+  mode         TEXT NOT NULL,              -- 'ambient' | 'enforced'
+  required     INTEGER NOT NULL DEFAULT 0,
+  answered     INTEGER NOT NULL DEFAULT 0,
+  passed       INTEGER NOT NULL DEFAULT 0, -- boolean
+  updated_at   TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- Read paths that must stay fast: the SessionStart hook and the PreToolUse gate
+-- both run on the critical path of a user action (PRD §9).
+CREATE INDEX IF NOT EXISTS idx_concepts_domain       ON concepts(domain);
+CREATE INDEX IF NOT EXISTS idx_session_concepts_sid  ON session_concepts(session_id);
+CREATE INDEX IF NOT EXISTS idx_attempts_concept_ts   ON attempts(concept_id, ts DESC);
+CREATE INDEX IF NOT EXISTS idx_attempts_session      ON attempts(session_id);
+CREATE INDEX IF NOT EXISTS idx_mastery_next_review   ON mastery(next_review);