@pugi/cli 0.1.0-beta.22 → 0.1.0-beta.24

package/dist/core/theme/context.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Leak L30 (2026-05-27) — Theme React context + `useTheme` hook.
+ *
+ * Threads the active theme's color tokens through the Ink component
+ * tree so individual components do not need to call `resolveTheme()`
+ * on every render. The provider is mounted once at the top of the
+ * REPL Ink tree (in `repl-render.tsx`); standalone CLI commands
+ * (`pugi doctor`, `pugi theme`) can mount the provider themselves
+ * when they print colored output.
+ *
+ * Design contract:
+ *
+ *   - The hook returns the resolved `ThemeColors` token set, NOT the
+ *     full `ResolvedTheme`. Component code only needs the color
+ *     values; the slug + source label live on the parent (the
+ *     `/theme` table renders them, individual components do not).
+ *
+ *   - When no provider is mounted, `useTheme()` returns the
+ *     `default` preset's colors. This is intentional — pure render
+ *     components that get imported into a test without a wrapper
+ *     should not crash. The behaviour matches `useContext` semantics
+ *     of every other Pugi context (`SessionContext`, `WorkspaceContext`).
+ *
+ *   - The provider takes the *resolved slug* (not the file path).
+ *     The caller is responsible for calling `resolveTheme()` once at
+ *     mount time and re-mounting on slug change. We deliberately do
+ *     NOT poll the config file from inside the provider — Ink
+ *     re-renders on every prop change would otherwise risk
+ *     reentrancy with the input box's raw-mode handler.
+ *
+ *   - The provider value is memoised against the slug so child
+ *     components see referentially-equal colors across re-renders
+ *     when the slug has not changed. This matters for `useMemo` /
+ *     `useEffect` dependency lists in downstream consumers.
+ *
+ * Test surface: `test/commands/theme-context.spec.tsx` mounts the
+ * provider with each preset slug, asserts the hook returns the
+ * matching color tokens, and asserts the default-when-no-provider
+ * fallback path.
+ */
+import { createContext, useContext, useMemo, } from 'react';
+import { DEFAULT_THEME, getThemeColors, } from './presets.js';
+/**
+ * The context default is the `default` preset's colors. Components
+ * imported into a test or non-REPL render that lack a provider
+ * therefore behave as if the operator never overrode the theme.
+ */
+const ThemeContext = createContext({
+    slug: DEFAULT_THEME,
+    colors: getThemeColors(DEFAULT_THEME),
+});
+/**
+ * Mount the theme provider with a resolved slug. The provider
+ * memoises the color lookup against `slug` so child components see
+ * referentially-stable colors across re-renders.
+ *
+ * Production wiring (`tui/repl-render.tsx`):
+ *
+ *   const resolved = resolveTheme({ workspaceRoot, env: process.env });
+ *   render(<ThemeProvider slug={resolved.slug}><Repl … /></ThemeProvider>);
+ *
+ * The wrapper is intentionally a thin pass-through (no side effects,
+ * no `useEffect`) so it can be mounted from any Ink renderer
+ * including the one-shot CLI surfaces in `runtime/cli.ts`.
+ */
+export function ThemeProvider({ slug, children }) {
+    const value = useMemo(() => ({ slug, colors: getThemeColors(slug) }), [slug]);
+    return _jsx(ThemeContext.Provider, { value: value, children: children });
+}
+/**
+ * Hook that returns the active theme's color tokens.
+ *
+ * Components reference tokens by semantic name (`accent`, `success`,
+ * `error`) instead of literal hex codes so a theme flip is a
+ * single-write operation. Tests can mount any preset without
+ * touching the disk; the production REPL resolves once at mount and
+ * re-mounts on `/theme <name>`.
+ */
+export function useTheme() {
+    return useContext(ThemeContext).colors;
+}
+/**
+ * Debug helper — returns the currently-active slug + colors. Used by
+ * the `/theme` slash command's preview path; production components
+ * should call `useTheme()` so the boundary stays narrow.
+ */
+export function useThemeDebug() {
+    return useContext(ThemeContext);
+}
+//# sourceMappingURL=context.js.map

package/dist/core/theme/presets.js

