atris 3.17.0 → 3.22.0

package/lib/memory-view.js

@@ -0,0 +1,95 @@
+// Memory view — another way to look at memory updates. Reads the workspace's
+// compounding memory (lessons.md, learnings.jsonl, task projection) and builds a
+// content spec rendered as a beautiful HTML page by lib/html-render.
+//
+// Pure-ish: file reads in, a { theme, brand, slides } spec out. Anti-slop by
+// construction (the renderer sanitizes, so em dashes in the raw lessons file
+// never reach the page).
+
+const fs = require('fs');
+const path = require('path');
+
+// "- **[2026-06-18] some-id** — pass — text..." -> { date, id, status, text }
+function parseLessons(text) {
+  const out = [];
+  for (const line of String(text || '').split('\n')) {
+    const m = line.match(/^-\s*\*\*\[([^\]]+)\]\s*([^*]+?)\*\*\s*[—:-]*\s*(pass|fail)?\s*[—:-]*\s*(.*)$/i);
+    if (!m) continue;
+    out.push({ date: m[1].trim(), id: m[2].trim(), status: (m[3] || '').toLowerCase(), text: m[4].trim() });
+  }
+  return out; // append-only file: oldest first
+}
+
+function parseLearnings(text) {
+  const out = [];
+  for (const line of String(text || '').split('\n')) {
+    if (!line.trim()) continue;
+    try { const j = JSON.parse(line); out.push({ ts: j.ts, type: j.type, key: j.key, insight: j.insight }); } catch {}
+  }
+  return out;
+}
+
+function readFileSafe(p) { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } }
+
+function readTaskCounts(root) {
+  try {
+    const j = JSON.parse(readFileSafe(path.join(root, '.atris', 'state', 'tasks.projection.json')));
+    const tasks = Array.isArray(j.tasks) ? j.tasks : [];
+    const by = (s) => tasks.filter((t) => (t.status || '').toLowerCase() === s).length;
+    return { total: tasks.length, done: by('done') + by('accepted'), active: by('active') + by('in_progress'), review: by('review') + by('ready') };
+  } catch { return null; }
+}
+
+function gatherMemory(root = process.cwd()) {
+  const lessons = parseLessons(readFileSafe(path.join(root, 'atris', 'lessons.md')));
+  const learnings = parseLearnings(readFileSafe(path.join(root, 'atris', 'learnings.jsonl')));
+  const tasks = readTaskCounts(root);
+  return { lessons, learnings, tasks };
+}
+
+function clip(s, n) { s = String(s || ''); return s.length > n ? s.slice(0, n - 1).trimEnd() + '…' : s; }
+function titleize(id) { return String(id || '').replace(/[-_]+/g, ' ').trim(); }
+function plural(n, word) { return `${n} ${word}${n === 1 ? '' : 's'}`; }
+
+function buildMemorySpec(root = process.cwd(), opts = {}) {
+  const theme = opts.theme || 'atris';
+  const brand = { name: opts.brand || 'Atris', accent: '.' };
+  const { lessons, learnings, tasks } = gatherMemory(root);
+  const recent = lessons.slice(-8).reverse(); // newest first
+
+  const slides = [];
+  slides.push({
+    type: 'title',
+    headline: 'What the workspace **learned**',
+    sub: `${plural(lessons.length, 'lesson')} and ${plural(learnings.length, 'note')} compounded into memory${tasks ? `, ${plural(tasks.done, 'task')} done` : ''}.`,
+  });
+  slides.push({ type: 'bignumber', number: String(lessons.length), label: 'lessons compounded into the workspace' });
+
+  if (recent.length) {
+    slides.push({
+      type: 'columns', heading: 'Most recent lessons',
+      columns: recent.slice(0, 3).map((l) => ({ h: titleize(l.id), b: clip(l.text, 150) })),
+    });
+    slides.push({
+      type: 'panel', heading: 'Memory updates', sub: 'Lessons and notes, newest first.',
+      panel: {
+        header: { title: 'Recent updates', meta: `${recent.length} shown` },
+        rows: recent.map((l, i) => ({
+          title: titleize(l.id), sub: l.date,
+          value: l.status || 'note', sev: l.status === 'fail' ? 0 : (l.status === 'pass' ? 2 : 1),
+          active: i === 0,
+        })),
+      },
+    });
+  }
+  if (learnings.length) {
+    slides.push({
+      type: 'columns', heading: 'Notes from the field',
+      columns: learnings.slice(-3).reverse().map((n) => ({ h: titleize(n.key || n.type || 'note'), b: clip(n.insight, 150) })),
+    });
+  }
+  slides.push({ type: 'close', tagline: 'Memory lives in the filesystem, not the model.', footer: `${brand.name} workspace memory` });
+  return { theme, brand, slides };
+}
+
+module.exports = { buildMemorySpec, gatherMemory, parseLessons, parseLearnings, readTaskCounts };

