openclew 0.0.1 → 0.2.0

package/lib/inject.js

@@ -0,0 +1,42 @@
+/**
+ * Inject openclew block into an existing instruction file.
+ */
+
+const fs = require("fs");
+
+const OPENCLEW_BLOCK = `
+## Project knowledge (openclew)
+
+This file is the **entry point** for project documentation.
+
+**Doc-first rule:** before any task, read \`doc/_INDEX.md\` to find docs related to the task. Read them before exploring code.
+
+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
+
+Each doc has 3 levels: **L1** (metadata — read first to decide relevance) → **L2** (summary) → **L3** (full details, only when needed).
+
+**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\`.
+`.trim();
+
+const MARKER_START = "<!-- openclew_START -->";
+const MARKER_END = "<!-- openclew_END -->";
+
+function isAlreadyInjected(filePath) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  return content.includes(MARKER_START);
+}
+
+function inject(filePath) {
+  if (isAlreadyInjected(filePath)) {
+    return false;
+  }
+
+  const content = fs.readFileSync(filePath, "utf-8");
+  const block = `\n\n${MARKER_START}\n${OPENCLEW_BLOCK}\n${MARKER_END}\n`;
+  fs.writeFileSync(filePath, content + block, "utf-8");
+  return true;
+}
+
+module.exports = { inject, isAlreadyInjected, OPENCLEW_BLOCK, MARKER_START };

package/lib/new-doc.js

@@ -0,0 +1,46 @@
+/**
+ * openclew new <title> — create a new living doc.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { livingContent, 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);
+const title = titleArgs.join(" ");
+
+if (!title) {
+  console.error('Usage: openclew new "Title of the document"');
+  process.exit(1);
+}
+
+const projectRoot = process.cwd();
+const docDir = path.join(projectRoot, "doc");
+if (!fs.existsSync(docDir)) {
+  console.error("No doc/ directory found. Run 'openclew init' first.");
+  process.exit(1);
+}
+if (!readConfig(projectRoot)) {
+  console.warn("Warning: no .openclew.json found. Run 'openclew init' first.");
+}
+
+const slug = slugify(title);
+const filename = `_${slug}.md`;
+const filepath = path.join(docDir, filename);
+
+if (fs.existsSync(filepath)) {
+  console.error(`File already exists: doc/${filename}`);
+  process.exit(1);
+}
+
+fs.writeFileSync(filepath, livingContent(title), "utf-8");
+console.log(`Created doc/${filename}`);
+console.log("");
+console.log("Next: open the file and fill in:");
+console.log("  L1 — subject, status, keywords (so the index can find it)");
+console.log("  L2 — objective + key points (what agents and humans need to know)");
+console.log("  L3 — full details (only when needed)");

package/lib/new-log.js

@@ -0,0 +1,48 @@
+/**
+ * openclew log <title> — create a new session log.
+ */
+
+const fs = require("fs");
+const path = require("path");
+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);
+const title = titleArgs.join(" ");
+
+if (!title) {
+  console.error('Usage: openclew log "Title of the log"');
+  process.exit(1);
+}
+
+const projectRoot = process.cwd();
+const logDir = path.join(projectRoot, "doc", "log");
+if (!fs.existsSync(logDir)) {
+  console.error("No doc/log/ directory found. Run 'openclew init' first.");
+  process.exit(1);
+}
+if (!readConfig(projectRoot)) {
+  console.warn("Warning: no .openclew.json found. Run 'openclew init' first.");
+}
+
+const slug = slugifyLog(title);
+const date = today();
+const filename = `${date}_${slug}.md`;
+const filepath = path.join(logDir, filename);
+
+if (fs.existsSync(filepath)) {
+  console.error(`File already exists: doc/log/${filename}`);
+  process.exit(1);
+}
+
+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("  L2 — problem + solution (the facts, frozen after this session)");
+console.log("");
+console.log("Logs are immutable — once written, never modified.");

package/lib/templates.js

