@cuongtran001/kanna 0.39.2

package/src/server/llm-provider.test.ts

@@ -0,0 +1,134 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { DEFAULT_OPENAI_SDK_MODEL, DEFAULT_OPENROUTER_SDK_MODEL } from "../shared/types"
+import {
+  normalizeLlmProviderSnapshot,
+  OPENAI_BASE_URL,
+  OPENROUTER_BASE_URL,
+  readLlmProviderSnapshot,
+  resolveLlmProviderBaseUrl,
+  writeLlmProviderSnapshot,
+} from "./llm-provider"
+
+let tempDirs: string[] = []
+const TEST_FILE_PATH = "/tmp/kanna-test-llm-provider.json"
+
+afterEach(async () => {
+  await Promise.all(tempDirs.map((dir) => rm(dir, { recursive: true, force: true })))
+  tempDirs = []
+})
+
+async function createTempFilePath() {
+  const dir = await mkdtemp(path.join(tmpdir(), "kanna-llm-provider-"))
+  tempDirs.push(dir)
+  return path.join(dir, "llm-provider.json")
+}
+
+describe("resolveLlmProviderBaseUrl", () => {
+  test("derives known provider URLs and preserves custom URLs", () => {
+    expect(resolveLlmProviderBaseUrl("openai", "")).toBe(OPENAI_BASE_URL)
+    expect(resolveLlmProviderBaseUrl("openrouter", "")).toBe(OPENROUTER_BASE_URL)
+    expect(resolveLlmProviderBaseUrl("custom", " https://example.com/v1 ")).toBe("https://example.com/v1")
+  })
+})
+
+describe("normalizeLlmProviderSnapshot", () => {
+  test("normalizes a valid custom provider config", () => {
+    expect(normalizeLlmProviderSnapshot({
+      provider: "custom",
+      apiKey: "  test-key  ",
+      model: "  gpt-test  ",
+      baseUrl: " https://example.com/v1 ",
+    }, TEST_FILE_PATH)).toEqual({
+      provider: "custom",
+      apiKey: "test-key",
+      model: "gpt-test",
+      baseUrl: "https://example.com/v1",
+      resolvedBaseUrl: "https://example.com/v1",
+      enabled: true,
+      warning: null,
+      filePathDisplay: TEST_FILE_PATH,
+    })
+  })
+
+  test("disables invalid configs with a warning", () => {
+    const snapshot = normalizeLlmProviderSnapshot({
+      provider: "custom",
+      apiKey: "test-key",
+      model: "gpt-test",
+      baseUrl: "",
+    }, TEST_FILE_PATH)
+
+    expect(snapshot.enabled).toBe(false)
+    expect(snapshot.warning).toContain("custom provider requires a baseUrl")
+  })
+})
+
+describe("readLlmProviderSnapshot", () => {
+  test("returns defaults when the file does not exist", async () => {
+    const filePath = await createTempFilePath()
+    expect(await readLlmProviderSnapshot(filePath)).toEqual({
+      provider: "openai",
+      apiKey: "",
+      model: DEFAULT_OPENAI_SDK_MODEL,
+      baseUrl: "",
+      resolvedBaseUrl: OPENAI_BASE_URL,
+      enabled: false,
+      warning: null,
+      filePathDisplay: filePath,
+    })
+  })
+
+  test("returns a warning when the file contains invalid json", async () => {
+    const filePath = await createTempFilePath()
+    await writeFile(filePath, "{not-json", "utf8")
+
+    const snapshot = await readLlmProviderSnapshot(filePath)
+    expect(snapshot.enabled).toBe(false)
+    expect(snapshot.warning).toContain("invalid JSON")
+  })
+
+  test("fills named-provider default models when the file omits them", async () => {
+    const filePath = await createTempFilePath()
+    await writeFile(filePath, JSON.stringify({
+      provider: "openrouter",
+      apiKey: "test-key",
+      baseUrl: null,
+    }), "utf8")
+
+    const snapshot = await readLlmProviderSnapshot(filePath)
+    expect(snapshot.model).toBe(DEFAULT_OPENROUTER_SDK_MODEL)
+    expect(snapshot.enabled).toBe(true)
+  })
+})
+
+describe("writeLlmProviderSnapshot", () => {
+  test("writes normalized config to disk", async () => {
+    const filePath = await createTempFilePath()
+    const snapshot = await writeLlmProviderSnapshot({
+      provider: "openrouter",
+      apiKey: " test-key ",
+      model: " openrouter/model ",
+      baseUrl: "ignored",
+    }, filePath)
+
+    expect(snapshot).toEqual({
+      provider: "openrouter",
+      apiKey: "test-key",
+      model: "openrouter/model",
+      baseUrl: "ignored",
+      resolvedBaseUrl: OPENROUTER_BASE_URL,
+      enabled: true,
+      warning: null,
+      filePathDisplay: filePath,
+    })
+    expect(await Bun.file(filePath).json()).toEqual({
+      provider: "openrouter",
+      apiKey: "test-key",
+      model: "openrouter/model",
+      baseUrl: null,
+    })
+  })
+})

