@toolkit-cli/toolkode 1.3.7

package/src/util/flock.ts

@@ -0,0 +1,333 @@
+import path from "path"
+import os from "os"
+import { randomBytes, randomUUID } from "crypto"
+import { mkdir, readFile, rm, stat, utimes, writeFile } from "fs/promises"
+import { Global } from "@/global"
+import { Hash } from "@/util/hash"
+
+export namespace Flock {
+  const root = path.join(Global.Path.state, "locks")
+  // Defaults for callers that do not provide timing options.
+  const defaultOpts = {
+    staleMs: 60_000,
+    timeoutMs: 5 * 60_000,
+    baseDelayMs: 100,
+    maxDelayMs: 2_000,
+  }
+
+  export interface WaitEvent {
+    key: string
+    attempt: number
+    delay: number
+    waited: number
+  }
+
+  export type Wait = (input: WaitEvent) => void | Promise<void>
+
+  export interface Options {
+    dir?: string
+    signal?: AbortSignal
+    staleMs?: number
+    timeoutMs?: number
+    baseDelayMs?: number
+    maxDelayMs?: number
+    onWait?: Wait
+  }
+
+  type Opts = {
+    staleMs: number
+    timeoutMs: number
+    baseDelayMs: number
+    maxDelayMs: number
+  }
+
+  type Owned = {
+    acquired: true
+    startHeartbeat: (intervalMs?: number) => void
+    release: () => Promise<void>
+  }
+
+  export interface Lease {
+    release: () => Promise<void>
+    [Symbol.asyncDispose]: () => Promise<void>
+  }
+
+  function code(err: unknown) {
+    if (typeof err !== "object" || err === null || !("code" in err)) return
+    const value = err.code
+    if (typeof value !== "string") return
+    return value
+  }
+
+  function sleep(ms: number, signal?: AbortSignal) {
+    return new Promise<void>((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(signal.reason ?? new Error("Aborted"))
+        return
+      }
+
+      let timer: NodeJS.Timeout | undefined
+
+      const done = () => {
+        signal?.removeEventListener("abort", abort)
+        resolve()
+      }
+
+      const abort = () => {
+        if (timer) {
+          clearTimeout(timer)
+        }
+        signal?.removeEventListener("abort", abort)
+        reject(signal?.reason ?? new Error("Aborted"))
+      }
+
+      signal?.addEventListener("abort", abort, { once: true })
+      timer = setTimeout(done, ms)
+    })
+  }
+
+  function jitter(ms: number) {
+    const j = Math.floor(ms * 0.3)
+    const d = Math.floor(Math.random() * (2 * j + 1)) - j
+    return Math.max(0, ms + d)
+  }
+
+  function mono() {
+    return performance.now()
+  }
+
+  function wall() {
+    return performance.timeOrigin + mono()
+  }
+
+  async function stats(file: string) {
+    try {
+      return await stat(file)
+    } catch (err) {
+      const errCode = code(err)
+      if (errCode === "ENOENT" || errCode === "ENOTDIR") return
+      throw err
+    }
+  }
+
+  async function stale(lockDir: string, heartbeatPath: string, metaPath: string, staleMs: number) {
+    // Stale detection allows automatic recovery after crashed owners.
+    const now = wall()
+    const heartbeat = await stats(heartbeatPath)
+    if (heartbeat) {
+      return now - heartbeat.mtimeMs > staleMs
+    }
+
+    const meta = await stats(metaPath)
+    if (meta) {
+      return now - meta.mtimeMs > staleMs
+    }
+
+    const dir = await stats(lockDir)
+    if (!dir) {
+      return false
+    }
+
+    return now - dir.mtimeMs > staleMs
+  }
+
+  async function tryAcquireLockDir(lockDir: string, opts: Opts): Promise<Owned | { acquired: false }> {
+    const token = randomUUID?.() ?? randomBytes(16).toString("hex")
+    const metaPath = path.join(lockDir, "meta.json")
+    const heartbeatPath = path.join(lockDir, "heartbeat")
+
+    try {
+      await mkdir(lockDir, { mode: 0o700 })
+    } catch (err) {
+      if (code(err) !== "EEXIST") {
+        throw err
+      }
+
+      if (!(await stale(lockDir, heartbeatPath, metaPath, opts.staleMs))) {
+        return { acquired: false }
+      }
+
+      const breakerPath = lockDir + ".breaker"
+      try {
+        await mkdir(breakerPath, { mode: 0o700 })
+      } catch (claimErr) {
+        const errCode = code(claimErr)
+        if (errCode === "EEXIST") {
+          const breaker = await stats(breakerPath)
+          if (breaker && wall() - breaker.mtimeMs > opts.staleMs) {
+            await rm(breakerPath, { recursive: true, force: true }).catch(() => undefined)
+          }
+          return { acquired: false }
+        }
+
+        if (errCode === "ENOENT" || errCode === "ENOTDIR") {
+          return { acquired: false }
+        }
+
+        throw claimErr
+      }
+
+      try {
+        // Breaker ownership ensures only one contender performs stale cleanup.
+        if (!(await stale(lockDir, heartbeatPath, metaPath, opts.staleMs))) {
+          return { acquired: false }
+        }
+
+        await rm(lockDir, { recursive: true, force: true })
+
+        try {
+          await mkdir(lockDir, { mode: 0o700 })
+        } catch (retryErr) {
+          const errCode = code(retryErr)
+          if (errCode === "EEXIST" || errCode === "ENOTEMPTY") {
+            return { acquired: false }
+          }
+          throw retryErr
+        }
+      } finally {
+        await rm(breakerPath, { recursive: true, force: true }).catch(() => undefined)
+      }
+    }
+
+    const meta = {
+      token,
+      pid: process.pid,
+      hostname: os.hostname(),
+      createdAt: new Date().toISOString(),
+    }
+
+    await writeFile(heartbeatPath, "", { flag: "wx" }).catch(async () => {
+      await rm(lockDir, { recursive: true, force: true })
+      throw new Error("Lock acquired but heartbeat already existed (possible compromise).")
+    })
+
+    await writeFile(metaPath, JSON.stringify(meta, null, 2), { flag: "wx" }).catch(async () => {
+      await rm(lockDir, { recursive: true, force: true })
+      throw new Error("Lock acquired but meta.json already existed (possible compromise).")
+    })
+
+    let timer: NodeJS.Timeout | undefined
+
+    const startHeartbeat = (intervalMs = Math.max(100, Math.floor(opts.staleMs / 3))) => {
+      if (timer) return
+      // Heartbeat prevents long critical sections from being evicted as stale.
+      timer = setInterval(() => {
+        const t = new Date()
+        void utimes(heartbeatPath, t, t).catch(() => undefined)
+      }, intervalMs)
+      timer.unref?.()
+    }
+
+    const release = async () => {
+      if (timer) {
+        clearInterval(timer)
+        timer = undefined
+      }
+
+      const current = await readFile(metaPath, "utf8")
+        .then((raw) => {
+          const parsed = JSON.parse(raw)
+          if (!parsed || typeof parsed !== "object") return {}
+          return {
+            token: "token" in parsed && typeof parsed.token === "string" ? parsed.token : undefined,
+          }
+        })
+        .catch((err) => {
+          const errCode = code(err)
+          if (errCode === "ENOENT" || errCode === "ENOTDIR") {
+            throw new Error("Refusing to release: lock is compromised (metadata missing).")
+          }
+          if (err instanceof SyntaxError) {
+            throw new Error("Refusing to release: lock is compromised (metadata invalid).")
+          }
+          throw err
+        })
+      // Token check prevents deleting a lock that was re-acquired by another process.
+      if (current.token !== token) {
+        throw new Error("Refusing to release: lock token mismatch (not the owner).")
+      }
+
+      await rm(lockDir, { recursive: true, force: true })
+    }
+
+    return {
+      acquired: true,
+      startHeartbeat,
+      release,
+    }
+  }
+
+  async function acquireLockDir(
+    lockDir: string,
+    input: { key: string; onWait?: Wait; signal?: AbortSignal },
+    opts: Opts,
+  ) {
+    const stop = mono() + opts.timeoutMs
+    let attempt = 0
+    let waited = 0
+    let delay = opts.baseDelayMs
+
+    while (true) {
+      input.signal?.throwIfAborted()
+
+      const res = await tryAcquireLockDir(lockDir, opts)
+      if (res.acquired) {
+        return res
+      }
+
+      if (mono() > stop) {
+        throw new Error(`Timed out waiting for lock: ${input.key}`)
+      }
+
+      attempt += 1
+      const ms = jitter(delay)
+      await input.onWait?.({
+        key: input.key,
+        attempt,
+        delay: ms,
+        waited,
+      })
+      await sleep(ms, input.signal)
+      waited += ms
+      delay = Math.min(opts.maxDelayMs, Math.floor(delay * 1.7))
+    }
+  }
+
+  export async function acquire(key: string, input: Options = {}): Promise<Lease> {
+    input.signal?.throwIfAborted()
+    const cfg: Opts = {
+      staleMs: input.staleMs ?? defaultOpts.staleMs,
+      timeoutMs: input.timeoutMs ?? defaultOpts.timeoutMs,
+      baseDelayMs: input.baseDelayMs ?? defaultOpts.baseDelayMs,
+      maxDelayMs: input.maxDelayMs ?? defaultOpts.maxDelayMs,
+    }
+    const dir = input.dir ?? root
+
+    await mkdir(dir, { recursive: true })
+    const lockfile = path.join(dir, Hash.fast(key) + ".lock")
+    const lock = await acquireLockDir(
+      lockfile,
+      {
+        key,
+        onWait: input.onWait,
+        signal: input.signal,
+      },
+      cfg,
+    )
+    lock.startHeartbeat()
+
+    const release = () => lock.release()
+    return {
+      release,
+      [Symbol.asyncDispose]() {
+        return release()
+      },
+    }
+  }
+
+  export async function withLock<T>(key: string, fn: () => Promise<T>, input: Options = {}) {
+    await using _ = await acquire(key, input)
+    input.signal?.throwIfAborted()
+    return await fn()
+  }
+}

