@uknows/setup 0.0.0-stage → 0.1.0

package/lib/ui.mjs

@@ -0,0 +1,106 @@
+/*
+ * Terminal input and output. Plain text, no color. Normal text goes to
+ * stdout and errors to stderr. With --json, normal text is left out, so
+ * stdout holds only the JSON report, and nothing ever prompts.
+ */
+import { createInterface } from 'node:readline'
+import { HOSTS, STACKS } from './contract.mjs'
+
+/** A usage error: exit 2 with the message and a hint to run --help. */
+export class UsageError extends Error {}
+
+const FRAMEWORKS = { express: 'Express', fastify: 'Fastify', nestjs: 'NestJS', koa: 'Koa', hapi: 'Hapi', nitro: 'Nitro',
+  nuxt: 'Nuxt', next: 'Next.js', fastapi: 'FastAPI', django: 'Django', flask: 'Flask', starlette: 'Starlette',
+  falcon: 'Falcon', tornado: 'Tornado', aspnetcore: 'ASP.NET Core', 'spring-boot': 'Spring Boot', quarkus: 'Quarkus',
+  micronaut: 'Micronaut', echo: 'Echo', gin: 'Gin', chi: 'chi', laravel: 'Laravel', symfony: 'Symfony', slim: 'Slim',
+  rails: 'Rails', sinatra: 'Sinatra' }
+
+export const stackLabel = (id) => STACKS.find((s) => s.id === id)?.label ?? 'an unknown stack'
+export const hostLabel = (id) => HOSTS.find((h) => h.id === id)?.label ?? id
+export const frameworkLabel = (id) => FRAMEWORKS[id] ?? id
+export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`
+export const unique = (list) => [...new Set(list)]
+/** 'a', 'a and b', 'a, b and c'. */
+export const list = (names) => (names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names.at(-1)}` : names.join(''))
+
+/**
+ * @param {{stdin?: any, stdout?: any, stderr?: any, json?: boolean, interactive?: boolean}} [io]
+ *   interactive defaults to: stdin and stdout are terminals and json is off.
+ */
+export function createUI({ stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, json = false, interactive } = {}) {
+  let rl = null, closed = false
+  const queue = [], waiting = []
+  const nextLine = () => {
+    if (!rl) {
+      rl = createInterface({ input: stdin, terminal: false })
+      rl.on('line', (line) => (waiting.length ? waiting.shift()(line) : queue.push(line)))
+      rl.on('close', () => { closed = true; while (waiting.length) waiting.shift()(null) })
+    }
+    if (queue.length) return Promise.resolve(queue.shift())
+    return closed ? Promise.resolve(null) : new Promise((resolve) => waiting.push(resolve))
+  }
+  const print = (text = '') => { if (!json) stdout.write(`${text}\n`) }
+  /** null when input ended. */
+  const prompt = (question) => { stdout.write(`${question} `); return nextLine() }
+
+  return {
+    interactive: interactive ?? Boolean(stdin.isTTY && stdout.isTTY && !json),
+    print,
+    error: (text) => stderr.write(`${text}\n`),
+    /** @param {import('./types.mjs').Block} block */
+    block(block) {
+      print(block.title)
+      block.lines.forEach((line, i) => print(`  ${i + 1}. ${line}`))
+      for (const s of block.snippets ?? []) {
+        print(`  ${s.caption}:`)
+        for (const line of s.code.split('\n')) print(`      ${line}`)
+      }
+      print()
+    },
+    async ask(question) { return ((await prompt(question)) ?? '').trim() },
+    /**
+     * Read 1 line without showing it, for a key. In a terminal, raw mode stops the echo. Backspace works,
+     * Ctrl-C and Ctrl-D skip. Without a terminal (tests, pipes) it reads a plain line. Never stores the answer.
+     */
+    async secret(question) {
+      const tty = stdin.isTTY && typeof stdin.setRawMode === 'function'
+      if (tty) stdin.setRawMode(true)
+      let line
+      try { line = await prompt(question) } finally { if (tty) { stdin.setRawMode(false); stdout.write('\n') } }
+      let out = ''
+      for (const ch of line ?? '') {
+        if (ch === '\u0003' || ch === '\u0004') return ''
+        if (ch === '\u007f' || ch === '\b') out = out.slice(0, -1)
+        else if (ch === '\u0015') out = ''
+        else if (ch >= ' ') out += ch
+      }
+      return out
+    },
+    /** Y/n. Empty means yes. Ended input means no. */
+    async confirm(question) {
+      for (let tries = 0; tries < 3; tries++) {
+        const answer = await prompt(question)
+        if (answer === null) return false
+        const a = answer.trim().toLowerCase()
+        if (a === '' || a === 'y' || a === 'yes') return true
+        if (a === 'n' || a === 'no') return false
+        print('Type y or n.')
+      }
+      return false
+    },
+    /** A numbered menu. Returns the 0-based index. 3 bad answers: usage error. */
+    async choose(title, options) {
+      print(title)
+      options.forEach((option, i) => print(`  ${i + 1}. ${option}`))
+      for (let tries = 0; tries < 3; tries++) {
+        const answer = await prompt(`Type a number from 1 to ${options.length}:`)
+        if (answer === null) break
+        const n = Number(answer.trim())
+        if (Number.isInteger(n) && n >= 1 && n <= options.length) return n - 1
+        print(`Type a number from 1 to ${options.length}.`)
+      }
+      throw new UsageError('No choice was made.')
+    },
+    close() { rl?.close() },
+  }
+}

