@wjarka/cezarion 0.10.0-pr30.54

package/dist/skills.js

@@ -0,0 +1,251 @@
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve, basename, dirname, extname } from 'node:path';
+import { gatedSkillsRepos } from './config.js';
+import { getTeamSkillsCached } from './skills-remote.js';
+import { readWorkspaceUiState } from './workspace/ui-state.js';
+/* Precedence order — earlier dirs win name collisions. `npx skills` writes
+   the canonical copy to `.agents/skills/<name>/SKILL.md` and mirrors it into
+   each agent's dir (often as symlinks) — scanning them all and deduping by
+   name yields exactly the union of unique skills.
+
+   Exported for the drift guard in `test/unit/skill-dirs.test.ts` (#374): the
+   cockpit's empty-state hint hand-copies this list into the bundle
+   (`packages/web/src/components/skill-empty-hint.tsx`) because it runs in another
+   process, so adding a dir here without updating the hint makes the hint lie.
+   That test pins this list and says where to go. */
+export const SKILL_DIRS = [
+    { dir: '.ai/cezar/skills', source: 'cezar' },
+    { dir: '.ai/skills', source: 'ai' },
+    { dir: '.agents/skills', source: 'agents' },
+    { dir: '.claude/skills', source: 'agents' },
+    { dir: '.codex/skills', source: 'agents' },
+    { dir: '.cursor/skills', source: 'agents' },
+    { dir: '.opencode/skills', source: 'agents' },
+];
+/* Deliberately `homedir()` and not `agentHomePaths().claude`: these do NOT follow an
+   agent profile (`src/core/agent-profiles.ts`). A skill is CONTENT — a playbook — not
+   identity, and a second Claude login is not a second skill library. `npx skills`, which
+   writes the `~/.claude/skills` mirror, is profile-unaware for the same reason. */
+const GLOBAL_SKILL_DIRS = [
+    { dir: join(homedir(), '.agents/skills'), source: 'global' },
+    { dir: join(homedir(), '.claude/skills'), source: 'global' },
+];
+/**
+ * Discover the merged skill catalog for a repo. Name collisions resolve
+ * local-first: `.ai/cezar/skills` → `.ai/skills` → `.agents/skills` + agent
+ * mirrors → global (`~/.agents/skills`, `~/.claude/skills`) → team repo
+ * ("the user's repo is the source of truth"). Missing directories are fine —
+ * an empty catalog is fully supported (steps fall back to their plain
+ * prompt). Team skills come from the in-process cache; the first call starts
+ * a background load so nothing here ever waits on the network.
+ *
+ * Opt-out gate: skills from a *default* (vendor) skills repo — `open-mercato/skills`
+ * for the zero-config majority, see `gatedSkillsRepos` — appear unless the user has
+ * curated them away. `importedSkills` in the GLOBAL `~/.cezar/ui-state.json` (not the
+ * per-repo file — the selection describes the person and must not depend on the launch
+ * directory, multi-project workspace) is a tri-state: ABSENT means "not curated" and
+ * every default skill shows (the historical behavior — no upgrade break for existing
+ * installs); a PRESENT array (even `[]`) means the user has taken control and only those
+ * names show. A repo that sets its own `skillsRepos` gates nothing regardless. This is the
+ * single chokepoint, so the decision is identical for every consumer — catalog, composer
+ * picker, planner, runner.
+ */
+export async function discoverSkills(repoRoot) {
+    const [lists, gatedRepos, uiState] = await Promise.all([
+        Promise.all([
+            ...SKILL_DIRS.map(({ dir, source }) => readMarkdownSkills(resolve(repoRoot, dir), source)),
+            ...GLOBAL_SKILL_DIRS.map(({ dir, source }) => readMarkdownSkills(dir, source)),
+        ]),
+        gatedSkillsRepos(repoRoot),
+        readWorkspaceUiState(),
+    ]);
+    const teamSkills = filterImportedTeamSkills(getTeamSkillsCached(repoRoot), gatedRepos, readImportedSkills(uiState));
+    const merged = [];
+    const seen = new Set();
+    for (const skills of [...lists, teamSkills]) {
+        for (const skill of skills) {
+            if (seen.has(skill.name))
+                continue;
+            seen.add(skill.name);
+            merged.push(skill);
+        }
+    }
+    merged.sort((a, b) => a.name.localeCompare(b.name));
+    return merged;
+}
+/**
+ * The imported team-skill names from a raw `ui-state.json` object, as a tri-state:
+ * `undefined` means the key is absent — "not curated", so every default skill shows
+ * (the opt-out default that keeps existing installs whole); an array (even empty) is
+ * the user's explicit selection. Defensive because the file is user-editable: a value
+ * that is not an array degrades to `undefined` (keep all — the safe, backward-compatible
+ * reading), and non-string / empty entries inside an array are dropped rather than thrown on.
+ */
+export function readImportedSkills(uiState) {
+    const value = uiState.importedSkills;
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((name) => typeof name === 'string' && name.length > 0);
+}
+/**
+ * The opt-out gate: keep every team skill whose repo is NOT gated (a repo with its own
+ * configured `skillsRepos` — auto-loads everything). For skills from a gated default
+ * (vendor) repo, `importedSkills === undefined` keeps them ALL (not curated — the
+ * historical behavior), while a present array keeps only the named ones. Local skills
+ * carry no `team` and are always kept. Pure so the gate is unit-testable without a
+ * network clone (the gated set is a const default otherwise).
+ */
+export function filterImportedTeamSkills(teamSkills, gatedRepos, importedSkills) {
+    // Not curated → the full default catalog still appears (no upgrade break).
+    if (importedSkills === undefined)
+        return [...teamSkills];
+    const imported = new Set(importedSkills);
+    return teamSkills.filter((skill) => !skill.team || !gatedRepos.has(skill.team.repo) || imported.has(skill.name));
+}
+/**
+ * Walk a skills dir for entrypoints, following directory symlinks. Once a
+ * directory contains `SKILL.md`, it is one directory-based skill and its
+ * supporting Markdown (for example `references/*.md`) is not scanned. Other
+ * directories retain the legacy recursive `*.md` discovery behavior.
+ */
+async function skillEntryPaths(dir, depth, visited) {
+    if (depth < 0)
+        return [];
+    let real;
+    try {
+        real = await realpath(dir);
+    }
+    catch {
+        return []; // missing dir or dangling symlink
+    }
+    if (visited.has(real))
+        return [];
+    visited.add(real);
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const skillEntry = entries.find((entry) => entry.name === 'SKILL.md');
+    if (skillEntry) {
+        const skillPath = join(dir, skillEntry.name);
+        try {
+            if ((await stat(skillPath)).isFile())
+                return [skillPath];
+        }
+        catch {
+            // A dangling or unreadable SKILL.md does not hide other valid entries.
+        }
+    }
+    const paths = [];
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        let isDir = entry.isDirectory();
+        if (entry.isSymbolicLink()) {
+            try {
+                isDir = (await stat(path)).isDirectory(); // stat follows the link
+            }
+            catch {
+                continue; // dangling symlink
+            }
+        }
+        if (isDir) {
+            paths.push(...(await skillEntryPaths(path, depth - 1, visited)));
+        }
+        else if (extname(entry.name).toLowerCase() === '.md') {
+            paths.push(path);
+        }
+    }
+    return paths;
+}
+async function readMarkdownSkills(dir, source) {
+    const paths = await skillEntryPaths(dir, 4, new Set());
+    const skills = [];
+    for (const absPath of paths) {
+        let raw;
+        try {
+            raw = await readFile(absPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const { frontmatter, body } = parseFrontmatter(raw);
+        const base = basename(absPath, extname(absPath));
+        // The `SKILL.md` convention names the skill after its directory.
+        const fallback = base.toLowerCase() === 'skill' ? basename(dirname(absPath)) : base;
+        const name = typeof frontmatter.name === 'string' && frontmatter.name.trim()
+            ? frontmatter.name.trim()
+            : fallback;
+        const description = typeof frontmatter.description === 'string' && frontmatter.description.trim()
+            ? frontmatter.description.trim()
+            : undefined;
+        const interactive = frontmatter.interactive === 'true' ? true : undefined;
+        skills.push({ name, description, interactive, body, path: absPath, source });
+    }
+    return skills;
+}
+/**
+ * Tiny purpose-built frontmatter parser — a leading `---\n … \n---\n` block
+ * with `key: value` lines, `key: [a, b]` inline arrays and `key:` + `  - a`
+ * block arrays. Deliberately not full YAML so we avoid a parser dependency
+ * for skill files.
+ */
+export function parseFrontmatter(raw) {
+    // Normalize CRLF and lone CR — otherwise frontmatter is silently dropped.
+    const text = raw.replace(/\r\n?/g, '\n');
+    if (!text.startsWith('---\n'))
+        return { frontmatter: {}, body: raw };
+    // Match the closing delimiter only on its own line so a `---` thematic
+    // break inside the body doesn't terminate the block early.
+    const end = text.indexOf('\n---\n', 4);
+    const endAtEof = text.endsWith('\n---') ? text.length - 4 : -1;
+    const closeAt = end === -1 ? endAtEof : end;
+    if (closeAt === -1)
+        return { frontmatter: {}, body: raw };
+    const block = text.slice(4, closeAt);
+    const afterDelimiter = end === -1 ? -1 : text.indexOf('\n', closeAt + 1);
+    const body = afterDelimiter === -1 ? '' : text.slice(afterDelimiter + 1);
+    const frontmatter = {};
+    const lines = block.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (!line.trim() || line.trim().startsWith('#'))
+            continue;
+        const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const key = m[1];
+        const rest = (m[2] ?? '').trim();
+        if (rest === '') {
+            const items = [];
+            while (i + 1 < lines.length && /^\s*-\s+/.test(lines[i + 1] ?? '')) {
+                items.push(stripQuotes((lines[i + 1] ?? '').replace(/^\s*-\s+/, '').trim()));
+                i++;
+            }
+            frontmatter[key] = items;
+            continue;
+        }
+        if (rest.startsWith('[') && rest.endsWith(']')) {
+            const inner = rest.slice(1, -1).trim();
+            frontmatter[key] = inner
+                ? inner
+                    .split(',')
+                    .map((s) => stripQuotes(s.trim()))
+                    .filter((s) => s.length > 0)
+                : [];
+            continue;
+        }
+        frontmatter[key] = stripQuotes(rest);
+    }
+    return { frontmatter, body };
+}
+function stripQuotes(s) {
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+        return s.slice(1, -1);
+    }
+    return s;
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/dist/todos.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+/**
+ * The global follow-up inbox (spec 007): `.ai/cezar/todos.json`, a flat JSON
+ * array agents append to (via CEZ_TODOS_FILE). Agent entries are external
+ * data — each one is zod-validated on read and malformed ones are skipped
+ * with a warning, never fatal. Server writes are serialized with an
+ * in-process lock (the janitor `withLock` pattern) and land atomically
+ * (tmp + rename, the runs.json pattern).
+ */
+export declare const todoSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    ts: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    summary: z.ZodString;
+    action: z.ZodOptional<z.ZodString>;
+    prUrl: z.ZodOptional<z.ZodString>;
+    suggestedSkill: z.ZodOptional<z.ZodString>;
+    suggestedArgs: z.ZodOptional<z.ZodString>;
+    suggestedPrompt: z.ZodOptional<z.ZodString>;
+    runnable: z.ZodOptional<z.ZodBoolean>;
+    startedTaskId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TodoItem = z.infer<typeof todoSchema> & {
+    id: string;
+};
+export declare function todosPath(dataDir: string): string;
+export declare function readTodos(dataDir: string): Promise<TodoItem[]>;
+/** Check off (delete) an entry. False when the id isn't there. */
+export declare function removeTodo(dataDir: string, id: string): Promise<boolean>;
+/** The task text "▶ Run" turns an entry into: the suggested prompt (or the summary when the
+ *  entry carries none), plus the suggested args as a trailing line. The single server-side
+ *  source for `POST /api/todos/:id/start`; the cockpit's prefill copy
+ *  (`packages/web/src/routes/inbox.tsx`, #374) lives in another process and cannot import this, so
+ *  the two are pinned to the shared cases in `test/fixtures/todo-task-text.json`. */
+export declare function todoTaskText(todo: Pick<TodoItem, 'summary' | 'suggestedPrompt' | 'suggestedArgs'>): string;
+/** Record that "▶ Run" turned the entry into task `taskId`. The entry stays
+ *  in the file as an audit trail; the GUI hides started entries. First start wins: an entry
+ *  that already carries a `startedTaskId` is left untouched and answers false, so the
+ *  best-effort `todoId` bookkeeping on `POST /api/runs` (#374) can never overwrite the audit
+ *  trail — the check shares this lock, so two concurrent launches cannot both claim the entry. */
+export declare function markStarted(dataDir: string, id: string, taskId: string): Promise<boolean>;
+/** Subscribe to `dataDir`'s inbox changes; the watch is created on the first
+ *  subscription and torn down when the last subscriber leaves. Returns the
+ *  unsubscribe function (idempotent — a stale double call can never tear down
+ *  a watch that later subscribers re-created). */
+export declare function onTodosChanged(dataDir: string, cb: () => void): () => void;
+/** Test hook: is a live watch registered for `dataDir`? */
+export declare function todosWatchActive(dataDir: string): boolean;

package/dist/todos.js

@@ -0,0 +1,201 @@
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { mkdirSync, watch } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+/**
+ * The global follow-up inbox (spec 007): `.ai/cezar/todos.json`, a flat JSON
+ * array agents append to (via CEZ_TODOS_FILE). Agent entries are external
+ * data — each one is zod-validated on read and malformed ones are skipped
+ * with a warning, never fatal. Server writes are serialized with an
+ * in-process lock (the janitor `withLock` pattern) and land atomically
+ * (tmp + rename, the runs.json pattern).
+ */
+export const todoSchema = z.object({
+    id: z.string().min(1).optional(),
+    ts: z.string().optional(),
+    taskId: z.string().optional(),
+    summary: z.string().min(1),
+    action: z.string().optional(),
+    prUrl: z.string().optional(),
+    suggestedSkill: z.string().optional(),
+    suggestedArgs: z.string().optional(),
+    suggestedPrompt: z.string().optional(),
+    /** Explicit intent; legacy entries infer it from an executable suggestion. */
+    runnable: z.boolean().optional(),
+    /** Set by the server when "▶ Run" turned this entry into a task. */
+    startedTaskId: z.string().optional(),
+});
+export function todosPath(dataDir) {
+    return join(dataDir, 'todos.json');
+}
+// ---- in-process lock (15-line port of janitor's storage.withLock) ----------
+const locks = new Map();
+async function withLock(key, fn) {
+    const prev = locks.get(key) ?? Promise.resolve();
+    let release = () => undefined;
+    const next = new Promise((r) => {
+        release = r;
+    });
+    locks.set(key, prev.then(() => next));
+    try {
+        await prev;
+        return await fn();
+    }
+    finally {
+        release();
+    }
+}
+// ---- read / write -----------------------------------------------------------
+/** Parse + validate the file. Broken JSON / non-array → []; bad entries are
+ *  skipped with a warning; entries without an id get one assigned. */
+async function readRaw(dataDir) {
+    let raw;
+    try {
+        raw = await fs.readFile(todosPath(dataDir), 'utf8');
+    }
+    catch {
+        return { items: [], needsRewrite: false }; // no file yet — empty inbox
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[cez] todos.json is not valid JSON — showing an empty inbox (${message})`);
+        return { items: [], needsRewrite: false };
+    }
+    if (!Array.isArray(parsed)) {
+        console.warn('[cez] todos.json is not a JSON array — showing an empty inbox');
+        return { items: [], needsRewrite: false };
+    }
+    const items = [];
+    let needsRewrite = false;
+    for (const entry of parsed) {
+        const result = todoSchema.safeParse(entry);
+        if (!result.success) {
+            console.warn(`[cez] skipped a malformed todos.json entry: ${result.error.issues.map((i) => i.message).join('; ')}`);
+            continue;
+        }
+        if (!result.data.id) {
+            // Agent entries arrive without ids — assign one so the GUI can address
+            // the entry; the file is rewritten (under the lock) on this read.
+            needsRewrite = true;
+            items.push({ ...result.data, id: randomUUID() });
+        }
+        else {
+            items.push({ ...result.data, id: result.data.id });
+        }
+    }
+    return { items, needsRewrite };
+}
+async function writeAtomic(dataDir, items) {
+    const file = todosPath(dataDir);
+    const tmp = `${file}.tmp`;
+    await fs.mkdir(dataDir, { recursive: true });
+    await fs.writeFile(tmp, JSON.stringify(items, null, 2), 'utf8');
+    await fs.rename(tmp, file);
+}
+export async function readTodos(dataDir) {
+    return withLock(dataDir, async () => {
+        const { items, needsRewrite } = await readRaw(dataDir);
+        if (needsRewrite) {
+            await writeAtomic(dataDir, items).catch(() => undefined); // best effort
+        }
+        return items;
+    });
+}
+/** Check off (delete) an entry. False when the id isn't there. */
+export async function removeTodo(dataDir, id) {
+    return withLock(dataDir, async () => {
+        const { items } = await readRaw(dataDir);
+        const next = items.filter((t) => t.id !== id);
+        if (next.length === items.length)
+            return false;
+        await writeAtomic(dataDir, next);
+        return true;
+    });
+}
+/** The task text "▶ Run" turns an entry into: the suggested prompt (or the summary when the
+ *  entry carries none), plus the suggested args as a trailing line. The single server-side
+ *  source for `POST /api/todos/:id/start`; the cockpit's prefill copy
+ *  (`packages/web/src/routes/inbox.tsx`, #374) lives in another process and cannot import this, so
+ *  the two are pinned to the shared cases in `test/fixtures/todo-task-text.json`. */
+export function todoTaskText(todo) {
+    let task = (todo.suggestedPrompt ?? todo.summary).trim() || todo.summary;
+    if (todo.suggestedArgs)
+        task += `\n\nArguments: ${todo.suggestedArgs}`;
+    return task;
+}
+/** Record that "▶ Run" turned the entry into task `taskId`. The entry stays
+ *  in the file as an audit trail; the GUI hides started entries. First start wins: an entry
+ *  that already carries a `startedTaskId` is left untouched and answers false, so the
+ *  best-effort `todoId` bookkeeping on `POST /api/runs` (#374) can never overwrite the audit
+ *  trail — the check shares this lock, so two concurrent launches cannot both claim the entry. */
+export async function markStarted(dataDir, id, taskId) {
+    return withLock(dataDir, async () => {
+        const { items } = await readRaw(dataDir);
+        const item = items.find((t) => t.id === id);
+        if (!item || item.startedTaskId)
+            return false;
+        item.startedTaskId = taskId;
+        await writeAtomic(dataDir, items);
+        return true;
+    });
+}
+const watches = new Map();
+/** Start watching `dataDir` for todos.json changes (agents write it from
+ *  another process). Degrades to a watcher-less entry on error. */
+function startWatch(dataDir) {
+    const emitter = new EventEmitter();
+    emitter.setMaxListeners(100);
+    const entry = { emitter, watcher: undefined, timer: undefined };
+    try {
+        mkdirSync(dataDir, { recursive: true });
+        const watcher = watch(dataDir, (_event, filename) => {
+            if (filename && filename !== 'todos.json')
+                return;
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            entry.timer = setTimeout(() => emitter.emit('changed'), 300);
+            entry.timer.unref?.();
+        });
+        watcher.on('error', () => undefined); // a dying watcher must not kill the server
+        watcher.unref?.();
+        entry.watcher = watcher;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[cez] todos watch unavailable — the Inbox updates on refresh only (${message})`);
+    }
+    watches.set(dataDir, entry);
+    return entry;
+}
+/** Subscribe to `dataDir`'s inbox changes; the watch is created on the first
+ *  subscription and torn down when the last subscriber leaves. Returns the
+ *  unsubscribe function (idempotent — a stale double call can never tear down
+ *  a watch that later subscribers re-created). */
+export function onTodosChanged(dataDir, cb) {
+    const entry = watches.get(dataDir) ?? startWatch(dataDir);
+    entry.emitter.on('changed', cb);
+    let unsubscribed = false;
+    return () => {
+        if (unsubscribed)
+            return;
+        unsubscribed = true;
+        entry.emitter.off('changed', cb);
+        if (entry.emitter.listenerCount('changed') > 0)
+            return;
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.watcher?.close();
+        watches.delete(dataDir);
+    };
+}
+/** Test hook: is a live watch registered for `dataDir`? */
+export function todosWatchActive(dataDir) {
+    return watches.has(dataDir);
+}
+//# sourceMappingURL=todos.js.map

