@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/src/theme/theme-contracts.ts

@@ -0,0 +1,139 @@
+/**
+ * SCREEN-2002 — the TUI's one theme token model.
+ *
+ * Before this, five things decided a colour: `PALETTE` (Ink names), `ANSI` (raw SGR for the markdown
+ * pipeline), `marked-terminal`'s own chalk defaults, `cli-highlight`'s `DEFAULT_THEME`, and a handful
+ * of `chalk.<name>` calls. A theme that rewrote only the first two would leave a daltonized run with
+ * red/green code blocks, because `cli-highlight` falls back PER KEY to its own theme. So the model
+ * carries every group a renderer reads, and the style builder derives every encoding from it through
+ * chalk — which is exactly what Ink's own `colorize` does, so no mapping layer is invented.
+ *
+ * Values use INK'S colour grammar verbatim (`<chalk name> | #rrggbb | ansi256(n) | rgb(r,g,b)`), so a
+ * theme file, a built-in and a component all speak one language and the grammar doubles as the
+ * injection floor: no raw escape sequence can enter through a theme.
+ */
+
+/** A colour in Ink's grammar. Validated at the boundary, never parsed twice. */
+export type TThemeColor = string;
+
+/** Foreground and border roles every Ink component reads. */
+export interface IThemeColors {
+  readonly text: {
+    readonly accent: TThemeColor;
+    readonly emphasis: TThemeColor;
+    readonly success: TThemeColor;
+    readonly warning: TThemeColor;
+    readonly error: TThemeColor;
+    readonly session: TThemeColor;
+    readonly muted: TThemeColor;
+    readonly onAccent: TThemeColor;
+  };
+  readonly border: {
+    readonly attention: TThemeColor;
+    readonly focused: TThemeColor;
+    readonly active: TThemeColor;
+    readonly muted: TThemeColor;
+    readonly error: TThemeColor;
+  };
+  readonly status: {
+    readonly running: TThemeColor;
+    readonly success: TThemeColor;
+    readonly error: TThemeColor;
+    readonly denied: TThemeColor;
+    readonly waiting: TThemeColor;
+    readonly cancelled: TThemeColor;
+    readonly idle: TThemeColor;
+  };
+}
+
+/**
+ * Every key `marked-terminal` colours by default, including `html` — a key left out would keep that
+ * dependency's own gray under every theme.
+ *
+ * Deliberately absent, because they carry no colour today and giving them one would change rendering
+ * rather than theme it: `strong` (`chalk.bold`), `em` (`chalk.italic`), `listitem` and `hr`
+ * (`chalk.reset`), and a diff's `diff `/`index ` metadata rows, which this package writes itself as
+ * dim over the inherited foreground.
+ */
+export interface IThemeMarkdown {
+  readonly heading: TThemeColor;
+  readonly firstHeading: TThemeColor;
+  readonly code: TThemeColor;
+  readonly codespan: TThemeColor;
+  readonly link: TThemeColor;
+  readonly href: TThemeColor;
+  readonly blockquote: TThemeColor;
+  readonly del: TThemeColor;
+  readonly html: TThemeColor;
+  readonly diffAdded: TThemeColor;
+  readonly diffRemoved: TThemeColor;
+  readonly diffAddedBackground: TThemeColor;
+  readonly diffRemovedBackground: TThemeColor;
+  readonly diffHunk: TThemeColor;
+}
+
+/**
+ * `cli-highlight`'s seventeen coloured keys, ALL REQUIRED. Its `colorizeNode` reads
+ * `theme[token] || DEFAULT_THEME[token] || plain`, so one missing key restores that dependency's
+ * red/green pair — the exact thing a daltonized theme exists to remove.
+ */
+export interface IThemeSyntax {
+  readonly keyword: TThemeColor;
+  readonly built_in: TThemeColor;
+  readonly type: TThemeColor;
+  readonly literal: TThemeColor;
+  readonly number: TThemeColor;
+  readonly regexp: TThemeColor;
+  readonly string: TThemeColor;
+  readonly class: TThemeColor;
+  readonly function: TThemeColor;
+  readonly comment: TThemeColor;
+  readonly doctag: TThemeColor;
+  readonly meta: TThemeColor;
+  readonly tag: TThemeColor;
+  readonly name: TThemeColor;
+  readonly attr: TThemeColor;
+  readonly addition: TThemeColor;
+  readonly deletion: TThemeColor;
+}
+
+/** The colour ramp of the package's one animation. Cadence is not themed. */
+export interface IThemeMotion {
+  readonly wave: readonly [TThemeColor, TThemeColor, TThemeColor, TThemeColor];
+}
+
+export type TThemeAppearance = 'dark' | 'light';
+export type TThemeSource = 'built-in' | 'user' | 'plugin';
+
+export interface ITuiTheme {
+  /** `dark`, `light`, `dark-daltonized`, `light-daltonized`, `custom:<slug>`, `custom:<plugin>:<slug>`. */
+  readonly id: string;
+  readonly name: string;
+  readonly appearance: TThemeAppearance;
+  readonly source: TThemeSource;
+  readonly colors: IThemeColors;
+  readonly markdown: IThemeMarkdown;
+  readonly syntax: IThemeSyntax;
+  readonly motion: IThemeMotion;
+}
+
+/** The seventeen `syntax` keys, in the order `cli-highlight` declares them. */
+export const THEME_SYNTAX_KEYS: readonly (keyof IThemeSyntax)[] = [
+  'keyword',
+  'built_in',
+  'type',
+  'literal',
+  'number',
+  'regexp',
+  'string',
+  'class',
+  'function',
+  'comment',
+  'doctag',
+  'meta',
+  'tag',
+  'name',
+  'attr',
+  'addition',
+  'deletion',
+];

