learn-anything-cli 0.2.1 → 0.4.0-beta.1

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

@@ -0,0 +1,150 @@
+/**
+ * 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 { unified } from 'unified';
+import remarkParse from 'remark-parse';
+// ---- Helpers -----------------------------------------------------------
+/** Recursively extract plain text from an AST node.
+ *
+ * Does NOT descend into nested `list` nodes — those are structural
+ * children (details under a concept) and should not contribute to
+ * the parent concept's name.
+ */
+function extractText(node) {
+    if (!node || typeof node !== 'object')
+        return '';
+    const n = node;
+    if (n.type === 'text' && typeof n.value === 'string') {
+        return n.value;
+    }
+    // Don't descend into lists: their content belongs to child concepts/details.
+    if (n.type === 'list')
+        return '';
+    if (Array.isArray(n.children)) {
+        return n.children.map(extractText).join('');
+    }
+    return '';
+}
+/** Narrow a child node to a specific type. */
+function isHeading(node, depth) {
+    if (!node || typeof node !== 'object')
+        return false;
+    const n = node;
+    return n.type === 'heading' && n.depth === depth;
+}
+function isList(node) {
+    if (!node || typeof node !== 'object')
+        return false;
+    return node.type === 'list';
+}
+// ---- Public API ---------------------------------------------------------
+/**
+ * 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 function parseKnowledgeMap(markdown) {
+    const tree = unified().use(remarkParse).parse(markdown);
+    let topic = '';
+    const domains = [];
+    let currentDomain = null;
+    for (const node of tree.children) {
+        // # Title
+        if (isHeading(node, 1)) {
+            topic = extractText(node).trim();
+            continue;
+        }
+        // ## DomainName
+        if (isHeading(node, 2)) {
+            if (currentDomain)
+                domains.push(currentDomain);
+            currentDomain = {
+                name: extractText(node).trim(),
+                concepts: [],
+            };
+            continue;
+        }
+        // - Concept list (only process if we're inside a domain)
+        if (isList(node) && currentDomain) {
+            const list = node;
+            for (const item of list.children) {
+                processListItem(item, currentDomain, markdown);
+            }
+        }
+    }
+    // Push the last domain
+    if (currentDomain)
+        domains.push(currentDomain);
+    return { topic, domains };
+}
+/**
+ * Get list-item text via source position slicing.
+ *
+ * remark-parse consumes `__init__` as `<strong>init</strong>`, losing the
+ * underscores. By slicing the original markdown source at the paragraph's
+ * position offsets, we preserve the exact original text including any
+ * markdown formatting characters.
+ */
+function extractListItemText(item, source) {
+    for (const child of item.children) {
+        if (child.type === 'paragraph') {
+            const para = child;
+            const pos = para.position;
+            if (pos?.start && pos?.end) {
+                const start = pos.start;
+                const end = pos.end;
+                if (start.offset !== undefined && end.offset !== undefined) {
+                    return source.slice(start.offset, end.offset);
+                }
+            }
+        }
+    }
+    // Fallback to recursive text extraction
+    return extractText(item);
+}
+/** Strip common Markdown escape backslashes (e.g. `\_` → `_`, `\*` → `*`). */
+function unescapeMarkdown(text) {
+    return text.replace(/\\([\\`*{}[\]()#+\-.!_>~|])/g, '$1');
+}
+/** Extract a concept (and its optional details) from a list item. */
+function processListItem(item, domain, source) {
+    const name = unescapeMarkdown(extractListItemText(item, source).trim());
+    if (!name)
+        return;
+    const concept = { name, children: [] };
+    // Look for a nested list inside this list item (these are third-level details)
+    for (const child of item.children) {
+        if (isList(child)) {
+            for (const nestedItem of child.children) {
+                const detailName = unescapeMarkdown(extractListItemText(nestedItem, source).trim());
+                if (detailName) {
+                    concept.children.push(detailName);
+                }
+            }
+        }
+    }
+    domain.concepts.push(concept);
+}
+//# sourceMappingURL=parser.js.map

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

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export declare const stateV1Schema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    topic: z.ZodString;
+    slug: z.ZodString;
+    created: z.ZodString;
+    domains: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        slug: z.ZodString;
+        concepts: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            slug: z.ZodString;
+            status: z.ZodEnum<{
+                unexplored: "unexplored";
+                in_progress: "in_progress";
+                needs_practice: "needs_practice";
+                mastered: "mastered";
+            }>;
+            confidence: z.ZodNumber;
+            practice_count: z.ZodNumber;
+            explain_count: z.ZodNumber;
+            last_explained: z.ZodNullable<z.ZodString>;
+            last_practiced: z.ZodNullable<z.ZodString>;
+            details: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type StateV1Schema = z.infer<typeof stateV1Schema>;
+export type ValidationResult = {
+    success: true;
+    data: StateV1Schema;
+} | {
+    success: false;
+    errors: z.ZodIssue[];
+};
+/** Validate an unknown value against the StateV1 schema. */
+export declare function validateStateV1(value: unknown): ValidationResult;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+// ---- Helpers -----------------------------------------------------------
+/** Datetime: YYYY-MM-DD or YYYY-MM-DD HH:mm:ss. */
+const dateTimeStr = () => z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?$/, 'Expected YYYY-MM-DD or YYYY-MM-DD HH:mm:ss');
+const nullableDateTimeStr = () => dateTimeStr().nullable();
+// ---- Concept schema ----------------------------------------------------
+const conceptSchema = z.object({
+    name: z.string().min(1),
+    slug: z.string().min(1),
+    status: z.enum(['unexplored', 'in_progress', 'needs_practice', 'mastered']),
+    confidence: z.number().min(0).max(1),
+    practice_count: z.number().int().min(0),
+    explain_count: z.number().int().min(0),
+    last_explained: nullableDateTimeStr(),
+    last_practiced: nullableDateTimeStr(),
+    details: z.array(z.string()),
+});
+// ---- Domain schema -----------------------------------------------------
+const domainSchema = z.object({
+    name: z.string().min(1),
+    slug: z.string().min(1),
+    concepts: z.array(conceptSchema),
+});
+// ---- Top-level StateV1 schema ------------------------------------------
+export const stateV1Schema = z.object({
+    version: z.literal(1),
+    topic: z.string().min(1),
+    slug: z.string().min(1),
+    created: dateTimeStr(),
+    domains: z.array(domainSchema),
+});
+// ---- Public API ---------------------------------------------------------
+/** Validate an unknown value against the StateV1 schema. */
+export function validateStateV1(value) {
+    const result = stateV1Schema.safeParse(value);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, errors: result.error.issues };
+}
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * Generate a stable kebab-case slug from a human-readable name.
+ *
+ * Rules (applied in order):
+ * 1. Replace `/` with `-`
+ * 2. Replace spaces with `-`
+ * 3. Remove characters that are NOT letters, digits, `-`, or `_`
+ * 4. Convert ASCII letters to lowercase; preserve non-ASCII characters
+ * 5. Collapse consecutive `-` into a single `-`
+ * 6. Trim leading / trailing `-`
+ */
+export declare function generateSlug(name: string): string;
+//# sourceMappingURL=slug.d.ts.map

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

@@ -0,0 +1,28 @@
+/**
+ * Generate a stable kebab-case slug from a human-readable name.
+ *
+ * Rules (applied in order):
+ * 1. Replace `/` with `-`
+ * 2. Replace spaces with `-`
+ * 3. Remove characters that are NOT letters, digits, `-`, or `_`
+ * 4. Convert ASCII letters to lowercase; preserve non-ASCII characters
+ * 5. Collapse consecutive `-` into a single `-`
+ * 6. Trim leading / trailing `-`
+ */
+export function generateSlug(name) {
+    const slug = name
+        // 1. / → -
+        .replace(/\//g, '-')
+        // 2. space → -
+        .replace(/\s/g, '-')
+        // 3. Remove chars that are NOT [letter, digit, -, _]
+        .replace(/[^\p{L}\p{N}\-_]/gu, '')
+        // 4. ASCII letters to lowercase (preserves non-ASCII)
+        .replace(/[A-Z]/g, (ch) => ch.toLowerCase())
+        // 5. Collapse consecutive -
+        .replace(/-{2,}/g, '-')
+        // 6. Trim leading/trailing -
+        .replace(/^-+|-+$/g, '');
+    return slug;
+}
+//# sourceMappingURL=slug.js.map

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

@@ -0,0 +1,63 @@
+/** Valid status values for a concept's learning state. */
+export type ConceptStatus = 'unexplored' | 'in_progress' | 'needs_practice' | 'mastered';
+/** A third-level detail under a concept — plain name, no independent state. */
+export type Detail = string;
+/** A single concept within a domain — the minimum trackable unit. */
+export interface Concept {
+    name: string;
+    slug: string;
+    status: ConceptStatus;
+    confidence: number;
+    practice_count: number;
+    explain_count: number;
+    last_explained: string | null;
+    last_practiced: string | null;
+    details: Detail[];
+}
+/** A top-level knowledge domain containing concepts. */
+export interface Domain {
+    name: string;
+    slug: string;
+    concepts: Concept[];
+}
+/** state.json v1 top-level structure — the single source of truth. */
+export interface StateV1 {
+    version: 1;
+    topic: string;
+    slug: string;
+    created: string;
+    domains: Domain[];
+}
+/** A single concept entry in v0 state.yaml. */
+export interface V0Concept {
+    path: string;
+    status: string;
+    last_practiced: string | null;
+    practice_count: number;
+    confidence: number;
+    /** v0 used `last_session` — migrate maps it to `last_explained`. */
+    last_session?: string | null;
+    explain_count?: number;
+}
+/** Top-level shape of v0 state.yaml. */
+export interface V0State {
+    topic: string;
+    created: string;
+    concepts: V0Concept[];
+}
+/** Parsed structure extracted from v0 knowledge-map.md. */
+export interface ParsedConcept {
+    name: string;
+    children: string[];
+}
+/** A domain extracted from v0 knowledge-map.md. */
+export interface ParsedDomain {
+    name: string;
+    concepts: ParsedConcept[];
+}
+/** Result of parsing a v0 knowledge-map.md. */
+export interface ParsedKnowledgeMap {
+    topic: string;
+    domains: ParsedDomain[];
+}
+//# sourceMappingURL=types.d.ts.map

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

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

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