@@ -0,0 +1,368 @@
+/**
+ * Template content for living docs and logs.
+ * Embedded here so the CLI works standalone without needing to locate template files.
+ */
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function slugify(title) {
+  return title
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, "_")
+    .replace(/^_|_$/g, "");
+}
+
+function slugifyLog(title) {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function livingContent(title) {
+  const date = today();
+  return `<!-- L1_START -->
+# L1 - Metadata
+type: Reference
+subject: ${title}
+created: ${date}
+updated: ${date}
+short_story:
+status: Active
+category:
+keywords: []
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this document exists -->
+
+## Key points
+<!-- 3-5 essential takeaways -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Full technical content -->
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| ${date} | Initial creation |
+<!-- L3_END -->
+`;
+}
+
+function logContent(title) {
+  const date = today();
+  return `<!-- L1_START -->
+# L1 - Metadata
+date: ${date}
+type: Feature
+subject: ${title}
+short_story:
+status: In progress
+category:
+keywords: []
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this work was undertaken -->
+
+## Problem
+<!-- What was observed -->
+
+## Solution
+<!-- How it was resolved -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Technical details, code changes, debugging steps... -->
+<!-- L3_END -->
+`;
+}
+
+/**
+ * Guide doc — always created by init.
+ * This is what agents read to understand openclew.
+ */
+function guideContent() {
+  const date = today();
+  return `<!-- L1_START -->
+# L1 - Metadata
+type: Guide
+subject: How openclew works
+created: ${date}
+updated: ${date}
+short_story: How openclew structures project knowledge in 3 levels (L1/L2/L3) so AI agents and humans navigate efficiently.
+status: Active
+category: Documentation
+keywords: [openclew, L1, L2, L3, index, living-doc, log]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## What is openclew?
+
+openclew gives your project a structured memory that both humans and AI agents can navigate efficiently.
+
+## Doc-first rule
+
+Before starting any task, read \`doc/_INDEX.md\` to find docs related to the task. Read them before exploring code. This avoids reinventing what's already documented.
+
+## Two types of docs
+
+**Living docs** (\`doc/_*.md\`): knowledge that evolves with the project.
+Architecture decisions, conventions, known pitfalls — anything that stays relevant over time.
+Naming: \`doc/_UPPER_SNAKE_CASE.md\` (e.g. \`doc/_AUTH_DESIGN.md\`)
+
+**Logs** (\`doc/log/YYYY-MM-DD_*.md\`): frozen facts from a work session.
+What happened, what was decided, what was tried. Never modified after the session.
+Naming: \`doc/log/YYYY-MM-DD_lowercase-slug.md\` (e.g. \`doc/log/2026-01-15_setup-auth.md\`)
+
+## Three levels per doc
+
+Every doc has 3 levels. Read only what you need:
+
+- **L1 — Metadata** (~40 tokens): subject, keywords, status. Read this first to decide if the doc is relevant.
+- **L2 — Summary**: the essential context — objective, key points, decisions.
+- **L3 — Details**: full technical content. Only read when deep-diving.
+
+## Index
+
+\`doc/_INDEX.md\` is auto-generated from L1 metadata on every git commit (via a pre-commit hook).
+Never edit it manually. To force a rebuild: \`openclew index\`
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+## Creating a living doc
+
+Create \`doc/_TITLE.md\` (uppercase snake_case) with this structure:
+
+\`\`\`
+<!-- L1_START -->
+# L1 - Metadata
+type: Reference
+subject: Title
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+short_story:
+status: Active
+category:
+keywords: []
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+## Objective
+## Key points
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+<!-- L3_END -->
+\`\`\`
+
+**When to create one:**
+- A decision was made that others need to know (architecture, convention, API design)
+- A pattern or pitfall keeps coming up
+- You want an agent to know something at the start of every session
+
+## Creating a log
+
+Create \`doc/log/YYYY-MM-DD_slug.md\` (lowercase, hyphens) with this structure:
+
+\`\`\`
+<!-- L1_START -->
+# L1 - Metadata
+date: YYYY-MM-DD
+type: Feature
+subject: Title
+short_story:
+status: In progress
+category:
+keywords: []
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+## Objective
+## Problem
+## Solution
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+<!-- L3_END -->
+\`\`\`
+
+**When to create one:**
+- End of a work session (what was done, what's left)
+- A bug was investigated and resolved
+- A spike or experiment was conducted
+
+Logs are immutable — once the session ends, the log is never modified.
+
+## How agents should use this
+
+1. At session start: read the entry point file
+2. Before any task: read \`doc/_INDEX.md\`, scan L1 metadata, identify relevant docs
+3. Read L2 of relevant docs for context
+4. Only read L3 when you need implementation details
+5. After significant work: create or update living docs and logs directly
+
+The index (\`doc/_INDEX.md\`) auto-regenerates on every git commit. To force a rebuild: \`openclew index\`
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| ${date} | Created by openclew init |
+<!-- L3_END -->
+`;
+}
+
+/**
+ * Example living doc — shows what a filled-in doc looks like.
+ */
+function exampleLivingDocContent() {
+  const date = today();
+  return `<!-- L1_START -->
+# L1 - Metadata
+type: Reference
+subject: Architecture overview
+created: ${date}
+updated: ${date}
+short_story: High-level architecture of the project — components, data flow, key decisions.
+status: Active
+category: Architecture
+keywords: [architecture, overview, components]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+Document the high-level architecture so new contributors and AI agents understand the system quickly.
+
+## Key points
+- Replace this with your actual architecture
+- Describe the main components and how they interact
+- Note key technical decisions and their rationale
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Replace this with your actual architecture details -->
+
+This is an example living doc created by \`openclew init\`.
+Edit it to document your project's architecture, or delete it and create your own.
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| ${date} | Created by openclew init (example) |
+<!-- L3_END -->
+`;
+}
+
+/**
+ * Example log — shows what a filled-in log looks like.
+ */
+function exampleLogContent() {
+  const date = today();
+  return `<!-- L1_START -->
+# L1 - Metadata
+date: ${date}
+type: Feature
+subject: Set up openclew
+short_story: Initialized openclew for structured project knowledge. Created doc/ structure, git hook, guide, and example docs.
+status: Done
+category: Tooling
+keywords: [openclew, setup, documentation]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+Set up structured documentation so AI agents and new contributors can navigate project knowledge efficiently.
+
+## Problem
+Project knowledge was scattered — README, inline comments, tribal knowledge. Each new AI session started from zero.
+
+## Solution
+Installed openclew. Every doc now has L1 (metadata for triage), L2 (summary for context), L3 (details when needed).
+The index auto-regenerates on each commit via a git hook.
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+This log was created by \`openclew init\`.
+It shows what a filled-in log looks like. Logs are immutable — once the session ends, the log is frozen.
+For evolving knowledge, use living docs (\`doc/_*.md\`).
+<!-- L3_END -->
+`;
+}
+
+module.exports = {
+  livingContent,
+  logContent,
+  guideContent,
+  exampleLivingDocContent,
+  exampleLogContent,
+  slugify,
+  slugifyLog,
+  today,
+};

package/package.json

@@ -1,10 +1,35 @@
 {
   "name": "openclew",
-  "version": "0.0.1",
-  "description": "Long Life Memory for LLMs",
+  "version": "0.2.0",
+  "description": "Long Life Memory for LLMs — structured project knowledge for AI agents and humans",
   "license": "MIT",
+  "bin": {
+    "openclew": "./bin/openclew.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "hooks/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "llm",
+    "documentation",
+    "knowledge",
+    "memory",
+    "claude",
+    "cursor",
+    "copilot",
+    "agents"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/openclew/openclew"
+  },
+  "engines": {
+    "node": ">=16"
   }
 }

package/templates/living.md

@@ -0,0 +1,45 @@
+<!-- L1_START -->
+# L1 - Metadata
+type: Reference | Architecture | Guide | Analysis
+subject: Short title (< 60 chars)
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+short_story: 1-2 sentences. What this doc covers and what it concludes. Must be enough to decide if you need to read further.
+status: Active | Stable | Archived
+category: Main domain (e.g. Auth, API, Database, UI...)
+keywords: [tag1, tag2, tag3]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this document exists, what need it covers -->
+
+## Key points
+<!-- 3-5 essential takeaways -->
+
+## Solution
+<!-- Recommended approach or pattern -->
+
+## Watch out
+<!-- Common pitfalls, edge cases, things to be aware of -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Full technical content: code examples, diagrams, references, deep dives... -->
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| YYYY-MM-DD | Initial creation |
+<!-- L3_END -->

package/templates/log.md

@@ -0,0 +1,36 @@
+<!-- L1_START -->
+# L1 - Metadata
+date: YYYY-MM-DD
+type: Bug | Feature | Refactor | Doc | Deploy
+subject: Short title (< 60 chars)
+short_story: 1-2 sentences. What happened and what was the outcome. Include conclusions, not just process.
+status: Done | In progress | Abandoned
+category: Main domain (e.g. Auth, API, Database, UI...)
+keywords: [tag1, tag2, tag3]
+<!-- L1_END -->
+
+---
+
+<!-- L2_START -->
+# L2 - Summary
+
+## Objective
+<!-- Why this work was undertaken -->
+
+## Problem
+<!-- What was observed, context of discovery -->
+
+## Solution
+<!-- How it was resolved -->
+
+## Watch out
+<!-- Side effects, edge cases, things to know -->
+<!-- L2_END -->
+
+---
+
+<!-- L3_START -->
+# L3 - Details
+
+<!-- Technical details: code changes, debugging steps, commands, references... -->
+<!-- L3_END -->