@cuongtran001/kanna 1.2.0 → 1.3.1

package/src/server/ws-router-skills.test.ts

@@ -0,0 +1,194 @@
+import { 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 {
+  assertSafeSkillId,
+  assertSafeSkillSource,
+  buildInstallSkillCommand,
+  buildUninstallSkillCommand,
+  getGlobalSkillLockPath,
+  listInstalledSkills,
+  parseInstalledSkillsLock,
+} from "./ws-router-skills"
+
+describe("ws-router-skills", () => {
+  describe("assertSafeSkillSource", () => {
+    test("trims and accepts valid owner/repo pairs", () => {
+      expect(assertSafeSkillSource("owner/repo")).toBe("owner/repo")
+      expect(assertSafeSkillSource(" owner/repo ")).toBe("owner/repo")
+      expect(assertSafeSkillSource("Org-Name/my.skill_1")).toBe("Org-Name/my.skill_1")
+    })
+
+    test("rejects invalid sources", () => {
+      expect(() => assertSafeSkillSource("https://github.com/owner/repo")).toThrow("owner/repo")
+      expect(() => assertSafeSkillSource("just-a-name")).toThrow("owner/repo")
+      expect(() => assertSafeSkillSource("")).toThrow()
+      expect(() => assertSafeSkillSource("owner/repo/extra")).toThrow()
+    })
+  })
+
+  describe("assertSafeSkillId", () => {
+    test("trims and accepts valid skill ids", () => {
+      expect(assertSafeSkillId("my-skill")).toBe("my-skill")
+      expect(assertSafeSkillId(" my-skill_1 ")).toBe("my-skill_1")
+      expect(assertSafeSkillId("A")).toBe("A")
+    })
+
+    test("rejects invalid skill ids", () => {
+      expect(() => assertSafeSkillId("../nope")).toThrow("Skill id is invalid.")
+      expect(() => assertSafeSkillId("")).toThrow()
+      expect(() => assertSafeSkillId("-bad-start")).toThrow()
+    })
+  })
+
+  describe("getGlobalSkillLockPath", () => {
+    test("returns XDG_STATE_HOME path when env var is set", () => {
+      const orig = process.env.XDG_STATE_HOME
+      try {
+        process.env.XDG_STATE_HOME = "/custom/state"
+        const lockPath = getGlobalSkillLockPath()
+        expect(lockPath).toContain("/custom/state")
+        expect(lockPath).toContain(".skill-lock.json")
+      } finally {
+        if (orig === undefined) {
+          delete process.env.XDG_STATE_HOME
+        } else {
+          process.env.XDG_STATE_HOME = orig
+        }
+      }
+    })
+
+    test("falls back to ~/.agents/.skill-lock.json", () => {
+      const orig = process.env.XDG_STATE_HOME
+      try {
+        delete process.env.XDG_STATE_HOME
+        const lockPath = getGlobalSkillLockPath()
+        expect(lockPath).toContain(".agents")
+        expect(lockPath).toContain(".skill-lock.json")
+      } finally {
+        if (orig !== undefined) {
+          process.env.XDG_STATE_HOME = orig
+        }
+      }
+    })
+  })
+
+  describe("parseInstalledSkillsLock", () => {
+    test("parses installed global skills from a lock payload", () => {
+      const snapshot = parseInstalledSkillsLock({
+        version: 1,
+        skills: {
+          zeta: {
+            source: "owner/zeta",
+            sourceType: "github",
+            sourceUrl: "https://github.com/owner/zeta",
+            skillPath: "skills/zeta/SKILL.md",
+            installedAt: "2026-05-01T01:00:00.000Z",
+            updatedAt: "2026-05-01T02:00:00.000Z",
+            pluginName: "zeta-plugin",
+          },
+          alpha: {
+            source: "owner/alpha",
+            sourceType: "github",
+          },
+          ignored: "not an object",
+        },
+      }, "/tmp/.skill-lock.json")
+
+      expect(snapshot.lockFilePath).toBe("/tmp/.skill-lock.json")
+      // Skills are sorted alphabetically
+      expect(snapshot.skills.map((s) => s.name)).toEqual(["alpha", "zeta"])
+      expect(snapshot.skills[0]).toMatchObject({
+        name: "alpha",
+        source: "owner/alpha",
+        sourceType: "github",
+        sourceUrl: "",
+        installedAt: "",
+        updatedAt: "",
+      })
+      expect(snapshot.skills[1]).toMatchObject({
+        name: "zeta",
+        source: "owner/zeta",
+        skillPath: "skills/zeta/SKILL.md",
+        pluginName: "zeta-plugin",
+      })
+    })
+
+    test("returns empty skills list for invalid/null input", () => {
+      expect(parseInstalledSkillsLock(null, "/path").skills).toEqual([])
+      expect(parseInstalledSkillsLock("string", "/path").skills).toEqual([])
+      expect(parseInstalledSkillsLock({}, "/path").skills).toEqual([])
+      expect(parseInstalledSkillsLock({ skills: [] }, "/path").skills).toEqual([])
+    })
+  })
+
+  describe("listInstalledSkills", () => {
+    test("returns empty snapshot when lock file is missing", async () => {
+      const dir = await mkdtemp(path.join(tmpdir(), "kanna-skills-"))
+      try {
+        const missingPath = path.join(dir, "missing.json")
+        const result = await listInstalledSkills(missingPath)
+        expect(result).toEqual({ lockFilePath: missingPath, skills: [] })
+      } finally {
+        await rm(dir, { recursive: true, force: true })
+      }
+    })
+
+    test("returns empty snapshot when lock file is invalid JSON", async () => {
+      const dir = await mkdtemp(path.join(tmpdir(), "kanna-skills-"))
+      try {
+        const invalidPath = path.join(dir, ".skill-lock.json")
+        await writeFile(invalidPath, "{", "utf8")
+        const result = await listInstalledSkills(invalidPath)
+        expect(result).toEqual({ lockFilePath: invalidPath, skills: [] })
+      } finally {
+        await rm(dir, { recursive: true, force: true })
+      }
+    })
+  })
+
+  describe("buildInstallSkillCommand", () => {
+    test("builds global install command for universal and claude-code aliases", () => {
+      const cmd = buildInstallSkillCommand("owner/repo", "my-skill")
+      // First element is the binary (platform-dependent), skip it
+      expect(cmd.slice(1)).toEqual([
+        "skills",
+        "add",
+        "owner/repo",
+        "--skill",
+        "my-skill",
+        "--global",
+        "--agent",
+        "universal",
+        "claude-code",
+        "--yes",
+      ])
+    })
+
+    test("throws on invalid source or skillId", () => {
+      expect(() => buildInstallSkillCommand("https://github.com/o/r", "skill")).toThrow()
+      expect(() => buildInstallSkillCommand("owner/repo", "../bad")).toThrow()
+    })
+  })
+
+  describe("buildUninstallSkillCommand", () => {
+    test("builds global uninstall command for universal and claude-code aliases", () => {
+      const cmd = buildUninstallSkillCommand("my-skill")
+      expect(cmd.slice(1)).toEqual([
+        "skills",
+        "remove",
+        "my-skill",
+        "--global",
+        "--agent",
+        "universal",
+        "claude-code",
+        "--yes",
+      ])
+    })
+
+    test("throws on invalid skillId", () => {
+      expect(() => buildUninstallSkillCommand("../bad")).toThrow()
+    })
+  })
+})

package/src/server/ws-router-skills.ts

@@ -0,0 +1,204 @@
+/**
+ * ws-router-skills.ts
+ *
+ * Pure skill-management utilities extracted from ws-router.ts.
+ * No closure dependencies from createWsRouter — safe to test in isolation.
+ *
+ * Covers: assertSafeSkill*, getGlobalSkillLockPath, parseInstalledSkillsLock,
+ * listInstalledSkills, searchSkills, buildInstall/UninstallSkillCommand,
+ * installSkill, uninstallSkill.
+ */
+import os from "node:os"
+import path from "node:path"
+import type { AnyValue } from "../shared/errors"
+import { isRecord } from "../shared/errors"
+import { readTextFileOrThrow, spawnCommandCapture } from "./ws-router-io.adapter"
+import type { InstalledSkillsSnapshot, SkillInstallResult, SkillSearchSnapshot, SkillUninstallResult } from "../shared/types"
+
+const SKILL_AGENT_ALIASES = ["universal", "claude-code"] as const
+
+export function assertSafeSkillSource(source: string) {
+  const normalized = source.trim()
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(normalized)) {
+    throw new Error("Skill source must be an owner/repo pair.")
+  }
+  return normalized
+}
+
+export function assertSafeSkillId(skillId: string) {
+  const normalized = skillId.trim()
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(normalized)) {
+    throw new Error("Skill id is invalid.")
+  }
+  return normalized
+}
+
+export function getGlobalSkillLockPath() {
+  const xdgStateHome = process.env.XDG_STATE_HOME?.trim()
+  if (xdgStateHome) {
+    return path.join(xdgStateHome, "skills", ".skill-lock.json")
+  }
+  return path.join(os.homedir(), ".agents", ".skill-lock.json")
+}
+
+function asString(value: AnyValue) {
+  return typeof value === "string" ? value : ""
+}
+
+export function parseInstalledSkillsLock(parsed: AnyValue, lockFilePath: string): InstalledSkillsSnapshot {
+  const skillsRaw = isRecord(parsed) && isRecord(parsed.skills) && !Array.isArray(parsed.skills)
+    ? parsed.skills
+    : null
+  const skillsRecord: Record<string, AnyValue> = skillsRaw ?? {}
+
+  const skills = Object.entries(skillsRecord)
+    .filter(([, entry]) => entry && typeof entry === "object" && !Array.isArray(entry))
+    .map(([name, entry]) => {
+      const record: Record<string, AnyValue> = isRecord(entry) ? entry : {}
+      return {
+        name,
+        source: asString(record.source),
+        sourceType: asString(record.sourceType),
+        sourceUrl: asString(record.sourceUrl),
+        skillPath: asString(record.skillPath) || undefined,
+        installedAt: asString(record.installedAt),
+        updatedAt: asString(record.updatedAt),
+        pluginName: asString(record.pluginName) || undefined,
+      }
+    })
+    .sort((a, b) => a.name.localeCompare(b.name))
+
+  return {
+    lockFilePath,
+    skills,
+  }
+}
+
+export async function listInstalledSkills(lockFilePath = getGlobalSkillLockPath()): Promise<InstalledSkillsSnapshot> {
+  try {
+    return parseInstalledSkillsLock(JSON.parse(await readTextFileOrThrow(lockFilePath)), lockFilePath)
+  } catch {
+    return {
+      lockFilePath,
+      skills: [],
+    }
+  }
+}
+
+export async function searchSkills(query: string, limit = 100): Promise<SkillSearchSnapshot> {
+  const normalizedQuery = query.trim()
+  if (normalizedQuery.length < 2) {
+    return {
+      query: normalizedQuery,
+      searchType: "fuzzy",
+      skills: [],
+      count: 0,
+      duration_ms: 0,
+    }
+  }
+
+  const normalizedLimit = Math.max(1, Math.min(100, Math.trunc(limit)))
+  const url = new URL("https://skills.sh/api/search")
+  url.searchParams.set("q", normalizedQuery)
+  url.searchParams.set("limit", String(normalizedLimit))
+
+  const response = await fetch(url, {
+    signal: AbortSignal.timeout(10_000),
+  })
+  if (!response.ok) {
+    throw new Error(`Skills search failed with status ${response.status}.`)
+  }
+
+  const payload: Partial<SkillSearchSnapshot> = await response.json()
+  return {
+    query: typeof payload.query === "string" ? payload.query : normalizedQuery,
+    searchType: typeof payload.searchType === "string" ? payload.searchType : "fuzzy",
+    skills: Array.isArray(payload.skills)
+      ? payload.skills
+        .filter((skill) => (
+          skill
+          && typeof skill === "object"
+          && typeof skill.id === "string"
+          && typeof skill.skillId === "string"
+          && typeof skill.name === "string"
+          && typeof skill.source === "string"
+        ))
+        .map((skill) => ({
+          id: skill.id,
+          skillId: skill.skillId,
+          name: skill.name,
+          installs: typeof skill.installs === "number" ? skill.installs : 0,
+          source: skill.source,
+        }))
+      : [],
+    count: typeof payload.count === "number" ? payload.count : 0,
+    duration_ms: typeof payload.duration_ms === "number" ? payload.duration_ms : 0,
+  }
+}
+
+export function buildInstallSkillCommand(source: string, skillId: string) {
+  return [
+    process.platform === "win32" ? "npx.cmd" : "npx",
+    "skills",
+    "add",
+    assertSafeSkillSource(source),
+    "--skill",
+    assertSafeSkillId(skillId),
+    "--global",
+    "--agent",
+    ...SKILL_AGENT_ALIASES,
+    "--yes",
+  ]
+}
+
+export function buildUninstallSkillCommand(skillId: string) {
+  return [
+    process.platform === "win32" ? "npx.cmd" : "npx",
+    "skills",
+    "remove",
+    assertSafeSkillId(skillId),
+    "--global",
+    "--agent",
+    ...SKILL_AGENT_ALIASES,
+    "--yes",
+  ]
+}
+
+async function runSkillCommand(command: string[]) {
+  const cwd = os.homedir()
+  const { stdout, stderr, exitCode } = await spawnCommandCapture(command, cwd, {
+    ...process.env,
+    DISABLE_TELEMETRY: process.env.DISABLE_TELEMETRY ?? "1",
+  })
+
+  if (exitCode !== 0) {
+    throw new Error(stderr.trim() || stdout.trim() || `skills CLI exited with code ${exitCode}.`)
+  }
+
+  return { cwd, stdout, stderr }
+}
+
+export async function installSkill(source: string, skillId: string): Promise<SkillInstallResult> {
+  const command = buildInstallSkillCommand(source, skillId)
+  const { cwd, stdout, stderr } = await runSkillCommand(command)
+  return {
+    source: command[3],
+    skillId: command[5],
+    command,
+    cwd,
+    stdout,
+    stderr,
+  }
+}
+
+export async function uninstallSkill(skillId: string): Promise<SkillUninstallResult> {
+  const command = buildUninstallSkillCommand(skillId)
+  const { cwd, stdout, stderr } = await runSkillCommand(command)
+  return {
+    skillId: command[3],
+    command,
+    cwd,
+    stdout,
+    stderr,
+  }
+}

