@znight/cli 0.0.0-stage → 0.1.1

package/src/runtime.ts

@@ -0,0 +1,86 @@
+/**
+ * JavaScript runtimes the application can run on (`znight dev`, `znight start`) and executable
+ * lookup in `PATH`.
+ */
+import { accessSync, constants, statSync } from 'node:fs'
+import { delimiter, isAbsolute, join } from 'node:path'
+
+/** Runtime of the application process. */
+export type RuntimeName = 'node' | 'bun'
+
+/** `--runtime` values: `auto` picks Bun when the CLI itself runs on Bun, Node.js otherwise. */
+export type RuntimeOption = RuntimeName | 'auto'
+
+/** The runtime executing the CLI. */
+export interface HostRuntime {
+  readonly name: RuntimeName
+  /** Absolute path of the running executable (`process.execPath`). */
+  readonly execPath: string
+  readonly platform: NodeJS.Platform
+}
+
+/** Detects the runtime executing this process. */
+export function detectHostRuntime(): HostRuntime {
+  const isBun = typeof process.versions['bun'] === 'string'
+  return { name: isBun ? 'bun' : 'node', execPath: process.execPath, platform: process.platform }
+}
+
+/** Resolves `auto`. */
+export function resolveRuntime(option: RuntimeOption | undefined, host: HostRuntime): RuntimeName {
+  return option === undefined || option === 'auto' ? host.name : option
+}
+
+/**
+ * Finds an executable in `PATH` (`PATHEXT` extensions on Windows). Absolute paths are checked as is.
+ * Returns `undefined` when not found.
+ */
+export function which(
+  command: string,
+  env: Readonly<Record<string, string | undefined>>,
+  platform: NodeJS.Platform = process.platform,
+): string | undefined {
+  const extensions =
+    platform === 'win32' ? ['', ...(env['PATHEXT'] ?? '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean)] : ['']
+  const candidates = isAbsolute(command)
+    ? [command]
+    : (env['PATH'] ?? env['Path'] ?? '')
+        .split(platform === 'win32' ? ';' : delimiter)
+        .filter(directory => directory !== '')
+        .map(directory => join(directory, command))
+  for (const candidate of candidates) {
+    for (const extension of extensions) {
+      const file = candidate + extension
+      if (isExecutable(file, platform)) return file
+    }
+  }
+  return undefined
+}
+
+function isExecutable(file: string, platform: NodeJS.Platform): boolean {
+  try {
+    if (!statSync(file).isFile()) return false
+    if (platform !== 'win32') accessSync(file, constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The executable of `runtime`: the running executable when it is that runtime, otherwise the one
+ * found in `PATH`.
+ */
+export function runtimeExecutable(
+  runtime: RuntimeName,
+  host: HostRuntime,
+  env: Readonly<Record<string, string | undefined>>,
+): string | undefined {
+  if (runtime === host.name) return host.execPath
+  return which(runtime, env, host.platform)
+}
+
+/** Runtime arguments placed before the entry file. */
+export function runtimeArguments(runtime: RuntimeName, extra: readonly string[] = []): string[] {
+  // Vite emits source maps for server builds: map stack traces to the TypeScript sources.
+  return runtime === 'node' ? ['--enable-source-maps', ...extra] : [...extra]
+}

package/src/scaffold/create.ts

@@ -0,0 +1,65 @@
+/** Writing a new project to disk, initialising git and installing dependencies. */
+import type { ProcessService, RunResult } from '../integrations/process.ts'
+import type { PackageManager } from './options.ts'
+import type { ProjectFile } from './templates.ts'
+
+import { mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { installCommand } from './options.ts'
+
+/** Entries tolerated in the target directory (a fresh clone, editor settings). */
+const IGNORABLE_ENTRIES = new Set(['.git', '.DS_Store', 'Thumbs.db', '.idea', '.vscode'])
+
+/** State of the target directory of `znight new`. */
+export type TargetState = 'missing' | 'empty' | 'not-empty' | 'file'
+
+/** Inspects the target directory. */
+export function targetState(directory: string): TargetState {
+  let stats: ReturnType<typeof statSync>
+  try {
+    stats = statSync(directory)
+  } catch {
+    return 'missing'
+  }
+  if (!stats.isDirectory()) return 'file'
+  return readdirSync(directory).every(entry => IGNORABLE_ENTRIES.has(entry)) ? 'empty' : 'not-empty'
+}
+
+/** Writes `files` under `directory` (created when missing). Returns the written paths. */
+export function writeProject(directory: string, files: readonly ProjectFile[]): string[] {
+  mkdirSync(directory, { recursive: true })
+  for (const file of files) {
+    const target = join(directory, file.path)
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, file.content)
+  }
+  return files.map(file => file.path)
+}
+
+/** Outcome of {@link initGit}. */
+export type GitOutcome = 'initialized' | 'inside-repository' | 'unavailable' | 'failed'
+
+/** `git init` in `directory`, unless it already is inside a git work tree (monorepos). */
+export async function initGit(
+  processes: ProcessService,
+  directory: string,
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<GitOutcome> {
+  const inside = await processes.run('git', ['rev-parse', '--is-inside-work-tree'], { cwd: directory, env })
+  if (inside.error !== undefined) return 'unavailable'
+  if (inside.code === 0 && inside.stdout.trim() === 'true') return 'inside-repository'
+  const init = await processes.run('git', ['init', '--quiet'], { cwd: directory, env })
+  return init.code === 0 ? 'initialized' : 'failed'
+}
+
+/** `<pm> install` in `directory`, output captured. */
+export function installDependencies(
+  processes: ProcessService,
+  directory: string,
+  packageManager: PackageManager,
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<RunResult> {
+  const [command, ...args] = installCommand(packageManager)
+  return processes.run(command, args, { cwd: directory, env })
+}

package/src/scaffold/options.ts

@@ -0,0 +1,103 @@
+/** Choices of `znight new`. */
+
+/** Package managers supported by `znight new`. */
+export type PackageManager = 'bun' | 'npm' | 'pnpm' | 'yarn'
+
+/** HTTP adapters of `@znight/http`. */
+export type HttpAdapterName = 'node' | 'fastify' | 'express' | 'hono'
+
+/** Optional features of a new project. */
+export type Feature = 'config' | 'observability' | 'messaging' | 'schedule' | 'openapi'
+
+/** Every package manager, in display order. */
+export const PACKAGE_MANAGERS: readonly PackageManager[] = ['bun', 'npm', 'pnpm', 'yarn']
+
+/** Every HTTP adapter, in display order. */
+export const HTTP_ADAPTERS: readonly HttpAdapterName[] = ['node', 'fastify', 'express', 'hono']
+
+/** Every feature, in display (and canonical) order. */
+export const FEATURES: readonly Feature[] = ['config', 'observability', 'messaging', 'schedule', 'openapi']
+
+/** Features selected when none are given. */
+export const DEFAULT_FEATURES: readonly Feature[] = ['config', 'observability']
+
+/** Labels shown by the prompts and the help. */
+export const ADAPTER_LABELS: Readonly<Record<HttpAdapterName, string>> = {
+  node: 'node:http (built-in, zero dependency)',
+  fastify: 'Fastify',
+  express: 'Express',
+  hono: 'Hono',
+}
+
+/** Labels shown by the prompts. */
+export const FEATURE_LABELS: Readonly<Record<Feature, string>> = {
+  config: 'Config: type-safe configuration classes (@znight/config)',
+  observability: 'Observability: structured logs, metrics, tracing (@znight/observability)',
+  messaging: 'Messaging: message consumers and publishing (@znight/messaging)',
+  schedule: 'Schedule: cron, interval and timeout jobs (@znight/schedule)',
+  openapi: 'OpenAPI: openapi.json and an API reference at /docs (@znight/openapi)',
+}
+
+/** Everything that determines the files of a new project. */
+export interface ProjectOptions {
+  /** npm package name. */
+  readonly name: string
+  readonly packageManager: PackageManager
+  readonly adapter: HttpAdapterName
+  /** Selected features, in canonical order. */
+  readonly features: readonly Feature[]
+  /** Version range base of the `@znight/*` packages (the CLI version). */
+  readonly znightVersion: string
+}
+
+/**
+ * Parses `--features` (`config,observability`, `none`, `all`). Returns the features in canonical
+ * order, or the unknown names.
+ */
+export function parseFeatures(value: string): { features: Feature[] } | { unknown: string[] } {
+  const names = value
+    .split(',')
+    .map(name => name.trim().toLowerCase())
+    .filter(name => name !== '')
+  if (names.length === 1 && names[0] === 'none') return { features: [] }
+  if (names.length === 1 && names[0] === 'all') return { features: [...FEATURES] }
+  const unknown = names.filter(name => !FEATURES.includes(name as Feature))
+  if (unknown.length > 0) return { unknown }
+  return { features: FEATURES.filter(feature => names.includes(feature)) }
+}
+
+/**
+ * Default package manager: the one that launched the CLI (`npm_config_user_agent`: `pnpm dlx`,
+ * `yarn dlx`, `bunx`, `npx`), else Bun when running on Bun, else npm.
+ */
+export function detectPackageManager(
+  env: Readonly<Record<string, string | undefined>>,
+  runningOnBun: boolean,
+): PackageManager {
+  const agent = env['npm_config_user_agent'] ?? ''
+  const name = agent.split('/')[0]
+  if (name === 'bun' || name === 'npm' || name === 'pnpm' || name === 'yarn') return name
+  return runningOnBun ? 'bun' : 'npm'
+}
+
+/** `bun install`, `npm install`... */
+export function installCommand(pm: PackageManager): readonly [string, ...string[]] {
+  return [pm, 'install']
+}
+
+/** `bun run dev`, `npm run dev`, `pnpm dev`, `yarn dev`. */
+export function runScript(pm: PackageManager, script: string): string {
+  return pm === 'pnpm' || pm === 'yarn' ? `${pm} ${script}` : `${pm} run ${script}`
+}
+
+/** Runs a binary of the project: `npx znight`, `bunx znight`, `pnpm znight`, `yarn znight`. */
+export function execBinary(pm: PackageManager, binary: string): string {
+  switch (pm) {
+    case 'npm':
+      return `npx ${binary}`
+    case 'bun':
+      return `bunx ${binary}`
+    default:
+      return `${pm} ${binary}`
+  }
+}