termi-kids 0.1.0

package/dist/projects/store.js

@@ -0,0 +1,325 @@
+/**
+ * Project store: open kid projects, list them, and work with their files.
+ *
+ * Each project lives at projectsDir()/<slug>/ and holds:
+ * - .termi.json   project metadata (ProjectMeta, written atomically)
+ * - TERMI.md      the project notes the model reads and updates
+ * - kid files     index.html, style.css, game.js, and friends
+ * - vendor files  engine files like kaplay.mjs, never counted as kid files
+ *
+ * All file access is jailed to the project directory. Paths are resolved
+ * and prefix-checked, with case folding on Windows.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicWriteFileSync, projectsDir } from '../config/paths.js';
+/** The metadata file inside every project directory. */
+export const metaFileName = '.termi.json';
+/** The notes file the model keeps for the kid. Not a kid file. */
+export const notesFileName = 'TERMI.md';
+/** Vendored engine files. Present on disk, never counted or touched as kid files. */
+const vendorEngineFiles = new Set(['kaplay.mjs']);
+/** Largest size a single kid file may be, in bytes. */
+export const maxKidFileBytes = 256 * 1024;
+/** TERMI.md never grows past this many lines. */
+export const maxTermiMdLines = 60;
+const outsideProjectMessage = 'That file is outside your project. Termi will not touch it.';
+const specialNameMessage = 'That file name is off limits. Pick a different name.';
+const tooLargeMessage = 'That file is too big. Keep each file under 256 KB.';
+function caseFold(p) {
+    return process.platform === 'win32' ? p.toLowerCase() : p;
+}
+/**
+ * Resolves a relative path inside the project directory.
+ * Returns null when the path is absolute, empty, or escapes the project.
+ */
+function resolveInside(dir, relPath) {
+    if (typeof relPath !== 'string' || relPath.trim().length === 0)
+        return null;
+    if (path.isAbsolute(relPath))
+        return null;
+    const base = path.resolve(dir);
+    const resolved = path.resolve(base, relPath);
+    if (caseFold(resolved) === caseFold(base))
+        return null;
+    if (!caseFold(resolved).startsWith(caseFold(base + path.sep)))
+        return null;
+    return resolved;
+}
+/** Real path segments, with empty and "." entries dropped. */
+function segmentsOf(relPath) {
+    return relPath.split(/[\\/]/).filter((s) => s.length > 0 && s !== '.');
+}
+/** True for dotfiles (like .termi.json) anywhere in the path. */
+function hasDotSegment(relPath) {
+    return segmentsOf(relPath).some((s) => s.startsWith('.'));
+}
+/** True for vendored engine files like kaplay.mjs. */
+export function isVendorFile(relPath) {
+    const segs = segmentsOf(relPath);
+    const last = segs.length > 0 ? segs[segs.length - 1] : undefined;
+    return last !== undefined && vendorEngineFiles.has(last);
+}
+/**
+ * Lists kid files under a directory. Excludes TERMI.md, dotfiles
+ * (which covers .termi.json), and vendored engine files.
+ */
+function walkKidFiles(dir) {
+    const out = [];
+    const visit = (current, relParts) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const childParts = [...relParts, entry.name];
+            const childAbs = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                visit(childAbs, childParts);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const relPath = childParts.join('/');
+            if (relPath === notesFileName)
+                continue;
+            if (vendorEngineFiles.has(relPath))
+                continue;
+            let bytes = 0;
+            try {
+                bytes = fs.statSync(childAbs).size;
+            }
+            catch {
+                continue;
+            }
+            out.push({ relPath, bytes });
+        }
+    };
+    visit(dir, []);
+    out.sort((a, b) => a.relPath.localeCompare(b.relPath));
+    return out;
+}
+/** Flattens a value to one safe line. Leading #, - and > marks are stripped. */
+function sanitizeLine(value) {
+    return value
+        .split(/\r?\n/)
+        .map((line) => line.replace(/^[\s#>-]+/, '').trim())
+        .filter((line) => line.length > 0)
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Renders TERMI.md with the exact template headings.
+ * Field text can never break the heading structure, and the result
+ * stays at or under maxTermiMdLines. Oldest "Built so far" bullets
+ * are dropped first when space runs out.
+ */
+export function renderTermiMd(prettyName, fields) {
+    const title = sanitizeLine(prettyName) || 'My Project';
+    const what = sanitizeLine(fields.whatThisIs) || 'A Termi project.';
+    let files = fields.files.map(sanitizeLine).filter((f) => f.length > 0);
+    let built = fields.builtSoFar.map(sanitizeLine).filter((b) => b.length > 0);
+    if (built.length === 0)
+        built = ['Just getting started.'];
+    const recap = sanitizeLine(fields.recapLine) || 'We are just getting started.';
+    const compose = () => [
+        `# ${title}`,
+        '',
+        '## What this is',
+        what,
+        '',
+        '## Files',
+        ...files.map((f) => `- ${f}`),
+        '',
+        '## Built so far',
+        ...built.map((b) => `- ${b}`),
+        '',
+        '## Recap line',
+        recap,
+        '',
+    ];
+    let lines = compose();
+    while (lines.length > maxTermiMdLines && built.length > 1) {
+        built = built.slice(1);
+        lines = compose();
+    }
+    while (lines.length > maxTermiMdLines && files.length > 1) {
+        files = files.slice(0, -1);
+        lines = compose();
+    }
+    return lines.join('\n');
+}
+/** Pulls the template fields back out of TERMI.md text. */
+export function parseTermiMd(content) {
+    const sections = new Map();
+    let current = null;
+    for (const line of content.split(/\r?\n/)) {
+        const heading = /^##\s+(.+)$/.exec(line);
+        if (heading && heading[1] !== undefined) {
+            current = heading[1].trim().toLowerCase();
+            if (!sections.has(current))
+                sections.set(current, []);
+            continue;
+        }
+        if (/^#\s/.test(line))
+            continue;
+        if (current !== null)
+            sections.get(current)?.push(line);
+    }
+    const grab = (name) => (sections.get(name) ?? []).map((l) => l.trim()).filter((l) => l.length > 0);
+    const stripBullet = (l) => l.replace(/^-\s*/, '').trim();
+    return {
+        whatThisIs: grab('what this is').join(' '),
+        files: grab('files').map(stripBullet),
+        builtSoFar: grab('built so far').map(stripBullet),
+        recapLine: grab('recap line').join(' '),
+    };
+}
+/** Writes a project's metadata file atomically. */
+export function saveProjectMeta(meta) {
+    const target = path.join(projectsDir(), meta.slug, metaFileName);
+    atomicWriteFileSync(target, JSON.stringify(meta, null, 2) + '\n');
+}
+const metaKeys = ['slug', 'prettyName', 'scaffoldId', 'themeId', 'createdAt', 'lastOpenedAt'];
+function loadMeta(slug) {
+    const metaPath = path.join(projectsDir(), slug, metaFileName);
+    let raw;
+    try {
+        raw = fs.readFileSync(metaPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof data !== 'object' || data === null)
+        return null;
+    const record = data;
+    for (const key of metaKeys) {
+        const value = record[key];
+        if (typeof value !== 'string' || value.length === 0)
+            return null;
+    }
+    return {
+        slug, // the directory name is the truth for the slug
+        prettyName: record.prettyName,
+        scaffoldId: record.scaffoldId,
+        themeId: record.themeId,
+        createdAt: record.createdAt,
+        lastOpenedAt: record.lastOpenedAt,
+    };
+}
+function makeContext(meta) {
+    const dir = path.join(projectsDir(), meta.slug);
+    const listKidFiles = () => walkKidFiles(dir);
+    const readFile = (relPath) => {
+        const target = resolveInside(dir, relPath);
+        if (target === null)
+            return null;
+        if (hasDotSegment(relPath))
+            return null;
+        try {
+            if (!fs.statSync(target).isFile())
+                return null;
+            return fs.readFileSync(target, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    };
+    const writeFile = (relPath, content) => {
+        const target = resolveInside(dir, relPath);
+        if (target === null)
+            throw new Error(outsideProjectMessage);
+        if (hasDotSegment(relPath) || isVendorFile(relPath))
+            throw new Error(specialNameMessage);
+        if (Buffer.byteLength(content, 'utf8') > maxKidFileBytes)
+            throw new Error(tooLargeMessage);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, content, 'utf8');
+    };
+    const readTermiMd = () => {
+        try {
+            return fs.readFileSync(path.join(dir, notesFileName), 'utf8');
+        }
+        catch {
+            return renderTermiMd(meta.prettyName, {
+                whatThisIs: '',
+                files: listKidFiles().map((f) => f.relPath),
+                builtSoFar: [],
+                recapLine: '',
+            });
+        }
+    };
+    const updateTermiMd = (fields) => {
+        const current = parseTermiMd(readTermiMd());
+        if (current.files.length === 0) {
+            current.files = listKidFiles().map((f) => f.relPath);
+        }
+        if (fields.whatThisIs !== undefined)
+            current.whatThisIs = fields.whatThisIs;
+        if (fields.builtSoFar !== undefined) {
+            for (const item of fields.builtSoFar) {
+                const clean = sanitizeLine(item);
+                if (clean.length > 0 && !current.builtSoFar.includes(clean)) {
+                    current.builtSoFar.push(clean);
+                }
+            }
+        }
+        if (fields.recapLine !== undefined)
+            current.recapLine = fields.recapLine;
+        atomicWriteFileSync(path.join(dir, notesFileName), renderTermiMd(meta.prettyName, current));
+    };
+    const touch = () => {
+        meta.lastOpenedAt = new Date().toISOString();
+        saveProjectMeta(meta);
+    };
+    return { meta, dir, listKidFiles, readFile, writeFile, readTermiMd, updateTermiMd, touch };
+}
+/** Opens a project by slug. Returns null when it is missing or broken. */
+export function openProject(slug) {
+    if (typeof slug !== 'string' || slug.length === 0)
+        return null;
+    if (slug.includes('/') || slug.includes('\\') || slug.startsWith('.'))
+        return null;
+    const meta = loadMeta(slug);
+    if (meta === null)
+        return null;
+    return makeContext(meta);
+}
+/** All projects with valid metadata, most recently opened first. */
+export function listProjects() {
+    let entries;
+    try {
+        entries = fs.readdirSync(projectsDir(), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const metas = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const meta = loadMeta(entry.name);
+        if (meta !== null)
+            metas.push(meta);
+    }
+    metas.sort((a, b) => {
+        if (a.lastOpenedAt !== b.lastOpenedAt) {
+            return a.lastOpenedAt < b.lastOpenedAt ? 1 : -1;
+        }
+        return a.slug.localeCompare(b.slug);
+    });
+    return metas;
+}

package/dist/providers/errors.js

@@ -0,0 +1,207 @@
+/**
+ * Maps anything a provider call can throw onto the small ProviderError
+ * taxonomy {rate-limit, auth, server, network}. Provider error bodies are
+ * never echoed to the kid; describeForKid only returns T registry copy.
+ */
+import { APICallError, RetryError } from 'ai';
+import { formatResetTime } from '../ui/errors.js';
+import { T } from '../ui/text.js';
+const NETWORK_ERROR_CODES = new Set([
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ENOTFOUND',
+    'ETIMEDOUT',
+    'EAI_AGAIN',
+    'EPIPE',
+    'ENETUNREACH',
+    'EHOSTUNREACH',
+]);
+function isProviderError(err) {
+    if (err === null || typeof err !== 'object') {
+        return false;
+    }
+    const kind = err.kind;
+    return kind === 'rate-limit' || kind === 'auth' || kind === 'server' || kind === 'network';
+}
+function isNetworkCode(code) {
+    return typeof code === 'string' && (NETWORK_ERROR_CODES.has(code) || code.startsWith('UND_ERR'));
+}
+function isNetworkish(err) {
+    if (err === null || typeof err !== 'object') {
+        return false;
+    }
+    const e = err;
+    if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+        return true;
+    }
+    if (isNetworkCode(e.code)) {
+        return true;
+    }
+    if (e.cause !== null && typeof e.cause === 'object') {
+        if (isNetworkCode(e.cause.code)) {
+            return true;
+        }
+    }
+    if (err instanceof TypeError) {
+        // Global fetch surfaces connection failures as TypeError.
+        return true;
+    }
+    if (typeof e.message === 'string' &&
+        /fetch failed|network|socket hang up|getaddrinfo|aborted/i.test(e.message)) {
+        return true;
+    }
+    return false;
+}
+/** Parses "90", "1m30s", "500ms" style values into whole seconds. */
+function parseDurationSeconds(value) {
+    const v = value.trim();
+    if (/^\d+(\.\d+)?$/.test(v)) {
+        return Math.max(0, Math.round(Number(v)));
+    }
+    const re = /(\d+(?:\.\d+)?)(ms|s|m|h|d)/g;
+    let total = 0;
+    let matched = false;
+    let m;
+    while ((m = re.exec(v)) !== null) {
+        const amount = Number(m[1] ?? '0');
+        const unit = m[2] ?? 's';
+        matched = true;
+        switch (unit) {
+            case 'ms':
+                total += amount / 1000;
+                break;
+            case 's':
+                total += amount;
+                break;
+            case 'm':
+                total += amount * 60;
+                break;
+            case 'h':
+                total += amount * 3600;
+                break;
+            case 'd':
+                total += amount * 86400;
+                break;
+        }
+    }
+    return matched ? Math.max(0, Math.round(total)) : undefined;
+}
+function parseRetryAfter(get) {
+    const direct = get('retry-after');
+    if (direct !== null && direct.length > 0) {
+        if (/^\d+(\.\d+)?$/.test(direct.trim())) {
+            return Math.max(0, Math.round(Number(direct)));
+        }
+        const asDate = Date.parse(direct);
+        if (!Number.isNaN(asDate)) {
+            return Math.max(0, Math.round((asDate - Date.now()) / 1000));
+        }
+    }
+    const backendReset = get('x-codex-primary-reset-after-seconds');
+    if (backendReset !== null && /^\d+(\.\d+)?$/.test(backendReset.trim())) {
+        return Math.max(0, Math.round(Number(backendReset)));
+    }
+    for (const name of [
+        'x-ratelimit-reset-after',
+        'x-ratelimit-reset-requests',
+        'x-ratelimit-reset-tokens',
+    ]) {
+        const value = get(name);
+        if (value !== null && value.length > 0) {
+            const parsed = parseDurationSeconds(value);
+            if (parsed !== undefined) {
+                return parsed;
+            }
+        }
+    }
+    return undefined;
+}
+function getterFromRecord(headers) {
+    if (headers === undefined) {
+        return () => null;
+    }
+    const map = new Map();
+    for (const [key, value] of Object.entries(headers)) {
+        map.set(key.toLowerCase(), value);
+    }
+    return (name) => map.get(name.toLowerCase()) ?? null;
+}
+function getterFromUnknown(headers) {
+    if (headers instanceof Headers) {
+        return (name) => headers.get(name);
+    }
+    if (headers !== null && typeof headers === 'object' && !Array.isArray(headers)) {
+        const record = {};
+        for (const [key, value] of Object.entries(headers)) {
+            if (typeof value === 'string') {
+                record[key] = value;
+            }
+        }
+        return getterFromRecord(record);
+    }
+    return () => null;
+}
+function fromStatus(status, get) {
+    if (status === 429) {
+        const retryAfter = parseRetryAfter(get);
+        return retryAfter !== undefined ? { kind: 'rate-limit', retryAfter } : { kind: 'rate-limit' };
+    }
+    if (status === 401 || status === 403) {
+        return { kind: 'auth' };
+    }
+    if (status >= 500) {
+        return { kind: 'server' };
+    }
+    return { kind: 'server' };
+}
+/** Classifies any thrown value from a provider call into a ProviderError. */
+export function classifyProviderError(err) {
+    if (isProviderError(err)) {
+        return err;
+    }
+    // The AI SDK wraps the real failure in a RetryError once retries run out.
+    // Classify the last underlying error so a 429 still shows the quota screen.
+    if (RetryError.isInstance(err) && err.lastError !== undefined) {
+        return classifyProviderError(err.lastError);
+    }
+    if (APICallError.isInstance(err)) {
+        if (err.statusCode !== undefined) {
+            return fromStatus(err.statusCode, getterFromRecord(err.responseHeaders));
+        }
+        return { kind: 'network' };
+    }
+    if (err instanceof Response) {
+        return fromStatus(err.status, (name) => err.headers.get(name));
+    }
+    if (err !== null && typeof err === 'object') {
+        const o = err;
+        const status = typeof o.statusCode === 'number'
+            ? o.statusCode
+            : typeof o.status === 'number'
+                ? o.status
+                : undefined;
+        if (status !== undefined) {
+            return fromStatus(status, getterFromUnknown(o.responseHeaders ?? o.headers));
+        }
+    }
+    if (isNetworkish(err)) {
+        return { kind: 'network' };
+    }
+    return { kind: 'server' };
+}
+/** Returns the kid copy from the T registry for this error. */
+export function describeForKid(err) {
+    const classified = classifyProviderError(err);
+    switch (classified.kind) {
+        case 'rate-limit':
+            return classified.retryAfter !== undefined
+                ? T.quota.message.replace('{time}', formatResetTime(classified.retryAfter))
+                : T.quota.messageNoTime;
+        case 'auth':
+            return T.errors.auth;
+        case 'server':
+            return T.errors.server;
+        case 'network':
+            return T.errors.network;
+    }
+}