skillrepo 1.3.1 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "Set up SkillRepo in any IDE — one command",
   "type": "module",
   "bin": {

package/src/commands/init.mjs

@@ -24,6 +24,8 @@ import {
   confirm,
 } from "../lib/prompt.mjs";
 
+import { resolveKeyFromEnvFiles } from "../lib/resolve-key.mjs";
+
 const DEFAULT_URL = "https://skillrepo.dev";
 
 /**
@@ -32,7 +34,7 @@ const DEFAULT_URL = "https://skillrepo.dev";
  */
 function parseFlags(argv) {
   const flags = {
-    key: process.env.SKILLREPO_ACCESS_KEY || null,
+    key: resolveKeyFromEnvFiles(),
     url: process.env.SKILLREPO_URL || DEFAULT_URL,
     yes: false,
   };

package/src/lib/mergers/claude-mcp.mjs

@@ -39,7 +39,7 @@ export function mergeClaudeMcpConfig(mcpUrl) {
     config.mcpServers = {};
   }
 
-  const action = config.mcpServers.skillrepo ? "merged" : "created";
+  const action = config.mcpServers.skillrepo ? "updated" : "merged";
   config.mcpServers.skillrepo = serverEntry;
 
   writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");

package/src/lib/mergers/hooks-json.mjs

@@ -1,16 +1,35 @@
 /**
- * Merger for Claude Code .claude/hooks/hooks.json
- * Writes hook scripts and merges hook entries into hooks.json.
+ * Merger for Claude Code hooks into .claude/settings.local.json
+ * Writes hook scripts and merges hook entries into settings.local.json.
  *
  * Merge strategy: add SessionStart and UserPromptSubmit entries
- * without destroying existing hooks. Idempotent — skips if already installed.
+ * without destroying existing settings. Idempotent — skips if already installed.
+ * Cleans up stale .claude/hooks/hooks.json if it exists.
  */
 
+import { unlinkSync } from "node:fs";
 import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
-import { claudeHooksJson, claudeSyncHook, claudePromptHook } from "../paths.mjs";
+import { claudeSettingsLocal, claudeSyncHook, claudePromptHook, claudePreToolHook, claudeHooksDir } from "../paths.mjs";
+import { join } from "node:path";
 
-const SYNC_COMMAND = "node .claude/hooks/skillrepo-sync.mjs";
-const PROMPT_COMMAND = "node .claude/hooks/skillrepo-prompt-match.mjs";
+const DEFAULT_SYNC_COMMAND = "node .claude/hooks/skillrepo-sync.mjs";
+const DEFAULT_PROMPT_COMMAND = "node .claude/hooks/skillrepo-prompt-match.mjs";
+const DEFAULT_PRETOOL_COMMAND = "node .claude/hooks/skillrepo-pretool-match.mjs";
+
+/**
+ * Extract a hook command from a hooks config group, falling back to a default.
+ * @param {object} hooksConfig - The hooks config object from the server payload
+ * @param {string} eventName - e.g. "SessionStart" or "UserPromptSubmit"
+ * @param {string} fallback - default command if extraction fails
+ * @returns {string}
+ */
+function extractCommand(hooksConfig, eventName, fallback) {
+  try {
+    return hooksConfig[eventName][0].hooks[0].command || fallback;
+  } catch {
+    return fallback;
+  }
+}
 
 /**
  * Check if a command is already installed in a hook group array.
@@ -28,13 +47,17 @@ function hasCommand(groups, command) {
 }
 
 /**
- * Merge SkillRepo hooks into hooks.json and write hook scripts.
- * @param {string} hooksJsonContent - The canonical hooks.json content from the API
+ * Merge SkillRepo hooks into .claude/settings.local.json and write hook scripts.
+ * @param {object} hooksConfig - The hooks config object from the server payload (settingsHooks.hooks)
  * @param {string} syncHookContent - The sync hook script content
  * @param {string} promptHookContent - The prompt-match hook script content
+ * @param {string} [preToolHookContent] - The pretool-match hook script content (optional for backward compat)
  * @returns {{ results: { path: string; action: string }[] }}
  */
-export function mergeHooksConfig(hooksJsonContent, syncHookContent, promptHookContent) {
+export function mergeHooksConfig(hooksConfig, syncHookContent, promptHookContent, preToolHookContent) {
+  const syncCommand = extractCommand(hooksConfig, "SessionStart", DEFAULT_SYNC_COMMAND);
+  const promptCommand = extractCommand(hooksConfig, "UserPromptSubmit", DEFAULT_PROMPT_COMMAND);
+  const preToolCommand = extractCommand(hooksConfig, "PreToolUse", DEFAULT_PRETOOL_COMMAND);
   const results = [];
 
   // Always write hook scripts (latest version from server)
@@ -52,23 +75,37 @@ export function mergeHooksConfig(hooksJsonContent, syncHookContent, promptHookCo
     action: promptExisted ? "updated" : "created",
   });
 
-  // Merge hooks.json
-  const filePath = claudeHooksJson();
-  const existing = readFileSafe(filePath);
-
-  if (existing === null) {
-    writeFileSafe(filePath, hooksJsonContent);
-    results.push({ path: ".claude/hooks/hooks.json", action: "created" });
-    return { results };
+  if (preToolHookContent) {
+    const preToolExisted = readFileSafe(claudePreToolHook()) !== null;
+    writeFileSafe(claudePreToolHook(), preToolHookContent);
+    results.push({
+      path: ".claude/hooks/skillrepo-pretool-match.mjs",
+      action: preToolExisted ? "updated" : "created",
+    });
   }
 
-  let config;
+  // Clean up stale .claude/hooks/hooks.json if it exists
+  const staleHooksJson = join(claudeHooksDir(), "hooks.json");
   try {
-    config = JSON.parse(existing);
+    unlinkSync(staleHooksJson);
+    results.push({ path: ".claude/hooks/hooks.json", action: "removed" });
   } catch {
-    throw new Error(
-      "Cannot parse .claude/hooks/hooks.json — invalid JSON. Fix or delete it, then run setup again."
-    );
+    // File doesn't exist — nothing to clean up
+  }
+
+  // Merge hooks into .claude/settings.local.json
+  const filePath = claudeSettingsLocal();
+  const existing = readFileSafe(filePath);
+
+  let config = {};
+  if (existing !== null) {
+    try {
+      config = JSON.parse(existing);
+    } catch {
+      throw new Error(
+        "Cannot parse .claude/settings.local.json — invalid JSON. Fix or delete it, then run setup again."
+      );
+    }
   }
 
   if (!config.hooks) config.hooks = {};
@@ -76,28 +113,42 @@ export function mergeHooksConfig(hooksJsonContent, syncHookContent, promptHookCo
 
   // Merge SessionStart
   if (!Array.isArray(config.hooks.SessionStart)) config.hooks.SessionStart = [];
-  if (!hasCommand(config.hooks.SessionStart, SYNC_COMMAND)) {
+  if (!hasCommand(config.hooks.SessionStart, syncCommand)) {
     config.hooks.SessionStart.push({
       matcher: "startup|resume",
-      hooks: [{ type: "command", command: SYNC_COMMAND }],
+      hooks: [{ type: "command", command: syncCommand }],
     });
     changed = true;
   }
 
   // Merge UserPromptSubmit
   if (!Array.isArray(config.hooks.UserPromptSubmit)) config.hooks.UserPromptSubmit = [];
-  if (!hasCommand(config.hooks.UserPromptSubmit, PROMPT_COMMAND)) {
+  if (!hasCommand(config.hooks.UserPromptSubmit, promptCommand)) {
     config.hooks.UserPromptSubmit.push({
-      hooks: [{ type: "command", command: PROMPT_COMMAND }],
+      hooks: [{ type: "command", command: promptCommand }],
     });
     changed = true;
   }
 
-  if (changed) {
+  // Merge PreToolUse
+  if (preToolHookContent) {
+    if (!Array.isArray(config.hooks.PreToolUse)) config.hooks.PreToolUse = [];
+    if (!hasCommand(config.hooks.PreToolUse, preToolCommand)) {
+      config.hooks.PreToolUse.push({
+        hooks: [{ type: "command", command: preToolCommand }],
+      });
+      changed = true;
+    }
+  }
+
+  if (existing === null) {
+    writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");
+    results.push({ path: ".claude/settings.local.json", action: "created" });
+  } else if (changed) {
     writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");
-    results.push({ path: ".claude/hooks/hooks.json", action: "merged" });
+    results.push({ path: ".claude/settings.local.json", action: "merged" });
   } else {
-    results.push({ path: ".claude/hooks/hooks.json", action: "skipped" });
+    results.push({ path: ".claude/settings.local.json", action: "skipped" });
   }
 
   return { results };

package/src/lib/paths.mjs

@@ -12,11 +12,13 @@ const cwd = () => process.cwd();
 export const claudeMcpJson = () => join(cwd(), ".mcp.json");
 export const claudeDir = () => join(cwd(), ".claude");
 export const claudeHooksDir = () => join(cwd(), ".claude", "hooks");
-export const claudeHooksJson = () => join(cwd(), ".claude", "hooks", "hooks.json");
+export const claudeSettingsLocal = () => join(cwd(), ".claude", "settings.local.json");
 export const claudeSyncHook = () => join(cwd(), ".claude", "hooks", "skillrepo-sync.mjs");
 export const claudePromptHook = () => join(cwd(), ".claude", "hooks", "skillrepo-prompt-match.mjs");
+export const claudePreToolHook = () => join(cwd(), ".claude", "hooks", "skillrepo-pretool-match.mjs");
 export const claudeSkillrepoMd = () => join(cwd(), ".claude", "skillrepo.md");
 export const claudeSkillrepoIndex = () => join(cwd(), ".claude", "skillrepo-index.json");
+export const claudeSkillrepoConfig = () => join(cwd(), ".claude", "skillrepo-config.json");
 
 // Cursor
 export const cursorDir = () => join(cwd(), ".cursor");

package/src/lib/resolve-key.mjs

@@ -0,0 +1,36 @@
+/**
+ * Resolve SKILLREPO_ACCESS_KEY from process.env → .env.local → .env.
+ * Extracted as a shared module so it can be tested independently.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Resolve SKILLREPO_ACCESS_KEY from .env.local → .env → process.env.
+ * @returns {string|null}
+ */
+export function resolveKeyFromEnvFiles() {
+  if (process.env.SKILLREPO_ACCESS_KEY) return process.env.SKILLREPO_ACCESS_KEY;
+  const cwd = process.cwd();
+  for (const file of [".env.local", ".env"]) {
+    try {
+      const lines = readFileSync(join(cwd, file), "utf-8").split("\n");
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("#") || !trimmed.includes("=")) continue;
+        const eqIdx = trimmed.indexOf("=");
+        const key = trimmed.slice(0, eqIdx).trim();
+        if (key === "SKILLREPO_ACCESS_KEY") {
+          let val = trimmed.slice(eqIdx + 1).trim();
+          if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.slice(1, -1);
+          }
+          val = val.replace(/\s+#.*$/, "");
+          if (val) return val;
+        }
+      }
+    } catch { /* file not found, continue */ }
+  }
+  return null;
+}

package/src/lib/write-configs.mjs

@@ -4,7 +4,7 @@
  */
 
 import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
-import { claudeSkillrepoMd, claudeSkillrepoIndex, cursorSkillrepoMdc } from "./paths.mjs";
+import { claudeSkillrepoMd, claudeSkillrepoIndex, claudeSkillrepoConfig, cursorSkillrepoMdc } from "./paths.mjs";
 import { mergeClaudeMcpConfig } from "./mergers/claude-mcp.mjs";
 import { mergeCursorMcpConfig } from "./mergers/cursor-mcp.mjs";
 import { mergeWindsurfMcpConfig } from "./mergers/windsurf-mcp.mjs";
@@ -38,11 +38,19 @@ export function writeAllConfigs({ ides, mcpUrl, apiKey, payload }) {
     writeFileSafe(claudeSkillrepoIndex(), payload.claudeCode.skillIndex.content);
     results.push({ path: ".claude/skillrepo-index.json", action: indexExisted ? "updated" : "created" });
 
-    // Hooks (SessionStart sync + UserPromptSubmit prompt-match)
+    // Hook config (injection limits + companion map)
+    if (payload.claudeCode.skillrepoConfig?.content) {
+      const configExisted = readFileSafe(claudeSkillrepoConfig()) !== null;
+      writeFileSafe(claudeSkillrepoConfig(), payload.claudeCode.skillrepoConfig.content);
+      results.push({ path: ".claude/skillrepo-config.json", action: configExisted ? "updated" : "created" });
+    }
+
+    // Hooks (SessionStart sync + UserPromptSubmit prompt-match + PreToolUse pretool-match)
     const hookResults = mergeHooksConfig(
-      payload.claudeCode.hooksJson.content,
+      payload.claudeCode.settingsHooks.hooks,
       payload.claudeCode.syncHook.content,
-      payload.claudeCode.promptHook.content
+      payload.claudeCode.promptHook.content,
+      payload.claudeCode.preToolHook?.content
     );
     results.push(...hookResults.results);
   }

package/src/test/mergers/claude-mcp.test.mjs

@@ -1,6 +1,6 @@
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -46,13 +46,13 @@ describe("Claude Code MCP config merger", () => {
 
     const result = mergeClaudeMcpConfig("https://skillrepo.dev/api/mcp");
 
-    assert.equal(result.action, "created"); // new entry, not merge
+    assert.equal(result.action, "merged"); // adding to existing file
     const content = JSON.parse(readFileSync(join(tempDir, ".mcp.json"), "utf-8"));
     assert.ok(content.mcpServers.other, "other server preserved");
     assert.ok(content.mcpServers.skillrepo, "skillrepo added");
   });
 
-  it("updates existing skillrepo entry (merged)", async () => {
+  it("updates existing skillrepo entry", async () => {
     const { mergeClaudeMcpConfig } = await import("../../lib/mergers/claude-mcp.mjs");
 
     const existing = {
@@ -64,7 +64,7 @@ describe("Claude Code MCP config merger", () => {
 
     const result = mergeClaudeMcpConfig("https://new-url.com/api/mcp");
 
-    assert.equal(result.action, "merged");
+    assert.equal(result.action, "updated");
     const content = JSON.parse(readFileSync(join(tempDir, ".mcp.json"), "utf-8"));
     assert.equal(content.mcpServers.skillrepo.url, "https://new-url.com/api/mcp");
   });

package/src/test/mergers/hooks-json.test.mjs

@@ -20,17 +20,18 @@ afterEach(() => {
 
 const SYNC_CONTENT = "// sync hook";
 const PROMPT_CONTENT = "// prompt hook";
-const HOOKS_JSON = JSON.stringify({
-  hooks: {
-    SessionStart: [{ matcher: "startup|resume", hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-sync.mjs" }] }],
-    UserPromptSubmit: [{ hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-prompt-match.mjs" }] }],
-  },
-}, null, 2) + "\n";
-
-describe("Hooks JSON merger", () => {
-  it("creates all files when nothing exists", async () => {
+const PRETOOL_CONTENT = "// pretool hook";
+
+const HOOKS_CONFIG = {
+  SessionStart: [{ matcher: "startup|resume", hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-sync.mjs" }] }],
+  UserPromptSubmit: [{ hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-prompt-match.mjs" }] }],
+  PreToolUse: [{ hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-pretool-match.mjs" }] }],
+};
+
+describe("Hooks settings.local.json merger", () => {
+  it("creates settings.local.json and scripts when nothing exists", async () => {
     const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
-    const { results } = mergeHooksConfig(HOOKS_JSON, SYNC_CONTENT, PROMPT_CONTENT);
+    const { results } = mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT);
 
     // Check sync hook written
     const syncResult = results.find((r) => r.path.includes("sync"));
@@ -42,30 +43,37 @@ describe("Hooks JSON merger", () => {
     assert.equal(promptResult.action, "created");
     assert.equal(readFileSync(join(tempDir, ".claude/hooks/skillrepo-prompt-match.mjs"), "utf-8"), PROMPT_CONTENT);
 
-    // Check hooks.json created
-    const jsonResult = results.find((r) => r.path.includes("hooks.json"));
-    assert.equal(jsonResult.action, "created");
+    // Check settings.local.json created
+    const settingsResult = results.find((r) => r.path.includes("settings.local.json"));
+    assert.equal(settingsResult.action, "created");
+
+    const config = JSON.parse(readFileSync(join(tempDir, ".claude/settings.local.json"), "utf-8"));
+    assert.equal(config.hooks.SessionStart.length, 1);
+    assert.equal(config.hooks.UserPromptSubmit.length, 1);
   });
 
-  it("merges into existing hooks.json without destroying other hooks", async () => {
+  it("merges into existing settings without destroying other keys", async () => {
     const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
 
-    // Pre-existing hooks.json with a different hook
+    // Pre-existing settings.local.json with permissions and other hooks
     const existing = {
+      permissions: { allow: ["Bash(*)", "Read(*)"] },
       hooks: {
         PreToolUse: [{ hooks: [{ type: "command", command: "node other-hook.mjs" }] }],
       },
     };
-    mkdirSync(join(tempDir, ".claude/hooks"), { recursive: true });
-    writeFileSync(join(tempDir, ".claude/hooks/hooks.json"), JSON.stringify(existing, null, 2));
+    mkdirSync(join(tempDir, ".claude"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/settings.local.json"), JSON.stringify(existing, null, 2));
 
-    const { results } = mergeHooksConfig(HOOKS_JSON, SYNC_CONTENT, PROMPT_CONTENT);
+    const { results } = mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT);
 
-    const jsonResult = results.find((r) => r.path.includes("hooks.json"));
-    assert.equal(jsonResult.action, "merged");
+    const settingsResult = results.find((r) => r.path.includes("settings.local.json"));
+    assert.equal(settingsResult.action, "merged");
 
-    const config = JSON.parse(readFileSync(join(tempDir, ".claude/hooks/hooks.json"), "utf-8"));
-    // Original hook preserved
+    const config = JSON.parse(readFileSync(join(tempDir, ".claude/settings.local.json"), "utf-8"));
+    // Original permissions preserved
+    assert.deepEqual(config.permissions, { allow: ["Bash(*)", "Read(*)"] });
+    // Original hooks preserved
     assert.equal(config.hooks.PreToolUse.length, 1);
     // New hooks added
     assert.equal(config.hooks.SessionStart.length, 1);
@@ -82,50 +90,55 @@ describe("Hooks JSON merger", () => {
         UserPromptSubmit: [{ hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-prompt-match.mjs" }] }],
       },
     };
-    mkdirSync(join(tempDir, ".claude/hooks"), { recursive: true });
-    writeFileSync(join(tempDir, ".claude/hooks/hooks.json"), JSON.stringify(existing, null, 2));
+    mkdirSync(join(tempDir, ".claude"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/settings.local.json"), JSON.stringify(existing, null, 2));
 
-    const { results } = mergeHooksConfig(HOOKS_JSON, SYNC_CONTENT, PROMPT_CONTENT);
+    const { results } = mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT);
 
-    const jsonResult = results.find((r) => r.path.includes("hooks.json"));
-    assert.equal(jsonResult.action, "skipped");
+    const settingsResult = results.find((r) => r.path.includes("settings.local.json"));
+    assert.equal(settingsResult.action, "skipped");
   });
 
   it("adds missing UserPromptSubmit when only SessionStart exists", async () => {
     const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
 
-    // Only SessionStart installed (pre-existing v1.1 setup)
+    // Only SessionStart installed
     const existing = {
       hooks: {
         SessionStart: [{ matcher: "startup|resume", hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-sync.mjs" }] }],
       },
     };
-    mkdirSync(join(tempDir, ".claude/hooks"), { recursive: true });
-    writeFileSync(join(tempDir, ".claude/hooks/hooks.json"), JSON.stringify(existing, null, 2));
+    mkdirSync(join(tempDir, ".claude"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/settings.local.json"), JSON.stringify(existing, null, 2));
 
-    const { results } = mergeHooksConfig(HOOKS_JSON, SYNC_CONTENT, PROMPT_CONTENT);
+    const { results } = mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT);
 
-    const jsonResult = results.find((r) => r.path.includes("hooks.json"));
-    assert.equal(jsonResult.action, "merged");
+    const settingsResult = results.find((r) => r.path.includes("settings.local.json"));
+    assert.equal(settingsResult.action, "merged");
 
-    const config = JSON.parse(readFileSync(join(tempDir, ".claude/hooks/hooks.json"), "utf-8"));
-    // SessionStart unchanged
+    const config = JSON.parse(readFileSync(join(tempDir, ".claude/settings.local.json"), "utf-8"));
     assert.equal(config.hooks.SessionStart.length, 1);
-    // UserPromptSubmit added
     assert.equal(config.hooks.UserPromptSubmit.length, 1);
     assert.equal(config.hooks.UserPromptSubmit[0].hooks[0].command, "node .claude/hooks/skillrepo-prompt-match.mjs");
   });
 
-  it("always updates hook scripts even when hooks.json is skipped", async () => {
+  it("always updates hook scripts even when settings merge is skipped", async () => {
     const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
 
-    // Install once
+    // Install once with old scripts
     mkdirSync(join(tempDir, ".claude/hooks"), { recursive: true });
     writeFileSync(join(tempDir, ".claude/hooks/skillrepo-sync.mjs"), "// old sync");
     writeFileSync(join(tempDir, ".claude/hooks/skillrepo-prompt-match.mjs"), "// old prompt");
-    writeFileSync(join(tempDir, ".claude/hooks/hooks.json"), HOOKS_JSON);
+    mkdirSync(join(tempDir, ".claude"), { recursive: true });
+    const existing = {
+      hooks: {
+        SessionStart: [{ matcher: "startup|resume", hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-sync.mjs" }] }],
+        UserPromptSubmit: [{ hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-prompt-match.mjs" }] }],
+      },
+    };
+    writeFileSync(join(tempDir, ".claude/settings.local.json"), JSON.stringify(existing, null, 2));
 
-    const { results } = mergeHooksConfig(HOOKS_JSON, "// new sync", "// new prompt");
+    const { results } = mergeHooksConfig(HOOKS_CONFIG, "// new sync", "// new prompt");
 
     // Scripts updated
     const syncResult = results.find((r) => r.path.includes("sync.mjs"));
@@ -135,17 +148,126 @@ describe("Hooks JSON merger", () => {
     const promptResult = results.find((r) => r.path.includes("prompt-match"));
     assert.equal(promptResult.action, "updated");
     assert.equal(readFileSync(join(tempDir, ".claude/hooks/skillrepo-prompt-match.mjs"), "utf-8"), "// new prompt");
+
+    // Settings skipped
+    const settingsResult = results.find((r) => r.path.includes("settings.local.json"));
+    assert.equal(settingsResult.action, "skipped");
+  });
+
+  it("cleans up stale .claude/hooks/hooks.json", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+
+    // Create stale hooks.json
+    mkdirSync(join(tempDir, ".claude/hooks"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/hooks/hooks.json"), '{"hooks":{}}');
+
+    const { results } = mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT);
+
+    // Stale file removed
+    assert.equal(existsSync(join(tempDir, ".claude/hooks/hooks.json")), false);
+    const removedResult = results.find((r) => r.path === ".claude/hooks/hooks.json");
+    assert.equal(removedResult.action, "removed");
+
+    // settings.local.json created
+    const settingsResult = results.find((r) => r.path.includes("settings.local.json"));
+    assert.equal(settingsResult.action, "created");
+  });
+
+  it("throws on invalid JSON in settings.local.json", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+
+    mkdirSync(join(tempDir, ".claude"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/settings.local.json"), "not json{");
+
+    assert.throws(
+      () => mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT),
+      /Cannot parse/
+    );
   });
 
-  it("throws on invalid JSON in hooks.json", async () => {
+  it("merges SessionStart when existing value is null", async () => {
     const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
 
+    // Pre-populate settings.local.json with SessionStart: null
+    const existing = {
+      hooks: { SessionStart: null },
+    };
+    mkdirSync(join(tempDir, ".claude"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/settings.local.json"), JSON.stringify(existing, null, 2));
+
+    const { results } = mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT);
+
+    const settingsResult = results.find((r) => r.path.includes("settings.local.json"));
+    assert.equal(settingsResult.action, "merged");
+
+    const config = JSON.parse(readFileSync(join(tempDir, ".claude/settings.local.json"), "utf-8"));
+    assert.ok(Array.isArray(config.hooks.SessionStart), "SessionStart should be an array");
+    assert.equal(config.hooks.SessionStart.length, 1);
+    assert.equal(config.hooks.SessionStart[0].hooks[0].command, "node .claude/hooks/skillrepo-sync.mjs");
+  });
+
+  it("documents partial write when JSON parse fails (hook scripts written before throw)", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+
+    // Create old sync script on disk
     mkdirSync(join(tempDir, ".claude/hooks"), { recursive: true });
-    writeFileSync(join(tempDir, ".claude/hooks/hooks.json"), "not json{");
+    writeFileSync(join(tempDir, ".claude/hooks/skillrepo-sync.mjs"), "// old content");
 
+    // Create invalid settings.local.json
+    mkdirSync(join(tempDir, ".claude"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/settings.local.json"), "not valid json{{{");
+
+    // Should throw on invalid JSON
     assert.throws(
-      () => mergeHooksConfig(HOOKS_JSON, SYNC_CONTENT, PROMPT_CONTENT),
+      () => mergeHooksConfig(HOOKS_CONFIG, "// new sync content", PROMPT_CONTENT),
       /Cannot parse/
     );
+
+    // Document the partial-write behavior: sync script was updated before the throw
+    const syncOnDisk = readFileSync(join(tempDir, ".claude/hooks/skillrepo-sync.mjs"), "utf-8");
+    assert.equal(syncOnDisk, "// new sync content", "sync script should have new content (partial write)");
+  });
+
+  it("writes pretool hook script when preToolHookContent is provided", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+    const { results } = mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT, PRETOOL_CONTENT);
+
+    const preToolResult = results.find((r) => r.path.includes("pretool"));
+    assert.equal(preToolResult.action, "created");
+    assert.equal(readFileSync(join(tempDir, ".claude/hooks/skillrepo-pretool-match.mjs"), "utf-8"), PRETOOL_CONTENT);
+  });
+
+  it("merges PreToolUse hook into settings.local.json", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+    mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT, PRETOOL_CONTENT);
+
+    const config = JSON.parse(readFileSync(join(tempDir, ".claude/settings.local.json"), "utf-8"));
+    assert.ok(Array.isArray(config.hooks.PreToolUse), "PreToolUse should be an array");
+    assert.equal(config.hooks.PreToolUse.length, 1);
+    assert.equal(config.hooks.PreToolUse[0].hooks[0].command, "node .claude/hooks/skillrepo-pretool-match.mjs");
+  });
+
+  it("skips pretool hook when preToolHookContent is not provided", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+    const { results } = mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT);
+
+    const preToolResult = results.find((r) => r.path.includes("pretool"));
+    assert.equal(preToolResult, undefined, "no pretool result when content not provided");
+    assert.equal(existsSync(join(tempDir, ".claude/hooks/skillrepo-pretool-match.mjs")), false);
+  });
+
+  it("does not duplicate PreToolUse when already installed", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+
+    // First install
+    mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT, PRETOOL_CONTENT);
+    // Second install
+    const { results } = mergeHooksConfig(HOOKS_CONFIG, SYNC_CONTENT, PROMPT_CONTENT, PRETOOL_CONTENT);
+
+    const settingsResult = results.find((r) => r.path.includes("settings.local.json"));
+    assert.equal(settingsResult.action, "skipped");
+
+    const config = JSON.parse(readFileSync(join(tempDir, ".claude/settings.local.json"), "utf-8"));
+    assert.equal(config.hooks.PreToolUse.length, 1, "should not duplicate PreToolUse entry");
   });
 });

package/src/test/resolve-key.test.mjs

@@ -0,0 +1,85 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+let originalCwd;
+let tempDir;
+let originalEnv;
+
+beforeEach(() => {
+  originalCwd = process.cwd;
+  originalEnv = process.env.SKILLREPO_ACCESS_KEY;
+  delete process.env.SKILLREPO_ACCESS_KEY;
+  tempDir = mkdtempSync(join(tmpdir(), "cli-resolve-key-test-"));
+  process.cwd = () => tempDir;
+});
+
+afterEach(() => {
+  process.cwd = originalCwd;
+  if (originalEnv !== undefined) {
+    process.env.SKILLREPO_ACCESS_KEY = originalEnv;
+  } else {
+    delete process.env.SKILLREPO_ACCESS_KEY;
+  }
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("resolveKeyFromEnvFiles", () => {
+  it("short-circuits when key is in process.env", async () => {
+    process.env.SKILLREPO_ACCESS_KEY = "sk_live_from_env";
+    const { resolveKeyFromEnvFiles } = await import("../lib/resolve-key.mjs");
+    const result = resolveKeyFromEnvFiles();
+    assert.equal(result, "sk_live_from_env");
+  });
+
+  it("reads plain value from .env.local", async () => {
+    writeFileSync(join(tempDir, ".env.local"), "SKILLREPO_ACCESS_KEY=sk_live_abc123\n");
+    const { resolveKeyFromEnvFiles } = await import("../lib/resolve-key.mjs");
+    const result = resolveKeyFromEnvFiles();
+    assert.equal(result, "sk_live_abc123");
+  });
+
+  it("reads double-quoted value from .env.local", async () => {
+    writeFileSync(join(tempDir, ".env.local"), 'SKILLREPO_ACCESS_KEY="sk_live_quoted"\n');
+    const { resolveKeyFromEnvFiles } = await import("../lib/resolve-key.mjs");
+    const result = resolveKeyFromEnvFiles();
+    assert.equal(result, "sk_live_quoted");
+  });
+
+  it("strips inline comment from value", async () => {
+    writeFileSync(join(tempDir, ".env.local"), "SKILLREPO_ACCESS_KEY=sk_live_abc123 # my key\n");
+    const { resolveKeyFromEnvFiles } = await import("../lib/resolve-key.mjs");
+    const result = resolveKeyFromEnvFiles();
+    assert.equal(result, "sk_live_abc123");
+  });
+
+  it("falls back to .env when .env.local is absent", async () => {
+    writeFileSync(join(tempDir, ".env"), "SKILLREPO_ACCESS_KEY=sk_live_fallback\n");
+    const { resolveKeyFromEnvFiles } = await import("../lib/resolve-key.mjs");
+    const result = resolveKeyFromEnvFiles();
+    assert.equal(result, "sk_live_fallback");
+  });
+
+  it("returns null when key is absent in both files", async () => {
+    writeFileSync(join(tempDir, ".env.local"), "OTHER_VAR=hello\n");
+    writeFileSync(join(tempDir, ".env"), "ANOTHER_VAR=world\n");
+    const { resolveKeyFromEnvFiles } = await import("../lib/resolve-key.mjs");
+    const result = resolveKeyFromEnvFiles();
+    assert.equal(result, null);
+  });
+
+  it("returns null when both files are missing", async () => {
+    const { resolveKeyFromEnvFiles } = await import("../lib/resolve-key.mjs");
+    const result = resolveKeyFromEnvFiles();
+    assert.equal(result, null);
+  });
+
+  it("ignores commented-out key line", async () => {
+    writeFileSync(join(tempDir, ".env.local"), "# SKILLREPO_ACCESS_KEY=sk_live_old\n");
+    const { resolveKeyFromEnvFiles } = await import("../lib/resolve-key.mjs");
+    const result = resolveKeyFromEnvFiles();
+    assert.equal(result, null);
+  });
+});