package/src/server/ws-router-utils.ts

@@ -0,0 +1,224 @@
+/**
+ * Pure utilities for ws-router — no closure over createWsRouter state.
+ * Extracted from ws-router.ts to reduce its size.
+ */
+import type { ServerWebSocket } from "bun"
+import { log } from "../shared/log"
+import type { SidebarData } from "../shared/types"
+import { PROTOCOL_VERSION } from "../shared/types"
+import type { ServerEnvelope, SubscriptionTopic } from "../shared/protocol"
+import type { EventStore } from "./event-store"
+
+// ── Shared interfaces ──────────────────────────────────────────────────────────
+
+export interface ClientState {
+  subscriptions: Map<string, SubscriptionTopic>
+  snapshotSignatures: Map<string, string>
+  protectedDraftChatIds?: Set<string>
+  pushDeviceId?: string | null
+  originHost?: string
+}
+
+export interface SnapshotBroadcastFilter {
+  includeSidebar?: boolean
+  includeLocalProjects?: boolean
+  includeUpdate?: boolean
+  includeKeybindings?: boolean
+  includeAppSettings?: boolean
+  includePushConfig?: boolean
+  chatIds?: Set<string>
+  projectIds?: Set<string>
+  terminalIds?: Set<string>
+}
+
+export interface SnapshotComputationCache {
+  sidebar?: {
+    data: SidebarData
+    signature: string
+  }
+}
+
+// ── Profiling helpers ─────────────────────────────────────────────────────────
+
+export function isSendToStartingProfilingEnabled(): boolean {
+  return process.env.KANNA_PROFILE_SEND_TO_STARTING === "1"
+}
+
+export function logSendToStartingProfile(
+  traceId: string | null | undefined,
+  startedAt: number | null | undefined,
+  stage: string,
+  details?: Record<string, unknown>
+): void {
+  if (!traceId || startedAt === undefined || startedAt === null || !isSendToStartingProfilingEnabled()) {
+    return
+  }
+
+  log.info("[kanna/send->starting][server]", JSON.stringify({
+    traceId,
+    stage,
+    elapsedMs: Number((performance.now() - startedAt).toFixed(1)),
+    ...details,
+  }))
+}
+
+// ── Subscription counting ─────────────────────────────────────────────────────
+
+export function countSubscriptionsByTopic(ws: ServerWebSocket<ClientState>): {
+  total: number
+  sidebar: number
+  chat: number
+  projectGit: number
+  localProjects: number
+  update: number
+  keybindings: number
+  appSettings: number
+  terminal: number
+} {
+  let sidebar = 0
+  let chat = 0
+  let projectGit = 0
+  let localProjects = 0
+  let update = 0
+  let keybindings = 0
+  let appSettings = 0
+  let terminal = 0
+
+  for (const topic of ws.data.subscriptions.values()) {
+    switch (topic.type) {
+      case "sidebar":
+        sidebar += 1
+        break
+      case "chat":
+        chat += 1
+        break
+      case "project-git":
+        projectGit += 1
+        break
+      case "local-projects":
+        localProjects += 1
+        break
+      case "update":
+        update += 1
+        break
+      case "keybindings":
+        keybindings += 1
+        break
+      case "app-settings":
+        appSettings += 1
+        break
+      case "terminal":
+        terminal += 1
+        break
+    }
+  }
+
+  return {
+    total: ws.data.subscriptions.size,
+    sidebar,
+    chat,
+    projectGit,
+    localProjects,
+    update,
+    keybindings,
+    appSettings,
+    terminal,
+  }
+}
+
+// ── Store helpers ─────────────────────────────────────────────────────────────
+
+export function getSidebarProjectOrder(store: EventStore): string[] {
+  return typeof store.getSidebarProjectOrder === "function"
+    ? store.getSidebarProjectOrder()
+    : []
+}
+
+// ── Stale-state detection ─────────────────────────────────────────────────────
+
+const BENIGN_STALE_STATE_MESSAGES = [
+  /^Chat not found$/,
+  /^Queued message not found$/,
+  /^File is no longer changed: /,
+  /^Project not found$/,
+] as const
+
+export function isBenignStaleStateMessage(message: string): boolean {
+  return BENIGN_STALE_STATE_MESSAGES.some((pattern) => pattern.test(message))
+}
+
+// ── WebSocket send helper ─────────────────────────────────────────────────────
+
+export function send(ws: ServerWebSocket<ClientState>, message: ServerEnvelope): number {
+  const payload = JSON.stringify(message)
+  ws.send(payload)
+  return payload.length
+}
+
+export function ensureSnapshotSignatures(
+  ws: ServerWebSocket<ClientState>
+): Map<string, string> {
+  if (!ws.data.snapshotSignatures) {
+    ws.data.snapshotSignatures = new Map()
+  }
+
+  return ws.data.snapshotSignatures
+}
+
+// ── Topic / envelope helpers ──────────────────────────────────────────────────
+
+export function shouldIncludeTopic(
+  topic: SubscriptionTopic,
+  filter?: SnapshotBroadcastFilter
+): boolean {
+  if (!filter) {
+    return true
+  }
+
+  if (topic.type === "sidebar") {
+    return Boolean(filter.includeSidebar)
+  }
+  if (topic.type === "local-projects") {
+    return Boolean(filter.includeLocalProjects)
+  }
+  if (topic.type === "update") {
+    return Boolean(filter.includeUpdate)
+  }
+  if (topic.type === "keybindings") {
+    return Boolean(filter.includeKeybindings)
+  }
+  if (topic.type === "app-settings") {
+    return Boolean(filter.includeAppSettings)
+  }
+  if (topic.type === "push-config") {
+    return Boolean(filter.includePushConfig)
+  }
+  if (topic.type === "chat") {
+    return filter.chatIds?.has(topic.chatId) ?? false
+  }
+  if (topic.type === "project-git") {
+    return filter.projectIds?.has(topic.projectId) ?? false
+  }
+  if (topic.type === "terminal") {
+    return filter.terminalIds?.has(topic.terminalId) ?? false
+  }
+
+  return true
+}
+
+// timings.derivedAtMs = Date.now() on every call, making every snapshot unique
+// and defeating signature-based dedup. Strip timings from the signature so that
+// idle/finished chats are only sent once instead of on every broadcastSnapshots call.
+export function getStableChatSnapshotSignature(
+  snapshot: Extract<ServerEnvelope, { type: "snapshot" }>["snapshot"]
+): string {
+  if (snapshot.type === "chat" && snapshot.data?.runtime) {
+    const { timings: _t, ...stableRuntime } = snapshot.data.runtime
+    return JSON.stringify({ type: snapshot.type, data: { ...snapshot.data, runtime: stableRuntime } })
+  }
+  return JSON.stringify(snapshot)
+}
+
+// Re-export PROTOCOL_VERSION so callers that import from utils don't need a
+// second import just for the protocol version.
+export { PROTOCOL_VERSION }