@raidiant/notifai 0.2.1 → 0.4.0

package/src/ui/config-view.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import os from 'node:os'
+import path from 'node:path'
+import { CONFIG_KEYS, loadConfig } from '../config.js'
+import { configInfo } from '../config-schema.js'
+import { renderConfigExplain, renderConfigList, renderConfigPlain } from './config-view.js'
+import { width } from './theme.js'
+
+const config = loadConfig({
+  cwd: os.tmpdir(),
+  env: { XDG_CONFIG_HOME: path.join(os.tmpdir(), 'notifai-config-view-tests') },
+})
+
+describe('renderConfigPlain', () => {
+  it('is the flat form scripts already parse', () => {
+    // This is the agent-facing shape and the reason the pretty renderer is
+    // gated on a human terminal. Restyling it would be a breaking change for
+    // an audience that cannot see the styling.
+    const lines = renderConfigPlain(config, false)
+    expect(lines).toHaveLength(CONFIG_KEYS.length)
+    expect(lines[0]).toBe(`base_url = ${JSON.stringify(config.base_url.value)}`)
+    for (const line of lines) expect(line).toMatch(/^[a-z_]+ = /)
+  })
+
+  it('appends the raw source tag under --explain', () => {
+    const lines = renderConfigPlain(config, true)
+    expect(lines[0]).toBe(
+      `base_url = ${JSON.stringify(config.base_url.value)}  [${config.base_url.source}]`,
+    )
+  })
+
+  it('carries no colour, so a pipe gets no escape bytes', () => {
+    for (const line of renderConfigPlain(config, true)) {
+      expect(line).toBe(line.replace(/\[[0-9;]*m/g, ''))
+    }
+  })
+})
+
+describe('renderConfigList', () => {
+  it('names every non-advanced key and explains it', () => {
+    const text = renderConfigList(config).join('\n')
+    for (const key of CONFIG_KEYS) {
+      // Derived, not listed: a hardcoded set of advanced keys silently becomes
+      // an assertion about yesterday's key list the moment a key is added.
+      if (configInfo(key).advanced === true) continue
+      expect(text, key).toContain(key)
+    }
+    expect(text).toContain('Questions & presence')
+    expect(text).toContain('notifai config explain')
+  })
+
+  it('reveals advanced keys only when asked', () => {
+    expect(renderConfigList(config).join('\n')).not.toContain('base_url')
+    expect(renderConfigList(config, { showAdvanced: true }).join('\n')).toContain('base_url')
+  })
+
+  it('fits the terminal, so no row wraps into the next', () => {
+    const columns = process.stdout.columns
+    Object.defineProperty(process.stdout, 'columns', { value: 80, configurable: true })
+    try {
+      for (const line of renderConfigList(config, { showAdvanced: true })) {
+        expect(width(line), line).toBeLessThanOrEqual(80)
+      }
+    } finally {
+      Object.defineProperty(process.stdout, 'columns', { value: columns, configurable: true })
+    }
+  })
+})
+
+describe('renderConfigExplain', () => {
+  it('answers what it is, what it is now, and what it accepts', () => {
+    const text = renderConfigExplain('require_idle', config).join('\n')
+    expect(text).toContain('require_idle')
+    expect(text).toContain('Only when I have stepped away')
+    expect(text).toContain('Accepts')
+    expect(text).toContain('true or false')
+    // The copyable next step; the old output stopped at the value.
+    expect(text).toContain('notifai config set require_idle')
+  })
+
+  it('lists what each choice of an enum means', () => {
+    const text = renderConfigExplain('sound', config).join('\n')
+    for (const choice of ['default', 'done', 'attention', 'alert', 'none']) {
+      expect(text, choice).toContain(choice)
+    }
+    expect(text).toContain('the completion chime')
+  })
+})

package/src/ui/config-view.ts

@@ -0,0 +1,138 @@
+/**
+ * Rendering for the configuration surfaces a person reads.
+ *
+ * The agent-facing shapes are untouched and live elsewhere: `--json` is the
+ * contract, and the flat `key = value` form stays exactly as it was for
+ * anything that is not a terminal. What is new is only what a human sees.
+ */
+import { CONFIG_KEYS, type CliConfig, type ConfigKey } from '../config.js'
+import {
+  CONFIG_GROUPS,
+  acceptedValues,
+  configInfo,
+  configKeysByGroup,
+  describeSource,
+  formatValue,
+} from '../config-schema.js'
+import { glyph, pad, style, terminalWidth, width, wrap } from './theme.js'
+
+/**
+ * The full settings listing, grouped and explained.
+ *
+ * Each key gets its name (what you type), its value (what is in force), where
+ * that value came from, and one line on what it does. The name leads rather
+ * than the friendly label because the next thing a reader does with it is type
+ * it into `config set`.
+ */
+export function renderConfigList(
+  config: CliConfig,
+  options: { showAdvanced?: boolean } = {},
+): string[] {
+  const columns = terminalWidth()
+  const lines: string[] = []
+  const nameWidth = Math.max(...CONFIG_KEYS.map((key) => key.length))
+  const SUMMARY_INDENT = '      '
+
+  for (const group of CONFIG_GROUPS) {
+    const keys = configKeysByGroup(group.id).filter(
+      (info) => options.showAdvanced === true || info.advanced !== true,
+    )
+    if (keys.length === 0) continue
+
+    lines.push('')
+    lines.push(style.heading(group.title))
+    for (const line of wrap(group.blurb, columns - 2)) lines.push(style.dim(`  ${line}`))
+    lines.push('')
+
+    for (const info of keys) {
+      const entry = config[info.key]
+      const source = describeSource(entry.source)
+      const value = formatValue(info.key, entry.value)
+      const isSet = source.label !== 'default'
+      // The provenance mark is only drawn when there is provenance to show;
+      // an empty dim segment still emits escape codes, so a `trimEnd` on the
+      // finished string cannot remove it.
+      const provenance = isSet ? `  ${style.dim(`${glyph.bullet} ${source.label}`)}` : ''
+      lines.push(
+        `  ${style.code(pad(info.key, nameWidth))}  ` +
+          `${isSet ? style.value(value) : style.unset(value)}${provenance}`,
+      )
+      for (const line of wrap(info.summary, columns - SUMMARY_INDENT.length)) {
+        lines.push(style.dim(`${SUMMARY_INDENT}${line}`))
+      }
+    }
+  }
+
+  lines.push('')
+  lines.push(
+    style.dim(
+      `${glyph.arrow} ${style.code('notifai config explain <key>')} for what one of these means and how to change it.`,
+    ),
+  )
+  return lines
+}
+
+/**
+ * Everything about one key, for someone who has asked about it specifically.
+ *
+ * This is the payoff of the listing above staying terse: the reader arrives
+ * here already knowing which key they care about, so the full paragraph, the
+ * legal values, and the layer the current value came from can all be spent on
+ * that one key.
+ */
+export function renderConfigExplain(key: ConfigKey, config: CliConfig): string[] {
+  const info = configInfo(key)
+  const entry = config[key]
+  const source = describeSource(entry.source)
+  const columns = terminalWidth()
+  const lines: string[] = []
+
+  lines.push('')
+  lines.push(`${style.code(key)}  ${style.dim(glyph.bullet)}  ${style.heading(info.label)}`)
+  lines.push('')
+
+  for (const paragraph of info.detail.split('\n\n')) {
+    for (const line of wrap(paragraph, columns - 2)) lines.push(`  ${line}`)
+    lines.push('')
+  }
+
+  const valueLabel = formatValue(key, entry.value)
+  lines.push(
+    `  ${style.dim(pad('Now', 10))}${style.value(valueLabel)}  ${style.dim(`${glyph.bullet} ${source.label}`)}`,
+  )
+  if (source.path !== null) lines.push(`  ${style.dim(pad('', 10))}${style.dim(source.path)}`)
+  lines.push(`  ${style.dim(pad('Accepts', 10))}${acceptedValues(key)}`)
+
+  if (info.choices !== undefined && info.choiceHints !== undefined) {
+    lines.push('')
+    for (const choice of info.choices) {
+      const hint = info.choiceHints[choice]
+      lines.push(
+        `  ${style.dim(pad('', 10))}${style.code(pad(choice, 14))}${style.dim(hint ?? '')}`.trimEnd(),
+      )
+    }
+  }
+
+  lines.push('')
+  const example = info.example ?? (info.choices?.[0] ?? 'value')
+  lines.push(`  ${style.dim('Change it')} ${style.code(`notifai config set ${key} ${example}`)}`)
+  if (entry.source !== 'default' && entry.source !== 'flag') {
+    lines.push(`  ${style.dim('Inherit it')} ${style.code(`notifai config unset ${key}`)}`)
+  }
+  lines.push('')
+  return lines
+}
+
+/** The flat form, unchanged, for anything that is not a person at a terminal. */
+export function renderConfigPlain(config: CliConfig, explain: boolean): string[] {
+  return CONFIG_KEYS.map((key) => {
+    const entry = config[key]
+    const provenance = explain ? `  [${entry.source}]` : ''
+    return `${key} = ${JSON.stringify(entry.value)}${provenance}`
+  })
+}
+
+/** Longest visible line, for callers that need to size a rule or a box. */
+export function widestLine(lines: readonly string[]): number {
+  return Math.max(0, ...lines.map((line) => width(line)))
+}

package/src/ui/help.ts

@@ -0,0 +1,124 @@
+/**
+ * Help that answers "what can I do here", not "what strings does argv accept".
+ *
+ * The old help listed seventeen commands in one flat column, with the two a new
+ * user needs (`init`, `login`) sitting between a platform capability dump and
+ * an entry point marked "Internal:". Everything was equally prominent, which is
+ * the same as nothing being prominent.
+ *
+ * Grouping and colour are Commander's own (`commandsGroup`, `optionsGroup`, and
+ * the `styleX` hooks it calls when the output has colours); this module only
+ * supplies the palette and the group vocabulary. Commander turns its styling
+ * off by itself when the output is not a terminal, so piped help stays plain
+ * without a second code path.
+ */
+import { Help, type Command, type HelpConfiguration, type Option } from 'commander'
+import { glyph, style } from './theme.js'
+
+/**
+ * Group headings, in the order a reader meets them.
+ *
+ * Ordering is by who needs it and when: first run, then daily use, then the
+ * commands agents drive, then the things touched once or never. Commander
+ * renders groups in first-use order, so these constants are also the layout.
+ */
+export const GROUP = {
+  start: 'Getting started:',
+  daily: 'Everyday:',
+  agent: 'For agents and scripts:',
+  advanced: 'Account and wiring:',
+  help: 'Help:',
+} as const
+
+/** Option groups for `send`, which carries thirty flags. */
+export const SEND_GROUP = {
+  content: 'What it says:',
+  routing: 'Where it goes:',
+  presentation: 'How it arrives:',
+  reply: 'Asking for an answer:',
+  advanced: 'Advanced:',
+} as const
+
+/** Group order, independent of the order commands happen to be registered in. */
+const GROUP_ORDER: readonly string[] = [
+  GROUP.start,
+  GROUP.daily,
+  GROUP.agent,
+  GROUP.advanced,
+  GROUP.help,
+]
+
+function groupRank(heading: string): number {
+  const index = GROUP_ORDER.indexOf(heading)
+  // Anything not named above keeps its position relative to its peers, because
+  // the sort is stable — which is what lets the same override run over option
+  // groups without needing to know their headings.
+  return index === -1 ? GROUP_ORDER.length : index
+}
+
+export const helpConfiguration: HelpConfiguration = {
+  // Groups already carry the intended order; alphabetising would scatter the
+  // dependency between `login` and everything that needs a credential.
+  sortSubcommands: false,
+  sortOptions: false,
+  showGlobalOptions: false,
+
+  /**
+   * Commander seeds group order from the raw registration order, which ties
+   * how the help reads to where a `program.command(…)` block happens to sit in
+   * the file — move one and the help silently reorders. Sorting the finished
+   * grouping makes `GROUP_ORDER` the single place that decision is made.
+   *
+   * The same override runs over option groups, whose headings are not in
+   * `GROUP_ORDER` at all. They all rank equal, and `sort` is stable, so they
+   * keep the order they were declared in.
+   */
+  groupItems<T extends Command | Option>(
+    this: Help,
+    unsortedItems: T[],
+    visibleItems: T[],
+    getGroup: (item: T) => string,
+  ): Map<string, T[]> {
+    // `.call` cannot carry the method's own generic through, so the signature
+    // is restated once here instead of widening every caller to
+    // `Command | Option`.
+    const base = Help.prototype.groupItems as unknown as (
+      this: Help,
+      unsorted: T[],
+      visible: T[],
+      group: (item: T) => string,
+    ) => Map<string, T[]>
+    const grouped = base.call(this, unsortedItems, visibleItems, getGroup)
+    return new Map([...grouped.entries()].sort((a, b) => groupRank(a[0]) - groupRank(b[0])))
+  },
+
+  styleTitle: (title: string): string => style.heading(title),
+  styleCommandText: (text: string): string => style.accent(text),
+  styleSubcommandTerm: (text: string): string => style.code(text),
+  styleOptionTerm: (text: string): string => style.code(text),
+  styleArgumentTerm: (text: string): string => style.code(text),
+  styleDescriptionText: (text: string): string => text,
+  styleUsage: (text: string): string => text,
+}
+
+/**
+ * Footer for the root help.
+ *
+ * Its whole job is to make the interactive app discoverable, because someone
+ * reading a wall of flags has already demonstrated they did not know it was
+ * there.
+ */
+export function rootHelpFooter(): string {
+  const lines = [
+    '',
+    style.heading('Start here'),
+    `  ${style.code('notifai')}              ${style.dim(
+      `${glyph.arrow} the interactive app: status, settings, devices, test sends`,
+    )}`,
+    `  ${style.code('notifai init')}         ${style.dim(`${glyph.arrow} set this project up, step by step`)}`,
+    '',
+    style.dim(`Every command takes ${style.code('--help')}. Machine-readable output: ${style.code('--json')}.`),
+    style.dim(`Settings are explained by ${style.code('notifai config show')} and ${style.code('notifai config explain <key>')}.`),
+  ]
+  return lines.join('\n')
+}

package/src/ui/theme.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest'
+import { card, clip, pad, width, wrap } from './theme.js'
+
+/**
+ * These run with colour off — vitest's stdout is not a TTY, so `picocolors`
+ * resolves to identity functions. That is the interesting case: it is the one
+ * every agent, pipe and CI log gets, and the one where a layout bug is
+ * invisible to a human developer reading a colourful terminal.
+ */
+
+const RED = ''
+const RESET = ''
+
+describe('width', () => {
+  it('counts printable characters, not escape bytes', () => {
+    expect(width('hello')).toBe(5)
+    expect(width(`${RED}hello${RESET}`)).toBe(5)
+  })
+})
+
+describe('pad', () => {
+  it('pads by visible width so colour cannot break a column', () => {
+    expect(width(pad(`${RED}ab${RESET}`, 6))).toBe(6)
+    expect(pad('ab', 4)).toBe('ab  ')
+  })
+
+  it('never truncates when the text already exceeds the column', () => {
+    expect(pad('abcdef', 3)).toBe('abcdef')
+  })
+})
+
+describe('wrap', () => {
+  it('breaks on whitespace within the limit', () => {
+    expect(wrap('one two three four', 9)).toEqual(['one two', 'three', 'four'])
+  })
+
+  it('returns bare lines, leaving indentation to the caller', () => {
+    // The regression this guards: wrap used to indent continuation lines
+    // itself while callers indented every line, so each wrapped paragraph
+    // stepped further right down the page.
+    for (const line of wrap('alpha beta gamma delta', 11)) {
+      expect(line.startsWith(' ')).toBe(false)
+    }
+  })
+
+  it('keeps a word that is longer than the limit rather than losing it', () => {
+    expect(wrap('supercalifragilistic', 5)).toEqual(['supercalifragilistic'])
+  })
+})
+
+describe('clip', () => {
+  it('leaves text that already fits', () => {
+    expect(clip('short', 10)).toBe('short')
+  })
+
+  it('truncates by visible width and never mid-escape', () => {
+    const clipped = clip(`${RED}abcdefghij${RESET}`, 5)
+    expect(width(clipped)).toBeLessThanOrEqual(5)
+    // A slice by String.length would cut through `` and spill the
+    // raw bytes into the terminal.
+    expect(clipped).toContain(RED)
+    expect(clipped.endsWith(RESET)).toBe(true)
+  })
+})
+
+describe('card', () => {
+  it('draws a closed box whose rows all share one width', () => {
+    const lines = card('Status', ['a', 'bbbbbbbbbb'], 40)
+    const widths = new Set(lines.map((line) => width(line)))
+    expect(widths.size).toBe(1)
+    expect(lines[0]).toContain('Status')
+  })
+
+  it('measures rows by visible width, so colour does not skew the border', () => {
+    const plain = card('T', ['abcdef'], 40)
+    const coloured = card('T', [`${RED}abcdef${RESET}`], 40)
+    expect(plain.map(width)).toEqual(coloured.map(width))
+  })
+
+  it('survives a terminal that reports no usable width', () => {
+    // A pty reporting zero columns made the obvious library call compute a
+    // negative pad and throw, taking the whole interactive app with it. A
+    // status card may degrade; it must never be the thing that crashes.
+    expect(() => card('Status', ['something reasonably long here'], 0)).not.toThrow()
+    expect(card('Status', ['x'], 0).length).toBe(3)
+  })
+
+  it('clips a row too wide for the terminal instead of wrapping it', () => {
+    const lines = card('T', ['x'.repeat(200)], 40)
+    for (const line of lines) expect(width(line)).toBeLessThanOrEqual(40)
+  })
+})