termi-kids 0.1.0

package/dist/surfaces/chat.js

@@ -0,0 +1,439 @@
+/**
+ * The build session: live preview, safety wiring, the agent turn loop,
+ * heartbeat while waiting, typewriter reveal, badges, and chat commands.
+ *
+ * The agent loop and project snapshot modules load lazily so this file
+ * imports cleanly even while other wave modules are still landing.
+ */
+import * as p from '@clack/prompts';
+import { getSecret } from '../auth/keychain.js';
+import { hasTokens } from '../auth/tokens.js';
+import { startPreview } from '../preview/server.js';
+import { createProviderClient, pickClassifierBackend, } from '../providers/index.js';
+import { classifyProviderError } from '../providers/errors.js';
+import { appendAudit } from '../safety/audit.js';
+import { createSafetyPipeline } from '../safety/classifier.js';
+import { ensureGuardFetch } from '../safety/guarddownload.js';
+import { lazyGuardAccessor } from '../safety/guardrunner.js';
+import { guardModelReady } from '../safety/modelstore.js';
+import { createSessionState } from '../safety/session.js';
+import { renderProviderError } from '../ui/errors.js';
+import { heartbeatLine, mascot } from '../ui/mascot.js';
+import { style } from '../ui/theme.js';
+import { T } from '../ui/text.js';
+import { questsFor, questStepLine } from '../projects/quests.js';
+import { providerLabel } from '../setup/wizard.js';
+import { executeDone, executeIdeas, executePreview, executeRedo, executeUndo, helpText, parseCommand, } from './commands.js';
+import { awardBadge, loadBadges } from './home.js';
+import { renderBadgeShelf } from '../ui/celebrate.js';
+/** Milliseconds between heartbeat updates while the agent works. */
+const HEARTBEAT_MS = 3500;
+/** Per-character delay for the typewriter reveal. */
+const TYPE_DELAY_MS = 12;
+/** Ceiling on the whole reveal, so long replies never feel slow. */
+const TYPE_TOTAL_BUDGET_MS = 1500;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Reveals reply text one character at a time. Instant when the
+ * TERMI_FAST_TEXT=1 env flag is set (tests and impatient builders).
+ */
+export async function typewriter(text, write = (chunk) => void process.stdout.write(chunk), delayMs = TYPE_DELAY_MS) {
+    // The reveal never exceeds the total budget: long replies speed up and
+    // print instantly once the per-character delay rounds down to zero.
+    const perChar = Math.min(delayMs, Math.floor(TYPE_TOTAL_BUDGET_MS / Math.max(1, text.length)));
+    if (process.env.TERMI_FAST_TEXT === '1' || perChar <= 0) {
+        write(`${text}\n`);
+        return;
+    }
+    for (const ch of text) {
+        write(ch);
+        await sleep(perChar);
+    }
+    write('\n');
+}
+/** True when the reply already offers what to try next. */
+export function replyHasTryNext(reply) {
+    return /try (this|it|that|next)|next,? (try|you)|how about|you could/i.test(reply);
+}
+function mascotExpressionFrom(name) {
+    const known = [
+        'happy',
+        'thinking',
+        'building',
+        'celebrating',
+        'oops',
+        'gentleNo',
+    ];
+    return known.includes(name) ? name : 'gentleNo';
+}
+function providerAvailability(settings) {
+    return {
+        'openai-chatgpt': hasTokens(),
+        'openai-api': (getSecret('api-key-openai-api') ?? '').length > 0,
+        anthropic: (getSecret('api-key-anthropic') ?? '').length > 0,
+        // A Grok key only counts once a parent confirmed the adults-only terms.
+        xai: (getSecret('api-key-xai') ?? '').length > 0 && settings.xaiParentAck,
+    };
+}
+function say(text) {
+    console.log(text);
+}
+function offlineScreen() {
+    return [mascot('gentleNo'), '', T.offline.noProvider, T.offline.stillWorks].join('\n');
+}
+const noopSnapshots = {
+    beginTurn() {
+        // No snapshot module yet; undo and redo report nothing to do.
+    },
+    undo: () => false,
+    redo: () => false,
+};
+/** The chat screen for one open project. Resolves when the kid leaves. */
+export async function runChat(project, settings) {
+    let preview = null;
+    try {
+        preview = await startPreview(project.dir, { openBrowser: true });
+        p.log.success(`${T.chat.previewOpened} ${style.dim(preview.url)}`);
+    }
+    catch {
+        p.log.warn('The preview could not start. We can still build.');
+    }
+    const audit = (event) => {
+        try {
+            appendAudit(event);
+        }
+        catch {
+            // The chat never falls over because the audit disk write failed.
+        }
+    };
+    const session = createSessionState();
+    let provider = null;
+    if (settings.activeProvider !== null) {
+        try {
+            provider = createProviderClient(settings.activeProvider);
+        }
+        catch {
+            provider = null;
+        }
+    }
+    const backend = pickClassifierBackend(settings, providerAvailability(settings));
+    // The guard hot-attaches: null while its model still downloads, live from
+    // the first check after the file lands. A missing file also (re)starts the
+    // background fetch, and is written to the safety log: a deleted model
+    // file must not detach a safety layer invisibly.
+    if (settings.localClassifier && !guardModelReady()) {
+        audit({
+            ts: new Date().toISOString(),
+            layer: 'system',
+            event: 'guard_missing',
+            excerpt: 'safety checker on, model file not present; background fetch started',
+        });
+        void ensureGuardFetch();
+    }
+    const safety = createSafetyPipeline({
+        classifierModel: () => backend.classifierClient !== null
+            ? backend.classifierClient.languageModel('classifier', settings.modelAlias)
+            : null,
+        moderationKey: () => backend.moderationKey,
+        localGuard: lazyGuardAccessor(settings.localClassifier),
+        audit,
+    });
+    let snapshots = noopSnapshots;
+    try {
+        const snapMod = await import('../projects/snapshots.js');
+        snapshots = snapMod.createSnapshotStore(project);
+    }
+    catch {
+        snapshots = noopSnapshots;
+    }
+    let runTurnFn = null;
+    try {
+        const loop = await import('../agent/loop.js');
+        runTurnFn = loop.runTurn;
+    }
+    catch {
+        runTurnFn = null;
+    }
+    let ideaPool = null;
+    let ideaNext = 0;
+    const nextIdeas = async (count) => {
+        if (ideaPool === null) {
+            try {
+                const mod = await import('../projects/ideas.js');
+                ideaPool = mod.getIdeas(project.meta.scaffoldId);
+            }
+            catch {
+                ideaPool = [];
+            }
+        }
+        if (ideaPool.length === 0) {
+            return [];
+        }
+        const out = [];
+        for (let i = 0; i < count && i < ideaPool.length; i += 1) {
+            const idea = ideaPool[ideaNext % ideaPool.length];
+            if (idea !== undefined) {
+                out.push(idea);
+            }
+            ideaNext += 1;
+        }
+        return out;
+    };
+    const activeLabel = settings.activeProvider !== null ? providerLabel(settings.activeProvider) : 'AI helper';
+    let prevTurnErrored = false;
+    let turnsTaken = 0;
+    const doTurn = async (kidMessage) => {
+        if (provider === null || runTurnFn === null) {
+            say(offlineScreen());
+            return 'offline';
+        }
+        const started = Date.now();
+        let heartbeatCleared = false;
+        const spin = p.spinner();
+        spin.start(T.chat.thinking);
+        const beat = setInterval(() => {
+            if (!heartbeatCleared) {
+                spin.message(heartbeatLine(Math.round((Date.now() - started) / 1000)));
+            }
+        }, HEARTBEAT_MS);
+        const clearHeartbeat = () => {
+            if (!heartbeatCleared) {
+                heartbeatCleared = true;
+                clearInterval(beat);
+                spin.stop(T.chat.working);
+            }
+        };
+        const ui = {
+            onActivity(line) {
+                clearHeartbeat();
+                say(style.dim(`  ${line}`));
+            },
+        };
+        let result;
+        try {
+            result = await runTurnFn(kidMessage, {
+                provider,
+                modelAlias: settings.modelAlias,
+                safety,
+                session,
+                project,
+                snapshots,
+                preview,
+                audit,
+                ui,
+            });
+        }
+        catch (err) {
+            clearInterval(beat);
+            if (!heartbeatCleared) {
+                spin.stop();
+            }
+            say(renderProviderError(classifyProviderError(err), activeLabel));
+            prevTurnErrored = true;
+            return 'error';
+        }
+        clearInterval(beat);
+        if (!heartbeatCleared) {
+            spin.stop(T.chat.working);
+        }
+        turnsTaken += 1;
+        if (result.status === 'ok') {
+            const reply = result.replyText ?? '';
+            if (reply.length > 0) {
+                await typewriter(reply);
+            }
+            if (reply.length > 0 && !replyHasTryNext(reply)) {
+                const ideas = await nextIdeas(2);
+                if (ideas.length > 0) {
+                    say(style.dim(['Try this next:', ...ideas.map((idea) => `  - ${idea}`)].join('\n')));
+                }
+            }
+            if (result.filesChanged.length > 0) {
+                await awardBadge('first-change');
+            }
+            if (prevTurnErrored) {
+                await awardBadge('bug-squasher');
+            }
+            prevTurnErrored = false;
+            return 'ok';
+        }
+        if (result.status === 'blocked') {
+            if (result.screen !== null) {
+                say([
+                    mascot(mascotExpressionFrom(result.screen.mascotExpression)),
+                    '',
+                    style.title(result.screen.title),
+                    result.screen.body,
+                ].join('\n'));
+            }
+            else {
+                say([mascot('gentleNo'), '', T.blocks.generic].join('\n'));
+            }
+            return 'blocked';
+        }
+        const error = result.error ?? { kind: 'server' };
+        say(renderProviderError(error, activeLabel));
+        prevTurnErrored = true;
+        return 'error';
+    };
+    const finish = async () => {
+        try {
+            if (turnsTaken > 0) {
+                project.updateTermiMd({ recapLine: `We worked on ${project.meta.prettyName}.` });
+            }
+            project.touch();
+        }
+        catch {
+            // Notes are best effort on the way out.
+        }
+        if (preview !== null) {
+            try {
+                await preview.stop();
+            }
+            catch {
+                // The process is leaving anyway.
+            }
+        }
+    };
+    p.log.message(style.dim(T.chat.doneHint));
+    if (questsFor(project.meta.scaffoldId).length > 0) {
+        p.log.message(style.dim(T.quest.hint));
+    }
+    let quest = null;
+    let questStep = 0;
+    const questAdvance = async () => {
+        if (quest === null) {
+            return;
+        }
+        questStep += 1;
+        if (questStep >= quest.steps.length) {
+            quest = null;
+            say(style.title(T.quest.finished));
+            await awardBadge('quest-hero');
+        }
+        else {
+            say(style.dim(T.quest.stepDone));
+        }
+    };
+    let hintIndex = 0;
+    for (;;) {
+        const hint = T.hints[hintIndex % T.hints.length] ?? '';
+        hintIndex += 1;
+        const step = quest !== null ? quest.steps[questStep] : undefined;
+        if (quest !== null && step !== undefined) {
+            say(style.title(questStepLine(quest, questStep)));
+            say(style.dim(T.quest.enterToSend.replace('{prompt}', step.prompt)));
+        }
+        const raw = await p.text({
+            message: T.chat.placeholder,
+            placeholder: step !== undefined ? step.prompt : hint,
+        });
+        if (p.isCancel(raw)) {
+            await finish();
+            return 'quit';
+        }
+        const cmd = parseCommand(raw);
+        switch (cmd.kind) {
+            case 'chat': {
+                // In a quest, plain Enter sends the suggested step prompt.
+                const text = cmd.text.length > 0 ? cmd.text : (step?.prompt ?? '');
+                if (text.length > 0) {
+                    const outcome = await doTurn(text);
+                    if (outcome === 'ok') {
+                        await questAdvance();
+                    }
+                }
+                break;
+            }
+            case 'quest': {
+                if (quest !== null) {
+                    quest = null;
+                    say(T.quest.stopped);
+                    break;
+                }
+                const available = questsFor(project.meta.scaffoldId);
+                if (available.length === 0) {
+                    say(T.quest.none);
+                    break;
+                }
+                if (available.length === 1) {
+                    quest = available[0] ?? null;
+                }
+                else {
+                    const picked = await p.select({
+                        message: T.quest.pick,
+                        options: available.map((q) => ({ value: q.id, label: `${q.emoji} ${q.title}` })),
+                    });
+                    if (p.isCancel(picked)) {
+                        break;
+                    }
+                    quest = available.find((q) => q.id === picked) ?? null;
+                }
+                if (quest !== null) {
+                    questStep = 0;
+                    say(T.quest.start);
+                }
+                break;
+            }
+            case 'undo':
+                executeUndo(snapshots, preview, say);
+                break;
+            case 'redo':
+                executeRedo(snapshots, preview, say);
+                break;
+            case 'preview':
+                await executePreview(preview, say);
+                break;
+            case 'ideas':
+                await executeIdeas(project.meta.scaffoldId, say);
+                break;
+            case 'badges':
+                say(renderBadgeShelf(loadBadges()));
+                break;
+            case 'learn':
+                try {
+                    const learn = await import('../learn/runner.js');
+                    await learn.runLearnMenu();
+                }
+                catch {
+                    say('Learn mode is taking a nap. Try again soon.');
+                }
+                break;
+            case 'help':
+                say(helpText());
+                break;
+            case 'done':
+                await executeDone({
+                    scaffoldId: project.meta.scaffoldId,
+                    prettyName: project.meta.prettyName,
+                    updateRecap: (line) => {
+                        project.updateTermiMd({ recapLine: line });
+                    },
+                }, (badgeId) => awardBadge(badgeId), say);
+                break;
+            case 'new':
+                await finish();
+                return 'new';
+            case 'quit':
+                say(T.errors.goodbye);
+                await finish();
+                return 'quit';
+            case 'grownups':
+                try {
+                    const panel = await import('../grownups/panel.js');
+                    await panel.runPanel();
+                }
+                catch {
+                    say(T.grownups.needsGrownup);
+                }
+                break;
+            case 'unknown':
+                say(cmd.suggestion !== null
+                    ? T.chat.didYouMean.replace('{command}', `/${cmd.suggestion}`)
+                    : T.chat.unknownCommand);
+                break;
+        }
+    }
+}

