learn-anything-cli 0.3.0 → 0.4.0

package/README.md

@@ -23,6 +23,12 @@ npm install -g learn-anything-cli
 learn-anything init
 ```
 
+### Context7 Integration (Optional)
+
+When running `init` or `update`, you'll be prompted to enable **Context7** for documentation verification. When enabled, the AI will fetch official documentation and verify its explanations against authoritative sources — improving teaching accuracy.
+
+If you haven't set up Context7 yet, run `npx ctx7 setup` or visit the [Context7 docs](https://context7.com/docs/resources/all-clients) for your specific AI tool.
+
 After init, your AI assistant gains five learning commands:
 
 | Command                          | What it does                                                 |

package/README.zh-CN.md

@@ -21,6 +21,12 @@ npm install -g learn-anything-cli
 learn-anything init
 ```
 
+### Context7 集成（可选）
+
+在执行 `init` 或 `update` 时，会提示是否启用 **Context7** 文档验证。启用后，AI 会获取官方文档并对照权威来源验证其教学内容——提高教学准确性。
+
+如果你还没有配置 Context7，运行 `npx ctx7 setup` 或访问 [Context7 文档](https://context7.com/docs/resources/all-clients) 查看你使用的 AI 工具的配置方式。
+
 初始化后，你的 AI 助手获得五个学习命令：
 
 | 命令                             | 功能                                   |

package/dist/cli/index.js

@@ -24,6 +24,8 @@ program
     .option('--tools <tools>', m.cli.toolsOptionDescription(availableToolIds.join(', ')))
     .option('--force', m.cli.forceOption)
     .option('--lang <locale>', m.cli.langOption)
+    .option('--context7', 'Enable Context7 documentation verification')
+    .option('--no-context7', 'Disable Context7 documentation verification')
     .action(async (targetPath = '.', options) => {
     const cliLocale = resolveLocale(options?.lang);
     const mc = cliLocale !== earlyLocale ? getMessages(cliLocale).cli : m.cli;
@@ -51,6 +53,7 @@ program
             tools: options?.tools,
             force: options?.force,
             locale: cliLocale,
+            context7: options?.context7,
         });
         await initCommand.execute(targetPath);
     }

package/dist/core/init.d.ts

@@ -4,18 +4,24 @@ type InitCommandOptions = {
     force?: boolean;
     locale?: SupportedLocale;
     update?: boolean;
+    context7?: boolean;
 };
 export declare class InitCommand {
     private readonly toolsArg?;
     private readonly force;
     private readonly locale;
     private readonly isUpdate;
+    private readonly context7Arg?;
+    private context7Enabled;
     constructor(options?: InitCommandOptions);
     execute(targetPath?: string): Promise<void>;
+    private promptContext7;
     private detectTools;
     private hasToolDir;
     private interactiveSelect;
     private generateSkillsForTool;
+    /** Read a compiled script from dist/scripts/ (bundled alongside this module). */
+    private readCompiledScript;
     private generateCommandsForTool;
 }
 export {};

package/dist/core/init.js

@@ -2,12 +2,14 @@ import path from 'path';
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { AI_TOOLS, LEARN_DIR } from './config.js';
 import { isInteractive } from '../utils/interactive.js';
 import { generateCommands, CommandAdapterRegistry } from './command-generation/index.js';
 import { getSkillTemplates, getCommandContents, generateSkillContent } from './shared/index.js';
 import { getMessages } from '../i18n/index.js';