package/src/theme/theme-document.ts

@@ -0,0 +1,278 @@
+/**
+ * SCREEN-2002 — the theme file boundary.
+ *
+ * A theme file is `{ name?, base?, overrides? }`: a name, a built-in to start from, and a SPARSE map
+ * over the same token paths the built-ins use. It is refused WHOLE on the first unknown token or
+ * invalid value, with a `$.`-path naming what was wrong — the keybindings document's contract, for
+ * the same reason. A partially-applied theme is the state where a reader cannot tell which colours
+ * are theirs and which the base's, and a file that silently loses its third line is worse than a
+ * file that is skipped with its reason printed.
+ *
+ * The token paths are not listed here. They are WALKED from the base theme, so `ITuiTheme` gaining a
+ * key makes it overridable and `ITuiTheme` losing one makes it refused — there is no second
+ * declaration of the token model to drift from the first.
+ *
+ * Values go through `isThemeColor`, which is also the injection floor: a raw escape sequence is not
+ * in Ink's grammar, so it cannot enter through a theme.
+ */
+import { isJsonRecord } from '../json-value.js';
+import { sanitizeTerminalText } from '../sanitize-terminal-text.js';
+import { BUILT_IN_THEMES, DEFAULT_THEME_ID } from './built-in-themes.js';
+import { isThemeColor, THEME_COLOR_GRAMMAR } from './theme-styles.js';
+
+import type { IJsonRecord, TJsonValue } from '../json-value.js';
+import type { ITuiTheme, TThemeSource } from './theme-contracts.js';
+
+export interface IThemeDocumentInput {
+  /** The namespaced id the caller minted — `custom:<slug>` or `custom:<plugin>:<slug>`. */
+  readonly id: string;
+  /** The file's own name, for the `Skipped theme "<file>": …` line. */
+  readonly fileName: string;
+  readonly source: TThemeSource;
+  readonly text: string;
+}
+
+export type TThemeDocumentResult =
+  { readonly ok: true; readonly theme: ITuiTheme } | { readonly ok: false; readonly error: string };
+
+const DOCUMENT_KEYS = new Set(['name', 'base', 'overrides']);
+const MAX_NAME_LENGTH = 60;
+// eslint-disable-next-line no-control-regex -- matching the control range IS the point here
+const CONTROL_CHARACTER = /[\u0000-\u001F\u007F-\u009F]/u;
+
+const CONTROL_CHARACTERS = new RegExp(CONTROL_CHARACTER.source, 'gu');
+
+/**
+ * Untrusted text on its way into a line a terminal will print — the one escaping policy, exported
+ * so the surfaces that build their OWN diagnostics use it rather than re-deriving it.
+ *
+ * A diagnostic is the one part of a refused file that reaches the terminal, and it quotes what was
+ * wrong — so without this the injection floor the grammar provides is defeated by the message that
+ * reports a violation of it. Escaped rather than stripped, because an author has to SEE what their
+ * file contains (`"\u001b[31m"`) instead of a value that looks fine.
+ *
+ * `JSON.stringify` alone is NOT enough, and that is the whole reason this is a function: it escapes
+ * U+0000–U+001F and leaves U+007F and the C1 range literal — including U+009B and U+009D, the
+ * single-byte spellings of CSI and OSC. A terminal accepts both spellings (`sanitize-terminal-text.ts`
+ * says so and handles both), so quoting only the 7-bit one leaves the 8-bit one's parameters
+ * standing as a live sequence.
+ */
+export function quoteThemeText(value: string): string {
+  return JSON.stringify(value).replace(
+    CONTROL_CHARACTERS,
+    (character) => `\\u${(character.codePointAt(0) ?? 0).toString(16).padStart(4, '0')}`,
+  );
+}
+
+/**
+ * The same escaping WITHOUT the surrounding quotes, for a field a caller already quotes — so a
+ * refused file does not print as `Skipped theme ""My Theme.json"": …`.
+ */
+export function escapeThemeText(value: string): string {
+  return quoteThemeText(value).slice(1, -1);
+}
+
+/**
+ * Prose a surface did not write — a dependency's message, a path from the environment. Sanitized
+ * rather than quoted, because it is a sentence; `sanitizeTerminalText` removes both spellings of
+ * every sequence, and the tab/newline it keeps are flattened so one diagnostic stays one line.
+ */
+export function sanitizeThemeProse(message: string): string {
+  return sanitizeTerminalText(message).replaceAll('\n', ' ').replaceAll('\t', ' ').trim();
+}
+
+/** A path SEGMENT taken from the file. Plain keys read as themselves; anything else is quoted. */
+function pathSegment(key: string): string {
+  return CONTROL_CHARACTER.test(key) ? quoteThemeText(key) : key;
+}
+
+function refuse(error: string): TThemeDocumentResult {
+  return { ok: false, error };
+}
+
+type TMergeResult =
+  | { readonly ok: true; readonly value: TJsonValue }
+  | { readonly ok: false; readonly error: string };
+
+function mergeColor(override: TJsonValue, path: string): TMergeResult {
+  if (typeof override !== 'string')
+    return { ok: false, error: `${path}: expected a colour string` };
+  if (!isThemeColor(override)) {
+    return {
+      ok: false,
+      error: `${path}: ${quoteThemeText(override)} is not a colour in Ink's grammar (${THEME_COLOR_GRAMMAR})`,
+    };
+  }
+  return { ok: true, value: override };
+}
+
+function mergeArray(base: readonly TJsonValue[], override: TJsonValue, path: string): TMergeResult {
+  if (!Array.isArray(override) || override.length !== base.length) {
+    return { ok: false, error: `${path}: expected exactly ${base.length} colours` };
+  }
+  const merged: TJsonValue[] = [];
+  for (const [index, item] of base.entries()) {
+    const result = mergeNode(item, override[index] ?? null, `${path}[${index}]`);
+    if (!result.ok) return result;
+    merged.push(result.value);
+  }
+  return { ok: true, value: merged };
+}
+
+function mergeRecord(base: IJsonRecord, override: TJsonValue, path: string): TMergeResult {
+  if (!isJsonRecord(override)) return { ok: false, error: `${path}: expected an object of tokens` };
+  const merged: IJsonRecord = { ...base };
+  for (const key of Object.keys(override)) {
+    // Own-property only: a JSON document can carry a literal `__proto__` key, and the base theme
+    // has no own property by that name, so the same check that catches a typo catches that too.
+    if (!Object.prototype.hasOwnProperty.call(base, key)) {
+      return { ok: false, error: `${path}.${pathSegment(key)} is not a theme token` };
+    }
+    const result = mergeNode(
+      base[key] ?? null,
+      override[key] ?? null,
+      `${path}.${pathSegment(key)}`,
+    );
+    if (!result.ok) return result;
+    merged[key] = result.value;
+  }
+  return { ok: true, value: merged };
+}
+
+/** One node of the token tree, matched against the SHAPE of the base theme's node. */
+function mergeNode(base: TJsonValue, override: TJsonValue, path: string): TMergeResult {
+  if (typeof base === 'string') return mergeColor(override, path);
+  if (Array.isArray(base)) return mergeArray(base, override, path);
+  if (isJsonRecord(base)) return mergeRecord(base, override, path);
+  return { ok: false, error: `${path} is not a theme token` };
+}
+
+type TThemeTokens = Pick<ITuiTheme, 'colors' | 'markdown' | 'syntax' | 'motion'>;
+
+/**
+ * The merged tree, read back as the token groups it was built from.
+ *
+ * A JSON round-trip rather than a type assertion, in both directions: the token interfaces have no
+ * index signature, so neither shape is assignable to the other and an assertion between them is
+ * what TypeScript rightly refuses. The conversion is sound by construction — `mergeNode` copies the
+ * BASE theme's shape and replaces only string leaves with strings the grammar accepted, so every key
+ * `ITuiTheme` declares is present and every leaf is a `TThemeColor`. An unknown key or a non-colour
+ * leaf is a refusal above this line and never reaches it.
+ */
+function asThemeTokens(value: TJsonValue): TThemeTokens {
+  return JSON.parse(JSON.stringify(value)) as TThemeTokens;
+}
+
+/** The four token groups, as JSON — the base for the walk above. */
+function themeTokens(theme: ITuiTheme): IJsonRecord {
+  return JSON.parse(
+    JSON.stringify({
+      colors: theme.colors,
+      markdown: theme.markdown,
+      syntax: theme.syntax,
+      motion: theme.motion,
+    }),
+  ) as IJsonRecord;
+}
+
+function readDocument(text: string): TMergeResult {
+  let parsed: TJsonValue;
+  try {
+    parsed = JSON.parse(text) as TJsonValue;
+  } catch (cause) {
+    return {
+      ok: false,
+      error: `$: ${cause instanceof Error ? sanitizeThemeProse(cause.message) : 'invalid JSON'}`,
+    };
+  }
+  if (!isJsonRecord(parsed)) return { ok: false, error: '$: expected an object' };
+  for (const key of Object.keys(parsed)) {
+    if (!DOCUMENT_KEYS.has(key)) {
+      return { ok: false, error: `$.${pathSegment(key)} is not a theme token` };
+    }
+  }
+  return { ok: true, value: parsed };
+}
+
+function readName(document: IJsonRecord, fallback: string): TMergeResult {
+  const name = document.name;
+  // The FALLBACK is checked on the same terms. It is the id the loader minted, which is constrained
+  // where it is minted — but "the caller already made it safe" is the assumption that put an
+  // unchecked string on every list row once, and this is the function that renders the answer.
+  if (name === undefined) {
+    if (CONTROL_CHARACTER.test(fallback)) {
+      return { ok: false, error: '$.name: the minted id must not contain control characters' };
+    }
+    if (fallback.length > MAX_NAME_LENGTH) {
+      return {
+        ok: false,
+        error: `$.name: the minted id must be at most ${MAX_NAME_LENGTH} characters`,
+      };
+    }
+    return { ok: true, value: fallback };
+  }
+  if (typeof name !== 'string' || name.trim().length === 0) {
+    return { ok: false, error: '$.name: expected a non-empty string' };
+  }
+  // A name is APPLIED, so unlike a diagnostic it is rendered on every `/theme list` row and every
+  // picker row for the whole session. A control character there is an escape the terminal acts on,
+  // and a newline breaks the box the row is drawn in — so the file is refused rather than the name
+  // repaired, which is this module's one policy.
+  if (CONTROL_CHARACTER.test(name)) {
+    return { ok: false, error: '$.name: must not contain control characters' };
+  }
+  if (name.length > MAX_NAME_LENGTH) {
+    return { ok: false, error: `$.name: must be at most ${MAX_NAME_LENGTH} characters` };
+  }
+  return { ok: true, value: name };
+}
+
+function readBase(
+  document: IJsonRecord,
+):
+  | { readonly ok: true; readonly theme: ITuiTheme }
+  | { readonly ok: false; readonly error: string } {
+  // `=== undefined`, not `??`: an explicit `null` is a value the file states, and "applied whole or
+  // refused whole" means it is refused rather than silently read as "unset".
+  const id = document.base === undefined ? DEFAULT_THEME_ID : document.base;
+  if (typeof id !== 'string') return { ok: false, error: '$.base: expected a built-in theme id' };
+  const base = BUILT_IN_THEMES.find((theme) => theme.id === id);
+  if (!base) return { ok: false, error: `$.base: ${quoteThemeText(id)} is not a built-in theme` };
+  return { ok: true, theme: base };
+}
+
+/**
+ * Parse one theme file. The `id`, the `source` and the `appearance` are NOT the document's to
+ * decide: the id is minted from where the file was found so nothing can shadow a built-in, the
+ * source is where it was read from, and the appearance follows the base a theme chose to extend.
+ */
+export function parseThemeDocument(input: IThemeDocumentInput): TThemeDocumentResult {
+  const document = readDocument(input.text);
+  if (!document.ok) return refuse(document.error);
+  const fields = document.value as IJsonRecord;
+
+  const base = readBase(fields);
+  if (!base.ok) return refuse(base.error);
+
+  const name = readName(fields, input.id);
+  if (!name.ok) return refuse(name.error);
+
+  const overrides = fields.overrides === undefined ? {} : fields.overrides;
+  const tokens = mergeNode(themeTokens(base.theme), overrides, '$.overrides');
+  if (!tokens.ok) return refuse(tokens.error);
+
+  const { colors, markdown, syntax, motion } = asThemeTokens(tokens.value);
+  return {
+    ok: true,
+    theme: {
+      id: input.id,
+      name: name.value as string,
+      appearance: base.theme.appearance,
+      source: input.source,
+      colors,
+      markdown,
+      syntax,
+      motion,
+    },
+  };
+}