package/dist/surfaces/commands.js

@@ -0,0 +1,206 @@
+/**
+ * Chat command parsing and execution helpers.
+ *
+ * Parsing is pure and synchronous so it is easy to test. Execution helpers
+ * take every dependency as an argument, which keeps chat.ts a thin shell
+ * and keeps this module importable before the rest of the wave lands.
+ */
+import { celebrate } from '../ui/celebrate.js';
+import { T } from '../ui/text.js';
+import { glyph } from '../ui/theme.js';
+/** Every slash command the chat understands, in help order. */
+export const COMMAND_NAMES = [
+    'preview',
+    'undo',
+    'redo',
+    'new',
+    'ideas',
+    'badges',
+    'learn',
+    'quest',
+    'help',
+    'done',
+    'quit',
+    'grownups',
+];
+/** Commands a kid can type as a plain word, no slash needed. */
+export const BARE_WORDS = [
+    'undo',
+    'help',
+    'ideas',
+    'done',
+    'preview',
+    'badges',
+    'learn',
+    'quest',
+    'quit',
+];
+/**
+ * Leaving words kids type on their own. Each maps to quit so a goodbye
+ * never becomes a paid AI turn.
+ */
+export const QUIT_SYNONYMS = ['exit', 'stop', 'bye', 'leave'];
+/** Classic edit distance. Small inputs only, so the simple table is fine. */
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const next = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            next[j] = Math.min((next[j - 1] ?? 0) + 1, (prev[j] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        prev = next;
+    }
+    return prev[b.length] ?? 0;
+}
+/** The closest known command within maxDistance edits, or null. */
+export function nearestCommand(word, maxDistance = 2) {
+    let best = null;
+    let bestDistance = maxDistance + 1;
+    for (const name of COMMAND_NAMES) {
+        const distance = levenshtein(word, name);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = name;
+        }
+    }
+    return bestDistance <= maxDistance ? best : null;
+}
+/**
+ * Turns raw kid input into a typed command.
+ * Slash commands match by their first word. Unknown slash words get a
+ * did-you-mean suggestion. Single bare words like "undo" also work.
+ * Everything else is a chat message for the agent.
+ */
+export function parseCommand(raw) {
+    const input = raw.trim();
+    if (input.length === 0) {
+        return { kind: 'chat', text: '' };
+    }
+    if (input.startsWith('/')) {
+        const word = (input.slice(1).trim().split(/\s+/)[0] ?? '').toLowerCase();
+        if (COMMAND_NAMES.includes(word)) {
+            return { kind: word };
+        }
+        if (QUIT_SYNONYMS.includes(word)) {
+            return { kind: 'quit' };
+        }
+        return { kind: 'unknown', word, suggestion: nearestCommand(word) };
+    }
+    if (!/\s/.test(input)) {
+        const lower = input.toLowerCase();
+        if (BARE_WORDS.includes(lower)) {
+            return { kind: lower };
+        }
+        if (QUIT_SYNONYMS.includes(lower)) {
+            return { kind: 'quit' };
+        }
+    }
+    return { kind: 'chat', text: input };
+}
+/** The kid-facing command list. */
+export function helpText() {
+    const rows = [
+        ['/preview', 'watch your project run'],
+        ['/undo', 'take back the last change'],
+        ['/redo', 'bring a change back'],
+        ['/new', 'start a fresh project'],
+        ['/ideas', 'get fun ideas'],
+        ['/badges', 'see your badges'],
+        ['/learn', 'play short AI lessons'],
+        ['/quest', 'build with me, step by step'],
+        ['/help', 'show this list'],
+        ['/done', 'finish and celebrate'],
+        ['/quit', 'stop for today'],
+        ['/grownups', 'grown-up zone, PIN needed'],
+    ];
+    const lines = rows.map(([cmd, what]) => `  ${cmd.padEnd(10)} ${what}`);
+    return [
+        'Here is what I can do:',
+        ...lines,
+        'Plain words work too, like undo, ideas, or quit.',
+    ].join('\n');
+}
+/** Undo the last change and tell the preview to reload. */
+export function executeUndo(snapshots, preview, say) {
+    const ok = snapshots.undo();
+    if (ok) {
+        preview?.notifyChange();
+        say(T.chat.undoDone);
+    }
+    else {
+        say(T.chat.nothingToUndo);
+    }
+    return ok;
+}
+/** Bring back the change that undo removed. */
+export function executeRedo(snapshots, preview, say) {
+    const ok = snapshots.redo();
+    if (ok) {
+        preview?.notifyChange();
+        say(T.chat.redoDone);
+    }
+    else {
+        say(T.chat.nothingToRedo);
+    }
+    return ok;
+}
+/** Prints idea lines for a scaffold. Loads the idea bank lazily. */
+export async function executeIdeas(scaffoldId, say) {
+    let ideas = [];
+    try {
+        const mod = await import('../projects/ideas.js');
+        ideas = mod.getIdeas(scaffoldId);
+    }
+    catch {
+        ideas = [];
+    }
+    if (ideas.length === 0) {
+        say('I am out of ideas right now. Try /help.');
+        return;
+    }
+    const bullet = glyph('bulb');
+    say(['Here are some ideas:', ...ideas.map((idea) => `  ${bullet} ${idea}`)].join('\n'));
+}
+/** Reopens the browser at the preview URL. */
+export async function executePreview(preview, say) {
+    if (preview === null) {
+        say('The preview is not running right now.');
+        return;
+    }
+    say(`${T.chat.previewOpened} ${preview.url}`);
+    try {
+        const mod = await import('open');
+        await mod.default(preview.url);
+    }
+    catch {
+        // The URL is printed above, so the kid can still open it by hand.
+    }
+}
+/** True for the project types where /done earns the Game Shipped badge. */
+export function donEarnsGameBadge(scaffoldId) {
+    return scaffoldId === 'games' || scaffoldId === 'biggames';
+}
+/**
+ * The /done moment: celebration, the Game Shipped badge for game projects,
+ * and a recap line saved for the next session.
+ */
+export async function executeDone(target, award, say) {
+    const isGame = donEarnsGameBadge(target.scaffoldId);
+    say(celebrate(isGame ? T.celebrations.gameShipped : T.celebrations.generic));
+    if (isGame) {
+        await award('game-shipped');
+    }
+    try {
+        target.updateRecap(`We finished ${target.prettyName}!`);
+    }
+    catch {
+        // Notes are best effort; the celebration already happened.
+    }
+}