nikcli 0.0.6

package/src/tool/write.txt

@@ -0,0 +1,8 @@
+Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.

package/src/util/archive.ts

@@ -0,0 +1,16 @@
+import { $ } from "bun"
+import path from "path"
+
+export namespace Archive {
+  export async function extractZip(zipPath: string, destDir: string) {
+    if (process.platform === "win32") {
+      const winZipPath = path.resolve(zipPath)
+      const winDestDir = path.resolve(destDir)
+      // $global:ProgressPreference suppresses PowerShell's blue progress bar popup
+      const cmd = `$global:ProgressPreference = 'SilentlyContinue'; Expand-Archive -Path '${winZipPath}' -DestinationPath '${winDestDir}' -Force`
+      await $`powershell -NoProfile -NonInteractive -Command ${cmd}`.quiet()
+    } else {
+      await $`unzip -o -q ${zipPath} -d ${destDir}`.quiet()
+    }
+  }
+}

package/src/util/color.ts

@@ -0,0 +1,19 @@
+export namespace Color {
+  export function isValidHex(hex?: string): hex is string {
+    if (!hex) return false
+    return /^#[0-9a-fA-F]{6}$/.test(hex)
+  }
+
+  export function hexToRgb(hex: string): { r: number; g: number; b: number } {
+    const r = parseInt(hex.slice(1, 3), 16)
+    const g = parseInt(hex.slice(3, 5), 16)
+    const b = parseInt(hex.slice(5, 7), 16)
+    return { r, g, b }
+  }
+
+  export function hexToAnsiBold(hex?: string): string | undefined {
+    if (!isValidHex(hex)) return undefined
+    const { r, g, b } = hexToRgb(hex)
+    return `\x1b[38;2;${r};${g};${b}m\x1b[1m`
+  }
+}

package/src/util/context.ts

@@ -0,0 +1,25 @@
+import { AsyncLocalStorage } from "async_hooks"
+
+export namespace Context {
+  export class NotFound extends Error {
+    constructor(public override readonly name: string) {
+      super(`No context found for ${name}`)
+    }
+  }
+
+  export function create<T>(name: string) {
+    const storage = new AsyncLocalStorage<T>()
+    return {
+      use() {
+        const result = storage.getStore()
+        if (!result) {
+          throw new NotFound(name)
+        }
+        return result
+      },
+      provide<R>(value: T, fn: () => R) {
+        return storage.run(value, fn)
+      },
+    }
+  }
+}

package/src/util/defer.ts

@@ -0,0 +1,12 @@
+export function defer<T extends () => void | Promise<void>>(
+  fn: T,
+): T extends () => Promise<void> ? { [Symbol.asyncDispose]: () => Promise<void> } : { [Symbol.dispose]: () => void } {
+  return {
+    [Symbol.dispose]() {
+      fn()
+    },
+    [Symbol.asyncDispose]() {
+      return Promise.resolve(fn())
+    },
+  } as any
+}

package/src/util/error.ts

@@ -0,0 +1,77 @@
+import { isRecord } from "./record"
+
+export function errorFormat(error: unknown): string {
+  if (error instanceof Error) {
+    return error.stack ?? `${error.name}: ${error.message}`
+  }
+
+  if (typeof error === "object" && error !== null) {
+    try {
+      return JSON.stringify(error, null, 2)
+    } catch {
+      return "Unexpected error (unserializable)"
+    }
+  }
+
+  return String(error)
+}
+
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    if (error.message) return error.message
+    if (error.name) return error.name
+  }
+
+  if (isRecord(error) && typeof error.message === "string" && error.message) {
+    return error.message
+  }
+
+  const text = String(error)
+  if (text && text !== "[object Object]") return text
+
+  const formatted = errorFormat(error)
+  if (formatted && formatted !== "{}") return formatted
+  return "unknown error"
+}
+
+export function errorData(error: unknown) {
+  if (error instanceof Error) {
+    return {
+      type: error.name,
+      message: errorMessage(error),
+      stack: error.stack,
+      cause: error.cause === undefined ? undefined : errorFormat(error.cause),
+      formatted: errorFormatted(error),
+    }
+  }
+
+  if (!isRecord(error)) {
+    return {
+      type: typeof error,
+      message: errorMessage(error),
+      formatted: errorFormatted(error),
+    }
+  }
+
+  const data = Object.getOwnPropertyNames(error).reduce<Record<string, unknown>>((acc, key) => {
+    const value = error[key]
+    if (value === undefined) return acc
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      acc[key] = value
+      return acc
+    }
+    acc[key] = value instanceof Error ? value.message : String(value)
+    return acc
+  }, {})
+
+  if (typeof data.message !== "string") data.message = errorMessage(error)
+  if (typeof data.type !== "string") data.type = (error as any).constructor?.name
+  data.formatted = errorFormatted(error)
+  return data
+}
+
+function errorFormatted(error: unknown) {
+  const formatted = errorFormat(error)
+  if (formatted !== "{}") return formatted
+  return String(error)
+}

