qbsm-init 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# qbsm-init
+
+One-shot CLI that wires **qb-skill-manager** (skills auto-extraction for Claude Code) into any project. After running this, Claude Code in that project can call the qbsm MCP server (SSE, hosted on Fly.io) to record skills demonstrated in the conversation.
+
+## Quick start
+
+```bash
+# 1. Sign up + issue an API token at https://qb-skill-manager.fly.dev/settings/tokens
+# 2. Run qbsm-init in your project directory:
+npx qbsm-init --api-key qbsm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+That writes three files in your project (all merged idempotently if they already exist):
+
+- `.mcp.json` — registers `qbsm` as a remote SSE MCP server
+- `CLAUDE.md` — appends a guidance section so Claude Code knows when to call the tools
+- `.claude/settings.json` — hooks that nudge the agent to call `register_skill` after package installs
+
+Then start a Claude Code session as usual; the `qbsm` server appears in `claude mcp list`.
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--api-key <key>` | Required (or interactive prompt). Get at `https://qb-skill-manager.fly.dev/settings/tokens` |
+| `--server-url <url>` | Override server (default `https://qb-skill-manager.fly.dev`) |
+| `-y, --yes` | Non-interactive mode; `--api-key` becomes required |
+| `--no-hooks` | Skip `.claude/settings.json` hook registration |
+| `--overwrite` | Replace existing `<qbsm:start>…<qbsm:end>` section in CLAUDE.md |
+| `-h, --help` | Show help |
+
+Positional `[target-path]` (default `.`) lets you point at a sibling directory.
+
+## Generated `.mcp.json` entry
+
+```json
+{
+  "mcpServers": {
+    "qbsm": {
+      "type": "sse",
+      "url": "https://qb-skill-manager.fly.dev/api/mcp/sse",
+      "headers": { "x-api-key": "qbsm_..." }
+    }
+  }
+}
+```
+
+`.mcp.json` is gitignored by default in Next.js / many templates. **Do not commit your API key**.
+
+## Tools exposed
+
+| Tool | Purpose |
+|------|---------|
+| `auth_status` | Confirm which user the API key resolves to |
+| `register_skill` | Record a demonstrated skill (idempotent on `category + name`) |
+| `update_skill` | Adjust proficiency / reason / tags on an existing skill |
+| `list_my_skills` | List the user's recent skills |
+
+## Tokens
+
+If a token is leaked, revoke it at `https://qb-skill-manager.fly.dev/settings/tokens` and re-run `qbsm-init --api-key <new>` to overwrite `.mcp.json`.

