@raidiant/notifai 10.1.1 → 10.1.3

package/src/ui/banner.ts

@@ -1,95 +0,0 @@
-/**
- * The wordmark shown when a human opens the interactive app.
- *
- * Three tiers, chosen by what the terminal can actually render rather than by
- * what looks best in a screenshot: box-drawing blocks when the terminal is wide
- * and Unicode-capable, a pure-ASCII form that survives anywhere, and a plain
- * word when neither fits. A banner that wraps is worse than no banner, so the
- * width check is not optional.
- *
- * The art is embedded rather than rendered at run time. It is one fixed word
- * that will never change, and shipping a font engine to redraw a constant on
- * every launch would cost every install — including the agents that never see
- * it — for no benefit.
- */
-import { gradientBlock, style, terminalWidth, unicode } from './theme.js'
-
-/** ANSI Shadow. 50 columns, 6 rows. */
-const BLOCK = [
-  '███╗   ██╗ ██████╗ ████████╗██╗███████╗ █████╗ ██╗',
-  '████╗  ██║██╔═══██╗╚══██╔══╝██║██╔════╝██╔══██╗██║',
-  '██╔██╗ ██║██║   ██║   ██║   ██║█████╗  ███████║██║',
-  '██║╚██╗██║██║   ██║   ██║   ██║██╔══╝  ██╔══██║██║',
-  '██║ ╚████║╚██████╔╝   ██║   ██║██║     ██║  ██║██║',
-  '╚═╝  ╚═══╝ ╚═════╝    ╚═╝   ╚═╝╚═╝     ╚═╝  ╚═╝╚═╝',
-]
-
-/** Pure ASCII. 34 columns, 4 rows — safe on any terminal, any code page. */
-const ASCII = [
-  '  _  _  ___ _____ ___ ___ _   ___ ',
-  ' | \\| |/ _ \\_   _|_ _| __/_\\ |_ _|',
-  ' | .` | (_) || |  | || _/ _ \\ | | ',
-  ' |_|\\_|\\___/ |_| |___|_/_/ \\_\\___|',
-]
-
-export type BannerSize = 'block' | 'ascii' | 'word'
-
-export function bannerSize(columns = terminalWidth()): BannerSize {
-  if (unicode && columns >= 54) return 'block'
-  if (columns >= 38) return 'ascii'
-  return 'word'
-}
-
-/** The wordmark as rendered lines, gradient included. */
-export function bannerLines(columns = terminalWidth()): string[] {
-  switch (bannerSize(columns)) {
-    case 'block':
-      return gradientBlock(BLOCK)
-    case 'ascii':
-      return gradientBlock(ASCII)
-    case 'word':
-      return gradientBlock(['N O T I F A I'])
-  }
-}
-
-/**
- * Reveal the wordmark one row at a time.
- *
- * Deliberately brief and deliberately skippable: this runs before someone can
- * do anything, so it may not become a wait. It is skipped entirely when output
- * is not a TTY, when `NOTIFAI_NO_ANIMATION` is set, and under `CI`.
- */
-export async function printBanner(
-  options: { animate?: boolean; env?: NodeJS.ProcessEnv; write?: (line: string) => void } = {},
-): Promise<void> {
-  const env = options.env ?? process.env
-  const write = options.write ?? ((line: string) => process.stdout.write(`${line}\n`))
-  const lines = bannerLines()
-  const animate =
-    options.animate !== false &&
-    process.stdout.isTTY === true &&
-    (env['NOTIFAI_NO_ANIMATION'] ?? '') === '' &&
-    (env['CI'] ?? '') === ''
-
-  write('')
-  for (const line of lines) {
-    // Two columns, matching the tagline and the status card beneath it. Flush
-    // left, the wordmark reads as a separate thing sitting above the app.
-    write(`  ${line}`)
-    if (animate) await new Promise((resolve) => setTimeout(resolve, 26))
-  }
-  write('')
-}
-
-/**
- * One line of orientation under the wordmark — and it must stay one line.
- * Wrapped onto two it stops reading as a subtitle and starts reading as the
- * first paragraph of something, so a narrow terminal gets the version alone.
- */
-export function tagline(version: string, columns = terminalWidth()): string {
-  const full = 'Native notifications for agents and local programs'
-  // Two leading columns of indent, two trailing for the version.
-  return columns >= full.length + 12
-    ? `${style.dim(full)}  ${style.dim(`v${version}`)}`
-    : style.dim(`v${version}`)
-}

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

