openclew 0.2.0 → 0.3.0

package/lib/init.js

@@ -15,7 +15,7 @@ const readline = require("readline");
 const { detectInstructionFiles, findAgentsMdCaseInsensitive } = require("./detect");
 const { inject, isAlreadyInjected } = require("./inject");
 const { writeConfig } = require("./config");
-const { guideContent, exampleLivingDocContent, exampleLogContent, today } = require("./templates");
+const { guideContent, frameworkIntegrationContent, exampleRefdocContent, exampleLogContent, today } = require("./templates");
 
 const PROJECT_ROOT = process.cwd();
 const DOC_DIR = path.join(PROJECT_ROOT, "doc");
@@ -126,8 +126,8 @@ function installPreCommitHook() {
   }
 
   const preCommitPath = path.join(hooksDir, "pre-commit");
-  const indexScript = `if [ -f doc/generate-index.py ]; then
-  python3 doc/generate-index.py doc 2>/dev/null || echo "openclew: index generation failed"
+  const indexScript = `if command -v npx >/dev/null 2>&1; then
+  npx --yes openclew index 2>/dev/null || echo "openclew: index generation failed"
   git add doc/_INDEX.md 2>/dev/null
 fi`;
 
@@ -150,26 +150,37 @@ fi`;
   return true;
 }
 
-function copyGenerateIndex() {
-  const src = path.join(__dirname, "..", "hooks", "generate-index.py");
-  const dst = path.join(DOC_DIR, "generate-index.py");
+function updateGitignore() {
+  const gitignorePath = path.join(PROJECT_ROOT, ".gitignore");
+  const entry = "doc/log/";
 
-  if (fs.existsSync(dst)) {
-    console.log("  doc/generate-index.py already exists");
-    return false;
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, "utf-8");
+    if (content.includes(entry)) {
+      console.log("  .gitignore already ignores doc/log/");
+      return;
+    }
+    fs.appendFileSync(gitignorePath, `\n${entry}\n`, "utf-8");
+    console.log("  Added doc/log/ to .gitignore");
+  } else {
+    fs.writeFileSync(gitignorePath, `${entry}\n`, "utf-8");
+    console.log("  Created .gitignore with doc/log/");
   }
+}
 
