@skilltap/core 0.5.3 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilltap/core",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Core library for skilltap — agent skill management",
   "type": "module",
   "license": "MIT",

package/src/doctor.test.ts

@@ -4,6 +4,17 @@ import { join } from "node:path";
 import { makeTmpDir, removeTmpDir } from "@skilltap/test-utils";
 import { runDoctor } from "./doctor";
 
+const SKILL_RECORD = {
+  description: "",
+  ref: null,
+  sha: null,
+  path: null,
+  tap: null,
+  also: [],
+  installedAt: "2024-01-01T00:00:00.000Z",
+  updatedAt: "2024-01-01T00:00:00.000Z",
+};
+
 let homeDir: string;
 let configDir: string;
 
@@ -508,3 +519,191 @@ describe("runDoctor", () => {
     expect(called).toContain("npm");
   });
 });
+
+// ─── Per-project installed.json ───────────────────────────────────────────────
+
+describe("per-project: checkInstalled", () => {
+  let projectDir: string;
+
+  beforeEach(async () => {
+    projectDir = await makeTmpDir();
+  });
+
+  afterEach(async () => {
+    await removeTmpDir(projectDir);
+  });
+
+  test("counts project skills separately in detail", async () => {
+    await mkdir(join(projectDir, ".agents"), { recursive: true });
+    await writeFile(
+      join(projectDir, ".agents", "installed.json"),
+      JSON.stringify({
+        version: 1,
+        skills: [
+          {
+            ...SKILL_RECORD,
+            name: "proj-skill",
+            repo: "https://github.com/example/proj-skill",
+            scope: "project",
+          },
+        ],
+      }, null, 2),
+    );
+
+    const result = await runDoctor({ projectRoot: projectDir });
+    const check = result.checks.find((c) => c.name === "installed")!;
+    expect(check.status).toBe("pass");
+    expect(check.detail).toMatch(/1\s+skill/);
+    expect(check.detail).toContain("project");
+  });
+
+  test("fails when project installed.json is corrupt", async () => {
+    await mkdir(join(projectDir, ".agents"), { recursive: true });
+    await writeFile(join(projectDir, ".agents", "installed.json"), "bad json {{{");
+
+    const result = await runDoctor({ projectRoot: projectDir });
+    const check = result.checks.find((c) => c.name === "installed")!;
+    expect(check.status).toBe("fail");
+    expect(check.issues?.some((i) => i.message.includes("corrupt"))).toBe(true);
+  });
+
+  test("merges global and project skills", async () => {
+    const skilltapDir = join(configDir, "skilltap");
+    await mkdir(skilltapDir, { recursive: true });
+    await writeFile(
+      join(skilltapDir, "installed.json"),
+      JSON.stringify({
+        version: 1,
+        skills: [
+          {
+            ...SKILL_RECORD,
+            name: "global-skill",
+            repo: "https://github.com/example/global-skill",
+            scope: "global",
+          },
+        ],
+      }, null, 2),
+    );
+
+    await mkdir(join(projectDir, ".agents"), { recursive: true });
+    await writeFile(
+      join(projectDir, ".agents", "installed.json"),
+      JSON.stringify({
+        version: 1,
+        skills: [
+          {
+            ...SKILL_RECORD,
+            name: "proj-skill",
+            repo: "https://github.com/example/proj-skill",
+            scope: "project",
+          },
+        ],
+      }, null, 2),
+    );
+
+    const result = await runDoctor({ projectRoot: projectDir });
+    const check = result.checks.find((c) => c.name === "installed")!;
+    expect(check.status).toBe("pass");
+    expect(check.detail).toContain("2");
+    expect(check.detail).toContain("1 global");
+    expect(check.detail).toContain("1 project");
+  });
+});
+
+describe("per-project: checkSkills", () => {
+  let projectDir: string;
+
+  beforeEach(async () => {
+    projectDir = await makeTmpDir();
+  });
+
+  afterEach(async () => {
+    await removeTmpDir(projectDir);
+  });
+
+  test("warns when project skill directory is missing", async () => {
+    await mkdir(join(projectDir, ".agents"), { recursive: true });
+    await writeFile(
+      join(projectDir, ".agents", "installed.json"),
+      JSON.stringify({
+        version: 1,
+        skills: [
+          {
+            ...SKILL_RECORD,
+            name: "missing-proj-skill",
+            repo: "https://github.com/example/skill",
+            scope: "project",
+          },
+        ],
+      }, null, 2),
+    );
+
+    const result = await runDoctor({ projectRoot: projectDir });
+    const check = result.checks.find((c) => c.name === "skills")!;
+    expect(check.status).toBe("warn");
+    expect(
+      check.issues?.some((i) => i.message.includes("missing-proj-skill")),
+    ).toBe(true);
+    expect(
+      check.issues?.find((i) => i.message.includes("missing-proj-skill"))?.message,
+    ).toContain(join(projectDir, ".agents", "skills", "missing-proj-skill"));
+  });
+
+  test("passes when project skill directory exists", async () => {
+    await mkdir(join(projectDir, ".agents", "skills", "my-proj-skill"), { recursive: true });
+    await writeFile(
+      join(projectDir, ".agents", "installed.json"),
+      JSON.stringify({
+        version: 1,
+        skills: [
+          {
+            ...SKILL_RECORD,
+            name: "my-proj-skill",
+            repo: "https://github.com/example/skill",
+            scope: "project",
+          },
+        ],
+      }, null, 2),
+    );
+
+    const result = await runDoctor({ projectRoot: projectDir });
+    const check = result.checks.find((c) => c.name === "skills")!;
+    expect(check.status).toBe("pass");
+  });
+
+  test("detects orphan directories in project skills dir", async () => {
+    await mkdir(join(projectDir, ".agents", "skills", "orphan"), { recursive: true });
+    await writeFile(
+      join(projectDir, ".agents", "installed.json"),
+      JSON.stringify({
+        version: 1,
+        skills: [
+          {
+            ...SKILL_RECORD,
+            name: "tracked-skill",
+            repo: "https://github.com/example/skill",
+            scope: "project",
+          },
+        ],
+      }, null, 2),
+    );
+
+    const result = await runDoctor({ projectRoot: projectDir });
+    const check = result.checks.find((c) => c.name === "skills")!;
+    expect(check.status).toBe("warn");
+    expect(check.issues?.some((i) => i.message.includes("orphan"))).toBe(true);
+  });
+
+  test("does not scan project orphans when no project skills tracked", async () => {
+    // Project has a .agents/skills/ dir but no installed.json tracking project skills
+    await mkdir(join(projectDir, ".agents", "skills", "untracked"), { recursive: true });
+
+    const result = await runDoctor({ projectRoot: projectDir });
+    const check = result.checks.find((c) => c.name === "skills")!;
+    // No project skills tracked → no orphan scan → only global check runs
+    const orphanIssues = check.issues?.filter((i) =>
+      i.message.includes(join(projectDir, ".agents")),
+    ) ?? [];
+    expect(orphanIssues).toHaveLength(0);
+  });
+});

