groundwork-method 0.0.1 → 0.10.0

package/src/generators/workspace-dev-cli/cli-src/src/commands/surface.ts

@@ -0,0 +1,214 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { Ctx, CliError } from '../util/context';
+import { ROOT, GROUNDWORK_SURFACES_FILE } from '../util/paths';
+import { Painter } from '../theme/color';
+import { Renderer } from '../theme/render';
+
+// ---------------------------------------------------------------------------
+// Surface registry & capability ledger (`./dev surface status`)
+//
+// Read-only view over .groundwork/surfaces.json — the machine-readable twin of
+// docs/surfaces.md. Architecture writes it, bet validation appends capability
+// rows, surface activation appends surfaces; this command only reads.
+// ---------------------------------------------------------------------------
+
+interface Surface {
+  slug: string;
+  type?: string;
+  platform?: string;
+  status?: string; // active | planned | dormant | retired
+  coreAccess?: string;
+  auth?: string;
+  scaffold?: string;
+  testMedium?: string | null;
+  designTrack?: string;
+}
+
+interface LedgerCell {
+  state?: string; // delivered | planned | omitted | n/a
+  bet?: string;
+  ref?: string;
+  rationale?: string;
+}
+
+interface Capability {
+  key: string;
+  name?: string;
+  cells?: Record<string, LedgerCell>;
+}
+
+interface SurfacesFile {
+  schema?: string;
+  version?: number;
+  core?: { deployment?: string; contractFormat?: string; contractsPath?: string };
+  surfaces?: Surface[];
+  capabilities?: Capability[];
+}
+
+function readSurfacesFile(): SurfacesFile | null {
+  if (!fs.existsSync(GROUNDWORK_SURFACES_FILE)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(GROUNDWORK_SURFACES_FILE, 'utf8')) as SurfacesFile;
+  } catch {
+    throw new CliError(
+      `Could not parse ${path.relative(ROOT, GROUNDWORK_SURFACES_FILE)}`,
+      'Fix or remove the malformed JSON file — docs/surfaces.md is its human twin.',
+    );
+  }
+}
+
+function isRetired(s: Surface): boolean {
+  return s.status === 'retired';
+}
+
+/** One painted character per ledger state. A missing or unknown state renders as
+ *  the illegal empty cell — loud on purpose: bet validation fills every column. */
+function cellGlyph(p: Painter, state: string | undefined): string {
+  const u = p.caps.unicode;
+  if (state === 'delivered') return p.paint('success', u ? '●' : '*');
+  if (state === 'planned') return p.paint('warning', u ? '◐' : '~');
+  if (state === 'omitted') return p.dim(u ? '○' : 'o');
+  if (state === 'n/a') return p.dim(u ? '·' : '.');
+  return p.paint('error', '!');
+}
+
+/** Planned-cell counts per non-retired surface — the sync backlog at a glance.
+ *  Retired columns are frozen history and never count as backlog. */
+function backlogOf(surfaces: Surface[], capabilities: Capability[]): Record<string, number> {
+  const backlog: Record<string, number> = {};
+  for (const s of surfaces) {
+    if (!isRetired(s)) backlog[s.slug] = 0;
+  }
+  for (const cap of capabilities) {
+    for (const slug of Object.keys(backlog)) {
+      if (cap.cells?.[slug]?.state === 'planned') backlog[slug] += 1;
+    }
+  }
+  return backlog;
+}
+
+/** Cells that are missing or carry an unknown state — the machine form of the
+ *  illegal empty ledger cell. Every registry surface gets a column, retired
+ *  included (frozen history or auto-n/a per the retired-column rule). */
+function illegalCellsOf(surfaces: Surface[], capabilities: Capability[]): string[] {
+  const states = new Set(['delivered', 'planned', 'omitted', 'n/a']);
+  const out: string[] = [];
+  for (const cap of capabilities) {
+    for (const s of surfaces) {
+      const cell = cap.cells?.[s.slug];
+      if (!cell || !cell.state || !states.has(cell.state)) {
+        out.push(`${cap.key} × ${s.slug}`);
+      }
+    }
+  }
+  return out;
+}
+
+/** Pad to a visible width, ANSI-safe: pad the plain text, then paint — painted
+ *  strings defeat padEnd (the table comment in bet.ts explains why). */
+function padPlain(text: string, width: number): string {
+  return text.padEnd(width);
+}
+
+export async function surfaceCmd(ctx: Ctx): Promise<number> {
+  const noun = ctx.args.filter((a) => !a.startsWith('-'))[0] ?? 'status';
+  switch (noun) {
+    case 'status':
+      return status(ctx);
+    default:
+      throw new CliError('Usage: ./dev surface status [--json]');
+  }
+}
+
+async function status(ctx: Ctx): Promise<number> {
+  const { r } = ctx;
+  const json = ctx.json || ctx.args.includes('--json');
+  const file = readSurfacesFile();
+  const ro = r.asStream(process.stdout);
+
+  if (!file) {
+    if (json) {
+      process.stdout.write(JSON.stringify({ present: false }, null, 2) + '\n');
+      return 0;
+    }
+    ro.info('No surface registry (.groundwork/surfaces.json) — the groundwork-surface-activation skill bootstraps it.');
+    return 0;
+  }
+
+  const surfaces = (file.surfaces ?? []).filter((s) => Boolean(s.slug));
+  const capabilities = (file.capabilities ?? []).filter((c) => Boolean(c.key));
+  const backlog = backlogOf(surfaces, capabilities);
+  const illegalCells = illegalCellsOf(surfaces, capabilities);
+
+  if (json) {
+    process.stdout.write(
+      JSON.stringify({ present: true, core: file.core ?? null, surfaces, capabilities, backlog, illegalCells }, null, 2) + '\n',
+    );
+    return 0;
+  }
+
+  const p = ro.painter;
+  ro.logo('Surface Board');
+
+  // --- Registry: slug, type, platform, status, scaffold, test medium ---------
+  ro.table(
+    'Surface Registry',
+    surfaces.map((s) => {
+      const slug = isRetired(s) ? p.dim(padPlain(`${s.slug} (retired)`, 28)) : padPlain(s.slug, 28);
+      const shape = `${s.type ?? '?'} · ${s.platform ?? '?'}`;
+      const detail = `${s.status ?? '?'} · ${s.scaffold ?? '?'} · ${s.testMedium ?? '—'}`;
+      return [slug, shape, detail] as [string, string, string];
+    }),
+  );
+  if (surfaces.length === 0) {
+    ro.info('Registry is empty — a headless core is legal; its contracts stand alone.');
+  }
+
+  // --- Capability ledger: rows × surface columns -----------------------------
+  if (capabilities.length === 0) {
+    ro.info('Capability ledger is empty — bet validation appends capability rows when bets close.');
+  } else {
+    const keyWidth = Math.max(...capabilities.map((c) => c.key.length), 'capability'.length) + 2;
+    const colWidth = (s: Surface): number => (isRetired(s) ? s.slug.length + ' (retired)'.length : s.slug.length) + 2;
+    const header =
+      p.dim(padPlain('capability', keyWidth)) +
+      surfaces
+        .map((s) => (isRetired(s) ? p.dim(padPlain(`${s.slug} (retired)`, colWidth(s))) : padPlain(s.slug, colWidth(s))))
+        .join('');
+    const rows: Array<[string, string, string]> = [[header, '', '']];
+    for (const cap of capabilities) {
+      const line =
+        padPlain(cap.key, keyWidth) +
+        surfaces
+          .map((s) => cellGlyph(p, cap.cells?.[s.slug]?.state) + ' '.repeat(colWidth(s) - 1))
+          .join('');
+      rows.push([line, '', '']);
+    }
+    ro.table('Capability Ledger', rows);
+    const u = p.caps.unicode;
+    ro.info(
+      `${cellGlyph(p, 'delivered')} delivered  ${cellGlyph(p, 'planned')} planned  ${cellGlyph(p, 'omitted')} omitted  ${cellGlyph(p, 'n/a')} n/a  ${p.paint('error', '!')} empty ${u ? '—' : '-'} illegal`,
+    );
+  }
+
+  // --- Illegal empty cells: a real signal, never hidden -----------------------
+  for (const cell of illegalCells) {
+    ro.error(`Empty ledger cell: ${cell} — illegal state; bet validation fills every column or the bet does not close.`);
+  }
+
+  // --- Sync backlog: planned cells per active surface -------------------------
+  const entries = Object.entries(backlog);
+  if (entries.length > 0 && capabilities.length > 0) {
+    ro.step('Sync backlog (planned cells)');
+    for (const [slug, count] of entries) {
+      ro.cmd(slug, count === 0 ? 'in sync — no planned cells' : `${count} planned cell${count === 1 ? '' : 's'}`);
+    }
+    const total = entries.reduce((acc, [, n]) => acc + n, 0);
+    if (total === 0 && illegalCells.length === 0) {
+      ro.success('All surfaces in sync — every ledger decision is on record.');
+    }
+  }
+
+  return 0;
+}