@@ -0,0 +1,228 @@
+/**
+ * Leak L30 (2026-05-27) — TUI color theme presets.
+ *
+ * Sibling to `core/output-style/presets.ts` but addressing a different
+ * layer of the operator surface:
+ *
+ *   - `output-style` steers the engine's PROSE register (terse /
+ *     explanatory / russian-formal / casual). It compiles into a rule
+ *     block appended to the system prompt; the model adjusts voice.
+ *
+ *   - `theme` steers the LOCAL TUI's color palette. It never reaches
+ *     the engine; only the Ink components in `tui/*.tsx` read it. The
+ *     operator can run any output-style under any theme — the two
+ *     surfaces are orthogonal.
+ *
+ * Design contract:
+ *
+ *   - The catalogue is a closed set of 4 entries — `default`, `dark`,
+ *     `light`, `colorblind`. The slug union is intentionally tight so
+ *     the operator can hold the full surface in working memory and so
+ *     Ink consumers can switch on every slug without a fall-through.
+ *
+ *   - Each preset defines 7 semantic color tokens (foreground, muted,
+ *     accent, success, warning, error, background). Ink components
+ *     reference these tokens via `useTheme()` instead of inlining
+ *     literal hex codes. The brand accent `#3da9fc` is preserved in
+ *     `default` so the existing header / splash chrome reads
+ *     identically when no override is active.
+ *
+ *   - `colorblind` is tuned for deuteranopia (red-green color
+ *     blindness, ~5% of male population). Status colors are mapped to
+ *     a blue-yellow axis (`success` cyan, `warning` yellow, `error`
+ *     bright-magenta) so the OK/WARN/ERROR triplet remains
+ *     distinguishable without red/green discrimination. The accent is
+ *     also shifted to bright-yellow `#ffd166` so it does not collide
+ *     with the success cue.
+ *
+ *   - `light` uses darker foreground + lighter accent values so the
+ *     palette reads on a white terminal background. Most operators
+ *     run dark terminals, so `dark` is closer to the default;
+ *     `light` exists specifically for screen-share / projector demos
+ *     where the room is bright.
+ *
+ *   - All color values are 6-digit hex strings prefixed with `#`. Ink's
+ *     `Text color` prop accepts hex strings directly; we deliberately
+ *     do NOT use named colors like `green` / `red` so the palette is
+ *     fully under operator control. The Ink-named fallback for OK/
+ *     WARN/ERROR exists separately in `doctor-table.tsx` legacy code
+ *     and gets superseded once the theme context is wired.
+ *
+ * Test surface: `test/commands/theme-presets.spec.ts` exercises
+ * catalogue invariants (4 entries, unique slugs, every preset has all
+ * 7 tokens, hex format, colorblind palette avoids red-green for
+ * status), the `isThemeSlug` predicate, and the `compileSampleRow`
+ * helper used by the preview table.
+ */
+/**
+ * The closed list of theme slugs in catalogue order. Mirror used by
+ * the CLI surface (`/theme` table, `pugi theme --list`) so the
+ * operator sees themes in a stable order regardless of iteration
+ * order of the keyed catalogue.
+ */
+export const THEME_SLUGS = Object.freeze([
+    'default',
+    'dark',
+    'light',
+    'colorblind',
+]);
+/**
+ * Default slug used when no workspace-/user-level preference is set.
+ * Exported so `state.ts` and the CLI handler share one constant.
+ */
+export const DEFAULT_THEME = 'default';
+/**
+ * Catalogue keyed by slug. Frozen so callers cannot mutate the
+ * shared rows; the CLI handler returns slugs, not preset references,
+ * to keep the boundary clean.
+ *
+ * Color choices:
+ *
+ *   - `default` accent `#3da9fc` is the existing Pugi blue baked into
+ *     `repl.tsx` header + `/help` palette. Preserved verbatim so the
+ *     default theme reads identically to pre-L30 chrome.
+ *
+ *   - `dark` saturates the brand palette for deep-black terminals
+ *     (true-black iTerm, kitty, alacritty). Accent cyan `#22d3ee`
+ *     pops against `#0a0a0a`; foreground is a near-white `#f5f5f5`
+ *     that does not glare.
+ *
+ *   - `light` inverts the contrast: foreground is `#1a1a1a` (near-
+ *     black), background `#fafafa` (off-white), accent `#1e40af`
+ *     (deep blue, readable on white). Status colors are darkened
+ *     equivalents — `#15803d` green, `#a16207` amber, `#b91c1c`
+ *     deep-red — so they retain saturation on bright backgrounds.
+ *
+ *   - `colorblind` shifts the status axis from red-green to
+ *     blue-yellow. `#0ea5e9` cyan replaces green, `#facc15` yellow
+ *     stays warning, `#d946ef` magenta replaces red. The
+ *     deuteranopia community can distinguish blue from yellow from
+ *     magenta even when red/green collapse. Accent moves to
+ *     `#ffd166` bright-yellow so it does not collide with success
+ *     cyan; we trade brand consistency for accessibility here, which
+ *     is the explicit purpose of the preset.
+ */
+export const THEMES = Object.freeze({
+    default: Object.freeze({
+        slug: 'default',
+        title: 'Default',
+        gloss: 'Current Pugi palette — blue accent on dark terminal.',
+        colors: Object.freeze({
+            foreground: '#e5e7eb',
+            background: '#0f172a',
+            muted: '#94a3b8',
+            accent: '#3da9fc',
+            success: '#22c55e',
+            warning: '#eab308',
+            error: '#ef4444',
+        }),
+    }),
+    dark: Object.freeze({
+        slug: 'dark',
+        title: 'Dark',
+        gloss: 'Saturated palette for deep-black terminals (iTerm, alacritty, kitty).',
+        colors: Object.freeze({
+            foreground: '#f5f5f5',
+            background: '#0a0a0a',
+            muted: '#737373',
+            accent: '#22d3ee',
+            success: '#4ade80',
+            warning: '#fbbf24',
+            error: '#f87171',
+        }),
+    }),
+    light: Object.freeze({
+        slug: 'light',
+        title: 'Light',
+        gloss: 'Inverted palette for projector demos + white-background terminals.',
+        colors: Object.freeze({
+            foreground: '#1a1a1a',
+            background: '#fafafa',
+            muted: '#525252',
+            accent: '#1e40af',
+            success: '#15803d',
+            warning: '#a16207',
+            error: '#b91c1c',
+        }),
+    }),
+    colorblind: Object.freeze({
+        slug: 'colorblind',
+        title: 'Colorblind',
+        gloss: 'High-contrast deuteranopia-safe — status on blue-yellow-magenta axis.',
+        colors: Object.freeze({
+            foreground: '#f5f5f5',
+            background: '#0f172a',
+            muted: '#9ca3af',
+            accent: '#ffd166',
+            success: '#0ea5e9',
+            warning: '#facc15',
+            error: '#d946ef',
+        }),
+    }),
+});
+/**
+ * Type-narrowing predicate. Used by the slash-command parser + state
+ * loader so an unknown string from operator input or a stale config
+ * file degrades to the default theme instead of crashing.
+ */
+export function isThemeSlug(value) {
+    return (typeof value === 'string' && THEME_SLUGS.includes(value));
+}
+/**
+ * Resolve the colors for a slug. Pure lookup; never throws. Callers
+ * pass the slug from `resolveTheme()` so unknown values cannot reach
+ * this helper, but defensive isThemeSlug + DEFAULT_THEME fallback is
+ * still applied so future refactors cannot regress to a runtime
+ * crash on a stale config.
+ */
+export function getThemeColors(slug) {
+    const preset = THEMES[slug] ?? THEMES[DEFAULT_THEME];
+    return preset.colors;
+}
+/**
+ * Render the theme catalogue as a plain-text table for the `/theme`
+ * + `pugi theme` surfaces. Marks the active slug with `*` so the
+ * operator can see at a glance which theme is in effect.
+ *
+ * Pure renderer (no fs, no env). Identical text is emitted from both
+ * the slash dispatcher and the top-level CLI command so operators
+ * trained on one surface read the same table on the other.
+ *
+ * The plain-text variant skips the color-sample preview row — Ink's
+ * `<ThemeTable>` in `tui/theme-table.tsx` renders the sample row
+ * inline using `Text color={preset.colors.accent}` so the operator
+ * can preview each palette before switching.
+ */
+export function renderThemeTable(active) {
+    const slugWidth = Math.max('NAME'.length, ...THEME_SLUGS.map((slug) => slug.length));
+    const header = `${'NAME'.padEnd(slugWidth)}  GLOSS`;
+    const rows = THEME_SLUGS.map((slug) => {
+        const preset = THEMES[slug];
+        const marker = slug === active ? '*' : ' ';
+        return `${marker} ${slug.padEnd(slugWidth)}  ${preset.gloss}`;
+    });
+    return [header, ...rows].join('\n');
+}
+/**
+ * Build the per-row sample text used by `<ThemeTable>`. Pure helper
+ * so the spec can assert the canonical sample copy ("Aa 123 OK WARN
+ * ERROR") without mounting Ink. The TUI component colors each
+ * fragment with the matching token (`foreground`, `accent`, `success`,
+ * `warning`, `error`) — this helper only returns the source strings
+ * the renderer splices in.
+ */
+export function compileSampleRow(slug) {
+    // The strings are slug-independent today; the helper exists so
+    // future presets can ship per-theme sample copy (e.g. localised
+    // OK/ERROR labels for a future `russian-tui` preset) without
+    // touching the consumer Ink component.
+    void slug;
+    return Object.freeze({
+        foreground: 'Aa',
+        accent: '123',
+        success: 'OK',
+        warning: 'WARN',
+        error: 'ERROR',
+    });
+}
+//# sourceMappingURL=presets.js.map