+import { CONTEXT7_GUIDANCE } from './templates/context7-guidance.js';
 const require = createRequire(import.meta.url);
 const { version: VERSION } = require('../../package.json');
 export class InitCommand {
@@ -15,11 +17,14 @@ export class InitCommand {
     force;
     locale;
     isUpdate;
+    context7Arg;
+    context7Enabled = false;
     constructor(options = {}) {
         this.toolsArg = options.tools;
         this.force = options.force ?? false;
         this.locale = options.locale ?? 'en';
         this.isUpdate = options.update ?? false;
+        this.context7Arg = options.context7;
     }
     async execute(targetPath = '.') {
         const resolvedPath = path.resolve(targetPath);
@@ -28,7 +33,14 @@ export class InitCommand {
         await FileSystemUtils.ensureDir(resolvedPath);
         // Create .learn/ directory in the target project
         const learnDir = path.join(resolvedPath, LEARN_DIR);
-        await FileSystemUtils.ensureDir(path.join(learnDir, 'topics'));
+        const topicsDir = path.join(learnDir, 'topics');
+        await FileSystemUtils.ensureDir(topicsDir);
+        // Run v0→v1 migration for any existing learning data
+        const { migrateAll } = await import('./learn-protocol/index.js');
+        const report = await migrateAll(topicsDir);
+        if (report.migratedCount > 0) {
+            console.log(chalk.green(m.init.migrationComplete(report.migratedCount)));
+        }
         console.log(chalk.bold(m.init.header));
         // Detect available tools
         const availableTools = await this.detectTools(resolvedPath);
@@ -59,6 +71,12 @@ export class InitCommand {
                 .join(', '))));
             return;
         }
+        // Context7 setup
+        this.context7Enabled = await this.promptContext7();
+        if (this.context7Enabled) {
+            console.log(chalk.dim(m.init.context7Enabled));
+        }
+        console.log('');
         // Generate skill files for each tool
         for (const tool of selectedTools) {
             if (!tool.skillsDir)
@@ -79,6 +97,21 @@ export class InitCommand {
         console.log(cmd(chalk.cyan('/learn:review [topic-name]'), chalk.dim('    — Review progress, spaced repetition recommendations')));
         console.log(cmd(chalk.cyan('/learn:status [topic-name]'), chalk.dim('    — Visualize learning state as knowledge map heatmap')));
         console.log('');
+        if (this.context7Enabled) {
+            console.log(chalk.dim(m.init.context7SetupHint));
+            console.log('');
+        }
+    }
+    async promptContext7() {
+        const m = getMessages(this.locale);
+        if (this.context7Arg === true)
+            return true;
+        if (this.context7Arg === false)
+            return false;
+        if (!isInteractive())
+            return true;
+        const { confirm } = await import('@inquirer/prompts');
+        return confirm({ message: m.init.context7Prompt, default: true });
     }
     async detectTools(_resolvedPath) {
         return AI_TOOLS;
@@ -117,10 +150,31 @@ export class InitCommand {
         for (const entry of skillTemplates) {
             const skillDir = path.join(resolvedPath, tool.skillsDir, 'skills', entry.dirName);
             const skillFile = path.join(skillDir, 'SKILL.md');
-            const content = generateSkillContent(entry.template, VERSION);
+            const content = generateSkillContent(entry.template, VERSION, this.context7Enabled && isDocVerificationTemplate(entry.workflowId)
+                ? injectContext7Guidance
+                : undefined);
             await FileSystemUtils.writeFile(skillFile, content);
+            const scriptsDir = path.join(skillDir, 'scripts');
+            // topic / explain / practice → utils.mjs + render.mjs
+            if (entry.dirName === 'learn-anything-topic' ||
+                entry.dirName === 'learn-anything-explain' ||
+                entry.dirName === 'learn-anything-practice') {
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'utils.mjs'), this.readCompiledScript('utils.mjs'));
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'render.mjs'), this.readCompiledScript('render.mjs'));
+            }
+            // status → utils.mjs + status.mjs
+            if (entry.dirName === 'learn-anything-status') {
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'utils.mjs'), this.readCompiledScript('utils.mjs'));
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'status.mjs'), this.readCompiledScript('status.mjs'));
+            }
+            // review → no scripts needed
         }
     }
+    /** Read a compiled script from dist/scripts/ (bundled alongside this module). */
+    readCompiledScript(filename) {
+        const scriptPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'scripts', filename);
+        return fs.readFileSync(scriptPath, 'utf-8');
+    }
     async generateCommandsForTool(resolvedPath, tool) {
         const adapter = CommandAdapterRegistry.get(tool.value);
         if (!adapter)
@@ -133,4 +187,15 @@ export class InitCommand {
         }
     }
 }
+const DOC_VERIFICATION_WORKFLOWS = new Set(['topic', 'explain', 'practice']);
+function isDocVerificationTemplate(workflowId) {
+    return DOC_VERIFICATION_WORKFLOWS.has(workflowId);
+}
+function injectContext7Guidance(instructions) {
+    const marker = '\n## Command:';
+    const index = instructions.indexOf(marker);
+    if (index === -1)
+        return instructions + CONTEXT7_GUIDANCE;
+    return instructions.slice(0, index) + CONTEXT7_GUIDANCE + instructions.slice(index);
+}
 //# sourceMappingURL=init.js.map

package/dist/core/learn-protocol/index.d.ts