package/src/doctor.ts

@@ -49,6 +49,7 @@ export interface DoctorResult {
 
 export interface DoctorOptions {
   fix?: boolean;
+  projectRoot?: string;
   onCheck?: (check: DoctorCheck) => void;
 }
 
@@ -257,96 +258,105 @@ async function checkDirs(): Promise<DoctorCheck> {
 
 // ─── Check 4: installed.json ──────────────────────────────────────────────────
 
-async function checkInstalled(): Promise<{
-  check: DoctorCheck;
-  installed: InstalledJson | null;
-}> {
-  const installedFile = join(getConfigDir(), "installed.json");
-
-  if (!(await fileExists(installedFile))) {
-    return {
-      check: {
-        name: "installed",
-        status: "pass",
-        detail: "0 skills (no installed.json)",
-      },
-      installed: { version: 1, skills: [] },
-    };
-  }
+async function readInstalledFile(
+  file: string,
+  label: string,
+  issues: DoctorIssue[],
+): Promise<InstalledJson | null> {
+  if (!(await fileExists(file))) return null;
 
   let raw: unknown;
   try {
-    raw = await Bun.file(installedFile).json();
+    raw = await Bun.file(file).json();
   } catch (e) {
-    const backupFile = `${installedFile}.bak`;
-    return {
-      check: {
-        name: "installed",
-        status: "fail",
-        issues: [
-          {
-            message: `installed.json is corrupt: ${e}`,
-            fixable: true,
-            fixDescription: `backed up to installed.json.bak, created fresh`,
-            fix: async () => {
-              await copyFile(installedFile, backupFile).catch(() => {});
-              await writeFile(
-                installedFile,
-                JSON.stringify({ version: 1, skills: [] }, null, 2),
-              );
-            },
-          },
-        ],
+    const backupFile = `${file}.bak`;
+    const backupName = `${label}.bak`;
+    issues.push({
+      message: `${label} is corrupt: ${e}`,
+      fixable: true,
+      fixDescription: `backed up to ${backupName}, created fresh`,
+      fix: async () => {
+        await copyFile(file, backupFile).catch(() => {});
+        await writeFile(file, JSON.stringify({ version: 1, skills: [] }, null, 2));
       },
-      installed: null,
-    };
+    });
+    return null;
   }
 
   const result = InstalledJsonSchema.safeParse(raw);
   if (!result.success) {
-    const backupFile = `${installedFile}.bak`;
-    return {
-      check: {
-        name: "installed",
-        status: "fail",
-        issues: [
-          {
-            message: `installed.json is invalid: ${z.prettifyError(result.error)}`,
-            fixable: true,
-            fixDescription: `backed up to installed.json.bak, created fresh`,
-            fix: async () => {
-              await copyFile(installedFile, backupFile).catch(() => {});
-              await writeFile(
-                installedFile,
-                JSON.stringify({ version: 1, skills: [] }, null, 2),
-              );
-            },
-          },
-        ],
+    const backupFile = `${file}.bak`;
+    const backupName = `${label}.bak`;
+    issues.push({
+      message: `${label} is invalid: ${z.prettifyError(result.error)}`,
+      fixable: true,
+      fixDescription: `backed up to ${backupName}, created fresh`,
+      fix: async () => {
+        await copyFile(file, backupFile).catch(() => {});
+        await writeFile(file, JSON.stringify({ version: 1, skills: [] }, null, 2));
       },
-      installed: null,
-    };
+    });
+    return null;
   }
 
-  const { skills } = result.data;
-  return {
-    check: {
-      name: "installed",
-      status: "pass",
-      detail: `${skills.length} skill${skills.length === 1 ? "" : "s"}`,
-    },
-    installed: result.data,
-  };
+  return result.data;
+}
+
+async function checkInstalled(projectRoot?: string): Promise<{
+  check: DoctorCheck;
+  installed: InstalledJson | null;
+}> {
+  const globalFile = join(getConfigDir(), "installed.json");
+  const issues: DoctorIssue[] = [];
+
+  const globalInstalled = await readInstalledFile(globalFile, "installed.json", issues);
+  const projectInstalled = projectRoot
+    ? await readInstalledFile(
+        join(projectRoot, ".agents", "installed.json"),
+        ".agents/installed.json",
+        issues,
+      )
+    : null;
+
+  const allSkills = [
+    ...(globalInstalled?.skills ?? []),
+    ...(projectInstalled?.skills ?? []),
+  ];
+  const merged: InstalledJson = { version: 1 as const, skills: allSkills };
+
+  if (issues.length > 0) {
+    return { check: { name: "installed", status: "fail", issues }, installed: merged };
+  }
+
+  const globalCount = globalInstalled?.skills.length ?? 0;
+  const projectCount = projectInstalled?.skills.length ?? 0;
+  const total = allSkills.length;
+
+  let detail: string;
+  if (!globalInstalled && !projectInstalled) {
+    detail = "0 skills (no installed.json)";
+  } else if (projectInstalled !== null) {
+    detail = `${total} skill${total === 1 ? "" : "s"} (${globalCount} global, ${projectCount} project)`;
+  } else {
+    detail = `${total} skill${total === 1 ? "" : "s"}`;
+  }
+
+  return { check: { name: "installed", status: "pass", detail }, installed: merged };
 }
 
 // ─── Check 5: Skills Integrity ────────────────────────────────────────────────
 
-async function checkSkills(installed: InstalledJson): Promise<DoctorCheck> {
+async function checkSkills(installed: InstalledJson, projectRoot?: string): Promise<DoctorCheck> {
   const issues: DoctorIssue[] = [];
-  const trackedNames = new Set<string>();
+  const globalTracked = new Set<string>();
+  const projectTracked = new Set<string>();
 
   for (const skill of installed.skills) {
-    trackedNames.add(skill.name);
+    if (skill.scope === "project") {
+      projectTracked.add(skill.name);
+    } else if (skill.scope !== "linked") {
+      globalTracked.add(skill.name);
+    }
 
     if (skill.scope === "linked") {
       if (skill.path && !(await resolvedDirExists(skill.path))) {
@@ -368,35 +378,42 @@ async function checkSkills(installed: InstalledJson): Promise<DoctorCheck> {
       continue;
     }
 
-    const installDir = skillInstallDir(skill.name, "global");
+    const isProject = skill.scope === "project" && !!projectRoot;
+    const installDir = isProject
+      ? skillInstallDir(skill.name, "project", projectRoot)
+      : skillInstallDir(skill.name, "global");
+
     if (!(await resolvedDirExists(installDir))) {
       const skillName = skill.name;
+      const skillScope = skill.scope as "global" | "project";
+      const capturedRoot = projectRoot;
       issues.push({
         message: `${skillName}: recorded in installed.json but directory missing at ${installDir}`,
         fixable: true,
         fixDescription: `removed from installed.json`,
         fix: async () => {
-          const r = await loadInstalled();
+          const effectiveRoot = skillScope === "project" ? capturedRoot : undefined;
+          const r = await loadInstalled(effectiveRoot);
           if (!r.ok) return;
-          await saveInstalled({
-            ...r.value,
-            skills: r.value.skills.filter((s) => s.name !== skillName),
-          });
+          await saveInstalled(
+            { ...r.value, skills: r.value.skills.filter((s) => s.name !== skillName) },
+            effectiveRoot,
+          );
         },
       });
     }
   }
 
-  // Check for orphan directories
-  const skillsDir = join(globalBase(), ".agents", "skills");
-  if (await resolvedDirExists(skillsDir)) {
+  // Global orphan scan
+  const globalSkillsDir = join(globalBase(), ".agents", "skills");
+  if (await resolvedDirExists(globalSkillsDir)) {
     try {
-      const entries = await readdir(skillsDir, { withFileTypes: true });
+      const entries = await readdir(globalSkillsDir, { withFileTypes: true });
       for (const entry of entries) {
         if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-        if (!trackedNames.has(entry.name)) {
+        if (!globalTracked.has(entry.name)) {
           issues.push({
-            message: `${entry.name}: directory exists at ${join(skillsDir, entry.name)} but not tracked in installed.json`,
+            message: `${entry.name}: directory exists at ${join(globalSkillsDir, entry.name)} but not tracked in installed.json`,
             fixable: false,
           });
         }
@@ -406,6 +423,27 @@ async function checkSkills(installed: InstalledJson): Promise<DoctorCheck> {
     }
   }
 
+  // Project orphan scan (only when there are project-tracked skills)
+  if (projectRoot && projectTracked.size > 0) {
+    const projectSkillsDir = join(projectRoot, ".agents", "skills");
+    if (await resolvedDirExists(projectSkillsDir)) {
+      try {
+        const entries = await readdir(projectSkillsDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+          if (!projectTracked.has(entry.name)) {
+            issues.push({
+              message: `${entry.name}: directory exists at ${join(projectSkillsDir, entry.name)} but not tracked in installed.json`,
+              fixable: false,
+            });
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+
   const total = installed.skills.length;
   const missing = issues.filter((i) => i.fixable).length;
   const onDisk = total - missing;
@@ -427,7 +465,7 @@ async function checkSkills(installed: InstalledJson): Promise<DoctorCheck> {
 
 // ─── Check 6: Agent Symlinks ──────────────────────────────────────────────────
 
-async function checkSymlinks(installed: InstalledJson): Promise<DoctorCheck> {
+async function checkSymlinks(installed: InstalledJson, projectRoot?: string): Promise<DoctorCheck> {
   const issues: DoctorIssue[] = [];
   let total = 0;
   let valid = 0;
@@ -435,12 +473,17 @@ async function checkSymlinks(installed: InstalledJson): Promise<DoctorCheck> {
   for (const skill of installed.skills) {
     if (skill.also.length === 0) continue;
 
+    const isProject = skill.scope === "project" && !!projectRoot;
+    const expectedTarget = isProject
+      ? skillInstallDir(skill.name, "project", projectRoot)
+      : skillInstallDir(skill.name, "global");
+    const base = isProject ? projectRoot! : globalBase();
+
     for (const agent of skill.also) {
       const agentRelDir = AGENT_PATHS[agent];
       if (!agentRelDir) continue;
 
-      const expectedTarget = skillInstallDir(skill.name, "global");
-      const linkPath = join(globalBase(), agentRelDir, skill.name);
+      const linkPath = join(base, agentRelDir, skill.name);
       total++;
 
       const isLink = await isSymlinkAt(linkPath);
@@ -735,6 +778,7 @@ async function checkNpm(installed: InstalledJson): Promise<DoctorCheck | null> {
 export async function runDoctor(options?: DoctorOptions): Promise<DoctorResult> {
   const fix = options?.fix ?? false;
   const onCheck = options?.onCheck;
+  const projectRoot = options?.projectRoot;
   const checks: DoctorCheck[] = [];
 
   async function emit(check: DoctorCheck): Promise<DoctorCheck> {
@@ -766,17 +810,17 @@ export async function runDoctor(options?: DoctorOptions): Promise<DoctorResult>
   await emit(await checkDirs());
 
   // 4. installed.json (provides installed for later checks)
-  const { check: installedCheck, installed } = await checkInstalled();
+  const { check: installedCheck, installed } = await checkInstalled(projectRoot);
   await emit(installedCheck);
 
   const safeInstalled = installed ?? { version: 1 as const, skills: [] };
   const safeConfig = config ?? ConfigSchema.parse({});
 
   // 5. Skills integrity
-  await emit(await checkSkills(safeInstalled));
+  await emit(await checkSkills(safeInstalled, projectRoot));
 
   // 6. Agent symlinks
-  await emit(await checkSymlinks(safeInstalled));
+  await emit(await checkSymlinks(safeInstalled, projectRoot));
 
   // 7. Taps
   await emit(await checkTaps(safeConfig));

package/src/self-update.test.ts

@@ -0,0 +1,224 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { makeTmpDir, removeTmpDir } from "@skilltap/test-utils";
+import { checkForUpdate, downloadAndInstall, isCompiledBinary } from "./self-update";
+
+type Env = { XDG_CONFIG_HOME?: string };
+
+let savedEnv: Env;
+let configDir: string;
+let tmpDir: string;
+
+beforeEach(async () => {
+  savedEnv = { XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME };
+  configDir = await makeTmpDir();
+  tmpDir = await makeTmpDir();
+  process.env.XDG_CONFIG_HOME = configDir;
+  // Ensure the skilltap config subdir exists (writeCache needs it)
+  await mkdir(join(configDir, "skilltap"), { recursive: true });
+});
+
+afterEach(async () => {
+  if (savedEnv.XDG_CONFIG_HOME === undefined) delete process.env.XDG_CONFIG_HOME;
+  else process.env.XDG_CONFIG_HOME = savedEnv.XDG_CONFIG_HOME;
+  await removeTmpDir(configDir);
+  await removeTmpDir(tmpDir);
+});
+
+async function writeCache(latest: string, hoursAgo = 0): Promise<void> {
+  const checkedAt = new Date(Date.now() - hoursAgo * 3_600_000).toISOString();
+  await Bun.write(
+    join(configDir, "skilltap", "update-check.json"),
+    JSON.stringify({ checkedAt, latest }),
+  );
+}
+
+// ─── checkForUpdate ───────────────────────────────────────────────────────────
+
+describe("checkForUpdate", () => {
+  test("returns null when no cache file exists", async () => {
+    const result = await checkForUpdate("1.0.0");
+    expect(result).toBeNull();
+  });
+
+  test("returns null when cached version equals current", async () => {
+    await writeCache("1.0.0");
+    const result = await checkForUpdate("1.0.0");
+    expect(result).toBeNull();
+  });
+
+  test("returns null when cached version is older than current", async () => {
+    await writeCache("0.9.0");
+    const result = await checkForUpdate("1.0.0");
+    expect(result).toBeNull();
+  });
+
+  test("detects patch update", async () => {
+    await writeCache("1.0.1");
+    const result = await checkForUpdate("1.0.0");
+    expect(result).not.toBeNull();
+    expect(result?.type).toBe("patch");
+    expect(result?.current).toBe("1.0.0");
+    expect(result?.latest).toBe("1.0.1");
+  });
+
+  test("detects minor update", async () => {
+    await writeCache("1.1.0");
+    const result = await checkForUpdate("1.0.5");
+    expect(result?.type).toBe("minor");
+  });
+
+  test("detects major update", async () => {
+    await writeCache("2.0.0");
+    const result = await checkForUpdate("1.9.9");
+    expect(result?.type).toBe("major");
+  });
+
+  test("returns null when cache has malformed version", async () => {
+    await writeCache("not-a-version");
+    const result = await checkForUpdate("1.0.0");
+    expect(result).toBeNull();
+  });
+
+  test("returns null when current version is malformed", async () => {
+    await writeCache("1.0.1");
+    const result = await checkForUpdate("not-a-version");
+    expect(result).toBeNull();
+  });
+
+  test("returns cached data even when cache is stale (background refresh fires)", async () => {
+    // Write a stale cache (25 hours ago)
+    await writeCache("1.2.0", 25);
+    // Should still return the cached data (background fetch is fire-and-forget)
+    const result = await checkForUpdate("1.0.0", 24);
+    expect(result).not.toBeNull();
+    expect(result?.latest).toBe("1.2.0");
+  });
+
+  test("respects custom intervalHours — fresh cache not stale", async () => {
+    // Cache is 1 hour old; interval is 2 hours → not stale → no background fetch
+    await writeCache("2.0.0", 1);
+    const result = await checkForUpdate("1.0.0", 2);
+    expect(result).not.toBeNull();
+    expect(result?.type).toBe("major");
+  });
+});
+
+// ─── isCompiledBinary ─────────────────────────────────────────────────────────
+
+describe("isCompiledBinary", () => {
+  test("returns false when running under bun (test env)", () => {
+    // Tests run via `bun test`, so process.execPath is the bun binary
+    expect(isCompiledBinary()).toBe(false);
+  });
+});
+
+// ─── downloadAndInstall ───────────────────────────────────────────────────────
+
+const fakeBinary = new Uint8Array([0x7f, 0x45, 0x4c, 0x46]); // ELF magic bytes
+
+function okFetch(_url: string): Promise<Response> {
+  return Promise.resolve(new Response(fakeBinary, { status: 200 }));
+}
+
+function notFoundFetch(_url: string): Promise<Response> {
+  return Promise.resolve(new Response(null, { status: 404 }));
+}
+
+function networkErrorFetch(_url: string): Promise<Response> {
+  return Promise.reject(new Error("ECONNREFUSED: connection refused"));
+}
+
+describe("downloadAndInstall", () => {
+  test("returns error on HTTP 404", async () => {
+    const execPath = join(tmpDir, "skilltap");
+    await Bun.write(execPath, "old");
+
+    const result = await downloadAndInstall("9.9.9", notFoundFetch, execPath);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.message).toContain("HTTP 404");
+  });
+
+  test("returns error on network failure", async () => {
+    const execPath = join(tmpDir, "skilltap");
+    await Bun.write(execPath, "old");
+
+    const result = await downloadAndInstall("9.9.9", networkErrorFetch, execPath);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.message).toContain("Download failed");
+  });
+
+  test("replaces binary with downloaded content on success", async () => {
+    const execPath = join(tmpDir, "skilltap");
+    await Bun.write(execPath, "old content");
+
+    const result = await downloadAndInstall("9.9.9", okFetch, execPath);
+
+    expect(result.ok).toBe(true);
+    const written = new Uint8Array(await Bun.file(execPath).arrayBuffer());
+    expect(written).toEqual(fakeBinary);
+  });
+
+  test("temp file is cleaned up after successful install", async () => {
+    const execPath = join(tmpDir, "skilltap");
+    await Bun.write(execPath, "old");
+
+    await downloadAndInstall("9.9.9", okFetch, execPath);
+
+    expect(await Bun.file(`${execPath}.update`).exists()).toBe(false);
+  });
+
+  test("binary is made executable after install", async () => {
+    const execPath = join(tmpDir, "skilltap");
+    await Bun.write(execPath, "old");
+
+    await downloadAndInstall("9.9.9", okFetch, execPath);
+
+    const stat = await Bun.file(execPath).stat();
+    // Check owner execute bit (0o100)
+    expect(stat.mode & 0o100).toBe(0o100);
+  });
+
+  test("updates version cache after successful install", async () => {
+    const execPath = join(tmpDir, "skilltap");
+    await Bun.write(execPath, "old");
+
+    await downloadAndInstall("9.9.9", okFetch, execPath);
+
+    const cacheFile = join(configDir, "skilltap", "update-check.json");
+    const cache = (await Bun.file(cacheFile).json()) as { latest: string };
+    expect(cache.latest).toBe("9.9.9");
+  });
+
+  test("returns error when binary replacement fails", async () => {
+    // Put execPath inside a read-only directory so Bun.write to tmpPath (execPath.update) fails
+    const roDir = join(tmpDir, "readonly");
+    await mkdir(roDir, { recursive: true });
+    await Bun.$`chmod 555 ${roDir}`.quiet();
+    const execPath = join(roDir, "skilltap");
+
+    const result = await downloadAndInstall("9.9.9", okFetch, execPath);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.message).toContain("Failed to replace binary");
+    expect(result.error.hint).toContain("sudo");
+  });
+
+  test("temp file cleaned up when replacement fails", async () => {
+    const roDir = join(tmpDir, "readonly2");
+    await mkdir(roDir, { recursive: true });
+    await Bun.$`chmod 555 ${roDir}`.quiet();
+    const execPath = join(roDir, "skilltap");
+
+    await downloadAndInstall("9.9.9", okFetch, execPath);
+
+    // tmpPath = ${execPath}.update — write failed (EACCES), so it should not exist
+    expect(await Bun.file(`${execPath}.update`).exists()).toBe(false);
+  });
+});

package/src/self-update.ts

@@ -124,12 +124,16 @@ function getPlatformAsset(): string | null {
   return null;
 }
 
+type FetchFn = typeof fetch;
+
 /**
  * Download the specified release from GitHub and atomically replace the
  * running binary. Only works when running as a compiled binary.
  */
 export async function downloadAndInstall(
   version: string,
+  _fetch: FetchFn = fetch,
+  _execPath: string = process.execPath,
 ): Promise<Result<void, UserError>> {
   const asset = getPlatformAsset();
   if (!asset) {
@@ -142,12 +146,11 @@ export async function downloadAndInstall(
   }
 
   const url = `https://github.com/${GITHUB_OWNER}/${GITHUB_REPO}/releases/download/v${version}/${asset}`;
-  const execPath = process.execPath;
-  const tmpPath = `${execPath}.update`;
+  const tmpPath = `${_execPath}.update`;
 
   let response: Response;
   try {
-    response = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+    response = await _fetch(url, { signal: AbortSignal.timeout(60_000) });
   } catch (e) {
     return err(
       new NetworkError(`Download failed: ${e}`) as unknown as UserError,
@@ -164,7 +167,7 @@ export async function downloadAndInstall(
     const buffer = await response.arrayBuffer();
     await Bun.write(tmpPath, buffer);
     await Bun.$`chmod +x ${tmpPath}`.quiet();
-    await Bun.$`cp -a ${tmpPath} ${execPath} && rm -f ${tmpPath}`.quiet();
+    await Bun.$`mv -f ${tmpPath} ${_execPath}`.quiet();
   } catch (e) {
     // Clean up temp file if possible
     Bun.$`rm -f ${tmpPath}`.quiet();