package/src/util/eventloop.ts

@@ -0,0 +1,20 @@
+import { Log } from "./log"
+
+export namespace EventLoop {
+  export async function wait() {
+    return new Promise<void>((resolve) => {
+      const check = () => {
+        const active = [...(process as any)._getActiveHandles(), ...(process as any)._getActiveRequests()]
+        Log.Default.info("eventloop", {
+          active,
+        })
+        if ((process as any)._getActiveHandles().length === 0 && (process as any)._getActiveRequests().length === 0) {
+          resolve()
+        } else {
+          setImmediate(check)
+        }
+      }
+      check()
+    })
+  }
+}

package/src/util/filesystem.ts

@@ -0,0 +1,125 @@
+import { realpathSync, statSync } from "fs"
+import { dirname, join, relative, resolve as pathResolve } from "path"
+import { mkdir } from "fs/promises"
+
+export namespace Filesystem {
+  export function stat(p: string): import("fs").Stats | undefined {
+    try {
+      return statSync(p)
+    } catch {
+      return undefined
+    }
+  }
+
+  export async function readJson<T>(p: string): Promise<T> {
+    return Bun.file(p).json() as Promise<T>
+  }
+
+  export async function writeJson(p: string, data: unknown): Promise<void> {
+    await mkdir(dirname(p), { recursive: true })
+    await Bun.write(p, JSON.stringify(data, null, 2))
+  }
+
+  export async function readText(p: string): Promise<string> {
+    return Bun.file(p).text()
+  }
+
+  export async function write(p: string, text: string | Buffer): Promise<void> {
+    await mkdir(dirname(p), { recursive: true })
+    await Bun.write(p, text)
+  }
+
+  export function resolve(p: string): string {
+    return pathResolve(p)
+  }
+
+
+  export const exists = (p: string) =>
+    Bun.file(p)
+      .stat()
+      .then(() => true)
+      .catch(() => false)
+
+  export const isDir = (p: string) =>
+    Bun.file(p)
+      .stat()
+      .then((s) => s.isDirectory())
+      .catch(() => false)
+  /**
+   * On Windows, normalize a path to its canonical casing using the filesystem.
+   * This is needed because Windows paths are case-insensitive but LSP servers
+   * may return paths with different casing than what we send them.
+   */
+  export function normalizePath(p: string): string {
+    if (process.platform !== "win32") return p
+    try {
+      return realpathSync.native(p)
+    } catch {
+      return p
+    }
+  }
+  export function overlaps(a: string, b: string) {
+    const relA = relative(a, b)
+    const relB = relative(b, a)
+    return !relA || !relA.startsWith("..") || !relB || !relB.startsWith("..")
+  }
+
+  export function contains(parent: string, child: string) {
+    return !relative(parent, child).startsWith("..")
+  }
+
+  export async function findUp(target: string, start: string, stop?: string) {
+    let current = start
+    const result = []
+    while (true) {
+      const search = join(current, target)
+      if (await exists(search)) result.push(search)
+      if (stop === current) break
+      const parent = dirname(current)
+      if (parent === current) break
+      current = parent
+    }
+    return result
+  }
+
+  export async function* up(options: { targets: string[]; start: string; stop?: string }) {
+    const { targets, start, stop } = options
+    let current = start
+    while (true) {
+      for (const target of targets) {
+        const search = join(current, target)
+        if (await exists(search)) yield search
+      }
+      if (stop === current) break
+      const parent = dirname(current)
+      if (parent === current) break
+      current = parent
+    }
+  }
+
+  export async function globUp(pattern: string, start: string, stop?: string) {
+    let current = start
+    const result = []
+    while (true) {
+      try {
+        const glob = new Bun.Glob(pattern)
+        for await (const match of glob.scan({
+          cwd: current,
+          absolute: true,
+          onlyFiles: true,
+          followSymlinks: true,
+          dot: true,
+        })) {
+          result.push(match)
+        }
+      } catch {
+        // Skip invalid glob patterns
+      }
+      if (stop === current) break
+      const parent = dirname(current)
+      if (parent === current) break
+      current = parent
+    }
+    return result
+  }
+}

package/src/util/flock.ts

@@ -0,0 +1,329 @@
+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) {
+    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 {
+        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
+      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
+        })
+      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,11 @@
+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>) => {
+    const parsed = schema.parse(input)
+    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/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()
+}