@jiy/quizme 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jingyuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# QuizMe
+
+QuizMe 是一个本地 CLI MVP，用于将 Claude Code 会话上下文、仓库上下文或用户输入主题转化为短小的面试风格选择题。
+
+## 文档
+
+- [产品文档](docs/product.md)
+- [技术文档](docs/technical.md)
+
+## 安装
+
+```bash
+npm install -g @jiy/quizme
+```
+
+无需全局安装也可直接用 `npx`：
+
+```bash
+npx @jiy/quizme
+```
+
+## 前置条件
+
+题目生成和 `why` 模式会调用本机的 **Claude Code CLI**（`claude` 命令）。请确保已安装并位于 `PATH`：
+
+```bash
+claude --version   # 能输出版本号即可
+```
+
+未安装可运行 `npm install -g @anthropic-ai/claude-code`，或参考 [Claude Code 文档](https://docs.anthropic.com/claude-code)。
+
+> 无 `claude` 时仍可离线体验：`QUIZME_PROVIDER=local`。
+
+## 使用方式
+
+```bash
+quizme
+quizme --repo .
+quizme "React rendering and caching"
+```
+
+## 说明
+
+- 默认模式会从 `~/.claude/projects` 读取当前仓库最近的 Claude Code transcript。统计、档案、设置、复习等功能通过交互式主界面进入。
+- 本地数据存储在平台 app data 目录中，并使用 `sqlite3`。
+- 在受限环境中，存储会 fallback 到 `./.quizme`。也可以通过 `QUIZME_DATA_DIR=/path/to/data` 覆盖数据目录。
+- 题目生成和 `why` 模式会调用本地 `claude` CLI 的 print mode（`--bare` + `--tools ""`，禁用 agent tool；上下文已写入 prompt）。
+- 离线 demo 可使用 `QUIZME_PROVIDER=local`。如果希望优先使用 Claude、失败后 fallback 到本地 provider，可使用 `QUIZME_PROVIDER_FALLBACK=local`。

package/dist/cli/config.js

@@ -0,0 +1,37 @@
+import { runInkSetup } from "../ui/renderApp.js";
+export async function ensureConfig(store) {
+    const existing = store.getConfig("user");
+    if (existing) {
+        return normalizeConfig(existing);
+    }
+    const config = await runInkSetup({
+        onComplete: (next) => {
+            store.setConfig("user", next);
+        }
+    });
+    return normalizeConfig(config);
+}
+export function normalizeConfig(config = {}) {
+    return {
+        level: config.level || "mid",
+        language: config.language || "en",
+        dailyGoal: Number(config.dailyGoal || 5),
+        soundEnabled: config.soundEnabled === true,
+        createdAt: config.createdAt || new Date().toISOString()
+    };
+}
+function pickLevel(value) {
+    switch (String(value).trim()) {
+        case "1": return "junior";
+        case "3": return "senior";
+        case "4": return "staff";
+        default: return "mid";
+    }
+}
+export function isValidLevel(value) {
+    return value === "junior" || value === "mid" || value === "senior" || value === "staff";
+}
+export function isValidLanguage(value) {
+    return value === "zh-CN" || value === "en";
+}
+export { pickLevel };

package/dist/cli/index.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { createStore } from "../storage/index.js";
+import { ensureConfig } from "./config.js";
+import { runQuizSession } from "./session.js";
+import { getLatestClaudeSummary } from "../sources/claudeSession.js";
+import { getRepoSummary } from "../sources/repository.js";
+import { getTopicSummary } from "../sources/topic.js";
+import { runInkHome } from "../ui/renderApp.js";
+function parseArgs(argv) {
+    const args = { _: [] };
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "--repo") {
+            args.repo = argv[i + 1];
+            i += 1;
+        }
+        else if (token === "--help" || token === "-h") {
+            args.help = true;
+        }
+        else {
+            args._.push(token);
+        }
+    }
+    return args;
+}
+function printHelp() {
+    console.log(`
+quizme
+
+Usage:
+  quizme
+  quizme --repo .
+  quizme "React rendering"
+  `);
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        printHelp();
+        return;
+    }
+    const store = createStore();
+    const config = await ensureConfig(store);
+    if (args.repo || args._.length > 0) {
+        const source = resolveSource(args);
+        return runQuizSession({ store, config, source });
+    }
+    await runInkHome({ store, config, resolveSource });
+}
+function resolveSource(args) {
+    if (args.repo) {
+        return getRepoSummary(path.resolve(args.repo));
+    }
+    if (args._.length > 0) {
+        return getTopicSummary(args._.join(" "));
+    }
+    return getLatestClaudeSummary(process.cwd());
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`QuizMe error: ${message}`);
+    process.exitCode = 1;
+});

