@sdotwinter/openclaw-deterministic 0.6.0 → 0.8.0

package/bin/doctor.js

@@ -3,25 +3,19 @@
 const fs = require("fs");
 const path = require("path");
 
+const pkg = require("../package.json");
+
 const HOME = process.env.HOME;
-const workspace = path.join(HOME, ".openclaw", "workspace");
+const openclawRoot = path.join(HOME, ".openclaw");
+const workspace = path.join(openclawRoot, "workspace");
 
-const paths = {
+const files = {
   operating: path.join(workspace, "OPERATING_RULES.md"),
-  soul: path.join(workspace, "SOUL.md"),
   detSoul: path.join(workspace, "SOUL.deterministic.md"),
+  soul: path.join(workspace, "SOUL.md"),
   compactor: path.join(workspace, "skills", "memory-compactor", "SKILL.md"),
-  semantic: path.join(workspace, "memory", "semantic", "openclaw.md"),
 };
 
-const MARKER_OVERLAY = "## Deterministic Governance Overlay";
-const MARKER_OPERATING_CANON = "Deterministic Execution Contract — Hardened Overlay";
-const MARKER_DETSOUL_CANON = "Deterministic Governance Overlay — Canonical";
-const MARKER_COMPACTOR_CANON = "## Hybrid Trigger Model";
-
-const HARD_LIMIT = 1200;
-const RISK_THRESHOLD = 1020;
-
 function exists(p) {
   try {
     fs.accessSync(p);
@@ -35,68 +29,89 @@ function read(p) {
   return fs.readFileSync(p, "utf8");
 }
 
-// cheap, consistent estimate (good enough for thresholds)
-function tokenEstimate(text) {
-  if (!text) return 0;
-  const words = text.trim().split(/\s+/).filter(Boolean).length;
-  return Math.ceil(words * 1.3);
+function versionFromFile(content) {
+  const match = content.match(/Installed by openclaw-deterministic v([0-9.]+)/);
+  return match ? match[1] : null;
 }
 
-function ok(msg) { console.log(`✅ ${msg}`); }
-function warn(msg) { console.log(`⚠ ${msg}`); }
-function fail(msg) { console.log(`❌ ${msg}`); }
+function checkVersion(filePath, label) {
+  if (!exists(filePath)) {
+    console.log(`❌ ${label} missing.`);
+    return;
+  }
 
-console.log("\nRunning deterministic doctor...\n");
+  const content = read(filePath);
+  const version = versionFromFile(content);
 
-// --- Presence checks
-exists(paths.operating) ? ok("OPERATING_RULES.md present.") : fail("OPERATING_RULES.md missing.");
-exists(paths.detSoul) ? ok("SOUL.deterministic.md present.") : fail("SOUL.deterministic.md missing.");
-exists(paths.compactor) ? ok("memory-compactor SKILL.md present.") : fail("memory-compactor SKILL.md missing.");
-exists(paths.soul) ? ok("SOUL.md present.") : fail("SOUL.md missing.");
+  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})`);
+  }
+}
 
-// If core files are missing, stop early (still exit cleanly)
-if (!exists(paths.operating) || !exists(paths.detSoul) || !exists(paths.compactor) || !exists(paths.soul)) {
-  console.log("\nDoctor complete (incomplete install).\n");
-  process.exit(0);
+function overlayEnabled() {
+  if (!exists(files.soul)) return false;
+  const content = read(files.soul);
+  return content.includes("SOUL.deterministic.md");
 }
 
-// --- Activation checks
-const soul = read(paths.soul);
-if (soul.includes(MARKER_OVERLAY)) ok("Deterministic overlay ENABLED in SOUL.md.");
-else warn("Deterministic overlay installed but NOT enabled (run: oc-deterministic enable).");
+function estimateSemanticTokens() {
+  const semanticPath = path.join(
+    openclawRoot,
+    "workspace",
+    "memory",
+    "semantic",
+    "openclaw.md"
+  );
 
-// --- Integrity checks (cross-file coherence)
-const operating = read(paths.operating);
-if (operating.includes(MARKER_OPERATING_CANON)) ok("OPERATING_RULES.md matches canonical marker.");
-else warn("OPERATING_RULES.md marker missing (file may be customized or outdated).");
+  if (!exists(semanticPath)) return 0;
 
-if (operating.includes("SOUL.deterministic.md")) ok("OPERATING_RULES.md references SOUL.deterministic.md.");
-else warn("OPERATING_RULES.md does not reference SOUL.deterministic.md (recommended).");
+  const content = read(semanticPath);
+  return Math.ceil(content.length / 4);
+}
 
-const detSoul = read(paths.detSoul);
-if (detSoul.includes(MARKER_DETSOUL_CANON)) ok("SOUL.deterministic.md matches canonical marker.");
-else warn("SOUL.deterministic.md marker missing (file may be customized or outdated).");
+console.log("\nRunning deterministic doctor...\n");
 
-const compactor = read(paths.compactor);
-if (compactor.includes(MARKER_COMPACTOR_CANON)) ok("memory-compactor includes Hybrid Trigger Model.");
-else warn("memory-compactor missing Hybrid Trigger Model marker (skill may be outdated).");
+if (!exists(openclawRoot)) {
+  console.log("❌ OpenClaw directory not found.");
+  process.exit(1);
+}
 
-// --- Semantic health
-if (exists(paths.semantic)) {
-  const semantic = read(paths.semantic);
-  const tokens = tokenEstimate(semantic);
+if (!exists(workspace)) {
+  console.log("❌ Workspace missing.");
+  process.exit(1);
+}
 
-  console.log(`\nSemantic memory tokens (est): ${tokens}`);
+checkVersion(files.operating, "OPERATING_RULES.md");
+checkVersion(files.detSoul, "SOUL.deterministic.md");
+checkVersion(files.compactor, "memory-compactor SKILL.md");
 
-  if (tokens > HARD_LIMIT) {
-    warn("ABOVE HARD LIMIT (Tier C enforced for semantic operations).");
-  } else if (tokens > RISK_THRESHOLD) {
-    warn("Near risk threshold (85%). Semantic appends should behave as Tier C per compactor rules.");
+if (exists(files.soul)) {
+  console.log("✅ SOUL.md present.");
+  if (overlayEnabled()) {
+    console.log("✅ Deterministic overlay ENABLED in SOUL.md.");
   } else {
-    ok("Semantic memory within safe bounds.");
+    console.log("⚠ Deterministic overlay NOT enabled in SOUL.md.");
   }
 } else {
-  console.log("\nℹ No semantic memory file detected (ok).");
+  console.log("⚠ SOUL.md not found.");
+}
+
+const semanticTokens = estimateSemanticTokens();
+console.log(`\nSemantic memory tokens (est): ${semanticTokens}`);
+
+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.");
 }
 
 console.log("\nDoctor complete.\n");

package/bin/install.js

@@ -3,11 +3,16 @@
 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 args = process.argv.slice(2);
+const DRY_RUN = args.includes("--dry-run");
+
 const tpl = (name) => path.join(__dirname, "..", "templates", name);
 
 const target = {
@@ -24,56 +29,72 @@ This system loads and adheres to SOUL.deterministic.md as a governing philosophi
 `;
 
 function exists(p) {
-  try { fs.accessSync(p); return true; } catch { return false; }
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 function ensureDir(p) {
-  fs.mkdirSync(p, { recursive: true });
-}
-
-function read(p) {
-  return fs.readFileSync(p, "utf8");
+  if (!DRY_RUN) {
+    fs.mkdirSync(p, { recursive: true });
+  }
 }
 
-function write(p, content) {
+function writeFile(p, content) {
+  if (DRY_RUN) {
+    console.log(`[DRY-RUN] Would write: ${p}`);
+    return;
+  }
   ensureDir(path.dirname(p));
   fs.writeFileSync(p, content);
 }
 
-function copyFile(src, dst) {
-  ensureDir(path.dirname(dst));
-  fs.copyFileSync(src, dst);
+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);
 }
 
-function stamp() {
-  return new Date().toISOString().replaceAll(":", "-");
+function timestamp() {
+  return new Date().toISOString().replace(/:/g, "-");
 }
 
 function backupSnapshot(pathsToBackup) {
+  if (DRY_RUN) {
+    console.log("[DRY-RUN] Would create backup snapshot.");
+    return null;
+  }
+
   ensureDir(backupsRoot);
-  const snap = path.join(backupsRoot, stamp());
+  const snap = path.join(backupsRoot, timestamp());
   ensureDir(snap);
 
   for (const p of pathsToBackup) {
     if (!exists(p)) continue;
-    const rel = path.relative(openclawRoot, p); // keep structure
-    const dst = path.join(snap, rel);
-    ensureDir(path.dirname(dst));
-    fs.copyFileSync(p, dst);
+
+    const relative = path.relative(openclawRoot, p);
+    const destination = path.join(snap, relative);
+
+    ensureDir(path.dirname(destination));
+    fs.copyFileSync(p, destination);
   }
 
   return snap;
 }
 
 function installTemplates() {
-  copyFile(tpl("OPERATING_RULES.md"), target.operating);
-  console.log("Installed: OPERATING_RULES.md");
-
-  copyFile(tpl("SOUL.deterministic.md"), target.detSoul);
-  console.log("Installed: SOUL.deterministic.md");
-
-  copyFile(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() {
@@ -83,28 +104,50 @@ function bootstrapSoulIfMissing() {
   }
 
   console.log("No SOUL.md detected — bootstrapping fresh SOUL.md with deterministic overlay.");
-  write(target.soul, OVERLAY_BLOCK.trim() + "\n");
+
+  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...");
-const snap = backupSnapshot([target.operating, target.detSoul, target.soul, target.compactor]);
-console.log(`Backup location: ${snap}`);
+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,
+]);
+
+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.6.0",
+  "version": "0.8.0",
   "description": "Deterministic governance and memory compaction layer for OpenClaw",
   "keywords": [
     "openclaw",