package/src/server/llm-provider.ts

@@ -0,0 +1,207 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import path from "node:path"
+import OpenAI from "openai"
+import { getLlmProviderFilePath } from "../shared/branding"
+import {
+  DEFAULT_OPENAI_SDK_MODEL,
+  DEFAULT_OPENROUTER_SDK_MODEL,
+  type LlmProviderFile,
+  type LlmProviderKind,
+  type LlmProviderSnapshot,
+  type LlmProviderValidationResult,
+} from "../shared/types"
+
+export const OPENAI_BASE_URL = "https://api.openai.com/v1"
+export const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+
+const DEFAULT_PROVIDER: LlmProviderKind = "openai"
+
+function formatDisplayPath(filePath: string) {
+  const homePath = homedir()
+  if (filePath === homePath) return "~"
+  if (filePath.startsWith(`${homePath}${path.sep}`)) {
+    return `~${filePath.slice(homePath.length)}`
+  }
+  return filePath
+}
+
+function resolveProvider(value: unknown) {
+  if (value === "openai" || value === "openrouter" || value === "custom") {
+    return value
+  }
+  return null
+}
+
+function normalizeString(value: unknown) {
+  return typeof value === "string" ? value.trim() : ""
+}
+
+export function resolveLlmProviderBaseUrl(provider: LlmProviderKind, baseUrl: string) {
+  if (provider === "openai") return OPENAI_BASE_URL
+  if (provider === "openrouter") return OPENROUTER_BASE_URL
+  return baseUrl.trim()
+}
+
+export function resolveLlmProviderDefaultModel(provider: LlmProviderKind) {
+  if (provider === "openai") return DEFAULT_OPENAI_SDK_MODEL
+  if (provider === "openrouter") return DEFAULT_OPENROUTER_SDK_MODEL
+  return ""
+}
+
+export function normalizeLlmProviderSnapshot(
+  value: unknown,
+  filePath = getLlmProviderFilePath(homedir())
+): LlmProviderSnapshot {
+  const source = value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null
+  const warnings: string[] = []
+
+  if (!source) {
+    return createDefaultSnapshot(
+      filePath,
+      value === undefined || value === null ? null : "LLM provider file must contain a JSON object. Using defaults."
+    )
+  }
+
+  const provider = resolveProvider(source.provider)
+  const apiKey = normalizeString(source.apiKey)
+  const model = normalizeString(source.model)
+  const baseUrl = normalizeString(source.baseUrl)
+
+  if (!provider) {
+    warnings.push("provider must be one of openai, openrouter, or custom")
+  }
+  if (source.apiKey !== undefined && typeof source.apiKey !== "string") {
+    warnings.push("apiKey must be a string")
+  }
+  if (source.model !== undefined && typeof source.model !== "string") {
+    warnings.push("model must be a string")
+  }
+  if (source.baseUrl !== undefined && source.baseUrl !== null && typeof source.baseUrl !== "string") {
+    warnings.push("baseUrl must be a string or null")
+  }
+  if ((provider ?? DEFAULT_PROVIDER) === "custom" && !baseUrl) {
+    warnings.push("custom provider requires a baseUrl")
+  }
+
+  const normalizedProvider = provider ?? DEFAULT_PROVIDER
+  const resolvedModel = model || resolveLlmProviderDefaultModel(normalizedProvider)
+  const resolvedBaseUrl = resolveLlmProviderBaseUrl(normalizedProvider, baseUrl)
+  const enabled = warnings.length === 0 && apiKey.length > 0 && resolvedModel.length > 0 && resolvedBaseUrl.length > 0
+
+  return {
+    provider: normalizedProvider,
+    apiKey,
+    model: resolvedModel,
+    baseUrl,
+    resolvedBaseUrl,
+    enabled,
+    warning: warnings.length > 0 ? `Some LLM provider settings are invalid: ${warnings.join("; ")}` : null,
+    filePathDisplay: formatDisplayPath(filePath),
+  }
+}
+
+function createDefaultSnapshot(filePath: string, warning: string | null = null): LlmProviderSnapshot {
+  return {
+    provider: DEFAULT_PROVIDER,
+    apiKey: "",
+    model: DEFAULT_OPENAI_SDK_MODEL,
+    baseUrl: "",
+    resolvedBaseUrl: OPENAI_BASE_URL,
+    enabled: false,
+    warning,
+    filePathDisplay: formatDisplayPath(filePath),
+  }
+}
+
+export async function readLlmProviderSnapshot(filePath = getLlmProviderFilePath(homedir())) {
+  try {
+    const text = await readFile(filePath, "utf8")
+    if (!text.trim()) {
+      return createDefaultSnapshot(filePath, "LLM provider file was empty. Using defaults.")
+    }
+    return normalizeLlmProviderSnapshot(JSON.parse(text), filePath)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
+      return createDefaultSnapshot(filePath)
+    }
+    if (error instanceof SyntaxError) {
+      return createDefaultSnapshot(filePath, "LLM provider file is invalid JSON. Using defaults.")
+    }
+    throw error
+  }
+}
+
+export async function writeLlmProviderSnapshot(
+  value: Pick<LlmProviderFile, "provider" | "apiKey" | "model"> & { baseUrl: string },
+  filePath = getLlmProviderFilePath(homedir())
+) {
+  const snapshot = normalizeLlmProviderSnapshot(value, filePath)
+  const payload: LlmProviderFile = {
+    provider: snapshot.provider,
+    apiKey: snapshot.apiKey,
+    model: snapshot.model,
+    baseUrl: snapshot.provider === "custom" ? snapshot.baseUrl : null,
+  }
+  await mkdir(path.dirname(filePath), { recursive: true })
+  await writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8")
+  return snapshot
+}
+
+function toSerializableValue(value: unknown): unknown {
+  if (value === null || value === undefined) return value ?? null
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value
+  if (Array.isArray(value)) {
+    return value.map((entry) => toSerializableValue(entry))
+  }
+  if (value instanceof Error) {
+    return toSerializableValue(Object.fromEntries(
+      Object.getOwnPropertyNames(value).map((key) => [key, (value as unknown as Record<string, unknown>)[key]])
+    ))
+  }
+  if (typeof value === "object") {
+    const record = value as Record<string, unknown>
+    return Object.fromEntries(
+      Object.keys(record).map((key) => [key, toSerializableValue(record[key])])
+    )
+  }
+  return String(value)
+}
+
+export async function validateLlmProviderCredentials(
+  value: Pick<LlmProviderSnapshot, "provider" | "apiKey" | "model" | "baseUrl">
+): Promise<LlmProviderValidationResult> {
+  const snapshot = normalizeLlmProviderSnapshot(value)
+  if (!snapshot.enabled) {
+    return {
+      ok: false,
+      error: {
+        type: "config_error",
+        message: snapshot.warning ?? "LLM provider configuration is incomplete.",
+      },
+    }
+  }
+
+  try {
+    const client = new OpenAI({
+      apiKey: snapshot.apiKey,
+      baseURL: snapshot.resolvedBaseUrl,
+    })
+    await client.responses.create({
+      model: snapshot.model,
+      input: "Reply with ok.",
+      max_output_tokens: 5,
+    })
+    return {
+      ok: true,
+      error: null,
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      error: toSerializableValue(error),
+    }
+  }
+}

