learn-anything-cli 0.2.1 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # Learn Anything
 
+[English](./README.md) | [中文](./README.zh-CN.md)
+
 AI-powered recursive learning system — turns your AI coding assistant into an interactive tutor using the Socratic method and TDD-style exercises.
 
 Generate skill and command files for **30+ AI tools** (Claude Code, Cursor, Gemini CLI, Codex, Copilot, Windsurf, etc.), then use slash commands to systematically master any technical topic.

package/dist/cli/index.js

@@ -43,7 +43,7 @@ program
                 throw error;
             }
             else {
-                throw new Error(mc.cannotAccess(targetPath, error.message));
+                throw new Error(mc.cannotAccess(targetPath, error.message), { cause: error });
             }
         }
         const { InitCommand } = await import('../core/init.js');

package/dist/core/command-generation/registry.js

@@ -1,4 +1,4 @@
-import { claudeAdapter, cursorAdapter, codexAdapter, geminiAdapter, } from './adapters/index.js';
+import { claudeAdapter, cursorAdapter, codexAdapter, geminiAdapter } from './adapters/index.js';
 export class CommandAdapterRegistry {
     static adapters = new Map();
     static {

package/dist/core/config.js

@@ -1,33 +1,161 @@
 export const LEARN_DIR = '.learn';
 export const AI_TOOLS = [
-    { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq' },
-    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent' },
-    { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie', skillsDir: '.augment' },
-    { name: 'Bob Shell', value: 'bob', available: true, successLabel: 'Bob Shell', skillsDir: '.bob' },
-    { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code', skillsDir: '.claude' },
+    {
+        name: 'Amazon Q Developer',
+        value: 'amazon-q',
+        available: true,
+        successLabel: 'Amazon Q Developer',
+        skillsDir: '.amazonq',
+    },
+    {
+        name: 'Antigravity',
+        value: 'antigravity',
+        available: true,
+        successLabel: 'Antigravity',
+        skillsDir: '.agent',
+    },
+    {
+        name: 'Auggie (Augment CLI)',
+        value: 'auggie',
+        available: true,
+        successLabel: 'Auggie',
+        skillsDir: '.augment',
+    },
+    {
+        name: 'Bob Shell',
+        value: 'bob',
+        available: true,
+        successLabel: 'Bob Shell',
+        skillsDir: '.bob',
+    },
+    {
+        name: 'Claude Code',
+        value: 'claude',
+        available: true,
+        successLabel: 'Claude Code',
+        skillsDir: '.claude',
+    },
     { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline' },
     { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex', skillsDir: '.codex' },
-    { name: 'ForgeCode', value: 'forgecode', available: true, successLabel: 'ForgeCode', skillsDir: '.forge' },
-    { name: 'CodeBuddy Code (CLI)', value: 'codebuddy', available: true, successLabel: 'CodeBuddy Code', skillsDir: '.codebuddy' },
-    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue' },
-    { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec' },
+    {
+        name: 'ForgeCode',
+        value: 'forgecode',
+        available: true,
+        successLabel: 'ForgeCode',
+        skillsDir: '.forge',
+    },
+    {
+        name: 'CodeBuddy Code (CLI)',
+        value: 'codebuddy',
+        available: true,
+        successLabel: 'CodeBuddy Code',
+        skillsDir: '.codebuddy',
+    },
+    {
+        name: 'Continue',
+        value: 'continue',
+        available: true,
+        successLabel: 'Continue (VS Code / JetBrains / Cli)',
+        skillsDir: '.continue',
+    },
+    {
+        name: 'CoStrict',
+        value: 'costrict',
+        available: true,
+        successLabel: 'CoStrict',
+        skillsDir: '.cospec',
+    },
     { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush', skillsDir: '.crush' },
-    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor' },
-    { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid', skillsDir: '.factory' },
-    { name: 'Gemini CLI', value: 'gemini', available: true, successLabel: 'Gemini CLI', skillsDir: '.gemini' },
-    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github', detectionPaths: ['.github/copilot-instructions.md', '.github/instructions', '.github/workflows/copilot-setup-steps.yml', '.github/prompts', '.github/agents', '.github/skills', '.github/.mcp.json'] },
+    {
+        name: 'Cursor',
+        value: 'cursor',
+        available: true,
+        successLabel: 'Cursor',
+        skillsDir: '.cursor',
+    },
+    {
+        name: 'Factory Droid',
+        value: 'factory',
+        available: true,
+        successLabel: 'Factory Droid',
+        skillsDir: '.factory',
+    },
+    {
+        name: 'Gemini CLI',
+        value: 'gemini',
+        available: true,
+        successLabel: 'Gemini CLI',
+        skillsDir: '.gemini',
+    },
+    {
+        name: 'GitHub Copilot',
+        value: 'github-copilot',
+        available: true,
+        successLabel: 'GitHub Copilot',
+        skillsDir: '.github',
+        detectionPaths: [
+            '.github/copilot-instructions.md',
+            '.github/instructions',
+            '.github/workflows/copilot-setup-steps.yml',
+            '.github/prompts',
+            '.github/agents',
+            '.github/skills',
+            '.github/.mcp.json',
+        ],
+    },
     { name: 'iFlow', value: 'iflow', available: true, successLabel: 'iFlow', skillsDir: '.iflow' },
     { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie' },
-    { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code', skillsDir: '.kilocode' },
+    {
+        name: 'Kilo Code',
+        value: 'kilocode',
+        available: true,
+        successLabel: 'Kilo Code',
+        skillsDir: '.kilocode',
+    },
     { name: 'Kiro', value: 'kiro', available: true, successLabel: 'Kiro', skillsDir: '.kiro' },
-    { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode', skillsDir: '.opencode' },
+    {
+        name: 'OpenCode',
+        value: 'opencode',
+        available: true,
+        successLabel: 'OpenCode',
+        skillsDir: '.opencode',
+    },
     { name: 'Pi', value: 'pi', available: true, successLabel: 'Pi', skillsDir: '.pi' },
     { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder' },
-    { name: 'Lingma', value: 'lingma', available: true, successLabel: 'Lingma', skillsDir: '.lingma' },
-    { name: 'Qwen Code', value: 'qwen', available: true, successLabel: 'Qwen Code', skillsDir: '.qwen' },
-    { name: 'RooCode', value: 'roocode', available: true, successLabel: 'RooCode', skillsDir: '.roo' },
+    {
+        name: 'Lingma',
+        value: 'lingma',
+        available: true,
+        successLabel: 'Lingma',
+        skillsDir: '.lingma',
+    },
+    {
+        name: 'Qwen Code',
+        value: 'qwen',
+        available: true,
+        successLabel: 'Qwen Code',
+        skillsDir: '.qwen',
+    },
+    {
+        name: 'RooCode',
+        value: 'roocode',
+        available: true,
+        successLabel: 'RooCode',
+        skillsDir: '.roo',
+    },
     { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae', skillsDir: '.trae' },
-    { name: 'Windsurf', value: 'windsurf', available: true, successLabel: 'Windsurf', skillsDir: '.windsurf' },
-    { name: 'AGENTS.md (works with Amp, VS Code, …)', value: 'agents', available: false, successLabel: 'your AGENTS.md-compatible assistant' },
+    {
+        name: 'Windsurf',
+        value: 'windsurf',
+        available: true,
+        successLabel: 'Windsurf',
+        skillsDir: '.windsurf',
+    },
+    {
+        name: 'AGENTS.md (works with Amp, VS Code, …)',
+        value: 'agents',
+        available: false,
+        successLabel: 'your AGENTS.md-compatible assistant',
+    },
 ];
 //# sourceMappingURL=config.js.map

package/dist/core/init.js

@@ -5,8 +5,8 @@ import { createRequire } from 'module';
 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 { generateCommands, CommandAdapterRegistry } from './command-generation/index.js';
+import { getSkillTemplates, getCommandContents, generateSkillContent } from './shared/index.js';
 import { getMessages } from '../i18n/index.js';
 const require = createRequire(import.meta.url);
 const { version: VERSION } = require('../../package.json');
@@ -53,7 +53,10 @@ export class InitCommand {
         }
         if (selectedTools.length === 0) {
             console.log(chalk.yellow(m.init.noToolsSelected));
-            console.log(chalk.dim(m.init.availableTools(availableTools.filter((t) => t.available).map((t) => t.value).join(', '))));
+            console.log(chalk.dim(m.init.availableTools(availableTools
+                .filter((t) => t.available)
+                .map((t) => t.value)
+                .join(', '))));
             return;
         }
         // Generate skill files for each tool
@@ -77,7 +80,7 @@ export class InitCommand {
         console.log(cmd(chalk.cyan('/learn:status [topic-name]'), chalk.dim('    — Visualize learning state as knowledge map heatmap')));
         console.log('');
     }
-    async detectTools(resolvedPath) {
+    async detectTools(_resolvedPath) {
         return AI_TOOLS;
     }
     hasToolDir(resolvedPath, tool) {
@@ -93,7 +96,7 @@ export class InitCommand {
     }
     async interactiveSelect(tools) {
         const availableTools = tools.filter((t) => t.available && t.skillsDir);
-        const { search, checkbox } = await import('@inquirer/prompts');
+        const { checkbox } = await import('@inquirer/prompts');
         // Auto-detect existing tool dirs and pre-select them
         const detected = availableTools.filter((t) => this.hasToolDir(process.cwd(), t));
         const detectedValues = new Set(detected.map((t) => t.value));

package/dist/core/shared/skill-generation.js

@@ -1,11 +1,31 @@
 import { getLearnTopicSkillTemplate, getLearnExplainSkillTemplate, getLearnPracticeSkillTemplate, getLearnReviewSkillTemplate, getLearnStatusSkillTemplate, getLearnTopicCommandTemplate, getLearnExplainCommandTemplate, getLearnPracticeCommandTemplate, getLearnReviewCommandTemplate, getLearnStatusCommandTemplate, } from '../templates/skill-templates.js';
 export function getSkillTemplates() {
     return [
-        { template: getLearnTopicSkillTemplate(), dirName: 'learn-anything-topic', workflowId: 'topic' },
-        { template: getLearnExplainSkillTemplate(), dirName: 'learn-anything-explain', workflowId: 'explain' },
-        { template: getLearnPracticeSkillTemplate(), dirName: 'learn-anything-practice', workflowId: 'practice' },
-        { template: getLearnReviewSkillTemplate(), dirName: 'learn-anything-review', workflowId: 'review' },
-        { template: getLearnStatusSkillTemplate(), dirName: 'learn-anything-status', workflowId: 'status' },
+        {
+            template: getLearnTopicSkillTemplate(),
+            dirName: 'learn-anything-topic',
+            workflowId: 'topic',
+        },
+        {
+            template: getLearnExplainSkillTemplate(),
+            dirName: 'learn-anything-explain',
+            workflowId: 'explain',
+        },
+        {
+            template: getLearnPracticeSkillTemplate(),
+            dirName: 'learn-anything-practice',
+            workflowId: 'practice',
+        },
+        {
+            template: getLearnReviewSkillTemplate(),
+            dirName: 'learn-anything-review',
+            workflowId: 'review',
+        },
+        {
+            template: getLearnStatusSkillTemplate(),
+            dirName: 'learn-anything-status',
+            workflowId: 'status',
+        },
     ];
 }
 export function getCommandTemplates() {

package/dist/core/templates/skill-templates.d.ts

@@ -1,7 +1,7 @@
 export type { SkillTemplate, CommandTemplate } from './types.js';
-export { getLearnTopicSkillTemplate, getLearnTopicCommandTemplate } from './workflows/learn-topic.js';
-export { getLearnExplainSkillTemplate, getLearnExplainCommandTemplate } from './workflows/learn-explain.js';
-export { getLearnPracticeSkillTemplate, getLearnPracticeCommandTemplate } from './workflows/learn-practice.js';
-export { getLearnReviewSkillTemplate, getLearnReviewCommandTemplate } from './workflows/learn-review.js';
-export { getLearnStatusSkillTemplate, getLearnStatusCommandTemplate } from './workflows/learn-status.js';
+export { getLearnTopicSkillTemplate, getLearnTopicCommandTemplate, } from './workflows/learn-topic.js';
+export { getLearnExplainSkillTemplate, getLearnExplainCommandTemplate, } from './workflows/learn-explain.js';
+export { getLearnPracticeSkillTemplate, getLearnPracticeCommandTemplate, } from './workflows/learn-practice.js';
+export { getLearnReviewSkillTemplate, getLearnReviewCommandTemplate, } from './workflows/learn-review.js';
+export { getLearnStatusSkillTemplate, getLearnStatusCommandTemplate, } from './workflows/learn-status.js';
 //# sourceMappingURL=skill-templates.d.ts.map

package/dist/core/templates/skill-templates.js

@@ -1,6 +1,6 @@
-export { getLearnTopicSkillTemplate, getLearnTopicCommandTemplate } from './workflows/learn-topic.js';
-export { getLearnExplainSkillTemplate, getLearnExplainCommandTemplate } from './workflows/learn-explain.js';
-export { getLearnPracticeSkillTemplate, getLearnPracticeCommandTemplate } from './workflows/learn-practice.js';
-export { getLearnReviewSkillTemplate, getLearnReviewCommandTemplate } from './workflows/learn-review.js';
-export { getLearnStatusSkillTemplate, getLearnStatusCommandTemplate } from './workflows/learn-status.js';
+export { getLearnTopicSkillTemplate, getLearnTopicCommandTemplate, } from './workflows/learn-topic.js';
+export { getLearnExplainSkillTemplate, getLearnExplainCommandTemplate, } from './workflows/learn-explain.js';
+export { getLearnPracticeSkillTemplate, getLearnPracticeCommandTemplate, } from './workflows/learn-practice.js';
+export { getLearnReviewSkillTemplate, getLearnReviewCommandTemplate, } from './workflows/learn-review.js';
+export { getLearnStatusSkillTemplate, getLearnStatusCommandTemplate, } from './workflows/learn-status.js';
 //# sourceMappingURL=skill-templates.js.map

package/dist/core/templates/workflows/learn-explain.js

@@ -93,7 +93,7 @@ Synthesize these signals to judge whether the user is beginner, intermediate, or
 
 ### Step 4: Record Learning Session
 
-⚠️ CRITICAL — Do this in the SAME turn as your explanation, BEFORE presenting sub-topics. Do NOT skip this step.
+⚠️ CRITICAL — Write the session file FIRST, then output its content to the conversation. This ensures zero drift between what the user sees and what gets saved. Do this BEFORE presenting sub-topics (Step 5).
 
 **A) Determine the filename:**
 
@@ -108,9 +108,11 @@ Examples:
 
 Match the language the user is learning in — don't force-translate.
 
-**B) Save the FULL explanation — use the Write tool:**
+**B) Compose then WRITE the session file FIRST — use the Write tool:**
 
-The session file must contain the COMPLETE explanation you just delivered — not just bullet points. The user should be able to re-read this file and get the full learning experience without looking at the chat.
+Compose your COMPLETE explanation (positioning, analogy, core mechanism, code example with walkthrough, misconceptions, Socratic check, and quick summary). The user should be able to re-read this file and get the full learning experience without looking at the chat.
+
+Write this content to the session file FIRST, before outputting anything to the conversation.
 
 \`\`\`markdown
 # [Concept Name] — Learning Session
@@ -124,31 +126,31 @@ The session file must contain the COMPLETE explanation you just delivered — no
 
 ## Positioning
 
-[Copy the one-sentence positioning you gave — where this concept sits in the knowledge map]
+[Write the one-sentence positioning — where this concept sits in the knowledge map]
 
 ## Analogy
 
-[Copy the real-world metaphor/analogy you used]
+[Write the real-world metaphor/analogy you composed]
 
 ## Core Mechanism
 
-[Copy the full "what and why" explanation in clear language, with all details]
+[Write the full "what and why" explanation in clear language, with all details]
 
 ## Code Example
 
 \`\`\`[language]
-[Copy the complete code example you showed, with all comments]
+[Write the complete code example, with all comments]
 \`\`\`
 
 [Include your walkthrough of the code — what each part does]
 
 ## Common Misconceptions
 
-[Copy the misconceptions you discussed]
+[Write the misconceptions you identified]
 
 ## Socratic Check
 
-[Copy the thinking questions you posed to the user]
+[Write the thinking questions you composed]
 
 ---
 
@@ -163,9 +165,13 @@ The session file must contain the COMPLETE explanation you just delivered — no
 (Will be updated after the user chooses a sub-topic direction)
 \`\`\`
 
-**C) Update state.yaml — use the Edit tool:**
+**C) Output the file content to the conversation:**
+
+After writing the session file, present the EXACT content of the file you just wrote as your conversation response. Do NOT rephrase or regenerate — copy the file content verbatim into your message. Only after echoing the file content, proceed to Step 5 (identify sub-topics).
+
+**D) Update state.yaml — use the Edit tool:**
 
-Edit \`./.learn/topics/<topic-name>/state.yaml\`:
+In the same turn, also use the Edit tool to update \`./.learn/topics/<topic-name>/state.yaml\`:
 - If concept status is \`unexplored\`, update to \`in_progress\`
 - Update \`last_session\` to current date
 - If the user showed good understanding, increase \`confidence\` by 0.05 to 0.1
@@ -229,9 +235,9 @@ const COMMAND_CONTENT = `Use the learn-anything-explain skill to handle the user
 Follow the workflow defined in the skill:
 1. Load context: match topic → read knowledge map → read learning state
 2. Assess user level (beginner/intermediate/advanced) and adjust teaching strategy
-3. Follow the explanation structure: positioning → analogy → core mechanism → code example → common misconceptions → Socratic check
-4. CRITICAL — in the same turn as your explanation, use the Write tool to save the FULL explanation to ./.learn/topics/<topic>/sessions/<concept-name>-YYYY-MM-DD.md (match the user's language), use the Edit tool to update state.yaml
-5. Identify sub-topics as recursive entry points (only AFTER saving the session)`;
+3. Compose the full explanation: positioning → analogy → core mechanism → code example → common misconceptions → Socratic check
+4. CRITICAL — Write the session file FIRST (./.learn/topics/<topic>/sessions/<concept-name>-YYYY-MM-DD.md, matching the user's language), then echo the file content verbatim to the conversation. Also update state.yaml with Edit.
+5. Identify sub-topics as recursive entry points (only AFTER saving the session and echoing to conversation)`;
 export function getLearnExplainSkillTemplate() {
     return {
         name: SKILL_NAME,

package/dist/core/templates/workflows/learn-practice.js

@@ -310,9 +310,11 @@ The user submits their code or answer in the chat. Review it using the framework
    - Set status to needs_practice
    - Note specific areas to focus on
 
-**In the same turn as your feedback**, save the session record. ⚠️ Do NOT wait for the user's next message — feedback text and file writes must happen together.
+⚠️ CRITICAL — Write the session file FIRST, then echo its content to the conversation. This ensures zero drift between what the user sees and what gets saved.
 
-- Use the Write tool to create \`./.learn/topics/<topic-name>/sessions/<concept-name>-practice-YYYY-MM-DD.md\` — match the user's language (see Step 5 for naming rules and format)
+1. **Write the session file** — Use the Write tool to create \`./.learn/topics/<topic-name>/sessions/<concept-name>-practice-YYYY-MM-DD.md\` with the full feedback content (see Step 5 for naming rules and format). Include everything: your acknowledgment, Socratic follow-up questions, edge case discussion, code quality tips, and final assessment.
+
+2. **Output the file content to the conversation** — After writing, present the exact content of the file you just wrote as your conversation response. Do NOT rephrase or regenerate it — copy the file content verbatim into your message.
 
 ### Step 5: Practice Session Record Format
 
@@ -375,8 +377,8 @@ Follow the workflow defined in the skill:
 2. Assess difficulty level based on state.yaml (beginner/intermediate/challenge)
 3. Project Mode: use Bash to create exercise dir → use Write to create README.md + starter file → tell user to open in IDE
    Chat Mode: generate exercise in chat (background → requirements → code template → hint)
-4. Project Mode: use Read to review user's code file → optionally use Bash to run it → provide structured feedback, and in the same turn use Write to save session record + Edit to update state.yaml
-   Chat Mode: review code submitted in chat → provide structured feedback, and in the same turn use Write to save session record + Edit to update state.yaml`;
+4. Project Mode: use Read to review user's code file → optionally use Bash to run it → compose feedback → Write session file FIRST → echo file content verbatim to conversation + Edit to update state.yaml
+   Chat Mode: review code submitted in chat → compose feedback → Write session file FIRST → echo file content verbatim to conversation + Edit to update state.yaml`;
 export function getLearnPracticeSkillTemplate() {
     return {
         name: SKILL_NAME,

package/dist/i18n/index.js

@@ -8,10 +8,7 @@ export function getMessages(locale) {
     return messages[locale];
 }
 export function detectSystemLocale() {
-    const langEnv = process.env.LANG ||
-        process.env.LC_ALL ||
-        process.env.LANGUAGE ||
-        '';
+    const langEnv = process.env.LANG || process.env.LC_ALL || process.env.LANGUAGE || '';
     if (/^zh[_-]/i.test(langEnv)) {
         return 'zh-CN';
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learn-anything-cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "AI-powered recursive learning system with Socratic method and TDD practice",
   "keywords": [
     "learn-anything-cli",
@@ -46,14 +46,24 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src/",
-    "prepublishOnly": "pnpm run build"
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "pnpm run build",
+    "prepare": "husky"
   },
   "engines": {
     "node": ">=20.0.0"
   },
   "devDependencies": {
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
+    "@eslint/js": "^10.0.1",
     "@types/node": "^24.2.0",
     "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.7",
+    "prettier": "^3.8.3",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.50.1",
     "vitest": "^3.2.4"
@@ -65,5 +75,14 @@
     "fast-glob": "^3.3.3",
     "yaml": "^2.8.2",
     "zod": "^4.0.17"
+  },
+  "lint-staged": {
+    "*.{ts,js,mjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
   }
 }