@defrex/autobuild 0.8.0

package/packages/core/src/cli/installation.ts

@@ -0,0 +1,333 @@
+import { stat, readFile, realpath } from 'node:fs/promises'
+import { join, resolve, sep } from 'node:path'
+import semver from 'semver'
+import { PLUGIN_API_VERSION } from '../plugins/manifest'
+import { defaultDistRoot } from './init'
+
+export interface DistributionIdentity {
+  root: string
+  packageName: string
+  version: string
+  /** Bun records the resolved forge commit in a distribution-local `.bun-tag`. */
+  commit?: string
+  bunTag?: string
+  sourceCheckout: boolean
+  binaryPath: string
+}
+
+export type InstallScope = 'local' | 'global'
+
+/** Where the owning package manager obtained the distribution: a `github:`
+ * forge dependency, or a version range satisfied from the npm registry. */
+export type InstallChannel = 'github' | 'npm'
+
+interface ManagedInstallationBase extends DistributionIdentity {
+  sourceCheckout: false
+  ownerRoot: string
+  ownerManifest: string
+  ownerLock: string
+  /** The owning manifest's direct dependency value, byte for byte. */
+  dependency: string
+  scope: InstallScope
+}
+
+export interface BunForgeInstallation extends ManagedInstallationBase {
+  channel: 'github'
+  owner: string
+  repository: string
+}
+
+export interface NpmRegistryInstallation extends ManagedInstallationBase {
+  channel: 'npm'
+}
+
+export type ManagedInstallation = BunForgeInstallation | NpmRegistryInstallation
+
+export type InstallationInspection =
+  | { kind: 'source'; identity: DistributionIdentity; reason: string }
+  | { kind: 'bun-forge'; installation: BunForgeInstallation }
+  | { kind: 'npm-registry'; installation: NpmRegistryInstallation }
+  | { kind: 'unknown'; identity: DistributionIdentity; reason: string }
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path)
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw error
+  }
+}
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function exactVersion(value: unknown, path: string): string {
+  if (typeof value !== 'string' || semver.valid(value) !== value) {
+    throw new Error(`${path} has an invalid package version`)
+  }
+  return value
+}
+
+function binaryRelativePath(manifest: Record<string, unknown>, path: string): string {
+  const bin = manifest.bin
+  if (typeof bin === 'string' && bin !== '') return bin
+  const entries = object(bin)
+  const ab = entries?.ab
+  if (typeof ab !== 'string' || ab === '') {
+    throw new Error(`${path} does not declare the ab binary`)
+  }
+  return ab
+}
+
+/** Read only distribution-local metadata. This is the complete `ab --version`
+ * path: no cwd, project configuration, package-manager command, or network. */
+export async function readDistributionIdentity(
+  root = defaultDistRoot(),
+): Promise<DistributionIdentity> {
+  const distributionRoot = resolve(root)
+  const packagePath = join(distributionRoot, 'package.json')
+  let manifest: Record<string, unknown>
+  try {
+    manifest = object(JSON.parse(await readFile(packagePath, 'utf8'))) ?? {}
+  } catch (error) {
+    throw new Error(
+      `cannot read installed Autobuild metadata at ${packagePath}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    )
+  }
+  if (typeof manifest.name !== 'string' || manifest.name === '') {
+    throw new Error(`${packagePath} has no package name`)
+  }
+  const binary = binaryRelativePath(manifest, packagePath)
+  const sourceCheckout = await exists(join(distributionRoot, '.git'))
+  let bunTag: string | undefined
+  let commit: string | undefined
+  try {
+    bunTag = (await readFile(join(distributionRoot, '.bun-tag'), 'utf8')).trim()
+    const match = /-([0-9a-f]{7,40})$/i.exec(bunTag)
+    if (match?.[1] !== undefined) commit = match[1]
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+  }
+  return {
+    root: distributionRoot,
+    packageName: manifest.name,
+    version: exactVersion(manifest.version, packagePath),
+    ...(commit === undefined ? {} : { commit }),
+    ...(bunTag === undefined ? {} : { bunTag }),
+    sourceCheckout,
+    binaryPath: resolve(distributionRoot, binary),
+  }
+}
+
+export function formatInstalledVersion(identity: DistributionIdentity): string {
+  return [
+    `autobuild ${identity.version}${identity.commit === undefined ? '' : ` (commit ${identity.commit})`}`,
+    `plugin API ${PLUGIN_API_VERSION}`,
+  ].join('\n')
+}
+
+function ownerRootForPackage(identity: DistributionIdentity): string | undefined {
+  const packageSegments = identity.packageName.split('/')
+  if (packageSegments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    return undefined
+  }
+  const suffix = [sep, 'node_modules', sep, packageSegments.join(sep)].join('')
+  if (!identity.root.endsWith(suffix)) return undefined
+  const owner = identity.root.slice(0, -suffix.length)
+  return owner === '' ? sep : owner
+}
+
+function githubDependency(value: unknown): { owner: string; repository: string } | undefined {
+  if (typeof value !== 'string') return undefined
+  const match = /^github:([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)(?:#([^\s]+))?$/.exec(value)
+  if (match?.[1] === undefined || match[2] === undefined) return undefined
+  return { owner: match[1], repository: match[2] }
+}
+
+/** A registry dependency is a semver range (what `bun add <pkg>@<version>`
+ * writes) that the installed version satisfies. Aliases, tags, URLs, and
+ * `file:`/`link:` specifiers are not registry installs. */
+function registryDependency(value: unknown, installedVersion: string): boolean {
+  if (typeof value !== 'string' || value.trim() === '') return false
+  if (semver.validRange(value) === null) return false
+  return semver.satisfies(installedVersion, value)
+}
+
+async function parseJson(path: string): Promise<Record<string, unknown>> {
+  try {
+    return object(JSON.parse(await readFile(path, 'utf8'))) ?? {}
+  } catch (error) {
+    throw new Error(
+      `${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+}
+
+async function parseJsonc(path: string): Promise<Record<string, unknown>> {
+  try {
+    const value = Bun.JSONC.parse(await readFile(path, 'utf8'))
+    return object(value) ?? {}
+  } catch (error) {
+    throw new Error(
+      `${path} is not valid JSONC: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+}
+
+function lockDependency(lock: Record<string, unknown>, packageName: string): unknown {
+  const workspace = object(object(lock.workspaces)?.[''])
+  return object(workspace?.dependencies)?.[packageName]
+}
+
+function lockPackageRecord(
+  lock: Record<string, unknown>,
+  packageName: string,
+): unknown[] | undefined {
+  const value = object(lock.packages)?.[packageName]
+  return Array.isArray(value) ? value : undefined
+}
+
+async function samePath(left: string, right: string): Promise<boolean> {
+  try {
+    return (await realpath(left)) === (await realpath(right))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw error
+  }
+}
+
+/** Validate Bun's direct install records before permitting mutation. A
+ * `github:` dependency is a forge install whose repository comes from the
+ * owning manifest/lock, never by splitting the ambiguous hyphen-delimited
+ * `.bun-tag`. A semver-range dependency satisfied by the installed version,
+ * whose lock record resolves to that exact registry version, is an npm
+ * registry install. Anything else is a named refusal. */
+export async function inspectInstallation(options: {
+  distRoot?: string
+  globalBin: string
+}): Promise<InstallationInspection> {
+  const identity = await readDistributionIdentity(options.distRoot)
+  if (identity.sourceCheckout) {
+    return {
+      kind: 'source',
+      identity,
+      reason: 'running from a source checkout (.git is present)',
+    }
+  }
+
+  const ownerRoot = ownerRootForPackage(identity)
+  if (ownerRoot === undefined) {
+    return {
+      kind: 'unknown',
+      identity,
+      reason: 'the distribution is not a direct Bun node_modules package',
+    }
+  }
+  const ownerManifest = join(ownerRoot, 'package.json')
+  const ownerLock = join(ownerRoot, 'bun.lock')
+
+  try {
+    const manifest = await parseJson(ownerManifest)
+    const lock = await parseJsonc(ownerLock)
+    const dependency = object(manifest.dependencies)?.[identity.packageName]
+    const repository = githubDependency(dependency)
+    const registry = repository === undefined && registryDependency(dependency, identity.version)
+    if ((repository === undefined && !registry) || typeof dependency !== 'string') {
+      return {
+        kind: 'unknown',
+        identity,
+        reason: `${ownerManifest} does not declare ${identity.packageName} as a direct github: dependency or an npm registry version range satisfied by ${identity.version}`,
+      }
+    }
+    if (lockDependency(lock, identity.packageName) !== dependency) {
+      return {
+        kind: 'unknown',
+        identity,
+        reason: `${ownerLock} does not agree with the direct dependency in ${ownerManifest}`,
+      }
+    }
+    const scope: InstallScope = (await samePath(join(options.globalBin, 'ab'), identity.binaryPath))
+      ? 'global'
+      : 'local'
+    if (repository === undefined) {
+      // Registry provenance: Bun records `<name>@<version>` with an empty
+      // registry marker; a forge, tarball, or workspace resolution differs.
+      const record = lockPackageRecord(lock, identity.packageName)
+      if (
+        record === undefined ||
+        record[0] !== `${identity.packageName}@${identity.version}` ||
+        record[1] !== ''
+      ) {
+        return {
+          kind: 'unknown',
+          identity,
+          reason: `${ownerLock} does not resolve ${identity.packageName} to registry version ${identity.version}`,
+        }
+      }
+      return {
+        kind: 'npm-registry',
+        installation: {
+          ...identity,
+          sourceCheckout: false,
+          channel: 'npm',
+          ownerRoot,
+          ownerManifest,
+          ownerLock,
+          dependency,
+          scope,
+        },
+      }
+    }
+    const expectedTagPrefix = `${repository.owner}-${repository.repository}-`
+    if (
+      identity.bunTag === undefined ||
+      !identity.bunTag.startsWith(expectedTagPrefix) ||
+      identity.commit === undefined
+    ) {
+      return {
+        kind: 'unknown',
+        identity,
+        reason: 'the installed .bun-tag is malformed or contradicts the owning dependency',
+      }
+    }
+    const record = lockPackageRecord(lock, identity.packageName)
+    const resolvedPackage =
+      `${identity.packageName}@github:${repository.owner}/${repository.repository}` +
+      `#${identity.commit}`
+    if (record === undefined || record[0] !== resolvedPackage || record[2] !== identity.bunTag) {
+      return {
+        kind: 'unknown',
+        identity,
+        reason: `${ownerLock} does not contain matching Bun forge provenance`,
+      }
+    }
+
+    return {
+      kind: 'bun-forge',
+      installation: {
+        ...identity,
+        sourceCheckout: false,
+        channel: 'github',
+        ownerRoot,
+        ownerManifest,
+        ownerLock,
+        owner: repository.owner,
+        repository: repository.repository,
+        dependency,
+        scope,
+      },
+    }
+  } catch (error) {
+    return {
+      kind: 'unknown',
+      identity,
+      reason: error instanceof Error ? error.message : String(error),
+    }
+  }
+}

package/packages/core/src/cli/keyboard.ts

@@ -0,0 +1,261 @@
+import type { TerminalInputEvent } from './terminal'
+import {
+  KITTY_KEYBOARD_FLAGS,
+  KITTY_KEYBOARD_MODE,
+  type TerminalModeController,
+} from './terminal-restore'
+
+/** Progressive enhancement flags requested from Kitty-compatible terminals. */
+export { KITTY_KEYBOARD_FLAGS } from './terminal-restore'
+/** Ask for the current progressive keyboard enhancement flags. */
+export const QUERY_KEYBOARD_FLAGS = '\x1b[?u'
+/**
+ * Push disambiguated escape codes (1), alternate keys (4), all keys as escape
+ * codes (8), and associated text (16). Alternate keys are essential: without
+ * them Cyrillic Ctrl-C reports key 1089 and the decoder cannot recognize it.
+ */
+export const PUSH_KEYBOARD_FLAGS = KITTY_KEYBOARD_MODE.enter
+/** Pop exactly the keyboard mode frame pushed by this process. */
+export const POP_KEYBOARD_FLAGS = KITTY_KEYBOARD_MODE.restore
+/**
+ * Primary Device Attributes is not a keyboard command. It follows the
+ * verification query because its guaranteed, ordered reply lets verification
+ * fail deterministically when no keyboard-flags reply arrives.
+ */
+export const DEVICE_ATTRIBUTES_QUERY = '\x1b[c'
+
+/**
+ * Kitty modifiers are `1 + bitfield`; caps and num lock are reported on every
+ * key in report-all-keys mode and must not turn an ordinary key into a chord.
+ */
+export const MODIFIER_LOCK_MASK = 0b1100_0000
+/** Shift and lock bits may still produce text; ctrl/alt/super/hyper/meta may not. */
+const MODIFIER_TEXT_MASK = 0b1100_0001
+/** No decoded numeric parameter can exceed Unicode's seven-digit maximum scalar. */
+export const MAX_CSI_PARAM_DIGITS = 7
+/**
+ * Three 7-digit key fields, two colons, a semicolon, 3-digit modifier, `:1`,
+ * `ESC[` and `u` fit in 32 bytes. Forty therefore covers every Ctrl-C report
+ * while keeping the parallel, non-consuming interrupt watch deliberately tight.
+ */
+export const INTERRUPT_WATCH_MAX = 40
+
+/** ECMA-48 parameter/intermediate bytes that may extend a CSI run. */
+export function isCsiParameterByte(ch: string): boolean {
+  if (ch.length !== 1) return false
+  const code = ch.charCodeAt(0)
+  return code >= 0x20 && code <= 0x3f
+}
+
+/**
+ * CSI sequences end at a byte in 0x40-0x7e. This includes every ASCII letter,
+ * so one ordinary letter always terminates an accumulating or draining run.
+ */
+export function endsCsi(sequence: string): boolean {
+  if (sequence.length <= 2) return false
+  const code = sequence.charCodeAt(sequence.length - 1)
+  return code >= 0x40 && code <= 0x7e
+}
+
+/** Decode a `1 + bitfield` modifier parameter into submit-versus-newline. */
+function modifiedReturn(mod: number | undefined): TerminalInputEvent {
+  if (mod === undefined) return { type: 'enter' }
+  const bits = Math.max(0, mod - 1)
+  return (bits & ~MODIFIER_LOCK_MASK) === 0 ? { type: 'enter' } : { type: 'newline' }
+}
+
+function parseParam(value: string | undefined): number | undefined {
+  if (value === undefined || value === '') return undefined
+  const parsed = Number.parseInt(value, 10)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+function isTextCodePoint(code: number | undefined): code is number {
+  return (
+    code !== undefined &&
+    code >= 0x20 &&
+    code <= 0x10ffff &&
+    !(code >= 0x7f && code <= 0x9f) &&
+    !(code >= 0xd800 && code <= 0xdfff)
+  )
+}
+
+/** Kitty reserves U+E000-U+F8FF in the key-code field for functional keys. */
+function isFunctionalKeyCode(code: number): boolean {
+  return code >= 57344 && code <= 63743
+}
+
+export type CsiReport =
+  | { kind: 'input'; event: TerminalInputEvent }
+  | { kind: 'keyboard-flags'; flags: number }
+  | { kind: 'device-attributes' }
+  | { kind: 'ignored' }
+
+const ignored = (): CsiReport => ({ kind: 'ignored' })
+const input = (event: TerminalInputEvent): CsiReport => ({ kind: 'input', event })
+
+/** Decode one complete CSI sequence, whether legacy, Kitty CSI-u, or a reply. */
+export function decodeCsi(sequence: string): CsiReport {
+  if (!sequence.startsWith('\x1b[') || !endsCsi(sequence)) return ignored()
+  const final = sequence.at(-1)
+  const body = sequence.slice(2, -1)
+
+  if (final === 'u' && body.startsWith('?')) {
+    return { kind: 'keyboard-flags', flags: parseParam(body.slice(1)) ?? 0 }
+  }
+  if (final === 'c' && body.startsWith('?')) return { kind: 'device-attributes' }
+
+  const params = body.split(';')
+  if (final === 'u') {
+    const [primaryRaw, shiftedRaw, baseRaw] = (params[0] ?? '').split(':')
+    const primary = parseParam(primaryRaw)
+    const shifted = parseParam(shiftedRaw)
+    const base = parseParam(baseRaw)
+    const [modRaw, eventRaw] = (params[1] ?? '').split(':')
+    const mod = parseParam(modRaw)
+    const event = parseParam(eventRaw) ?? 1
+    if (event !== 1 && event !== 2) return ignored()
+
+    if (primary === 13) return input(modifiedReturn(mod))
+    if (primary === 27) return input({ type: 'escape' })
+    if (primary === 127 || primary === 8) return input({ type: 'backspace' })
+    if (primary === 9) return ignored()
+
+    const bits = Math.max(0, (mod ?? 1) - 1)
+    if ((bits & 0b100) !== 0) {
+      const chordKeys = base === undefined ? [primary] : [primary, base]
+      // The Dvorak physical-QWERTY-C collision contains both 106 and 99. The
+      // produced `j` wins: a newline is recoverable while an interrupt is not.
+      if (chordKeys.includes(106)) return input({ type: 'newline' })
+      if (chordKeys.includes(99)) return input({ type: 'interrupt' })
+    }
+
+    if ((bits & ~MODIFIER_TEXT_MASK) !== 0) return ignored()
+
+    if (params[2] !== undefined) {
+      const codes = params[2].split(':').map(parseParam)
+      if (codes.length === 0 || !codes.every(isTextCodePoint)) return ignored()
+      // Do not spread: valid associated text is unbounded and a large argument
+      // list eventually throws. Folding remains safe for long IME commits.
+      let text = ''
+      for (const code of codes) text += String.fromCodePoint(code)
+      return input({ type: 'text', text })
+    }
+
+    const shiftedOnly = (bits & ~MODIFIER_LOCK_MASK) === 0b1
+    // The base-layout subfield names a physical position, not text in the
+    // operator's layout, and is intentionally never a printable fallback.
+    const code = shiftedOnly && shifted !== undefined ? shifted : primary
+    if (!isTextCodePoint(code) || isFunctionalKeyCode(code)) return ignored()
+    const text = String.fromCodePoint(code)
+    // Best effort for the bounded pre-verification window. Associated text is
+    // required after verification because this is wrong for shifted layouts.
+    return input({
+      type: 'text',
+      text: shiftedOnly && shifted === undefined ? text.toUpperCase() : text,
+    })
+  }
+
+  if (final === '~') {
+    if (params[0] === '27' && parseParam(params[2]) === 13) {
+      return input(modifiedReturn(parseParam(params[1])))
+    }
+    if (params[0] === '1' || params[0] === '7') return input({ type: 'home' })
+    if (params[0] === '4' || params[0] === '8') return input({ type: 'end' })
+    return ignored()
+  }
+
+  type Motion = Exclude<TerminalInputEvent['type'], 'text' | 'paste'>
+  const motions: Record<string, Motion | undefined> = {
+    A: 'up',
+    B: 'down',
+    C: 'right',
+    D: 'left',
+    H: 'home',
+    F: 'end',
+  }
+  const motion = final === undefined ? undefined : motions[final]
+  return motion === undefined ? ignored() : input({ type: motion })
+}
+
+export function isInterruptSequence(sequence: string): boolean {
+  const report = decodeCsi(sequence)
+  return report.kind === 'input' && report.event.type === 'interrupt'
+}
+
+type KeyboardPhase =
+  | 'idle'
+  | 'probing'
+  | 'supported'
+  | 'verifying'
+  | 'active'
+  | 'declined'
+  | 'finished'
+
+export interface KeyboardProtocol {
+  query(): void
+  reported(flags: number): void
+  deviceAttributes(): void
+  screenEntered(): void
+  screenLeaving(): void
+  readonly pushed: boolean
+}
+
+/** Negotiate and balance the per-screen Kitty keyboard mode stack. */
+export function createKeyboardProtocol(
+  write: (chunk: string) => void,
+  modes: TerminalModeController,
+): KeyboardProtocol {
+  let phase: KeyboardPhase = 'idle'
+  let onScreen = false
+
+  const push = (): void => {
+    if (phase !== 'supported' || !onScreen) return
+    phase = 'verifying'
+    // The ledger arms before the push write. Queries do not alter terminal
+    // state and therefore remain ordinary output after the declared enter.
+    modes.enter(KITTY_KEYBOARD_MODE)
+    write(QUERY_KEYBOARD_FLAGS + DEVICE_ATTRIBUTES_QUERY)
+  }
+
+  return {
+    query(): void {
+      if (phase !== 'idle') return
+      write(QUERY_KEYBOARD_FLAGS)
+      phase = 'probing'
+    },
+    reported(flags: number): void {
+      if (phase === 'probing') {
+        phase = 'supported'
+        push()
+        return
+      }
+      if (phase !== 'verifying') return
+      if ((flags & KITTY_KEYBOARD_FLAGS) === KITTY_KEYBOARD_FLAGS) {
+        phase = 'active'
+      } else {
+        modes.leave(KITTY_KEYBOARD_MODE)
+        phase = 'declined'
+      }
+    },
+    deviceAttributes(): void {
+      if (phase !== 'verifying') return
+      modes.leave(KITTY_KEYBOARD_MODE)
+      phase = 'declined'
+    },
+    screenEntered(): void {
+      if (phase === 'finished') return
+      onScreen = true
+      push()
+    },
+    screenLeaving(): void {
+      if (phase === 'finished') return
+      if (phase === 'verifying' || phase === 'active') modes.leave(KITTY_KEYBOARD_MODE)
+      phase = 'finished'
+      onScreen = false
+    },
+    get pushed(): boolean {
+      return phase === 'verifying' || phase === 'active'
+    },
+  }
+}