package/lib/workspace.mjs

@@ -0,0 +1,198 @@
+/*
+ * A read view of the repo plus the edits staged in this run. Producers read
+ * through it, so a later producer sees the edits of an earlier one. Nothing
+ * here writes to disk: the engine writes ws.changes() on apply.
+ *
+ * Paths are repo-relative with '/' on every OS. '.' is the root.
+ */
+import { closeSync, existsSync, lstatSync, openSync, readFileSync, readSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, posix, relative, resolve, sep } from 'node:path'
+
+/** Folders that never hold a service or deploy file of the app. Dot folders are skipped too, except .github. */
+export const SKIP_DIRS = new Set(['node_modules', 'vendor', 'venv', 'target', 'build', 'dist', 'out', 'bin', 'obj',
+  '__pycache__', 'coverage', 'test', 'tests', '__tests__', 'test_data', 'testdata', 'fixtures', 'examples', 'example', 'samples'])
+const BOM = '\uFEFF'
+const LIMIT = 20000
+
+/**
+ * @typedef {Object} Change  The net change to 1 file after every staged edit.
+ * @property {string} file
+ * @property {string|null} before   Disk text before this run, BOM removed. null = new file.
+ * @property {string} after         Text to write, BOM removed.
+ * @property {boolean} bom          The disk file starts with a UTF-8 BOM. The engine writes it back.
+ * @property {string[]} why         The why of each edit, in order.
+ */
+
+export class Workspace {
+  /** @param {string} root absolute or relative path of the repo root */
+  constructor(root) {
+    this.root = resolve(root)
+    /** @type {Map<string, string>} */ this.overlay = new Map()
+    /** @type {Map<string, string|null>} */ this.original = new Map()
+    /** @type {Map<string, string[]>} */ this.whys = new Map()
+    /** True when files() stopped at its limit. */ this.truncated = false
+  }
+
+  /** Absolute native path. */
+  abs(path) {
+    checkPath(path)
+    return path === '.' ? this.root : join(this.root, ...path.split('/'))
+  }
+
+  stat(path) {
+    try { return lstatSync(this.abs(path)) } catch { return null }
+  }
+
+  exists(path) { return this.overlay.has(path) || this.stat(path) !== null }
+
+  /** A real folder (not a link). */
+  isDir(path) { return Boolean(this.stat(path)?.isDirectory()) }
+
+  /** Current text: staged edits first, else disk. BOM removed. null when missing, a link or not a file. */
+  read(path) {
+    checkPath(path)
+    return this.overlay.has(path) ? this.overlay.get(path) : this.disk(path)
+  }
+
+  /** Text on disk, ignoring staged edits. BOM removed. */
+  disk(path) {
+    const stat = this.stat(path)
+    if (!stat?.isFile()) return null
+    const text = readFileSync(this.abs(path), 'utf8')
+    return text.startsWith(BOM) ? text.slice(1) : text
+  }
+
+  hasBom(path) {
+    if (!this.stat(path)?.isFile()) return false
+    const fd = openSync(this.abs(path), 'r')
+    try {
+      const head = Buffer.alloc(3)
+      return readSync(fd, head, 0, 3, 0) === 3 && head[0] === 0xef && head[1] === 0xbb && head[2] === 0xbf
+    } finally { closeSync(fd) }
+  }
+
+  /** Names in a folder (files and folders, links included), plus staged new files. Sorted. */
+  list(dir = '.') {
+    const names = new Set()
+    try { for (const name of readdirSync(this.abs(dir))) names.add(name) } catch { /* missing */ }
+    const prefix = dir === '.' ? '' : `${dir}/`
+    for (const path of this.overlay.keys()) {
+      if (path.startsWith(prefix) && !path.slice(prefix.length).includes('/')) names.add(path.slice(prefix.length))
+    }
+    return [...names].sort(byCodePoint)
+  }
+
+  /**
+   * Every regular file under dir, recursive, sorted. Skips links, SKIP_DIRS
+   * and dot folders except .github. Includes staged new files.
+   */
+  files(dir = '.') {
+    const out = new Set()
+    const walk = (rel) => {
+      let entries
+      try { entries = readdirSync(this.abs(rel), { withFileTypes: true }) } catch { return }
+      for (const entry of entries) {
+        if (out.size >= LIMIT) { this.truncated = true; return }
+        const path = rel === '.' ? entry.name : `${rel}/${entry.name}`
+        if (entry.isSymbolicLink()) continue
+        if (entry.isDirectory()) {
+          if (SKIP_DIRS.has(entry.name) || (entry.name.startsWith('.') && entry.name !== '.github')) continue
+          walk(path)
+        } else if (entry.isFile()) out.add(path)
+      }
+    }
+    walk(dir)
+    const prefix = dir === '.' ? '' : `${dir}/`
+    for (const path of this.overlay.keys()) if (path.startsWith(prefix)) out.add(path)
+    return [...out].sort(byCodePoint)
+  }
+
+  /**
+   * Stage an edit. Throws when edit.before is not the current text, which
+   * means 2 producers raced on the same file.
+   * @param {import('./types.mjs').Edit} edit
+   */
+  stage(edit) {
+    const current = this.read(edit.file)
+    const stale = edit.before === null ? current !== null || this.exists(edit.file) : current !== edit.before
+    if (stale) throw new Error(`Edit for ${edit.file} is out of date`)
+    if (edit.after === current) return
+    if (!this.original.has(edit.file)) this.original.set(edit.file, current)
+    this.overlay.set(edit.file, edit.after)
+    this.whys.set(edit.file, [...(this.whys.get(edit.file) ?? []), edit.why])
+  }
+
+  /** Net changes, in the order files were first staged. Files that ended up unchanged are left out. */
+  changes() {
+    const out = []
+    for (const [file, before] of this.original) {
+      const after = this.overlay.get(file)
+      if (after === before) continue
+      out.push({ file, before, after, bom: before !== null && this.hasBom(file), why: this.whys.get(file) ?? [] })
+    }
+    return out
+  }
+}
+
+/** @param {string} root */
+export const createWorkspace = (root) => new Workspace(root)
+
+/**
+ * @typedef {Object} RepoView  A read view of the whole git repo around the root, for --path runs in a monorepo.
+ * @property {() => string[]} files
+ * @property {(path: string) => string|null} read
+ * @property {(path: string) => boolean} exists
+ * @property {(path: string) => import('node:fs').Stats|null} stat
+ * @property {string} top   The repo top, relative to the root: '.', '..' or '../..'.
+ */
+
+/**
+ * The files of the whole git repo when the root is a folder inside it. Paths
+ * stay relative to the root: a file above it reads as '../../k8s/api.yaml'.
+ * Inside the root, reads go through ws, so staged edits count. Only folders
+ * up to 5 levels above the root count, and never the home folder, which can
+ * be a dotfiles repo. Nothing here writes.
+ * @param {Workspace} ws
+ * @returns {RepoView}
+ */
+export function repoView(ws) {
+  let top = null
+  for (let dir = ws.root, n = 0; n <= 5 && dir !== homedir(); dir = dirname(dir), n++) {
+    if (existsSync(join(dir, '.git'))) { top = dir; break }
+    if (dirname(dir) === dir) break
+  }
+  const view = { files: () => ws.files(), read: (path) => ws.read(path), exists: (path) => ws.exists(path), stat: (path) => ws.stat(path), top: '.' }
+  if (!top || top === ws.root) return view
+  const outer = createWorkspace(top)
+  const prefix = relative(top, ws.root).split(sep).join('/')
+  const above = (path) => path.startsWith('../')
+  const toTop = (path) => posix.normalize(`${prefix}/${path}`)
+  let files = null
+  return {
+    files: () => (files ??= [...new Set([...ws.files(), ...outer.files().map((p) => posix.relative(prefix, p))])].sort(byCodePoint)),
+    read: (path) => (above(path) ? outer.read(toTop(path)) : ws.read(path)),
+    exists: (path) => (above(path) ? outer.exists(toTop(path)) : ws.exists(path)),
+    stat: (path) => (above(path) ? outer.stat(toTop(path)) : ws.stat(path)),
+    top: prefix.split('/').map(() => '..').join('/'),
+  }
+}
+
+/** Folders from dir up to top, nearest first: upFrom('a/b', '..') is ['a/b', 'a', '.', '..']. */
+export function upFrom(dir, top = '.') {
+  const out = []
+  for (let d = dir; out.length < 64; d = d === '.' ? '..' : /^\.\.(\/\.\.)*$/.test(d) ? `${d}/..` : d.includes('/') ? d.slice(0, d.lastIndexOf('/')) : '.') {
+    out.push(d)
+    if (d === top) break
+  }
+  return out
+}
+
+export function checkPath(path) {
+  if (typeof path !== 'string' || !path || path.includes('\\') || path.startsWith('/') || /^[A-Za-z]:/.test(path)
+    || (path !== '.' && path.split('/').some((part) => !part || part === '.' || part === '..'))) {
+    throw new Error(`Not a repo-relative path: ${path}`)
+  }
+}
+
+function byCodePoint(a, b) { return a < b ? -1 : a > b ? 1 : 0 }

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@uknows/setup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Add standard OpenTelemetry to your app in 1 command, so it sends traces to UKNOWS. Shows the change, asks once, can undo.",
+  "keywords": [
+    "uknows",
+    "opentelemetry",
+    "otel",
+    "apm",
+    "tracing",
+    "observability",
+    "setup",
+    "cli"
+  ],
+  "homepage": "https://uknows.defacloud.my/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MohammediYunus/uknows.git",
+    "directory": "packages/uknows-setup"
+  },
+  "license": "Apache-2.0",
+  "author": "UKNOWS",
+  "type": "module",
+  "bin": {
+    "uknows-setup": "bin/uknows-setup.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "node tools/prepublish.mjs"
+  }
+}