package/src/util/fn.ts

@@ -0,0 +1,21 @@
+import { z } from "zod"
+
+export function fn<T extends z.ZodType, Result>(schema: T, cb: (input: z.infer<T>) => Result) {
+  const result = (input: z.infer<T>) => {
+    let parsed
+    try {
+      parsed = schema.parse(input)
+    } catch (e) {
+      console.trace("schema validation failure stack trace:")
+      if (e instanceof z.ZodError) {
+        console.error("schema validation issues:", JSON.stringify(e.issues, null, 2))
+      }
+      throw e
+    }
+
+    return cb(parsed)
+  }
+  result.force = (input: z.infer<T>) => cb(input)
+  result.schema = schema
+  return result
+}

package/src/util/format.ts

@@ -0,0 +1,20 @@
+export function formatDuration(secs: number) {
+  if (secs <= 0) return ""
+  if (secs < 60) return `${secs}s`
+  if (secs < 3600) {
+    const mins = Math.floor(secs / 60)
+    const remaining = secs % 60
+    return remaining > 0 ? `${mins}m ${remaining}s` : `${mins}m`
+  }
+  if (secs < 86400) {
+    const hours = Math.floor(secs / 3600)
+    const remaining = Math.floor((secs % 3600) / 60)
+    return remaining > 0 ? `${hours}h ${remaining}m` : `${hours}h`
+  }
+  if (secs < 604800) {
+    const days = Math.floor(secs / 86400)
+    return days === 1 ? "~1 day" : `~${days} days`
+  }
+  const weeks = Math.floor(secs / 604800)
+  return weeks === 1 ? "~1 week" : `~${weeks} weeks`
+}