@@ -1,90 +0,0 @@
-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(`wait_seconds = ${JSON.stringify(config.wait_seconds.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(
-      `wait_seconds = ${JSON.stringify(config.wait_seconds.value)}  [${config.wait_seconds.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')
-    expect(text).toContain('notifai config explain')
-  })
-
-  it('reveals advanced keys only when asked', () => {
-    expect(renderConfigList(config).join('\n')).not.toContain('collapse_key')
-    expect(renderConfigList(config, { showAdvanced: true }).join('\n')).toContain('collapse_key')
-    expect(renderConfigList(config, { showAdvanced: true }).join('\n')).not.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('ask_notifications', config).join('\n')
-    expect(text).toContain('ask_notifications')
-    expect(text).toContain('Send questions to my devices')
-    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 ask_notifications')
-  })
-
-  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')
-    expect(text).toContain('Device default')
-  })
-})

package/src/ui/config-view.ts

@@ -1,138 +0,0 @@
-/**
- * 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('')
-  const command = 'notifai config explain <key>'
-  const help = `${glyph.arrow} ${command} for what one of these means and how to change it.`
-  for (const line of wrap(help, columns)) {
-    lines.push(style.dim(line.replace(command, style.code(command))))
-  }
-  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.test.ts

@@ -1,16 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { rootHelpFooter } from './help.js'
-
-function stripAnsi(text: string): string {
-  return text.replace(/\u001B\[[0-9;]*m/g, '')
-}
-
-describe('rootHelpFooter', () => {
-  it('leads first-run with init, not the interactive app', () => {
-    const footer = stripAnsi(rootHelpFooter())
-    const start = footer.slice(footer.indexOf('Start here'))
-    const firstCommand = start.match(/notifai(?: init)?/)?.[0]
-    expect(firstCommand).toBe('notifai init')
-    expect(start.indexOf('notifai init')).toBeLessThan(start.search(/notifai\s{2,}/))
-  })
-})

package/src/ui/help.ts

@@ -1,128 +0,0 @@
-/**
- * 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 one a new
- * user needs (`init`) 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:',
-} 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,
-]
-
-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.
- *
- * First-run is `notifai init`. The interactive app is what a human opens
- * later, once setup is no longer the thing in the way.
- */
-export function rootHelpFooter(): string {
-  const lines = [
-    '',
-    style.heading('Start here'),
-    `  ${style.code('notifai init')}         ${style.dim(`${glyph.arrow} set this project up, step by step`)}`,
-    `  ${style.code('notifai')}              ${style.dim(
-      `${glyph.arrow} after setup: status, settings, devices, test sends`,
-    )}`,
-    '',
-    style.heading('First call, for an agent'),
-    `  ${style.code('notifai send --kind done --title "All 42 tests passed" --body "Finished in 3m 10s. Next: review the release candidate."')}`,
-    `  ${style.code('notifai ask "Deploy migration 0007 to production?" --choice Deploy --choice Hold')}`,
-    `  ${style.dim(`${glyph.arrow} ${style.code('ask')} needs question routing installed; ${style.code('notifai doctor --json')} says whether it is.`)}`,
-    '',
-    style.dim(
-      `Every command takes ${style.code('--help')}. Where a command has machine-readable output it takes ${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

@@ -1,92 +0,0 @@
-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)
-  })
-})