termi-kids 0.1.0

package/dist/learn/lessons.js

@@ -0,0 +1,490 @@
+/**
+ * Learn mode lesson data: six scripted lessons about building with AI.
+ *
+ * Pure data plus one rule-based prompt grader. No model calls, no network,
+ * no disk. Copy follows the kid rules: grade 4 to 5 reading level, every
+ * sentence under 15 words, mascot voice, no dashes.
+ */
+/** The six lessons, in teaching order. Ids double as badge ids. */
+export const LESSONS = [
+    {
+        id: 'learn-1',
+        title: 'Meet your AI helper',
+        emoji: '\u{1F916}',
+        intro: 'Let us meet the robot brain that helps you build.',
+        steps: [
+            { kind: 'say', text: 'Hi! I am Termi. An AI program does my thinking.' },
+            {
+                kind: 'say',
+                text: 'An AI learned from millions of examples. It guesses what comes next.',
+            },
+            {
+                kind: 'say',
+                text: 'Good guesses look smart. But some guesses are wrong. That is normal.',
+            },
+            {
+                kind: 'choice',
+                question: 'Is the AI a person?',
+                options: [
+                    {
+                        label: 'Yes, a tiny person lives in the computer',
+                        feedback: 'Good guess, but no. It is a program that guesses from patterns.',
+                    },
+                    {
+                        label: 'No, it is a computer program',
+                        correct: true,
+                        feedback: 'Right! It is a tool, like a super calculator for words.',
+                    },
+                    {
+                        label: 'Maybe it is a robot ghost',
+                        feedback: 'Ha! No ghosts here. It is a program that guesses from patterns.',
+                    },
+                ],
+            },
+            {
+                kind: 'choice',
+                question: 'The AI sounds friendly. Does it have real feelings?',
+                options: [
+                    {
+                        label: 'Yes, it likes me a lot',
+                        feedback: 'It sounds warm, but no. It makes friendly words without feeling them.',
+                    },
+                    {
+                        label: 'No, it only makes friendly words',
+                        correct: true,
+                        feedback: 'Right! Friendly words are part of its job. It feels nothing.',
+                    },
+                ],
+            },
+            {
+                kind: 'choice',
+                question: 'What should you keep secret from an AI?',
+                options: [
+                    {
+                        label: 'My real name, school, and address',
+                        correct: true,
+                        feedback: 'Yes! Keep real life info secret. Made up names are perfect.',
+                    },
+                    {
+                        label: 'My game ideas',
+                        feedback: 'Share those! Ideas are safe. Keep your real name and address secret.',
+                    },
+                    {
+                        label: 'Nothing at all',
+                        feedback: 'Careful! Keep your real name, school, and address secret.',
+                    },
+                ],
+            },
+            { kind: 'say', text: 'Big rule: the AI is a tool. You are the human in charge.' },
+            {
+                kind: 'mission',
+                text: 'Open any project. Then say: change the title to something silly. Watch your AI helper work.',
+            },
+        ],
+    },
+    {
+        id: 'learn-2',
+        title: 'Super prompts',
+        emoji: '✨',
+        intro: 'Strong asks get strong builds. Time to power up.',
+        steps: [
+            {
+                kind: 'say',
+                text: 'A super prompt tells three things. What to change. Where it is. How it should look.',
+            },
+            {
+                kind: 'say',
+                text: 'Weak ask: make it cool. Strong ask: make the player a red dragon.',
+            },
+            { kind: 'say', text: 'Now you be the judge. Grade these prompts.' },
+            {
+                kind: 'grade',
+                prompt: 'make it better',
+                isGood: false,
+                why: 'Better how? It does not say what to change or how.',
+            },
+            {
+                kind: 'grade',
+                prompt: 'make the player a red dragon',
+                isGood: true,
+                why: 'It names the player and says how: a red dragon.',
+            },
+            {
+                kind: 'grade',
+                prompt: 'fix the game',
+                isGood: false,
+                why: 'Fix what? It does not say what looks wrong or where.',
+            },
+            {
+                kind: 'grade',
+                prompt: 'change the sky in my game to purple with stars',
+                isGood: true,
+                why: 'It says what, the sky, and how, purple with stars.',
+            },
+            { kind: 'say', text: 'Nice grading! Now write your own super prompt.' },
+            {
+                kind: 'mission',
+                text: 'Open a project. Try your super prompt for real. Make it say what, where, and how.',
+            },
+        ],
+    },
+    {
+        id: 'learn-3',
+        title: 'Small steps win',
+        emoji: '\u{1F422}',
+        intro: 'Big projects grow one small step at a time.',
+        steps: [
+            { kind: 'say', text: 'Want a whole new game? Awesome. We build it in small steps.' },
+            { kind: 'say', text: 'Ask for one change. Check the preview. Then ask for the next.' },
+            {
+                kind: 'choice',
+                question: 'You want a faster player, a new boss, and new music. What do you ask first?',
+                options: [
+                    {
+                        label: 'All three at once',
+                        feedback: 'Tempting! But big asks get tangled. One at a time wins.',
+                    },
+                    {
+                        label: 'Just the faster player',
+                        correct: true,
+                        feedback: 'Yes! One change, then a preview check. Then the next one.',
+                    },
+                ],
+            },
+            {
+                kind: 'choice',
+                question: 'Your change landed. What comes next?',
+                options: [
+                    {
+                        label: 'Check the preview',
+                        correct: true,
+                        feedback: 'Right! Look first, so you know it worked.',
+                    },
+                    {
+                        label: 'Ask for five more changes',
+                        feedback: 'Hold on! Check the preview first. Make sure it worked.',
+                    },
+                ],
+            },
+            {
+                kind: 'say',
+                text: 'Small steps make bugs easy to spot. You always know what changed.',
+            },
+            {
+                kind: 'mission',
+                text: 'Pick one small change. Say: make the player a little faster. Then check the preview.',
+            },
+        ],
+    },
+    {
+        id: 'learn-4',
+        title: 'Be a code detective',
+        emoji: '\u{1F50D}',
+        intro: 'Grab your magnifying glass. We will track what the AI did.',
+        steps: [
+            { kind: 'say', text: 'When I build, I print activity lines. They say what I touched.' },
+            { kind: 'say', text: 'A line like "edited game.js" means that file changed.' },
+            {
+                kind: 'choice',
+                question: 'The line says "edited style.css". What changed?',
+                options: [
+                    {
+                        label: 'The look, like colors and sizes',
+                        correct: true,
+                        feedback: 'Yes! Looks live in style.css: colors, sizes, and fonts.',
+                    },
+                    {
+                        label: 'The game rules',
+                        feedback: 'Not this time. Rules live in game.js. Looks live in style.css.',
+                    },
+                ],
+            },
+            {
+                kind: 'choice',
+                question: 'Which file most likely holds the score code?',
+                options: [
+                    {
+                        label: 'game.js',
+                        correct: true,
+                        feedback: 'Right! Game logic, like the score, lives in game.js.',
+                    },
+                    {
+                        label: 'style.css',
+                        feedback: 'Close! style.css is looks only. Score logic lives in game.js.',
+                    },
+                    {
+                        label: 'index.html',
+                        feedback: 'Good thought! That file is the page frame. Score code lives in game.js.',
+                    },
+                ],
+            },
+            {
+                kind: 'choice',
+                question: 'You want to find the change inside a file. What is the fast way?',
+                options: [
+                    {
+                        label: 'Search for words from your ask, like speed',
+                        correct: true,
+                        feedback: 'Smart! The change sits near words from your ask.',
+                    },
+                    {
+                        label: 'Read every single line',
+                        feedback: 'That works, but it is slow. Search for words from your ask.',
+                    },
+                ],
+            },
+            { kind: 'say', text: 'Reading the changes teaches you real code, bit by bit.' },
+            {
+                kind: 'mission',
+                text: 'Ask for one small change. Then read the activity lines and find the file that changed.',
+            },
+        ],
+    },
+    {
+        id: 'learn-5',
+        title: 'When it goes wrong',
+        emoji: '\u{1F41B}',
+        intro: 'Bugs happen to every builder. Even me. Beep.',
+        steps: [
+            { kind: 'say', text: 'A bug is when your project does something you did not want.' },
+            { kind: 'say', text: 'Every builder makes bugs. The pros make them every day.' },
+            {
+                kind: 'choice',
+                question: 'Your game broke after a change. Whose fault is it?',
+                options: [
+                    {
+                        label: 'Mine. I am bad at this',
+                        feedback: 'No way! Bugs are normal for every builder. Never blame yourself.',
+                    },
+                    {
+                        label: 'Nobody. Bugs just happen when we build',
+                        correct: true,
+                        feedback: 'Right! Bugs are part of building. We find them and fix them.',
+                    },
+                ],
+            },
+            {
+                kind: 'say',
+                text: 'To get a fix, tell me two things. What you SEE. What you WANTED.',
+            },
+            {
+                kind: 'choice',
+                question: 'Which bug report helps the most?',
+                options: [
+                    {
+                        label: 'It is broken',
+                        feedback: 'Broken how? Say what you see and what you wanted.',
+                    },
+                    {
+                        label: 'The player sinks through the floor. I want it to stand',
+                        correct: true,
+                        feedback: 'Perfect! What you see, plus what you wanted. Easy to fix.',
+                    },
+                ],
+            },
+            {
+                kind: 'choice',
+                question: 'A change made things worse. What is the safest move?',
+                options: [
+                    {
+                        label: 'Type /undo',
+                        correct: true,
+                        feedback: 'Yes! Undo takes back the last change. It is always safe.',
+                    },
+                    {
+                        label: 'Pile on more changes',
+                        feedback: 'Risky! Changes can stack into a mess. Undo is the safe reset.',
+                    },
+                ],
+            },
+            { kind: 'say', text: 'Remember: /undo is always safe. No mistake is stuck forever.' },
+            {
+                kind: 'mission',
+                text: 'Spot something odd in a project. Say: I see this, but I wanted that. Then watch the fix.',
+            },
+        ],
+    },
+    {
+        id: 'learn-6',
+        title: 'You are the boss',
+        emoji: '\u{1F451}',
+        intro: 'Crown on. The AI works for you, boss.',
+        steps: [
+            { kind: 'say', text: 'The AI suggests ideas. You decide what your project becomes.' },
+            {
+                kind: 'choice',
+                question: 'The AI suggests a blue ship. You wanted green. Who wins?',
+                options: [
+                    {
+                        label: 'The AI. It is smarter',
+                        feedback: 'Nope! It only suggests. Ask for the green ship.',
+                    },
+                    {
+                        label: 'Me. It is my project',
+                        correct: true,
+                        feedback: 'Right! You decide. The AI helps, but you are the boss.',
+                    },
+                ],
+            },
+            { kind: 'say', text: 'Do not like a suggestion? Skip it. Or remix it your way.' },
+            {
+                kind: 'choice',
+                question: 'The AI gives you a boring idea. What can you do?',
+                options: [
+                    {
+                        label: 'Use it anyway',
+                        feedback: 'You can, but you do not have to. Add your own twist!',
+                    },
+                    {
+                        label: 'Remix it with my own twist',
+                        correct: true,
+                        feedback: 'Yes! Your twist makes it yours. That is real creating.',
+                    },
+                ],
+            },
+            {
+                kind: 'choice',
+                question: 'What makes a project truly yours?',
+                options: [
+                    {
+                        label: 'The AI wrote most of the code',
+                        feedback: 'Code is one part. Your ideas and choices make it yours.',
+                    },
+                    {
+                        label: 'My ideas, my choices, my style',
+                        correct: true,
+                        feedback: 'Exactly! Your ideas and choices make it yours. The AI just helps.',
+                    },
+                ],
+            },
+            {
+                kind: 'say',
+                text: 'That was the last lesson. You know the secrets now. Beep beep, proud robot noises.',
+            },
+            {
+                kind: 'mission',
+                text: 'Type /ideas in a project. Pick one idea. Then change it to fit your style.',
+            },
+        ],
+    },
+];
+/** Doing words a strong prompt starts from. */
+const ACTION_WORDS = [
+    'make',
+    'add',
+    'change',
+    'move',
+    'fix',
+    'turn',
+    'give',
+    'put',
+    'paint',
+    'color',
+    'swap',
+    'grow',
+    'shrink',
+    'show',
+    'hide',
+    'draw',
+    'build',
+    'remove',
+    'delete',
+    'rename',
+    'set',
+];
+/** Things and places a kid project usually has. */
+const THING_WORDS = [
+    'player',
+    'title',
+    'background',
+    'score',
+    'game',
+    'ball',
+    'sky',
+    'enemy',
+    'enemies',
+    'button',
+    'page',
+    'music',
+    'sound',
+    'pet',
+    'story',
+    'level',
+    'character',
+    'star',
+    'stars',
+    'rock',
+    'rocks',
+    'cloud',
+    'clouds',
+    'text',
+    'screen',
+    'jump',
+    'ship',
+    'bat',
+    'ghost',
+    'boss',
+    'wall',
+    'floor',
+    'platform',
+    'colors',
+    'dragon',
+    'header',
+    'board',
+    'timer',
+    'life',
+    'lives',
+    'coin',
+    'coins',
+    'monster',
+    'hero',
+    'world',
+    'menu',
+];
+/** Kid project file names also count as naming a place. */
+const FILE_NAME_RE = /\b[\w-]+\.(?:js|html|css)\b/i;
+/**
+ * Simple personal-info patterns: names, addresses, phones, emails, schools.
+ * Same intent as the safety prefilter, trimmed for practice text.
+ */
+const PII_RES = [
+    /[a-z0-9._%+-]+@[a-z0-9][a-z0-9.-]*\.[a-z]{2,}/i,
+    /\+?\d(?:[\s().-]?\d){8,}/,
+    /\bmy (?:real |full )?name is\b/i,
+    /\bmy (?:home )?address is\b/i,
+    /\bmy school is\b/i,
+    /\b\d{1,5}\s+\w+\s+(?:street|avenue|road|lane|drive|st|ave|rd|ln|dr)\b/i,
+];
+const GRADER_TIPS = {
+    action: 'Start with a doing word, like make, add, or change.',
+    thing: 'Name the thing to change, like the player or the title.',
+    length: 'Say a bit more. Tell what, where, and how.',
+    pii: 'Keep real names, addresses, and numbers secret. Your project never needs them.',
+};
+function hasWordFrom(text, words) {
+    return words.some((word) => new RegExp(`\\b${word}\\b`, 'i').test(text));
+}
+/**
+ * Rule-based prompt check, no model call. A good prompt has a doing word,
+ * names a thing or place, runs four or more words, and holds no personal info.
+ */
+export function gradePrompt(text) {
+    const trimmed = text.trim();
+    const tips = [];
+    if (!hasWordFrom(trimmed, ACTION_WORDS)) {
+        tips.push(GRADER_TIPS.action);
+    }
+    if (!hasWordFrom(trimmed, THING_WORDS) && !FILE_NAME_RE.test(trimmed)) {
+        tips.push(GRADER_TIPS.thing);
+    }
+    const wordCount = trimmed.split(/\s+/).filter((word) => word.length > 0).length;
+    if (wordCount < 4) {
+        tips.push(GRADER_TIPS.length);
+    }
+    if (PII_RES.some((re) => re.test(trimmed))) {
+        tips.push(GRADER_TIPS.pii);
+    }
+    return { good: tips.length === 0, tips };
+}
+/** The grader, packaged for lesson two's free-type finale. */
+export const PROMPT_GRADER = { gradePrompt };

