@toolkit-cli/toolkode 1.3.7

package/src/hooks/index.ts

@@ -0,0 +1,302 @@
+/**
+ * tk_ toolkode — Command Hook Engine
+ *
+ * Runs shell commands at lifecycle points: PreToolUse, PostToolUse,
+ * SessionStart, Stop, Notification, SubagentStart/Stop, etc.
+ *
+ * Configured in settings.json under "hooks" key.
+ * Communicates via stdin (JSON input), stdout/stderr, and exit codes.
+ */
+import { spawn } from "child_process"
+import { Config } from "../config/config"
+import { Log } from "../util/log"
+
+const log = Log.create({ service: "hooks" })
+
+export namespace Hooks {
+  /* ── Types ──────────────────────────────────────────────────── */
+
+  export type HookEventName =
+    | "PreToolUse"
+    | "PostToolUse"
+    | "PostToolUseFailure"
+    | "SessionStart"
+    | "SessionEnd"
+    | "Stop"
+    | "StopFailure"
+    | "Notification"
+    | "SubagentStart"
+    | "SubagentStop"
+    | "UserPromptSubmit"
+    | "PermissionRequest"
+    | "TaskCreated"
+    | "TaskCompleted"
+    | "TeammateIdle"
+    | "ConfigChange"
+    | "CwdChanged"
+    | "FileChanged"
+    | "PreCompact"
+    | "PostCompact"
+    | "InstructionsLoaded"
+
+  export interface CommandHook {
+    type: "command"
+    command: string
+    timeout?: number // seconds, default 600
+    if?: string // permission rule syntax filter
+    shell?: string // "bash" | "zsh" | "powershell"
+  }
+
+  export interface PromptHook {
+    type: "prompt"
+    prompt: string
+    model?: string
+    timeout?: number
+  }
+
+  export interface AgentHook {
+    type: "agent"
+    prompt: string
+    model?: string
+    timeout?: number
+  }
+
+  export interface HttpHook {
+    type: "http"
+    url: string
+    headers?: Record<string, string>
+    allowedEnvVars?: string[]
+    timeout?: number
+  }
+
+  export type HookDef = CommandHook | PromptHook | AgentHook | HttpHook
+
+  export interface HookGroup {
+    matcher?: string // regex pattern for filtering
+    hooks: HookDef[]
+  }
+
+  export interface HookResult {
+    exitCode: number
+    stdout: string
+    stderr: string
+    blocked: boolean
+    reason?: string
+  }
+
+  /* ── Config Loading ─────────────────────────────────────────── */
+
+  let hooksConfig: Record<string, HookGroup[]> = {}
+  let disabled = false
+
+  export async function loadFromConfig(): Promise<void> {
+    if (process.env.TOOLKODE_DISABLE_HOOKS === "1" || process.env.TOOLKODE_DISABLE_HOOKS === "true") {
+      disabled = true
+      log.info("hooks disabled via TOOLKODE_DISABLE_HOOKS")
+      return
+    }
+
+    try {
+      const config = await Config.get()
+      // hooks is stored as an "any" field in config since we added it to knownKeys
+      hooksConfig = (config as any).hooks ?? {}
+      const count = Object.values(hooksConfig).reduce((sum, groups) => sum + groups.length, 0)
+      if (count > 0) log.info("hooks loaded", { events: Object.keys(hooksConfig).length, groups: count })
+    } catch (err) {
+      log.error("failed to load hooks config", { error: err })
+    }
+  }
+
+  /** Reload hooks (e.g., after config change) */
+  export async function reload(): Promise<void> {
+    await loadFromConfig()
+  }
+
+  /* ── Hook Execution ─────────────────────────────────────────── */
+
+  /** Fire all matching hooks for an event */
+  export async function fire(
+    event: HookEventName,
+    input: Record<string, any>,
+    matchValue?: string,
+  ): Promise<HookResult[]> {
+    if (disabled) return []
+
+    const groups = hooksConfig[event]
+    if (!groups || groups.length === 0) return []
+
+    const results: HookResult[] = []
+
+    // Run all matching groups in parallel
+    const promises = groups
+      .filter((group) => {
+        if (!group.matcher || group.matcher === "") return true
+        if (!matchValue) return true
+        try {
+          return new RegExp(group.matcher).test(matchValue)
+        } catch {
+          return group.matcher === matchValue
+        }
+      })
+      .flatMap((group) =>
+        group.hooks.map(async (hook) => {
+          try {
+            const result = await executeHook(hook, { ...input, hook_event_name: event })
+            results.push(result)
+          } catch (err) {
+            log.error("hook execution failed", { event, error: err })
+            results.push({ exitCode: 1, stdout: "", stderr: String(err), blocked: false })
+          }
+        }),
+      )
+
+    await Promise.all(promises)
+    return results
+  }
+
+  /** Check if any result blocked the action */
+  export function isBlocked(results: HookResult[]): { blocked: boolean; reason?: string } {
+    const blocker = results.find((r) => r.blocked)
+    if (blocker) return { blocked: true, reason: blocker.reason }
+    return { blocked: false }
+  }
+
+  /** Execute a single hook */
+  async function executeHook(hook: HookDef, input: Record<string, any>): Promise<HookResult> {
+    switch (hook.type) {
+      case "command":
+        return executeCommandHook(hook, input)
+      case "http":
+        return executeHttpHook(hook, input)
+      case "prompt":
+        // Prompt hooks would need LLM integration — placeholder for now
+        return { exitCode: 0, stdout: "", stderr: "", blocked: false }
+      case "agent":
+        // Agent hooks would need subagent spawning — placeholder for now
+        return { exitCode: 0, stdout: "", stderr: "", blocked: false }
+      default:
+        return { exitCode: 0, stdout: "", stderr: "", blocked: false }
+    }
+  }
+
+  /** Execute a command hook via shell */
+  function executeCommandHook(hook: CommandHook, input: Record<string, any>): Promise<HookResult> {
+    const timeoutMs = (hook.timeout ?? 600) * 1000
+    const shell = hook.shell === "powershell" ? "powershell.exe" : process.env.SHELL || "/bin/bash"
+
+    return new Promise((resolve) => {
+      const child = spawn(shell, ["-c", hook.command], {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          CLAUDE_PROJECT_DIR: process.cwd(),
+          TOOLKODE_PROJECT_DIR: process.cwd(),
+        },
+        timeout: timeoutMs,
+      })
+
+      let stdout = ""
+      let stderr = ""
+
+      child.stdout?.on("data", (data: Buffer) => {
+        stdout += data.toString()
+      })
+      child.stderr?.on("data", (data: Buffer) => {
+        stderr += data.toString()
+      })
+
+      // Write input JSON to stdin
+      child.stdin?.write(JSON.stringify(input))
+      child.stdin?.end()
+
+      child.on("close", (code) => {
+        const exitCode = code ?? 0
+        const blocked = exitCode === 2
+
+        // Try to parse structured JSON output
+        let reason = blocked ? stderr.trim() : undefined
+        if (stdout.trim().startsWith("{")) {
+          try {
+            const json = JSON.parse(stdout.trim())
+            if (json.hookSpecificOutput?.permissionDecision === "deny") {
+              resolve({
+                exitCode,
+                stdout,
+                stderr,
+                blocked: true,
+                reason: json.hookSpecificOutput.permissionDecisionReason || reason,
+              })
+              return
+            }
+            if (json.decision === "block") {
+              resolve({
+                exitCode,
+                stdout,
+                stderr,
+                blocked: true,
+                reason: json.reason || reason,
+              })
+              return
+            }
+          } catch {
+            // Not JSON, treat as plain text
+          }
+        }
+
+        resolve({ exitCode, stdout, stderr, blocked, reason })
+      })
+
+      child.on("error", (err) => {
+        resolve({ exitCode: 1, stdout: "", stderr: err.message, blocked: false })
+      })
+    })
+  }
+
+  /** Execute an HTTP hook */
+  async function executeHttpHook(hook: HttpHook, input: Record<string, any>): Promise<HookResult> {
+    const timeoutMs = (hook.timeout ?? 600) * 1000
+
+    // Resolve env vars in headers
+    const headers: Record<string, string> = { "Content-Type": "application/json" }
+    if (hook.headers) {
+      const allowed = new Set(hook.allowedEnvVars ?? [])
+      for (const [key, value] of Object.entries(hook.headers)) {
+        headers[key] = value.replace(/\$\{?(\w+)\}?/g, (_, name) => {
+          if (allowed.has(name)) return process.env[name] ?? ""
+          return ""
+        })
+      }
+    }
+
+    try {
+      const res = await fetch(hook.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(input),
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+
+      const text = await res.text()
+      let blocked = false
+      let reason: string | undefined
+
+      if (text.trim().startsWith("{")) {
+        try {
+          const json = JSON.parse(text)
+          if (json.hookSpecificOutput?.permissionDecision === "deny") {
+            blocked = true
+            reason = json.hookSpecificOutput.permissionDecisionReason
+          }
+          if (json.decision === "block") {
+            blocked = true
+            reason = json.reason
+          }
+        } catch {}
+      }
+
+      return { exitCode: res.ok ? 0 : 1, stdout: text, stderr: "", blocked, reason }
+    } catch (err) {
+      return { exitCode: 1, stdout: "", stderr: String(err), blocked: false }
+    }
+  }
+}

