@llmkb/claude-code 0.1.0

package/lib/skills.ts

@@ -0,0 +1,554 @@
+/** Skill installer for ``llmkb init``.
+
+Copies built-in SKILL.md files from the package into
+``.claude/skills/llmkb/<name>/`` and stamps each skill directory with
+``.llmkb-version`` so ``llmkb status`` can detect version mismatches.
+
+For Cursor, writes ``.mdc`` rule files to ``.cursor/rules/llmkb/`` instead.
+*/
+
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { PACKAGE_VERSION } from "./types.js";
+
+export interface SkillDef {
+  name: string;
+  description: string;
+  body: string;
+}
+
+/** Built-in llmkb skill definitions. */
+const SKILLS: SkillDef[] = [
+  {
+    name: "llmkb-guide",
+    description:
+      "Use when the user asks how llmkb works, how to get started, or what llmkb can do. Examples: 'How do I use llmkb?', 'What is llmkb?', 'Get started with llmkb', 'Show me the llmkb architecture'",
+    body: [
+      "## Overview",
+      "",
+      "llmkb is an AI-powered knowledge base that transforms documents into an organized, interlinked wiki and knowledge graph. It uses a three-layer model: raw sources (PDFs, code, markdown) → LLM-generated wiki pages → structured knowledge graph with entity relationships.",
+      "",
+      "## Quick Start",
+      "",
+      "```",
+      "llmkb status            -- check your current configuration",
+      "llmkb whoami            -- show active space and credentials",
+      "docker compose --profile mvp ps  -- verify MCP server is running",
+      "```",
+      "",
+      "## Workflow",
+      "",
+      "### 1. Verify Setup",
+      "",
+      "Start by checking that everything is configured:",
+      "",
+      "- Run `llmkb status` to confirm version stamps match",
+      "- Run `llmkb whoami` to verify credentials are stored",
+      "- Check `docker compose --profile mvp ps` to confirm the API container is running",
+      "",
+      "### 2. Search the Wiki",
+      "",
+      "Use `space_search` with a specific query targeting your space:",
+      "",
+      "```",
+      "-- space_search example --",
+      `space_search(space_name: "my-project", query: "authentication flow")`,
+      "-- result: ranked list of wiki pages with snippets and confidence scores --",
+      "```",
+      "",
+      "### 3. Read a Page",
+      "",
+      "Get the full content of a wiki page:",
+      "",
+      "```",
+      "-- space_read example --",
+      `space_read(space_name: "my-project", path: "/docs/architecture")`,
+      "-- result: full wiki content with frontmatter, body, and metadata --",
+      "```",
+      "",
+      "### 4. Explore the Graph",
+      "",
+      "When you need to understand how concepts connect:",
+      "",
+      "```",
+      "-- space_graph example --",
+      `space_graph(space_name: "my-project", mode: "neighbours", entity: "AuthModule")`,
+      "-- result: entity nodes, relationship edges, and community clusters --",
+      "```",
+      "",
+      "### 5. Save New Information",
+      "",
+      "Write directly to a space when you discover something new:",
+      "",
+      "```",
+      "-- space_write example --",
+      `space_write(`,
+      `  space_name: "my-project",`,
+      `  path: "/notes/api-pattern",`,
+      `  content: "# API Pattern\\nThe project uses repository pattern with SQLAlchemy."`,
+      `)`,
+      "-- result: new wiki page created in the space --",
+      "```",
+      "",
+      "## Troubleshooting",
+      "",
+      "| Error | Cause | Fix |",
+      "|-------|-------|-----|",
+      '| "Space not found" | Wrong space name | Run `llmkb use` to see configured spaces |',
+      '| "Token required" | Private space needs auth | Run `llmkb login --space <name>` |',
+      "| MCP server timeout | Docker not running | `docker compose --profile mvp ps` to check |",
+      "| Version mismatch | Skills or config out of date | `llmkb init` to re-install |",
+      "",
+      "## Self-Check",
+      "",
+      "- [ ] Active space configured via `llmkb status`",
+      "- [ ] Tokens stored in keychain or env vars",
+      "- [ ] MCP server reachable: `docker compose --profile mvp ps`",
+      "- [ ] Version stamps match package version",
+    ].join("\n"),
+  },
+  {
+    name: "llmkb-query",
+    description:
+      "Use when searching or reading wiki content via MCP tools. Examples: 'Search the wiki for X', 'Read this wiki page', 'Find relevant documentation', 'Look up authentication patterns', 'What does the wiki say about pgvector?'",
+    body: [
+      "## Overview",
+      "",
+      "Search and read your llmkb wiki using hybrid full-text + vector search and knowledge graph navigation. Start with `space_search` to find relevant pages, then use `space_read` to get full content.",
+      "",
+      "## Quick Start",
+      "",
+      "```",
+      "-- search for information --",
+      `space_search(space_name: "my-project", query: "pgvector indexing")`,
+      "",
+      "-- read a specific page --",
+      `space_read(space_name: "my-project", path: "/docs/indexing-strategy")`,
+      "```",
+      "",
+      "## Workflow",
+      "",
+      "### 1. Find Relevant Content",
+      "",
+      "Start with `space_search` to locate relevant wiki pages:",
+      "",
+      "```",
+      "-- search with a specific query --",
+      `space_search(space_name: "my-project", query: "authentication flow")`,
+      "",
+      "-- search with confidence filter --",
+      `space_search(space_name: "my-project", query: "database schema", min_confidence: 0.8)`,
+      "```",
+      "",
+      "Returns ranked results with paths, snippets, confidence scores, and entity types.",
+      "",
+      "### 2. Read Full Content",
+      "",
+      "Once you have identified the right page, read it fully:",
+      "",
+      "```",
+      "-- read by path --",
+      `space_read(space_name: "my-project", path: "/docs/architecture")`,
+      "",
+      "-- result includes frontmatter (type, category, source_pages) and full body content --",
+      "```",
+      "",
+      "### 3. Get a Space Overview",
+      "",
+      "For a structured summary of a space's content:",
+      "",
+      "```",
+      "-- overview of all entities and pages --",
+      `space_guide(space_name: "my-project")`,
+      "-- result: summary of entity types, page categories, and top-level relationships --",
+      "```",
+      "",
+      "### 4. Explore Entity Relationships",
+      "",
+      "When search results surface an entity, dig into its connections:",
+      "",
+      "```",
+      "-- find neighbours of a specific entity --",
+      `space_graph(space_name: "my-project", mode: "neighbours", entity: "AuthModule")`,
+      "-- result: all entities directly connected to AuthModule with relationship types --",
+      "```",
+      "",
+      "## Troubleshooting",
+      "",
+      "| Error | Cause | Fix |",
+      "|-------|-------|-----|",
+      "| Empty results | Query too narrow | Broaden terms or check space has content with `space_guide` |",
+      '| "Space not found" | Wrong space name | `llmkb status` to list configured spaces |',
+      "| Path not found | Page path incorrect | Search first with `space_search` to find the exact path |",
+      "| Token error | Expired credentials | `llmkb login --space <name>` |",
+      "",
+      "## Self-Check",
+      "",
+      "- [ ] Used `space_search` first to find relevant pages",
+      "- [ ] Used `space_read` to get full context when snippet is insufficient",
+      "- [ ] Verified the space name matches a configured space",
+      "- [ ] Used `space_graph` for deeper relationship exploration when needed",
+    ].join("\n"),
+  },
+  {
+    name: "llmkb-sync",
+    description:
+      "Use when syncing local files to an llmkb space for ingestion. Examples: 'Upload these docs', 'Sync this folder to my wiki', 'Ingest this README', 'Watch this directory for changes', 'Upload my codebase'",
+    body: [
+      "## Overview",
+      "",
+      "Sync local files and codebases to your llmkb spaces for processing and wiki generation. Files are content-addressed (SHA256) so unchanged files skip re-processing. Supports PDF, Markdown, code files, images, and audio.",
+      "",
+      "## Quick Start",
+      "",
+      "```",
+      "llmkb sync                    -- sync current directory to active space",
+      "llmkb sync --space my-project -- sync to a specific space",
+      "llmkb sync --watch            -- watch directory for changes",
+      "```",
+      "",
+      "## Workflow",
+      "",
+      "### 1. Sync Files to a Space",
+      "",
+      "Navigate to the directory containing files you want to ingest and run:",
+      "",
+      "```",
+      "cd /path/to/your/project",
+      "llmkb sync --space my-project",
+      "```",
+      "",
+      "The command will:",
+      "",
+      "1. Walk the directory recursively",
+      "2. Compute SHA256 hashes for each file",
+      "3. Skip unchanged files (cached in `.llmkb/sync-state.json`)",
+      "4. Upload new/changed files via TUS protocol",
+      "5. Report progress per file",
+      "",
+      "### 2. Watch for Changes",
+      "",
+      "Keep a directory synced automatically:",
+      "",
+      "```",
+      "llmkb sync --watch --space my-project",
+      "```",
+      "",
+      "Watcher behaviour:",
+      "",
+      "- Respects `.gitignore` and `.llmkbignore` patterns",
+      "- Debounces rapid file changes",
+      "- Detects file renames by content hash (not path)",
+      "- Press Ctrl+C to stop watching",
+      "",
+      "### 3. Check Sync Status",
+      "",
+      "After syncing, verify ingestion progress:",
+      "",
+      "```",
+      "llmkb status --space my-project",
+      "```",
+      "",
+      "### 4. Query Synced Content",
+      "",
+      "Once processing completes, search the newly ingested content:",
+      "",
+      "```",
+      `space_search(space_name: "my-project", query: "topics from the synced files")`,
+      "```",
+      "",
+      "## Troubleshooting",
+      "",
+      "| Error | Cause | Fix |",
+      "|-------|-------|-----|",
+      "| File skipped | Matches .gitignore or .llmkbignore | Check ignore files |",
+      "| Upload failed | TUS endpoint unreachable | Verify Docker is running |",
+      "| Hash mismatch | File changed during upload | Re-run `llmkb sync` |",
+      '| "No space configured" | No active space | `llmkb use <space-name>` |',
+      "| Sync slow | Large directory | Use `--verbose` to see progress; files over 5MB use chunked TUS uploads |",
+      "",
+      "## Self-Check",
+      "",
+      "- [ ] Files upload successfully (check terminal output for each file)",
+      "- [ ] Ingestion job progresses through phases",
+      "- [ ] Wiki pages generated after processing completes",
+      "- [ ] Unchanged files are skipped (cached by SHA256)",
+    ].join("\n"),
+  },
+  {
+    name: "llmkb-exploring",
+    description:
+      "Use when exploring architecture, codebase structure, and entity relationships. Examples: 'How does X work?', 'Show me the codebase architecture', 'What connections exist in this space?', 'Find relationships between these concepts', 'Map the auth module dependencies'",
+    body: [
+      "## Overview",
+      "",
+      "Explore entity relationships, knowledge graph structure, and how different pieces of information connect in your llmkb spaces. Use graph queries to discover neighbours, find paths between entities, and get structured space overviews.",
+      "",
+      "## Quick Start",
+      "",
+      "```",
+      "-- explore neighbours of an entity --",
+      `space_graph(space_name: "my-project", mode: "neighbours", entity: "AuthModule")`,
+      "",
+      "-- find path between two entities --",
+      `space_graph(space_name: "my-project", mode: "path", source: "ServiceA", target: "ServiceB")`,
+      "```",
+      "",
+      "## Workflow",
+      "",
+      "### 1. Get a Space Overview",
+      "",
+      "Start with `space_guide` for a high-level summary:",
+      "",
+      "```",
+      `space_guide(space_name: "my-project")`,
+      "-- result: entity count, relationship count, page categories, top-level clusters --",
+      "```",
+      "",
+      "### 2. Explore Neighbourhoods",
+      "",
+      "Drill into a specific entity to see its direct connections:",
+      "",
+      "```",
+      `space_graph(space_name: "my-project", mode: "neighbours", entity: "AuthModule")`,
+      "-- result: all entities directly connected to AuthModule with relationship types and confidence scores --",
+      "```",
+      "",
+      "### 3. Find Paths",
+      "",
+      "Discover how two entities connect through intermediate nodes:",
+      "",
+      "```",
+      `space_graph(space_name: "my-project", mode: "path", source: "Database", target: "UserService")`,
+      "-- result: shortest path showing each hop with relationship type --",
+      "```",
+      "",
+      "### 4. Search Within the Exploration",
+      "",
+      "When you find interesting entities, search for more details:",
+      "",
+      "```",
+      `space_search(space_name: "my-project", query: "user authentication")`,
+      "```",
+      "",
+      "## Troubleshooting",
+      "",
+      "| Error | Cause | Fix |",
+      "|-------|-------|-----|",
+      "| Empty graph | Space has no processed content | Run `llmkb sync` to upload files first |",
+      '| "Entity not found" | Wrong entity name | Use `space_search` to find the exact label |',
+      "| No path found | Entities not connected in the graph | Try broader search to find bridging entities |",
+      "| Graph too large | Too many neighbours | Narrow the entity or use `space_search` instead |",
+      "",
+      "## Self-Check",
+      "",
+      "- [ ] Started with `space_guide` for orientation",
+      "- [ ] Used `space_graph` with `neighbours` mode for direct connections",
+      "- [ ] Used `space_graph` with `path` mode for indirect connections",
+      "- [ ] Followed up with `space_search` for deeper context",
+    ].join("\n"),
+  },
+  {
+    name: "llmkb-admin",
+    description:
+      "Use when managing spaces, tokens, configuration, or credentials. Examples: 'Show my space members', 'Configure a new space', 'Manage API tokens', 'Switch active space', 'Check my credentials', 'Set up a new project with llmkb'",
+    body: [
+      "## Overview",
+      "",
+      "Manage llmkb spaces, API tokens, configuration settings, and credentials. The CLI provides commands for switching spaces, authenticating, and verifying setup.",
+      "",
+      "## Quick Start",
+      "",
+      "```",
+      "llmkb status              -- check version stamps and active config",
+      "llmkb use my-project      -- switch active space",
+      "llmkb login --space admin -- store credentials for a space",
+      "```",
+      "",
+      "## Workflow",
+      "",
+      "### 1. Initialise a Project",
+      "",
+      "Set up a new project with llmkb:",
+      "",
+      "```",
+      "cd /path/to/project",
+      "llmkb init --space my-project",
+      "```",
+      "",
+      "This creates:",
+      "",
+      "- `.claude-plugin/plugin.json` — plugin metadata for discovery",
+      "- `.mcp.json` — MCP server registration with Docker stdio transport",
+      "- `.llmkb/spaces.yml` — space configuration",
+      "- `.llmkb/config.yml` — plugin behaviour settings",
+      "- `.claude/skills/llmkb/` — 5 Claude Code skills",
+      "",
+      "For Cursor: `llmkb init --platform cursor` writes equivalent `.cursor/` files.",
+      "",
+      "To skip skill installation: `llmkb init --no-with-skills` (for config-only setup).",
+      "",
+      "### 2. Authenticate",
+      "",
+      "Store credentials for a space after init:",
+      "",
+      "```",
+      "llmkb login --space my-project",
+      "```",
+      "",
+      "This stores the space token in the OS keychain. For CI/headless environments, set the `LLMKB_TOKEN` environment variable instead.",
+      "",
+      "### 3. Switch Spaces",
+      "",
+      "When working with multiple spaces:",
+      "",
+      "```",
+      "llmkb use client-project",
+      "llmkb login --space client-project",
+      "llmkb status --space client-project",
+      "```",
+      "",
+      "### 4. Verify Setup",
+      "",
+      "Check that everything is configured correctly:",
+      "",
+      "```",
+      "llmkb status",
+      "llmkb whoami",
+      "```",
+      "",
+      "The `status` command warns on:",
+      "",
+      "- Config version mismatch: `llmkb init` to update",
+      "- Skill version mismatch: `llmkb init` to re-install skills",
+      "- Missing or expired tokens",
+      "",
+      "### 5. Token Management",
+      "",
+      "- Space tokens grant read access to a specific space",
+      "- Admin tokens grant write/admin access",
+      "- Tokens are stored in the OS keychain (requires `keychain` package)",
+      "- Set `LLMKB_TOKEN` / `LLMKB_ADMIN_TOKEN` env vars for CI",
+      "- Token groups allow sharing a single token across multiple spaces",
+      "",
+      "## Troubleshooting",
+      "",
+      "| Error | Cause | Fix |",
+      "|-------|-------|-----|",
+      '| "Version mismatch" | Config or skills out of date | `llmkb init` to update |',
+      '| "Not found: .llmkb/" | Project not initialised | `llmkb init` first |',
+      "| Keychain access denied | Missing keychain permission | Fall back to `LLMKB_TOKEN` env var |",
+      "| Token expired | Credentials rotated | `llmkb login --space <name>` |",
+      "| Multiple spaces confusing | Wrong active space | `llmkb use <name>` to switch |",
+      "",
+      "## Self-Check",
+      "",
+      "- [ ] Project initialised with `llmkb init`",
+      "- [ ] Tokens stored and accessible (keychain or env vars)",
+      "- [ ] Correct space is active via `llmkb use`",
+      "- [ ] Version stamps match package version (`llmkb status`)",
+      "- [ ] MCP server is running: `docker compose --profile mvp ps`",
+    ].join("\n"),
+  },
+];
+
+/**
+ * Install all built-in skills to the appropriate platform path.
+ *
+ * For Claude Code: writes SKILL.md files to `.claude/skills/llmkb/<name>/`.
+ * For Cursor: writes `.mdc` rule files to `.cursor/rules/llmkb/`.
+ *
+ * Creates idempotent copies — safe to re-run.
+ *
+ * @param platform Target platform: "claude" (default) or "cursor".
+ * @returns The number of skills installed.
+ */
+export async function installSkills(
+  platform: "claude" | "cursor" = "claude",
+  projectDir?: string,
+): Promise<number> {
+  if (platform === "cursor") {
+    // Cursor skills are handled by writer.ts writeCursorRules()
+    // This function only handles Claude Code SKILL.md installation
+    return 0;
+  }
+
+  const projectRoot = projectDir ?? process.cwd();
+  const targetDir = join(projectRoot, ".claude", "skills", "llmkb");
+
+  for (const skill of SKILLS) {
+    const skillDir = join(targetDir, skill.name);
+    await mkdir(skillDir, { recursive: true });
+
+    const trigger = skill.name.replace("llmkb-", "/llmkb-");
+
+    const frontmatter = [
+      "---",
+      `name: ${skill.name}`,
+      `description: ${skill.description}`,
+      `trigger: ${trigger}`,
+      "---",
+      "",
+    ].join("\n");
+
+    await writeFile(
+      join(skillDir, "SKILL.md"),
+      frontmatter + skill.body + "\n",
+      "utf-8",
+    );
+
+    // Version stamp
+    await writeFile(
+      join(skillDir, ".llmkb-version"),
+      PACKAGE_VERSION + "\n",
+      "utf-8",
+    );
+  }
+
+  return SKILLS.length;
+}
+
+/**
+ * Check version stamps of all installed skills against the current package version.
+ *
+ * @param skillsDir Absolute path to `.claude/skills/llmkb/`.
+ * @returns Array of version mismatches, one per skill directory.
+ */
+export async function checkSkillVersions(
+  skillsDir: string,
+): Promise<{ name: string; installed: string; current: string }[]> {
+  const mismatches: { name: string; installed: string; current: string }[] = [];
+
+  if (!existsSync(skillsDir)) return mismatches;
+
+  const { readdir } = await import("node:fs/promises");
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const versionPath = join(skillsDir, entry.name, ".llmkb-version");
+    try {
+      const content = await readFile(versionPath, "utf-8");
+      const installedVersion = content.split("\n")[0]?.trim();
+      if (installedVersion && installedVersion !== PACKAGE_VERSION) {
+        mismatches.push({
+          name: entry.name,
+          installed: installedVersion,
+          current: PACKAGE_VERSION,
+        });
+      }
+    } catch {
+      // No version stamp file — treat as mismatch
+      mismatches.push({
+        name: entry.name,
+        installed: "(none)",
+        current: PACKAGE_VERSION,
+      });
+    }
+  }
+
+  return mismatches;
+}