skillrepo 1.5.0 → 1.6.1

package/package.json

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

package/src/lib/fs-utils.mjs

@@ -3,7 +3,7 @@
  * Creates directories as needed, handles errors cleanly.
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, chmodSync } from "node:fs";
 import { dirname } from "node:path";
 
 /**
@@ -35,6 +35,15 @@ export function writeFileSafe(filePath, content) {
   writeFileSync(filePath, content, "utf-8");
 }
 
+/**
+ * Write a file and mark it executable (0o755).
+ * Used for hook scripts that have shebangs and are invoked directly.
+ */
+export function writeExecutable(filePath, content) {
+  writeFileSafe(filePath, content);
+  chmodSync(filePath, 0o755);
+}
+
 /**
  * Check if a path exists (file or directory).
  */

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

@@ -8,13 +8,21 @@
  */
 
 import { unlinkSync } from "node:fs";
-import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
+import { readFileSafe, writeFileSafe, writeExecutable } from "../fs-utils.mjs";
 import { claudeSettingsLocal, claudeSyncHook, claudePromptHook, claudePreToolHook, claudeHooksDir } from "../paths.mjs";
 import { join } from "node:path";
 
-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";
+const DEFAULT_SYNC_COMMAND = ".claude/hooks/skillrepo-sync.mjs";
+const DEFAULT_PROMPT_COMMAND = ".claude/hooks/skillrepo-prompt-match.mjs";
+const DEFAULT_PRETOOL_COMMAND = ".claude/hooks/skillrepo-pretool-match.mjs";
+
+// Legacy commands used before v1.6.1 — recognized during migration so
+// re-running init replaces them rather than duplicating.
+const LEGACY_COMMANDS = new Set([
+  "node .claude/hooks/skillrepo-sync.mjs",
+  "node .claude/hooks/skillrepo-prompt-match.mjs",
+  "node .claude/hooks/skillrepo-pretool-match.mjs",
+]);
 
 /**
  * Extract a hook command from a hooks config group, falling back to a default.
@@ -46,6 +54,26 @@ function hasCommand(groups, command) {
   );
 }
 
+/**
+ * Replace legacy `node .claude/hooks/...` commands with the new direct-execution
+ * format. Returns true if any replacement was made.
+ */
+function replaceLegacyCommands(groups) {
+  if (!Array.isArray(groups)) return false;
+  let replaced = false;
+  for (const group of groups) {
+    if (!Array.isArray(group.hooks)) continue;
+    for (const hook of group.hooks) {
+      if (LEGACY_COMMANDS.has(hook.command)) {
+        // Strip the "node " prefix → ".claude/hooks/..."
+        hook.command = hook.command.replace(/^node /, "");
+        replaced = true;
+      }
+    }
+  }
+  return replaced;
+}
+
 /**
  * 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)
@@ -60,16 +88,17 @@ export function mergeHooksConfig(hooksConfig, syncHookContent, promptHookContent
   const preToolCommand = extractCommand(hooksConfig, "PreToolUse", DEFAULT_PRETOOL_COMMAND);
   const results = [];
 
-  // Always write hook scripts (latest version from server)
+  // Always write hook scripts (latest version from server) and mark executable.
+  // Scripts have #!/usr/bin/env node shebangs and are invoked directly (not via `node`).
   const syncExisted = readFileSafe(claudeSyncHook()) !== null;
-  writeFileSafe(claudeSyncHook(), syncHookContent);
+  writeExecutable(claudeSyncHook(), syncHookContent);
   results.push({
     path: ".claude/hooks/skillrepo-sync.mjs",
     action: syncExisted ? "updated" : "created",
   });
 
   const promptExisted = readFileSafe(claudePromptHook()) !== null;
-  writeFileSafe(claudePromptHook(), promptHookContent);
+  writeExecutable(claudePromptHook(), promptHookContent);
   results.push({
     path: ".claude/hooks/skillrepo-prompt-match.mjs",
     action: promptExisted ? "updated" : "created",
@@ -77,7 +106,7 @@ export function mergeHooksConfig(hooksConfig, syncHookContent, promptHookContent
 
   if (preToolHookContent) {
     const preToolExisted = readFileSafe(claudePreToolHook()) !== null;
-    writeFileSafe(claudePreToolHook(), preToolHookContent);
+    writeExecutable(claudePreToolHook(), preToolHookContent);
     results.push({
       path: ".claude/hooks/skillrepo-pretool-match.mjs",
       action: preToolExisted ? "updated" : "created",
@@ -111,6 +140,13 @@ export function mergeHooksConfig(hooksConfig, syncHookContent, promptHookContent
   if (!config.hooks) config.hooks = {};
   let changed = false;
 
+  // Migrate legacy "node .claude/hooks/..." commands to direct execution
+  for (const event of ["SessionStart", "UserPromptSubmit", "PreToolUse"]) {
+    if (Array.isArray(config.hooks[event]) && replaceLegacyCommands(config.hooks[event])) {
+      changed = true;
+    }
+  }
+
   // Merge SessionStart
   if (!Array.isArray(config.hooks.SessionStart)) config.hooks.SessionStart = [];
   if (!hasCommand(config.hooks.SessionStart, syncCommand)) {

package/src/lib/paths.mjs

@@ -24,7 +24,10 @@ export const claudeSkillrepoConfig = () => join(cwd(), ".claude", "skillrepo-con
 export const cursorDir = () => join(cwd(), ".cursor");
 export const cursorMcpJson = () => join(cwd(), ".cursor", "mcp.json");
 export const cursorRulesDir = () => join(cwd(), ".cursor", "rules");
+export const cursorHooksDir = () => join(cwd(), ".cursor", "hooks");
 export const cursorSkillrepoMdc = () => join(cwd(), ".cursor", "rules", "skillrepo.mdc");
+export const cursorSkillrepoIndex = () => join(cwd(), ".cursor", "skillrepo-index.json");
+export const cursorHooksJson = () => join(cwd(), ".cursor", "hooks.json");
 
 // Windsurf (always global — no project-level config)
 export const windsurfDir = () => join(homedir(), ".codeium", "windsurf");

package/src/lib/write-configs.mjs

@@ -3,8 +3,21 @@
  * Calls individual mergers and collects results.
  */
 
