@overscore/cli 0.12.0 → 0.13.1

package/dist/index.js

@@ -3,11 +3,19 @@ import fs from "fs";
 import path from "path";
 import http from "http";
 import net from "net";
+import os from "os";
 import { execSync } from "child_process";
 import { createInterface } from "readline";
 import { createHash, randomBytes } from "crypto";
 import yauzl from "yauzl";
 // ── Shared helpers ──────────────────────────────────────────────────
+// Name CLI-minted API keys after the machine + date so stale keys are
+// recognizable and revocable in the Hub UI (mitigates key sprawl). Keys are
+// project-scoped; revoke unused ones under Project Settings → API Keys.
+function cliKeyName() {
+    const host = (os.hostname() || "unknown").split(".")[0];
+    return `cli ${host} ${new Date().toISOString().slice(0, 10)}`;
+}
 function parseEnv(content) {
     const env = {};
     for (const line of content.split("\n")) {
@@ -187,7 +195,7 @@ async function refreshApiKey(projectSlug) {
         const keyRes = await fetch(`${HUB_URL}/api/projects/${projectSlug}/api-keys`, {
             method: "POST",
             headers: { Authorization: `Bearer ${deviceToken}`, "Content-Type": "application/json" },
-            body: JSON.stringify({ name: `cli-${Date.now()}` }),
+            body: JSON.stringify({ name: cliKeyName() }),
         });
         if (keyRes.ok) {
             const data = (await keyRes.json());
@@ -239,27 +247,85 @@ const SECRET_FILE_EXTENSIONS = new Set([
     ".pfx",
     ".jks",
     ".keystore",
+    ".p8",
+    ".ppk",
+    ".gpg",
+    ".asc",
+    ".tfstate", // Terraform state — often contains plaintext secrets
+    ".tfvars",
+]);
+// Exact filenames that are secrets regardless of (or lacking) an extension.
+const SECRET_FILE_NAMES = new Set([
+    "service-account.json",
+    "service_account.json",
+    "serviceaccount.json",
+    "gcp-credentials.json",
+    "credentials.json",
+    "id_rsa",
+    "id_dsa",
+    "id_ecdsa",
+    "id_ed25519",
+    ".netrc",
+    ".pgpass",
+    ".htpasswd",
+    "secrets.json",
+    "secrets.yaml",
+    "secrets.yml",
 ]);
-function collectSourceFiles(dir, prefix) {
+function isSecretFileName(name) {
+    const lower = name.toLowerCase();
+    if (SECRET_FILE_NAMES.has(lower))
+        return true;
+    const ext = lower.substring(lower.lastIndexOf("."));
+    if (SECRET_FILE_EXTENSIONS.has(ext))
+        return true;
+    // Terraform state backups: terraform.tfstate.backup, *.tfstate.*
+    if (lower.includes(".tfstate"))
+        return true;
+    return false;
+}
+/**
+ * Walk a directory collecting deployable source files. Excludes machine-state
+ * and secrets, NEVER follows symlinks (a symlink could point at ~/.ssh/id_rsa
+ * or outside the project), and honors .overscoreignore at the project root.
+ */
+function collectSourceFiles(dir, prefix, ctx) {
+    // Initialize ignore context on the first (root) call.
+    const c = ctx ?? { patterns: loadOverscoreIgnore(dir), skipped: [] };
     const files = [];
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        // Never traverse or upload symlinks — they can escape the project tree
+        // or point at credentials. Skip silently-but-noted.
+        if (entry.isSymbolicLink()) {
+            c.skipped.push((prefix ? `${prefix}/` : "") + entry.name + " (symlink)");
+            continue;
+        }
         if (SOURCE_EXCLUDE.has(entry.name))
             continue;
         if (entry.name.startsWith(".env"))
             continue; // .env, .env.local, .env.production, etc.
         if (entry.name.endsWith(".log"))
             continue;
-        const ext = entry.name.substring(entry.name.lastIndexOf(".")).toLowerCase();
-        if (SECRET_FILE_EXTENSIONS.has(ext))
+        if (isSecretFileName(entry.name)) {
+            c.skipped.push((prefix ? `${prefix}/` : "") + entry.name + " (secret)");
             continue;
+        }
         const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (isIgnored(relativePath, entry.isDirectory(), c.patterns))
+            continue;
         if (entry.isDirectory()) {
-            files.push(...collectSourceFiles(path.join(dir, entry.name), relativePath));
+            files.push(...collectSourceFiles(path.join(dir, entry.name), relativePath, c));
         }
         else {
             files.push(relativePath);
         }
     }
+    // Surface what was withheld so a deploy is never silently lossy on secrets.
+    if (!ctx && c.skipped.length > 0) {
+        console.log(`  Skipped ${c.skipped.length} sensitive/symlinked file(s): ${c.skipped
+            .slice(0, 10)
+            .join(", ")}${c.skipped.length > 10 ? ", …" : ""}`);
+    }
     return files;
 }
 function extractZip(zipBuffer, targetDir) {
@@ -325,9 +391,16 @@ async function deploy() {
     }
     const builtFiles = collectFiles(distDir, "");
     console.log(`  Found ${builtFiles.length} built files.`);
-    // Collect source files
-    const sourceFiles = collectSourceFiles(process.cwd(), "");
-    console.log(`  Found ${sourceFiles.length} source files.`);
+    // Collect source files (skipped entirely with --no-source). Source is saved
+    // for versioning/restore; symlinks and secrets are always excluded.
+    const noSource = process.argv.includes("--no-source");
+    const sourceFiles = noSource ? [] : collectSourceFiles(process.cwd(), "");
+    if (noSource) {
+        console.log("  Skipping source upload (--no-source).");
+    }
+    else {
+        console.log(`  Found ${sourceFiles.length} source files.`);
+    }
     // Upload via deploy API
     console.log("  Uploading...");
     const formData = new FormData();
@@ -1063,7 +1136,7 @@ async function loadAnalysisConfig() {
                 Authorization: `Bearer ${deviceToken}`,
                 "Content-Type": "application/json",
             },
-            body: JSON.stringify({ name: `cli-${Date.now()}` }),
+            body: JSON.stringify({ name: cliKeyName() }),
         });
         if (keyGenRes.ok) {
             const data = (await keyGenRes.json());
@@ -1300,11 +1373,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 +1430,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 +1474,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 +1499,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 +1548,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 +2588,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.1",
   "description": "CLI for deploying Overscore dashboards and publishing analyses",
   "bin": {
     "overscore": "dist/index.js"