package/dist/learn/runner.js

@@ -0,0 +1,193 @@
+/**
+ * Learn mode runner: the lesson menu, lesson playback, and progress.
+ *
+ * Everything here is scripted and offline: no model calls, no network.
+ * Progress lives in a small JSON file at TERMI_HOME/learn.json. Finished
+ * lessons earn a badge once and stay replayable forever. Every prompt is
+ * cancel-safe: Ctrl+C exits kindly without marking the lesson complete.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import * as p from '@clack/prompts';
+import { atomicWriteFileSync, termiHome } from '../config/paths.js';
+import { awardBadge } from '../surfaces/home.js';
+import { celebrate } from '../ui/celebrate.js';
+import { mascot } from '../ui/mascot.js';
+import { glyph, style } from '../ui/theme.js';
+import { gradePrompt, LESSONS } from './lessons.js';
+/** Where the finished-lesson list lives. */
+export function learnFilePath() {
+    return path.join(termiHome(), 'learn.json');
+}
+/** The finished lesson ids, oldest first. Missing or broken file means none. */
+export function loadProgress() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(learnFilePath(), 'utf8'));
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const completed = parsed.completed;
+            if (Array.isArray(completed)) {
+                return { completed: completed.filter((id) => typeof id === 'string') };
+            }
+        }
+    }
+    catch {
+        // No file yet means no lessons finished yet.
+    }
+    return { completed: [] };
+}
+/** Records a finished lesson. Repeat finishes change nothing. */
+export function markLessonDone(id) {
+    const progress = loadProgress();
+    if (progress.completed.includes(id)) {
+        return;
+    }
+    progress.completed.push(id);
+    atomicWriteFileSync(learnFilePath(), JSON.stringify(progress, null, 2));
+}
+/** Menu line for one lesson, with a done mark once it is finished. */
+export function lessonMenuLabel(lesson, done) {
+    const base = `${lesson.emoji} ${lesson.title}`;
+    return done ? `${base} ${glyph('check')}` : base;
+}
+function defaultSay(text) {
+    console.log(text);
+}
+const SAY_FACES = ['happy', 'thinking', 'building'];
+function kindStop(say) {
+    say([mascot('gentleNo'), '', 'Okay, we can stop here. Come back any time!'].join('\n'));
+}
+async function runChoiceStep(step, say) {
+    const pick = await p.select({
+        message: step.question,
+        options: step.options.map((option, index) => ({ value: index, label: option.label })),
+    });
+    if (p.isCancel(pick)) {
+        return false;
+    }
+    const chosen = step.options[pick];
+    if (chosen !== undefined) {
+        const right = chosen.correct === true;
+        const mark = right ? glyph('check') : glyph('bulb');
+        const paint = right ? style.good : style.warm;
+        say(paint(`${mark} ${chosen.feedback}`));
+    }
+    return true;
+}
+async function runGradeStep(step, say) {
+    const pick = await p.select({
+        message: `Grade this prompt: "${step.prompt}"`,
+        options: [
+            { value: 'good', label: 'Super prompt' },
+            { value: 'bad', label: 'Needs work' },
+        ],
+    });
+    if (p.isCancel(pick)) {
+        return false;
+    }
+    const right = (pick === 'good') === step.isGood;
+    say(right
+        ? style.good(`${glyph('check')} You got it! ${step.why}`)
+        : style.warm(`${glyph('bulb')} Look again. ${step.why}`));
+    return true;
+}
+/**
+ * Lesson two's free-type finale: the kid writes a prompt and the
+ * rule-based grader answers with kind tips. No model call, ever.
+ * Returns false only when the kid cancels.
+ */
+export async function runPromptPractice(say = defaultSay) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const typed = await p.text({
+            message: 'Your turn! Write your own super prompt.',
+            placeholder: 'make the player a red dragon',
+        });
+        if (p.isCancel(typed)) {
+            return false;
+        }
+        const grade = gradePrompt(typed ?? '');
+        if (grade.good) {
+            say(style.good(`${glyph('check')} That is a super prompt! Save it for your next build.`));
+            return true;
+        }
+        say(style.warm('Close! A tip or two:'));
+        for (const tip of grade.tips) {
+            say(`  ${glyph('bulb')} ${tip}`);
+        }
+        if (attempt === 0) {
+            say('One more try. You have got this.');
+        }
+    }
+    say('Good practice! Super prompts take a few tries.');
+    return true;
+}
+/**
+ * Plays one lesson start to finish. Returns true when the kid reached the
+ * end. The badge and the done mark only land on a full play-through.
+ */
+export async function runLesson(lesson, say = defaultSay) {
+    say([mascot('happy'), '', style.title(`${lesson.emoji} ${lesson.title}`), lesson.intro].join('\n'));
+    let sayCount = 0;
+    for (const step of lesson.steps) {
+        if (step.kind === 'say') {
+            const face = SAY_FACES[sayCount % SAY_FACES.length] ?? 'happy';
+            sayCount += 1;
+            say([mascot(face), '', step.text].join('\n'));
+        }
+        else if (step.kind === 'choice') {
+            if (!(await runChoiceStep(step, say))) {
+                kindStop(say);
+                return false;
+            }
+        }
+        else if (step.kind === 'grade') {
+            if (!(await runGradeStep(step, say))) {
+                kindStop(say);
+                return false;
+            }
+        }
+        else {
+            if (lesson.id === 'learn-2' && !(await runPromptPractice(say))) {
+                kindStop(say);
+                return false;
+            }
+            p.note(step.text, 'Your mission');
+        }
+    }
+    say(celebrate(`Lesson done: ${lesson.title}!`));
+    markLessonDone(lesson.id);
+    await awardBadge(lesson.id, say);
+    return true;
+}
+/**
+ * The learn menu: all six lessons with done marks, replay welcome.
+ * Loops until the kid picks the exit row or cancels.
+ */
+export async function runLearnMenu() {
+    console.log(mascot('happy'));
+    console.log('Welcome to Termi school! Six tiny lessons, zero homework.');
+    for (;;) {
+        const done = new Set(loadProgress().completed);
+        const options = [
+            ...LESSONS.map((lesson) => ({
+                value: lesson.id,
+                label: lessonMenuLabel(lesson, done.has(lesson.id)),
+                ...(done.has(lesson.id) ? { hint: 'Done! Play it again any time.' } : {}),
+            })),
+            { value: '__back__', label: 'All done for now' },
+        ];
+        const firstOpen = LESSONS.find((lesson) => !done.has(lesson.id));
+        const pick = await p.select({
+            message: 'Pick a lesson.',
+            options,
+            initialValue: firstOpen !== undefined ? firstOpen.id : '__back__',
+        });
+        if (p.isCancel(pick) || pick === '__back__') {
+            console.log('Come back any time. The lessons never run out.');
+            return;
+        }
+        const lesson = LESSONS.find((entry) => entry.id === pick);
+        if (lesson !== undefined) {
+            await runLesson(lesson);
+        }
+    }
+}