kanna-code 0.37.0 → 0.39.0

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

@@ -1,11 +1,19 @@
 import { describe, expect, test } from "bun:test"
-import { mkdtemp, rm } from "node:fs/promises"
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import path from "node:path"
 import type { AppSettingsSnapshot, KeybindingsSnapshot, LlmProviderSnapshot, UpdateSnapshot } from "../shared/types"
 import { PROTOCOL_VERSION } from "../shared/types"
 import { createEmptyState } from "./events"
-import { createWsRouter } from "./ws-router"
+import {
+  assertSafeSkillId,
+  assertSafeSkillSource,
+  buildInstallSkillCommand,
+  buildUninstallSkillCommand,
+  createWsRouter,
+  listInstalledSkills,
+  parseInstalledSkillsLock,
+} from "./ws-router"
 
 function withSidebarGroupDefaults(group: {
   groupKey: string
@@ -96,6 +104,99 @@ const DEFAULT_APP_SETTINGS_SNAPSHOT: AppSettingsSnapshot = {
   filePathDisplay: "~/.kanna/data/settings.json",
 }
 
+describe("skills helpers", () => {
+  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")
+    expect(snapshot.skills.map((skill) => skill.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 an empty installed skills snapshot when the lock file is missing or invalid", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "kanna-skills-"))
+    try {
+      const missingPath = path.join(dir, "missing.json")
+      expect(await listInstalledSkills(missingPath)).toEqual({
+        lockFilePath: missingPath,
+        skills: [],
+      })
+
+      const invalidPath = path.join(dir, ".skill-lock.json")
+      await writeFile(invalidPath, "{", "utf8")
+      expect(await listInstalledSkills(invalidPath)).toEqual({
+        lockFilePath: invalidPath,
+        skills: [],
+      })
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test("validates skill source and id before building commands", () => {
+    expect(assertSafeSkillSource(" owner/repo ")).toBe("owner/repo")
+    expect(assertSafeSkillId(" my-skill_1 ")).toBe("my-skill_1")
+    expect(() => assertSafeSkillSource("https://github.com/owner/repo")).toThrow("owner/repo")
+    expect(() => assertSafeSkillId("../nope")).toThrow("Skill id is invalid.")
+  })
+
+  test("builds global install and uninstall commands for universal and Claude Code aliases", () => {
+    expect(buildInstallSkillCommand("owner/repo", "my-skill").slice(1)).toEqual([
+      "skills",
+      "add",
+      "owner/repo",
+      "--skill",
+      "my-skill",
+      "--global",
+      "--agent",
+      "universal",
+      "claude-code",
+      "--yes",
+    ])
+    expect(buildUninstallSkillCommand("my-skill").slice(1)).toEqual([
+      "skills",
+      "remove",
+      "my-skill",
+      "--global",
+      "--agent",
+      "universal",
+      "claude-code",
+      "--yes",
+    ])
+  })
+})
+
 const DEFAULT_UPDATE_SNAPSHOT: UpdateSnapshot = {
   currentVersion: "0.12.0",
   latestVersion: null,

package/src/server/ws-router.ts

@@ -1,3 +1,6 @@
+import { readFile } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
 import type { ServerWebSocket } from "bun"
 import { PROTOCOL_VERSION } from "../shared/types"
 import type { ClientEnvelope, ServerEnvelope, SubscriptionTopic } from "../shared/protocol"
@@ -16,9 +19,19 @@ import { writeStandaloneTranscriptExport } from "./standalone-export"
 import { TerminalManager } from "./terminal-manager"
 import type { UpdateManager } from "./update-manager"
 import { deriveChatSnapshot, deriveLocalProjectsSnapshot, deriveSidebarData } from "./read-models"
-import type { AppSettingsPatch, AppSettingsSnapshot, LlmProviderSnapshot, LlmProviderValidationResult } from "../shared/types"
+import type {
+  AppSettingsPatch,
+  AppSettingsSnapshot,
+  InstalledSkillsSnapshot,
+  LlmProviderSnapshot,
+  LlmProviderValidationResult,
+  SkillInstallResult,
+  SkillSearchSnapshot,
+  SkillUninstallResult,
+} from "../shared/types"
 
 const DEFAULT_CHAT_RECENT_LIMIT = 200
+const SKILL_AGENT_ALIASES = ["universal", "claude-code"] as const
 
 function isSendToStartingProfilingEnabled() {
   return process.env.KANNA_PROFILE_SEND_TO_STARTING === "1"
@@ -149,6 +162,207 @@ function send(ws: ServerWebSocket<ClientState>, message: ServerEnvelope) {
   return payload.length
 }
 
+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: unknown) {
+  return typeof value === "string" ? value : ""
+}
+
+export function parseInstalledSkillsLock(parsed: unknown, lockFilePath: string): InstalledSkillsSnapshot {
+  const skillsRecord = parsed
+    && typeof parsed === "object"
+    && "skills" in parsed
+    && parsed.skills
+    && typeof parsed.skills === "object"
+    && !Array.isArray(parsed.skills)
+      ? parsed.skills as Record<string, unknown>
+      : {}
+
+  const skills = Object.entries(skillsRecord)
+    .filter(([, entry]) => entry && typeof entry === "object" && !Array.isArray(entry))
+    .map(([name, entry]) => {
+      const record = entry as Record<string, unknown>
+      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 readFile(lockFilePath, "utf8")), 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 = await response.json() as Partial<SkillSearchSnapshot>
+  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 subprocess = Bun.spawn(command, {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      ...process.env,
+      DISABLE_TELEMETRY: process.env.DISABLE_TELEMETRY ?? "1",
+    },
+  })
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(subprocess.stdout).text(),
+    new Response(subprocess.stderr).text(),
+    subprocess.exited,
+  ])
+
+  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,
+  }
+}
+
 function ensureSnapshotSignatures(ws: ServerWebSocket<ClientState>) {
   if (!ws.data.snapshotSignatures) {
     ws.data.snapshotSignatures = new Map()
@@ -913,6 +1127,26 @@ export function createWsRouter({
           send(ws, { v: PROTOCOL_VERSION, type: "ack", id, result })
           return
         }
+        case "skills.search": {
+          const snapshot = await searchSkills(command.query, command.limit)
+          send(ws, { v: PROTOCOL_VERSION, type: "ack", id, result: snapshot })
+          return
+        }
+        case "skills.install": {
+          const result = await installSkill(command.source, command.skillId)
+          send(ws, { v: PROTOCOL_VERSION, type: "ack", id, result })
+          return
+        }
+        case "skills.uninstall": {
+          const result = await uninstallSkill(command.skillId)
+          send(ws, { v: PROTOCOL_VERSION, type: "ack", id, result })
+          return
+        }
+        case "skills.listInstalled": {
+          const result = await listInstalledSkills()
+          send(ws, { v: PROTOCOL_VERSION, type: "ack", id, result })
+          return
+        }
         case "project.open": {
           await ensureProjectDirectory(command.localPath)
           const normalizedPath = resolveLocalPath(command.localPath)

package/src/shared/protocol.ts

@@ -68,6 +68,10 @@ export type ClientCommand =
   | { type: "settings.writeAppSettings"; analyticsEnabled: boolean }
   | { type: "settings.writeAppSettingsPatch"; patch: AppSettingsPatch }
   | { type: "settings.readLlmProvider" }
+  | { type: "skills.search"; query: string; limit?: number }
+  | { type: "skills.install"; source: string; skillId: string }
+  | { type: "skills.uninstall"; skillId: string }
+  | { type: "skills.listInstalled" }
   | {
       type: "settings.writeLlmProvider"
       provider: LlmProviderSnapshot["provider"]

package/src/shared/types.ts

@@ -15,6 +15,55 @@ export type AttachmentKind = "image" | "file"
 export type StandaloneTranscriptAttachmentMode = "metadata" | "bundle"
 export type StandaloneTranscriptTheme = "light" | "dark"
 
+export interface SkillSearchResult {
+  id: string
+  skillId: string
+  name: string
+  installs: number
+  source: string
+}
+
+export interface SkillSearchSnapshot {
+  query: string
+  searchType: string
+  skills: SkillSearchResult[]
+  count: number
+  duration_ms: number
+}
+
+export interface SkillInstallResult {
+  source: string
+  skillId: string
+  command: string[]
+  cwd: string
+  stdout: string
+  stderr: string
+}
+
+export interface SkillUninstallResult {
+  skillId: string
+  command: string[]
+  cwd: string
+  stdout: string
+  stderr: string
+}
+
+export interface InstalledSkillSummary {
+  name: string
+  source: string
+  sourceType: string
+  sourceUrl: string
+  skillPath?: string
+  installedAt: string
+  updatedAt: string
+  pluginName?: string
+}
+
+export interface InstalledSkillsSnapshot {
+  lockFilePath: string
+  skills: InstalledSkillSummary[]
+}
+
 export interface ChatAttachment {
   id: string
   kind: AttachmentKind