package/src/server/machine-name.ts

@@ -0,0 +1,22 @@
+import { hostname } from "node:os"
+import process from "node:process"
+import { spawnSync } from "node:child_process"
+
+function runAndRead(command: string, args: string[]) {
+  const result = spawnSync(command, args, { encoding: "utf8" })
+  if (result.status !== 0) return null
+  const value = result.stdout.trim()
+  return value || null
+}
+
+export function getMachineDisplayName() {
+  if (process.platform === "darwin") {
+    const computerName = runAndRead("scutil", ["--get", "ComputerName"])
+    if (computerName) {
+      return computerName
+    }
+  }
+
+  const rawHostname = hostname().trim()
+  return rawHostname.replace(/\.local$|\.lan$/i, "") || "This Machine"
+}

package/src/server/paths-route.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { startKannaServer } from "./server"
+
+const tempDirs: string[] = []
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((d) => rm(d, { recursive: true, force: true })))
+})
+
+async function startServer(port: number) {
+  const projectDir = await mkdtemp(path.join(tmpdir(), "kanna-paths-route-"))
+  tempDirs.push(projectDir)
+  const server = await startKannaServer({ port, strictPort: true })
+  return { server, projectDir }
+}
+
+describe("GET /api/projects/:id/paths", () => {
+  test("returns 404 for unknown project", async () => {
+    const { server } = await startServer(4330)
+    try {
+      const response = await fetch(`http://localhost:${server.port}/api/projects/does-not-exist/paths`)
+      expect(response.status).toBe(404)
+    } finally {
+      await server.stop()
+    }
+  })
+
+  test("returns top-level entries for empty query", async () => {
+    const { server, projectDir } = await startServer(4331)
+    try {
+      await mkdir(path.join(projectDir, "src"))
+      await writeFile(path.join(projectDir, "README.md"), "")
+
+      const project = await server.store.openProject(projectDir, "t")
+      const response = await fetch(`http://localhost:${server.port}/api/projects/${project.id}/paths`)
+      expect(response.status).toBe(200)
+      const payload = await response.json() as { paths: Array<{ path: string; kind: string }> }
+      const names = payload.paths.map((p) => p.path)
+      expect(names).toContain("README.md")
+      expect(names).toContain("src/")
+    } finally {
+      await server.stop()
+    }
+  })
+
+  test("respects ?query= and ?limit=", async () => {
+    const { server, projectDir } = await startServer(4332)
+    try {
+      for (let i = 0; i < 5; i++) await writeFile(path.join(projectDir, `file-${i}.txt`), "")
+
+      const project = await server.store.openProject(projectDir, "t")
+      const response = await fetch(
+        `http://localhost:${server.port}/api/projects/${project.id}/paths?query=file&limit=2`,
+      )
+      const payload = await response.json() as { paths: Array<{ path: string }> }
+      expect(payload.paths.length).toBe(2)
+    } finally {
+      await server.stop()
+    }
+  })
+})