-import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
-import { claudeSkillrepoMd, claudeSkillrepoIndex, claudeSkillrepoConfig, cursorSkillrepoMdc } from "./paths.mjs";
+import { resolve } from "node:path";
+import { readFileSafe, writeFileSafe, writeExecutable } from "./fs-utils.mjs";
+import { claudeSkillrepoMd, claudeSkillrepoIndex, claudeSkillrepoConfig } from "./paths.mjs";
+
+/**
+ * Validate that a server-supplied path stays within an allowed directory.
+ * Prevents path traversal attacks from compromised server responses.
+ */
+function assertPathContained(filePath, allowedDir) {
+  const abs = resolve(process.cwd(), filePath);
+  const boundary = resolve(process.cwd(), allowedDir);
+  if (!abs.startsWith(boundary + "/") && abs !== boundary) {
+    throw new Error(`Server returned path outside ${allowedDir}: ${filePath}`);
+  }
+}
 import { mergeClaudeMcpConfig } from "./mergers/claude-mcp.mjs";
 import { mergeCursorMcpConfig } from "./mergers/cursor-mcp.mjs";
 import { mergeWindsurfMcpConfig } from "./mergers/windsurf-mcp.mjs";
@@ -59,10 +72,37 @@ export function writeAllConfigs({ ides, mcpUrl, apiKey, payload }) {
   if (ides.includes("cursor")) {
     results.push(mergeCursorMcpConfig(mcpUrl));
 
-    // Skill mapping file (always refresh with latest)
-    const cursorMdcExisted = readFileSafe(cursorSkillrepoMdc()) !== null;
-    writeFileSafe(cursorSkillrepoMdc(), payload.cursor.skillrepoMdc.content);
-    results.push({ path: ".cursor/rules/skillrepo.mdc", action: cursorMdcExisted ? "updated" : "created" });
+    // Write all rule files (per-skill .mdc + aggregate .mdc)
+    if (Array.isArray(payload.cursor?.rules)) {
+      for (const rule of payload.cursor.rules) {
+        assertPathContained(rule.path, ".cursor");
+        const existed = readFileSafe(rule.path) !== null;
+        writeFileSafe(rule.path, rule.content);
+        results.push({ path: rule.path, action: existed ? "updated" : "created" });
+      }
+    } else if (payload.cursor?.skillrepoMdc) {
+      // Legacy fallback: single .mdc file (pre-v2 server)
+      const existed = readFileSafe(payload.cursor.skillrepoMdc.path) !== null;
+      writeFileSafe(payload.cursor.skillrepoMdc.path, payload.cursor.skillrepoMdc.content);
+      results.push({ path: payload.cursor.skillrepoMdc.path, action: existed ? "updated" : "created" });
+    }
+
+    // Cursor hooks and skill index
+    if (payload.cursor?.hooksJson) {
+      const existed = readFileSafe(payload.cursor.hooksJson.path) !== null;
+      writeFileSafe(payload.cursor.hooksJson.path, payload.cursor.hooksJson.content);
+      results.push({ path: payload.cursor.hooksJson.path, action: existed ? "updated" : "created" });
+    }
+    if (payload.cursor?.sessionHook) {
+      const existed = readFileSafe(payload.cursor.sessionHook.path) !== null;
+      writeExecutable(payload.cursor.sessionHook.path, payload.cursor.sessionHook.content);
+      results.push({ path: payload.cursor.sessionHook.path, action: existed ? "updated" : "created" });
+    }
+    if (payload.cursor?.skillIndex) {
+      const existed = readFileSafe(payload.cursor.skillIndex.path) !== null;
+      writeFileSafe(payload.cursor.skillIndex.path, payload.cursor.skillIndex.content);
+      results.push({ path: payload.cursor.skillIndex.path, action: existed ? "updated" : "created" });
+    }
   }
 
   // Windsurf

package/src/test/e2e/HANDOFF.md

@@ -0,0 +1,244 @@
+# CLI E2E Test Harness — Handoff
+
+## What This Is
+
+A new agent needs to build a CLI E2E test platform for SkillRepo's `npx skillrepo init` command. The feature code is complete and merged (PR #479). The CLI E2E tests are the missing piece — no test code has been written yet, only the branch and directory exist.
+
+## Current State
+
+**Branch:** `feat/457-cli-e2e-tests` (off `feat/457-integration`)
+**Directory created:** `packages/cli/src/test/e2e/` (empty)
+**Approved plan:** `/Users/jpace/.claude/plans/valiant-scribbling-whisper.md`
+
+## What Was Built (the feature being tested)
+
+Epic #457: "Deterministic Skill Injection — Cross-Integration Architecture"
+
+The CLI (`npx skillrepo init`) now generates:
+
+**Claude Code files:**
+- `.claude/skillrepo.md` — skill reference
+- `.claude/skillrepo-index.json` — skill index with `contextSignals` (files, project, tasks)
+- `.claude/skillrepo-config.json` — version 2 config with `signals` array and `companions` map
+- `.claude/hooks/skillrepo-sync.mjs` — SessionStart hook (refreshes configs + repo profiling)
+- `.claude/hooks/skillrepo-prompt-match.mjs` — UserPromptSubmit hook (weighted scoring + profile multiplier)
+- `.claude/hooks/skillrepo-pretool-match.mjs` — PreToolUse hook (dynamic signal map + glob matching)
+- `.claude/settings.local.json` — hook registration (merged with existing)
+- `.mcp.json` — MCP server config
+
+**Cursor files:**
+- `.cursor/rules/skillrepo-{name}.mdc` — per-skill rules with `globs` for file-based activation
+- `.cursor/rules/skillrepo.mdc` — aggregate `alwaysApply` rule for skills without file signals
+- `.cursor/hooks.json` — registers `sessionStart` hook
+- `.cursor/hooks/skillrepo-session.mjs` — session hook with repo profiling + project-aware context
+- `.cursor/skillrepo-index.json` — skill index (same as Claude Code)
+- `.cursor/mcp.json` — MCP server config
+
+**Both:**
+- `.env.local` — `SKILLREPO_ACCESS_KEY=...`
+
+## Key Code Paths
+
+| File | What it does |
+|------|-------------|
+| `packages/cli/bin/skillrepo.mjs` | CLI entry point |
+| `packages/cli/src/commands/init.mjs` | Init command: detect IDEs → prompt for key → fetch payload → write configs |
+| `packages/cli/src/lib/http.mjs` | `fetchSetupPayload(apiKey, baseUrl)` — GET `/api/v1/setup` with Bearer auth |
+| `packages/cli/src/lib/write-configs.mjs` | Orchestrates all file writes per IDE, includes path traversal protection |
+| `packages/cli/src/lib/paths.mjs` | All output file path constants |
+| `packages/cli/src/lib/detect-ides.mjs` | Scans for `.claude/`, `.cursor/`, `.vscode/` directories |
+| `packages/cli/src/lib/fs-utils.mjs` | `readFileSafe()`, `writeFileSafe()` |
+| `packages/cli/src/lib/mergers/` | Individual mergers for settings.local.json, mcp.json, etc. |
+| `src/lib/setup/generate.ts` | Server-side: `generateSetupPayload()` produces the full payload |
+
+## The HTTP Contract
+
+The CLI makes ONE HTTP call:
+
+```
+GET {baseUrl}/api/v1/setup
+Authorization: Bearer sk_live_...
+Accept: application/json
+User-Agent: skillrepo-cli/1.0.0
+```
+
+Response is a `SetupPayload` JSON object (see `src/lib/setup/generate.ts` for the type).
+
+## What To Build
+
+### Approach: Subprocess + Mock HTTP Server
+
+Tests run the actual CLI binary (`node bin/skillrepo.mjs init`) as a child process against a lightweight mock HTTP server. This tests what users actually experience.
+
+### Test Runner
+
+Use `node:test` (Node.js built-in) — consistent with existing CLI tests in `packages/cli/src/test/`. Coverage via `c8` wrapping the subprocess.
+
+### Files To Create
+
+| File | Purpose |
+|------|---------|
+| `packages/cli/src/test/e2e/mock-server.mjs` | Minimal `node:http` server returning configurable `SetupPayload` |
+| `packages/cli/src/test/e2e/payload-factory.mjs` | Builds realistic payloads with various skill configurations |
+| `packages/cli/src/test/e2e/cli-init.test.mjs` | Full init flow E2E tests |
+
+### Mock Server Requirements
+
+- Listens on random available port
+- Serves `GET /api/v1/setup` with configurable payload
+- Validates `Authorization: Bearer sk_live_...` header
+- Returns 401 for invalid/missing keys
+- Returns 200 with payload for valid keys
+- Shuts down cleanly after tests
+
+### Payload Factory Requirements
+
+Must generate realistic `SetupPayload` objects matching what `generateSetupPayload()` produces. Include:
+
+1. Skills WITH contextSignals (files, project, tasks populated)
+2. Skills WITHOUT contextSignals (null)
+3. Skills with special characters in descriptions (colons, quotes — YAML safety)
+4. Configurable skill count
+5. Both Claude Code and Cursor output structures
+
+Reference `src/lib/setup/generate.ts` for the exact `SetupPayload` type:
+
+```typescript
+interface SetupPayload {
+  skillCount: number;
+  mcpUrl: string;
+  skillEntries: string[];
+  claudeCode: {
+    skillrepoMd: { path: string; content: string };
+    syncHook: { path: string; content: string };
+    settingsHooks: { hooks: Record<string, unknown> };
+    skillIndex: { path: string; content: string };
+    skillrepoConfig: { path: string; content: string };
+    promptHook: { path: string; content: string };
+    preToolHook: { path: string; content: string };
+  };
+  cursor: {
+    rules: Array<{ path: string; content: string }>;
+    hooksJson: { path: string; content: string };
+    sessionHook: { path: string; content: string };
+    skillIndex: { path: string; content: string };
+  };
+}
+```
+
+### Test Cases (goal-driven, not implementation-driven)
+
+Tests verify OUTCOMES ("does this produce a working setup?") not IMPLEMENTATION ("does the string contain this function name?").
+
+**1. Full Init Flow**
+- `init --yes --url http://localhost:{port} --key sk_live_test` in a temp dir produces all expected files
+- Running init twice produces correct merge behavior (updated, not duplicated)
+- Invalid API key returns clean auth error message
+- Unreachable server returns clean network error message
+
+**2. Generated Files Are Structurally Valid**
+- All JSON files (`skillrepo-config.json`, `skillrepo-index.json`, `hooks.json`, `settings.local.json`, `mcp.json`) parse without error
+- YAML frontmatter in `.mdc` files parses correctly (including descriptions with colons)
+- Hook scripts compile as valid JavaScript (`vm.compileFunction` or `new Function()`)
+
+**3. Signal Map Works End-to-End**
+- Extract `matchGlob` from the generated PreToolUse hook script, eval it, and test against real file paths:
+  - `**/*.tsx` matches `src/components/Button.tsx` ✓
+  - `**/*.tsx` does NOT match `src/utils/helper.ts` ✗
+  - `**/*.test.*` matches `tests/foo.test.ts` ✓
+  - `**/api/**/route.ts` matches `src/app/api/users/route.ts` ✓
+  - `**/*.{ts,tsx}` does not crash (regex metachar escaping) ✓
+- Extract `extractFilePath` and verify it parses tool input correctly
+- Extract `scoreSkills` and verify: task signals = 3x weight, keywords = 1x
+- Extract `applyProfileMultiplier` and verify: matching project = 1.5x, no match = 0.3x, no tags = 1.0x
+
+**4. Cursor Output Goals**
+- Skills with `contextSignals.files` produce per-skill `.mdc` with `globs` frontmatter
+- Skills without file signals go to aggregate `skillrepo.mdc` with `alwaysApply: true`
+- No skill appears in both per-skill AND aggregate files
+- `hooks.json` is valid JSON with `sessionStart` event
+- Session hook script produces valid `additional_context` JSON when executed
+
+**5. Claude Code Output Goals**
+- Config has `version: 2` and parseable `signals` array
+- Signal entries have toolName, files, project, tasks fields
+- Companions are correctly resolved
+- All three hooks registered in `settings.local.json`
+- Sync hook contains repo profiling logic
+
+**6. Repo Profiling**
+- In a simulated Next.js project (temp dir with `package.json` containing `next`, `react`), the sync hook's profiling code detects the correct frameworks
+- Execute the profiling section of the generated sync hook and verify the output
+
+**7. Security**
+- Server-supplied `.mdc` path outside `.cursor/` is rejected with error (path traversal protection)
+
+### How To Extract and Test Generated Functions
+
+The generated hook scripts are JavaScript strings. To test functions like `matchGlob`:
+
+```javascript
+import { readFileSync } from 'fs';
+
+// Read the generated hook script
+const script = readFileSync('.claude/hooks/skillrepo-pretool-match.mjs', 'utf-8');
+
+// Extract matchGlob function
+const matchGlobMatch = script.match(/function matchGlob\(filePath, pattern\) \{[\s\S]*?\n\}/);
+const matchGlobBody = matchGlobMatch[0]
+  .replace(/^function matchGlob\(filePath, pattern\) \{/, '')
+  .replace(/\}$/, '');
+const matchGlob = new Function('filePath', 'pattern', matchGlobBody);
+
+// Now test it
+assert.strictEqual(matchGlob('src/components/Button.tsx', '**/*.tsx'), true);
+assert.strictEqual(matchGlob('src/utils/helper.ts', '**/*.tsx'), false);
+```
+
+### Existing Test Patterns to Follow
+
+Look at `packages/cli/src/test/` for the established patterns:
+- `detect-ides.test.mjs` — temp directory creation, `process.cwd()` override
+- `mergers/hooks-json.test.mjs` — file merge testing (19 test cases)
+- `env-local.test.mjs` — `.env.local` merge behavior
+
+All use `node:test`, `node:assert`, `mkdtempSync`, `rmSync` for cleanup.
+
+### Coverage
+
+Use `c8` to instrument the CLI subprocess. Add to root `package.json`:
+
+```json
+"test:cli-e2e": "cd packages/cli && c8 node --test src/test/e2e/*.test.mjs"
+```
+
+Coverage output should be merged into the overall codecov upload in `.github/workflows/e2e.yml`.
+
+### Running the Tests
+
+```bash
+# From repo root
+cd packages/cli && node --test src/test/e2e/cli-init.test.mjs
+
+# With coverage
+cd packages/cli && c8 node --test src/test/e2e/cli-init.test.mjs
+```
+
+## Important Rules (from CLAUDE.md and memory)
+
+- NEVER edit `.claude/` generated files directly — modify generators in `src/lib/setup/generate.ts`
+- NEVER run tests against production — require explicit `DATABASE_URL_E2E` (this harness doesn't need a DB since it mocks the HTTP server)
+- Always use GitHub Issues, never Asana
+- Run `npm run check` before considering work complete
+- CLI is at `packages/cli/` — it's a standalone package with its own `package.json`
+- CLI version is currently 1.6.0 — bump if CLI code changes
+
+## References
+
+- Epic: https://github.com/atxpace/skill-repo/issues/457
+- Integration PR (merged): https://github.com/atxpace/skill-repo/pull/479
+- Review fixes PR: https://github.com/atxpace/skill-repo/pull/480
+- Approved plan: `/Users/jpace/.claude/plans/valiant-scribbling-whisper.md`
+- Existing CLI tests: `packages/cli/src/test/`
+- Server-side generator: `src/lib/setup/generate.ts`
+- CLI write orchestrator: `packages/cli/src/lib/write-configs.mjs`