@sdotwinter/openclaw-deterministic 0.7.0 → 0.9.0

package/bin/doctor.js

@@ -5,6 +5,9 @@ const path = require("path");
 
 const pkg = require("../package.json");
 
+const args = process.argv.slice(2);
+const JSON_MODE = args.includes("--json");
+
 const HOME = process.env.HOME;
 const openclawRoot = path.join(HOME, ".openclaw");
 const workspace = path.join(openclawRoot, "workspace");
@@ -34,27 +37,6 @@ function versionFromFile(content) {
   return match ? match[1] : null;
 }
 
-function checkVersion(filePath, label) {
-  if (!exists(filePath)) {
-    console.log(`❌ ${label} missing.`);
-    return;
-  }
-
-  const content = read(filePath);
-  const version = versionFromFile(content);
-
-  if (!version) {
-    console.log(`⚠ ${label} version stamp missing.`);
-    return;
-  }
-
-  if (version === pkg.version) {
-    console.log(`✅ ${label} version matches CLI (${version})`);
-  } else {
-    console.log(`⚠ ${label} version mismatch (installed ${version}, CLI ${pkg.version})`);
-  }
-}
-
 function overlayEnabled() {
   if (!exists(files.soul)) return false;
   const content = read(files.soul);
@@ -76,43 +58,129 @@ function estimateSemanticTokens() {
   return Math.ceil(content.length / 4);
 }
 
-console.log("\nRunning deterministic doctor...\n");
+function evaluateVersion(filePath) {
+  if (!exists(filePath)) {
+    return { status: "missing", version: null };
+  }
+
+  const content = read(filePath);
+  const version = versionFromFile(content);
+
+  if (!version) {
+    return { status: "no-stamp", version: null };
+  }
 
-if (!exists(openclawRoot)) {
-  console.log("❌ OpenClaw directory not found.");
-  process.exit(1);
+  if (version === pkg.version) {
+    return { status: "match", version };
+  }
+
+  return { status: "mismatch", version };
 }
 
-if (!exists(workspace)) {
-  console.log("❌ Workspace missing.");
-  process.exit(1);
+function evaluate() {
+  const result = {
+    cliVersion: pkg.version,
+    openclawDetected: exists(openclawRoot),
+    workspaceDetected: exists(workspace),
+    files: {},
+    overlayEnabled: false,
+    semanticTokens: 0,
+    semanticStatus: "safe",
+  };
+
+  if (!result.openclawDetected || !result.workspaceDetected) {
+    return result;
+  }
+
+  result.files.operating = evaluateVersion(files.operating);
+  result.files.detSoul = evaluateVersion(files.detSoul);
+  result.files.compactor = evaluateVersion(files.compactor);
+
+  result.overlayEnabled = overlayEnabled();
+
+  const tokens = estimateSemanticTokens();
+  result.semanticTokens = tokens;
+
+  if (tokens > 1200) {
+    result.semanticStatus = "hard-limit-exceeded";
+  } else if (tokens > 1020) {
+    result.semanticStatus = "risk-threshold";
+  } else {
+    result.semanticStatus = "safe";
+  }
+
+  return result;
 }
 
-checkVersion(files.operating, "OPERATING_RULES.md");
-checkVersion(files.detSoul, "SOUL.deterministic.md");
-checkVersion(files.compactor, "memory-compactor SKILL.md");
+function printHuman(result) {
+  console.log("\nRunning deterministic doctor...\n");
+
+  if (!result.openclawDetected) {
+    console.log("❌ OpenClaw directory not found.");
+    process.exit(1);
+  }
+
+  if (!result.workspaceDetected) {
+    console.log("❌ Workspace missing.");
+    process.exit(1);
+  }
+
+  for (const [name, info] of Object.entries(result.files)) {
+    const label =
+      name === "operating"
+        ? "OPERATING_RULES.md"
+        : name === "detSoul"
+        ? "SOUL.deterministic.md"
+        : "memory-compactor SKILL.md";
+
+    if (info.status === "missing") {
+      console.log(`❌ ${label} missing.`);
+    } else if (info.status === "no-stamp") {
+      console.log(`⚠ ${label} version stamp missing.`);
+    } else if (info.status === "mismatch") {
+      console.log(
+        `⚠ ${label} version mismatch (installed ${info.version}, CLI ${pkg.version})`
+      );
+    } else {
+      console.log(`✅ ${label} version matches CLI (${info.version})`);
+    }
+  }
 
-if (exists(files.soul)) {
   console.log("✅ SOUL.md present.");
-  if (overlayEnabled()) {
-    console.log("✅ Deterministic overlay ENABLED in SOUL.md.");
+  console.log(
+    result.overlayEnabled
+      ? "✅ Deterministic overlay ENABLED in SOUL.md."
+      : "⚠ Deterministic overlay NOT enabled in SOUL.md."
+  );
+
+  console.log(`\nSemantic memory tokens (est): ${result.semanticTokens}`);
+
+  if (result.semanticStatus === "hard-limit-exceeded") {
+    console.log("❌ Semantic memory exceeds HARD_LIMIT (1200).");
+  } else if (result.semanticStatus === "risk-threshold") {
+    console.log("⚠ Semantic memory above risk threshold (1020).");
   } else {
-    console.log("⚠ Deterministic overlay NOT enabled in SOUL.md.");
+    console.log("✅ Semantic memory within safe bounds.");
   }
-} else {
-  console.log("⚠ SOUL.md not found.");
+
+  console.log("\nDoctor complete.\n");
 }
 
-const semanticTokens = estimateSemanticTokens();
-console.log(`\nSemantic memory tokens (est): ${semanticTokens}`);
+const result = evaluate();
+
+if (JSON_MODE) {
+  console.log(JSON.stringify(result, null, 2));
+
+  if (!result.openclawDetected || !result.workspaceDetected) {
+    process.exit(2);
+  }
+
+  if (result.semanticStatus === "hard-limit-exceeded") {
+    process.exit(3);
+  }
 
-if (semanticTokens > 1200) {
-  console.log("❌ Semantic memory exceeds HARD_LIMIT (1200).");
-} else if (semanticTokens > 1020) {
-  console.log("⚠ Semantic memory above risk threshold (1020).");
-} else {
-  console.log("✅ Semantic memory within safe bounds.");
+  process.exit(0);
 }
 
-console.log("\nDoctor complete.\n");
+printHuman(result);
 process.exit(0);

package/bin/install.js

@@ -3,12 +3,15 @@
 const fs = require("fs");
 const path = require("path");
 
+const pkg = require("../package.json");
+
 const HOME = process.env.HOME;
 const openclawRoot = path.join(HOME, ".openclaw");
 const workspace = path.join(openclawRoot, "workspace");
 const backupsRoot = path.join(openclawRoot, "backups", "deterministic");
 
-const pkg = require("../package.json");
+const args = process.argv.slice(2);
+const DRY_RUN = args.includes("--dry-run");
 
 const tpl = (name) => path.join(__dirname, "..", "templates", name);
 
@@ -35,10 +38,16 @@ function exists(p) {
 }
 
 function ensureDir(p) {
-  fs.mkdirSync(p, { recursive: true });
+  if (!DRY_RUN) {
+    fs.mkdirSync(p, { recursive: true });
+  }
 }
 
 function writeFile(p, content) {
+  if (DRY_RUN) {
+    console.log(`[DRY-RUN] Would write: ${p}`);
+    return;
+  }
   ensureDir(path.dirname(p));
   fs.writeFileSync(p, content);
 }
@@ -47,6 +56,11 @@ function copyWithVersionStamp(templatePath, targetPath) {
   const versionStamp = `<!-- Installed by openclaw-deterministic v${pkg.version} -->\n`;
   const content = fs.readFileSync(templatePath, "utf8");
   const stamped = versionStamp + content;
+
+  if (DRY_RUN) {
+    console.log(`[DRY-RUN] Would install: ${targetPath}`);
+  }
+
   writeFile(targetPath, stamped);
 }
 
@@ -55,14 +69,21 @@ function timestamp() {
 }
 
 function backupSnapshot(pathsToBackup) {
+  if (DRY_RUN) {
+    console.log("[DRY-RUN] Would create backup snapshot.");
+    return null;
+  }
+
   ensureDir(backupsRoot);
   const snap = path.join(backupsRoot, timestamp());
   ensureDir(snap);
 
   for (const p of pathsToBackup) {
     if (!exists(p)) continue;
+
     const relative = path.relative(openclawRoot, p);
     const destination = path.join(snap, relative);
+
     ensureDir(path.dirname(destination));
     fs.copyFileSync(p, destination);
   }
@@ -71,23 +92,9 @@ function backupSnapshot(pathsToBackup) {
 }
 
 function installTemplates() {
-  copyWithVersionStamp(
-    tpl("OPERATING_RULES.md"),
-    target.operating
-  );
-  console.log("Installed: OPERATING_RULES.md");
-
-  copyWithVersionStamp(
-    tpl("SOUL.deterministic.md"),
-    target.detSoul
-  );
-  console.log("Installed: SOUL.deterministic.md");
-
-  copyWithVersionStamp(
-    tpl("memory-compactor.SKILL.md"),
-    target.compactor
-  );
-  console.log("Installed: skills/memory-compactor/SKILL.md");
+  copyWithVersionStamp(tpl("OPERATING_RULES.md"), target.operating);
+  copyWithVersionStamp(tpl("SOUL.deterministic.md"), target.detSoul);
+  copyWithVersionStamp(tpl("memory-compactor.SKILL.md"), target.compactor);
 }
 
 function bootstrapSoulIfMissing() {
@@ -97,33 +104,50 @@ function bootstrapSoulIfMissing() {
   }
 
   console.log("No SOUL.md detected — bootstrapping fresh SOUL.md with deterministic overlay.");
+
+  if (DRY_RUN) {
+    console.log("[DRY-RUN] Would create SOUL.md with deterministic overlay.");
+    return;
+  }
+
   writeFile(target.soul, OVERLAY_BLOCK.trim() + "\n");
   console.log("Created: SOUL.md (deterministic overlay enabled by default)");
 }
 
 if (!exists(openclawRoot)) {
   console.error("OpenClaw not found at ~/.openclaw");
-  console.error("Install OpenClaw first, then rerun oc-deterministic install.");
   process.exit(1);
 }
 
 if (!exists(workspace)) {
   console.error("OpenClaw workspace missing at ~/.openclaw/workspace");
-  console.error("OpenClaw may not be fully initialized. Run `openclaw onboard` then retry.");
   process.exit(1);
 }
 
-console.log("Creating deterministic backup snapshot...");
+if (DRY_RUN) {
+  console.log("\nRunning deterministic install (dry-run mode)...\n");
+} else {
+  console.log("Creating deterministic backup snapshot...");
+}
+
 const snap = backupSnapshot([
   target.operating,
   target.detSoul,
   target.soul,
   target.compactor,
 ]);
-console.log(`Backup location: ${snap}`);
+
+if (snap) {
+  console.log(`Backup location: ${snap}`);
+}
 
 installTemplates();
 bootstrapSoulIfMissing();
 
-console.log("\nDeterministic governance installed successfully.");
+if (DRY_RUN) {
+  console.log("\nDry-run complete. No changes were written.\n");
+} else {
+  console.log("\nDeterministic governance installed successfully.\n");
+}
+
 process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdotwinter/openclaw-deterministic",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Deterministic governance and memory compaction layer for OpenClaw",
   "keywords": [
     "openclaw",