openclew 0.0.1 → 0.2.0

package/lib/checkout.js

@@ -0,0 +1,288 @@
+/**
+ * openclew checkout — end-of-session summary + log creation.
+ *
+ * 1. Collect git activity (today's commits, uncommitted changes)
+ * 2. Display summary table
+ * 3. Create a session log pre-filled with the activity
+ * 4. Regenerate the index
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const { logContent, slugifyLog, today } = require("./templates");
+const { readConfig } = require("./config");
+
+const PROJECT_ROOT = process.cwd();
+const DOC_DIR = path.join(PROJECT_ROOT, "doc");
+const LOG_DIR = path.join(DOC_DIR, "log");
+
+function run(cmd) {
+  try {
+    return execSync(cmd, { cwd: PROJECT_ROOT, encoding: "utf-8" }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function collectGitActivity() {
+  const date = today();
+
+  // Today's commits
+  const commitLog = run(
+    `git log --since="${date} 00:00" --format="%h %s" --no-merges`
+  );
+  const commits = commitLog
+    ? commitLog.split("\n").filter((l) => l.trim())
+    : [];
+
+  // Uncommitted changes
+  const status = run("git status --porcelain");
+  const uncommitted = status ? status.split("\n").filter((l) => l.trim()) : [];
+
+  // Files changed today (committed)
+  const changedFiles = run(
+    `git diff --name-only HEAD~${Math.max(commits.length, 1)}..HEAD 2>/dev/null`
+  );
+  const files = changedFiles
+    ? changedFiles.split("\n").filter((l) => l.trim())
+    : [];
+
+  // Today's logs already created
+  const existingLogs = fs.existsSync(LOG_DIR)
+    ? fs.readdirSync(LOG_DIR).filter((f) => f.startsWith(date))
+    : [];
+
+  // Living docs
+  const livingDocs = fs.existsSync(DOC_DIR)
+    ? fs.readdirSync(DOC_DIR).filter((f) => f.startsWith("_") && f !== "_INDEX.md" && f.endsWith(".md"))
+    : [];
+
+  return { date, commits, uncommitted, files, existingLogs, livingDocs };
+}
+
+function extractActions(commits) {
+  // Group commits by type (feat, fix, refactor, docs, etc.)
+  return commits.map((c) => {
+    const match = c.match(/^([a-f0-9]+)\s+(\w+)(?:\(([^)]*)\))?:\s*(.+)$/);
+    if (match) {
+      return {
+        hash: match[1],
+        type: match[2],
+        scope: match[3] || "",
+        desc: match[4],
+      };
+    }
+    // Non-conventional commit
+    const parts = c.match(/^([a-f0-9]+)\s+(.+)$/);
+    return {
+      hash: parts ? parts[1] : "",
+      type: "other",
+      scope: "",
+      desc: parts ? parts[2] : c,
+    };
+  });
+}
+
+function typeLabel(type) {
+  const labels = {
+    feat: "Feature",
+    fix: "Fix",
+    refactor: "Refactor",
+    docs: "Doc",
+    test: "Test",
+    build: "Build",
+    chore: "Chore",
+  };
+  return labels[type] || type.charAt(0).toUpperCase() + type.slice(1);
+}
+
+function displaySummary(activity) {
+  const { date, commits, uncommitted, existingLogs, livingDocs } = activity;
+  const actions = extractActions(commits);
+
+  console.log(`\nopenclew checkout — ${date}\n`);
+
+  if (actions.length === 0 && uncommitted.length === 0) {
+    console.log("  Nothing to report — no commits or changes today.");
+    console.log("");
+    return null;
+  }
+
+  // Summary table
+  if (actions.length > 0) {
+    console.log("  Commits today:");
+    console.log(
+      "  ┌─────┬──────────────────────────────────────────────┬─────┐"
+    );
+    console.log(
+      "  │ Sta │ Action                                       │ Com │"
+    );
+    console.log(
+      "  ├─────┼──────────────────────────────────────────────┼─────┤"
+    );
+    for (const a of actions) {
+      const label = `${typeLabel(a.type)} : ${a.desc}`;
+      const truncated = label.length > 44 ? label.slice(0, 43) + "…" : label;
+      const padded = truncated.padEnd(44);
+      console.log(`  │ ✅  │ ${padded} │ 🟢  │`);
+    }
+    console.log(
+      "  └─────┴──────────────────────────────────────────────┴─────┘"
+    );
+    console.log("");
+  }
+
+  if (uncommitted.length > 0) {
+    console.log(`  Uncommitted changes: ${uncommitted.length} file(s)`);
+    for (const line of uncommitted.slice(0, 10)) {
+      console.log(`    ${line}`);
+    }
+    if (uncommitted.length > 10) {
+      console.log(`    ... and ${uncommitted.length - 10} more`);
+    }
+    console.log("");
+  }
+
+  // Documentation status
+  if (existingLogs.length > 0) {
+    console.log(`  📗 Today's logs: ${existingLogs.join(", ")}`);
+  } else {
+    console.log("  📕 No log created today");
+  }
+  console.log("");
+
+  // Living docs reminder
+  if (livingDocs.length > 0) {
+    console.log("  📚 Living docs — check if any need updating:");
+    for (const doc of livingDocs) {
+      console.log(`     ${doc}`);
+    }
+    console.log("");
+  }
+
+  return actions;
+}
+
+function generateSessionLog(activity, actions) {
+  const { date } = activity;
+
+  // Build a descriptive title from actions
+  let sessionTitle;
+  if (actions.length === 1) {
+    sessionTitle = actions[0].desc;
+  } else if (actions.length > 1) {
+    const types = [...new Set(actions.map((a) => typeLabel(a.type)))];
+    sessionTitle = types.join(" + ") + " session";
+  } else {
+    sessionTitle = "Work session";
+  }
+
+  // Build pre-filled log content
+  const keywords = [
+    ...new Set(actions.map((a) => a.scope).filter(Boolean)),
+  ];
+  const keywordsStr =
+    keywords.length > 0 ? `[${keywords.join(", ")}]` : "[]";
+
+  const commitList = actions
+    .map((a) => `- ${typeLabel(a.type)}: ${a.desc} (${a.hash})`)
+    .join("\n");
+
+  const content = `<!-- L1_START -->
+# L1 - Metadata
+date: ${date}
+type: ${actions.length === 1 ? actions[0].type === "fix" ? "Bug" : "Feature" : "Feature"}
+subject: ${sessionTitle}
+short_story: ${actions.map((a) => a.desc).join(". ")}.
+status: Done
+category:
+keywords: ${keywordsStr}
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this work was undertaken -->
+
+## What was done
+${commitList}
+
+## Result
+<!-- Outcome — what works now that didn't before -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Technical details, code changes, debugging steps... -->
+<!-- L3_END -->
+`;
+
+  const slug = slugifyLog(sessionTitle);
+  const filename = `${date}_${slug}.md`;
+  const filepath = path.join(LOG_DIR, filename);
+
+  if (fs.existsSync(filepath)) {
+    console.log(`  Log already exists: doc/log/${filename}`);
+    return null;
+  }
+
+  if (!fs.existsSync(LOG_DIR)) {
+    console.log("  No doc/log/ directory. Run 'openclew init' first.");
+    return null;
+  }
+
+  fs.writeFileSync(filepath, content, "utf-8");
+  console.log(`  📝 Created doc/log/${filename}`);
+  console.log("     Pre-filled with today's commits. Edit to add context.");
+  return filename;
+}
+
+function regenerateIndex() {
+  const indexScript = path.join(DOC_DIR, "generate-index.py");
+  if (!fs.existsSync(indexScript)) return;
+
+  try {
+    execSync(`python3 "${indexScript}" "${DOC_DIR}"`, { stdio: "pipe" });
+    console.log("  📋 Regenerated doc/_INDEX.md");
+  } catch {
+    // Silent — index will be regenerated on next commit anyway
+  }
+}
+
+function main() {
+  if (!fs.existsSync(DOC_DIR)) {
+    console.error("No doc/ directory found. Run 'openclew init' first.");
+    process.exit(1);
+  }
+
+  if (!readConfig(PROJECT_ROOT)) {
+    console.warn("Warning: no .openclew.json found. Run 'openclew init' first.\n");
+  }
+
+  const activity = collectGitActivity();
+  const actions = displaySummary(activity);
+
+  if (!actions || actions.length === 0) {
+    return;
+  }
+
+  // Create session log
+  console.log("─── Log ───");
+  const created = generateSessionLog(activity, actions);
+
+  // Regenerate index
+  if (created) {
+    regenerateIndex();
+  }
+
+  console.log("");
+}
+
+main();

package/lib/config.js

@@ -0,0 +1,34 @@
+/**
+ * Read/write .openclew.json config at project root.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const CONFIG_FILE = ".openclew.json";
+
+function configPath(projectRoot) {
+  return path.join(projectRoot || process.cwd(), CONFIG_FILE);
+}
+
+function readConfig(projectRoot) {
+  const p = configPath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeConfig(config, projectRoot) {
+  const p = configPath(projectRoot);
+  fs.writeFileSync(p, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+function getEntryPoint(projectRoot) {
+  const config = readConfig(projectRoot);
+  return config && config.entryPoint ? config.entryPoint : null;
+}
+
+module.exports = { readConfig, writeConfig, getEntryPoint, CONFIG_FILE };

package/lib/detect.js

@@ -0,0 +1,74 @@
+/**
+ * Detect existing AI instruction files in the project root.
+ * Returns an array of { tool, file, fullPath, isDir } objects.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const INSTRUCTION_FILES = [
+  { tool: "Claude Code", file: "CLAUDE.md" },
+  { tool: "Cursor", file: ".cursorrules" },
+  { tool: "Cursor", file: ".cursor/rules" },
+  { tool: "GitHub Copilot", file: ".github/copilot-instructions.md" },
+  { tool: "Windsurf", file: ".windsurfrules" },
+  { tool: "Windsurf", file: ".windsurf/rules" },
+  { tool: "Cline", file: ".clinerules" },
+  { tool: "Codex / Gemini", file: "AGENTS.md" },
+  { tool: "Antigravity", file: ".antigravity/rules.md" },
+  { tool: "Gemini CLI", file: ".gemini/GEMINI.md" },
+  { tool: "Aider", file: "CONVENTIONS.md" },
+];
+
+/**
+ * Find AGENTS.md case-insensitively in projectRoot.
+ * Returns the actual filename (e.g. "agents.md", "Agents.md") or null.
+ */
+function findAgentsMdCaseInsensitive(projectRoot) {
+  try {
+    const entries = fs.readdirSync(projectRoot);
+    const match = entries.find(
+      (e) => e.toLowerCase() === "agents.md" && fs.statSync(path.join(projectRoot, e)).isFile()
+    );
+    return match || null;
+  } catch {
+    return null;
+  }
+}
+
+function detectInstructionFiles(projectRoot) {
+  const found = [];
+  const seenLower = new Set();
+
+  for (const entry of INSTRUCTION_FILES) {
+    // Skip AGENTS.md in the static list — handled by case-insensitive scan
+    if (entry.file.toLowerCase() === "agents.md") continue;
+
+    const fullPath = path.join(projectRoot, entry.file);
+    if (fs.existsSync(fullPath)) {
+      const stat = fs.statSync(fullPath);
+      found.push({
+        tool: entry.tool,
+        file: entry.file,
+        fullPath,
+        isDir: stat.isDirectory(),
+      });
+      seenLower.add(entry.file.toLowerCase());
+    }
+  }
+
+  // Case-insensitive AGENTS.md detection
+  const agentsFile = findAgentsMdCaseInsensitive(projectRoot);
+  if (agentsFile && !seenLower.has(agentsFile.toLowerCase())) {
+    found.push({
+      tool: "Codex / Gemini",
+      file: agentsFile,
+      fullPath: path.join(projectRoot, agentsFile),
+      isDir: false,
+    });
+  }
+
+  return found;
+}
+
+module.exports = { detectInstructionFiles, findAgentsMdCaseInsensitive, INSTRUCTION_FILES };

