kcg-code 0.0.0-stage → 0.1.0

package/src/lib/__tests__/skills-catalog.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Unit test helper katalog skill (src/lib/skills-catalog.ts).
+ */
+import { describe, expect, test } from "bun:test";
+import type { SkillInfo } from "@/server/services/opencode-client";
+import type { RegistrySkill } from "@/server/services/skills-registry";
+import type { Project } from "@/types";
+import {
+  formatInstalls,
+  githubOwner,
+  installedProjectSkillNames,
+  isInstalled,
+  resolveSkillsProject,
+  visibleInstalledSkills,
+} from "../skills-catalog";
+
+describe("formatInstalls", () => {
+  test("ringkas per ribuan / jutaan", () => {
+    expect(formatInstalls(0)).toBe("0");
+    expect(formatInstalls(950)).toBe("950");
+    expect(formatInstalls(1000)).toBe("1K");
+    expect(formatInstalls(1234)).toBe("1.2K");
+    expect(formatInstalls(752_553)).toBe("753K");
+    expect(formatInstalls(1_300_000)).toBe("1.3M");
+  });
+});
+
+describe("deteksi terpasang", () => {
+  const skills: SkillInfo[] = [
+    {
+      name: "find-skills",
+      description: null,
+      location: "/p/.agents/skills/find-skills/SKILL.md",
+      source: "project",
+    },
+    { name: "Global-One", description: null, location: "/home/u/.config/x", source: "global" },
+    { name: "builtin", description: null, location: null, source: "builtin" },
+  ];
+  const reg = (skillId: string, name = skillId): RegistrySkill => ({
+    id: `a/b/${skillId}`,
+    name,
+    source: "a/b",
+    skillId,
+    installs: 1,
+    url: "",
+  });
+
+  test("hanya skill sumber project yang dihitung, case-insensitive", () => {
+    const names = installedProjectSkillNames(skills);
+    expect([...names]).toEqual(["find-skills"]);
+    expect(isInstalled(reg("FIND-SKILLS"), names)).toBe(true);
+    expect(isInstalled(reg("other", "find-skills"), names)).toBe(true);
+    expect(isInstalled(reg("global-one"), names)).toBe(false);
+  });
+});
+
+describe("resolveSkillsProject", () => {
+  const p = (id: string): Project => ({ id, name: id, path: `/${id}`, createdAt: 1 });
+  const projects = [p("a"), p("b")];
+
+  test("URL menang, lalu tersimpan; id tak dikenal dilewati", () => {
+    expect(resolveSkillsProject(projects, "b", "a")?.id).toBe("b");
+    expect(resolveSkillsProject(projects, "gone", "a")?.id).toBe("a");
+    expect(resolveSkillsProject(projects, null, "gone")).toBeNull();
+    expect(resolveSkillsProject(projects, null, null)).toBeNull();
+  });
+
+  test("satu-satunya Project dipilih otomatis", () => {
+    expect(resolveSkillsProject([p("only")], null, null)?.id).toBe("only");
+    expect(resolveSkillsProject([], null, null)).toBeNull();
+  });
+});
+
+describe("githubOwner", () => {
+  test("owner/repo -> owner; domain / bentuk lain -> null", () => {
+    expect(githubOwner("vercel-labs/skills")).toBe("vercel-labs");
+    expect(githubOwner("mintlify.com")).toBeNull();
+    expect(githubOwner("a/b/c")).toBeNull();
+  });
+});
+
+describe("visibleInstalledSkills", () => {
+  const s = (name: string, source: SkillInfo["source"], description: string | null = null) => ({
+    name,
+    description,
+    location: null,
+    source,
+  });
+  const all = [s("g1", "global"), s("builtin", "builtin"), s("p1", "project", "React helper")];
+
+  test("tanpa bawaan, project dulu, filter nama/deskripsi", () => {
+    expect(visibleInstalledSkills(all, "").map((x) => x.name)).toEqual(["p1", "g1"]);
+    expect(visibleInstalledSkills(all, "react").map((x) => x.name)).toEqual(["p1"]);
+    expect(visibleInstalledSkills(all, "G1").map((x) => x.name)).toEqual(["g1"]);
+  });
+});