package/src/util/git.ts

@@ -0,0 +1,35 @@
+import { Process } from "./process"
+
+export interface GitResult {
+  exitCode: number
+  text(): string
+  stdout: Buffer
+  stderr: Buffer
+}
+
+/**
+ * Run a git command.
+ *
+ * Uses Process helpers with stdin ignored to avoid protocol pipe inheritance
+ * issues in embedded/client environments.
+ */
+export async function git(args: string[], opts: { cwd: string; env?: Record<string, string> }): Promise<GitResult> {
+  return Process.run(["git", ...args], {
+    cwd: opts.cwd,
+    env: opts.env,
+    stdin: "ignore",
+    nothrow: true,
+  })
+    .then((result) => ({
+      exitCode: result.code,
+      text: () => result.stdout.toString(),
+      stdout: result.stdout,
+      stderr: result.stderr,
+    }))
+    .catch((error) => ({
+      exitCode: 1,
+      text: () => "",
+      stdout: Buffer.alloc(0),
+      stderr: Buffer.from(error instanceof Error ? error.message : String(error)),
+    }))
+}

package/src/util/glob.ts

@@ -0,0 +1,34 @@
+import { glob, globSync, type GlobOptions } from "glob"
+import { minimatch } from "minimatch"
+
+export namespace Glob {
+  export interface Options {
+    cwd?: string
+    absolute?: boolean
+    include?: "file" | "all"
+    dot?: boolean
+    symlink?: boolean
+  }
+
+  function toGlobOptions(options: Options): GlobOptions {
+    return {
+      cwd: options.cwd,
+      absolute: options.absolute,
+      dot: options.dot,
+      follow: options.symlink ?? false,
+      nodir: options.include !== "all",
+    }
+  }
+
+  export async function scan(pattern: string, options: Options = {}): Promise<string[]> {
+    return glob(pattern, toGlobOptions(options)) as Promise<string[]>
+  }
+
+  export function scanSync(pattern: string, options: Options = {}): string[] {
+    return globSync(pattern, toGlobOptions(options)) as string[]
+  }
+
+  export function match(pattern: string, filepath: string): boolean {
+    return minimatch(filepath, pattern, { dot: true })
+  }
+}

