learn-anything-cli 0.1.0

package/dist/core/init.js

@@ -0,0 +1,133 @@
+import path from 'path';
+import chalk from 'chalk';
+import * as fs from 'fs';
+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 { getMessages } from '../i18n/index.js';
+const require = createRequire(import.meta.url);
+const { version: VERSION } = require('../../package.json');
+export class InitCommand {
+    toolsArg;
+    force;
+    locale;
+    isUpdate;
+    constructor(options = {}) {
+        this.toolsArg = options.tools;
+        this.force = options.force ?? false;
+        this.locale = options.locale ?? 'en';
+        this.isUpdate = options.update ?? false;
+    }
+    async execute(targetPath = '.') {
+        const resolvedPath = path.resolve(targetPath);
+        const m = getMessages(this.locale);
+        // Ensure target directory exists
+        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'));
+        console.log(chalk.bold(m.init.header));
+        // Detect available tools
+        const availableTools = await this.detectTools(resolvedPath);
+        // Select tools
+        let selectedTools;
+        if (this.toolsArg === 'all') {
+            selectedTools = availableTools.filter((t) => t.available);
+        }
+        else if (this.toolsArg === 'none') {
+            selectedTools = [];
+        }
+        else if (this.toolsArg) {
+            const toolIds = this.toolsArg.split(',').map((t) => t.trim());
+            selectedTools = availableTools.filter((t) => toolIds.includes(t.value));
+        }
+        else if (this.isUpdate || !isInteractive()) {
+            // Update mode or non-interactive: auto-detect existing tool dirs
+            selectedTools = availableTools.filter((t) => t.available && this.hasToolDir(resolvedPath, t));
+        }
+        else {
+            selectedTools = await this.interactiveSelect(availableTools);
+        }
+        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(', '))));
+            return;
+        }
+        // Generate skill files for each tool
+        for (const tool of selectedTools) {
+            if (!tool.skillsDir)
+                continue;
+            await this.generateSkillsForTool(resolvedPath, tool);
+            await this.generateCommandsForTool(resolvedPath, tool);
+            console.log(chalk.green(m.init.skillGenerated(tool.name)));
+        }
+        console.log('');
+        console.log(chalk.bold(m.init.initComplete));
+        console.log(chalk.dim(m.init.globalDataPath(LEARN_DIR)));
+        console.log(chalk.dim(m.init.startLearning('/learn javascript')));
+        console.log(chalk.bold(m.init.availableCommands));
+        const cmd = m.init.cmdLine;
+        console.log(cmd(chalk.cyan('/learn:topic <topic-name>'), chalk.dim('      — Initialize or load a learning topic')));
+        console.log(cmd(chalk.cyan('/learn:explain <concept-name>'), chalk.dim('  — Recursively deep-dive into a concept')));
+        console.log(cmd(chalk.cyan('/learn:practice <concept-name>'), chalk.dim(' — TDD-style coding exercises')));
+        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('');
+    }
+    async detectTools(resolvedPath) {
+        return AI_TOOLS;
+    }
+    hasToolDir(resolvedPath, tool) {
+        if (!tool.skillsDir)
+            return false;
+        const dirPath = path.join(resolvedPath, tool.skillsDir);
+        try {
+            return fs.statSync(dirPath).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+    async interactiveSelect(tools) {
+        const availableTools = tools.filter((t) => t.available && t.skillsDir);
+        const { search, 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));
+        const choices = availableTools.map((t) => ({
+            name: t.name,
+            value: t.value,
+            checked: detectedValues.has(t.value),
+        }));
+        const selected = await checkbox({
+            message: getMessages(this.locale).init.interactiveSelectPrompt,
+            choices,
+            pageSize: 15,
+        });
+        return availableTools.filter((t) => selected.includes(t.value));
+    }
+    async generateSkillsForTool(resolvedPath, tool) {
+        const skillTemplates = getSkillTemplates();
+        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);
+            await FileSystemUtils.writeFile(skillFile, content);
+        }
+    }
+    async generateCommandsForTool(resolvedPath, tool) {
+        const adapter = CommandAdapterRegistry.get(tool.value);
+        if (!adapter)
+            return;
+        const commandContents = getCommandContents();
+        const generatedCommands = generateCommands(commandContents, adapter);
+        for (const cmd of generatedCommands) {
+            const filePath = path.resolve(resolvedPath, cmd.path);
+            await FileSystemUtils.writeFile(filePath, cmd.fileContent);
+        }
+    }
+}
+//# sourceMappingURL=init.js.map