package/dist/cli/session.js

@@ -0,0 +1,10 @@
+import { runInkQuiz } from "../ui/renderApp.js";
+export async function runQuizSession({ store, config, source, questionsOverride = null, mode = "mixed" }) {
+    await runInkQuiz({
+        store,
+        config,
+        source,
+        questionsOverride,
+        mode
+    });
+}

package/dist/generation/dedupe.js

@@ -0,0 +1,11 @@
+export function dedupeQuestions(questions, recentQuestions) {
+    const seen = new Set(recentQuestions.map((item) => `${item.topic}:${item.question}`));
+    return questions.filter((question) => {
+        const key = `${question.topic}:${question.question}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}

package/dist/generation/schema.js

@@ -0,0 +1,50 @@
+export const QUESTION_SCHEMA = {
+    type: "object",
+    properties: {
+        questions: {
+            type: "array",
+            minItems: 3,
+            maxItems: 5,
+            items: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    sourceMode: {
+                        type: "string",
+                        enum: ["contextual", "adjacent", "interview_style"]
+                    },
+                    topic: { type: "string" },
+                    difficulty: { type: "integer", minimum: 1, maximum: 5 },
+                    question: { type: "string" },
+                    choices: {
+                        type: "array",
+                        minItems: 4,
+                        maxItems: 4,
+                        items: {
+                            type: "object",
+                            properties: {
+                                id: { type: "string", enum: ["A", "B", "C", "D"] },
+                                text: { type: "string" }
+                            },
+                            required: ["id", "text"]
+                        }
+                    },
+                    answer: { type: "string", enum: ["A", "B", "C", "D"] },
+                    explanation: { type: "string" },
+                    whyWrong: { type: "object" },
+                    tags: {
+                        type: "array",
+                        minItems: 1,
+                        items: { type: "string" }
+                    },
+                    followUps: {
+                        type: "array",
+                        items: { type: "string" }
+                    }
+                },
+                required: ["id", "sourceMode", "topic", "difficulty", "question", "choices", "answer", "explanation", "whyWrong", "tags", "followUps"]
+            }
+        }
+    },
+    required: ["questions"]
+};

package/dist/generation/validator.js

@@ -0,0 +1,134 @@
+const VALID_CHOICE_IDS = ["A", "B", "C", "D"];
+const VALID_SOURCE_MODES = [
+    "contextual",
+    "adjacent",
+    "interview_style"
+];
+export class QuestionValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid question payload: ${issues.join("; ")}`);
+        this.name = "QuestionValidationError";
+        this.issues = issues;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isChoice(value) {
+    return isRecord(value)
+        && typeof value.id === "string"
+        && VALID_CHOICE_IDS.includes(value.id)
+        && typeof value.text === "string"
+        && value.text.trim().length > 0;
+}
+function validateOne(raw, index, issues) {
+    const at = `questions[${index}]`;
+    if (!isRecord(raw)) {
+        issues.push(`${at} is not an object`);
+        return null;
+    }
+    const errs = [];
+    if (typeof raw.id !== "string" || !raw.id.trim()) {
+        errs.push(`${at}.id missing`);
+    }
+    if (typeof raw.topic !== "string" || !raw.topic.trim()) {
+        errs.push(`${at}.topic missing`);
+    }
+    if (typeof raw.question !== "string" || raw.question.trim().length < 4) {
+        errs.push(`${at}.question missing or too short`);
+    }
+    if (typeof raw.explanation !== "string" || !raw.explanation.trim()) {
+        errs.push(`${at}.explanation missing`);
+    }
+    const sourceMode = raw.sourceMode;
+    if (typeof sourceMode !== "string" || !VALID_SOURCE_MODES.includes(sourceMode)) {
+        errs.push(`${at}.sourceMode must be one of ${VALID_SOURCE_MODES.join(", ")}`);
+    }
+    const difficulty = Number(raw.difficulty);
+    if (!Number.isInteger(difficulty) || difficulty < 1 || difficulty > 5) {
+        errs.push(`${at}.difficulty must be integer 1..5`);
+    }
+    const choices = raw.choices;
+    if (!Array.isArray(choices) || choices.length !== 4) {
+        errs.push(`${at}.choices must be exactly 4 items`);
+    }
+    else {
+        const ids = new Set();
+        choices.forEach((choice, i) => {
+            if (!isChoice(choice)) {
+                errs.push(`${at}.choices[${i}] invalid`);
+                return;
+            }
+            if (ids.has(choice.id)) {
+                errs.push(`${at}.choices[${i}] duplicate id ${choice.id}`);
+            }
+            ids.add(choice.id);
+        });
+        if (VALID_CHOICE_IDS.some((id) => !ids.has(id))) {
+            errs.push(`${at}.choices must include ids A, B, C, D`);
+        }
+    }
+    const answer = raw.answer;
+    if (typeof answer !== "string" || !VALID_CHOICE_IDS.includes(answer)) {
+        errs.push(`${at}.answer must be one of A, B, C, D`);
+    }
+    const whyWrong = raw.whyWrong;
+    if (!isRecord(whyWrong)) {
+        errs.push(`${at}.whyWrong must be an object`);
+    }
+    else if (typeof answer === "string") {
+        for (const id of VALID_CHOICE_IDS) {
+            if (id === answer)
+                continue;
+            if (typeof whyWrong[id] !== "string" || !whyWrong[id].trim()) {
+                errs.push(`${at}.whyWrong.${id} missing`);
+            }
+        }
+    }
+    const tags = raw.tags;
+    if (!Array.isArray(tags) || tags.length === 0 || tags.some((t) => typeof t !== "string" || !t.trim())) {
+        errs.push(`${at}.tags must be a non-empty array of strings`);
+    }
+    const followUps = raw.followUps;
+    if (!Array.isArray(followUps) || followUps.some((t) => typeof t !== "string")) {
+        errs.push(`${at}.followUps must be an array of strings`);
+    }
+    if (errs.length) {
+        issues.push(...errs);
+        return null;
+    }
+    return {
+        id: raw.id.trim(),
+        sourceMode: sourceMode,
+        topic: raw.topic.trim(),
+        difficulty,
+        question: raw.question.trim(),
+        choices: choices.map((c) => ({ id: c.id, text: c.text.trim() })),
+        answer: answer,
+        explanation: raw.explanation.trim(),
+        whyWrong: whyWrong,
+        tags: tags.map((t) => t.trim()),
+        followUps: followUps.map((t) => t.trim())
+    };
+}
+export function validateQuestions(payload) {
+    if (!isRecord(payload)) {
+        throw new QuestionValidationError(["payload is not an object"]);
+    }
+    const raw = payload.questions;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new QuestionValidationError(["questions must be a non-empty array"]);
+    }
+    const issues = [];
+    const valid = [];
+    raw.forEach((item, index) => {
+        const q = validateOne(item, index, issues);
+        if (q)
+            valid.push(q);
+    });
+    if (!valid.length) {
+        throw new QuestionValidationError(issues.length ? issues : ["no valid questions"]);
+    }
+    return valid;
+}

package/dist/platform/fs.js

@@ -0,0 +1,17 @@
+import fs from "node:fs";
+import path from "node:path";
+export function ensureDir(dirPath) {
+    fs.mkdirSync(dirPath, { recursive: true });
+}
+export function readJson(filePath, fallback = null) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+export function writeJson(filePath, value) {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, JSON.stringify(value, null, 2) + "\n", "utf8");
+}

package/dist/platform/paths.js

@@ -0,0 +1,27 @@
+import os from "node:os";
+import path from "node:path";
+export function getAppDataDir() {
+    if (process.env.QUIZME_DATA_DIR) {
+        return process.env.QUIZME_DATA_DIR;
+    }
+    const home = os.homedir();
+    if (process.platform === "darwin") {
+        return path.join(home, "Library", "Application Support", "quizme");
+    }
+    if (process.platform === "win32") {
+        return path.join(process.env.APPDATA || path.join(home, "AppData", "Roaming"), "quizme");
+    }
+    return path.join(process.env.XDG_DATA_HOME || path.join(home, ".local", "share"), "quizme");
+}
+export function slugifyProjectPath(projectPath) {
+    return projectPath.replace(/[:\\/]+/g, "-").replace(/_/g, "-");
+}
+export function getClaudeRoots(cwd = process.cwd()) {
+    return [
+        path.join(cwd, ".claude"),
+        path.join(os.homedir(), ".claude")
+    ];
+}
+export function getClaudeProjectsDir() {
+    return path.join(os.homedir(), ".claude", "projects");
+}