package/src/generators/workspace-dev-cli/cli-src/src/index.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import * as fs from 'fs';
+import { CommandDef, buildRegistry, findCommand } from './registry';
+import { Ctx, CliError, UsageError } from './util/context';
+import { makeRenderer, Renderer } from './theme/render';
+import { CONFIG_PATH } from './util/paths';
+import { DEV_CLI_VERSION } from './util/version';
+import { parseRunners } from './util/runners';
+import { loadProjectCommands } from './util/extensions';
+
+interface DevConfig {
+  projectPrefix?: string;
+  identity?: unknown;
+  terminal?: unknown;
+  runners?: unknown;
+}
+
+function loadConfig(): { config: DevConfig; tokens: unknown } {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')) as DevConfig;
+      return { config: raw, tokens: { identity: raw.identity, terminal: raw.terminal } };
+    }
+  } catch {
+    /* fall through to defaults */
+  }
+  return { config: {}, tokens: {} };
+}
+
+/** Built-in groups render first, in this order; project-declared groups (PROJECT and
+ *  any custom name) follow, so a project's own verbs are visible but never crowd out the
+ *  golden-path lifecycle. */
+const CORE_GROUPS = ['LIFECYCLE', 'QUALITY', 'BET WORKFLOW', 'META'];
+
+function showHelp(r: Renderer, commands: CommandDef[]): void {
+  r.logo('Local Development CLI');
+  const present = [...new Set(commands.map((c) => c.group))];
+  const order = [
+    ...CORE_GROUPS.filter((g) => present.includes(g)),
+    ...present.filter((g) => !CORE_GROUPS.includes(g)).sort(),
+  ];
+  for (const g of order) {
+    const cmds = commands.filter((c) => c.group === g);
+    if (cmds.length === 0) continue;
+    r.category(g);
+    for (const c of cmds) r.cmd(c.name, c.summary);
+  }
+  process.stderr.write('\n');
+}
+
+async function main(): Promise<number> {
+  const argv = process.argv.slice(2);
+
+  if (argv.includes('--version')) {
+    process.stdout.write(`${DEV_CLI_VERSION}\n`);
+    return 0;
+  }
+
+  // Extract global flags from anywhere in the args.
+  let json = false;
+  let help = false;
+  const rest: string[] = [];
+  for (const a of argv) {
+    if (a === '--json') json = true;
+    else if (a === '-h' || a === '--help') help = true;
+    else if (a === '-v' || a === '--verbose') {
+      /* accepted, no-op */
+    } else rest.push(a);
+  }
+
+  const { config, tokens } = loadConfig();
+  const r = makeRenderer(tokens);
+
+  // The merged registry: built-ins plus the project's own commands, the latter
+  // shadowing a built-in of the same name. One source of truth for dispatch, help,
+  // and completion.
+  const registry = buildRegistry(loadProjectCommands());
+
+  const command = rest[0];
+  const args = rest.slice(1);
+
+  if (!command || command === 'help' || help) {
+    showHelp(r, registry);
+    return 0;
+  }
+
+  const def = findCommand(registry, command);
+  if (!def) {
+    r.error(`Unknown command: ${command}`);
+    showHelp(r, registry);
+    return 2;
+  }
+
+  const ctx: Ctx = {
+    r,
+    json,
+    args,
+    projectPrefix: config.projectPrefix || 'workspace',
+    runners: parseRunners(config.runners),
+    commands: registry,
+  };
+
+  return def.handler(ctx);
+}
+
+// Graceful Ctrl+C — never leave the terminal in a bad state.
+process.on('SIGINT', () => {
+  process.stderr.write('\n');
+  process.stderr.write('\x1b[?25h'); // restore cursor in case a spinner was active
+  process.exit(130);
+});
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    const r = makeRenderer({});
+    if (err instanceof CliError) {
+      r.errorCard(err.message, err.action);
+      process.exit(1);
+    }
+    if (err instanceof UsageError) {
+      r.error(err.message);
+      process.exit(2);
+    }
+    r.errorCard(err?.message ?? String(err));
+    process.exit(1);
+  });