package/src/id/id.ts

@@ -0,0 +1,85 @@
+import z from "zod"
+import { randomBytes } from "crypto"
+
+export namespace Identifier {
+  const prefixes = {
+    event: "evt",
+    session: "ses",
+    message: "msg",
+    permission: "per",
+    question: "que",
+    user: "usr",
+    part: "prt",
+    pty: "pty",
+    tool: "tool",
+    workspace: "wrk",
+  } as const
+
+  export function schema(prefix: keyof typeof prefixes) {
+    return z.string().startsWith(prefixes[prefix])
+  }
+
+  const LENGTH = 26
+
+  // State for monotonic ID generation
+  let lastTimestamp = 0
+  let counter = 0
+
+  export function ascending(prefix: keyof typeof prefixes, given?: string) {
+    return generateID(prefix, false, given)
+  }
+
+  export function descending(prefix: keyof typeof prefixes, given?: string) {
+    return generateID(prefix, true, given)
+  }
+
+  function generateID(prefix: keyof typeof prefixes, descending: boolean, given?: string): string {
+    if (!given) {
+      return create(prefix, descending)
+    }
+
+    if (!given.startsWith(prefixes[prefix])) {
+      throw new Error(`ID ${given} does not start with ${prefixes[prefix]}`)
+    }
+    return given
+  }
+
+  function randomBase62(length: number): string {
+    const chars = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+    let result = ""
+    const bytes = randomBytes(length)
+    for (let i = 0; i < length; i++) {
+      result += chars[bytes[i] % 62]
+    }
+    return result
+  }
+
+  export function create(prefix: keyof typeof prefixes, descending: boolean, timestamp?: number): string {
+    const currentTimestamp = timestamp ?? Date.now()
+
+    if (currentTimestamp !== lastTimestamp) {
+      lastTimestamp = currentTimestamp
+      counter = 0
+    }
+    counter++
+
+    let now = BigInt(currentTimestamp) * BigInt(0x1000) + BigInt(counter)
+
+    now = descending ? ~now : now
+
+    const timeBytes = Buffer.alloc(6)
+    for (let i = 0; i < 6; i++) {
+      timeBytes[i] = Number((now >> BigInt(40 - 8 * i)) & BigInt(0xff))
+    }
+
+    return prefixes[prefix] + "_" + timeBytes.toString("hex") + randomBase62(LENGTH - 12)
+  }
+
+  /** Extract timestamp from an ascending ID. Does not work with descending IDs. */
+  export function timestamp(id: string): number {
+    const prefix = id.split("_")[0]
+    const hex = id.slice(prefix.length + 1, prefix.length + 13)
+    const encoded = BigInt("0x" + hex)
+    return Number(encoded / BigInt(0x1000))
+  }
+}

