@toolkit-cli/toolkode 1.3.7

package/src/config/markdown.ts

@@ -0,0 +1,99 @@
+import { NamedError } from "@toolkit-cli/util/error"
+import matter from "gray-matter"
+import { z } from "zod"
+import { Filesystem } from "../util/filesystem"
+
+export namespace ConfigMarkdown {
+  export const FILE_REGEX = /(?<![\w`])@(\.?[^\s`,.]*(?:\.[^\s`,.]+)*)/g
+  export const SHELL_REGEX = /!`([^`]+)`/g
+
+  export function files(template: string) {
+    return Array.from(template.matchAll(FILE_REGEX))
+  }
+
+  export function shell(template: string) {
+    return Array.from(template.matchAll(SHELL_REGEX))
+  }
+
+  // other coding agents like claude code allow invalid yaml in their
+  // frontmatter, we need to fallback to a more permissive parser for those cases
+  export function fallbackSanitization(content: string): string {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+    if (!match) return content
+
+    const frontmatter = match[1]
+    const lines = frontmatter.split(/\r?\n/)
+    const result: string[] = []
+
+    for (const line of lines) {
+      // skip comments and empty lines
+      if (line.trim().startsWith("#") || line.trim() === "") {
+        result.push(line)
+        continue
+      }
+
+      // skip lines that are continuations (indented)
+      if (line.match(/^\s+/)) {
+        result.push(line)
+        continue
+      }
+
+      // match key: value pattern
+      const kvMatch = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)$/)
+      if (!kvMatch) {
+        result.push(line)
+        continue
+      }
+
+      const key = kvMatch[1]
+      const value = kvMatch[2].trim()
+
+      // skip if value is empty, already quoted, or uses block scalar
+      if (value === "" || value === ">" || value === "|" || value.startsWith('"') || value.startsWith("'")) {
+        result.push(line)
+        continue
+      }
+
+      // if value contains a colon, convert to block scalar
+      if (value.includes(":")) {
+        result.push(`${key}: |-`)
+        result.push(`  ${value}`)
+        continue
+      }
+
+      result.push(line)
+    }
+
+    const processed = result.join("\n")
+    return content.replace(frontmatter, () => processed)
+  }
+
+  export async function parse(filePath: string) {
+    const template = await Filesystem.readText(filePath)
+
+    try {
+      const md = matter(template)
+      return md
+    } catch {
+      try {
+        return matter(fallbackSanitization(template))
+      } catch (err) {
+        throw new FrontmatterError(
+          {
+            path: filePath,
+            message: `${filePath}: Failed to parse YAML frontmatter: ${err instanceof Error ? err.message : String(err)}`,
+          },
+          { cause: err },
+        )
+      }
+    }
+  }
+
+  export const FrontmatterError = NamedError.create(
+    "ConfigFrontmatterError",
+    z.object({
+      path: z.string(),
+      message: z.string(),
+    }),
+  )
+}

package/src/config/migrate-tui-config.ts

@@ -0,0 +1,155 @@
+import path from "path"
+import { type ParseError as JsoncParseError, applyEdits, modify, parse as parseJsonc } from "jsonc-parser"
+import { unique } from "remeda"
+import z from "zod"
+import { ConfigPaths } from "./paths"
+import { TuiInfo, TuiOptions } from "./tui-schema"
+import { Instance } from "@/project/instance"
+import { Flag } from "@/flag/flag"
+import { Log } from "@/util/log"
+import { Filesystem } from "@/util/filesystem"
+import { Global } from "@/global"
+
+const log = Log.create({ service: "tui.migrate" })
+
+const TUI_SCHEMA_URL = "https://toolkode.com/tui.json"
+
+const LegacyTheme = TuiInfo.shape.theme.optional()
+const LegacyRecord = z.record(z.string(), z.unknown()).optional()
+
+const TuiLegacy = z
+  .object({
+    scroll_speed: TuiOptions.shape.scroll_speed.catch(undefined),
+    scroll_acceleration: TuiOptions.shape.scroll_acceleration.catch(undefined),
+    diff_style: TuiOptions.shape.diff_style.catch(undefined),
+  })
+  .strip()
+
+interface MigrateInput {
+  directories: string[]
+  custom?: string
+  managed: string
+}
+
+/**
+ * Migrates tui-specific keys (theme, keybinds, tui) from toolkode.json files
+ * into dedicated tui.json files. Migration is performed per-directory and
+ * skips only locations where a tui.json already exists.
+ */
+export async function migrateTuiConfig(input: MigrateInput) {
+  const opencode = await opencodeFiles(input)
+  for (const file of opencode) {
+    const source = await Filesystem.readText(file).catch((error) => {
+      log.warn("failed to read config for tui migration", { path: file, error })
+      return undefined
+    })
+    if (!source) continue
+    const errors: JsoncParseError[] = []
+    const data = parseJsonc(source, errors, { allowTrailingComma: true })
+    if (errors.length || !data || typeof data !== "object" || Array.isArray(data)) continue
+
+    const theme = LegacyTheme.safeParse("theme" in data ? data.theme : undefined)
+    const keybinds = LegacyRecord.safeParse("keybinds" in data ? data.keybinds : undefined)
+    const legacyTui = LegacyRecord.safeParse("tui" in data ? data.tui : undefined)
+    const extracted = {
+      theme: theme.success ? theme.data : undefined,
+      keybinds: keybinds.success ? keybinds.data : undefined,
+      tui: legacyTui.success ? legacyTui.data : undefined,
+    }
+    const tui = extracted.tui ? normalizeTui(extracted.tui) : undefined
+    if (extracted.theme === undefined && extracted.keybinds === undefined && !tui) continue
+
+    const target = path.join(path.dirname(file), "tui.json")
+    const targetExists = await Filesystem.exists(target)
+    if (targetExists) continue
+
+    const payload: Record<string, unknown> = {
+      $schema: TUI_SCHEMA_URL,
+    }
+    if (extracted.theme !== undefined) payload.theme = extracted.theme
+    if (extracted.keybinds !== undefined) payload.keybinds = extracted.keybinds
+    if (tui) Object.assign(payload, tui)
+
+    const wrote = await Filesystem.write(target, JSON.stringify(payload, null, 2))
+      .then(() => true)
+      .catch((error) => {
+        log.warn("failed to write tui migration target", { from: file, to: target, error })
+        return false
+      })
+    if (!wrote) continue
+
+    const stripped = await backupAndStripLegacy(file, source)
+    if (!stripped) {
+      log.warn("tui config migrated but source file was not stripped", { from: file, to: target })
+      continue
+    }
+    log.info("migrated tui config", { from: file, to: target })
+  }
+}
+
+function normalizeTui(data: Record<string, unknown>) {
+  const parsed = TuiLegacy.parse(data)
+  if (
+    parsed.scroll_speed === undefined &&
+    parsed.diff_style === undefined &&
+    parsed.scroll_acceleration === undefined
+  ) {
+    return
+  }
+  return parsed
+}
+
+async function backupAndStripLegacy(file: string, source: string) {
+  const backup = file + ".tui-migration.bak"
+  const hasBackup = await Filesystem.exists(backup)
+  const backed = hasBackup
+    ? true
+    : await Filesystem.write(backup, source)
+        .then(() => true)
+        .catch((error) => {
+          log.warn("failed to backup source config during tui migration", { path: file, backup, error })
+          return false
+        })
+  if (!backed) return false
+
+  const text = ["theme", "keybinds", "tui"].reduce((acc, key) => {
+    const edits = modify(acc, [key], undefined, {
+      formattingOptions: {
+        insertSpaces: true,
+        tabSize: 2,
+      },
+    })
+    if (!edits.length) return acc
+    return applyEdits(acc, edits)
+  }, source)
+
+  return Filesystem.write(file, text)
+    .then(() => {
+      log.info("stripped tui keys from server config", { path: file, backup })
+      return true
+    })
+    .catch((error) => {
+      log.warn("failed to strip legacy tui keys from server config", { path: file, backup, error })
+      return false
+    })
+}
+
+async function opencodeFiles(input: { directories: string[]; managed: string }) {
+  const project = Flag.OPENCODE_DISABLE_PROJECT_CONFIG
+    ? []
+    : await ConfigPaths.projectFiles("toolkode", Instance.directory, Instance.worktree)
+  const files = [...project, ...ConfigPaths.fileInDirectory(Global.Path.config, "toolkode")]
+  for (const dir of unique(input.directories)) {
+    files.push(...ConfigPaths.fileInDirectory(dir, "toolkode"))
+  }
+  if (Flag.OPENCODE_CONFIG) files.push(Flag.OPENCODE_CONFIG)
+  files.push(...ConfigPaths.fileInDirectory(input.managed, "toolkode"))
+
+  const existing = await Promise.all(
+    unique(files).map(async (file) => {
+      const ok = await Filesystem.exists(file)
+      return ok ? file : undefined
+    }),
+  )
+  return existing.filter((file): file is string => !!file)
+}

package/src/config/paths.ts

@@ -0,0 +1,174 @@
+import path from "path"
+import os from "os"
+import z from "zod"
+import { type ParseError as JsoncParseError, parse as parseJsonc, printParseErrorCode } from "jsonc-parser"
+import { NamedError } from "@toolkit-cli/util/error"
+import { Filesystem } from "@/util/filesystem"
+import { Flag } from "@/flag/flag"
+import { Global } from "@/global"
+
+export namespace ConfigPaths {
+  export async function projectFiles(name: string, directory: string, worktree: string) {
+    const files: string[] = []
+    for (const file of [`${name}.jsonc`, `${name}.json`]) {
+      const found = await Filesystem.findUp(file, directory, worktree)
+      for (const resolved of found.toReversed()) {
+        files.push(resolved)
+      }
+    }
+    return files
+  }
+
+  export async function directories(directory: string, worktree: string) {
+    return [
+      Global.Path.config,
+      ...(!Flag.OPENCODE_DISABLE_PROJECT_CONFIG
+        ? await Array.fromAsync(
+            Filesystem.up({
+              targets: [".toolkode"],
+              start: directory,
+              stop: worktree,
+            }),
+          )
+        : []),
+      ...(await Array.fromAsync(
+        Filesystem.up({
+          targets: [".toolkode"],
+          start: Global.Path.home,
+          stop: Global.Path.home,
+        }),
+      )),
+      ...(Flag.OPENCODE_CONFIG_DIR ? [Flag.OPENCODE_CONFIG_DIR] : []),
+    ]
+  }
+
+  export function fileInDirectory(dir: string, name: string) {
+    return [path.join(dir, `${name}.jsonc`), path.join(dir, `${name}.json`)]
+  }
+
+  export const JsonError = NamedError.create(
+    "ConfigJsonError",
+    z.object({
+      path: z.string(),
+      message: z.string().optional(),
+    }),
+  )
+
+  export const InvalidError = NamedError.create(
+    "ConfigInvalidError",
+    z.object({
+      path: z.string(),
+      issues: z.custom<z.core.$ZodIssue[]>().optional(),
+      message: z.string().optional(),
+    }),
+  )
+
+  /** Read a config file, returning undefined for missing files and throwing JsonError for other failures. */
+  export async function readFile(filepath: string) {
+    return Filesystem.readText(filepath).catch((err: NodeJS.ErrnoException) => {
+      if (err.code === "ENOENT") return
+      throw new JsonError({ path: filepath }, { cause: err })
+    })
+  }
+
+  type ParseSource = string | { source: string; dir: string }
+
+  function source(input: ParseSource) {
+    return typeof input === "string" ? input : input.source
+  }
+
+  function dir(input: ParseSource) {
+    return typeof input === "string" ? path.dirname(input) : input.dir
+  }
+
+  /** Apply {env:VAR} and {file:path} substitutions to config text. */
+  async function substitute(text: string, input: ParseSource, missing: "error" | "empty" = "error") {
+    text = text.replace(/\{env:([^}]+)\}/g, (_, varName) => {
+      return process.env[varName] || ""
+    })
+
+    const fileMatches = Array.from(text.matchAll(/\{file:[^}]+\}/g))
+    if (!fileMatches.length) return text
+
+    const configDir = dir(input)
+    const configSource = source(input)
+    let out = ""
+    let cursor = 0
+
+    for (const match of fileMatches) {
+      const token = match[0]
+      const index = match.index!
+      out += text.slice(cursor, index)
+
+      const lineStart = text.lastIndexOf("\n", index - 1) + 1
+      const prefix = text.slice(lineStart, index).trimStart()
+      if (prefix.startsWith("//")) {
+        out += token
+        cursor = index + token.length
+        continue
+      }
+
+      let filePath = token.replace(/^\{file:/, "").replace(/\}$/, "")
+      if (filePath.startsWith("~/")) {
+        filePath = path.join(os.homedir(), filePath.slice(2))
+      }
+
+      const resolvedPath = path.isAbsolute(filePath) ? filePath : path.resolve(configDir, filePath)
+      const fileContent = (
+        await Filesystem.readText(resolvedPath).catch((error: NodeJS.ErrnoException) => {
+          if (missing === "empty") return ""
+
+          const errMsg = `bad file reference: "${token}"`
+          if (error.code === "ENOENT") {
+            throw new InvalidError(
+              {
+                path: configSource,
+                message: errMsg + ` ${resolvedPath} does not exist`,
+              },
+              { cause: error },
+            )
+          }
+          throw new InvalidError({ path: configSource, message: errMsg }, { cause: error })
+        })
+      ).trim()
+
+      out += JSON.stringify(fileContent).slice(1, -1)
+      cursor = index + token.length
+    }
+
+    out += text.slice(cursor)
+    return out
+  }
+
+  /** Substitute and parse JSONC text, throwing JsonError on syntax errors. */
+  export async function parseText(text: string, input: ParseSource, missing: "error" | "empty" = "error") {
+    const configSource = source(input)
+    text = await substitute(text, input, missing)
+
+    const errors: JsoncParseError[] = []
+    const data = parseJsonc(text, errors, { allowTrailingComma: true })
+    if (errors.length) {
+      const lines = text.split("\n")
+      const errorDetails = errors
+        .map((e) => {
+          const beforeOffset = text.substring(0, e.offset).split("\n")
+          const line = beforeOffset.length
+          const column = beforeOffset[beforeOffset.length - 1].length + 1
+          const problemLine = lines[line - 1]
+
+          const error = `${printParseErrorCode(e.error)} at line ${line}, column ${column}`
+          if (!problemLine) return error
+
+          return `${error}\n   Line ${line}: ${problemLine}\n${"".padStart(column + 9)}^`
+        })
+        .join("\n")
+
+      throw new JsonError({
+        path: configSource,
+        message: `\n--- JSONC Input ---\n${text}\n--- Errors ---\n${errorDetails}\n--- End ---`,
+      })
+    }
+
+    return data
+  }
+}

package/src/config/tui-schema.ts

@@ -0,0 +1,36 @@
+import z from "zod"
+import { Config } from "./config"
+
+const KeybindOverride = z
+  .object(
+    Object.fromEntries(Object.keys(Config.Keybinds.shape).map((key) => [key, z.string().optional()])) as Record<
+      string,
+      z.ZodOptional<z.ZodString>
+    >,
+  )
+  .strict()
+
+export const TuiOptions = z.object({
+  scroll_speed: z.number().min(0.001).optional().describe("TUI scroll speed"),
+  scroll_acceleration: z
+    .object({
+      enabled: z.boolean().describe("Enable scroll acceleration"),
+    })
+    .optional()
+    .describe("Scroll acceleration settings"),
+  diff_style: z
+    .enum(["auto", "stacked"])
+    .optional()
+    .describe("Control diff rendering style: 'auto' adapts to terminal width, 'stacked' always shows single column"),
+})
+
+export const TuiInfo = z
+  .object({
+    $schema: z.string().optional(),
+    theme: z.string().optional(),
+    keybinds: KeybindOverride.optional(),
+    plugin: Config.PluginSpec.array().optional(),
+    plugin_enabled: z.record(z.string(), z.boolean()).optional(),
+  })
+  .extend(TuiOptions.shape)
+  .strict()

package/src/config/tui.ts

@@ -0,0 +1,212 @@
+import { existsSync } from "fs"
+import z from "zod"
+import { mergeDeep, unique } from "remeda"
+import { Config } from "./config"
+import { ConfigPaths } from "./paths"
+import { migrateTuiConfig } from "./migrate-tui-config"
+import { TuiInfo } from "./tui-schema"
+import { Instance } from "@/project/instance"
+import { Flag } from "@/flag/flag"
+import { Log } from "@/util/log"
+import { isRecord } from "@/util/record"
+import { Global } from "@/global"
+import { parsePluginSpecifier } from "@/plugin/shared"
+
+export namespace TuiConfig {
+  const log = Log.create({ service: "tui.config" })
+
+  export const Info = TuiInfo
+
+  export type PluginMeta = {
+    scope: "global" | "local"
+    source: string
+  }
+
+  type PluginEntry = {
+    item: Config.PluginSpec
+    meta: PluginMeta
+  }
+
+  type Acc = {
+    result: Info
+    entries: PluginEntry[]
+  }
+
+  export type Info = z.output<typeof Info> & {
+    plugin_meta?: Record<string, PluginMeta>
+  }
+
+  function pluginScope(file: string): PluginMeta["scope"] {
+    if (Instance.containsPath(file)) return "local"
+    return "global"
+  }
+
+  function dedupePlugins(list: PluginEntry[]) {
+    const seen = new Set<string>()
+    const result: PluginEntry[] = []
+    for (const item of list.toReversed()) {
+      const spec = Config.pluginSpecifier(item.item)
+      const name = spec.startsWith("file://") ? spec : parsePluginSpecifier(spec).pkg
+      if (seen.has(name)) continue
+      seen.add(name)
+      result.push(item)
+    }
+    return result.toReversed()
+  }
+
+  function mergeInfo(target: Info, source: Info): Info {
+    const merged = mergeDeep(target, source)
+    if (target.plugin && source.plugin) {
+      merged.plugin = [...target.plugin, ...source.plugin]
+    }
+    return merged
+  }
+
+  function customPath() {
+    return Flag.OPENCODE_TUI_CONFIG
+  }
+
+  function normalize(raw: Record<string, unknown>) {
+    const data = { ...raw }
+    if (!("tui" in data)) return data
+    if (!isRecord(data.tui)) {
+      delete data.tui
+      return data
+    }
+
+    const tui = data.tui
+    delete data.tui
+    return {
+      ...tui,
+      ...data,
+    }
+  }
+
+  function installDeps(dir: string): Promise<void> {
+    return Config.installDependencies(dir)
+  }
+
+  async function mergeFile(acc: Acc, file: string) {
+    const data = await loadFile(file)
+    acc.result = mergeInfo(acc.result, data)
+    if (!data.plugin?.length) return
+
+    const scope = pluginScope(file)
+    for (const item of data.plugin) {
+      acc.entries.push({
+        item,
+        meta: {
+          scope,
+          source: file,
+        },
+      })
+    }
+  }
+
+  const state = Instance.state(async () => {
+    let projectFiles = Flag.OPENCODE_DISABLE_PROJECT_CONFIG
+      ? []
+      : await ConfigPaths.projectFiles("tui", Instance.directory, Instance.worktree)
+    const directories = await ConfigPaths.directories(Instance.directory, Instance.worktree)
+    const custom = customPath()
+    const managed = Config.managedConfigDir()
+    await migrateTuiConfig({ directories, custom, managed })
+    // Re-compute after migration since migrateTuiConfig may have created new tui.json files
+    projectFiles = Flag.OPENCODE_DISABLE_PROJECT_CONFIG
+      ? []
+      : await ConfigPaths.projectFiles("tui", Instance.directory, Instance.worktree)
+
+    const acc: Acc = {
+      result: {},
+      entries: [],
+    }
+
+    for (const file of ConfigPaths.fileInDirectory(Global.Path.config, "tui")) {
+      await mergeFile(acc, file)
+    }
+
+    if (custom) {
+      await mergeFile(acc, custom)
+      log.debug("loaded custom tui config", { path: custom })
+    }
+
+    for (const file of projectFiles) {
+      await mergeFile(acc, file)
+    }
+
+    for (const dir of unique(directories)) {
+      if (!dir.endsWith(".toolkode") && dir !== Flag.OPENCODE_CONFIG_DIR) continue
+      for (const file of ConfigPaths.fileInDirectory(dir, "tui")) {
+        await mergeFile(acc, file)
+      }
+    }
+
+    if (existsSync(managed)) {
+      for (const file of ConfigPaths.fileInDirectory(managed, "tui")) {
+        await mergeFile(acc, file)
+      }
+    }
+
+    const merged = dedupePlugins(acc.entries)
+    acc.result.keybinds = Config.Keybinds.parse(acc.result.keybinds ?? {})
+    acc.result.plugin = merged.map((item) => item.item)
+    acc.result.plugin_meta = merged.length
+      ? Object.fromEntries(merged.map((item) => [Config.pluginSpecifier(item.item), item.meta]))
+      : undefined
+
+    const deps: Promise<void>[] = []
+    if (acc.result.plugin?.length) {
+      for (const dir of unique(directories)) {
+        if (!dir.endsWith(".toolkode") && dir !== Flag.OPENCODE_CONFIG_DIR) continue
+        deps.push(installDeps(dir))
+      }
+    }
+
+    return {
+      config: acc.result,
+      deps,
+    }
+  })
+
+  export async function get() {
+    return state().then((x) => x.config)
+  }
+
+  export async function waitForDependencies() {
+    const deps = await state().then((x) => x.deps)
+    await Promise.all(deps)
+  }
+
+  async function loadFile(filepath: string): Promise<Info> {
+    const text = await ConfigPaths.readFile(filepath)
+    if (!text) return {}
+    return load(text, filepath).catch((error) => {
+      log.warn("failed to load tui config", { path: filepath, error })
+      return {}
+    })
+  }
+
+  async function load(text: string, configFilepath: string): Promise<Info> {
+    const raw = await ConfigPaths.parseText(text, configFilepath, "empty")
+    if (!isRecord(raw)) return {}
+
+    // Flatten a nested "tui" key so users who wrote `{ "tui": { ... } }` inside tui.json
+    // (mirroring the old toolkode.json shape) still get their settings applied.
+    const normalized = normalize(raw)
+
+    const parsed = Info.safeParse(normalized)
+    if (!parsed.success) {
+      log.warn("invalid tui config", { path: configFilepath, issues: parsed.error.issues })
+      return {}
+    }
+
+    const data = parsed.data
+    if (data.plugin) {
+      for (let i = 0; i < data.plugin.length; i++) {
+        data.plugin[i] = await Config.resolvePluginSpec(data.plugin[i], configFilepath)
+      }
+    }
+
+    return data
+  }
+}

package/src/control-plane/adaptors/index.ts

@@ -0,0 +1,20 @@
+import { lazy } from "@/util/lazy"
+import type { Adaptor } from "../types"
+
+const ADAPTORS: Record<string, () => Promise<Adaptor>> = {
+  worktree: lazy(async () => (await import("./worktree")).WorktreeAdaptor),
+}
+
+export function getAdaptor(type: string): Promise<Adaptor> {
+  return ADAPTORS[type]()
+}
+
+export function installAdaptor(type: string, adaptor: Adaptor) {
+  // This is experimental: mostly used for testing right now, but we
+  // will likely allow this in the future. Need to figure out the
+  // TypeScript story
+
+  // @ts-expect-error we force the builtin types right now, but we
+  // will implement a way to extend the types for custom adaptors
+  ADAPTORS[type] = () => adaptor
+}