termi-kids 0.1.0

package/dist/auth/tokens.js

@@ -0,0 +1,219 @@
+/**
+ * On-disk token store for the ChatGPT sign-in (auth.json).
+ *
+ * Lives on disk, not in the keychain, because of platform blob size caps.
+ * Written atomically with owner-only mode. Refresh is single flight inside
+ * the process (promise mutex) and across processes (lockfile with stale
+ * takeover). Token values are never logged and never appear in errors.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicWriteFileSync, authJsonPath, locksDir } from '../config/paths.js';
+import { decodeIdToken, OAuthRefreshError, refreshTokens } from './oauth.js';
+/** Fallback lifetime assumption when issued_at is missing: 10 days. */
+const DEFAULT_LIFETIME_MS = 10 * 24 * 60 * 60 * 1000;
+/** Refresh proactively once 80 percent of the lifetime has passed. */
+const REFRESH_AT_FRACTION = 0.8;
+/** A lockfile older than this is considered abandoned and taken over. */
+const LOCK_STALE_MS = 30_000;
+/** Give up waiting for another process after this long. */
+const LOCK_WAIT_MS = 45_000;
+const LOCK_POLL_MS = 100;
+/** The saved sign-in can no longer be used. A grown-up must sign in again. */
+export class AuthDeadError extends Error {
+    reason;
+    constructor(reason) {
+        super('The saved sign-in no longer works. A grown-up needs to sign in again.');
+        this.name = 'AuthDeadError';
+        this.reason = reason;
+    }
+}
+/** Writes the token set atomically with owner-only permissions. */
+export function saveTokens(tokens) {
+    atomicWriteFileSync(authJsonPath(), JSON.stringify(tokens, null, 2), 0o600);
+}
+/** Reads and validates auth.json. Returns null when missing or malformed. */
+export function loadTokens() {
+    try {
+        const raw = fs.readFileSync(authJsonPath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return null;
+        }
+        const data = parsed;
+        if (data.provider !== 'openai-chatgpt' ||
+            typeof data.access_token !== 'string' ||
+            typeof data.refresh_token !== 'string' ||
+            typeof data.expires_at !== 'number') {
+            return null;
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+export function hasTokens() {
+    return loadTokens() !== null;
+}
+export function clearTokens() {
+    fs.rmSync(authJsonPath(), { force: true });
+}
+/** Marks the stored sign-in dead so callers stop retrying refresh. */
+export function markDead(reason) {
+    const current = loadTokens();
+    if (current !== null) {
+        saveTokens({ ...current, dead: true, deadReason: reason });
+    }
+}
+/** True once 80 percent of the token lifetime has passed (or it expired). */
+export function needsRefresh(tokens, now = Date.now()) {
+    if (now >= tokens.expires_at) {
+        return true;
+    }
+    const issuedAt = tokens.issued_at ?? tokens.expires_at - DEFAULT_LIFETIME_MS;
+    const lifetime = tokens.expires_at - issuedAt;
+    if (lifetime <= 0) {
+        return true;
+    }
+    return now >= issuedAt + lifetime * REFRESH_AT_FRACTION;
+}
+function authLockPath() {
+    return path.join(locksDir(), 'auth.lock');
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Acquires the cross-process refresh lock. Waits for a live lock, takes
+ * over a stale one (older than 30 seconds). Returns a release function.
+ */
+async function acquireLock() {
+    const lockFile = authLockPath();
+    fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            fs.writeFileSync(lockFile, JSON.stringify({ pid: process.pid, at: Date.now() }), {
+                flag: 'wx',
+                mode: 0o600,
+            });
+            return () => {
+                try {
+                    fs.rmSync(lockFile, { force: true });
+                }
+                catch {
+                    // Releasing is best effort; a leftover lock goes stale in 30s.
+                }
+            };
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST') {
+                throw err;
+            }
+            let stale = false;
+            try {
+                stale = Date.now() - fs.statSync(lockFile).mtimeMs > LOCK_STALE_MS;
+            }
+            catch {
+                // The lock vanished between attempts; retry right away.
+                continue;
+            }
+            if (stale) {
+                try {
+                    fs.rmSync(lockFile, { force: true });
+                }
+                catch {
+                    // Another process may have removed it first.
+                }
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new Error('auth-lock-timeout');
+            }
+            await sleep(LOCK_POLL_MS);
+        }
+    }
+}
+/** In-process single flight: concurrent callers share one refresh. */
+let refreshInFlight = null;
+/**
+ * Returns a usable access token. Refreshes proactively past 80 percent of
+ * the lifetime: persist first, then return. Terminal refresh failures mark
+ * the store dead and throw AuthDeadError.
+ */
+export async function getValidAccessToken(fetchImpl = globalThis.fetch) {
+    const current = loadTokens();
+    if (current === null) {
+        throw new AuthDeadError('no-tokens');
+    }
+    if (current.dead === true) {
+        throw new AuthDeadError(current.deadReason ?? 'dead');
+    }
+    if (!needsRefresh(current)) {
+        return current.access_token;
+    }
+    if (refreshInFlight === null) {
+        refreshInFlight = refreshWithLock(fetchImpl).finally(() => {
+            refreshInFlight = null;
+        });
+    }
+    return refreshInFlight;
+}
+async function refreshWithLock(fetchImpl) {
+    const release = await acquireLock();
+    try {
+        // Re-read after acquiring: another process may have refreshed already.
+        const current = loadTokens();
+        if (current === null) {
+            throw new AuthDeadError('no-tokens');
+        }
+        if (current.dead === true) {
+            throw new AuthDeadError(current.deadReason ?? 'dead');
+        }
+        if (!needsRefresh(current)) {
+            return current.access_token;
+        }
+        try {
+            const rotated = await refreshTokens(current.refresh_token, fetchImpl);
+            const now = Date.now();
+            const next = {
+                ...current,
+                access_token: rotated.access_token,
+                refresh_token: rotated.refresh_token ?? current.refresh_token,
+                id_token: rotated.id_token ?? current.id_token,
+                issued_at: now,
+                expires_at: rotated.expires_in !== undefined
+                    ? now + rotated.expires_in * 1000
+                    : now + DEFAULT_LIFETIME_MS,
+            };
+            delete next.dead;
+            delete next.deadReason;
+            if (rotated.id_token !== undefined) {
+                try {
+                    const info = decodeIdToken(rotated.id_token);
+                    if (info.accountId.length > 0) {
+                        next.account_id = info.accountId;
+                        next.plan_type = info.planType;
+                    }
+                }
+                catch {
+                    // Keep the prior identity fields when the new id_token is odd.
+                }
+            }
+            // Persist FIRST (the refresh token rotated), THEN return.
+            saveTokens(next);
+            return next.access_token;
+        }
+        catch (err) {
+            if (err instanceof OAuthRefreshError && err.kind === 'auth-dead') {
+                markDead(err.reason);
+                throw new AuthDeadError(err.reason);
+            }
+            throw err;
+        }
+    }
+    finally {
+        release();
+    }
+}

package/dist/cli.js

@@ -0,0 +1,258 @@
+/**
+ * The termi entry point: argv router and boot sequence.
+ *
+ * Boot: ensureDirs, loadSettings, tamper warning when the settings file
+ * fails its integrity check, the setup wizard when setup never finished,
+ * global crash handlers, then the route. Exit code 0 for normal paths,
+ * 1 for crashes (set by the global handlers).
+ */
+import fs from 'node:fs';
+import * as p from '@clack/prompts';
+import { isSetupComplete } from './config/pin.js';
+import { ensureDirs, errorLogPath } from './config/paths.js';
+import { loadSettings } from './config/settings.js';
+import { startPreview } from './preview/server.js';
+import { appendAudit } from './safety/audit.js';
+import { guardModelReady } from './safety/modelstore.js';
+import { renderBanner } from './ui/banner.js';
+import { installGlobalHandlers, renderCrash } from './ui/errors.js';
+import { mascot } from './ui/mascot.js';
+import { style } from './ui/theme.js';
+import { T } from './ui/text.js';
+import { executeIdeas } from './surfaces/commands.js';
+/** Pure boot branch logic: settings state in, actions out. */
+export function decideBoot(state) {
+    return {
+        warnTamper: state.tampered,
+        runWizard: !state.setupComplete,
+    };
+}
+/** The grown-up and kid help for the command line. */
+export function cliHelp() {
+    return [
+        'How to use Termi:',
+        '  termi            open the home menu',
+        '  termi new        start a new project',
+        '  termi go [name]  open a project and build',
+        '  termi preview    watch a project run',
+        '  termi ideas      get fun ideas',
+        '  termi learn      play six short lessons about AI',
+        '  termi grownups   grown-up zone (PIN needed)',
+        '  termi help       show this help',
+        '  termi --version  show the version',
+    ].join('\n');
+}
+function versionString() {
+    try {
+        const raw = fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.version === 'string' ? parsed.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function showTamperWarning() {
+    console.log(mascot('oops'));
+    console.log('Termi found changed settings. Safe settings are on now.');
+    console.log(style.dim('A grown-up can review this in the grown-up zone.'));
+    try {
+        appendAudit({
+            ts: new Date().toISOString(),
+            layer: 'system',
+            event: 'settings_change',
+            excerpt: 'settings integrity check failed, strict defaults applied',
+        });
+    }
+    catch {
+        // The warning is what matters most here.
+    }
+}
+async function resolveProject(nameArg, settings) {
+    let store;
+    try {
+        store = await import('./projects/store.js');
+    }
+    catch {
+        p.log.warn('Project tools are not ready yet.');
+        return null;
+    }
+    if (nameArg !== undefined && nameArg.length > 0) {
+        let slug = nameArg.toLowerCase();
+        try {
+            const create = await import('./projects/create.js');
+            slug = create.slugifyName(nameArg).slug;
+        }
+        catch {
+            // Use the lowercased name as a best-effort slug.
+        }
+        const direct = store.openProject(slug);
+        if (direct !== null) {
+            return direct;
+        }
+        p.log.warn('I cannot find that project. Pick one below.');
+    }
+    const metas = store.listProjects();
+    if (metas.length === 0) {
+        p.log.info('No projects yet. Run "termi new" to make one!');
+        return null;
+    }
+    const first = metas[0];
+    const initial = settings.lastProjectSlug !== null && metas.some((m) => m.slug === settings.lastProjectSlug)
+        ? settings.lastProjectSlug
+        : first?.slug;
+    const pick = await p.select({
+        message: 'Pick a project.',
+        options: metas.map((m) => ({ value: m.slug, label: m.prettyName })),
+        ...(initial !== undefined ? { initialValue: initial } : {}),
+    });
+    if (p.isCancel(pick)) {
+        return null;
+    }
+    return store.openProject(pick);
+}
+async function routePreview(nameArg, settings) {
+    const project = await resolveProject(nameArg, settings);
+    if (project === null) {
+        return;
+    }
+    const handle = await startPreview(project.dir, { openBrowser: true });
+    console.log(`${T.chat.previewOpened} ${style.dim(handle.url)}`);
+    console.log(style.dim('Press Ctrl+C when you are done watching.'));
+    await new Promise(() => {
+        // Held open on purpose; Ctrl+C ends it through the global handler.
+    });
+}
+async function routeIdeas(settings) {
+    let scaffoldId = 'games';
+    if (settings.lastProjectSlug !== null) {
+        try {
+            const store = await import('./projects/store.js');
+            const last = store.openProject(settings.lastProjectSlug);
+            if (last !== null) {
+                scaffoldId = last.meta.scaffoldId;
+            }
+        }
+        catch {
+            // Fall back to game ideas.
+        }
+    }
+    await executeIdeas(scaffoldId, (text) => {
+        console.log(text);
+    });
+}
+async function route(command, rest, settings) {
+    const home = await import('./surfaces/home.js');
+    switch (command) {
+        case '': {
+            await home.showHome(settings);
+            return;
+        }
+        case 'new': {
+            const project = await home.runNewProject(settings);
+            if (project !== null) {
+                await home.openChatLoop(project, settings);
+            }
+            return;
+        }
+        case 'go': {
+            const project = await resolveProject(rest[0], settings);
+            if (project !== null) {
+                await home.openChatLoop(project, settings);
+            }
+            return;
+        }
+        case 'preview': {
+            await routePreview(rest[0], settings);
+            return;
+        }
+        case 'ideas': {
+            await routeIdeas(settings);
+            return;
+        }
+        case 'learn': {
+            const learn = await import('./learn/runner.js');
+            await learn.runLearnMenu();
+            return;
+        }
+        case 'grownups': {
+            const panel = await import('./grownups/panel.js');
+            await panel.runPanel();
+            return;
+        }
+        default: {
+            console.log(`Hmm, "${command}" is not a Termi command.`);
+            console.log(cliHelp());
+            return;
+        }
+    }
+}
+/** Full boot and route. Exported for tests; auto-runs outside of them. */
+export async function main(argv = process.argv.slice(2)) {
+    const command = argv[0] ?? '';
+    if (command === '--version' || command === '-v') {
+        console.log(versionString());
+        return;
+    }
+    if (command === 'help' || command === '--help' || command === '-h') {
+        console.log(cliHelp());
+        return;
+    }
+    ensureDirs();
+    const loaded = loadSettings();
+    let settings = loaded.settings;
+    const decision = decideBoot({
+        firstRun: loaded.firstRun,
+        tampered: loaded.tampered,
+        setupComplete: isSetupComplete(),
+    });
+    if (decision.warnTamper) {
+        showTamperWarning();
+    }
+    if (decision.runWizard) {
+        const wizard = await import('./setup/wizard.js');
+        await wizard.runWizard();
+        settings = loadSettings().settings;
+        if (!isSetupComplete()) {
+            return;
+        }
+    }
+    else if (command === '') {
+        console.log(renderBanner());
+    }
+    installGlobalHandlers({
+        onCrash: (entry) => {
+            try {
+                fs.appendFileSync(errorLogPath(), entry);
+            }
+            catch {
+                // Nowhere left to write; the friendly screen still shows.
+            }
+        },
+        logPath: errorLogPath(),
+    });
+    // Resume the safety-checker download in the background when it is enabled
+    // but its model file is not on disk yet (declined-then-enabled, an
+    // interrupted transfer, or a wizard quit mid-download). Never blocks.
+    if (settings.localClassifier && !guardModelReady()) {
+        const { ensureGuardFetch } = await import('./safety/guarddownload.js');
+        void ensureGuardFetch();
+    }
+    await route(command, argv.slice(1), settings);
+}
+const underTest = process.env.VITEST !== undefined || process.env.NODE_ENV === 'test';
+if (!underTest) {
+    main()
+        .then(() => process.exit(0))
+        .catch((err) => {
+        const detail = err instanceof Error ? `${err.name}: ${err.message}\n${err.stack ?? ''}` : String(err);
+        try {
+            fs.appendFileSync(errorLogPath(), `[${new Date().toISOString()}] main\n${detail}\n`);
+        }
+        catch {
+            // Nowhere left to write.
+        }
+        console.error(renderCrash(errorLogPath()));
+        process.exit(1);
+    });
+}

package/dist/config/paths.js

@@ -0,0 +1,92 @@
+/**
+ * Central path helpers for Termi state on disk.
+ *
+ * Everything is computed lazily (functions, not top-level constants) so the
+ * TERMI_HOME and TERMI_PROJECTS_DIR environment overrides work at any point,
+ * which is what the test suite relies on.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** First port the preview server tries; it scans upward from here. */
+export const previewBasePort = 4311;
+/** Root for Termi's own state. Default: <home>/.termi. Override: TERMI_HOME. */
+export function termiHome() {
+    const override = process.env.TERMI_HOME;
+    if (override && override.trim().length > 0) {
+        return path.resolve(override);
+    }
+    return path.join(os.homedir(), '.termi');
+}
+/** Where kid projects live. Default: <home>/Termi. Override: TERMI_PROJECTS_DIR. */
+export function projectsDir() {
+    const override = process.env.TERMI_PROJECTS_DIR;
+    if (override && override.trim().length > 0) {
+        return path.resolve(override);
+    }
+    return path.join(os.homedir(), 'Termi');
+}
+/** Signed settings envelope (settings plus MAC). */
+export function settingsPath() {
+    return path.join(termiHome(), 'settings.json');
+}
+/** OAuth token store. Kept on disk, not in the keychain, due to blob size caps. */
+export function authJsonPath() {
+    return path.join(termiHome(), 'auth.json');
+}
+/** Forward hash chained audit log. */
+export function auditLogPath() {
+    return path.join(termiHome(), 'audit.log');
+}
+/** Crash details land here; the kid only ever sees a friendly screen. */
+export function errorLogPath() {
+    return path.join(termiHome(), 'error.log');
+}
+/** Content-addressed snapshot blobs and per-turn manifests. */
+export function snapshotsDir() {
+    return path.join(termiHome(), 'snapshots');
+}
+/** Cross-process lock files (for example the token refresh lock). */
+export function locksDir() {
+    return path.join(termiHome(), 'locks');
+}
+/** Local safety-model files (the on-device classifier). */
+export function modelsDir() {
+    return path.join(termiHome(), 'models');
+}
+/** Creates every directory Termi needs. Safe to call repeatedly. */
+export function ensureDirs() {
+    for (const dir of [termiHome(), projectsDir(), snapshotsDir(), locksDir(), modelsDir()]) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Writes a file atomically: temp file in the same directory, then rename.
+ * Mode defaults to 0o600 (owner only). Mode is best effort on Windows.
+ */
+export function atomicWriteFileSync(filePath, data, mode = 0o600) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpName = `.${path.basename(filePath)}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+    const tmpPath = path.join(dir, tmpName);
+    fs.writeFileSync(tmpPath, data, { mode });
+    try {
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        try {
+            fs.rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // Best effort cleanup; the original error matters more.
+        }
+        throw err;
+    }
+    try {
+        fs.chmodSync(filePath, mode);
+    }
+    catch {
+        // Best effort: chmod is mostly a no-op on Windows.
+    }
+}