package/dist/init.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/init.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+const DEFAULT_SERVER_URL = "https://qb-skill-manager.fly.dev";
+const SERVER_KEY = "qbsm";
+const CLAUDE_MD_SECTION_START = "<!-- qbsm:start -->";
+const CLAUDE_MD_SECTION_END = "<!-- qbsm:end -->";
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    const flags = {
+        targetPath: ".",
+        serverUrl: DEFAULT_SERVER_URL,
+        yes: false,
+        noHooks: false,
+        overwrite: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--help" || a === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        else if (a === "--yes" || a === "-y") {
+            flags.yes = true;
+        }
+        else if (a === "--no-hooks") {
+            flags.noHooks = true;
+        }
+        else if (a === "--overwrite") {
+            flags.overwrite = true;
+        }
+        else if (a === "--api-key") {
+            flags.apiKey = args[++i];
+        }
+        else if (a === "--server-url") {
+            flags.serverUrl = args[++i];
+        }
+        else if (!a.startsWith("-")) {
+            flags.targetPath = a;
+        }
+    }
+    return flags;
+}
+function printHelp() {
+    console.log(`
+qbsm-init — set up qb-skill-manager MCP integration for a project
+
+Usage:
+  npx qbsm-init [target-path] --api-key <qbsm_...> [options]
+
+Options:
+  --api-key <key>      Required. API token from ${DEFAULT_SERVER_URL}/settings/tokens
+  --server-url <url>   Override server URL (default: ${DEFAULT_SERVER_URL})
+  -y, --yes            Skip all prompts; use defaults
+      --no-hooks       Skip .claude/settings.json hooks registration
+      --overwrite      Overwrite .mcp.json / CLAUDE.md section if present
+  -h, --help           Show this help
+
+What it does (idempotent merge):
+  - .mcp.json           adds an "${SERVER_KEY}" entry pointing to the SSE endpoint
+  - CLAUDE.md           appends a guidance section between qbsm:start/end markers
+  - .claude/settings.json
+                        registers PostToolUse (npm/pip/go/cargo install detector)
+                        and Stop (session-stop hint) hooks unless --no-hooks
+`);
+}
+function ask(question, defaultValue) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const suffix = defaultValue ? ` (${defaultValue})` : "";
+    return new Promise((resolveAns) => {
+        rl.question(`${question}${suffix}: `, (a) => {
+            rl.close();
+            resolveAns(a.trim() || defaultValue || "");
+        });
+    });
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(path, value, mode = 0o644) {
+    writeFileSync(path, JSON.stringify(value, null, 2) + "\n", { mode });
+}
+function writeMcpJson(target, apiKey, serverUrl, overwrite) {
+    const path = join(target, ".mcp.json");
+    const entry = {
+        type: "sse",
+        url: `${serverUrl.replace(/\/$/, "")}/api/mcp/sse`,
+        headers: { "x-api-key": apiKey },
+    };
+    let config = readJson(path) ?? {};
+    const servers = (config.mcpServers && typeof config.mcpServers === "object"
+        ? config.mcpServers
+        : {});
+    if (servers[SERVER_KEY] && !overwrite) {
+        // upsert: replace existing qbsm entry (always — overwrite flag is for non-qbsm collisions)
+    }
+    servers[SERVER_KEY] = entry;
+    config.mcpServers = servers;
+    writeJson(path, config);
+    return path;
+}
+const CLAUDE_MD_BODY = `## qbsm (qb-skill-manager) usage
+
+You have access to the **qbsm** MCP server (SSE, remote). Use it to record skills you observe in the conversation.
+
+When to call:
+- After installing a package (npm/pip/go/cargo), call \`register_skill\` with \`category: "technical"\`, \`type: "tool"\` and the package name.
+- When the user demonstrates a non-obvious soft / domain skill, call \`register_skill\` with appropriate category.
+- Use \`list_my_skills\` to recall what's already recorded before suggesting a skill.
+- Duplicates (same \`category + name\`) are deduplicated server-side; calling \`register_skill\` again only bumps the occurrence count.
+
+Tool reference:
+- \`auth_status\` — confirm which user the API key resolves to.
+- \`register_skill(category, type, name, proficiency, reason, [confidence], [tags], [excerpt])\` — record a skill.
+- \`update_skill(skillId, [proficiency], [reason], [tags])\` — adjust an existing skill.
+- \`list_my_skills([limit], [category])\` — list the user's recent skills.
+`;
+function writeClaudeMd(target, overwrite) {
+    const path = join(target, "CLAUDE.md");
+    const block = `${CLAUDE_MD_SECTION_START}\n${CLAUDE_MD_BODY}${CLAUDE_MD_SECTION_END}\n`;
+    if (!existsSync(path)) {
+        writeFileSync(path, block, { mode: 0o644 });
+        return { path, action: "created" };
+    }
+    const current = readFileSync(path, "utf-8");
+    const startIdx = current.indexOf(CLAUDE_MD_SECTION_START);
+    const endIdx = current.indexOf(CLAUDE_MD_SECTION_END);
+    if (startIdx !== -1 && endIdx !== -1) {
+        if (!overwrite)
+            return { path, action: "skipped" };
+        const before = current.slice(0, startIdx);
+        const after = current.slice(endIdx + CLAUDE_MD_SECTION_END.length);
+        writeFileSync(path, `${before}${block.trimEnd()}\n${after.startsWith("\n") ? after.slice(1) : after}`, { mode: 0o644 });
+        return { path, action: "replaced" };
+    }
+    const sep = current.endsWith("\n") ? "" : "\n";
+    writeFileSync(path, `${current}${sep}\n${block}`, { mode: 0o644 });
+    return { path, action: "appended" };
+}
+const POST_TOOL_USE_INLINE = `bash -c 'INPUT=$(cat); CMD=$(echo "$INPUT" | jq -r ".tool_input.command // empty"); TOOL=$(echo "$INPUT" | jq -r ".tool_name // empty"); if [ "$TOOL" = "Bash" ] && echo "$CMD" | grep -qE "^[[:space:]]*(npm|pnpm|yarn|bun)[[:space:]]+(install|add|i)[[:space:]]+|^[[:space:]]*(pip|pip3|uv pip)[[:space:]]+install[[:space:]]+|^[[:space:]]*go[[:space:]]+(get|install)[[:space:]]+|^[[:space:]]*cargo[[:space:]]+(add|install)[[:space:]]+"; then echo "[qbsm] Detected a package install — consider calling MCP tool register_skill for each package actually used."; fi'`;
+const SESSION_STOP_INLINE = `bash -c 'echo "[qbsm] Session ended — if this session demonstrated new skills, call register_skill via the qbsm MCP server before exiting."'`;
+function writeClaudeSettings(target) {
+    const dir = join(target, ".claude");
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, "settings.json");
+    const config = readJson(path) ?? {};
+    const hooks = (config.hooks && typeof config.hooks === "object"
+        ? config.hooks
+        : {});
+    function upsertHook(event, matcher, command) {
+        const list = Array.isArray(hooks[event]) ? hooks[event] : [];
+        const already = list.some((g) => g.hooks?.some((h) => h.type === "command" && h.command === command));
+        if (already)
+            return;
+        list.push({ ...(matcher ? { matcher } : {}), hooks: [{ type: "command", command }] });
+        hooks[event] = list;
+    }
+    upsertHook("PostToolUse", "Bash", POST_TOOL_USE_INLINE);
+    upsertHook("Stop", undefined, SESSION_STOP_INLINE);
+    config.hooks = hooks;
+    const action = existsSync(path) ? "merged" : "created";
+    writeJson(path, config);
+    return { path, action };
+}
+async function main() {
+    const flags = parseArgs(process.argv);
+    const target = resolve(flags.targetPath);
+    console.log("\n🔧 qbsm-init — qb-skill-manager setup\n");
+    if (!existsSync(target) || !statSync(target).isDirectory()) {
+        console.error(`✗ Target path is not a directory: ${target}`);
+        process.exit(1);
+    }
+    let apiKey = flags.apiKey;
+    if (!apiKey) {
+        if (flags.yes) {
+            console.error(`✗ --api-key is required when --yes is set. Get one at ${flags.serverUrl}/settings/tokens`);
+            process.exit(1);
+        }
+        apiKey = await ask(`API key from ${flags.serverUrl}/settings/tokens`);
+        if (!apiKey) {
+            console.error("✗ No api-key provided. Aborting.");
+            process.exit(1);
+        }
+    }
+    if (!apiKey.startsWith("qbsm_")) {
+        console.error("✗ API key must start with 'qbsm_'");
+        process.exit(1);
+    }
+    const mcpPath = writeMcpJson(target, apiKey, flags.serverUrl, flags.overwrite);
+    console.log(`✓ .mcp.json   ${mcpPath}`);
+    const claude = writeClaudeMd(target, flags.overwrite);
+    console.log(`✓ CLAUDE.md   ${claude.path} (${claude.action})`);
+    if (flags.noHooks) {
+        console.log("→ Skipped .claude/settings.json (--no-hooks)");
+    }
+    else {
+        const settings = writeClaudeSettings(target);
+        console.log(`✓ .claude/settings.json   ${settings.path} (${settings.action})`);
+    }
+    console.log(`
+Done. Start a Claude Code session in ${target} and the qbsm MCP server will be
+reachable at ${flags.serverUrl}/api/mcp/sse with your API key.
+
+To verify quickly:
+  cd ${target} && claude mcp list   # should include "qbsm"
+`);
+}
+main().catch((e) => {
+    console.error(`✗ ${e.message}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "qbsm-init",
+  "version": "0.1.0",
+  "description": "One-shot CLI to wire qb-skill-manager MCP into a project (.mcp.json + CLAUDE.md + hooks)",
+  "type": "module",
+  "bin": {
+    "qbsm-init": "dist/init.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "qb-skill-manager",
+    "qbsm"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QuestBoard-inc/qb-skill-manager.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/QuestBoard-inc/qb-skill-manager#readme",
+  "bugs": {
+    "url": "https://github.com/QuestBoard-inc/qb-skill-manager/issues"
+  },
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}