package/lib/index-gen.js

@@ -0,0 +1,40 @@
+/**
+ * openclew index — regenerate doc/_INDEX.md
+ *
+ * Wraps hooks/generate-index.py. Falls back to a JS implementation
+ * if Python is not available.
+ */
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const docDir = path.join(process.cwd(), "doc");
+
+if (!fs.existsSync(docDir)) {
+  console.error("No doc/ directory found. Run 'openclew init' first.");
+  process.exit(1);
+}
+
+// Try local generate-index.py first
+const localScript = path.join(docDir, "generate-index.py");
+const packageScript = path.join(__dirname, "..", "hooks", "generate-index.py");
+const script = fs.existsSync(localScript) ? localScript : packageScript;
+
+if (fs.existsSync(script)) {
+  try {
+    const output = execSync(`python3 "${script}" "${docDir}"`, {
+      encoding: "utf-8",
+    });
+    console.log(output.trim());
+    process.exit(0);
+  } catch {
+    console.error(
+      "python3 not available. Install Python 3.8+ or regenerate manually."
+    );
+    process.exit(1);
+  }
+}
+
+console.error("generate-index.py not found. Run 'openclew init' first.");
+process.exit(1);

package/lib/init.js

@@ -0,0 +1,273 @@
+/**
+ * openclew init — set up openclew in the current project.
+ *
+ * 1. Create doc/ and doc/log/
+ * 2. Detect entry point (AGENTS.md case-insensitive by default)
+ * 3. Inject openclew block into entry point
+ * 4. Install pre-commit hook for index generation
+ * 5. Create guide + example docs
+ * 6. Generate initial _INDEX.md
+ */
+
+const fs = require("fs");
+const path = require("path");
+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 PROJECT_ROOT = process.cwd();
+const DOC_DIR = path.join(PROJECT_ROOT, "doc");
+const LOG_DIR = path.join(DOC_DIR, "log");
+const GIT_DIR = path.join(PROJECT_ROOT, ".git");
+
+const args = process.argv.slice(2);
+const noHook = args.includes("--no-hook");
+const noInject = args.includes("--no-inject");
+
+function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function createDirs() {
+  if (!fs.existsSync(DOC_DIR)) {
+    fs.mkdirSync(DOC_DIR, { recursive: true });
+    console.log("  Created doc/");
+  } else {
+    console.log("  doc/ already exists");
+  }
+
+  if (!fs.existsSync(LOG_DIR)) {
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+    console.log("  Created doc/log/");
+  } else {
+    console.log("  doc/log/ already exists");
+  }
+}
+
+/**
+ * Resolve the entry point file.
+ *
+ * Priority:
+ * 1. AGENTS.md (case-insensitive) — default, universal
+ * 2. Other detected instruction files — user picks one
+ * 3. Create AGENTS.md — if nothing exists
+ */
+async function resolveEntryPoint() {
+  if (noInject) {
+    console.log("  Skipping entry point setup (--no-inject)");
+    return null;
+  }
+
+  // 1. Check for AGENTS.md (case-insensitive)
+  const agentsFile = findAgentsMdCaseInsensitive(PROJECT_ROOT);
+  if (agentsFile) {
+    if (!process.stdin.isTTY) {
+      // Non-interactive: accept AGENTS.md by default
+      console.log(`  Using ${agentsFile} (non-interactive)`);
+      return { file: agentsFile, fullPath: path.join(PROJECT_ROOT, agentsFile), created: false };
+    }
+    const answer = await ask(`  Found ${agentsFile} — use as entry point? [Y/n] `);
+    if (answer === "" || answer.toLowerCase() === "y" || answer.toLowerCase() === "yes") {
+      return { file: agentsFile, fullPath: path.join(PROJECT_ROOT, agentsFile), created: false };
+    }
+  }
+
+  // 2. Detect other instruction files
+  const others = detectInstructionFiles(PROJECT_ROOT).filter(
+    (f) => !f.isDir && f.file.toLowerCase() !== "agents.md"
+  );
+
+  if (others.length > 0) {
+    console.log("  Detected instruction files:");
+    others.forEach((f, i) => console.log(`    ${i + 1}. ${f.file} (${f.tool})`));
+    console.log(`    ${others.length + 1}. Create new AGENTS.md`);
+
+    if (!process.stdin.isTTY) {
+      // Non-interactive: default to first detected file
+      console.log(`  Using ${others[0].file} (non-interactive)`);
+      return { file: others[0].file, fullPath: others[0].fullPath, created: false };
+    }
+
+    const choice = await ask(`  Choose entry point [1-${others.length + 1}]: `);
+    const idx = parseInt(choice, 10) - 1;
+
+    if (idx >= 0 && idx < others.length) {
+      return { file: others[idx].file, fullPath: others[idx].fullPath, created: false };
+    }
+  }
+
+  // 3. Create AGENTS.md
+  const agentsPath = path.join(PROJECT_ROOT, "AGENTS.md");
+  fs.writeFileSync(agentsPath, `# ${path.basename(PROJECT_ROOT)}\n\nProject instructions for AI agents.\n`, "utf-8");
+  console.log("  Created AGENTS.md");
+  return { file: "AGENTS.md", fullPath: agentsPath, created: true };
+}
+
+function installPreCommitHook() {
+  if (!fs.existsSync(GIT_DIR)) {
+    console.log("  No .git/ found — skipping hook installation");
+    return false;
+  }
+
+  const hooksDir = path.join(GIT_DIR, "hooks");
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+  }
+
+  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"
+  git add doc/_INDEX.md 2>/dev/null
+fi`;
+
+  const MARKER = "# openclew-index";
+
+  if (fs.existsSync(preCommitPath)) {
+    const existing = fs.readFileSync(preCommitPath, "utf-8");
+    if (existing.includes(MARKER)) {
+      console.log("  Pre-commit hook already contains openclew index generation");
+      return false;
+    }
+    fs.appendFileSync(preCommitPath, `\n\n${MARKER}\n${indexScript}\n`, "utf-8");
+    console.log("  Appended openclew index generation to existing pre-commit hook");
+  } else {
+    fs.writeFileSync(preCommitPath, `#!/bin/sh\n\n${MARKER}\n${indexScript}\n`, "utf-8");
+    fs.chmodSync(preCommitPath, "755");
+    console.log("  Created pre-commit hook for index generation");
+  }
+
+  return true;
+}
+
+function copyGenerateIndex() {
+  const src = path.join(__dirname, "..", "hooks", "generate-index.py");
+  const dst = path.join(DOC_DIR, "generate-index.py");
+
+  if (fs.existsSync(dst)) {
+    console.log("  doc/generate-index.py already exists");
+    return false;
+  }
+
+  if (fs.existsSync(src)) {
+    fs.copyFileSync(src, dst);
+    console.log("  Copied generate-index.py to doc/");
+    return true;
+  }
+
+  console.log("  generate-index.py not found in package — skipping");
+  return false;
+}
+
+function createDocs() {
+  // Guide — always created
+  const guidePath = path.join(DOC_DIR, "_USING_OPENCLEW.md");
+  if (!fs.existsSync(guidePath)) {
+    fs.writeFileSync(guidePath, guideContent(), "utf-8");
+    console.log("  Created doc/_USING_OPENCLEW.md (guide)");
+  } else {
+    console.log("  doc/_USING_OPENCLEW.md already exists");
+  }
+
+  // Example living doc
+  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)");
+  } else {
+    console.log("  doc/_ARCHITECTURE.md already exists");
+  }
+
+  // Example log
+  const logPath = path.join(LOG_DIR, `${today()}_setup-openclew.md`);
+  if (!fs.existsSync(logPath)) {
+    fs.writeFileSync(logPath, exampleLogContent(), "utf-8");
+    console.log(`  Created doc/log/${today()}_setup-openclew.md (example log)`);
+  } else {
+    console.log(`  doc/log/${today()}_setup-openclew.md already exists`);
+  }
+}
+
+function runIndexGenerator() {
+  const indexScript = path.join(DOC_DIR, "generate-index.py");
+  if (!fs.existsSync(indexScript)) 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)");
+  }
+}
+
+async function main() {
+  console.log("\nopenclew init\n");
+
+  // Step 1: Create directories
+  console.log("1. Project structure");
+  createDirs();
+
+  // Step 2: Copy index generator
+  console.log("\n2. Index generator");
+  copyGenerateIndex();
+
+  // Step 3: Entry point
+  console.log("\n3. Entry point");
+  const entryPoint = await resolveEntryPoint();
+
+  if (entryPoint) {
+    if (isAlreadyInjected(entryPoint.fullPath)) {
+      console.log(`  ${entryPoint.file} already has openclew block`);
+    } else {
+      inject(entryPoint.fullPath);
+      console.log(`  Injected openclew block into ${entryPoint.file}`);
+    }
+
+    writeConfig({ entryPoint: entryPoint.file }, PROJECT_ROOT);
+    console.log(`  Saved entry point → .openclew.json`);
+  } else {
+    // --no-inject: still create config to mark init was done
+    writeConfig({ entryPoint: null }, PROJECT_ROOT);
+  }
+
+  // Step 4: Pre-commit hook
+  console.log("\n4. Pre-commit hook");
+  if (noHook) {
+    console.log("  Skipping (--no-hook)");
+  } else {
+    installPreCommitHook();
+  }
+
+  // Step 5: Docs
+  console.log("\n5. Docs");
+  createDocs();
+
+  // Step 6: Generate index
+  console.log("\n6. Index");
+  runIndexGenerator();
+
+  // Done
+  console.log("\n─── Ready ───\n");
+  if (entryPoint) {
+    console.log(`  Entry point: ${entryPoint.file}`);
+  }
+  console.log("  Guide:       doc/_USING_OPENCLEW.md");
+  console.log("");
+  console.log("  Start a session with your agent now.");
+  console.log('  Ask it: "Read doc/_USING_OPENCLEW.md and document our architecture."');
+  console.log("  That's it — openclew works from here.");
+  console.log("");
+}
+
+main();