openclew 0.4.0 → 0.5.0

package/UPGRADING.md

@@ -133,6 +133,20 @@ openclew migrate            # should show "0 to migrate"
 
 ## Version-specific notes
 
+### → 0.5.0 (init guard + global config)
+
+`init` now creates `~/.openclew/config.json` on every run. If you are not inside
+a project directory (no `.git`, `package.json`, etc.), init stops after creating
+the global config — it no longer creates `doc/` or `AGENTS.md` in random
+directories.
+
+New command: `openclew peek` — displays the doc index.
+
+New: `scripts/qa.py` — QA checklist in box-drawing format (dev only, not
+published to npm).
+
+License changed from MIT to Apache 2.0.
+
 ### → 0.4.0 (format migration)
 
 First migration release. Converts from the legacy format (YAML frontmatter,

package/bin/openclew.js

@@ -34,6 +34,7 @@ Usage:
 Advanced:
   openclew status                  Documentation health dashboard
   openclew index                   Regenerate doc/_INDEX.md
+  openclew session-header          Format session header line
   openclew mcp                     Start MCP server (stdio JSON-RPC)
 
 Options (init):
@@ -72,6 +73,7 @@ const commands = {
   peek: () => require("../lib/peek"),
   status: () => require("../lib/status"),
   index: () => require("../lib/index-gen"),
+  "session-header": () => require("../lib/session-header"),
   mcp: () => require("../lib/mcp-server"),
 };
 

package/lib/init.js

@@ -1,26 +1,67 @@
 /**
  * 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
+ * 0. Create ~/.openclew/ (global config)
+ * 1. Detect if we're in a project (project markers)
+ *    - If not: stop after global config
+ *    - If yes: proceed with project init
+ * 2. Create doc/ and doc/log/
+ * 3. Detect entry point (AGENTS.md case-insensitive by default)
+ * 4. Inject openclew block into entry point
+ * 5. Install pre-commit hook for index generation
+ * 6. Create guide + example docs
+ * 7. Generate initial _INDEX.md
  */
 
 const fs = require("fs");
 const path = require("path");
+const os = require("os");
 const readline = require("readline");
 const { detectInstructionFiles, findAgentsMdCaseInsensitive } = require("./detect");
 const { inject, isAlreadyInjected } = require("./inject");
 const { writeConfig } = require("./config");
-const { guideContent, frameworkIntegrationContent, exampleRefdocContent, exampleLogContent, today } = require("./templates");
+const { guideContent, frameworkIntegrationContent, exampleRefdocContent, exampleLogContent, today, ocVersion } = 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 OPENCLEW_HOME = path.join(os.homedir(), ".openclew");
+
+const PROJECT_MARKERS = [".git", "package.json", "Cargo.toml", "pyproject.toml", "go.mod", "Gemfile", "composer.json", "Makefile", "pom.xml", "build.gradle", "CMakeLists.txt", "setup.py", "setup.cfg"];
+
+function isProjectDir() {
+  return PROJECT_MARKERS.some((m) => fs.existsSync(path.join(PROJECT_ROOT, m)));
+}
+
+function ensureGlobalDir() {
+  const created = !fs.existsSync(OPENCLEW_HOME);
+  if (created) {
+    fs.mkdirSync(OPENCLEW_HOME, { recursive: true });
+  }
+
+  const configPath = path.join(OPENCLEW_HOME, "config.json");
+  if (!fs.existsSync(configPath)) {
+    fs.writeFileSync(
+      configPath,
+      JSON.stringify({ version: ocVersion(), installedAt: today() }, null, 2) + "\n",
+      "utf-8"
+    );
+  } else {
+    // Update version on each init
+    try {
+      const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+      cfg.version = ocVersion();
+      fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+    } catch {}
+  }
+
+  if (created) {
+    console.log("  Created ~/.openclew/");
+  } else {
+    console.log("  ~/.openclew/ already exists");
+  }
+}
 
 const args = process.argv.slice(2);
 const noHook = args.includes("--no-hook");
@@ -295,8 +336,20 @@ function installSlashCommands() {
 async function main() {
   console.log("\nopenclew init\n");
 
+  // Step 0: Global config (~/.openclew/)
+  console.log("0. Global config");
+  ensureGlobalDir();
+
+  // Check if we're in a project
+  if (!isProjectDir()) {
+    console.log(`\n─── Done ───\n`);
+    console.log(`  openclew installed → ~/.openclew/`);
+    console.log("");
+    return;
+  }
+
   // Step 1: Create directories
-  console.log("1. Project structure");
+  console.log("\n1. Project structure");
   createDirs();
 
   // Step 2: Gitignore

package/lib/session-header.js

@@ -0,0 +1,60 @@
+/**
+ * openclew session-header — format a session header line.
+ *
+ * Usage:
+ *   openclew session-header --name "Refonte checkout" --tags voice,stt,voxtral
+ *   openclew session-header --name "Fix streaming" --tags streaming --date 2026-03-27
+ *
+ * Output:
+ *   📅 2026-03-28 🏷️  Refonte checkout -----  #voice #stt #voxtral
+ */
+
+const { today } = require("./templates");
+
+function formatSessionHeader(name, tags, date) {
+  if (!name) {
+    console.error("Error: --name is required");
+    console.error(
+      'Usage: openclew session-header --name "Session title" --tags tag1,tag2'
+    );
+    process.exit(1);
+  }
+
+  const d = date || today();
+  const hashTags = tags.length > 0 ? tags.map((t) => `#${t}`).join(" ") : "";
+  const line = `📅 ${d} 🏷️  ${name} -----  ${hashTags}`.trimEnd();
+
+  console.log(line);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  let name = "";
+  let tags = [];
+  let date = "";
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--name" && args[i + 1]) {
+      name = args[++i];
+    } else if (args[i] === "--tags" && args[i + 1]) {
+      tags = args[++i].split(",").map((t) => t.trim()).filter(Boolean);
+    } else if (args[i] === "--date" && args[i + 1]) {
+      date = args[++i];
+    }
+  }
+
+  formatSessionHeader(name, tags, date);
+}
+
+module.exports = { formatSessionHeader };
+
+if (require.main === module) {
+  main();
+} else {
+  // Called via require from bin/openclew.js — run main
+  const callerIsOpenclew =
+    process.argv[1] && process.argv[1].includes("openclew");
+  if (callerIsOpenclew) {
+    main();
+  }
+}

package/lib/templates.js

@@ -541,4 +541,5 @@ module.exports = {
   slugify,
   slugifyLog,
   today,
+  ocVersion,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclew",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Long Life Memory for LLMs — structured project knowledge for AI agents and humans",
   "license": "Apache-2.0",
   "bin": {