package/src/ide/index.ts

@@ -0,0 +1,74 @@
+import { BusEvent } from "@/bus/bus-event"
+import { Bus } from "@/bus"
+import z from "zod"
+import { NamedError } from "@toolkit-cli/util/error"
+import { Log } from "../util/log"
+import { Process } from "@/util/process"
+
+const SUPPORTED_IDES = [
+  { name: "Windsurf" as const, cmd: "windsurf" },
+  { name: "Visual Studio Code - Insiders" as const, cmd: "code-insiders" },
+  { name: "Visual Studio Code" as const, cmd: "code" },
+  { name: "Cursor" as const, cmd: "cursor" },
+  { name: "VSCodium" as const, cmd: "codium" },
+]
+
+export namespace Ide {
+  const log = Log.create({ service: "ide" })
+
+  export const Event = {
+    Installed: BusEvent.define(
+      "ide.installed",
+      z.object({
+        ide: z.string(),
+      }),
+    ),
+  }
+
+  export const AlreadyInstalledError = NamedError.create("AlreadyInstalledError", z.object({}))
+
+  export const InstallFailedError = NamedError.create(
+    "InstallFailedError",
+    z.object({
+      stderr: z.string(),
+    }),
+  )
+
+  export function ide() {
+    if (process.env["TERM_PROGRAM"] === "vscode") {
+      const v = process.env["GIT_ASKPASS"]
+      for (const ide of SUPPORTED_IDES) {
+        if (v?.includes(ide.name)) return ide.name
+      }
+    }
+    return "unknown"
+  }
+
+  export function alreadyInstalled() {
+    return process.env["OPENCODE_CALLER"] === "vscode" || process.env["OPENCODE_CALLER"] === "vscode-insiders"
+  }
+
+  export async function install(ide: (typeof SUPPORTED_IDES)[number]["name"]) {
+    const cmd = SUPPORTED_IDES.find((i) => i.name === ide)?.cmd
+    if (!cmd) throw new Error(`Unknown IDE: ${ide}`)
+
+    const p = await Process.run([cmd, "--install-extension", "toolkit-llm.toolkode"], {
+      nothrow: true,
+    })
+    const stdout = p.stdout.toString()
+    const stderr = p.stderr.toString()
+
+    log.info("installed", {
+      ide,
+      stdout,
+      stderr,
+    })
+
+    if (p.code !== 0) {
+      throw new InstallFailedError({ stderr })
+    }
+    if (stdout.includes("already installed")) {
+      throw new AlreadyInstalledError({})
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,243 @@
+import yargs from "yargs"
+import { hideBin } from "yargs/helpers"
+import { RunCommand } from "./cli/cmd/run"
+import { GenerateCommand } from "./cli/cmd/generate"
+import { Log } from "./util/log"
+import { ConsoleCommand } from "./cli/cmd/account"
+import { ProvidersCommand } from "./cli/cmd/providers"
+import { AgentCommand } from "./cli/cmd/agent"
+import { UpgradeCommand } from "./cli/cmd/upgrade"
+import { UninstallCommand } from "./cli/cmd/uninstall"
+import { ModelsCommand } from "./cli/cmd/models"
+import { UI } from "./cli/ui"
+import { Installation } from "./installation"
+import { NamedError } from "@toolkit-cli/util/error"
+import { FormatError } from "./cli/error"
+import { ServeCommand } from "./cli/cmd/serve"
+import { Filesystem } from "./util/filesystem"
+import { DebugCommand } from "./cli/cmd/debug"
+import { StatsCommand } from "./cli/cmd/stats"
+import { McpCommand } from "./cli/cmd/mcp"
+import { GithubCommand } from "./cli/cmd/github"
+import { ExportCommand } from "./cli/cmd/export"
+import { ImportCommand } from "./cli/cmd/import"
+import { AttachCommand } from "./cli/cmd/tui/attach"
+import { TuiThreadCommand } from "./cli/cmd/tui/thread"
+import { AcpCommand } from "./cli/cmd/acp"
+import { EOL } from "os"
+import { WebCommand } from "./cli/cmd/web"
+import { PrCommand } from "./cli/cmd/pr"
+import { SessionCommand } from "./cli/cmd/session"
+import { DbCommand } from "./cli/cmd/db"
+import path from "path"
+import { Global } from "./global"
+import { JsonMigration } from "./storage/json-migration"
+import { Database } from "./storage/db"
+import { errorMessage } from "./util/error"
+import { PluginCommand } from "./cli/cmd/plug"
+
+process.on("unhandledRejection", (e) => {
+  Log.Default.error("rejection", {
+    e: errorMessage(e),
+  })
+})
+
+process.on("uncaughtException", (e) => {
+  Log.Default.error("exception", {
+    e: errorMessage(e),
+  })
+})
+
+const cli = yargs(hideBin(process.argv))
+  .parserConfiguration({ "populate--": true })
+  .scriptName("toolkode")
+  .wrap(100)
+  .help("help", "show help")
+  .alias("help", "h")
+  .version("version", "show version number", Installation.VERSION)
+  .alias("version", "v")
+  .option("p", {
+    alias: "print",
+    describe: "run non-interactively with a prompt (headless mode). Alias for 'toolkode run'",
+    type: "string",
+  })
+  .option("print-logs", {
+    describe: "print logs to stderr",
+    type: "boolean",
+  })
+  .option("log-level", {
+    describe: "log level",
+    type: "string",
+    choices: ["DEBUG", "INFO", "WARN", "ERROR"],
+  })
+  .option("pure", {
+    describe: "run without external plugins",
+    type: "boolean",
+  })
+  .option("channels", {
+    describe: "enable channel servers (space-separated: plugin:name@marketplace or server:name)",
+    type: "string",
+  })
+  .option("dangerously-load-development-channels", {
+    describe: "bypass channel allowlist for development/testing",
+    type: "boolean",
+  })
+  .option("teammate-mode", {
+    describe: "display mode for agent teams: in-process or tmux",
+    type: "string",
+    choices: ["in-process", "tmux", "auto"],
+  })
+  .option("agent", {
+    describe: "run the session as a specific agent",
+    type: "string",
+  })
+  .option("agents", {
+    describe: "JSON defining session-scoped agents",
+    type: "string",
+  })
+  .middleware(async (opts) => {
+    if (opts.pure) {
+      process.env.OPENCODE_PURE = "1"
+    }
+
+    await Log.init({
+      print: process.argv.includes("--print-logs"),
+      dev: Installation.isLocal(),
+      level: (() => {
+        if (opts.logLevel) return opts.logLevel as Log.Level
+        if (Installation.isLocal()) return "DEBUG"
+        return "INFO"
+      })(),
+    })
+
+    process.env.AGENT = "1"
+    process.env.OPENCODE = "1"
+    process.env.OPENCODE_PID = String(process.pid)
+
+    Log.Default.info("toolkode", {
+      version: Installation.VERSION,
+      args: process.argv.slice(2),
+    })
+
+    const marker = path.join(Global.Path.data, "toolkode.db")
+    if (!(await Filesystem.exists(marker))) {
+      const tty = process.stderr.isTTY
+      process.stderr.write("Performing one time database migration, may take a few minutes..." + EOL)
+      const width = 36
+      const orange = "\x1b[38;5;214m"
+      const muted = "\x1b[0;2m"
+      const reset = "\x1b[0m"
+      let last = -1
+      if (tty) process.stderr.write("\x1b[?25l")
+      try {
+        await JsonMigration.run(Database.Client().$client, {
+          progress: (event) => {
+            const percent = Math.floor((event.current / event.total) * 100)
+            if (percent === last && event.current !== event.total) return
+            last = percent
+            if (tty) {
+              const fill = Math.round((percent / 100) * width)
+              const bar = `${"■".repeat(fill)}${"･".repeat(width - fill)}`
+              process.stderr.write(
+                `\r${orange}${bar} ${percent.toString().padStart(3)}%${reset} ${muted}${event.label.padEnd(12)} ${event.current}/${event.total}${reset}`,
+              )
+              if (event.current === event.total) process.stderr.write("\n")
+            } else {
+              process.stderr.write(`sqlite-migration:${percent}${EOL}`)
+            }
+          },
+        })
+      } finally {
+        if (tty) process.stderr.write("\x1b[?25h")
+        else {
+          process.stderr.write(`sqlite-migration:done${EOL}`)
+        }
+      }
+      process.stderr.write("Database migration complete." + EOL)
+    }
+  })
+  .usage("\n" + UI.logo())
+  .completion("completion", "generate shell completion script")
+  .command(AcpCommand)
+  .command(McpCommand)
+  .command(TuiThreadCommand)
+  .command(AttachCommand)
+  .command(RunCommand)
+  .command(GenerateCommand)
+  .command(DebugCommand)
+  .command(ConsoleCommand)
+  .command(ProvidersCommand)
+  .command(AgentCommand)
+  .command(UpgradeCommand)
+  .command(UninstallCommand)
+  .command(ServeCommand)
+  .command(WebCommand)
+  .command(ModelsCommand)
+  .command(StatsCommand)
+  .command(ExportCommand)
+  .command(ImportCommand)
+  .command(GithubCommand)
+  .command(PrCommand)
+  .command(SessionCommand)
+  .command(PluginCommand)
+  .command(DbCommand)
+  .fail((msg, err) => {
+    if (
+      msg?.startsWith("Unknown argument") ||
+      msg?.startsWith("Not enough non-option arguments") ||
+      msg?.startsWith("Invalid values:")
+    ) {
+      if (err) throw err
+      cli.showHelp("log")
+    }
+    if (err) throw err
+    process.exit(1)
+  })
+  .strict()
+
+try {
+  await cli.parse()
+} catch (e) {
+  let data: Record<string, any> = {}
+  if (e instanceof NamedError) {
+    const obj = e.toObject()
+    Object.assign(data, {
+      ...obj.data,
+    })
+  }
+
+  if (e instanceof Error) {
+    Object.assign(data, {
+      name: e.name,
+      message: e.message,
+      cause: e.cause?.toString(),
+      stack: e.stack,
+    })
+  }
+
+  if (e instanceof ResolveMessage) {
+    Object.assign(data, {
+      name: e.name,
+      message: e.message,
+      code: e.code,
+      specifier: e.specifier,
+      referrer: e.referrer,
+      position: e.position,
+      importKind: e.importKind,
+    })
+  }
+  Log.Default.error("fatal", data)
+  const formatted = FormatError(e)
+  if (formatted) UI.error(formatted)
+  if (formatted === undefined) {
+    UI.error("Unexpected error, check log file at " + Log.file() + " for more details" + EOL)
+    process.stderr.write(errorMessage(e) + EOL)
+  }
+  process.exitCode = 1
+} finally {
+  // Some subprocesses don't react properly to SIGTERM and similar signals.
+  // Most notably, some docker-container-based MCP servers don't handle such signals unless
+  // run using `docker run --init`.
+  // Explicitly exit to avoid any hanging subprocesses.
+  process.exit()
+}