package/dist/core/theme/state.js

@@ -0,0 +1,181 @@
+/**
+ * Leak L30 (2026-05-27) — Theme state persistence.
+ *
+ * Mirror of `core/output-style/state.ts` — same two-tier ladder
+ * (workspace > user > default), same `~/.pugi/config.json` envelope,
+ * same malformed-config tolerance. The two modules write to disjoint
+ * keys (`outputStyle` vs `theme`) of the same JSON file so neighbour
+ * settings (`permissionMode`, `privacy`, `model`, `outputStyle`)
+ * survive a theme flip.
+ *
+ * Two-tier storage:
+ *
+ *   1. **Workspace** — `<workspaceRoot>/.pugi/config.json`. Set by
+ *      `/theme <name>` or `pugi theme <name>` without `--persist`.
+ *      Overrides the user default for the current workspace only.
+ *
+ *   2. **User default** — `~/.pugi/config.json` (PUGI_HOME-aware).
+ *      Set by `pugi theme <name> --persist` or `/theme <name>
+ *      --persist`. Applies to every workspace that has no
+ *      workspace-level override.
+ *
+ * Precedence (highest → lowest):
+ *
+ *   workspace value > user value > DEFAULT_THEME ('default')
+ *
+ * The reader tolerates:
+ *   - missing file (returns the default slug),
+ *   - empty file (returns the default slug),
+ *   - malformed JSON (returns the default slug — DO NOT crash REPL
+ *     boot because of a hand-edited config),
+ *   - unknown slug (returns the default slug + emits no error; the
+ *     operator can `/theme` to see the table and re-set).
+ *
+ * The writer is a read-modify-write to preserve neighbouring keys
+ * (`outputStyle`, `permissionMode`, etc.) — overwriting the whole
+ * file would clobber the other tier's settings AND any sibling
+ * module's slot in the same envelope.
+ *
+ * Test surface: `test/commands/theme-state.spec.ts` exercises
+ * precedence, malformed-config tolerance, persistence across reads,
+ * the `--persist` (user-default) path, reset semantics, and the
+ * coexistence contract with `outputStyle` in the same file.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { DEFAULT_THEME, isThemeSlug } from './presets.js';
+/**
+ * Env override for `~/.pugi` so the spec can sandbox both tiers
+ * without touching the developer's real config. Re-exported under a
+ * theme-specific alias so consumers in this module do not need to
+ * import the output-style constant; the underlying env key is shared
+ * (`PUGI_HOME`) because the two modules write to the same config
+ * envelope.
+ */
+export const PUGI_HOME_ENV = 'PUGI_HOME';
+/**
+ * Resolve the active theme for the workspace, applying the
+ * precedence ladder (workspace > user > default).
+ *
+ * Pure read. Never writes, never throws — every IO failure degrades
+ * to the default slug. The function returns the source label too so
+ * the CLI surface can show the operator where the value came from.
+ */
+export function resolveTheme(io) {
+    const workspaceSlug = readSlugFromFile(workspaceConfigPath(io.workspaceRoot));
+    if (workspaceSlug)
+        return { slug: workspaceSlug, source: 'workspace' };
+    const userSlug = readSlugFromFile(userConfigPath(io.env ?? process.env));
+    if (userSlug)
+        return { slug: userSlug, source: 'user' };
+    return { slug: DEFAULT_THEME, source: 'default' };
+}
+/**
+ * Write `slug` to the workspace tier. Creates `<workspaceRoot>/.pugi/`
+ * if missing. Preserves neighbouring config keys via read-modify-write.
+ */
+export function setWorkspaceTheme(slug, io) {
+    writeSlugToFile(workspaceConfigPath(io.workspaceRoot), slug);
+}
+/**
+ * Write `slug` to the user tier (`~/.pugi/config.json`).
+ *
+ * Mirrors the workspace writer's read-modify-write so the user's
+ * `outputStyle` / `permissionMode` / `privacy` / `model` keys survive
+ * a theme flip.
+ */
+export function setUserTheme(slug, io) {
+    writeSlugToFile(userConfigPath(io.env ?? process.env), slug);
+}
+/**
+ * Clear the workspace tier's `theme` key. The user tier (and
+ * therefore the eventual resolved theme) is left untouched.
+ *
+ * Used by `/theme --reset` so the operator can revert a workspace
+ * override without nuking the rest of their workspace config (or the
+ * user default).
+ */
+export function clearWorkspaceTheme(io) {
+    clearSlugInFile(workspaceConfigPath(io.workspaceRoot));
+}
+/**
+ * Clear the user tier's `theme` key. Lower-blast-radius reset for
+ * operators who want every workspace to fall back to `default` unless
+ * an explicit workspace value is set.
+ */
+export function clearUserTheme(io) {
+    clearSlugInFile(userConfigPath(io.env ?? process.env));
+}
+/**
+ * Workspace config path. Exported for the spec; production callers
+ * should use the `setWorkspace…` / `resolveTheme` helpers.
+ */
+export function workspaceConfigPath(workspaceRoot) {
+    return resolve(workspaceRoot, '.pugi', 'config.json');
+}
+/**
+ * User config path resolved against `PUGI_HOME` (or `~/.pugi`).
+ * Exported for the spec.
+ */
+export function userConfigPath(env = process.env) {
+    const home = env[PUGI_HOME_ENV] ?? resolve(homedir(), '.pugi');
+    return resolve(home, 'config.json');
+}
+/**
+ * Read + parse a config file. Returns an empty object on any IO or
+ * parse error. Caller-provided JSON must be a plain object; arrays /
+ * scalars / null are treated as "no config" so a hand-edited file
+ * never crashes the REPL.
+ */
+function readConfigFile(path) {
+    if (!existsSync(path))
+        return {};
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    if (raw.trim().length === 0)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return {};
+    return parsed;
+}
+function writeConfigFile(path, config) {
+    mkdirSync(dirname(path), { recursive: true });
+    // 0o600 mirrors `core/output-style/state.ts` + `runtime/commands/config.ts` —
+    // the config file may hold preferredEndpoint URLs etc. that should
+    // not be world-readable.
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+function readSlugFromFile(path) {
+    const config = readConfigFile(path);
+    const candidate = config.theme;
+    return isThemeSlug(candidate) ? candidate : null;
+}
+function writeSlugToFile(path, slug) {
+    const config = readConfigFile(path);
+    config.theme = slug;
+    writeConfigFile(path, config);
+}
+function clearSlugInFile(path) {
+    const config = readConfigFile(path);
+    if (!('theme' in config))
+        return;
+    delete config.theme;
+    writeConfigFile(path, config);
+}
+//# sourceMappingURL=state.js.map