package/dist/todos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todos.js","sourceRoot":"","sources":["../src/todos.ts"],"names":[],"mappings":"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"}

package/dist/ui-state.d.ts

@@ -0,0 +1,26 @@
+import type { UiState } from './contract/index.js';
+/**
+ * `.ai/cezar/ui-state.json` — small GUI preferences the cockpit persists (files, not a DB).
+ * The server owns the schema and the writes (`PUT /api/ui-state` in `src/server/server.ts`);
+ * this is the shared read path, so the CLI can honour a preference the cockpit set (#391's
+ * `dismissedSkillsBanner`) without a second notion of where the file lives.
+ *
+ * Same zero-config rule as `src/config.ts`: missing, unreadable or malformed all degrade to
+ * `{}` — an absent preference, never a throw, never a blocked startup.
+ */
+export declare function uiStatePath(repoRoot: string): string;
+/**
+ * Read `ui-state.json` on demand — never cached, never throws.
+ *
+ * Typed by the CONTRACT (`UiState`), not by a loose record: `GET /api/v1/ui-state` answers this
+ * value verbatim, so a `Record<string, unknown>` here made the route name no key at all and the
+ * per-route parity guard vacuous — the same defect `healthSnapshot` had. `UiState` is a
+ * `z.looseObject`, so the index signature (and with it the round-trip promise of
+ * BACKWARD_COMPATIBILITY.md §3) survives; what it adds is the NAMES of the keys the server knows.
+ *
+ * The cast is unchanged in kind — the file is user-editable JSON and is deliberately NOT parsed
+ * through the schema, because a single malformed pref must not discard the whole bag (§3). What
+ * the type asserts is the wire shape the route promises; the write side (`PUT /ui-state`, validated
+ * by `uiStateBody`) is what actually enforces it.
+ */
+export declare function readUiState(repoRoot: string): Promise<UiState>;

