@erclx/aitk 1.2.0 → 1.4.0

package/src/ui.ts

@@ -1,11 +1,60 @@
-const GREEN = '\x1b[0;32m'
-const RED = '\x1b[0;31m'
-const YELLOW = '\x1b[0;33m'
-const WHITE = '\x1b[1;37m'
-const GREY = '\x1b[0;90m'
-const NC = '\x1b[0m'
+export interface Palette {
+  readonly GREEN: string
+  readonly RED: string
+  readonly YELLOW: string
+  readonly WHITE: string
+  readonly GREY: string
+  readonly NC: string
+}
+
+const COLOR: Palette = {
+  GREEN: '\x1b[0;32m',
+  RED: '\x1b[0;31m',
+  YELLOW: '\x1b[0;33m',
+  WHITE: '\x1b[1;37m',
+  GREY: '\x1b[0;90m',
+  NC: '\x1b[0m',
+}
+
+/**
+ * The blank palette keeps every frame character and drops only the escapes, so
+ * a captured run still reads as one block.
+ */
+const PLAIN: Palette = {
+  GREEN: '',
+  RED: '',
+  YELLOW: '',
+  WHITE: '',
+  GREY: '',
+  NC: '',
+}
+
+/**
+ * `NO_COLOR` follows the published convention, where any non-empty value turns
+ * color off whatever the value says.
+ */
+export function supportsColor(stream: { isTTY?: boolean }): boolean {
+  const optOut = process.env.NO_COLOR
+  if (optOut !== undefined && optOut !== '') return false
+  return stream.isTTY === true
+}
+
+/**
+ * The question is asked per stream rather than once for the process. The framed
+ * output goes to stderr and a structured record to stdout, so a run piping only
+ * its data keeps a terminal on stderr and keeps its color there. This is a
+ * third question again from `isNonInteractive`, which answers whether a caller
+ * can be prompted rather than whether a destination renders escapes.
+ *
+ * Read at write time rather than at import, so nothing freezes an answer taken
+ * before the caller's environment was in place.
+ */
+export function palette(stream: { isTTY?: boolean }): Palette {
+  return supportsColor(stream) ? COLOR : PLAIN
+}
 
 export function intro(title: string): void {
+  const { GREY, NC, WHITE } = palette(process.stderr)
   process.stderr.write(`${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}${title}${NC}\n`)
 }
 
@@ -15,18 +64,22 @@ export function intro(title: string): void {
  * leaving stdout clean for JSON and lists.
  */
 export function logInfo(message: string): void {
+  const { GREEN, GREY, NC } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC} ${GREEN}✓${NC} ${message}\n`)
 }
 
 export function logWarn(message: string): void {
+  const { GREY, NC, YELLOW } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC} ${YELLOW}!${NC} ${message}\n`)
 }
 
 export function logAdd(message: string): void {
+  const { GREEN, GREY, NC } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC} ${GREEN}+${NC} ${message}\n`)
 }
 
 export function logRemove(message: string): void {
+  const { GREY, NC, RED } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC} ${RED}-${NC} ${message}\n`)
 }
 
@@ -36,14 +89,17 @@ export function logRemove(message: string): void {
  * exit code rather than terminating mid-write.
  */
 export function logError(message: string): void {
+  const { GREY, NC, RED } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC} ${RED}✗${NC} ${message}\n`)
 }
 
 export function logStep(message: string): void {
+  const { GREY, NC, WHITE } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC}\n${GREY}├${NC} ${WHITE}${message}${NC}\n`)
 }
 
 export function outro(): void {
+  const { GREY, NC } = palette(process.stderr)
   process.stderr.write(`${GREY}└${NC}\n`)
 }
 
@@ -53,6 +109,7 @@ export function outro(): void {
  * such as a pull request body or the output of a git mutation.
  */
 export function pipeOutput(text: string): void {
+  const { GREY, NC } = palette(process.stderr)
   const lines = text.replace(/\n$/, '').split('\n')
   process.stderr.write(
     `${lines.map((line) => `${GREY}│${NC}  ${line}`).join('\n')}\n`,
@@ -65,12 +122,14 @@ export function plural(count: number, noun: string): string {
 }
 
 export function frameError(message: string): void {
+  const { GREY, NC, RED } = palette(process.stderr)
   process.stderr.write(
     `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${message}\n${GREY}└${NC}\n`,
   )
 }
 
 export function frameSuccess(command: string, target: string): void {
+  const { GREEN, GREY, NC, WHITE } = palette(process.stderr)
   process.stderr.write(
     `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}${command}${NC}\n${GREY}│${NC}\n${GREY}│${NC} ${GREEN}✓${NC} ${target}\n${GREY}└${NC}\n`,
   )
@@ -92,6 +151,7 @@ export async function select<Value>(opts: {
   nonInteractiveDefault?: boolean
 }): Promise<Value> {
   const { message, options } = opts
+  const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
   const count = options.length
   let cursor = 0
 

package/standards/design.md

@@ -34,6 +34,16 @@ Does not govern:
 - Plain English over technical notation. If a section could be removed and the developer would still build correctly from wireframes and code alone, remove it.
 - Keep table headers and role names intact so the render tooling can parse the token tables.
 
+## The uncertainty tag
+
+A cell no source anchors ends in ` ? verify`, written inside the cell rather than as a trailing column, since a trailing marker breaks the table parse. A cell wrapping itself in a code span carries the tag inside the span, as in `` `#ffffff ? verify` ``. Both spellings parse.
+
+The renderer splits the tag off the value, so a swatch and a font sample are built from the value alone and the marker shows beside it. The preview also reports how many cells are anchored against how many are tagged, which is the reading a reviewer takes the record's overall confidence from.
+
+Which columns that ratio reads is fixed by the table rather than by the record. The first column of each table names its row, and `Multiplier` and `When used` restate what the row already carries, so none of them is something a source could anchor and none is counted. That leaves `Intent` and `Value` in Color, `Family`, `Weight`, `Size`, and `Line height` in Typography, `Value` in Spacing, and `Radius` and `Width` in Borders. A cell tagged outside that set counts anyway, so a marker the preview draws is never missing from the ratio beside it.
+
+A prose section takes its uncertainty inline instead, in a sentence saying what is proposed and what has yet to confirm it. A tag appended to a paragraph renders verbatim.
+
 ## Sections
 
 Use `## Personality`, `## Color`, `## Typography`, `## Spacing`, `## Borders`, `## Motion`, and `## Iconography`. The token tables carry fixed headers the renderer reads.