@overscore/cli 0.12.0 → 0.13.0

package/dist/index.js

@@ -1300,11 +1300,52 @@ function syncClaudeMdImports(targetDir) {
     fs.writeFileSync(claudeMdPath, updated);
     return true;
 }
+function platformMetaPath(targetDir) {
+    return path.join(targetDir, ".claude", ".platform-meta.json");
+}
+function readPlatformMeta(targetDir) {
+    const p = platformMetaPath(targetDir);
+    if (!fs.existsSync(p))
+        return { version: 1, last_synced: {} };
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, "utf-8"));
+        if (parsed?.version === 1 && parsed.last_synced)
+            return parsed;
+    }
+    catch {
+        // fall through
+    }
+    return { version: 1, last_synced: {} };
+}
+function writePlatformMeta(targetDir, meta) {
+    const p = platformMetaPath(targetDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(meta, null, 2) + "\n");
+}
+function md5(s) {
+    return createHash("md5").update(s).digest("hex");
+}
+function decidePlatformWrite(fullPath, serverContent, serverHash, lastSyncedHash, force) {
+    if (force)
+        return { action: "write", reason: "force" };
+    if (!fs.existsSync(fullPath))
+        return { action: "write", reason: "new" };
+    const localContent = fs.readFileSync(fullPath, "utf-8");
+    if (localContent === serverContent)
+        return { action: "skip", reason: "unchanged" };
+    const localHash = md5(localContent);
+    if (lastSyncedHash && localHash === lastSyncedHash) {
+        return { action: "write", reason: "clean-update" };
+    }
+    return { action: "skip", reason: "user-modified" };
+}
 /**
  * Fetch the latest platform-owned Claude Code rules from the Hub and write
  * them into the project's .claude/ directory. Called from `deploy` (before
  * uploading), `pull` (after extracting), and `syncHubManagedRules` (analysis
  * paths). User-owned files (knowledge/, this-dashboard.md) are NOT touched.
+ *
+ * Preserves user edits via .claude/.platform-meta.json hash tracking.
  */
 async function syncPlatformRules(targetDir, baseUrl, apiKey) {
     try {
@@ -1316,17 +1357,39 @@ async function syncPlatformRules(targetDir, baseUrl, apiKey) {
         const data = (await res.json());
         if (!data.files)
             return;
-        let count = 0;
+        const meta = readPlatformMeta(targetDir);
+        const written = [];
+        const preserved = [];
         for (const [relPath, content] of Object.entries(data.files)) {
             const fullPath = path.join(targetDir, ".claude", relPath);
-            fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-            fs.writeFileSync(fullPath, content);
-            count++;
+            const serverHash = data.hashes?.[relPath] ?? md5(content);
+            const lastSyncedHash = meta.last_synced[relPath] ?? null;
+            const decision = decidePlatformWrite(fullPath, content, serverHash, lastSyncedHash, false);
+            if (decision.action === "write") {
+                fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+                fs.writeFileSync(fullPath, content);
+                meta.last_synced[relPath] = serverHash;
+                written.push(relPath);
+            }
+            else if (decision.reason === "unchanged") {
+                // Bootstrap: record hash even if we didn't write, so future
+                // user-edits are detected against the right baseline.
+                meta.last_synced[relPath] = serverHash;
+            }
+            else {
+                preserved.push(relPath);
+            }
         }
+        writePlatformMeta(targetDir, meta);
         const claudeUpdated = syncClaudeMdImports(targetDir);
-        const total = count + (claudeUpdated ? 1 : 0);
-        if (total > 0) {
-            console.log(`  Platform rules synced (${count} files${claudeUpdated ? " + CLAUDE.md updated" : ""}).`);
+        if (written.length > 0 || claudeUpdated) {
+            console.log(`  Platform rules synced (${written.length} file${written.length === 1 ? "" : "s"}${claudeUpdated ? " + CLAUDE.md updated" : ""}).`);
+        }
+        if (preserved.length > 0) {
+            console.log(`  Preserved ${preserved.length} locally-modified file${preserved.length === 1 ? "" : "s"} (Hub updates skipped):`);
+            for (const f of preserved)
+                console.log(`    ${f}`);
+            console.log(`  To accept Hub updates and discard your local edits, run: npx @overscore/cli platform update --force`);
         }
     }
     catch {
@@ -1338,13 +1401,16 @@ async function syncPlatformRules(targetDir, baseUrl, apiKey) {
  * can tell the user what's new. Called by `npx @overscore/cli platform update`.
  *
  * With `--check`: read-only mode. Reports what *would* change without writing.
+ * With `--force`: discard local edits and accept the Hub version verbatim.
  */
-async function platformUpdate(checkOnly = false) {
+async function platformUpdate(checkOnly = false, force = false) {
     const { apiUrl, apiKey } = await loadEnv();
     const baseUrl = apiUrl.replace(/\/api$/, "");
     console.log(checkOnly
         ? "\n  Checking platform rules (no changes will be written)...\n"
-        : "\n  Syncing platform rules from Hub...\n");
+        : force
+            ? "\n  Syncing platform rules from Hub (--force: local edits will be overwritten)...\n"
+            : "\n  Syncing platform rules from Hub...\n");
     const capPath = path.resolve(process.cwd(), ".claude", "platform-capabilities.md");
     const prevContent = fs.existsSync(capPath) ? fs.readFileSync(capPath, "utf-8") : null;
     const prevVersion = prevContent?.match(/^version:\s*(.+)$/m)?.[1]?.trim() ?? null;
@@ -1360,18 +1426,34 @@ async function platformUpdate(checkOnly = false) {
         console.error("\n  Error: No files in platform-rules response.\n");
         process.exit(1);
     }
+    const meta = readPlatformMeta(process.cwd());
     const updated = [];
+    const preserved = [];
     for (const [relPath, content] of Object.entries(data.files)) {
         const fullPath = path.join(process.cwd(), ".claude", relPath);
-        const existing = fs.existsSync(fullPath) ? fs.readFileSync(fullPath, "utf-8") : null;
-        if (existing !== content) {
+        const serverHash = data.hashes?.[relPath] ?? md5(content);
+        const lastSyncedHash = meta.last_synced[relPath] ?? null;
+        const decision = decidePlatformWrite(fullPath, content, serverHash, lastSyncedHash, force);
+        if (decision.action === "write") {
             updated.push(relPath);
             if (!checkOnly) {
                 fs.mkdirSync(path.dirname(fullPath), { recursive: true });
                 fs.writeFileSync(fullPath, content);
+                meta.last_synced[relPath] = serverHash;
             }
         }
+        else if (decision.reason === "unchanged") {
+            // Bootstrap: in non-check mode, record hash so future user-edits
+            // are detected against the right baseline.
+            if (!checkOnly)
+                meta.last_synced[relPath] = serverHash;
+        }
+        else {
+            preserved.push(relPath);
+        }
     }
+    if (!checkOnly)
+        writePlatformMeta(process.cwd(), meta);
     // syncClaudeMdImports only makes sense if we're actually writing files.
     // In check mode, compute whether imports would be added by reading current state.
     let claudeWouldChange = false;
@@ -1393,14 +1475,26 @@ async function platformUpdate(checkOnly = false) {
         if (claudeUpdated)
             updated.push(".claude/CLAUDE.md (@imports updated)");
     }
-    if (updated.length === 0) {
+    if (updated.length === 0 && preserved.length === 0) {
         console.log("  Already up to date — no changes.\n");
         return;
     }
-    const verb = checkOnly ? "Would update" : "Updated";
-    console.log(`  ${verb} ${updated.length} file${updated.length === 1 ? "" : "s"}:\n`);
-    for (const f of updated)
-        console.log(`    ${f}`);
+    if (updated.length > 0) {
+        const verb = checkOnly ? "Would update" : "Updated";
+        console.log(`  ${verb} ${updated.length} file${updated.length === 1 ? "" : "s"}:\n`);
+        for (const f of updated)
+            console.log(`    ${f}`);
+    }
+    if (preserved.length > 0) {
+        if (updated.length > 0)
+            console.log();
+        const verb = checkOnly ? "Would preserve" : "Preserved";
+        console.log(`  ${verb} ${preserved.length} locally-modified file${preserved.length === 1 ? "" : "s"} (Hub updates skipped):\n`);
+        for (const f of preserved)
+            console.log(`    ${f}`);
+        console.log(`\n  To accept the Hub version and discard your local edits, re-run with --force:`);
+        console.log(`    npx @overscore/cli platform update --force`);
+    }
     if (updated.includes("platform-capabilities.md")) {
         const newContent = data.files["platform-capabilities.md"];
         const newVersion = newContent.match(/^version:\s*(.+)$/m)?.[1]?.trim() ?? "unknown";
@@ -2421,19 +2515,23 @@ else if (command === "analysis") {
 else if (command === "platform") {
     if (subcommand === "update") {
         const checkOnly = process.argv.includes("--check");
-        platformUpdate(checkOnly);
+        const force = process.argv.includes("--force");
+        platformUpdate(checkOnly, force);
     }
     else {
         console.log(`
   overscore platform — Manage platform rules and capabilities
 
   Commands:
-    update          Sync latest platform rules, skills, and capabilities from Hub
-    update --check  Show what would change without writing anything
+    update           Sync latest platform rules, skills, and capabilities from Hub
+                     (preserves locally-modified rule files via hash tracking)
+    update --check   Show what would change without writing anything
+    update --force   Overwrite locally-modified rule files with the Hub version
 
   Examples:
     npx @overscore/cli platform update
     npx @overscore/cli platform update --check
+    npx @overscore/cli platform update --force
 `);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overscore/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "CLI for deploying Overscore dashboards and publishing analyses",
   "bin": {
     "overscore": "dist/index.js"