package/dist/ui-state.js

@@ -0,0 +1,38 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * `.ai/cezar/ui-state.json` — small GUI preferences the cockpit persists (files, not a DB).
+ * The server owns the schema and the writes (`PUT /api/ui-state` in `src/server/server.ts`);
+ * this is the shared read path, so the CLI can honour a preference the cockpit set (#391's
+ * `dismissedSkillsBanner`) without a second notion of where the file lives.
+ *
+ * Same zero-config rule as `src/config.ts`: missing, unreadable or malformed all degrade to
+ * `{}` — an absent preference, never a throw, never a blocked startup.
+ */
+export function uiStatePath(repoRoot) {
+    return join(repoRoot, '.ai/cezar', 'ui-state.json');
+}
+/**
+ * Read `ui-state.json` on demand — never cached, never throws.
+ *
+ * Typed by the CONTRACT (`UiState`), not by a loose record: `GET /api/v1/ui-state` answers this
+ * value verbatim, so a `Record<string, unknown>` here made the route name no key at all and the
+ * per-route parity guard vacuous — the same defect `healthSnapshot` had. `UiState` is a
+ * `z.looseObject`, so the index signature (and with it the round-trip promise of
+ * BACKWARD_COMPATIBILITY.md §3) survives; what it adds is the NAMES of the keys the server knows.
+ *
+ * The cast is unchanged in kind — the file is user-editable JSON and is deliberately NOT parsed
+ * through the schema, because a single malformed pref must not discard the whole bag (§3). What
+ * the type asserts is the wire shape the route promises; the write side (`PUT /ui-state`, validated
+ * by `uiStateBody`) is what actually enforces it.
+ */
+export async function readUiState(repoRoot) {
+    try {
+        const parsed = JSON.parse(await readFile(uiStatePath(repoRoot), 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=ui-state.js.map

package/dist/ui-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-state.js","sourceRoot":"","sources":["../src/ui-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,OAAO,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAgB;IAChD,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAClF,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;IACzE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/update-check.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Update discovery (#368): a best-effort, fire-and-forget check against the
+ * npm registry so the cockpit can tell the user a newer cezar exists — the
+ * root cause behind most "bug already fixed" reports is `npx` happily reusing
+ * a stale cached version forever. Silent on any failure: offline, slow
+ * registry or a weird payload must never affect startup.
+ */
+/** Newest published version when it's newer than `current`, else null. */
+export declare function checkForUpdate(pkgName: string, current: string): Promise<string | null>;
+/** Plain numeric semver compare (`1.2.10` > `1.2.9`); pre-release tags and
+ *  anything unparseable compare as 0 — good enough for release-only publishes. */
+export declare function isNewerVersion(candidate: string, current: string): boolean;

package/dist/update-check.js

@@ -0,0 +1,41 @@
+/**
+ * Update discovery (#368): a best-effort, fire-and-forget check against the
+ * npm registry so the cockpit can tell the user a newer cezar exists — the
+ * root cause behind most "bug already fixed" reports is `npx` happily reusing
+ * a stale cached version forever. Silent on any failure: offline, slow
+ * registry or a weird payload must never affect startup.
+ */
+const REGISTRY_TIMEOUT_MS = 3_000;
+/** Newest published version when it's newer than `current`, else null. */
+export async function checkForUpdate(pkgName, current) {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(pkgName)}/latest`, {
+            signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const latest = typeof data.version === 'string' ? data.version : null;
+        return latest && isNewerVersion(latest, current) ? latest : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Plain numeric semver compare (`1.2.10` > `1.2.9`); pre-release tags and
+ *  anything unparseable compare as 0 — good enough for release-only publishes. */
+export function isNewerVersion(candidate, current) {
+    const parse = (v) => v
+        .split('.')
+        .slice(0, 3)
+        .map((part) => Number.parseInt(part, 10) || 0);
+    const a = parse(candidate);
+    const b = parse(current);
+    for (let i = 0; i < 3; i++) {
+        const diff = (a[i] ?? 0) - (b[i] ?? 0);
+        if (diff !== 0)
+            return diff > 0;
+    }
+    return false;
+}
+//# sourceMappingURL=update-check.js.map