@kaynooo/cli-kit 0.19.0 → 0.21.0

package/src/usage.ts

@@ -0,0 +1,129 @@
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join } from 'node:path'
+import process from 'node:process'
+import { CLI_FOLDER } from './logs'
+
+// One run of a bin: which command it ran, the names of the flags it saw (never a value or an argument), how it exited and, on a usage error, the option it did not know.
+export interface UsageEntry {
+  at: string
+  bin: string
+  command?: string
+  flags: string[]
+  code: number
+  unknown?: string
+}
+
+const UNKNOWN_OPTION = /unknown option '(--[a-z][a-z0-9-]*)[=']/
+// A long name, or a single letter: anything else is an argument that happens to start with a dash, such as `-secret`.
+const FLAG_NAME = /^(?:--[a-z][a-z0-9-]*|-[a-zA-Z])$/
+const LONGEST_NAME = 40
+
+// Set when a run reported a usage error, so the entry of that run can name the option.
+let usageError: string | undefined
+
+export function noteUsageError(message: string): void {
+  usageError = message
+}
+
+// XDG_STATE_HOME when it is an absolute path, else ~/.local/state, as the spec says an empty or relative value is ignored.
+export function stateHome(env: Record<string, string | undefined> = process.env): string {
+  const dir = env.XDG_STATE_HOME
+
+  return dir !== undefined && isAbsolute(dir) ? dir : join(homedir(), '.local', 'state')
+}
+
+export function usagePath(env: Record<string, string | undefined> = process.env): string {
+  return join(stateHome(env), CLI_FOLDER, 'usage.jsonl')
+}
+
+// Whether runs are recorded: never under `bun test`, and not once KAYNOOO_CLI_NO_USAGE is set to anything but 0 or an empty value.
+export function usageRecorded(env: Record<string, string | undefined> = process.env): boolean {
+  const off = env.KAYNOOO_CLI_NO_USAGE
+
+  return env.NODE_ENV !== 'test' && (off === undefined || off === '' || off === '0')
+}
+
+// The flags among the arguments by name, `--limit=5` as `--limit`, stopping at `--`.
+export function flagNames(argv: readonly string[]): string[] {
+  const end = argv.indexOf('--')
+  const names = (end === -1 ? argv : argv.slice(0, end)).filter(word => word.startsWith('-') && word !== '-').map(word => word.includes('=') ? word.slice(0, word.indexOf('=')) : word)
+
+  return [...new Set(names)].filter(name => name.length <= LONGEST_NAME && FLAG_NAME.test(name))
+}
+
+// The entry for a run that exited with `code`, with the unknown option a usage error named.
+export function usageEntry(bin: string, command: string | undefined, argv: readonly string[], code: number, now = new Date()): UsageEntry {
+  const unknown = code === 2 && usageError !== undefined ? UNKNOWN_OPTION.exec(usageError)?.[1] : undefined
+
+  usageError = undefined
+
+  return { at: now.toISOString(), bin, ...(command === undefined ? {} : { command }), flags: flagNames(argv), code, ...(unknown === undefined ? {} : { unknown }) }
+}
+
+// Appends the run to the usage log, best effort: a log that cannot be written never changes what a bin prints or exits with.
+export function recordUsage(entry: UsageEntry, env: Record<string, string | undefined> = process.env): void {
+  if (!usageRecorded(env))
+    return
+
+  try {
+    const path = usagePath(env)
+
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+    appendFileSync(path, `${JSON.stringify(entry)}\n`, { mode: 0o600 })
+  }
+  catch {}
+}
+
+export async function readUsage(path = usagePath(), since = 0): Promise<UsageEntry[]> {
+  const file = Bun.file(path)
+
+  if (!await file.exists())
+    return []
+
+  return (await file.text()).split('\n').flatMap((line) => {
+    try {
+      const entry = JSON.parse(line) as UsageEntry
+
+      return Date.parse(entry.at) >= since ? [entry] : []
+    }
+    catch {
+      return []
+    }
+  })
+}
+
+export interface UsageSummary {
+  runs: number
+  bins: { bin: string, runs: number, failed: number, usageErrors: number }[]
+  usageErrors: { bin: string, command?: string, unknown: string, count: number }[]
+}
+
+// Runs per bin, and the usage errors by the option that was not known, most common first.
+export function summarizeUsage(entries: readonly UsageEntry[]): UsageSummary {
+  const bins = new Map<string, { runs: number, failed: number, usageErrors: number }>()
+  const errors = new Map<string, { bin: string, command?: string, unknown: string, count: number }>()
+
+  for (const entry of entries) {
+    const bin = bins.get(entry.bin) ?? { runs: 0, failed: 0, usageErrors: 0 }
+
+    bin.runs++
+    bin.failed += entry.code === 0 ? 0 : 1
+    bin.usageErrors += entry.code === 2 ? 1 : 0
+    bins.set(entry.bin, bin)
+
+    if (entry.code === 2 && entry.unknown !== undefined) {
+      const key = `${entry.bin} ${entry.command ?? ''} ${entry.unknown}`
+      const error = errors.get(key) ?? { bin: entry.bin, ...(entry.command === undefined ? {} : { command: entry.command }), unknown: entry.unknown, count: 0 }
+
+      error.count++
+      errors.set(key, error)
+    }
+  }
+
+  return {
+    runs: entries.length,
+    bins: [...bins].map(([bin, counts]) => ({ bin, ...counts })).toSorted((a, b) => b.runs - a.runs),
+    usageErrors: [...errors.values()].toSorted((a, b) => b.count - a.count),
+  }
+}

package/src/user-config.ts

@@ -0,0 +1,34 @@
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+
+export interface UserConfigLocation {
+  // The home folder; `$XDG_CONFIG_HOME` is then ignored unless `xdg` is given too.
+  home?: string | undefined
+  // The config base folder, `$XDG_CONFIG_HOME` or `<home>/.config` by default.
+  xdg?: string | undefined
+}
+
+export function configBase(where: UserConfigLocation = {}): string {
+  const xdg = where.xdg ?? (where.home === undefined ? process.env.XDG_CONFIG_HOME : undefined)
+
+  return xdg !== undefined && xdg !== '' ? xdg : join(where.home ?? homedir(), '.config')
+}
+
+// The one config file of a bin, `~/.config/kaynooo-cli/<bin>.json`: where it is written.
+export function userConfigPath(bin: string, where: UserConfigLocation = {}): string {
+  return join(configBase(where), 'kaynooo-cli', `${bin}.json`)
+}
+
+// Where to read a bin's config: the new file, else the first of `legacy` (paths under the config base, such as `['ft', 'config.json']`) that exists, else the new path. A legacy file is never moved or deleted.
+export function userConfigReadPath(bin: string, legacy: string[][] = [], where: UserConfigLocation = {}): string {
+  const current = userConfigPath(bin, where)
+
+  if (existsSync(current))
+    return current
+
+  const base = configBase(where)
+
+  return legacy.map(parts => join(base, ...parts)).find(path => existsSync(path)) ?? current
+}