package/dist/core/shared/index.d.ts

@@ -0,0 +1,3 @@
+export { getSkillTemplates, getCommandTemplates, getCommandContents, generateSkillContent, } from './skill-generation.js';
+export type { SkillTemplateEntry, CommandTemplateEntry } from './skill-generation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/shared/index.js

@@ -0,0 +1,2 @@
+export { getSkillTemplates, getCommandTemplates, getCommandContents, generateSkillContent, } from './skill-generation.js';
+//# sourceMappingURL=index.js.map

package/dist/core/shared/skill-generation.d.ts

@@ -0,0 +1,16 @@
+import { getLearnTopicCommandTemplate, type SkillTemplate } from '../templates/skill-templates.js';
+import type { CommandContent } from '../command-generation/index.js';
+export interface SkillTemplateEntry {
+    template: SkillTemplate;
+    dirName: string;
+    workflowId: string;
+}
+export interface CommandTemplateEntry {
+    template: ReturnType<typeof getLearnTopicCommandTemplate>;
+    id: string;
+}
+export declare function getSkillTemplates(): SkillTemplateEntry[];
+export declare function getCommandTemplates(): CommandTemplateEntry[];
+export declare function getCommandContents(): CommandContent[];
+export declare function generateSkillContent(template: SkillTemplate, generatedByVersion: string, transformInstructions?: (instructions: string) => string): string;
+//# sourceMappingURL=skill-generation.d.ts.map

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

@@ -0,0 +1,49 @@
+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' },
+    ];
+}
+export function getCommandTemplates() {
+    return [
+        { template: getLearnTopicCommandTemplate(), id: 'topic' },
+        { template: getLearnExplainCommandTemplate(), id: 'explain' },
+        { template: getLearnPracticeCommandTemplate(), id: 'practice' },
+        { template: getLearnReviewCommandTemplate(), id: 'review' },
+        { template: getLearnStatusCommandTemplate(), id: 'status' },
+    ];
+}
+export function getCommandContents() {
+    const commandTemplates = getCommandTemplates();
+    return commandTemplates.map(({ template, id }) => ({
+        id,
+        name: template.name,
+        description: template.description,
+        category: template.category,
+        tags: template.tags,
+        body: template.content,
+    }));
+}
+export function generateSkillContent(template, generatedByVersion, transformInstructions) {
+    const instructions = transformInstructions
+        ? transformInstructions(template.instructions)
+        : template.instructions;
+    return `---
+name: ${template.name}
+description: ${template.description}
+license: ${template.license || 'MIT'}
+compatibility: ${template.compatibility || 'Requires learn-anything CLI.'}
+metadata:
+  author: ${template.metadata?.author || 'learn-anything'}
+  version: "${template.metadata?.version || '1.0'}"
+  generatedBy: "${generatedByVersion}"
+---
+
+${instructions}
+`;
+}
+//# sourceMappingURL=skill-generation.js.map

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

@@ -0,0 +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';
+//# sourceMappingURL=skill-templates.d.ts.map

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

@@ -0,0 +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';
+//# sourceMappingURL=skill-templates.js.map

package/dist/core/templates/types.d.ts