@@ -0,0 +1,8 @@
+export type { ConceptStatus, Concept, Domain, StateV1, Detail, V0Concept, V0State, ParsedConcept, ParsedDomain, ParsedKnowledgeMap, } from './types.js';
+export { stateV1Schema, validateStateV1 } from './schema.js';
+export type { StateV1Schema, ValidationResult } from './schema.js';
+export { generateSlug } from './slug.js';
+export { parseKnowledgeMap } from './parser.js';
+export { isV0State, migrateV0ToV1, migrateAll } from './migrate.js';
+export type { MigrationResult, MigrationReport } from './migrate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/learn-protocol/index.js

@@ -0,0 +1,5 @@
+export { stateV1Schema, validateStateV1 } from './schema.js';
+export { generateSlug } from './slug.js';
+export { parseKnowledgeMap } from './parser.js';
+export { isV0State, migrateV0ToV1, migrateAll } from './migrate.js';
+//# sourceMappingURL=index.js.map

package/dist/core/learn-protocol/migrate.d.ts

@@ -0,0 +1,52 @@
+/**
+ * v0 -> v1 migration logic.
+ *
+ * Detects v0 state.yaml format and merges it with knowledge-map.md
+ * to produce a state.json v1 file. Migration is idempotent and
+ * creates .bak backups before writing.
+ *
+ * Migration chain:
+ *   state.yaml (v0) + knowledge-map.md (v0)
+ *     -> migrateV0ToV1()
+ *       -> state.json (v1) + state.yaml.v0.bak + knowledge-map.md.v0.bak
+ */
+import type { V0State } from './types.js';
+/**
+ * Check if a parsed YAML object matches the v0 state format.
+ *
+ * v0 is identified by having `topic` and `concepts` fields but
+ * NO `version` field. Returns `true` when the data matches v0.
+ */
+export declare function isV0State(data: unknown): data is V0State;
+export interface MigrationResult {
+    migrated: boolean;
+    topic: string;
+    reason?: 'already_migrated' | 'already_v1' | 'not_v0' | 'no_state_yaml' | 'error';
+    error?: string;
+}
+export interface MigrationReport {
+    migratedCount: number;
+    skippedCount: number;
+    results: MigrationResult[];
+}
+/**
+ * Migrate a single topic directory from v0 to v1.
+ *
+ * Reads `state.yaml` and `knowledge-map.md`, merges them into `state.json`,
+ * and creates `.bak` backup files. Idempotent — skips if already migrated.
+ *
+ * @param topicDir — Absolute path to the topic directory (e.g. `.learn/topics/javascript`)
+ * @returns A MigrationResult describing what happened
+ */
+export declare function migrateV0ToV1(topicDir: string): Promise<MigrationResult>;
+/**
+ * Migrate ALL topics under a base directory from v0 to v1.
+ *
+ * Scans `.learn/topics/` for topic subdirectories and runs
+ * migrateV0ToV1 on each one. Returns a summary report.
+ *
+ * @param baseDir — Path to the topics directory (e.g. `.learn/topics`)
+ * @returns MigrationReport with counts and per-topic results
+ */
+export declare function migrateAll(baseDir: string): Promise<MigrationReport>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/core/learn-protocol/migrate.js