package/src/server/paths.ts

@@ -0,0 +1,35 @@
+import { mkdir, stat } from "node:fs/promises"
+import { homedir } from "node:os"
+import path from "node:path"
+
+export function resolveLocalPath(localPath: string) {
+  const trimmed = localPath.trim()
+  if (!trimmed) {
+    throw new Error("Project path is required")
+  }
+  if (trimmed === "~") {
+    return homedir()
+  }
+  if (trimmed.startsWith("~/")) {
+    return path.join(homedir(), trimmed.slice(2))
+  }
+  return path.resolve(trimmed)
+}
+
+export async function ensureProjectDirectory(localPath: string) {
+  const resolvedPath = resolveLocalPath(localPath)
+
+  await mkdir(resolvedPath, { recursive: true })
+  const info = await stat(resolvedPath)
+  if (!info.isDirectory()) {
+    throw new Error("Project path must be a directory")
+  }
+}
+
+export function getProjectUploadDir(localPath: string) {
+  return path.join(resolveLocalPath(localPath), ".kanna", "uploads")
+}
+
+export function getProjectExportDir(localPath: string) {
+  return path.join(resolveLocalPath(localPath), ".kanna", "exports")
+}

package/src/server/process-utils.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from "bun:test"
+import { spawnDetached } from "./process-utils"
+
+describe("spawnDetached", () => {
+  test("rejects when the command does not exist", async () => {
+    await expect(spawnDetached("definitely-not-a-real-command-kanna", [])).rejects.toThrow("Command not found")
+  })
+
+  test("resolves when the process starts successfully", async () => {
+    await expect(spawnDetached("sh", ["-c", "exit 0"])).resolves.toBeUndefined()
+  })
+})

package/src/server/process-utils.ts

@@ -0,0 +1,47 @@
+import { spawn, spawnSync } from "node:child_process"
+
+function formatSpawnError(command: string, error: unknown) {
+  if (!(error instanceof Error)) {
+    return new Error(`Failed to start ${command}`)
+  }
+
+  const code = "code" in error ? (error as NodeJS.ErrnoException).code : undefined
+  if (code === "ENOENT") {
+    return new Error(`Command not found: ${command}`)
+  }
+
+  return new Error(error.message || `Failed to start ${command}`)
+}
+
+export function spawnDetached(command: string, args: string[]) {
+  return new Promise<void>((resolve, reject) => {
+    let child
+    try {
+      child = spawn(command, args, { stdio: "ignore", detached: true })
+    } catch (error) {
+      reject(formatSpawnError(command, error))
+      return
+    }
+
+    const handleError = (error: Error) => {
+      reject(formatSpawnError(command, error))
+    }
+
+    child.once("error", handleError)
+    child.once("spawn", () => {
+      child.off("error", handleError)
+      child.unref()
+      resolve()
+    })
+  })
+}
+
+export function hasCommand(command: string) {
+  const result = spawnSync("sh", ["-lc", `command -v ${command}`], { stdio: "ignore" })
+  return result.status === 0
+}
+
+export function canOpenMacApp(appName: string) {
+  const result = spawnSync("open", ["-Ra", appName], { stdio: "ignore" })
+  return result.status === 0
+}

