lecodes-cli 0.20.1 → 1.0.0

package/src/cli/output.ts

@@ -0,0 +1,102 @@
+import { createInterface } from "node:readline"
+
+/*
+ * Everything a command prints goes through here. Two channels, one rule:
+ *   stdout  the command's RESULT — what a pipe or `-o` would capture (JSON, JS, a listing)
+ *   stderr  diagnostics: progress, notes, warnings — never in the way of piped output
+ * `log` / `success` / `warn` are stdout (for commands whose output IS the conversation);
+ * `note` / `warnErr` / `logErr` are the stderr twins for commands that write a result to stdout.
+ */
+
+const useColor = process.stdout.isTTY && process.env.NO_COLOR === undefined
+const paint = (code: string, s: string): string => useColor ? `\x1b[${code}m${s}\x1b[0m` : s
+
+/** ANSI colours (no-ops when not a TTY or NO_COLOR is set). */
+export const c = {
+  bold: (s: string) => paint("1", s),
+  dim: (s: string) => paint("2", s),
+  red: (s: string) => paint("31", s),
+  green: (s: string) => paint("32", s),
+  yellow: (s: string) => paint("33", s),
+  cyan: (s: string) => paint("36", s),
+}
+
+export const log = (msg = ""): void => { process.stdout.write(msg + "\n") }
+export const info = (msg: string): void => log(msg)
+export const success = (msg: string): void => log(c.green("✓ ") + msg)
+export const warn = (msg: string): void => log(c.yellow("! ") + msg)
+
+export const logErr = (msg = ""): void => { process.stderr.write(msg + "\n") }
+export const note = (msg: string): void => logErr(c.dim(msg))
+export const warnErr = (msg: string): void => logErr(c.yellow("! ") + msg)
+
+const ANSI = /\x1b\[[0-9;]*m/g
+/** Printed width of a string — colour codes don't count. */
+export const printedWidth = (s: string): number => s.replace(ANSI, "").length
+
+/** Rows as aligned columns (the last column unpadded so colours don't drag trailing spaces). */
+export const table = (rows: string[][], indent = "  "): void => {
+  if (rows.length === 0) return
+  const widths = rows[0].map((_, i) => Math.max(...rows.map(r => printedWidth(r[i] ?? ""))))
+  for (const row of rows) {
+    const cells = row.map((cell, i) => i === row.length - 1 ? cell : cell + " ".repeat(Math.max(0, widths[i] - printedWidth(cell))))
+    log(indent + cells.join("  "))
+  }
+}
+
+/** A compact "3h ago" — absolute timestamps make tables unreadable at a glance. */
+export const relativeTime = (iso: string | null | undefined): string => {
+  if (!iso) return c.dim("never")
+  const ms = Date.now() - new Date(iso).getTime()
+  if (!Number.isFinite(ms)) return c.dim("—")
+  const mins = Math.round(ms / 60_000)
+  if (mins < 1) return "just now"
+  if (mins < 60) return `${mins}m ago`
+  const hours = Math.round(mins / 60)
+  if (hours < 24) return `${hours}h ago`
+  return `${Math.round(hours / 24)}d ago`
+}
+
+/** Keep a label short, dropping characters from the FRONT (paths matter most at the end). */
+const ellipsize = (s: string, max: number): string => s.length <= max ? s : "…" + s.slice(s.length - max + 1)
+
+/** A single, in-place-updating progress line (TTY only; a no-op when piped). */
+export const progress = (done: number, total: number, label = ""): void => {
+  if (!process.stdout.isTTY) return
+  const pct = total > 0 ? Math.round((done / total) * 100) : 100
+  process.stdout.clearLine(0)
+  process.stdout.cursorTo(0)
+  process.stdout.write(`  ${c.cyan(`${pct}`.padStart(3) + "%")} ${c.dim(`(${done}/${total})`)} ${c.dim(ellipsize(label, 48))}`)
+}
+
+/** Finish a progress line with a newline so later output starts cleanly. */
+export const endProgress = (): void => { if (process.stdout.isTTY) process.stdout.write("\n") }
+
+export const prompt = (question: string, fallback?: string): Promise<string> =>
+  new Promise(resolve => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    const suffix = fallback ? c.dim(` (${fallback})`) : ""
+    rl.question(`${question}${suffix}: `, answer => {
+      rl.close()
+      resolve(answer.trim() || fallback || "")
+    })
+  })
+
+/** Prompt without echoing the input (passwords, token paste). */
+export const promptHidden = (question: string): Promise<string> =>
+  new Promise(resolve => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true })
+    rl.question(`${question}: `, answer => {
+      rl.close()
+      process.stdout.write("\n")
+      resolve(answer.trim())
+    })
+    // Mute everything written after the prompt line was emitted (the keystroke echoes).
+    ;(rl as unknown as { _writeToOutput: (s: string) => void })._writeToOutput = () => {}
+  })
+
+export const confirm = async (question: string, fallback = false): Promise<boolean> => {
+  const answer = (await prompt(`${question} ${fallback ? "[Y/n]" : "[y/N]"}`)).toLowerCase()
+  if (!answer) return fallback
+  return answer === "y" || answer === "yes"
+}