package/lib/site.js

@@ -0,0 +1,114 @@
+// Static site generator — point it at a folder of markdown (docs, your wiki,
+// memory) and get a beautiful, navigable HTML site in the design system.
+// Builds on lib/deck-from-md (parse) + lib/html-render (render).
+//
+// buildSite(input, opts) -> { outDir, indexPath, pages }. Pure file I/O.
+
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const { parseMarkdownToSpec } = require('./deck-from-md');
+const { renderHtml, THEMES: BUILTIN } = require('./html-render');
+const { mergedThemes } = require('./theme');
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', 'coverage', '.cache']);
+const MD_EXTS = new Set(['.md', '.mdx']);
+
+function collectMd(input) {
+  const stat = fs.statSync(input);
+  if (stat.isFile()) return MD_EXTS.has(path.extname(input)) ? [input] : [];
+  const out = [];
+  (function walk(dir) {
+    for (const name of fs.readdirSync(dir).sort()) {
+      if (name.startsWith('.')) continue;
+      const full = path.join(dir, name);
+      let st; try { st = fs.statSync(full); } catch { continue; }
+      if (st.isDirectory()) { if (!SKIP_DIRS.has(name)) walk(full); }
+      else if (MD_EXTS.has(path.extname(name))) out.push(full);
+    }
+  })(input);
+  return out;
+}
+
+function slugFor(file, root) {
+  // base = the dir the site was built from (root may be a dir or a single .md file)
+  const base = MD_EXTS.has(path.extname(root)) ? path.dirname(root) : root;
+  const rel = path.relative(base, file).replace(/\.[^.]+$/, '');
+  return rel.replace(/[\\/]+/g, '-').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'page';
+}
+
+function firstHeading(md) {
+  const m = md.match(/^#{1,2}\s+(.+)$/m);
+  return m ? m[1].replace(/\*\*/g, '').trim() : null;
+}
+function firstParagraph(md) {
+  const body = md.replace(/^---\n[\s\S]*?\n---\n/, '');
+  for (const line of body.split('\n')) {
+    const t = line.trim();
+    if (!t || /^[#<>]/.test(t) || /^[-*+]/.test(t) || /^\|/.test(t) || /^```/.test(t)) continue;
+    return t.replace(/\*\*/g, '');
+  }
+  return '';
+}
+function clip(s, n) { s = String(s || ''); return s.length > n ? s.slice(0, n - 1).trimEnd() + '…' : s; }
+function titleFromSlug(slug) { return slug.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()); }
+
+function buildSite(input, opts = {}) {
+  const THEMES = mergedThemes(BUILTIN, opts.root || process.cwd());
+  const theme = THEMES[opts.theme] ? opts.theme : 'atris';
+  const siteTitle = opts.title || 'Atris';
+  const accent = opts.accent || '.';
+  const outDir = opts.out || 'dist';
+  const files = collectMd(input);
+  fs.mkdirSync(outDir, { recursive: true });
+  const nav = { home: 'index.html', label: siteTitle, accent };
+
+  const pages = [];
+  const seen = new Set();
+  for (const file of files) {
+    const md = fs.readFileSync(file, 'utf8');
+    const spec = parseMarkdownToSpec(md, { theme });
+    if (!THEMES[spec.theme]) spec.theme = theme;
+    let slug = slugFor(file, input);
+    while (seen.has(slug)) slug += '-1';
+    seen.add(slug);
+    const title = firstHeading(md) || titleFromSlug(slug);
+    const summary = firstParagraph(md);
+    const outFile = path.join(outDir, slug + '.html');
+    fs.writeFileSync(outFile, renderHtml(spec, { title, nav, themes: THEMES }));
+    pages.push({ src: file, out: outFile, href: slug + '.html', title, summary });
+  }
+
+  const indexSpec = {
+    theme, brand: { name: siteTitle, accent },
+    slides: [
+      { type: 'title', headline: opts.headline || `${siteTitle} **docs**`, sub: opts.sub || `${pages.length} page${pages.length === 1 ? '' : 's'}, one design system.` },
+      { type: 'toc', heading: 'Pages', items: pages.map((p) => ({ href: p.href, title: p.title, summary: clip(p.summary, 120) })) },
+      { type: 'close', tagline: opts.tagline || 'One workspace, one design system.', footer: siteTitle },
+    ],
+  };
+  const indexPath = path.join(outDir, 'index.html');
+  fs.writeFileSync(indexPath, renderHtml(indexSpec, { title: siteTitle, themes: THEMES }));
+  return { outDir, indexPath, pages };
+}
+
+const MIME = { '.html': 'text/html; charset=utf-8', '.css': 'text/css', '.js': 'text/javascript', '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg', '.svg': 'image/svg+xml' };
+
+// minimal static preview server for a built site dir (no deps)
+function serveSite(dir, port = 4321) {
+  const root = path.resolve(dir);
+  const server = http.createServer((req, res) => {
+    let rel = decodeURIComponent((req.url || '/').split('?')[0]);
+    if (rel.endsWith('/')) rel += 'index.html';
+    const file = path.normalize(path.join(root, rel));
+    if (!file.startsWith(root)) { res.writeHead(403); res.end('forbidden'); return; }
+    fs.readFile(file, (err, data) => {
+      if (err) { res.writeHead(404, { 'Content-Type': 'text/plain' }); res.end('not found'); return; }
+      res.writeHead(200, { 'Content-Type': MIME[path.extname(file)] || 'application/octet-stream' });
+      res.end(data);
+    });
+  });
+  return new Promise((resolve) => server.listen(port, () => resolve({ server, url: `http://localhost:${port}` })));
+}
+
+module.exports = { buildSite, serveSite, collectMd, slugFor, firstHeading, firstParagraph };

package/lib/slides-deck.js

@@ -220,8 +220,9 @@ const ARCHE = {
 };
 
 // ---------- public: spec -> requests ----------
-function buildDeck(spec) {
-  const theme = THEMES[spec.theme] || THEMES.terminal;
+function buildDeck(spec, opts = {}) {
+  const themes = opts.themes || THEMES;
+  const theme = themes[spec.theme] || THEMES.terminal;
   const ctx = makeCtx(theme);
   const slideIds = [];
   (spec.slides || []).forEach((s, i) => {

package/lib/theme.js

@@ -0,0 +1,264 @@
+// Brand themes — a project defines its own theme in .atris/theme.json and every
+// renderer (deck, HTML, site, memory view) uses it. Compounds like slop rules:
+// describe your brand once, every deck and page is on-brand.
+//
+// theme.json shapes (both accepted):
+//   { "color": { "accent": "#00A88F", "bg": "#0B1410" }, "fonts": { "display": "Fraunces" } }
+//   { "themes": { "acme": { "color": {...} }, "acme-light": { "color": {...} } } }
+// Partial themes inherit every missing token from the base (a full warm-dark theme).
+
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT_THEME_FILE = path.join('.atris', 'theme.json');
+
+// full base so a project can define just an accent + bg and inherit the rest
+const BASE = {
+  fonts: { display: 'Fraunces', body: 'Outfit', mono: 'ui-monospace, SFMono-Regular, monospace' },
+  color: {
+    bg: '#141110', panel: '#1E1915', panelAlt: '#2C2520', line: '#3D332D',
+    ink: '#EAE3D9', soft: '#A39B92', faint: '#7C736B',
+    accent: '#F59E0B', accent2: '#FBBF24', onAccent: '#141110',
+    sev: ['#F59E0B', '#FBBF24', '#7F97A4'],
+  },
+};
+
+const COLOR_ROLES = ['bg', 'panel', 'panelAlt', 'line', 'ink', 'soft', 'faint', 'accent', 'accent2', 'onAccent'];
+
+function normalizeTheme(t, base = BASE) {
+  const src = t && typeof t === 'object' ? t : {};
+  return {
+    fonts: { ...base.fonts, ...(src.fonts || {}) },
+    color: { ...base.color, ...(src.color || {}), sev: (src.color && src.color.sev) || base.color.sev },
+  };
+}
+
+function isValidThemeShape(t) {
+  if (!t || typeof t !== 'object') return false;
+  const hasColor = t.color && typeof t.color === 'object';
+  const hasFonts = t.fonts && typeof t.fonts === 'object';
+  return Boolean(hasColor || hasFonts);
+}
+
+// returns { name: normalizedTheme } from .atris/theme.json (or {} if none/bad)
+function loadProjectThemes(root = process.cwd()) {
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(path.join(root, PROJECT_THEME_FILE), 'utf8')); }
+  catch { return {}; }
+  const out = {};
+  if (raw && raw.themes && typeof raw.themes === 'object') {
+    for (const [name, t] of Object.entries(raw.themes)) if (isValidThemeShape(t)) out[name] = normalizeTheme(t);
+  } else if (isValidThemeShape(raw)) {
+    out[raw.name || 'brand'] = normalizeTheme(raw);
+  }
+  return out;
+}
+
+// merge built-in themes with project themes (project wins on name collision)
+function mergedThemes(builtin, root = process.cwd()) {
+  return { ...builtin, ...loadProjectThemes(root) };
+}
+
+function writeStarterTheme(root = process.cwd()) {
+  const file = path.join(root, PROJECT_THEME_FILE);
+  if (fs.existsSync(file)) return { file, already: true };
+  const starter = {
+    name: 'brand',
+    color: { accent: '#00A88F', accent2: '#3FD0B6', bg: '#0B1410', ink: '#E8F0EC' },
+    fonts: { display: 'Fraunces', body: 'Outfit' },
+  };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(starter, null, 2) + '\n');
+  return { file, already: false };
+}
+
+// ---------- color math (WCAG contrast — the tasteful guardrail) ----------
+function hexToRgb(hex) {
+  const h = String(hex == null ? '' : hex).trim().replace(/^#/, '');
+  const full = h.length === 3 ? h.split('').map((c) => c + c).join('') : h;
+  if (!/^[0-9a-fA-F]{6}$/.test(full)) return null;
+  return { r: parseInt(full.slice(0, 2), 16), g: parseInt(full.slice(2, 4), 16), b: parseInt(full.slice(4, 6), 16) };
+}
+
+function isHex(hex) { return hexToRgb(hex) != null; }
+
+function normHex(hex) {
+  const c = hexToRgb(hex);
+  if (!c) return null;
+  return '#' + [c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, '0')).join('').toUpperCase();
+}
+
+function relLuminance(hex) {
+  const c = hexToRgb(hex);
+  if (!c) return 0;
+  const lin = [c.r, c.g, c.b].map((v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2];
+}
+
+function contrastRatio(a, b) {
+  const hi = Math.max(relLuminance(a), relLuminance(b));
+  const lo = Math.min(relLuminance(a), relLuminance(b));
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+// the readable ink to drop on top of a solid color (near-black vs near-white)
+function bestOnColor(hex, dark = '#141110', light = '#FFFFFF') {
+  return contrastRatio(hex, dark) >= contrastRatio(hex, light) ? dark : light;
+}
+
+// blend two hex colors, t in [0,1] toward `b`
+function mix(a, b, t) {
+  const ca = hexToRgb(a), cb = hexToRgb(b);
+  if (!ca || !cb) return normHex(a) || '#000000';
+  const m = (x, y) => Math.round(x + (y - x) * t);
+  return '#' + [m(ca.r, cb.r), m(ca.g, cb.g), m(ca.b, cb.b)].map((v) => v.toString(16).padStart(2, '0')).join('').toUpperCase();
+}
+
+// ---------- the tasteful vocabulary (moods, fonts) used by `atris theme create` ----------
+const FONT_PERSONALITIES = {
+  'editorial-serif': { display: 'Fraunces', body: 'Outfit', mono: 'IBM Plex Mono' },
+  'clean-sans': { display: 'Space Grotesk', body: 'Outfit', mono: 'IBM Plex Mono' },
+  'mono-forward': { display: 'Space Grotesk', body: 'IBM Plex Mono', mono: 'IBM Plex Mono' },
+};
+
+// each mood is hand-tuned neutral scaffolding + a font pairing + curated accents.
+// the user picks a feeling; we keep the surface tasteful and let their accent lead.
+const MOODS = {
+  editorial: {
+    blurb: 'warm, literary, considered — Fraunces headlines on calm paper',
+    defaultMode: 'dark', fonts: 'editorial-serif',
+    swatches: ['#B5572E', '#D98E5C', '#9E3B2E', '#C08552'],
+    modes: {
+      dark:  { bg: '#1E1A16', panel: '#261F19', panelAlt: '#322820', line: '#443629', ink: '#EDE4D6', soft: '#B0A595', faint: '#837868' },
+      light: { bg: '#FBF8F2', panel: '#F2ECE0', panelAlt: '#E9E1D2', line: '#DCD2C0', ink: '#2A241D', soft: '#6B6256', faint: '#938A7C' },
+    },
+  },
+  technical: {
+    blurb: 'cool, precise, engineered — Space Grotesk on slate, mono accents',
+    defaultMode: 'dark', fonts: 'clean-sans',
+    swatches: ['#3B82F6', '#06B6D4', '#6366F1', '#14B8A6'],
+    modes: {
+      dark:  { bg: '#0E1116', panel: '#161B22', panelAlt: '#1C2330', line: '#2A3340', ink: '#E6EDF3', soft: '#9DA7B3', faint: '#6B7682' },
+      light: { bg: '#F7F9FB', panel: '#EEF2F6', panelAlt: '#E3E9F0', line: '#D2DAE3', ink: '#1A2230', soft: '#5A6675', faint: '#8A95A3' },
+    },
+  },
+  noir: {
+    blurb: 'high-contrast, near-black, one electric accent — confident and stark',
+    defaultMode: 'dark', forceMode: 'dark', fonts: 'clean-sans',
+    swatches: ['#C8FF00', '#FF2D78', '#FFB000', '#7DD3FC'],
+    modes: {
+      dark: { bg: '#0A0A0B', panel: '#131316', panelAlt: '#1B1B20', line: '#2A2A30', ink: '#F4F4F5', soft: '#A1A1AA', faint: '#6E6E76' },
+    },
+  },
+  paper: {
+    blurb: 'calm, light, low-key — ink on cream, nothing shouting',
+    defaultMode: 'light', forceMode: 'light', fonts: 'editorial-serif',
+    swatches: ['#2F4858', '#5B7553', '#B5572E', '#6B4E71'],
+    modes: {
+      light: { bg: '#FBF8F2', panel: '#F2ECE0', panelAlt: '#E9E1D2', line: '#DCD2C0', ink: '#2A241D', soft: '#6B6256', faint: '#938A7C' },
+    },
+  },
+  vivid: {
+    blurb: 'saturated, playful, energetic — a bold accent that carries the page',
+    defaultMode: 'dark', fonts: 'clean-sans',
+    swatches: ['#FF5C5C', '#8B5CF6', '#10B981', '#F59E0B'],
+    modes: {
+      dark:  { bg: '#121016', panel: '#1B1822', panelAlt: '#251F30', line: '#352C42', ink: '#F2EEF7', soft: '#ADA3BC', faint: '#7D7388' },
+      light: { bg: '#FCFAFF', panel: '#F3EFF9', panelAlt: '#E9E2F2', line: '#DAD0E6', ink: '#221B2C', soft: '#645A72', faint: '#938A9F' },
+    },
+  },
+};
+
+const MOOD_NAMES = Object.keys(MOODS);
+
+function resolveFonts(spec, mood) {
+  const m = MOODS[mood] || MOODS.editorial;
+  if (spec && typeof spec === 'object') return { ...FONT_PERSONALITIES[m.fonts], ...spec };
+  const key = spec && FONT_PERSONALITIES[spec] ? spec : m.fonts;
+  return { ...FONT_PERSONALITIES[key] };
+}
+
+function resolveMode(mood, mode) {
+  const m = MOODS[mood] || MOODS.editorial;
+  if (m.forceMode) return m.forceMode;
+  if ((mode === 'light' || mode === 'dark') && m.modes[mode]) return mode;
+  return m.defaultMode;
+}
+
+// pure: tasteful answers -> a full, normalized theme. The heart of `atris theme create`.
+//   answers = { mood, mode?, accent?, accent2?, fonts? }
+function buildTheme(answers = {}) {
+  const moodKey = MOODS[answers.mood] ? answers.mood : 'editorial';
+  const mood = MOODS[moodKey];
+  const mode = resolveMode(moodKey, answers.mode);
+  const surface = mood.modes[mode];
+
+  const accent = normHex(answers.accent) || mood.swatches[0];
+  const accent2 = normHex(answers.accent2) || mix(accent, surface.ink, 0.28);
+  const onAccent = bestOnColor(accent);
+  const fonts = resolveFonts(answers.fonts, moodKey);
+
+  return normalizeTheme({
+    color: { ...surface, accent, accent2, onAccent, sev: [accent, accent2, surface.faint] },
+    fonts,
+  });
+}
+
+// readability guardrail — human messages for low-contrast choices (empty array = clean)
+function themeWarnings(theme) {
+  const c = normalizeTheme(theme).color;
+  const warn = [];
+  const body = contrastRatio(c.ink, c.bg);
+  if (body < 4.5) warn.push(`body text (ink on bg) is ${body.toFixed(1)}:1 — below the 4.5:1 readable floor`);
+  const onAcc = contrastRatio(c.onAccent, c.accent);
+  if (onAcc < 4.5) warn.push(`text on the accent is ${onAcc.toFixed(1)}:1 — below 4.5:1`);
+  const accentBg = contrastRatio(c.accent, c.bg);
+  if (accentBg < 2.0) warn.push(`the accent barely separates from the background (${accentBg.toFixed(1)}:1) — pick a bolder color`);
+  return warn;
+}
+
+// write/replace a named theme in .atris/theme.json (always the themes-map form),
+// preserving every other theme. Throws (code EBADTHEME) if an existing file is present
+// but unparseable, so we never clobber a hand-edited brand file.
+function upsertProjectTheme(name, theme, root = process.cwd(), recipe = null) {
+  const themeName = (String(name == null ? '' : name).trim()) || 'brand';
+  const file = path.join(root, PROJECT_THEME_FILE);
+  let themes = {};
+  if (fs.existsSync(file)) {
+    let raw;
+    try { raw = JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch { const e = new Error(`${PROJECT_THEME_FILE} is not valid JSON — fix or remove it before saving`); e.code = 'EBADTHEME'; throw e; }
+    if (raw && raw.themes && typeof raw.themes === 'object') themes = { ...raw.themes };
+    else if (isValidThemeShape(raw)) themes[raw.name || 'brand'] = { name: raw.name, color: raw.color, fonts: raw.fonts };
+  }
+  const existed = Object.prototype.hasOwnProperty.call(themes, themeName);
+  const t = normalizeTheme(theme);
+  // recipe = the high-level answers (mood/mode/accent); inert to renderers, lets `theme edit` re-seed
+  const record = { name: themeName };
+  if (recipe && typeof recipe === 'object') record.recipe = recipe;
+  record.color = t.color; record.fonts = t.fonts;
+  themes[themeName] = record;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ themes }, null, 2) + '\n');
+  return { file, name: themeName, action: existed ? 'updated' : 'created', count: Object.keys(themes).length };
+}
+
+// the saved high-level answers for a theme, if present (for `theme edit` pre-fill)
+function loadThemeRecipe(name, root = process.cwd()) {
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(path.join(root, PROJECT_THEME_FILE), 'utf8')); }
+  catch { return null; }
+  const rec = raw && raw.themes && raw.themes[name];
+  return rec && rec.recipe && typeof rec.recipe === 'object' ? rec.recipe : null;
+}
+
+module.exports = {
+  BASE, COLOR_ROLES, normalizeTheme, isValidThemeShape, loadProjectThemes, mergedThemes,
+  writeStarterTheme, PROJECT_THEME_FILE,
+  hexToRgb, isHex, normHex, relLuminance, contrastRatio, bestOnColor, mix,
+  FONT_PERSONALITIES, MOODS, MOOD_NAMES, resolveFonts, resolveMode,
+  buildTheme, themeWarnings, upsertProjectTheme, loadThemeRecipe,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.17.0",
+  "version": "3.22.0",
   "main": "bin/atris.js",
   "bin": {
     "atris": "bin/atris.js",