-  if (fs.existsSync(src)) {
-    fs.copyFileSync(src, dst);
-    console.log("  Copied generate-index.py to doc/");
+function cleanupLegacyPython() {
+  // Remove legacy generate-index.py if present (replaced by JS-native index-gen)
+  const legacyScript = path.join(DOC_DIR, "generate-index.py");
+  if (fs.existsSync(legacyScript)) {
+    fs.unlinkSync(legacyScript);
+    console.log("  Removed legacy doc/generate-index.py (now JS-native)");
     return true;
   }
-
-  console.log("  generate-index.py not found in package — skipping");
+  console.log("  No legacy Python script to clean up");
   return false;
 }
 
-function createDocs() {
+function createDocs(entryPointPath) {
   // Guide — always created
   const guidePath = path.join(DOC_DIR, "_USING_OPENCLEW.md");
   if (!fs.existsSync(guidePath)) {
@@ -179,11 +190,30 @@ function createDocs() {
     console.log("  doc/_USING_OPENCLEW.md already exists");
   }
 
-  // Example living doc
+  // Framework integration guide
+  const frameworkPath = path.join(DOC_DIR, "_OPENCLEW_FRAMEWORK_INTEGRATION.md");
+  if (!fs.existsSync(frameworkPath)) {
+    fs.writeFileSync(frameworkPath, frameworkIntegrationContent(), "utf-8");
+    console.log("  Created doc/_OPENCLEW_FRAMEWORK_INTEGRATION.md (framework integration guide)");
+  } else {
+    console.log("  doc/_OPENCLEW_FRAMEWORK_INTEGRATION.md already exists");
+  }
+
+  // Architecture refdoc — seeded from existing instruction file if available
   const examplePath = path.join(DOC_DIR, "_ARCHITECTURE.md");
   if (!fs.existsSync(examplePath)) {
-    fs.writeFileSync(examplePath, exampleLivingDocContent(), "utf-8");
-    console.log("  Created doc/_ARCHITECTURE.md (example living doc)");
+    let existingInstructions = null;
+    if (entryPointPath && fs.existsSync(entryPointPath)) {
+      try {
+        existingInstructions = fs.readFileSync(entryPointPath, "utf-8");
+      } catch {}
+    }
+    fs.writeFileSync(examplePath, exampleRefdocContent(existingInstructions), "utf-8");
+    if (existingInstructions) {
+      console.log("  Created doc/_ARCHITECTURE.md (seeded from instruction file)");
+    } else {
+      console.log("  Created doc/_ARCHITECTURE.md (template)");
+    }
   } else {
     console.log("  doc/_ARCHITECTURE.md already exists");
   }
@@ -199,15 +229,14 @@ function createDocs() {
 }
 
 function runIndexGenerator() {
-  const indexScript = path.join(DOC_DIR, "generate-index.py");
-  if (!fs.existsSync(indexScript)) return;
+  if (!fs.existsSync(DOC_DIR)) return;
 
   try {
-    const { execSync } = require("child_process");
-    execSync(`python3 "${indexScript}" "${DOC_DIR}"`, { stdio: "pipe" });
-    console.log("  Generated doc/_INDEX.md");
-  } catch {
-    console.log("  Could not generate index (python3 not available)");
+    const { writeIndex } = require("./index-gen");
+    const { refdocs, logs } = writeIndex(DOC_DIR);
+    console.log(`  Generated doc/_INDEX.md (${refdocs} refdocs, ${logs} logs)`);
+  } catch (err) {
+    console.log(`  Could not generate index: ${err.message}`);
   }
 }
 
@@ -218,12 +247,16 @@ async function main() {
   console.log("1. Project structure");
   createDirs();
 
-  // Step 2: Copy index generator
-  console.log("\n2. Index generator");
-  copyGenerateIndex();
+  // Step 2: Gitignore
+  console.log("\n2. Gitignore");
+  updateGitignore();
+
+  // Step 3: Cleanup legacy Python (if upgrading from older version)
+  console.log("\n3. Index generator");
+  cleanupLegacyPython();
 
-  // Step 3: Entry point
-  console.log("\n3. Entry point");
+  // Step 4: Entry point
+  console.log("\n4. Entry point");
   const entryPoint = await resolveEntryPoint();
 
   if (entryPoint) {
@@ -241,20 +274,20 @@ async function main() {
     writeConfig({ entryPoint: null }, PROJECT_ROOT);
   }
 
-  // Step 4: Pre-commit hook
-  console.log("\n4. Pre-commit hook");
+  // Step 5: Pre-commit hook
+  console.log("\n5. Pre-commit hook");
   if (noHook) {
     console.log("  Skipping (--no-hook)");
   } else {
     installPreCommitHook();
   }
 
-  // Step 5: Docs
-  console.log("\n5. Docs");
-  createDocs();
+  // Step 6: Docs
+  console.log("\n6. Docs");
+  createDocs(entryPoint ? entryPoint.fullPath : null);
 
-  // Step 6: Generate index
-  console.log("\n6. Index");
+  // Step 7: Generate index
+  console.log("\n7. Index");
   runIndexGenerator();
 
   // Done

package/lib/inject.js

@@ -7,17 +7,26 @@ const fs = require("fs");
 const OPENCLEW_BLOCK = `
 ## Project knowledge (openclew)
 
-This file is the **entry point** for project documentation.
+This project uses \`doc/\` as its knowledge base. Before starting any task:
 
-**Doc-first rule:** before any task, read \`doc/_INDEX.md\` to find docs related to the task. Read them before exploring code.
+1. **Read \`doc/_INDEX.md\`** — it lists all available docs with a one-line summary each
+2. **Pick your reference doc(s)** — choose one or more docs relevant to what you're about to do
+3. **Read them** (L1 for relevance, L2 for context) — then start working
+4. **No matching doc?** — propose creating a refdoc with \`npx openclew new "Title"\` before starting
 
-Two types of docs in \`doc/\`:
-- **Living docs** (\`doc/_*.md\`) — evolve with the project (architecture, conventions, decisions)
-- **Logs** (\`doc/log/YYYY-MM-DD_*.md\`) — frozen facts from a session, never modified after
+If a doc contains placeholder comments (\`<!-- ... -->\`), fill them in based on what you observe in the code. This is expected — the docs are meant to be written by you.
 
-Each doc has 3 levels: **L1** (metadata — read first to decide relevance) → **L2** (summary) → **L3** (full details, only when needed).
+Two types of docs:
+- **Refdocs** (\`doc/_*.md\`) — architecture, conventions, decisions (evolve over time)
+- **Logs** (\`doc/log/YYYY-MM-DD_*.md\`) — frozen facts from past sessions
 
-**Creating docs:** when a decision, convention, or significant event needs to be captured, create the file directly following the format in \`doc/_USING_OPENCLEW.md\`.
+Each doc has 3 levels: **L1** (subject + brief — 1 line) → **L2** (summary) → **L3** (full details, only when needed).
+
+**Session commands** (user asks in chat, you run):
+- "checkout" → \`npx openclew checkout\` (end-of-session summary + log)
+- "new doc about X" → \`npx openclew new "X"\` (create refdoc)
+- "search X" → \`npx openclew search "X"\` (search docs)
+- "doc status" → \`npx openclew status\` (health dashboard)
 `.trim();
 
 const MARKER_START = "<!-- openclew_START -->";

package/lib/mcp-server.js

@@ -0,0 +1,313 @@
+/**
+ * openclew MCP server — Model Context Protocol over stdio.
+ *
+ * Exposes openclew docs as MCP tools so AI agents (Claude Code, Cursor, etc.)
+ * can search and read project documentation natively.
+ *
+ * Tools:
+ *   - search_docs(query)           Search docs by keyword (L1/metadata)
+ *   - read_doc(path, level?)       Read a doc at specified level (L1/L2/L3/full)
+ *   - list_docs(kind?)             List all docs with L1 metadata
+ *
+ * Protocol: MCP 2024-11-05 over stdio (JSON-RPC line-delimited)
+ * Zero dependencies — Node 16+ standard library only.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const { searchDocs, collectDocs, parseFile } = require("./search");
+
+const PROJECT_ROOT = process.cwd();
+const DOC_DIR = path.join(PROJECT_ROOT, "doc");
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+function ocVersion() {
+  try {
+    return require(path.join(__dirname, "..", "package.json")).version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function extractLevel(content, level) {
+  if (level === "full") return content;
+
+  const markers = {
+    L1: [/<!--\s*L1_START\s*-->/, /<!--\s*L1_END\s*-->/],
+    L2: [/<!--\s*L2_START\s*-->/, /<!--\s*L2_END\s*-->/],
+    L3: [/<!--\s*L3_START\s*-->/, /<!--\s*L3_END\s*-->/],
+  };
+
+  const key = level.toUpperCase();
+  if (!markers[key]) return content;
+
+  const [startRe, endRe] = markers[key];
+  const startMatch = content.match(startRe);
+  const endMatch = content.match(endRe);
+  if (!startMatch || !endMatch) return `No ${key} block found in this document.`;
+
+  const startIdx = startMatch.index + startMatch[0].length;
+  const endIdx = endMatch.index;
+  return content.slice(startIdx, endIdx).trim();
+}
+
+// ── MCP Tool implementations ────────────────────────────────────────
+
+function toolSearchDocs(params) {
+  const query = params.query;
+  if (!query) return { error: "Missing required parameter: query" };
+  if (!fs.existsSync(DOC_DIR)) return { error: "No doc/ directory found." };
+
+  const results = searchDocs(DOC_DIR, query);
+  return results.map((r) => ({
+    path: path.relative(PROJECT_ROOT, r.filepath),
+    kind: r.kind,
+    subject: r.meta.subject || r.filename,
+    doc_brief: r.meta.doc_brief || "",
+    status: r.meta.status || "",
+    category: r.meta.category || "",
+    score: r.score,
+  }));
+}
+
+function toolReadDoc(params) {
+  const docPath = params.path;
+  if (!docPath) return { error: "Missing required parameter: path" };
+
+  const absPath = path.resolve(PROJECT_ROOT, docPath);
+  // Security: ensure path is within project
+  if (!absPath.startsWith(PROJECT_ROOT)) return { error: "Path outside project." };
+  if (!fs.existsSync(absPath)) return { error: `File not found: ${docPath}` };
+
+  const content = fs.readFileSync(absPath, "utf-8");
+  const level = params.level || "L2";
+
+  return {
+    path: docPath,
+    level: level,
+    content: extractLevel(content, level),
+  };
+}
+
+function toolListDocs(params) {
+  if (!fs.existsSync(DOC_DIR)) return { error: "No doc/ directory found." };
+
+  const docs = collectDocs(DOC_DIR);
+  const kind = params.kind; // "refdoc", "log", or undefined (all)
+
+  return docs
+    .filter((d) => !kind || d.kind === kind)
+    .map((d) => ({
+      path: path.relative(PROJECT_ROOT, d.filepath),
+      kind: d.kind,
+      subject: d.meta.subject || d.filename,
+      doc_brief: d.meta.doc_brief || "",
+      status: d.meta.status || "",
+      category: d.meta.category || "",
+    }));
+}
+
+// ── MCP Protocol ────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: "search_docs",
+    description:
+      "Search project documentation by keyword. Searches subject, doc_brief, category, keywords, type, and status fields. Returns results sorted by relevance.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query (space-separated terms)",
+        },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "read_doc",
+    description:
+      "Read a project document at a specified level. L1 = subject + brief (~40 tokens). L2 = summary + key points. L3 = full technical details. full = entire file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Relative path to the document (e.g. doc/_ARCHITECTURE.md)",
+        },
+        level: {
+          type: "string",
+          enum: ["L1", "L2", "L3", "full"],
+          description: "Level of detail to return (default: L2)",
+        },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "list_docs",
+    description:
+      "List all project documents with their L1 metadata (subject, brief, status, category).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kind: {
+          type: "string",
+          enum: ["refdoc", "log"],
+          description: "Filter by document type. Omit to list all.",
+        },
+      },
+    },
+  },
+];
+
+const TOOL_HANDLERS = {
+  search_docs: toolSearchDocs,
+  read_doc: toolReadDoc,
+  list_docs: toolListDocs,
+};
+
+function handleMessage(msg) {
+  const { method, id, params } = msg;
+
+  switch (method) {
+    case "initialize":
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {} },
+          serverInfo: {
+            name: "openclew",
+            version: ocVersion(),
+          },
+        },
+      };
+
+    case "notifications/initialized":
+      return null; // No response for notifications
+
+    case "tools/list":
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: { tools: TOOLS },
+      };
+
+    case "tools/call": {
+      const toolName = params && params.name;
+      const handler = TOOL_HANDLERS[toolName];
+      if (!handler) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32601, message: `Unknown tool: ${toolName}` },
+        };
+      }
+
+      const toolArgs = params.arguments || {};
+      const result = handler(toolArgs);
+
+      // If result has an error field, return as tool error content
+      if (result && result.error) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: result.error }],
+            isError: true,
+          },
+        };
+      }
+
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          content: [
+            {
+              type: "text",
+              text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+            },
+          ],
+        },
+      };
+    }
+
+    default:
+      if (id !== undefined) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32601, message: `Method not found: ${method}` },
+        };
+      }
+      return null; // Ignore unknown notifications
+  }
+}
+
+// ── stdio transport ─────────────────────────────────────────────────
+
+function run() {
+  // Check if running as CLI help
+  const args = process.argv.slice(2);
+  const cmdIndex = args.indexOf("mcp");
+  const extraArgs = cmdIndex >= 0 ? args.slice(cmdIndex + 1) : args.slice(1);
+
+  if (extraArgs.includes("--help") || extraArgs.includes("-h")) {
+    console.log("openclew MCP server — Model Context Protocol over stdio");
+    console.log("");
+    console.log("Usage: openclew mcp");
+    console.log("");
+    console.log("Starts an MCP server on stdin/stdout for AI agent integration.");
+    console.log("Configure in your AI tool's MCP settings:");
+    console.log("");
+    console.log('  { "command": "npx", "args": ["openclew", "mcp"] }');
+    console.log("");
+    console.log("Tools exposed:");
+    console.log("  search_docs(query)       Search docs by keyword");
+    console.log("  read_doc(path, level?)   Read doc at L1/L2/L3/full");
+    console.log("  list_docs(kind?)         List all docs with L1 metadata");
+    process.exit(0);
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      const err = {
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32700, message: "Parse error" },
+      };
+      process.stdout.write(JSON.stringify(err) + "\n");
+      return;
+    }
+
+    const response = handleMessage(msg);
+    if (response) {
+      process.stdout.write(JSON.stringify(response) + "\n");
+    }
+  });
+
+  rl.on("close", () => process.exit(0));
+}
+
+// Export for tests
+module.exports = { handleMessage, extractLevel, TOOLS };
+
+// Run as CLI (invoked via dispatcher or directly)
+const calledAsMcp = process.argv.includes("mcp");
+if (require.main === module || calledAsMcp) {
+  run();
+}

package/lib/new-doc.js

@@ -1,20 +1,28 @@
 /**
- * openclew new <title> — create a new living doc.
+ * openclew new <title> — create a new refdoc.
  */
 
 const fs = require("fs");
 const path = require("path");
-const { livingContent, slugify } = require("./templates");
+const { refdocContent, slugify } = require("./templates");
 const { readConfig } = require("./config");
 
 const args = process.argv.slice(2);
-// Remove "new" command from args
-const cmdIndex = args.indexOf("new");
-const titleArgs = cmdIndex >= 0 ? args.slice(cmdIndex + 1) : args.slice(1);
+// Support both "add ref <title>" and legacy "new <title>"
+const refIndex = args.indexOf("ref");
+const newIndex = args.indexOf("new");
+let titleArgs;
+if (refIndex >= 0) {
+  titleArgs = args.slice(refIndex + 1);
+} else if (newIndex >= 0) {
+  titleArgs = args.slice(newIndex + 1);
+} else {
+  titleArgs = args.slice(1);
+}
 const title = titleArgs.join(" ");
 
 if (!title) {
-  console.error('Usage: openclew new "Title of the document"');
+  console.error('Usage: openclew add ref "Title of the document"');
   process.exit(1);
 }
 
@@ -37,7 +45,7 @@ if (fs.existsSync(filepath)) {
   process.exit(1);
 }
 
-fs.writeFileSync(filepath, livingContent(title), "utf-8");
+fs.writeFileSync(filepath, refdocContent(title), "utf-8");
 console.log(`Created doc/${filename}`);
 console.log("");
 console.log("Next: open the file and fill in:");

package/lib/new-log.js

@@ -8,13 +8,13 @@ const { logContent, slugifyLog, today } = require("./templates");
 const { readConfig } = require("./config");
 
 const args = process.argv.slice(2);
-// Remove "log" command from args
-const cmdIndex = args.indexOf("log");
-const titleArgs = cmdIndex >= 0 ? args.slice(cmdIndex + 1) : args.slice(1);
+// Support both "add log <title>" and legacy "log <title>"
+const logIndex = args.lastIndexOf("log");
+const titleArgs = logIndex >= 0 ? args.slice(logIndex + 1) : args.slice(1);
 const title = titleArgs.join(" ");
 
 if (!title) {
-  console.error('Usage: openclew log "Title of the log"');
+  console.error('Usage: openclew add log "Title of the log"');
   process.exit(1);
 }
 
@@ -42,7 +42,7 @@ fs.writeFileSync(filepath, logContent(title), "utf-8");
 console.log(`Created doc/log/${filename}`);
 console.log("");
 console.log("Next: open the file and fill in:");
-console.log("  L1 — type, status, short_story (what happened in 1-2 sentences)");
+console.log("  L1 — subject + doc_brief (what happened in 1-2 sentences)");
 console.log("  L2 — problem + solution (the facts, frozen after this session)");
 console.log("");
 console.log("Logs are immutable — once written, never modified.");