@@ -0,0 +1,16 @@
+export interface SkillTemplate {
+    name: string;
+    description: string;
+    instructions: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+}
+export interface CommandTemplate {
+    name: string;
+    description: string;
+    category: string;
+    tags: string[];
+    content: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/templates/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/templates/workflows/learn-explain.d.ts

@@ -0,0 +1,4 @@
+import type { SkillTemplate, CommandTemplate } from '../types.js';
+export declare function getLearnExplainSkillTemplate(): SkillTemplate;
+export declare function getLearnExplainCommandTemplate(): CommandTemplate;
+//# sourceMappingURL=learn-explain.d.ts.map

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

@@ -0,0 +1,203 @@
+const SKILL_NAME = 'learn-anything-explain';
+const SKILL_DESCRIPTION = 'Recursively deep-dive into a concept. AI explains, identifies deeper sub-topics, and lets you choose your own depth direction.';
+const INSTRUCTIONS = `Always respond in the same language the user uses.
+If the user speaks Chinese, explain all concepts, examples, and guidance in Chinese.
+
+---
+
+You are Learn Anything's Explanation Mentor. You excel at explaining complex concepts in simple, clear language.
+Your explanations follow the "Recursive Learning Method": first establish a foundation of understanding, then identify deeper sub-topics, letting the user choose whether to go deeper.
+
+## Your Teaching Philosophy
+
+1. **Understanding over Information** — Explaining one concept thoroughly matters more than covering ten superficially
+2. **Analogies Build Intuition** — Every abstract concept should have a real-world analogy
+3. **Socratic Guidance, Not Interrogation** — Questions help users discover answers themselves, not test them
+4. **Know When to Stop** — When the user signals understanding, offer depth options without pushing
+5. **Connect to the Knowledge Map** — Always show where the current concept fits in the broader knowledge system
+
+---
+
+## Command: /learn-explain <concept-name>
+
+### Step 1: Load Context
+
+1. **Match topic**: Infer the parent topic from the concept name.
+   - Look at all directories under \`./.learn/topics/\`
+   - If there's only one topic, use it directly
+   - If there are multiple topics, search knowledge maps for the concept name
+   - If no matching topic is found, ask the user "Which topic would you like to learn this concept under? Available topics: [list]"
+
+2. **Read knowledge map**: Use the Read tool to read \`./.learn/topics/<topic-name>/knowledge-map.md\`, locating the concept's position in the knowledge tree.
+
+3. **Read learning state**: Use the Read tool to read \`./.learn/topics/<topic-name>/state.yaml\`, finding the concept's current status.
+
+### Step 2: Assess User Level
+
+Synthesize these signals to judge whether the user is beginner, intermediate, or advanced:
+
+**Beginner signals:**
+- Short, vague questions (e.g., "What is a closure?")
+- Uses general descriptors ("I don't really get it", "completely lost")
+- Concept status is \`unexplored\`
+- Related concept confidence in state.yaml < 0.3
+
+**Intermediate signals:**
+- Uses some technical terms, though not always precise
+- Questions are targeted ("How do closures cause memory leaks?")
+- Concept status is \`in_progress\`
+- Related concept confidence in state.yaml 0.3-0.7
+
+**Advanced signals:**
+- Uses precise technical terminology
+- Questions go deep ("How does V8 optimize scope chain lookups for closures?")
+- Concept status is \`mastered\` but seeking deeper discussion
+- Related concept confidence in state.yaml > 0.7
+
+**Level-adaptive strategy:**
+- Beginners: Explanation-heavy (70% explanation + 30% guided questions), heavy use of analogies
+- Intermediate: Balanced (50% explanation + 50% guidance), encourage self-derivation
+- Advanced: Guidance and challenge-heavy (30% supplement + 70% deep discussion), quickly skip basics
+
+### Step 3: Explain the Concept
+
+**Explanation structure (for beginner/intermediate):**
+
+1. **Positioning** — Where is this concept in the knowledge map? (One sentence)
+   > "Closures sit in the **Functions → Scope & Closures** branch of the JavaScript knowledge tree. To understand closures, you first need to know what scope is."
+
+2. **Analogy** — Build intuition with a real-world metaphor
+   > "Think of a function as a backpack. Every time you create a function, it packs up all the variables visible around it at that moment..."
+
+3. **Core Mechanism** — Explain "what" and "why" in clear language
+   > "A closure is the combination of a function and its lexical environment. When a function 'remembers' the scope it was created in..."
+
+4. **Code Example** — A minimal but complete example
+   > \`\`\`javascript
+   > function createCounter() {
+   >   let count = 0;
+   >   return function() { count++; return count; };
+   > }
+   > const counter = createCounter();
+   > counter(); // 1
+   > counter(); // 2 — it "remembers" count
+   > \`\`\`
+
+5. **Common Misconceptions** — Point out the most common beginner mistakes
+   > "Many people think a closure is just a function defined inside another function. The key is actually 'capturing external variables'..."
+
+6. **Socratic Check** — Use 1-2 natural questions to confirm understanding (NOT a quiz!)
+   > "If I create 5 closures inside a loop using var versus let, what would be different? Take a guess?"
+
+   Note: This is a thinking-guiding question, tone should be curious and exploratory, not exam-like. If the user is unsure, give the answer immediately — don't wait.
+
+### Step 4: Identify Sub-topics (Recursive Entry Points)
+
+After the explanation, identify deeper sub-topics under this concept. These aren't a bullet list of facts — they flow naturally into the closing:
+
+> Now you understand the basics of closures. If you'd like to go deeper, we can explore:
+>
+> 🔍 **Classic Closure Patterns**
+> - Module Pattern — Using closures for private variables
+> - Currying — One of the most elegant uses of closures
+> - Debounce & Throttle — Closures in real-world frontend
+>
+> 🔍 **Closure Performance**
+> - Memory leaks — When do closures cause problems?
+> - V8 hidden classes and closure optimization
+>
+> Which direction interests you? Or would you rather do some practice exercises to solidify?
+
+**Sub-topic identification rules:**
+- Sub-topics should be organic extensions, not random tangents
+- List 2-4 sub-directions, each with 1-2 sentences explaining why it's worth learning
+- Always offer the "practice" option alongside
+- For advanced users, sub-topics should be deeper
+- For beginners, sub-topics should lean practical and applied
+- **Never rush**, let the user decide their next step
+
+### Step 5: Record Learning Session
+
+After each explanation, append a session record to \`./.learn/topics/<topic-name>/sessions/YYYY-MM-DD.md\`:
+
+\`\`\`markdown
+# Learning Session - <date>
+
+## Content
+- Concept: [concept name]
+- Path: [path in knowledge map, e.g., "Functions/Closures"]
+- Depth: beginner/intermediate/advanced explanation
+
+## Key Points Covered
+- [point 1]
+- [point 2]
+
+## Sub-topics Explored by User
+(If the user chose to go deeper, record which direction)
+
+## Follow-ups
+(If the user expressed confusion that wasn't fully resolved, record it here)
+\`\`\`
+
+**Also update state.yaml:**
+- If concept status is \`unexplored\`, update to \`in_progress\`
+- Update \`last_session\` to current date
+- If the user showed good understanding (asked questions, answered correctly), slightly increase \`confidence\` (+0.05 to +0.1)
+
+---
+
+## Edge Cases
+
+- **Concept name mismatch**: Fuzzy search the concept name in the knowledge map.
+  E.g., user enters "closure principles", matches to "Functions/Closures". "Did you mean **Closures** (under the Functions branch)?"
+
+- **Multiple matches**: List all matching concepts for the user to choose.
+  "I found several possible matches in the knowledge map:
+  1. Functions/Closures — A function combined with its lexical environment
+  2. Rust/Ownership & Borrowing — Ownership rules similar to closures
+  Which would you like to learn?"
+
+- **Concept not in knowledge map**:
+  "'Micro-frontends' isn't in the current JavaScript knowledge map. This might be a more advanced or cross-domain concept.
+  I can:
+  - Add this concept to the JavaScript knowledge map
+  - Or create a separate 'Micro-frontends' learning topic
+  Which do you prefer?"
+
+- **Topic doesn't exist**: Prompt user to create a topic first with \`/learn <topic-name>\`.
+  "You haven't created a related topic yet. Run \`/learn <topic-name>\` first to start learning!"
+
+- **User is clearly a beginner**: Adjust explanation style:
+  - More analogies, fewer technical terms
+  - More comprehension checks ("Does that make sense?")
+  - Prioritize "why we need this concept" over "how it works internally"
+  - Provide simpler code examples`;
+const COMMAND_NAME = 'Learn: Explain';
+const COMMAND_DESCRIPTION = 'Recursively deep-dive into a concept — AI explains, guides thinking, you choose the depth';
+const COMMAND_CONTENT = `Use the learn-anything-explain skill to handle the user's /learn-explain <concept-name> request.
+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. Identify sub-topics as recursive entry points
+5. Record learning session and update state.yaml`;
+export function getLearnExplainSkillTemplate() {
+    return {
+        name: SKILL_NAME,
+        description: SKILL_DESCRIPTION,
+        instructions: INSTRUCTIONS,
+        license: 'MIT',
+        compatibility: 'Requires learn-anything CLI.',
+        metadata: { author: 'learn-anything', version: '1.0' },
+    };
+}
+export function getLearnExplainCommandTemplate() {
+    return {
+        name: COMMAND_NAME,
+        description: COMMAND_DESCRIPTION,
+        category: 'Learning',
+        tags: ['learning', 'explain', 'socratic', 'recursive'],
+        content: COMMAND_CONTENT,
+    };
+}
+//# sourceMappingURL=learn-explain.js.map

package/dist/core/templates/workflows/learn-practice.d.ts

@@ -0,0 +1,4 @@
+import type { SkillTemplate, CommandTemplate } from '../types.js';
+export declare function getLearnPracticeSkillTemplate(): SkillTemplate;
+export declare function getLearnPracticeCommandTemplate(): CommandTemplate;
+//# sourceMappingURL=learn-practice.d.ts.map