@llmkb/claude-code 0.1.0

package/lib/writer.ts

@@ -0,0 +1,409 @@
+/** Idempotent config-file scaffolder.
+
+Creates the files that ``llmkb init`` places into the project root:
+``.claude-plugin/plugin.json``, ``.mcp.json``, ``.llmkb/spaces.yml``,
+``.llmkb/config.yml``, and a version stamp at ``.llmkb/.llmkb-version``.
+
+Supports ``--platform cursor`` to write Cursor-specific paths instead.
+*/
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { stringify } from "yaml";
+import {
+  PACKAGE_VERSION,
+  getDefaultPluginConfig,
+  type SpaceConfig,
+  type SpaceDef,
+} from "./types.js";
+import { readVersionStamp } from "./parser.js";
+import { writeHooks } from "../src/commands/hooks.js";
+
+export interface ScaffoldOptions {
+  /** Project root directory (defaults to ``process.cwd()``). */
+  projectDir?: string;
+  /** Target platform for config file paths. */
+  platform?: "claude" | "cursor";
+  /** Optional space name to pre-fill in the config. */
+  spaceName?: string;
+  /** Optional list of spaces for interactive multi-space setup. */
+  spaceDefs?: SpaceDef[];
+  /** Force overwrite even if version stamp matches. */
+  force?: boolean;
+  /** Also scaffold hook files. */
+  withHooks?: boolean;
+}
+
+function projectPath(projectDir: string, ...parts: string[]): string {
+  return resolve(projectDir, ...parts);
+}
+
+async function ensureDir(filePath: string): Promise<void> {
+  await mkdir(filePath, { recursive: true });
+}
+
+/** Plugin metadata file (required by Claude Code for discovery). */
+const PLUGIN_JSON = {
+  name: "llmkb",
+  description:
+    "LLM-powered knowledge base with wiki generation, semantic search, and knowledge graphs. Sync codebases, query spaces, and explore architecture from Claude.",
+  version: PACKAGE_VERSION,
+  author: { name: "llmkb" },
+  homepage: "https://llmkb.ai",
+  keywords: ["knowledge-base", "wiki", "mcp"],
+};
+
+/** MCP server registration (Docker stdio transport via --profile mvp). */
+const MCP_JSON_CLAUDE = {
+  mcpServers: {
+    llmkb: {
+      description:
+        "llmkb wiki — search, read, and write your knowledge base via MCP tools",
+      command: "docker",
+      args: [
+        "compose",
+        "--profile",
+        "mvp",
+        "exec",
+        "-i",
+        "api",
+        "python",
+        "-m",
+        "app.mcp.stdio",
+      ],
+    },
+  },
+};
+
+const MCP_JSON_CURSOR = {
+  mcpServers: {
+    llmkb: {
+      description:
+        "llmkb wiki — search, read, and write your knowledge base via MCP tools",
+      command: "docker",
+      args: [
+        "compose",
+        "--profile",
+        "mvp",
+        "exec",
+        "-i",
+        "api",
+        "python",
+        "-m",
+        "app.mcp.stdio",
+      ],
+    },
+  },
+};
+
+/** Build the ``spaces.yml`` content as a typed YAML document. */
+function buildSpaceConfig(spaceDefs: SpaceDef[]): SpaceConfig {
+  const config: SpaceConfig = {};
+  if (spaceDefs.length > 0) {
+    config.project_space = [{ id: spaceDefs[0]!.id }];
+    config.spaces = spaceDefs;
+  }
+  return config;
+}
+
+/** Build the default ``spaces.yml`` content with optional single-space pre-fill. */
+function spacesYml(projectSpaceId?: string): string {
+  if (!projectSpaceId) {
+    // Emit a fully commented-out template
+    return [
+      `# llmkb space configuration`,
+      `# Managed by \`llmkb init\`. Edit to add or remove spaces.`,
+      `#`,
+      `# Example:`,
+      `# project_space:`,
+      `#   - id: b6087faa-0bf0-4935-98b2-f3100905b99c`,
+      `#     slug: my_project`,
+      `#     name: "My Project"`,
+      `#   dirs: ['app', 'src']`,
+      `# spaces:`,
+      `#   - id: c599f13a-2d75-4e4e-8fb3-03afbac7e115`,
+      `#     name: "Reference Library"`,
+      `#     slug: reference_library`,
+      ``,
+    ].join("\n");
+  }
+
+  const config: SpaceConfig = {
+    project_space: [{ id: projectSpaceId }],
+  };
+  return (
+    `# llmkb space configuration\n` +
+    `# Managed by \`llmkb init\`. Edit to add or remove spaces.\n\n` +
+    stringify(config, { lineWidth: 120 })
+  );
+}
+
+/** Build ``.llmkb/config.yml`` with commented-out defaults. */
+function configYml(): string {
+  const defaults = getDefaultPluginConfig();
+
+  return [
+    `# .llmkb/config.yml — plugin behavior settings`,
+    `# Managed by \`llmkb init\`. Uncomment fields to override defaults.`,
+    ``,
+    `# llmkb_base_url: ${defaults.llmkb_base_url}`,
+    `#`,
+    `# watch:`,
+    `#   enabled: ${defaults.watch!.enabled}`,
+    `#   debounce_ms: ${defaults.watch!.debounce_ms}`,
+    `#   gitignore: ${defaults.watch!.gitignore}`,
+    `#   llmkbignore: ${defaults.watch!.llmkbignore}`,
+    `#   default_verbosity: ${defaults.watch!.default_verbosity}`,
+    `#`,
+    `# sync:`,
+    `#   concurrency: ${defaults.sync!.concurrency}`,
+    `#   retry_attempts: ${defaults.sync!.retry_attempts}`,
+    `#   retry_delay_ms: ${defaults.sync!.retry_delay_ms}`,
+    `#`,
+    `# hook:`,
+    `#   timeout_ms: ${defaults.hook!.timeout_ms}`,
+    `#   skip: ${defaults.hook!.skip}`,
+    `#`,
+    `# debug: ${defaults.debug}`,
+    ``,
+  ].join("\n");
+}
+
+/** Scaffold .claude-plugin/plugin.json */
+async function writePluginJson(projectDir: string): Promise<void> {
+  const dir = projectPath(projectDir, ".claude-plugin");
+  await ensureDir(dir);
+  await writeFile(
+    join(dir, "plugin.json"),
+    JSON.stringify(PLUGIN_JSON, null, 2) + "\n",
+    "utf-8",
+  );
+}
+
+/** Scaffold .mcp.json (Claude) or .cursor/mcp.json (Cursor). */
+async function writeMcpJson(
+  projectDir: string,
+  platform: "claude" | "cursor",
+): Promise<void> {
+  if (platform === "cursor") {
+    const dir = projectPath(projectDir, ".cursor");
+    await ensureDir(dir);
+    await writeFile(
+      join(dir, "mcp.json"),
+      JSON.stringify(MCP_JSON_CURSOR, null, 2) + "\n",
+      "utf-8",
+    );
+  } else {
+    await writeFile(
+      projectPath(projectDir, ".mcp.json"),
+      JSON.stringify(MCP_JSON_CLAUDE, null, 2) + "\n",
+      "utf-8",
+    );
+  }
+}
+
+/** Scaffold .llmkb/spaces.yml, .llmkb/config.yml, and .llmkb/.llmkb-version.
+
+Idempotent: if ``.llmkb/.llmkb-version`` exists and matches the current
+package version, all llmkb writes are skipped — the user's customizations
+are preserved. Call ``scaffoldConfig`` with ``force: true`` to bypass.
+
+@returns The list of files actually written (empty if skipped by idempotency).
+*/
+async function writeLlmkbDir(
+  projectDir: string,
+  spaceName?: string,
+  spaceDefs?: SpaceDef[],
+  force?: boolean,
+): Promise<string[]> {
+  const dir = projectPath(projectDir, ".llmkb");
+  const written: string[] = [];
+
+  // Idempotency check: skip if version stamp matches
+  if (!force) {
+    const stamp = await readVersionStamp(projectDir);
+    if (stamp === PACKAGE_VERSION) return written;
+  }
+
+  await ensureDir(dir);
+
+  // Write spaces.yml
+  if (spaceDefs && spaceDefs.length > 0) {
+    const config = buildSpaceConfig(spaceDefs);
+    await writeFile(
+      join(dir, "spaces.yml"),
+      stringify(config, { lineWidth: 120 }),
+      "utf-8",
+    );
+  } else {
+    await writeFile(
+      join(dir, "spaces.yml"),
+      spacesYml(spaceName) + "\n",
+      "utf-8",
+    );
+  }
+  written.push(".llmkb/spaces.yml");
+
+  // Write config.yml with commented-out defaults
+  await writeFile(join(dir, "config.yml"), configYml(), "utf-8");
+  written.push(".llmkb/config.yml");
+
+  // Write version stamp
+  await writeFile(join(dir, ".llmkb-version"), PACKAGE_VERSION + "\n", "utf-8");
+  written.push(".llmkb/.llmkb-version");
+
+  return written;
+}
+
+/** All cursor rule files for the llmkb knowledge base. */
+const CURSOR_RULES: Array<{
+  name: string;
+  description: string;
+  globs: string[];
+  content: string;
+}> = [
+  {
+    name: "llmkb-guide.mdc",
+    description:
+      "llmkb overview, architecture, getting started, and how to use llmkb spaces",
+    globs: ["*"],
+    content: [
+      "llmkb is an AI-powered knowledge base. It uses a three-layer model: raw sources (PDFs, code, markdown) -> LLM-generated wiki pages -> knowledge graph.",
+      "",
+      "- Run `docker compose --profile mvp ps` to verify the MCP server is running",
+      "- Use `space_search(space_name, query)` to find relevant wiki pages",
+      "- Use `space_read(space_name, path)` to read a specific wiki page",
+      "- Use `space_graph(space_name, mode, entity)` to explore entity relationships",
+      "- Check `llmkb status` to verify setup is correct",
+    ].join("\n"),
+  },
+  {
+    name: "llmkb-query.mdc",
+    description:
+      "Search and read wiki content via MCP tools — use space_search and space_read",
+    globs: ["*"],
+    content: [
+      "When asked to find information, always:",
+      "",
+      "1. Start with `space_search` to locate relevant wiki pages:",
+      `   space_search(space_name: "my-project", query: "<user's question>")`,
+      "2. Read the full content of the best matching page:",
+      `   space_read(space_name: "my-project", path: "/path/to/page")`,
+      "3. For relationship context, use:",
+      `   space_graph(space_name: "my-project", mode: "neighbours", entity: "<entity name>")`,
+    ].join("\n"),
+  },
+  {
+    name: "llmkb-sync.mdc",
+    description:
+      "File sync and upload rules — run llmkb sync after making significant changes",
+    globs: ["*"],
+    content: [
+      "Files modified under this project should be synced to the configured llmkb space.",
+      "",
+      "- Run `llmkb sync` from the project root after significant changes",
+      "- For continuous syncing: `llmkb sync --watch`",
+      "- Files are content-addressed (SHA256); unchanged files skip re-processing",
+      "- Respects .gitignore and .llmkbignore patterns",
+      "- After syncing, use `llmkb status` to check ingestion progress",
+    ].join("\n"),
+  },
+  {
+    name: "llmkb-exploring.mdc",
+    description:
+      "Architecture and graph exploration — use space_graph for entity relationships",
+    globs: ["*"],
+    content: [
+      "When asked about code architecture or entity relationships:",
+      "",
+      "1. Start with `space_guide` for a structured overview:",
+      `   space_guide(space_name: "my-project")`,
+      "2. Explore entity neighbourhoods:",
+      `   space_graph(space_name: "my-project", mode: "neighbours", entity: "<entity>")`,
+      "3. Find paths between entities:",
+      `   space_graph(space_name: "my-project", mode: "path", source: "<source>", target: "<target>")`,
+      "4. Follow up with `space_search` for deeper context",
+    ].join("\n"),
+  },
+  {
+    name: "llmkb-admin.mdc",
+    description:
+      "Space management, token setup, credentials, configuration, and llmkb CLI commands",
+    globs: ["*"],
+    content: [
+      "When setting up or managing llmkb:",
+      "",
+      "- `llmkb init` — scaffold project config files and skills",
+      "- `llmkb init --no-with-skills` — config-only setup (skip skills)",
+      "- `llmkb init --platform cursor` — use Cursor-compatible paths",
+      "- `llmkb login --project-space <id>` — store access token in keychain",
+      "- `llmkb whoami` — show current user identity and access token status",
+      "- `llmkb status` — verify versions, config, and installed skills",
+      "- Set LLMKB_ACCESS_TOKEN env var for CI/headless environments",
+    ].join("\n"),
+  },
+];
+
+/** Scaffold .cursor/rules/llmkb/ with all rule files. */
+async function writeCursorRules(projectDir: string): Promise<void> {
+  const rulesDir = projectPath(projectDir, ".cursor", "rules", "llmkb");
+  await ensureDir(rulesDir);
+  for (const rule of CURSOR_RULES) {
+    const frontmatter = [
+      "---",
+      `name: ${rule.name}`,
+      `description: ${rule.description}`,
+      `globs: ${JSON.stringify(rule.globs)}`,
+      "---",
+      "",
+    ].join("\n");
+    await writeFile(
+      join(rulesDir, rule.name),
+      frontmatter + rule.content + "\n",
+      "utf-8",
+    );
+  }
+}
+
+/** Run the full scaffold. Creates all config files idempotently. */
+export async function scaffoldConfig(
+  opts: ScaffoldOptions,
+): Promise<{ filesWritten: string[] }> {
+  const projectDir = opts.projectDir ?? process.cwd();
+  const platform = opts.platform ?? "claude";
+  const spaceName = opts.spaceName;
+  const spaceDefs = opts.spaceDefs;
+
+  const filesWritten: string[] = [];
+
+  await writePluginJson(projectDir);
+  filesWritten.push(".claude-plugin/plugin.json");
+
+  await writeMcpJson(projectDir, platform);
+  filesWritten.push(platform === "cursor" ? ".cursor/mcp.json" : ".mcp.json");
+
+  if (platform === "cursor") {
+    await writeCursorRules(projectDir);
+    filesWritten.push(".cursor/rules/llmkb/ (5 rule files)");
+  }
+
+  const llmkbFiles = await writeLlmkbDir(
+    projectDir,
+    spaceName,
+    spaceDefs,
+    opts.force,
+  );
+  for (const f of llmkbFiles) {
+    filesWritten.push(f);
+  }
+
+  if (opts.withHooks) {
+    const hookFiles = await writeHooks(projectDir, opts.force);
+    for (const f of hookFiles) {
+      filesWritten.push(f);
+    }
+  }
+
+  return { filesWritten };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@llmkb/claude-code",
+  "version": "0.1.0",
+  "description": "Claude Code plugin for llmkb — search, read, and write your knowledge base via MCP tools",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "llmkb": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "lib",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "tsx bin/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "cli-progress": "^3.12.0",
+    "commander": "^13.1.0",
+    "conf": "^13.1.0",
+    "ignore": "^7.0.3",
+    "keychain": "^1.5.0",
+    "picocolors": "^1.1.1",
+    "tus-js-client": "^4.3.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/cli-progress": "^3.11.6",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "llmkb",
+    "claude-code",
+    "mcp",
+    "knowledge-base",
+    "wiki"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}