open-multi-agent-kit 0.78.6 → 0.78.7

package/dist/cli/release-promotion-gate.js

@@ -3,13 +3,24 @@
  *
  * Computes a release viability score R_v from ten normalized input
  * dimensions and derives a verdict: block, pre-release, or stable.
+ *
+ * Weights are sourced from the omk.weights.v1 contract (releaseGate vector,
+ * normalize:true). The historical raw weights summed to 1.05; normalization
+ * divides weights, the regression penalty, and the verdict thresholds by the
+ * SAME factor (1/1.05), a pure uniform scaling — verdicts are mathematically
+ * identical for every input. Effective thresholds: preRelease ≈ 0.714286,
+ * stable ≈ 0.857143 (printed dynamically in reason strings).
  */
-import { RELEASE_GATE_WEIGHTS, } from "../runtime/contracts/weakness-remediation.js";
+import { releaseGateEffective } from "../runtime/weights-config.js";
 /** Factory that creates the default release promotion gate. */
 export function createReleasePromotionGate() {
+    const effective = releaseGateEffective();
+    const w = effective.weights;
+    const penalties = effective.penalties;
+    const preReleaseThreshold = effective.thresholds.preRelease;
+    const stableThreshold = effective.thresholds.stable;
     return {
         evaluate(inputs) {
-            const w = RELEASE_GATE_WEIGHTS;
             const demoRun = inputs.demoRun ?? false;
             const maturity = inputs.maturity ?? inputs.providerMinimum ?? 0;
             const versionConsistency = inputs.versionConsistency ?? inputs.semver ?? 1;
@@ -25,7 +36,7 @@ export function createReleasePromotionGate() {
                 w.proof * inputs.proofMedian +
                 w.maturity * maturity +
                 w.docs * inputs.docs * versionConsistency -
-                w.regression * inputs.regressionSeverity;
+                penalties.regression * inputs.regressionSeverity;
             const score = clamp01(rawScore);
             const reasons = [];
             const blocked = inputs.ci === 0 || inputs.freshInstallSmoke === 0 || versionConsistency === 0 || !demoRun;
@@ -48,20 +59,20 @@ export function createReleasePromotionGate() {
             if (blocked) {
                 verdict = "block";
             }
-            else if (score >= 0.90 && inputs.proofMedian >= 0.85 && maturity >= 0.80 && stableEligible) {
+            else if (score >= stableThreshold && inputs.proofMedian >= 0.85 && maturity >= 0.80 && stableEligible) {
                 verdict = "stable";
-                reasons.push(`Score ${formatScore(score)} meets stable threshold (≥0.90) with proof≥0.85, maturity≥0.80, live benchmark pass, sandbox violations=0, and exact-tag CI pass`);
+                reasons.push(`Score ${formatScore(score)} meets stable threshold (≥${stableThreshold.toFixed(2)}) with proof≥0.85, maturity≥0.80, live benchmark pass, sandbox violations=0, and exact-tag CI pass`);
             }
-            else if (score >= 0.75 && inputs.proofMedian >= 0.75) {
+            else if (score >= preReleaseThreshold && inputs.proofMedian >= 0.75) {
                 verdict = "pre-release";
-                reasons.push(`Score ${formatScore(score)} meets pre-release threshold (≥0.75) with proof≥0.75`);
-                if (score >= 0.90 && inputs.proofMedian >= 0.85 && maturity >= 0.80 && !stableEligible) {
+                reasons.push(`Score ${formatScore(score)} meets pre-release threshold (≥${preReleaseThreshold.toFixed(2)}) with proof≥0.75`);
+                if (score >= stableThreshold && inputs.proofMedian >= 0.85 && maturity >= 0.80 && !stableEligible) {
                     reasons.push("Stable verdict withheld until live benchmark passes, sandboxViolationCount is 0, and exact-tag CI passes");
                 }
             }
             else {
                 verdict = "block";
-                reasons.push(`Score ${formatScore(score)} below pre-release threshold (≥0.75) or proof below 0.75`);
+                reasons.push(`Score ${formatScore(score)} below pre-release threshold (≥${preReleaseThreshold.toFixed(2)}) or proof below 0.75`);
             }
             return {
                 score,

package/dist/cli/root.d.ts

@@ -1,4 +1,5 @@
 import type { Command } from "commander";
+export declare const OMK_ROOT_ENTRY_SURFACE = "omk-root-orchestrator";
 interface RootChatLaunchArgsOptions {
     readonly cliPath: string;
     readonly runId?: string;

package/dist/cli/root.js

@@ -3,6 +3,7 @@ import { t, initI18n } from "../util/i18n.js";
 import { buildCustomHelp } from "../util/help-text.js";
 const OMK_ENTRY_BRAND = "neon-grid";
 const OMK_ENTRY_UI = "neon-grid";
+export const OMK_ROOT_ENTRY_SURFACE = "omk-root-orchestrator";
 export function buildRootChatLaunchArgs(options) {
     const chatArgs = [
         options.cliPath,
@@ -90,7 +91,7 @@ export function configureRootProgram(program, OMK_VERSION, OMK_VERSION_FOOTER) {
         });
         const childEnv = {
             ...process.env,
-            OMK_ENTRY_SURFACE: "pi-omk",
+            OMK_ENTRY_SURFACE: OMK_ROOT_ENTRY_SURFACE,
         };
         const result = spawnSync(process.execPath, chatArgs, { stdio: "inherit", env: childEnv });
         if (result.status && result.status !== 0) {

package/dist/cli/theme/index.d.ts

@@ -1,9 +1,18 @@
 /**
  * CLI Theme — Barrel export for terminal capability, theme registry, and theme resolver.
  */
-export { getTerminalCapability, defaultThemeForCapability, } from "./terminal-capability.js";
-export type { TerminalCapability, ColorDepth, } from "./terminal-capability.js";
+export { getTerminalCapability, defaultThemeForCapability, detectColorTier, colorTierForDepth, } from "./terminal-capability.js";
+export type { TerminalCapability, ColorDepth, ColorTier, } from "./terminal-capability.js";
+export { hexToOklab, hexToRgb255, normalizeHex, nearestXterm256, buildXterm256Lookup, } from "./oklab-quantize.js";
+export type { OklabColor } from "./oklab-quantize.js";
+export { compileTheme } from "./render-table.js";
+export type { Ansi16Name, CompiledTheme, OmkThemeV1, RenderEntry, ThemeSemanticSpec, ThemeTokenKind, ThemeUsage, } from "./render-table.js";
 export { getBuiltinTheme, listBuiltinThemes, registerBuiltinTheme, __registry, } from "./theme-registry.js";
 export type { SemanticToken, ThemePalette, } from "./theme-registry.js";
 export { resolveTheme } from "./theme-resolver.js";
 export type { ResolveThemeOptions } from "./theme-resolver.js";
+export { renderStatusFrame } from "./status-frame.js";
+export { listThemeDocuments, loadThemeDocument, validateThemeDocument, } from "./theme-doc.js";
+export type { ThemeDocumentRef } from "./theme-doc.js";
+export { explainColorTier } from "./tier-explain.js";
+export type { ColorTierExplanation } from "./tier-explain.js";

package/dist/cli/theme/index.js

@@ -1,6 +1,11 @@
 /**
  * CLI Theme — Barrel export for terminal capability, theme registry, and theme resolver.
  */
-export { getTerminalCapability, defaultThemeForCapability, } from "./terminal-capability.js";
+export { getTerminalCapability, defaultThemeForCapability, detectColorTier, colorTierForDepth, } from "./terminal-capability.js";
+export { hexToOklab, hexToRgb255, normalizeHex, nearestXterm256, buildXterm256Lookup, } from "./oklab-quantize.js";
+export { compileTheme } from "./render-table.js";
 export { getBuiltinTheme, listBuiltinThemes, registerBuiltinTheme, __registry, } from "./theme-registry.js";
 export { resolveTheme } from "./theme-resolver.js";
+export { renderStatusFrame } from "./status-frame.js";
+export { listThemeDocuments, loadThemeDocument, validateThemeDocument, } from "./theme-doc.js";
+export { explainColorTier } from "./tier-explain.js";

package/dist/cli/theme/oklab-quantize.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CLI Theme — OKLab xterm-256 Quantizer
+ * Precomputes an OKLab nearest-neighbor lookup mapping 24-bit theme colors to
+ * xterm-256 indexes 16-255 ONLY. System colors 0-15 are never emitted because
+ * users commonly remap them, which would break theme contrast guarantees.
+ *
+ * Pure functions, no I/O. OKLab math is self-contained, ported from
+ * scripts/theme-check.mjs (Björn Ottosson sRGB → OKLab).
+ */
+export interface OklabColor {
+    readonly L: number;
+    readonly a: number;
+    readonly b: number;
+}
+/** Normalize "#aabbcc" / "AABBCC" to canonical "#AABBCC". Throws on bad input. */
+export declare function normalizeHex(hex: string): string;
+/** Parse a normalized 6-digit hex color into 0-255 RGB channels. */
+export declare function hexToRgb255(hex: string): readonly [number, number, number];
+export declare function hexToOklab(hex: string): OklabColor;
+/**
+ * Nearest xterm-256 index (16-255 only) for a 24-bit hex color, measured by
+ * Euclidean distance in OKLab.
+ */
+export declare function nearestXterm256(hex: string): number;
+/**
+ * Precompute a lookup table mapping each distinct theme color to its nearest
+ * xterm-256 index. Keys are normalized hex ("#AABBCC").
+ */
+export declare function buildXterm256Lookup(hexes: readonly string[]): ReadonlyMap<string, number>;

package/dist/cli/theme/oklab-quantize.js

@@ -0,0 +1,105 @@
+/**
+ * CLI Theme — OKLab xterm-256 Quantizer
+ * Precomputes an OKLab nearest-neighbor lookup mapping 24-bit theme colors to
+ * xterm-256 indexes 16-255 ONLY. System colors 0-15 are never emitted because
+ * users commonly remap them, which would break theme contrast guarantees.
+ *
+ * Pure functions, no I/O. OKLab math is self-contained, ported from
+ * scripts/theme-check.mjs (Björn Ottosson sRGB → OKLab).
+ */
+function linearize(c) {
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function channelsToOklab(r255, g255, b255) {
+    const r = linearize(r255 / 255);
+    const g = linearize(g255 / 255);
+    const b = linearize(b255 / 255);
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    return {
+        L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+        a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+        b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+    };
+}
+const HEX6_RE = /^#?[0-9A-Fa-f]{6}$/;
+/** Normalize "#aabbcc" / "AABBCC" to canonical "#AABBCC". Throws on bad input. */
+export function normalizeHex(hex) {
+    if (!HEX6_RE.test(hex)) {
+        throw new Error(`oklab-quantize: invalid 24-bit hex color "${hex}"`);
+    }
+    const v = hex.startsWith("#") ? hex.slice(1) : hex;
+    return `#${v.toUpperCase()}`;
+}
+/** Parse a normalized 6-digit hex color into 0-255 RGB channels. */
+export function hexToRgb255(hex) {
+    const v = normalizeHex(hex).slice(1);
+    return [
+        Number.parseInt(v.slice(0, 2), 16),
+        Number.parseInt(v.slice(2, 4), 16),
+        Number.parseInt(v.slice(4, 6), 16),
+    ];
+}
+export function hexToOklab(hex) {
+    const [r, g, b] = hexToRgb255(hex);
+    return channelsToOklab(r, g, b);
+}
+// xterm 6x6x6 color-cube channel levels (indexes 16-231).
+const CUBE_LEVELS = [0, 95, 135, 175, 215, 255];
+/** Build the OKLab palette for xterm indexes 16-255 (cube + grayscale ramp). */
+function buildXtermPalette() {
+    const entries = [];
+    for (let r = 0; r < 6; r++) {
+        for (let g = 0; g < 6; g++) {
+            for (let b = 0; b < 6; b++) {
+                entries.push({
+                    index: 16 + 36 * r + 6 * g + b,
+                    lab: channelsToOklab(CUBE_LEVELS[r], CUBE_LEVELS[g], CUBE_LEVELS[b]),
+                });
+            }
+        }
+    }
+    // Grayscale ramp: indexes 232-255 map to gray levels 8, 18, ..., 238.
+    for (let i = 0; i < 24; i++) {
+        const v = 8 + 10 * i;
+        entries.push({ index: 232 + i, lab: channelsToOklab(v, v, v) });
+    }
+    return entries;
+}
+// Precomputed once at module load — this is the "theme build/load time" cost.
+const XTERM_PALETTE = buildXtermPalette();
+/**
+ * Nearest xterm-256 index (16-255 only) for a 24-bit hex color, measured by
+ * Euclidean distance in OKLab.
+ */
+export function nearestXterm256(hex) {
+    const lab = hexToOklab(hex);
+    let bestIndex = 16;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (const entry of XTERM_PALETTE) {
+        const dL = lab.L - entry.lab.L;
+        const da = lab.a - entry.lab.a;
+        const db = lab.b - entry.lab.b;
+        const dist = dL * dL + da * da + db * db;
+        if (dist < bestDist) {
+            bestDist = dist;
+            bestIndex = entry.index;
+        }
+    }
+    return bestIndex;
+}
+/**
+ * Precompute a lookup table mapping each distinct theme color to its nearest
+ * xterm-256 index. Keys are normalized hex ("#AABBCC").
+ */
+export function buildXterm256Lookup(hexes) {
+    const lookup = new Map();
+    for (const hex of hexes) {
+        const key = normalizeHex(hex);
+        if (!lookup.has(key)) {
+            lookup.set(key, nearestXterm256(key));
+        }
+    }
+    return lookup;
+}

package/dist/cli/theme/render-table.d.ts

@@ -0,0 +1,59 @@
+/**
+ * CLI Theme — Render Table Compiler
+ * Compiles an omk.theme.v1 document (themes/*.theme.json) into per-surface
+ * render tables at startup. For each semantic token it precomputes the SGR
+ * sequence for the requested degradation tier:
+ *   truecolor → SGR 38;2;R;G;B
+ *   256       → SGR 38;5;N via the OKLab nearest-neighbor lookup (16-255 only)
+ *   16        → the theme's hand-authored ansi16 (fallback16) mapping
+ *   no-color  → empty string
+ * Single entrypoint: compileTheme(theme, tier).
+ */
+import type { ColorTier } from "./terminal-capability.js";
+export type ThemeUsage = "text" | "indicator" | "background";
+export type ThemeTokenKind = "state" | "chrome" | "background";
+export type Ansi16Name = "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "brightBlack" | "brightRed" | "brightGreen" | "brightYellow" | "brightBlue" | "brightMagenta" | "brightCyan" | "brightWhite";
+export interface ThemeSemanticSpec {
+    readonly color: string;
+    readonly glyph?: string;
+    readonly kind?: ThemeTokenKind;
+    readonly usage: ThemeUsage;
+}
+export interface OmkThemeV1 {
+    readonly schemaVersion: "omk.theme.v1";
+    readonly name: string;
+    readonly displayName?: string;
+    readonly mode: "dark" | "light";
+    readonly primitives: Readonly<Record<string, string>>;
+    readonly backgrounds: readonly string[];
+    readonly semantics: Readonly<Record<string, ThemeSemanticSpec>>;
+    readonly components: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    readonly fallback16: Readonly<Record<string, string>>;
+}
+export interface RenderEntry {
+    /** Semantic role this entry resolves (e.g. "dag.lane.running"). */
+    readonly role: string;
+    /** Canonical 24-bit hex of the underlying primitive. */
+    readonly hex: string;
+    /** Mandatory state glyph, or "" for chrome/background tokens. */
+    readonly glyph: string;
+    /** Precomputed SGR open sequence for the compiled tier ("" on no-color). */
+    readonly sgr: string;
+}
+export interface CompiledTheme {
+    readonly name: string;
+    readonly tier: ColorTier;
+    /** SGR reset for this tier ("" on no-color). */
+    readonly reset: string;
+    /** Semantic role → precomputed render entry. */
+    readonly tokens: Readonly<Record<string, RenderEntry>>;
+    /** Component surface → slot → precomputed render entry. */
+    readonly surfaces: Readonly<Record<string, Readonly<Record<string, RenderEntry>>>>;
+    /** Wrap text in the precomputed sequence for a semantic role. */
+    readonly paint: (role: string, text: string) => string;
+}
+/**
+ * Compile an omk.theme.v1 document into a per-surface render table for one
+ * degradation tier. Pure: computes everything up front, performs no I/O.
+ */
+export declare function compileTheme(theme: OmkThemeV1, tier: ColorTier): CompiledTheme;

package/dist/cli/theme/render-table.js

@@ -0,0 +1,112 @@
+/**
+ * CLI Theme — Render Table Compiler
+ * Compiles an omk.theme.v1 document (themes/*.theme.json) into per-surface
+ * render tables at startup. For each semantic token it precomputes the SGR
+ * sequence for the requested degradation tier:
+ *   truecolor → SGR 38;2;R;G;B
+ *   256       → SGR 38;5;N via the OKLab nearest-neighbor lookup (16-255 only)
+ *   16        → the theme's hand-authored ansi16 (fallback16) mapping
+ *   no-color  → empty string
+ * Single entrypoint: compileTheme(theme, tier).
+ */
+import { buildXterm256Lookup, normalizeHex, hexToRgb255 } from "./oklab-quantize.js";
+const ESC = "\u001b[";
+const SGR_RESET = `${ESC}0m`;
+// Foreground SGR codes for the 16-color tier (standard 30-37, bright 90-97).
+const ANSI16_FG = {
+    black: 30,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    blue: 34,
+    magenta: 35,
+    cyan: 36,
+    white: 37,
+    brightBlack: 90,
+    brightRed: 91,
+    brightGreen: 92,
+    brightYellow: 93,
+    brightBlue: 94,
+    brightMagenta: 95,
+    brightCyan: 96,
+    brightWhite: 97,
+};
+function isAnsi16Name(name) {
+    return Object.prototype.hasOwnProperty.call(ANSI16_FG, name);
+}
+function resolvePrimitiveHex(theme, role, color) {
+    const raw = theme.primitives[color];
+    if (raw === undefined) {
+        throw new Error(`compileTheme(${theme.name}): semantic "${role}" references unknown primitive "${color}"`);
+    }
+    return normalizeHex(raw);
+}
+function sgrForTier(theme, role, hex, tier, lookup256) {
+    switch (tier) {
+        case "truecolor": {
+            const [r, g, b] = hexToRgb255(hex);
+            return `${ESC}38;2;${r};${g};${b}m`;
+        }
+        case "256": {
+            const index = lookup256.get(hex);
+            if (index === undefined) {
+                throw new Error(`compileTheme(${theme.name}): missing 256-color lookup for "${role}" (${hex})`);
+            }
+            return `${ESC}38;5;${index}m`;
+        }
+        case "16": {
+            const name = theme.fallback16[role];
+            if (name === undefined || !isAnsi16Name(name)) {
+                throw new Error(`compileTheme(${theme.name}): semantic "${role}" has no valid ansi16 fallback (got "${name ?? "<missing>"}")`);
+            }
+            return `${ESC}${ANSI16_FG[name]}m`;
+        }
+        case "no-color":
+            return "";
+    }
+}
+/**
+ * Compile an omk.theme.v1 document into a per-surface render table for one
+ * degradation tier. Pure: computes everything up front, performs no I/O.
+ */
+export function compileTheme(theme, tier) {
+    // Precompute the OKLab → xterm-256 lookup once per compile (build/load time).
+    const distinctHexes = Object.entries(theme.semantics).map(([role, spec]) => resolvePrimitiveHex(theme, role, spec.color));
+    const lookup256 = tier === "256" ? buildXterm256Lookup(distinctHexes) : new Map();
+    const tokens = {};
+    for (const [role, spec] of Object.entries(theme.semantics)) {
+        const hex = resolvePrimitiveHex(theme, role, spec.color);
+        tokens[role] = {
+            role,
+            hex,
+            glyph: spec.glyph ?? "",
+            sgr: sgrForTier(theme, role, hex, tier, lookup256),
+        };
+    }
+    const surfaces = {};
+    for (const [surface, slots] of Object.entries(theme.components)) {
+        const compiled = {};
+        for (const [slot, role] of Object.entries(slots)) {
+            const entry = tokens[role];
+            if (entry === undefined) {
+                throw new Error(`compileTheme(${theme.name}): component ${surface}.${slot} references unknown semantic role "${role}"`);
+            }
+            compiled[slot] = entry;
+        }
+        surfaces[surface] = compiled;
+    }
+    const reset = tier === "no-color" ? "" : SGR_RESET;
+    return {
+        name: theme.name,
+        tier,
+        reset,
+        tokens,
+        surfaces,
+        paint(role, text) {
+            const entry = tokens[role];
+            if (entry === undefined || entry.sgr === "")
+                return text;
+            return entry.sgr + text + reset;
+        },
+    };
+}

package/dist/cli/theme/status-frame.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI Theme — Representative Status Frame
+ * Renders the ONE representative TUI status frame shared by the four-tier
+ * degradation snapshots (test/theme-degradation.test.mjs) and the
+ * `omk theme preview <name>` CLI surface. Keeping a single renderer
+ * guarantees the CLI preview shows exactly the snapshot-gated frame.
+ */
+import type { CompiledTheme } from "./render-table.js";
+/** One representative TUI status frame built from theme tokens + glyphs. */
+export declare function renderStatusFrame(ct: CompiledTheme): string;

package/dist/cli/theme/status-frame.js

@@ -0,0 +1,22 @@
+/**
+ * CLI Theme — Representative Status Frame
+ * Renders the ONE representative TUI status frame shared by the four-tier
+ * degradation snapshots (test/theme-degradation.test.mjs) and the
+ * `omk theme preview <name>` CLI surface. Keeping a single renderer
+ * guarantees the CLI preview shows exactly the snapshot-gated frame.
+ */
+function paintWithGlyph(ct, role, text) {
+    const entry = ct.tokens[role];
+    const glyph = entry?.glyph ?? "";
+    return ct.paint(role, glyph === "" ? text : `${glyph} ${text}`);
+}
+/** One representative TUI status frame built from theme tokens + glyphs. */
+export function renderStatusFrame(ct) {
+    const p = (role, text) => paintWithGlyph(ct, role, text);
+    return [
+        `${p("control.accent", "OMK//CONTROL")} ${p("control.dim", "night-city ops console")}`,
+        `${p("dag.lane.running", "lane compile")}  ${p("dag.lane.done", "lane schema")}  ${p("dag.lane.queued", "lane docs")}`,
+        `${p("evidence.pass", "contrast 48/48")}  ${p("evidence.pending", "snapshots")}  ${p("route.fallback", "provider kimi")}`,
+        `${p("telemetry.warn", "headroom 81%")}  ${p("control.fg", "tier ready")}`,
+    ].join("\n");
+}

package/dist/cli/theme/terminal-capability.d.ts

@@ -3,15 +3,20 @@
  * Detects color support, unicode, TTY status, and terminal dimensions.
  */
 export type ColorDepth = 0 | 1 | 4 | 8 | 24;
+/** Degradation tier used by the render-table compiler. */
+export type ColorTier = "truecolor" | "256" | "16" | "no-color";
 export interface TerminalCapability {
     readonly isTty: boolean;
     readonly isCi: boolean;
     readonly colorDisabled: boolean;
     readonly colorDepth: ColorDepth;
+    readonly colorTier: ColorTier;
     readonly unicode: boolean;
     readonly width: number;
 }
-export declare function getTerminalCapability(): TerminalCapability;
+export declare function colorTierForDepth(depth: ColorDepth): ColorTier;
+export declare function detectColorTier(argv?: readonly string[]): ColorTier;
+export declare function getTerminalCapability(argv?: readonly string[]): TerminalCapability;
 export declare function defaultThemeForCapability(cap: TerminalCapability): {
     name: string;
     mode: "dark" | "light" | "auto" | "mono";

package/dist/cli/theme/terminal-capability.js

@@ -14,8 +14,11 @@ function detectCi() {
         || process.env.APPVEYOR
         || process.env.JENKINS_URL);
 }
-function detectColorDepth() {
-    // Explicit opt-out
+function detectColorDepth(argv = process.argv) {
+    // Explicit opt-out: --no-color CLI flag or NO_COLOR env
+    if (argv.includes("--no-color")) {
+        return 0;
+    }
     if (process.env.NO_COLOR !== undefined || process.env.TERM === "dumb") {
         return 0;
     }
@@ -65,14 +68,27 @@ function getTerminalWidth() {
     }
     return 80;
 }
-export function getTerminalCapability() {
+export function colorTierForDepth(depth) {
+    if (depth === 24)
+        return "truecolor";
+    if (depth === 8)
+        return "256";
+    if (depth === 4 || depth === 1)
+        return "16";
+    return "no-color";
+}
+export function detectColorTier(argv = process.argv) {
+    return colorTierForDepth(detectColorDepth(argv));
+}
+export function getTerminalCapability(argv = process.argv) {
     const isCi = detectCi();
-    const colorDepth = detectColorDepth();
+    const colorDepth = detectColorDepth(argv);
     return {
         isTty: process.stdout.isTTY ?? false,
         isCi,
         colorDisabled: colorDepth === 0,
         colorDepth,
+        colorTier: colorTierForDepth(colorDepth),
         unicode: detectUnicode(),
         width: getTerminalWidth(),
     };

package/dist/cli/theme/theme-doc.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CLI Theme — omk.theme.v1 Document Loader
+ * Discovers, loads, and structurally validates themes/*.theme.json documents
+ * (the executable twin of schemas/omk.theme.v1.schema.json, mirroring
+ * scripts/theme-check.mjs validateTheme()). Read-only filesystem access.
+ */
+import type { OmkThemeV1 } from "./render-table.js";
+export interface ThemeDocumentRef {
+    /** Theme name derived from the file name (e.g. "night-city"). */
+    readonly name: string;
+    /** Absolute path of the .theme.json document. */
+    readonly path: string;
+}
+/** List omk.theme.v1 documents discoverable from cwd (or the package root). */
+export declare function listThemeDocuments(cwd?: string): readonly ThemeDocumentRef[];
+/** Load one theme document by name. Returns undefined when absent/unreadable. */
+export declare function loadThemeDocument(name: string, cwd?: string): OmkThemeV1 | undefined;
+/**
+ * Structural validation of an omk.theme.v1 document — the same executable
+ * rules scripts/theme-check.mjs enforces in CI. Returns [] when valid.
+ */
+export declare function validateThemeDocument(theme: OmkThemeV1): readonly string[];

package/dist/cli/theme/theme-doc.js

@@ -0,0 +1,97 @@
+/**
+ * CLI Theme — omk.theme.v1 Document Loader
+ * Discovers, loads, and structurally validates themes/*.theme.json documents
+ * (the executable twin of schemas/omk.theme.v1.schema.json, mirroring
+ * scripts/theme-check.mjs validateTheme()). Read-only filesystem access.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const ANSI16_NAMES = new Set([
+    "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white",
+    "brightBlack", "brightRed", "brightGreen", "brightYellow",
+    "brightBlue", "brightMagenta", "brightCyan", "brightWhite",
+]);
+/** Candidate themes/ directories: project cwd first, then the package root. */
+function themesDirCandidates(cwd) {
+    const moduleRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+    const candidates = [join(cwd, "themes"), join(moduleRoot, "themes")];
+    return [...new Set(candidates)];
+}
+/** List omk.theme.v1 documents discoverable from cwd (or the package root). */
+export function listThemeDocuments(cwd = process.cwd()) {
+    for (const dir of themesDirCandidates(cwd)) {
+        if (!existsSync(dir))
+            continue;
+        const refs = readdirSync(dir)
+            .filter((f) => f.endsWith(".theme.json"))
+            .map((f) => ({ name: f.replace(/\.theme\.json$/, ""), path: join(dir, f) }));
+        if (refs.length > 0)
+            return refs;
+    }
+    return [];
+}
+/** Load one theme document by name. Returns undefined when absent/unreadable. */
+export function loadThemeDocument(name, cwd = process.cwd()) {
+    const ref = listThemeDocuments(cwd).find((r) => r.name === name);
+    if (ref === undefined)
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(ref.path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Structural validation of an omk.theme.v1 document — the same executable
+ * rules scripts/theme-check.mjs enforces in CI. Returns [] when valid.
+ */
+export function validateThemeDocument(theme) {
+    const errors = [];
+    const err = (m) => { errors.push(m); };
+    if (theme.schemaVersion !== "omk.theme.v1")
+        err(`schemaVersion must be "omk.theme.v1"`);
+    if (!/^[a-z][a-z0-9-]*$/.test(theme.name ?? ""))
+        err("invalid theme name");
+    if (theme.mode !== "dark" && theme.mode !== "light")
+        err("mode must be dark|light");
+    const primitives = theme.primitives ?? {};
+    for (const [k, v] of Object.entries(primitives)) {
+        if (!/^#[0-9A-Fa-f]{6}$/.test(v))
+            err(`primitive ${k}: bad hex ${v}`);
+    }
+    for (const bg of theme.backgrounds ?? []) {
+        if (primitives[bg] === undefined)
+            err(`background "${bg}" is not a primitive`);
+    }
+    const semantics = theme.semantics ?? {};
+    for (const [role, spec] of Object.entries(semantics)) {
+        if (primitives[spec.color] === undefined)
+            err(`semantic ${role}: color "${spec.color}" is not a primitive`);
+        const kind = spec.kind ?? "state";
+        if (kind === "state" && (spec.glyph === undefined || spec.glyph === "")) {
+            err(`semantic state ${role}: missing mandatory glyph`);
+        }
+        if (!["text", "indicator", "background"].includes(spec.usage))
+            err(`semantic ${role}: bad usage`);
+    }
+    for (const [comp, slots] of Object.entries(theme.components ?? {})) {
+        for (const [slot, role] of Object.entries(slots)) {
+            if (semantics[role] === undefined)
+                err(`component ${comp}.${slot}: unknown semantic role "${role}"`);
+        }
+    }
+    const fb = theme.fallback16 ?? {};
+    for (const role of Object.keys(semantics)) {
+        if (fb[role] === undefined)
+            err(`fallback16: missing entry for semantic role "${role}"`);
+    }
+    for (const [role, name] of Object.entries(fb)) {
+        if (!ANSI16_NAMES.has(name))
+            err(`fallback16 ${role}: unknown ANSI-16 name "${name}"`);
+        if (semantics[role] === undefined)
+            err(`fallback16 ${role}: no such semantic role`);
+    }
+    return errors;
+}