@@ -0,0 +1,259 @@
+/**
+ * v0 -> v1 migration logic.
+ *
+ * Detects v0 state.yaml format and merges it with knowledge-map.md
+ * to produce a state.json v1 file. Migration is idempotent and
+ * creates .bak backups before writing.
+ *
+ * Migration chain:
+ *   state.yaml (v0) + knowledge-map.md (v0)
+ *     -> migrateV0ToV1()
+ *       -> state.json (v1) + state.yaml.v0.bak + knowledge-map.md.v0.bak
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { parseKnowledgeMap } from './parser.js';
+import { generateSlug } from './slug.js';
+import { stateV1Schema } from './schema.js';
+import { render } from '../../scripts/render.mjs';
+import { FileSystemUtils } from '../../utils/file-system.js';
+// ---- Public API ---------------------------------------------------------
+/**
+ * Check if a parsed YAML object matches the v0 state format.
+ *
+ * v0 is identified by having `topic` and `concepts` fields but
+ * NO `version` field. Returns `true` when the data matches v0.
+ */
+export function isV0State(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const obj = data;
+    // v0: has topic (string) and concepts (array), no version field
+    if (typeof obj.topic !== 'string' || !obj.topic)
+        return false;
+    if (!Array.isArray(obj.concepts))
+        return false;
+    if (obj.version !== undefined)
+        return false;
+    return true;
+}
+/**
+ * Migrate a single topic directory from v0 to v1.
+ *
+ * Reads `state.yaml` and `knowledge-map.md`, merges them into `state.json`,
+ * and creates `.bak` backup files. Idempotent — skips if already migrated.
+ *
+ * @param topicDir — Absolute path to the topic directory (e.g. `.learn/topics/javascript`)
+ * @returns A MigrationResult describing what happened
+ */
+export async function migrateV0ToV1(topicDir) {
+    const stateYamlPath = path.join(topicDir, 'state.yaml');
+    const knowledgeMapPath = path.join(topicDir, 'knowledge-map.md');
+    const stateJsonPath = path.join(topicDir, 'state.json');
+    const stateYamlBackup = path.join(topicDir, 'state.yaml.v0.bak');
+    const knowledgeMapBackup = path.join(topicDir, 'knowledge-map.md.v0.bak');
+    // 1. Skip if state.json already exists (already migrated)
+    if (await FileSystemUtils.fileExists(stateJsonPath)) {
+        try {
+            const existing = JSON.parse(await fs.readFile(stateJsonPath, 'utf-8'));
+            return {
+                migrated: false,
+                topic: existing.topic || path.basename(topicDir),
+                reason: 'already_migrated',
+            };
+        }
+        catch {
+            return {
+                migrated: false,
+                topic: path.basename(topicDir),
+                reason: 'already_migrated',
+            };
+        }
+    }
+    // 2. Check state.yaml exists
+    if (!(await FileSystemUtils.fileExists(stateYamlPath))) {
+        return {
+            migrated: false,
+            topic: path.basename(topicDir),
+            reason: 'no_state_yaml',
+        };
+    }
+    // 3. Read and parse state.yaml
+    let v0Data;
+    try {
+        const yamlContent = await fs.readFile(stateYamlPath, 'utf-8');
+        v0Data = parseYaml(yamlContent);
+    }
+    catch (err) {
+        return {
+            migrated: false,
+            topic: path.basename(topicDir),
+            reason: 'error',
+            error: `Failed to parse state.yaml: ${err.message}`,
+        };
+    }
+    // 4. Check v0 format (has topic + concepts, no version field)
+    if (!isV0State(v0Data)) {
+        return {
+            migrated: false,
+            topic: path.basename(topicDir),
+            reason: 'not_v0',
+        };
+    }
+    const v0State = v0Data;
+    // 7. Read and parse knowledge-map.md
+    let parsedMap;
+    if (await FileSystemUtils.fileExists(knowledgeMapPath)) {
+        try {
+            const kmContent = await fs.readFile(knowledgeMapPath, 'utf-8');
+            parsedMap = parseKnowledgeMap(kmContent);
+        }
+        catch (err) {
+            return {
+                migrated: false,
+                topic: v0State.topic,
+                reason: 'error',
+                error: `Failed to parse knowledge-map.md: ${err.message}`,
+            };
+        }
+    }
+    else {
+        // Without knowledge-map.md we can't build the hierarchy; skip
+        return {
+            migrated: false,
+            topic: v0State.topic,
+            reason: 'error',
+            error: 'knowledge-map.md not found',
+        };
+    }
+    // 8. Merge: build a lookup from v0 path -> V0Concept
+    const conceptLookup = new Map();
+    for (const c of v0State.concepts) {
+        conceptLookup.set(c.path, c);
+    }
+    // 9. Build StateV1 from parsed hierarchy + v0 state data
+    const domains = parsedMap.domains.map((pd) => ({
+        name: pd.name,
+        slug: generateSlug(pd.name),
+        concepts: pd.concepts.map((pc) => {
+            const v0Path = `${pd.name}/${pc.name}`;
+            const v0Concept = conceptLookup.get(v0Path);
+            return {
+                name: pc.name,
+                slug: generateSlug(pc.name),
+                status: mapStatus(v0Concept?.status),
+                confidence: v0Concept?.confidence ?? 0,
+                practice_count: v0Concept?.practice_count ?? 0,
+                explain_count: v0Concept?.explain_count ?? 0,
+                last_explained: v0Concept?.last_session ?? null,
+                last_practiced: v0Concept?.last_practiced ?? null,
+                details: pc.children,
+            };
+        }),
+    }));
+    const stateV1 = {
+        version: 1,
+        topic: v0State.topic,
+        slug: generateSlug(v0State.topic),
+        created: v0State.created,
+        domains,
+    };
+    // 10. Validate the generated state against the schema
+    const validation = stateV1Schema.safeParse(stateV1);
+    if (!validation.success) {
+        return {
+            migrated: false,
+            topic: v0State.topic,
+            reason: 'error',
+            error: `Generated state.json failed validation: ${validation.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`,
+        };
+    }
+    // 11. Write state.json
+    try {
+        await FileSystemUtils.writeFile(stateJsonPath, JSON.stringify(stateV1, null, 2) + '\n');
+    }
+    catch (err) {
+        return {
+            migrated: false,
+            topic: v0State.topic,
+            reason: 'error',
+            error: `Failed to write state.json: ${err.message}`,
+        };
+    }
+    // 12. Create backup files, then remove originals
+    //     After migration, state.json is the single source of truth,
+    //     so the v0 files should not remain alongside it.
+    try {
+        await fs.copyFile(stateYamlPath, stateYamlBackup);
+        await fs.copyFile(knowledgeMapPath, knowledgeMapBackup);
+        await fs.rm(stateYamlPath, { force: true });
+        await fs.rm(knowledgeMapPath, { force: true });
+    }
+    catch (err) {
+        // Backup/cleanup failure is non-fatal — state.json was already written
+        console.error(`Warning: Failed to create backup files or clean up originals in ${topicDir}: ${err.message}`);
+    }
+    // 13. Regenerate knowledge-map.md from state.json (v1 format)
+    try {
+        const rendered = render(stateV1);
+        await FileSystemUtils.writeFile(knowledgeMapPath, rendered);
+    }
+    catch (err) {
+        // Render failure is non-fatal — migration itself succeeded
+        console.error(`Warning: Failed to regenerate knowledge-map.md in ${topicDir}: ${err.message}`);
+    }
+    return {
+        migrated: true,
+        topic: v0State.topic,
+    };
+}
+/**
+ * Migrate ALL topics under a base directory from v0 to v1.
+ *
+ * Scans `.learn/topics/` for topic subdirectories and runs
+ * migrateV0ToV1 on each one. Returns a summary report.
+ *
+ * @param baseDir — Path to the topics directory (e.g. `.learn/topics`)
+ * @returns MigrationReport with counts and per-topic results
+ */
+export async function migrateAll(baseDir) {
+    const results = [];
+    let entryNames;
+    try {
+        entryNames = await fs.readdir(baseDir);
+    }
+    catch {
+        // Directory doesn't exist — nothing to migrate
+        return { migratedCount: 0, skippedCount: 0, results: [] };
+    }
+    // Check each entry to see if it's a directory
+    const topicDirs = [];
+    for (const name of entryNames) {
+        const fullPath = path.join(baseDir, name);
+        try {
+            const stat = await fs.stat(fullPath);
+            if (stat.isDirectory())
+                topicDirs.push(fullPath);
+        }
+        catch {
+            // Skip entries we can't stat
+        }
+    }
+    for (const dir of topicDirs) {
+        const result = await migrateV0ToV1(dir);
+        results.push(result);
+    }
+    const migratedCount = results.filter((r) => r.migrated).length;
+    const skippedCount = results.filter((r) => !r.migrated).length;
+    return { migratedCount, skippedCount, results };
+}
+// ---- Helpers -----------------------------------------------------------
+/** Map v0 status string to v1 ConceptStatus; default to 'unexplored'. */
+function mapStatus(status) {
+    if (status === 'in_progress' || status === 'needs_practice' || status === 'mastered') {
+        return status;
+    }
+    return 'unexplored';
+}
+//# sourceMappingURL=migrate.js.map

package/dist/core/learn-protocol/parser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Markdown parser for v0 knowledge-map.md.
+ *
+ * Uses unified + remark-parse to extract the hierarchical structure
+ * (domains -> concepts -> details) from the v0 knowledge-map format.
+ *
+ * This is used ONLY during migration (init/update), not at AI runtime.
+ *
+ * v0 knowledge-map.md format:
+ *
+ * ```md
+ * # Topic Name
+ * ## Domain 1
+ * - Concept A
+ *   - Detail A1
+ *   - Detail A2
+ * - Concept B
+ * ## Domain 2
+ * - Concept C
+ * ```
+ */
+import type { ParsedKnowledgeMap } from './types.js';
+/**
+ * Parse a v0 knowledge-map.md file content into a structured representation.
+ *
+ * The parser walks the mdast tree:
+ * - `# Title` (h1) -> topic name
+ * - `## DomainName` (h2) -> start a new domain
+ * - `- Concept` (top-level list item) -> add concept to current domain
+ * - `  - Detail` (nested list item) -> add detail to preceding concept
+ */
+export declare function parseKnowledgeMap(markdown: string): ParsedKnowledgeMap;
+//# sourceMappingURL=parser.d.ts.map