@uknows/setup 0.0.0-stage → 0.1.0

package/lib/cli.mjs

@@ -0,0 +1,166 @@
+/*
+ * Command line: parse the arguments, then run setup, remove or check.
+ * A hand-written parser, because util.parseArgs is experimental on Node 18.
+ */
+import { statSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { runCheck } from './check.mjs'
+import { CLI, DOCS_URL, INGEST_ENDPOINT, SECRET, SITE_URL } from './contract.mjs'
+import { toServiceName } from './detect.mjs'
+import { ingestEndpoint, siteUrl } from './endpoint.mjs'
+import { runRemove, runSetup } from './engine.mjs'
+import { TOOL, VERSION } from './manifest.mjs'
+import { UsageError, createUI } from './ui.mjs'
+
+const FLAGS = { '--dry-run': 'dryRun', '--yes': 'yes', '-y': 'yes', '--all': 'all', '--json': 'json', '--force': 'force',
+  '--check': 'check', '--help': 'help', '-h': 'help', '--version': 'version' }
+const VALUES = { '--path': 'path', '--service-name': 'serviceName' }
+const COMMANDS = { setup: ['dryRun', 'yes', 'path', 'all', 'json', 'serviceName', 'force'], remove: ['yes', 'path', 'json', 'force'], check: ['json'] }
+
+export const HELP = `uknows-setup adds OpenTelemetry to your app, so it sends traces to UKNOWS.
+
+Usage:
+  npx @uknows/setup [setup] [options]   Find your app, show the plan, then apply it.
+  npx @uknows/setup remove [options]    Undo what setup changed.
+  npx @uknows/setup check               Send 1 test span with the key in ${SECRET.name}.
+
+Options:
+  --dry-run               Show the plan. Change nothing.
+  --yes, -y               Apply without asking. Never asks any question.
+  --path <folder>         The folder to set up. The default is this folder.
+  --all                   Set up every service folder. Each one gets its own OTEL_SERVICE_NAME.
+  --service-name <name>   The name of the service in UKNOWS.
+  --json                  Print a JSON report. Without --yes, setup only plans.
+  --force                 Run even when the repo has changes that are not committed.
+  --check                 The same as the check command.
+  --help, -h              Show this help.
+  --version               Show the version.
+
+Exit codes:
+  0  Done, or nothing to do.
+  1  Stopped or failed. Nothing changed.
+  2  Usage error, or you need to pick a service.
+  3  You need to do 1 or more steps by hand.
+
+Environment:
+  ${SECRET.name}
+      Your key, for check, as ${SECRET.value}. Set it only in your terminal.
+  ${CLI.siteEnv}
+      A test UKNOWS site, for check and the docs links. The default is ${SITE_URL}.
+  ${CLI.endpointEnv}
+      A test ingest address, for setup and check. The default is ${INGEST_ENDPOINT}.
+
+After setup, the tool asks for your key to check it. The key does not show on the screen.
+This tool never writes your key to a file.
+Docs: ${DOCS_URL}
+`
+
+/** @returns {{command: 'setup'|'remove'|'check', dryRun: boolean, yes: boolean, all: boolean, json: boolean, force: boolean, help: boolean, version: boolean, path: string|null, serviceName: string|null}} */
+export function parseArgs(argv) {
+  const opts = { command: null, dryRun: false, yes: false, all: false, json: false, force: false, help: false, version: false, path: null, serviceName: null }
+  const given = []
+  let check = false
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (!arg.startsWith('-') || arg === '-') {
+      if (opts.command) throw new UsageError(`Unexpected argument: ${arg}.`)
+      if (!(arg in COMMANDS)) throw new UsageError(`Unknown command: ${arg}.`)
+      opts.command = arg
+      continue
+    }
+    const eq = arg.startsWith('--') ? arg.indexOf('=') : -1
+    const flag = eq > 0 ? arg.slice(0, eq) : arg
+    if (flag in VALUES) {
+      let value = eq > 0 ? arg.slice(eq + 1) : argv[i + 1]
+      if (eq < 0) {
+        if (value === undefined || value.startsWith('-')) throw new UsageError(`${flag} needs a value.`)
+        i++
+      }
+      if (!value) throw new UsageError(`${flag} needs a value.`)
+      opts[VALUES[flag]] = value
+      given.push([VALUES[flag], flag])
+    } else if (flag in FLAGS) {
+      if (eq > 0) throw new UsageError(`${flag} does not take a value.`)
+      if (FLAGS[flag] === 'check') check = true
+      else opts[FLAGS[flag]] = true
+      if (!['help', 'version', 'check'].includes(FLAGS[flag])) given.push([FLAGS[flag], flag])
+    } else throw new UsageError(`Unknown option: ${flag}.`)
+  }
+  if (check && opts.command && opts.command !== 'check') throw new UsageError(`--check does not work with ${opts.command}.`)
+  opts.command = check ? 'check' : opts.command ?? 'setup'
+  for (const [key, flag] of given) {
+    if (!COMMANDS[opts.command].includes(key)) throw new UsageError(`${flag} does not work with ${opts.command}.`)
+  }
+  return opts
+}
+
+/**
+ * Run the CLI. Returns the exit code.
+ * @param {string[]} argv
+ * @param {{stdin?: any, stdout?: any, stderr?: any, cwd?: string, env?: Record<string, string|undefined>, interactive?: boolean, deps?: object}} [io]
+ */
+export async function main(argv, io = {}) {
+  const { stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), env = process.env, deps = {} } = io
+  const json = argv.includes('--json')
+  const usage = (message) => {
+    stderr.write(`${message}\nRun uknows-setup --help.\n`)
+    if (json) stdout.write(`${JSON.stringify({ schema: 1, tool: TOOL, version: VERSION, command: null, status: 'usage-error', exitCode: 2, problems: [{ code: 'usage', message }] }, null, 2)}\n`)
+    return 2
+  }
+  let args
+  try {
+    args = parseArgs(argv)
+  } catch (error) {
+    if (error instanceof UsageError) return usage(error.message)
+    throw error
+  }
+  if (args.help) { stdout.write(HELP); return 0 }
+  if (args.version) { stdout.write(`${VERSION}\n`); return 0 }
+  if (args.command === 'check') return check(args, { stdout, stderr, env }, deps.runCheck ?? runCheck)
+
+  // setup writes the same ingest address that check sends to.
+  const endpoint = ingestEndpoint(env)
+  if (!endpoint) return usage(`${CLI.endpointEnv} must be an https address.`)
+  if (!siteUrl(env)) return usage(`${CLI.siteEnv} must be an https address with no path, for example https://uknows.example.com.`)
+  const root = resolve(cwd, args.path ?? '.')
+  let folder = false
+  try { folder = statSync(root).isDirectory() } catch { /* missing */ }
+  if (!folder) return usage(`${args.path ?? root} is not a folder.`)
+  if (args.serviceName !== null && (deps.toServiceName ?? toServiceName)(args.serviceName) !== args.serviceName) {
+    return usage(`${args.serviceName} is not a valid service name. Use lowercase letters, digits and -, up to 63 characters.`)
+  }
+  const ui = createUI({ stdin, stdout, stderr, json: args.json, interactive: io.interactive })
+  try {
+    const { code, report } = await (args.command === 'remove' ? runRemove : runSetup)({ ...args, root, endpoint, env }, { ...deps, ui })
+    if (args.json) stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    return code
+  } finally {
+    ui.close()
+  }
+}
+
+async function check(args, { stdout, stderr, env }, run) {
+  const result = await run({ env })
+  const status = result.exit === 2 ? 'no-key' : result.ok ? 'reached' : result.status === null ? 'network-error' : 'rejected'
+  const lines = redact(result.lines, env[SECRET.name])
+  if (args.json) {
+    stdout.write(`${JSON.stringify({ schema: 1, tool: TOOL, version: VERSION, command: 'check', status, exitCode: result.exit,
+      httpStatus: result.status, workspace: result.workspace, environment: result.environment, lines }, null, 2)}\n`)
+  } else {
+    (result.exit === 1 ? stderr : stdout).write(lines.map((line) => `${line}\n`).join(''))
+  }
+  return result.exit
+}
+
+/** Belt and braces: take every header value out of the lines, even if the server echoed it. */
+function redact(lines, headers) {
+  const secrets = []
+  for (const pair of String(headers ?? '').split(',')) {
+    const value = pair.slice(pair.indexOf('=') + 1).trim()
+    if (pair.includes('=') && value.length >= 4) {
+      secrets.push(value)
+      try { secrets.push(decodeURIComponent(value)) } catch { /* not encoded */ }
+    }
+  }
+  return lines.map((line) => secrets.reduce((out, secret) => out.split(secret).join('***'), String(line)))
+}