package/src/lib/__tests__/tone.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { BASE_FREQUENCY, scaleFrequency } from "../tone";
+
+describe("scaleFrequency", () => {
+  test("penanda pertama = nada dasar, makin ke bawah makin tinggi", () => {
+    expect(scaleFrequency(0)).toBeCloseTo(BASE_FREQUENCY, 2);
+    const freqs = [0, 1, 2, 3, 4, 5, 6, 7].map((i) => scaleFrequency(i));
+    for (let i = 1; i < freqs.length; i++) {
+      expect(freqs[i]).toBeGreaterThan(freqs[i - 1] as number);
+    }
+  });
+
+  test("nada mayor: langkah ke-3 (fa) = 5 semiton, oktaf penuh = 2x dasar", () => {
+    expect(scaleFrequency(3)).toBeCloseTo(BASE_FREQUENCY * 2 ** (5 / 12), 2);
+    expect(scaleFrequency(7)).toBeCloseTo(BASE_FREQUENCY * 2, 2);
+  });
+
+  test("ditahan di dua oktaf: tidak melengking & tidak turun lagi", () => {
+    // Derajat ke-14 = do dua oktaf di atas dasar; di atas itu nadanya sama.
+    expect(scaleFrequency(14)).toBeCloseTo(BASE_FREQUENCY * 4, 2);
+    expect(scaleFrequency(20)).toBeCloseTo(scaleFrequency(14), 2);
+    expect(scaleFrequency(1000)).toBeCloseTo(scaleFrequency(14), 2);
+    // Tidak pernah menurun (rail panjang tetap terasa menaik).
+    let prev = 0;
+    for (let i = 0; i < 40; i++) {
+      const f = scaleFrequency(i);
+      expect(f).toBeGreaterThanOrEqual(prev);
+      expect(f).toBeLessThanOrEqual(BASE_FREQUENCY * 4 + 0.01);
+      prev = f;
+    }
+  });
+
+  test("index negatif / pecahan tetap aman", () => {
+    expect(scaleFrequency(-5)).toBeCloseTo(BASE_FREQUENCY, 2);
+    expect(scaleFrequency(1.9)).toBeCloseTo(scaleFrequency(1), 2);
+  });
+});

package/src/lib/__tests__/turns-delta.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Unit test penerapan delta streaming di sisi Client (`appendMessagePartDelta`)
+ * — logika murni, meniru urutan event opencode 1.x: part dibuat dengan teks
+ * kosong (`message_part`), lalu teks bertambah lewat `message_part_delta`.
+ */
+import { describe, expect, test } from "bun:test";
+import type { SessionMessage } from "@/types";
+import { appendMessagePartDelta, upsertMessagePart } from "../turns";
+
+function base(): SessionMessage[] {
+  return upsertMessagePart([], "s1", "msg_a1", { type: "text", id: "prt_t1", text: "" });
+}
+
+describe("appendMessagePartDelta", () => {
+  test("menambahkan delta berurutan ke field part", () => {
+    let msgs = base();
+    for (const d of ["Ku", "cing ", "lucu."]) {
+      msgs = appendMessagePartDelta(msgs, "msg_a1", "prt_t1", "text", d);
+    }
+    expect(msgs[0]?.parts[0]?.text).toBe("Kucing lucu.");
+    expect(msgs[0]?.streaming).toBe(true);
+  });
+
+  test("field belum ada diperlakukan sebagai string kosong", () => {
+    const msgs = upsertMessagePart([], "s1", "msg_a1", { type: "reasoning", id: "prt_r1" });
+    const next = appendMessagePartDelta(msgs, "msg_a1", "prt_r1", "text", "pikir");
+    expect(next[0]?.parts[0]?.text).toBe("pikir");
+  });
+
+  test("pesan/part tak dikenal atau delta kosong -> array yang sama", () => {
+    const msgs = base();
+    expect(appendMessagePartDelta(msgs, "msg_x", "prt_t1", "text", "a")).toBe(msgs);
+    expect(appendMessagePartDelta(msgs, "msg_a1", "prt_x", "text", "a")).toBe(msgs);
+    expect(appendMessagePartDelta(msgs, "msg_a1", "prt_t1", "text", "")).toBe(msgs);
+  });
+
+  test("tidak memutasi state sebelumnya", () => {
+    const msgs = base();
+    const before = JSON.stringify(msgs);
+    appendMessagePartDelta(msgs, "msg_a1", "prt_t1", "text", "hai");
+    expect(JSON.stringify(msgs)).toBe(before);
+  });
+
+  test("snapshot final (message_part) menggantikan hasil akumulasi", () => {
+    let msgs = base();
+    msgs = appendMessagePartDelta(msgs, "msg_a1", "prt_t1", "text", "Kuc");
+    msgs = upsertMessagePart(msgs, "s1", "msg_a1", {
+      type: "text",
+      id: "prt_t1",
+      text: "Kucing lucu.",
+    });
+    expect(msgs[0]?.parts).toHaveLength(1);
+    expect(msgs[0]?.parts[0]?.text).toBe("Kucing lucu.");
+  });
+});