package/src/theme/theme-registry.ts

@@ -0,0 +1,127 @@
+/**
+ * SCREEN-2002 — the theme catalogue, and the port the command layer asks through.
+ *
+ * The registry is the only thing that turns an ID into a theme. Work unit 1 put the built-ins
+ * behind `listBuiltInThemes()`; work unit 3 adds user and plugin themes to the same list, and
+ * nothing downstream has to learn where a theme came from — a row carries its `source` so the
+ * picker and `/theme list` can SAY where it came from, which is a different question.
+ *
+ * An unknown id resolves to the default and reports the id it could not find. Resolving silently
+ * would make a removed plugin look like a theme that stopped working, and the id is the only thing
+ * that can name the cause.
+ */
+import { DEFAULT_THEME_ID, listBuiltInThemes, resolveTheme } from './built-in-themes.js';
+
+// The registry's default source, re-exported from the module that USES it. The package's public
+// surface takes this route rather than the theme barrel: the barrel re-exports `theme-context.tsx`,
+// and a public re-export chain that reaches a `.tsx` is what `sdk-public-surface` refuses.
+export { listBuiltInThemes } from './built-in-themes.js';
+
+import type { ITuiTheme } from './theme-contracts.js';
+import type {
+  IThemeAppearanceState,
+  IThemeCatalogueEntry,
+  IThemeCataloguePort,
+  TReducedMotionOverride,
+} from '@robota-sdk/agent-interface-command';
+
+/**
+ * A theme file that was found and refused. It is carried BESIDE the themes rather than among them,
+ * because a surface must be able to show the file without ever resolving to it — an id that can be
+ * listed and cannot be applied is the shape of the bug this avoids.
+ */
+export interface IThemeSkip {
+  /**
+   * The id the file WOULD have had, so a `/theme <id>` that fails has a visible reason — or, when
+   * the file's own NAME is what made an id impossible, the quoted name in its place. It is a label,
+   * not a key: two files can carry the same one.
+   */
+  readonly id: string;
+  readonly fileName: string;
+  /** The path-named diagnostic, verbatim from `parseThemeDocument`. */
+  readonly reason: string;
+}
+
+export interface IThemeResolution {
+  readonly theme: ITuiTheme;
+  /** The id that was asked for and not found. Absent ⇒ the request was satisfied. */
+  readonly unknownId?: string;
+}
+
+export interface IThemeRegistry {
+  list(): readonly ITuiTheme[];
+  get(id: string): ITuiTheme | undefined;
+  /** The theme for an id, falling back to the default and NAMING what it could not find. */
+  resolve(id: string | undefined): IThemeResolution;
+  /** The theme files that were found and refused, with the reason each was refused for. */
+  skipped(): readonly IThemeSkip[];
+}
+
+export function createThemeRegistry(
+  themes: readonly ITuiTheme[] = listBuiltInThemes(),
+  skipped: readonly IThemeSkip[] = [],
+): IThemeRegistry {
+  const byId = new Map(themes.map((theme) => [theme.id, theme]));
+  return {
+    list: () => themes,
+    skipped: () => skipped,
+    get: (id) => byId.get(id),
+    resolve: (id) => {
+      if (id === undefined || id === DEFAULT_THEME_ID) {
+        return { theme: resolveTheme(byId.get(DEFAULT_THEME_ID)) };
+      }
+      const found = byId.get(id);
+      if (found) return { theme: found };
+      return { theme: resolveTheme(byId.get(DEFAULT_THEME_ID)), unknownId: id };
+    },
+  };
+}
+
+/** The line a run prints once when its persisted theme is not installed. */
+export function formatUnknownThemeNotice(id: string): string {
+  return `Theme "${id}" is not installed — using "${DEFAULT_THEME_ID}".`;
+}
+
+function toEntry(theme: ITuiTheme): IThemeCatalogueEntry {
+  return {
+    id: theme.id,
+    name: theme.name,
+    appearance: theme.appearance,
+    source: theme.source,
+  };
+}
+
+export interface IThemeCataloguePortOptions {
+  readonly registry: IThemeRegistry;
+  /**
+   * Re-read on every call, not captured once: `/theme` reports what is PERSISTED, and the host
+   * applies a patch by writing the settings document. A snapshot would answer with the appearance
+   * the process started with, so the command would report the change it just made as not having
+   * happened.
+   */
+  readonly readAppearance: () => IThemeAppearanceState['settings'];
+  /**
+   * The pin on reduced motion for this run, when something above the settings applied one — WHICH
+   * tier and WHAT it pinned, as one value. Two optional fields would let a caller supply the tier
+   * alone, and a default for the missing half is exactly the wrong answer this pair exists to stop:
+   * `--no-reduced-motion` is an override too and pins the opposite value.
+   */
+  readonly reducedMotionPin?:
+    { readonly tier: TReducedMotionOverride; readonly reducedMotion: boolean } | undefined;
+}
+
+export function createThemeCataloguePort(options: IThemeCataloguePortOptions): IThemeCataloguePort {
+  return {
+    listThemes: () => options.registry.list().map(toEntry),
+    getTheme: (id) => {
+      const theme = options.registry.get(id);
+      return theme ? toEntry(theme) : undefined;
+    },
+    getAppearance: () => ({
+      settings: options.readAppearance(),
+      ...(options.reducedMotionPin === undefined
+        ? {}
+        : { reducedMotionPin: options.reducedMotionPin }),
+    }),
+  };
+}