package/src/util/hash.ts

@@ -0,0 +1,7 @@
+import { createHash } from "crypto"
+
+export namespace Hash {
+  export function fast(input: string | Buffer): string {
+    return createHash("sha1").update(input).digest("hex")
+  }
+}

package/src/util/iife.ts

@@ -0,0 +1,3 @@
+export function iife<T>(fn: () => T) {
+  return fn()
+}

package/src/util/keybind.ts

@@ -0,0 +1,103 @@
+import { isDeepEqual } from "remeda"
+import type { ParsedKey } from "@opentui/core"
+
+export namespace Keybind {
+  /**
+   * Keybind info derived from OpenTUI's ParsedKey with our custom `leader` field.
+   * This ensures type compatibility and catches missing fields at compile time.
+   */
+  export type Info = Pick<ParsedKey, "name" | "ctrl" | "meta" | "shift" | "super"> & {
+    leader: boolean // our custom field
+  }
+
+  export function match(a: Info | undefined, b: Info): boolean {
+    if (!a) return false
+    const normalizedA = { ...a, super: a.super ?? false }
+    const normalizedB = { ...b, super: b.super ?? false }
+    return isDeepEqual(normalizedA, normalizedB)
+  }
+
+  /**
+   * Convert OpenTUI's ParsedKey to our Keybind.Info format.
+   * This helper ensures all required fields are present and avoids manual object creation.
+   */
+  export function fromParsedKey(key: ParsedKey, leader = false): Info {
+    return {
+      name: key.name === " " ? "space" : key.name,
+      ctrl: key.ctrl,
+      meta: key.meta,
+      shift: key.shift,
+      super: key.super ?? false,
+      leader,
+    }
+  }
+
+  export function toString(info: Info | undefined): string {
+    if (!info) return ""
+    const parts: string[] = []
+
+    if (info.ctrl) parts.push("ctrl")
+    if (info.meta) parts.push("alt")
+    if (info.super) parts.push("super")
+    if (info.shift) parts.push("shift")
+    if (info.name) {
+      if (info.name === "delete") parts.push("del")
+      else parts.push(info.name)
+    }
+
+    let result = parts.join("+")
+
+    if (info.leader) {
+      result = result ? `<leader> ${result}` : `<leader>`
+    }
+
+    return result
+  }
+
+  export function parse(key: string): Info[] {
+    if (key === "none") return []
+
+    return key.split(",").map((combo) => {
+      // Handle <leader> syntax by replacing with leader+
+      const normalized = combo.replace(/<leader>/g, "leader+")
+      const parts = normalized.toLowerCase().split("+")
+      const info: Info = {
+        ctrl: false,
+        meta: false,
+        shift: false,
+        leader: false,
+        name: "",
+      }
+
+      for (const part of parts) {
+        switch (part) {
+          case "ctrl":
+            info.ctrl = true
+            break
+          case "alt":
+          case "meta":
+          case "option":
+            info.meta = true
+            break
+          case "super":
+            info.super = true
+            break
+          case "shift":
+            info.shift = true
+            break
+          case "leader":
+            info.leader = true
+            break
+          case "esc":
+            info.name = "escape"
+            break
+          default:
+            info.name = part
+            break
+        }
+      }
+
+      return info
+    })
+  }
+}