package/src/lib/api.ts

@@ -0,0 +1,306 @@
+/**
+ * Helper fetch API KCG Code (task 24).
+ *
+ * - Kesalahan HTTP dilempar sebagai `ApiError` dengan `status` dan `code`
+ *   (dari body `{ error }`) agar komponen menampilkan pesan yang tepat.
+ */
+
+/** Error hasil permintaan API dengan status HTTP dan kode domain. */
+export class ApiError extends Error {
+  readonly status: number;
+  readonly code: string;
+  /** Body JSON respons error (detail tambahan, mis. daftar item penghalang). */
+  readonly body: Record<string, unknown> | null;
+
+  constructor(
+    status: number,
+    code: string,
+    message: string,
+    body?: Record<string, unknown> | null,
+  ) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.body = body ?? null;
+  }
+}
+
+/**
+ * Dipanggil saat server membalas 401 `AUTH_REQUIRED` (sesi habis / terkunci
+ * otomatis / dicabut) — lock screen dipasang oleh `lib/auth.ts`.
+ */
+let onAuthRequired: (() => void) | null = null;
+export function setAuthRequiredHandler(fn: (() => void) | null): void {
+  onAuthRequired = fn;
+}
+
+/** Pemetaan kode error domain -> pesan ramah pengguna (design.md — Error Handling). */
+export function apiErrorMessage(code: string): string {
+  // Kode dari server headless opencode membawa detail status, mis.
+  // "OC_LIST_MODELS_FAILED(500)" -> cocokkan berdasarkan prefiks.
+  if (code.startsWith("OC_LIST_MODELS_FAILED")) {
+    return "Failed to load the model list from the opencode server.";
+  }
+  if (code.startsWith("OC_CREATE_SESSION_FAILED")) {
+    return "Failed to create the session on the opencode server.";
+  }
+  if (code.startsWith("OC_DELETE_SESSION_FAILED")) {
+    return "Failed to delete the session on the opencode server.";
+  }
+  if (code.startsWith("SKILLS_SEARCH_FAILED") || code.startsWith("SKILLS_AUDIT_FAILED")) {
+    return "Couldn't reach skills.sh. Check your connection and try again.";
+  }
+  if (code.startsWith("SERVER_START_FAILED")) {
+    return "Failed to start the opencode server for this project.";
+  }
+
+  switch (code) {
+    case "NAME_REQUIRED":
+      return "Project name is required.";
+    case "NAME_TAKEN":
+      return "That project name is already in use.";
+    case "PATH_TAKEN":
+      return "That path is already used by another project.";
+    case "PATH_OUTSIDE_SANDBOX":
+      return "The path is outside the Sandbox root.";
+    case "INVALID_PATH_CHARS":
+      return "The path contains invalid characters.";
+    case "PROJECT_NOT_FOUND":
+      return "Project not found.";
+    case "PROJECT_DIR_NOT_FOUND":
+      return "The project directory was not found on the server.";
+    case "PROJECT_HAS_SESSIONS":
+      return "The project still has sessions. Delete them first.";
+    case "UNSUPPORTED_AGENT_TYPE":
+      return "This CLI_Agent type is not supported.";
+    case "SESSION_NOT_FOUND":
+      return "Session not found.";
+    case "SESSION_NOT_RUNNING":
+      return "The session is not running.";
+    case "SESSION_ALREADY_RUNNING":
+      return "The session is already running.";
+    case "MODEL_NOT_FOUND":
+      return "The model is not available on this project's opencode server.";
+    case "INVALID_INSTRUCTIONS":
+      return "Instructions must be text.";
+    case "INSTRUCTIONS_TOO_LONG":
+      return "Instructions are too long (max 20,000 characters).";
+    case "INVALID_SKILL_QUERY":
+      return "Type at least 2 characters to search.";
+    case "INVALID_SKILL_ID":
+      return "That skill identifier is not valid.";
+    case "SKILLS_RATE_LIMITED":
+      return "skills.sh is rate limiting requests. Wait a moment and try again.";
+    case "SKILL_INSTALL_IN_PROGRESS":
+      return "Another skill is being installed in this project. Try again when it finishes.";
+    case "SKILL_INSTALL_FAILED":
+      return "Failed to install the skill. See the output for details.";
+    case "SKILL_INSTALL_CANCELLED":
+      return "Installation was cancelled.";
+    case "SKILL_INSTALL_TIMEOUT":
+      return "Installation timed out and was stopped.";
+    case "INSTALL_JOB_NOT_RUNNING":
+      return "That installation has already finished.";
+    case "INSTALL_JOB_LOST":
+      return "The server restarted before the installation finished.";
+    case "INSTALL_JOB_NOT_FOUND":
+      return "That installation is no longer available.";
+    case "AUTH_REQUIRED":
+      return "Your session is locked. Unlock to continue.";
+    case "AUTH_INVALID":
+      return "Incorrect PIN or password.";
+    case "CURRENT_SECRET_INVALID":
+      return "Your current PIN or password is incorrect.";
+    case "AUTH_RATE_LIMITED":
+      return "Too many attempts. Wait a moment and try again.";
+    case "AUTH_NOT_CONFIGURED":
+      return "No lock has been set up yet.";
+    case "WORKSPACE_PATH_REQUIRED":
+      return "Enter a folder path.";
+    case "WORKSPACE_PATH_INVALID":
+      return "That path isn't valid.";
+    case "WORKSPACE_PATH_NOT_ABSOLUTE":
+      return "Use a full path, like ~/code or /srv/projects.";
+    case "WORKSPACE_NOT_FOUND":
+      return 'That folder doesn\'t exist. Tick "Create the folder" to make it.';
+    case "WORKSPACE_PARENT_NOT_FOUND":
+      return "The folder above it doesn't exist. Only the last folder can be created.";
+    case "WORKSPACE_NOT_DIRECTORY":
+      return "That path is a file, not a folder.";
+    case "WORKSPACE_TOO_BROAD":
+      return "That folder is too broad. Pick a dedicated folder, not your home or a system folder.";
+    case "WORKSPACE_CONTAINS_APP_DATA":
+      return "That folder overlaps KCG Code's own data. Pick a different folder.";
+    case "WORKSPACE_NOT_WRITABLE":
+      return "KCG Code can't write to that folder. Check its permissions.";
+    case "WORKSPACE_PROJECTS_OUTSIDE":
+      return "Some projects are outside the new folder. Remove them or pick a folder that contains them:";
+    case "WORKSPACE_CREATE_FAILED":
+      return "Couldn't create the folder.";
+    case "WORKSPACE_CONFIG_UNREADABLE":
+    case "WORKSPACE_CONFIG_WRITE_FAILED":
+      return "Couldn't save the config file. Check its permissions.";
+    case "PASSKEY_INVALID":
+      return "That passkey wasn't accepted. Try again or use your PIN or password.";
+    case "PASSKEY_NONE":
+      return "No passkey is set up for this address yet.";
+    case "PASSKEY_UNSUPPORTED_ORIGIN":
+      return "Passkeys need a secure address (https or localhost).";
+    case "PASSKEY_CHALLENGE_INVALID":
+      return "The passkey request expired. Try again.";
+    case "PASSKEY_VERIFY_FAILED":
+      return "Couldn't verify the passkey. Try again.";
+    case "PASSKEY_ALREADY_REGISTERED":
+      return "This passkey is already added.";
+    case "PASSKEY_LIMIT":
+      return "You've reached the maximum of 20 passkeys. Remove one first.";
+    case "PASSKEY_LOCK_REQUIRED":
+      return "Set up a PIN or password before adding a passkey.";
+    case "PASSKEY_NAME_INVALID":
+      return "Passkey names must be 1–60 characters.";
+    case "PASSKEY_NOT_FOUND":
+      return "That passkey no longer exists.";
+    case "PIN_DIGITS_ONLY":
+      return "PIN can only contain numbers.";
+    case "PIN_LENGTH":
+      return "PIN must be 6–12 digits.";
+    case "PIN_TOO_SIMPLE":
+      return "That PIN is too easy to guess. Avoid repeated or sequential digits.";
+    case "PASSWORD_TOO_SHORT":
+      return "Password must be at least 8 characters.";
+    case "PASSWORD_TOO_LONG":
+      return "Password must be at most 128 characters.";
+    case "NICKNAME_TOO_LONG":
+      return "Nickname must be at most 40 characters.";
+    case "NICKNAME_INVALID":
+      return "Nickname contains invalid characters.";
+    case "AVATAR_PRESET_INVALID":
+      return "That avatar isn't available.";
+    case "AVATAR_TOO_LARGE":
+      return "The photo exceeds the 2 MB limit.";
+    case "ORIGIN_FORBIDDEN":
+      return "Request blocked: it didn't come from this app.";
+    case "INVALID_JSON":
+      return "The request JSON format is invalid.";
+    case "UNSUPPORTED_IMAGE_MIME":
+      return "Unsupported image format. Use PNG, JPEG, GIF, or WebP.";
+    case "IMAGE_TOO_LARGE":
+      return "The image exceeds the 20 MiB limit.";
+    case "FILE_TOO_LARGE":
+      return "The file exceeds the 20 MiB limit.";
+    case "EMPTY_UPLOAD":
+      return "The file is empty.";
+    case "ATTACHMENT_NOT_FOUND":
+      return "The attachment was not found (it may have been deleted).";
+    case "TUNNEL_LOCK_REQUIRED":
+      return "Set an app lock before turning on remote access.";
+    case "TUNNEL_NOT_CONFIGURED":
+      return "Remote access isn't configured. Set KCG_TUNNEL_API_URL and restart kcgcode.";
+    case "TUNNEL_SIGNED_OUT":
+      return "Connect this machine first.";
+    case "TUNNEL_PAIRING_EXPIRED":
+      return "The code expired before it was approved. Connect again.";
+    case "TUNNEL_PAIRING_DENIED":
+      return "The request was denied on the sign-in page.";
+    case "TUNNEL_DEVICE_REVOKED":
+      return "This machine was disconnected from your account. Connect again.";
+    case "TUNNEL_RATE_LIMITED":
+      return "Too many attempts. Wait a few minutes and try again.";
+    case "TUNNEL_API_UNREACHABLE":
+      return "Couldn't reach the remote access service. Check your connection.";
+    case "TUNNEL_AUTH_FAILED":
+      return "The tunnel server rejected this device. Try rotating the secret.";
+    case "TUNNEL_PROXY_FAILED":
+      return "The tunnel server couldn't publish your address. See the log for details.";
+    case "FRPC_UNSUPPORTED_PLATFORM":
+      return "Remote access isn't supported on this OS or CPU yet.";
+    case "LHR_SSH_MISSING":
+      return "localhost.run needs the ssh command, which wasn't found on this computer.";
+    case "LHR_START_FAILED":
+      return "Couldn't start the connection to localhost.run.";
+    case "LHR_DENIED":
+      return "localhost.run refused the connection. Try again in a moment.";
+    case "INVALID_PROVIDER":
+      return "Unknown remote access option.";
+    case "FRPC_DOWNLOAD_FAILED":
+    case "FRPC_NOT_FOUND":
+      return "Couldn't install the tunnel client (frpc). See the log for details.";
+    case "FRPC_CHECKSUM_MISMATCH":
+      return "The downloaded tunnel client failed verification and was discarded.";
+    case "FRPC_START_FAILED":
+      return "Couldn't start the tunnel client. See the log for details.";
+    default:
+      return `Something went wrong (${code}).`;
+  }
+}
+
+/**
+ * `fetch` dengan header otentikasi & penanganan error terstruktur.
+ * Melempar `ApiError` untuk status selain 2xx.
+ */
+export async function apiFetch(path: string, init: RequestInit = {}): Promise<Response> {
+  const headers = new Headers(init.headers);
+  // FormData/Blob: browser yang menetapkan content-type (+ boundary multipart).
+  const browserTyped =
+    init.body instanceof FormData ||
+    init.body instanceof Blob ||
+    init.body instanceof URLSearchParams;
+  if (init.body != null && !browserTyped && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  const res = await fetch(path, { ...init, headers });
+  if (!res.ok) {
+    let code = `HTTP_${res.status}`;
+    let body: Record<string, unknown> | null = null;
+    try {
+      const parsed = (await res.json()) as unknown;
+      if (parsed && typeof parsed === "object") {
+        body = parsed as Record<string, unknown>;
+        if (typeof body.error === "string" && body.error !== "") code = body.error;
+      }
+    } catch {
+      // body bukan JSON — pakai kode HTTP default.
+    }
+    if (res.status === 401 && code === "AUTH_REQUIRED") onAuthRequired?.();
+    throw new ApiError(res.status, code, apiErrorMessage(code), body);
+  }
+  return res;
+}
+
+/**
+ * Upload satu file (jenis apa pun) ke endpoint lampiran Session.
+ * `fetch` multipart mengelola boundary-nya sendiri, jadi content-type TIDAK
+ * di-set manual.
+ */
+export async function apiUploadFile(
+  path: string,
+  file: File,
+): Promise<{ id: string; filename: string; mime: string; size: number }> {
+  const body = new FormData();
+  body.append("file", file);
+  const res = await fetch(path, { method: "POST", body });
+  if (!res.ok) {
+    let code = `HTTP_${res.status}`;
+    try {
+      const parsed = (await res.json()) as { error?: string };
+      if (typeof parsed.error === "string" && parsed.error !== "") code = parsed.error;
+    } catch {
+      // body bukan JSON — pakai kode HTTP default.
+    }
+    if (res.status === 401 && code === "AUTH_REQUIRED") onAuthRequired?.();
+    throw new ApiError(res.status, code, apiErrorMessage(code));
+  }
+  const parsed = (await res.json()) as {
+    upload?: { id: string; filename: string; mime: string; size: number };
+  };
+  if (typeof parsed.upload?.id !== "string") {
+    throw new ApiError(res.status, "INVALID_UPLOAD_RESPONSE", "Invalid upload response.");
+  }
+  return parsed.upload;
+}
+
+/** URL HTTP untuk memuat gambar lampiran di `<img>`. */
+export function attachmentUrl(sessionId: string, attachmentId: string): string {
+  return `/api/uploads/${encodeURIComponent(sessionId)}/${encodeURIComponent(attachmentId)}`;
+}