package/src/server/project-paths.test.ts

@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { $ } from "bun"
+import { clearProjectPathCache, listProjectPaths } from "./project-paths"
+
+const tempDirs: string[] = []
+
+beforeEach(() => {
+  clearProjectPathCache()
+})
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })))
+})
+
+async function makeTempDir(prefix: string): Promise<string> {
+  const dir = await mkdtemp(path.join(tmpdir(), prefix))
+  tempDirs.push(dir)
+  return dir
+}
+
+describe("listProjectPaths", () => {
+  test("empty query returns top-level entries with dirs suffixed", async () => {
+    const root = await makeTempDir("kanna-paths-empty-")
+    await writeFile(path.join(root, "a.txt"), "a")
+    await mkdir(path.join(root, "src"))
+    await writeFile(path.join(root, "src", "b.ts"), "b")
+
+    const paths = await listProjectPaths({ projectId: "p1", localPath: root, query: "" })
+    const names = paths.map((p) => p.path).sort()
+    expect(names).toEqual(["a.txt", "src/"])
+    expect(paths.find((p) => p.path === "src/")?.kind).toBe("dir")
+    expect(paths.find((p) => p.path === "a.txt")?.kind).toBe("file")
+  })
+
+  test("git repo: returns tracked files + derived dirs", async () => {
+    const root = await makeTempDir("kanna-paths-git-")
+    await $`git init -q`.cwd(root)
+    await $`git -c user.email=t@t -c user.name=t commit -q --allow-empty -m init`.cwd(root)
+    await mkdir(path.join(root, "src"))
+    await writeFile(path.join(root, "src", "agent.ts"), "x")
+    await writeFile(path.join(root, "README.md"), "r")
+    await $`git add .`.cwd(root)
+    await $`git -c user.email=t@t -c user.name=t commit -q -m add`.cwd(root)
+
+    const paths = await listProjectPaths({ projectId: "p2", localPath: root, query: "agent" })
+    const names = paths.map((p) => p.path)
+    expect(names).toContain("src/agent.ts")
+  })
+
+  test("git repo: respects .gitignore for untracked files", async () => {
+    const root = await makeTempDir("kanna-paths-ignore-")
+    await $`git init -q`.cwd(root)
+    await writeFile(path.join(root, ".gitignore"), "node_modules\n")
+    await mkdir(path.join(root, "node_modules"))
+    await writeFile(path.join(root, "node_modules", "junk.js"), "x")
+    await writeFile(path.join(root, "app.ts"), "x")
+
+    const paths = await listProjectPaths({ projectId: "p3", localPath: root, query: "junk" })
+    expect(paths.map((p) => p.path)).not.toContain("node_modules/junk.js")
+  })
+
+  test("fuzzy ranking: prefix matches before substring matches", async () => {
+    const root = await makeTempDir("kanna-paths-rank-")
+    await writeFile(path.join(root, "review.ts"), "")
+    await writeFile(path.join(root, "unreview.ts"), "")
+
+    const paths = await listProjectPaths({ projectId: "p4", localPath: root, query: "rev" })
+    expect(paths.map((p) => p.path)).toEqual(["review.ts", "unreview.ts"])
+  })
+
+  test("respects limit", async () => {
+    const root = await makeTempDir("kanna-paths-limit-")
+    for (let i = 0; i < 10; i++) {
+      await writeFile(path.join(root, `file-${i}.txt`), "")
+    }
+
+    const paths = await listProjectPaths({ projectId: "p5", localPath: root, query: "file", limit: 3 })
+    expect(paths.length).toBe(3)
+  })
+
+  test("cache returns from memory on repeat call", async () => {
+    const root = await makeTempDir("kanna-paths-cache-")
+    await writeFile(path.join(root, "a.txt"), "")
+
+    const first = await listProjectPaths({ projectId: "p6", localPath: root, query: "a" })
+    await writeFile(path.join(root, "b.txt"), "") // added after first call
+    const second = await listProjectPaths({ projectId: "p6", localPath: root, query: "b" })
+
+    expect(first.map((p) => p.path)).toContain("a.txt")
+    expect(second.map((p) => p.path)).not.toContain("b.txt")
+  })
+})