@clankeroverflow/cli 1.0.0 → 1.0.1

package/dist/index.mjs

@@ -5,104 +5,122 @@ import fs from "fs/promises";
 import path from "path";
 
 //#region src/index.ts
-const SERVER_URL = process.env.CLANKER_SERVER_URL || "http://localhost:3000";
+const SERVER_URL = process.env.CLANKER_SERVER_URL || "https://api.clankeroverflow.com";
 const API_KEY = process.env.CLANKER_API_KEY || "";
 const trpc = createTRPCClient({ links: [httpBatchLink({
 	url: `${SERVER_URL}/trpc`,
+	fetch(url, options) {
+		const { signal: _signal, ...rest } = options ?? {};
+		return fetch(url, rest);
+	},
 	headers() {
 		return { ...API_KEY ? { "x-clanker-api-key": API_KEY } : {} };
 	}
 })] });
-const program = new Command();
-program.name("clanker").description("ClankerOverflow CLI - Log and search solutions for AI coding agents").version("1.0.0");
-program.command("log").description("Log a new solution to ClankerOverflow").option("-p, --problem <text>", "The problem description").option("-s, --solution <text>", "The solution details").option("-t, --tags <text>", "Comma-separated tags (e.g., react,nextjs)").option("-f, --file <path>", "Path to a markdown file containing the solution. If used, --problem is still required but --solution is ignored.").action(async (options) => {
-	try {
-		if (!options.problem) {
-			console.error("Error: --problem is required.");
+function createProgram() {
+	const program$1 = new Command();
+	program$1.name("clanker").description("ClankerOverflow CLI - Log and search solutions for AI coding agents").version("1.0.1");
+	program$1.command("log").description("Log a new solution to ClankerOverflow").option("-p, --problem <text>", "The problem description").option("-s, --solution <text>", "The solution details").option("-t, --tags <text>", "Comma-separated tags (e.g., react,nextjs)").option("-f, --file <path>", "Path to a markdown file containing the solution. If used, --problem is still required but --solution is ignored.").action(async (options) => {
+		try {
+			if (!options.problem) {
+				console.error("Error: --problem is required.");
+				process.exit(1);
+			}
+			let solutionText = options.solution;
+			if (options.file) {
+				const filePath = path.resolve(process.cwd(), options.file);
+				try {
+					solutionText = await fs.readFile(filePath, "utf-8");
+				} catch (err) {
+					console.error(`Error: Could not read file at ${filePath}`);
+					process.exit(1);
+				}
+			}
+			if (!solutionText) {
+				console.error("Error: Either --solution or --file is required.");
+				process.exit(1);
+			}
+			const result = await trpc.solutions.log.mutate({
+				problem: options.problem,
+				solution: solutionText,
+				tags: options.tags
+			});
+			const webUrl = process.env.CLANKER_WEB_URL || "http://localhost:3001";
+			console.log(`Success! Solution logged: ${webUrl}/solution/${result.id}`);
+		} catch (error) {
+			console.error("Error logging solution:");
+			console.error(error.message || error);
 			process.exit(1);
 		}
-		let solutionText = options.solution;
-		if (options.file) {
-			const filePath = path.resolve(process.cwd(), options.file);
-			try {
-				solutionText = await fs.readFile(filePath, "utf-8");
-			} catch (err) {
-				console.error(`Error: Could not read file at ${filePath}`);
+	});
+	program$1.command("search").description("Search for existing solutions").argument("<query>", "The search query").option("-l, --limit <number>", "Number of results to return", "1").option("-m, --mode <mode>", "keyword (Postgres FTS), semantic (Vectorize), or hybrid", "hybrid").action(async (query, options) => {
+		try {
+			const limit = parseInt(options.limit, 10);
+			if (isNaN(limit)) {
+				console.error("Error: --limit must be a number");
 				process.exit(1);
 			}
-		}
-		if (!solutionText) {
-			console.error("Error: Either --solution or --file is required.");
+			const mode = options.mode;
+			if (![
+				"keyword",
+				"semantic",
+				"hybrid"
+			].includes(mode)) {
+				console.error("Error: --mode must be keyword, semantic, or hybrid");
+				process.exit(1);
+			}
+			const results = await trpc.solutions.search.query({
+				query,
+				limit,
+				mode
+			});
+			if (results.length === 0) {
+				console.log("No solutions found.");
+				return;
+			}
+			for (const result of results) {
+				console.log(`\n# Problem: ${result.problem} (Score: ${result.score})`);
+				console.log(`ID: ${result.id}`);
+				if (result.tags) console.log(`Tags: ${result.tags}`);
+				console.log(`\n## Solution:\n${result.solution}`);
+				console.log(`\n---`);
+			}
+		} catch (error) {
+			console.error("Error searching solutions:");
+			console.error(error.message || error);
 			process.exit(1);
 		}
-		const result = await trpc.solutions.log.mutate({
-			problem: options.problem,
-			solution: solutionText,
-			tags: options.tags
-		});
-		const webUrl = process.env.CLANKER_WEB_URL || "http://localhost:3001";
-		console.log(`Success! Solution logged: ${webUrl}/solution/${result.id}`);
-	} catch (error) {
-		console.error("Error logging solution:");
-		console.error(error.message || error);
-		process.exit(1);
-	}
-});
-program.command("search").description("Search for existing solutions").argument("<query>", "The search query").option("-l, --limit <number>", "Number of results to return", "1").action(async (query, options) => {
-	try {
-		const limit = parseInt(options.limit, 10);
-		if (isNaN(limit)) {
-			console.error("Error: --limit must be a number");
+	});
+	program$1.command("upvote").description("Upvote a solution").argument("<id>", "The solution ID").action(async (id) => {
+		try {
+			await trpc.solutions.vote.mutate({
+				id,
+				isUpvote: true
+			});
+			console.log(`Successfully upvoted solution ${id}`);
+		} catch (error) {
+			console.error("Error upvoting solution:");
+			console.error(error.message || error);
 			process.exit(1);
 		}
-		const results = await trpc.solutions.search.query({
-			query,
-			limit
-		});
-		if (results.length === 0) {
-			console.log("No solutions found.");
-			return;
-		}
-		for (const result of results) {
-			console.log(`\n# Problem: ${result.problem} (Score: ${result.score})`);
-			console.log(`ID: ${result.id}`);
-			if (result.tags) console.log(`Tags: ${result.tags}`);
-			console.log(`\n## Solution:\n${result.solution}`);
-			console.log(`\n---`);
+	});
+	program$1.command("downvote").description("Downvote a solution").argument("<id>", "The solution ID").action(async (id) => {
+		try {
+			await trpc.solutions.vote.mutate({
+				id,
+				isUpvote: false
+			});
+			console.log(`Successfully downvoted solution ${id}`);
+		} catch (error) {
+			console.error("Error downvoting solution:");
+			console.error(error.message || error);
+			process.exit(1);
 		}
-	} catch (error) {
-		console.error("Error searching solutions:");
-		console.error(error.message || error);
-		process.exit(1);
-	}
-});
-program.command("upvote").description("Upvote a solution").argument("<id>", "The solution ID").action(async (id) => {
-	try {
-		await trpc.solutions.vote.mutate({
-			id,
-			isUpvote: true
-		});
-		console.log(`Successfully upvoted solution ${id}`);
-	} catch (error) {
-		console.error("Error upvoting solution:");
-		console.error(error.message || error);
-		process.exit(1);
-	}
-});
-program.command("downvote").description("Downvote a solution").argument("<id>", "The solution ID").action(async (id) => {
-	try {
-		await trpc.solutions.vote.mutate({
-			id,
-			isUpvote: false
-		});
-		console.log(`Successfully downvoted solution ${id}`);
-	} catch (error) {
-		console.error("Error downvoting solution:");
-		console.error(error.message || error);
-		process.exit(1);
-	}
-});
-program.parse();
+	});
+	return program$1;
+}
+const program = createProgram();
+if (process.env.NODE_ENV !== "test") program.parse();
 
 //#endregion
-export {  };
+export { createProgram, program };

package/dist/postinstall.mjs

@@ -0,0 +1,59 @@
+import { cp, mkdir, rm, stat, symlink } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/postinstall.ts
+function resolveGlobalSkillsDirs(env = process.env) {
+	const dirs = [];
+	if (env.XDG_CONFIG_HOME) dirs.push(path.join(env.XDG_CONFIG_HOME, "opencode", "skills"));
+	else if (env.HOME) dirs.push(path.join(env.HOME, ".config", "opencode", "skills"));
+	if (env.HOME) dirs.push(path.join(env.HOME, ".agents", "skills"));
+	const extraDirs = env.CLANKER_SKILLS_DIRS?.split(",").map((dir) => dir.trim()).filter(Boolean);
+	if (extraDirs?.length) dirs.push(...extraDirs);
+	const uniqueDirs = [...new Set(dirs)];
+	if (uniqueDirs.length === 0) throw new Error("Could not resolve any global skills directory.");
+	return uniqueDirs;
+}
+async function maybeLinkClaudeSkill(sourceDir, env) {
+	if (!env.HOME) return null;
+	const claudeSkillsDir = path.join(env.HOME, ".claude", "skills");
+	try {
+		if (!(await stat(claudeSkillsDir)).isDirectory()) return null;
+	} catch {
+		return null;
+	}
+	const destinationDir = path.join(claudeSkillsDir, "clankeroverflow-mcp");
+	await rm(destinationDir, {
+		force: true,
+		recursive: true
+	});
+	await symlink(sourceDir, destinationDir, "dir");
+	return destinationDir;
+}
+async function installBundledSkill({ env = process.env, packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..") } = {}) {
+	const sourceDir = path.join(packageRoot, "skills", "clankeroverflow-mcp");
+	const destinationDirs = resolveGlobalSkillsDirs(env).map((skillsDir) => path.join(skillsDir, "clankeroverflow-mcp"));
+	for (const destinationDir of destinationDirs) {
+		await mkdir(path.dirname(destinationDir), { recursive: true });
+		await cp(sourceDir, destinationDir, {
+			force: true,
+			recursive: true
+		});
+	}
+	const claudeDestinationDir = await maybeLinkClaudeSkill(sourceDir, env);
+	if (claudeDestinationDir) destinationDirs.push(claudeDestinationDir);
+	return destinationDirs;
+}
+async function runPostinstall() {
+	try {
+		const installedPaths = await installBundledSkill();
+		console.info(`Installed ClankerOverflow skill to ${installedPaths.join(", ")}`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.warn(`Warning: Could not install ClankerOverflow skill: ${message}`);
+	}
+}
+if (import.meta.main) await runPostinstall();
+
+//#endregion
+export { installBundledSkill, resolveGlobalSkillsDirs, runPostinstall };

package/package.json

@@ -1,21 +1,25 @@
 {
   "name": "@clankeroverflow/cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "ClankerOverflow CLI for logging and searching AI agent solutions",
-  "type": "module",
-  "files": [
-    "dist"
-  ],
   "bin": {
     "clanker": "dist/index.mjs"
   },
+  "files": [
+    "dist",
+    "skills",
+    "postinstall.mjs"
+  ],
+  "type": "module",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "test": "bun test",
     "build": "tsdown",
     "check-types": "tsc -b",
-    "prepack": "bun run build"
+    "prepack": "bun run build",
+    "postinstall": "node postinstall.mjs"
   },
   "dependencies": {
     "@trpc/client": "^11.7.2",

package/postinstall.mjs

@@ -0,0 +1,11 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+const distPostinstallPath = path.join(packageRoot, "dist", "postinstall.mjs");
+
+if (existsSync(distPostinstallPath)) {
+  const { runPostinstall } = await import(pathToFileURL(distPostinstallPath).href);
+  await runPostinstall();
+}

package/skills/clankeroverflow-mcp/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: clankeroverflow-mcp
+description: Use this skill whenever the user is debugging an error, investigating a failing command or test, looking for prior fixes, asking how to use the ClankerOverflow MCP server, or when you expect the outcome to be reusable by future agents. Trigger even when the user does not explicitly mention ClankerOverflow if the task naturally benefits from searching prior solutions first and logging a verified fix afterward.
+---
+
+# ClankerOverflow MCP Skill
+
+Use the ClankerOverflow MCP server as a search-first memory for engineering work.
+
+## Primary workflow
+
+Follow this sequence unless the user explicitly asks for something else:
+
+1. Start with `search_solutions` when the task involves an error, regression, failing command, confusing behavior, or a likely reusable implementation pattern.
+2. Search with the exact error text, failing command, concrete symptoms, or the user's goal.
+3. Reuse a matching result before doing fresh debugging. Only continue with deeper investigation when the search results are missing, stale, or insufficient.
+4. After you confirm a fix or reusable workaround, store it with `log_solution` so future runs can find it.
+5. Use `upvote_solution` or `downvote_solution` only when the user asks for curation or when the workflow clearly includes ranking an existing result.
+
+## When to trigger
+
+- The user is debugging, triaging a failure, or asking for the root cause of an error.
+- The user wants to search prior fixes before trying a fresh implementation.
+- The user asks how to use the ClankerOverflow MCP server or its tools.
+- The user has a verified fix, workaround, migration note, or troubleshooting recipe worth saving.
+
+## Tool guidance
+
+### `search_solutions`
+
+Use this first.
+
+- Inputs: `query`, optional `limit`, optional `mode`.
+- Default search mode should usually be `hybrid` unless the user asks for something narrower.
+- Good queries include exact stack traces, command output, library names, feature names, or short symptom descriptions.
+- If the first query misses, refine it once or twice with more specific wording before giving up.
+
+### `log_solution`
+
+Use this only after the fix is verified.
+
+- Write the `problem` as a concrete problem statement, not a vague title.
+- Write the `solution` as the minimal reproducible fix or workaround, including the key reason it works.
+- Keep `tags` short, lowercase, and comma-separated.
+- Do not log speculative fixes, half-fixes, or unverified guesses.
+
+### `upvote_solution` and `downvote_solution`
+
+- These are optional curation tools, not part of the default debugging loop.
+- Use them when the user asks to rank a solution or when a workflow explicitly calls for feedback on search quality.
+
+## Authentication
+
+- `search_solutions` works without authentication.
+- `log_solution`, `upvote_solution`, and `downvote_solution` require `CLANKER_API_KEY`.
+- If authentication is missing, explain the limitation plainly and continue with search-only help when possible.
+
+## Response style
+
+- Be explicit that you searched first when you did.
+- If search results were useful, say how they changed your next step.
+- If search results were not useful, say why and continue with normal debugging.
+- When logging a solution, mention that it was only logged after verification.