package/src/generators/workspace-dev-cli/cli-src/src/registry.ts

@@ -0,0 +1,194 @@
+import * as path from 'path';
+import { Ctx } from './util/context';
+import * as lifecycle from './commands/lifecycle';
+import * as quality from './commands/quality';
+import { doctor } from './commands/doctor';
+import * as bet from './commands/bet';
+import { surfaceCmd } from './commands/surface';
+import { completion } from './commands/completion';
+import { ProjectCommand } from './util/extensions';
+import { run } from './util/proc';
+import { ROOT } from './util/paths';
+
+/** Built-in groups, plus `PROJECT` and any custom group a project command declares.
+ *  The `string & {}` keeps editor completion for the known literals while admitting
+ *  project-defined group names. */
+export type CommandGroup = 'LIFECYCLE' | 'QUALITY' | 'BET WORKFLOW' | 'META' | 'PROJECT' | (string & {});
+
+export interface FlagDef {
+  name: string;
+  desc: string;
+}
+
+export interface CommandDef {
+  name: string;
+  group: CommandGroup;
+  summary: string;
+  /** Sub-nouns for completion (e.g. `new` → bet, milestone, slice). */
+  nouns?: string[];
+  flags?: FlagDef[];
+  handler: (ctx: Ctx) => Promise<number>;
+}
+
+/** The declarative command registry. This is the single source of truth that drives
+ *  dispatch, `--help`, shell completion, and usage validation — so they cannot drift. */
+export const COMMANDS: CommandDef[] = [
+  {
+    name: 'start',
+    group: 'LIFECYCLE',
+    summary: 'Boot infrastructure (Docker) + app services (native)',
+    flags: [{ name: '--docker', desc: 'Run all services in Docker' }],
+    handler: lifecycle.start,
+  },
+  {
+    name: 'stop',
+    group: 'LIFECYCLE',
+    summary: 'Gracefully tear down all services',
+    handler: lifecycle.stop,
+  },
+  {
+    name: 'reset',
+    group: 'LIFECYCLE',
+    summary: 'Stop, wipe volumes, start & migrate (full recycle)',
+    flags: [{ name: '--docker', desc: 'Recycle the all-Docker topology' }],
+    handler: lifecycle.reset,
+  },
+  {
+    name: 'migrate',
+    group: 'LIFECYCLE',
+    summary: 'Create service databases & apply schemas',
+    handler: lifecycle.migrate,
+  },
+  {
+    name: 'status',
+    group: 'LIFECYCLE',
+    summary: 'Show running services (--watch for a live dashboard)',
+    flags: [
+      { name: '--json', desc: 'Emit machine-readable JSON' },
+      { name: '--watch', desc: 'Live-refreshing dashboard (TTY only)' },
+    ],
+    handler: lifecycle.status,
+  },
+  {
+    name: 'logs',
+    group: 'LIFECYCLE',
+    summary: 'Print recent logs (logs <service> to filter; --follow to stream)',
+    flags: [{ name: '--follow', desc: 'Stream logs (TTY only)' }],
+    handler: lifecycle.logs,
+  },
+  {
+    name: 'health',
+    group: 'LIFECYCLE',
+    summary: 'Poll every app service + Jaeger health endpoint',
+    flags: [{ name: '--json', desc: 'Emit machine-readable JSON' }],
+    handler: lifecycle.health,
+  },
+  {
+    name: 'clean',
+    group: 'LIFECYCLE',
+    summary: 'Tear down & wipe state (--hard wipes volumes)',
+    flags: [{ name: '--hard', desc: 'Also wipe Docker volumes' }],
+    handler: lifecycle.clean,
+  },
+  {
+    name: 'doctor',
+    group: 'QUALITY',
+    summary: 'Verify the local environment',
+    flags: [{ name: '--json', desc: 'Emit machine-readable JSON' }],
+    handler: doctor,
+  },
+  {
+    name: 'test',
+    group: 'QUALITY',
+    summary: 'Run tests (integration | bet <slug>)',
+    nouns: ['integration', 'bet'],
+    flags: [
+      { name: '--integration', desc: 'Boot the stack for a bet suite' },
+      { name: '--keep', desc: 'Leave the stack running after tests' },
+    ],
+    handler: quality.test,
+  },
+  {
+    name: 'lint',
+    group: 'QUALITY',
+    summary: 'Run static analysis across services',
+    handler: quality.lint,
+  },
+  {
+    name: 'new',
+    group: 'BET WORKFLOW',
+    summary: 'Scaffold a bet / milestone / slice (red test stubs)',
+    nouns: ['bet', 'milestone', 'slice'],
+    handler: bet.newCmd,
+  },
+  {
+    name: 'archive',
+    group: 'BET WORKFLOW',
+    summary: "Archive a delivered bet's progress suite",
+    nouns: ['bet'],
+    handler: bet.archive,
+  },
+  {
+    name: 'bet',
+    group: 'BET WORKFLOW',
+    summary: 'Bet progress board (status [<slug>])',
+    nouns: ['status'],
+    flags: [{ name: '--json', desc: 'Emit machine-readable JSON (status)' }],
+    handler: bet.betCmd,
+  },
+  {
+    name: 'surface',
+    group: 'BET WORKFLOW',
+    summary: 'Surface registry & capability ledger (status)',
+    nouns: ['status'],
+    flags: [{ name: '--json', desc: 'Emit machine-readable JSON (status)' }],
+    handler: surfaceCmd,
+  },
+  {
+    name: 'completion',
+    group: 'META',
+    summary: 'Print a shell completion script (bash|zsh|fish)',
+    nouns: ['bash', 'zsh', 'fish'],
+    handler: completion,
+  },
+];
+
+export function findCommand(list: CommandDef[], name: string): CommandDef | undefined {
+  return list.find((c) => c.name === name);
+}
+
+/** Single-quote an argument for safe interpolation into a `bash -c` string. */
+function shellQuote(arg: string): string {
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Wrap a project command as a CommandDef whose handler runs it as a subprocess,
+ *  appending any extra args the user passed after the verb. Running as a subprocess
+ *  keeps the bundle zero-dependency — the project's command can pull in whatever it
+ *  needs without the core CLI knowing. */
+export function projectCommandDef(pc: ProjectCommand): CommandDef {
+  return {
+    name: pc.name,
+    group: pc.group || 'PROJECT',
+    summary: pc.summary,
+    handler: async (ctx: Ctx) => {
+      const cwd = pc.cwd ? path.join(ROOT, pc.cwd) : ROOT;
+      const env = pc.env ? { ...process.env, ...pc.env } : process.env;
+      const extra = ctx.args.map(shellQuote).join(' ');
+      const command = extra ? `${pc.run} ${extra}` : pc.run;
+      return run('bash', ['-c', command], { cwd, env });
+    },
+  };
+}
+
+/** Merge the built-in registry with the project's own commands. A project command
+ *  shadows a built-in of the same name — project wins — so a project can redefine a
+ *  verb (e.g. `start`) for a stack the default lifecycle does not fit, without editing
+ *  the bundle. The merged list is the single source of truth for dispatch, `--help`,
+ *  and completion, exactly as COMMANDS is for the built-ins alone. */
+export function buildRegistry(project: ProjectCommand[]): CommandDef[] {
+  const projDefs = project.map(projectCommandDef);
+  const shadowed = new Set(projDefs.map((d) => d.name));
+  const core = COMMANDS.filter((c) => !shadowed.has(c.name));
+  return [...core, ...projDefs];
+}

package/src/generators/workspace-dev-cli/cli-src/src/theme/color.ts

@@ -0,0 +1,130 @@
+/**
+ * Colour resolution: truecolor → ANSI 256 → bold/dim → plain, gated by terminal
+ * capability and the NO_COLOR / FORCE_COLOR standards. The render layer asks for a
+ * semantic role; this module decides how to paint it given the environment.
+ */
+
+import { BrandTokens, ColorRole, NoColorTreatment, RoleName } from './tokens';
+
+const RESET = '\x1b[0m';
+
+export type ColorDepth = 'none' | 'ansi16' | 'ansi256' | 'truecolor';
+
+export interface RenderCaps {
+  depth: ColorDepth;
+  unicode: boolean;
+  isTTY: boolean;
+}
+
+function envFlag(name: string): boolean {
+  const v = process.env[name];
+  return v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+}
+
+/** Detect the renderable capabilities of the current stdout. Honors NO_COLOR
+ *  (https://no-color.org) and FORCE_COLOR; detects truecolor via $COLORTERM. */
+export function detectCaps(stream: NodeJS.WriteStream = process.stdout): RenderCaps {
+  const isTTY = Boolean(stream.isTTY);
+  // Unicode: assume yes on UTF-8 locales / modern terminals; fall back to ASCII for
+  // dumb terminals or explicit opt-out.
+  const term = process.env.TERM ?? '';
+  const unicode =
+    term !== 'dumb' &&
+    !envFlag('ASCII_ONLY') &&
+    /utf-?8/i.test(process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG || 'UTF-8');
+
+  let depth: ColorDepth;
+  if (envFlag('NO_COLOR')) {
+    depth = 'none';
+  } else if (!isTTY && !envFlag('FORCE_COLOR')) {
+    depth = 'none';
+  } else {
+    const colorterm = (process.env.COLORTERM ?? '').toLowerCase();
+    if (colorterm === 'truecolor' || colorterm === '24bit') {
+      depth = 'truecolor';
+    } else if (/256/.test(term)) {
+      depth = 'ansi256';
+    } else if (term === 'dumb' || term === '') {
+      depth = 'none';
+    } else {
+      depth = 'ansi16';
+    }
+  }
+  return { depth, unicode, isTTY };
+}
+
+function hexToRgb(hex: string): [number, number, number] {
+  const m = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex.trim());
+  if (!m) return [255, 255, 255];
+  return [parseInt(m[1], 16), parseInt(m[2], 16), parseInt(m[3], 16)];
+}
+
+function treatmentCode(t: NoColorTreatment): string {
+  switch (t) {
+    case 'bold':
+    case 'bold+upper':
+      return '\x1b[1m';
+    case 'dim':
+      return '\x1b[2m';
+    case 'underline':
+      return '\x1b[4m';
+    default:
+      return '';
+  }
+}
+
+/** A bound painter: closes over the resolved tokens and capabilities so callers
+ *  just name a role. */
+export class Painter {
+  constructor(
+    public readonly tokens: BrandTokens,
+    public readonly caps: RenderCaps,
+  ) {}
+
+  private roleColor(role: RoleName): ColorRole | undefined {
+    return this.tokens.terminal?.colorRoles?.[role];
+  }
+
+  /** Paint text in a semantic role, degrading by capability. */
+  paint(role: RoleName, text: string): string {
+    const r = this.roleColor(role);
+    if (!r) return text;
+    if (r.noColor === 'bold+upper') text = text.toUpperCase();
+
+    if (this.caps.depth === 'none') {
+      const code = treatmentCode(r.noColor);
+      return code ? `${code}${text}${RESET}` : text;
+    }
+    if (this.caps.depth === 'truecolor' && r.truecolor) {
+      const [rr, gg, bb] = hexToRgb(r.truecolor);
+      return `\x1b[38;2;${rr};${gg};${bb}m${text}${RESET}`;
+    }
+    if (
+      (this.caps.depth === 'ansi256' || this.caps.depth === 'truecolor') &&
+      r.ansi256 !== null
+    ) {
+      return `\x1b[38;5;${r.ansi256}m${text}${RESET}`;
+    }
+    // ansi16 or missing colour value → degrade to the bold/dim treatment.
+    const code = treatmentCode(r.noColor);
+    return code ? `${code}${text}${RESET}` : text;
+  }
+
+  /** Paint with the brand primary accent (truecolor only; degrades to bold). */
+  primary(text: string): string {
+    if (this.caps.depth === 'truecolor') {
+      const [r, g, b] = hexToRgb(this.tokens.identity.primary);
+      return `\x1b[38;2;${r};${g};${b}m${text}${RESET}`;
+    }
+    if (this.caps.depth === 'none') return text;
+    return `\x1b[1m${text}${RESET}`;
+  }
+
+  bold(text: string): string {
+    return this.caps.depth === 'none' ? text : `\x1b[1m${text}${RESET}`;
+  }
+
+  dim(text: string): string {
+    return this.caps.depth === 'none' ? text : `\x1b[2m${text}${RESET}`;
+  }
+}