package/src/cli/run.ts

@@ -0,0 +1,106 @@
+import { parseArgv } from "./args"
+import { readFlags, unknownFlags, type Command, type Context } from "./command"
+import { CliError, UsageError } from "./errors"
+import { commandHelp, globalHelp, type Group } from "./help"
+import { c, log, logErr, warnErr } from "./output"
+
+/*
+ * The runner: argv → the command node → typed flags → run. Global switches are handled here for
+ * every node: --help / -h / `help <cmd…>`, --version / -v, --yes / -y (pre-approves first-use
+ * installs of optional peers, see hosts/peerInstall.ts).
+ */
+
+export type Cli = {
+  version: string
+  groups: Group[]
+  /** Printed under the global help. */
+  footer?: string
+  /** `lecodes --version` — the caller prints whatever it wants there. */
+  printVersion: () => void
+  /** Runs before the command (the project's .env, for instance). */
+  before?: () => void
+}
+
+const all = (groups: Group[]): Command<any>[] => groups.flatMap(g => g.commands)
+
+/** Levenshtein-closest command name for the "did you mean" line. */
+const closest = (name: string, cmds: Command<any>[]): string | undefined => {
+  const dist = (a: string, b: string): number => {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)] as number[])
+    for (let j = 1; j <= b.length; j++) d[0][j] = j
+    for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++)
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    return d[a.length][b.length]
+  }
+  const best = cmds.filter(x => !x.hidden).map(x => [x.name, dist(name, x.name)] as const).sort((p, q) => p[1] - q[1])[0]
+  return best && best[1] <= Math.max(2, Math.floor(name.length / 3)) ? best[0] : undefined
+}
+
+const find = (cmds: Command<any>[] | undefined, name: string): Command<any> | undefined =>
+  cmds?.find(x => x.name === name || x.aliases?.includes(name))
+
+const HELP_WORDS = new Set(["--help", "-h"])
+
+export const runCli = async (cli: Cli, argv: string[]): Promise<void> => {
+  cli.before?.()
+  if (argv.includes("--yes") || argv.includes("-y")) process.env.LECODES_YES = "1"
+
+  const top = all(cli.groups)
+  const help = () => globalHelp(cli.version, cli.groups, cli.footer)
+  let words = argv
+  // `lecodes help …` = `lecodes … --help`
+  if (words[0] === "help") words = [...words.slice(1), "--help"]
+  if (words.length === 0 || (words.length === 1 && HELP_WORDS.has(words[0]))) { log(help()); return }
+  if (words[0] === "--version" || words[0] === "-v" || words[0] === "version") { cli.printVersion(); return }
+
+  // walk the tree: every leading word that names a subcommand descends
+  const path: string[] = []
+  let node = find(top, words[0])
+  if (!node) {
+    const hint = closest(words[0], top)
+    logErr(c.red(`Unknown command: ${words[0]}`) + (hint ? `  — did you mean ${c.bold(hint)}?` : ""))
+    logErr(c.dim("Run `lecodes --help` for the list."))
+    process.exitCode = 1
+    return
+  }
+  path.push(node.name)
+  let rest = words.slice(1)
+  while (rest.length && node.commands) {
+    const sub = find(node.commands, rest[0])
+    if (!sub) break
+    node = sub
+    path.push(sub.name)
+    rest = rest.slice(1)
+  }
+
+  if (rest.some(w => HELP_WORDS.has(w)) && !node.passthrough) { log(commandHelp(path, node)); return }
+  if (!node.run) {
+    // a group called bare (or with a word that names no subcommand): its help is the answer
+    if (rest.length) logErr(c.red(`Unknown command: ${[...path, rest[0]].join(" ")}`))
+    log(commandHelp(path, node))
+    if (rest.length) process.exitCode = 1
+    return
+  }
+
+  const parsed = parseArgv(rest)
+  const spec = node.flags ?? {}
+  if (!node.passthrough) {
+    const unknown = unknownFlags(spec, parsed.flags)
+    if (unknown.length) warnErr(`${unknown.map(f => `--${f}`).join(", ")}: not an option of \`lecodes ${path.join(" ")}\` (see --help)`)
+  }
+  const ctx: Context<any> = { args: parsed.positional, flags: readFlags(spec, parsed.flags, path), raw: parsed.flags, argv: rest, path }
+  try {
+    await node.run(ctx)
+  } catch (e) {
+    if (e instanceof UsageError) { logErr(c.red("✗ ") + e.message); logErr(""); logErr(commandHelp(path, node)) }
+    else throw e
+    process.exitCode = 1
+  }
+}
+
+/** Top-level error reporting: a CliError is a message, anything else is unexpected. */
+export const reportError = (e: unknown): void => {
+  if (e instanceof CliError) logErr(c.red("✗ ") + e.message)
+  else logErr(c.red("✗ Unexpected error: ") + (e instanceof Error ? (e.stack ?? e.message) : String(e)))
+  process.exitCode = 1
+}