package/src/util/lazy.ts

@@ -0,0 +1,23 @@
+export function lazy<T>(fn: () => T) {
+  let value: T | undefined
+  let loaded = false
+
+  const result = (): T => {
+    if (loaded) return value as T
+    try {
+      value = fn()
+      loaded = true
+      return value as T
+    } catch (e) {
+      // Don't mark as loaded if initialization failed
+      throw e
+    }
+  }
+
+  result.reset = () => {
+    loaded = false
+    value = undefined
+  }
+
+  return result
+}

package/src/util/locale.ts

@@ -0,0 +1,81 @@
+export namespace Locale {
+  export function titlecase(str: string) {
+    return str.replace(/\b\w/g, (c) => c.toUpperCase())
+  }
+
+  export function time(input: number): string {
+    const date = new Date(input)
+    return date.toLocaleTimeString(undefined, { timeStyle: "short" })
+  }
+
+  export function datetime(input: number): string {
+    const date = new Date(input)
+    const localTime = time(input)
+    const localDate = date.toLocaleDateString()
+    return `${localTime} · ${localDate}`
+  }
+
+  export function todayTimeOrDateTime(input: number): string {
+    const date = new Date(input)
+    const now = new Date()
+    const isToday =
+      date.getFullYear() === now.getFullYear() && date.getMonth() === now.getMonth() && date.getDate() === now.getDate()
+
+    if (isToday) {
+      return time(input)
+    } else {
+      return datetime(input)
+    }
+  }
+
+  export function number(num: number): string {
+    if (num >= 1000000) {
+      return (num / 1000000).toFixed(1) + "M"
+    } else if (num >= 1000) {
+      return (num / 1000).toFixed(1) + "K"
+    }
+    return num.toString()
+  }
+
+  export function duration(input: number) {
+    if (input < 1000) {
+      return `${input}ms`
+    }
+    if (input < 60000) {
+      return `${(input / 1000).toFixed(1)}s`
+    }
+    if (input < 3600000) {
+      const minutes = Math.floor(input / 60000)
+      const seconds = Math.floor((input % 60000) / 1000)
+      return `${minutes}m ${seconds}s`
+    }
+    if (input < 86400000) {
+      const hours = Math.floor(input / 3600000)
+      const minutes = Math.floor((input % 3600000) / 60000)
+      return `${hours}h ${minutes}m`
+    }
+    const hours = Math.floor(input / 3600000)
+    const days = Math.floor((input % 3600000) / 86400000)
+    return `${days}d ${hours}h`
+  }
+
+  export function truncate(str: string, len: number): string {
+    if (str.length <= len) return str
+    return str.slice(0, len - 1) + "…"
+  }
+
+  export function truncateMiddle(str: string, maxLength: number = 35): string {
+    if (str.length <= maxLength) return str
+
+    const ellipsis = "…"
+    const keepStart = Math.ceil((maxLength - ellipsis.length) / 2)
+    const keepEnd = Math.floor((maxLength - ellipsis.length) / 2)
+
+    return str.slice(0, keepStart) + ellipsis + str.slice(-keepEnd)
+  }
+
+  export function pluralize(count: number, singular: string, plural: string): string {
+    const template = count === 1 ? singular : plural
+    return template.replace("{}", count.toString())
+  }
+}