@overscore/cli 0.13.20 → 0.13.21

package/dist/index.js

@@ -911,9 +911,125 @@ function formatCell(value) {
         return value.toLocaleString();
     return String(value);
 }
+// ── Pull safety: manifest + local-edit detection + backup ───────────────
+// Each pull records a manifest of the files it wrote, so a re-pull can tell whether
+// the folder has un-pulled local edits before it overwrites them. Without this,
+// `pull --force` silently destroys work that isn't in the Hub yet.
+const PULL_MANIFEST = ".overscore-pull.json";
+// Files we never track/hash: dependencies, secrets, VCS metadata, and the manifest itself.
+function isTrackedPullEntry(rel) {
+    const top = rel.split(path.sep)[0];
+    if (top === "node_modules" || top === ".git")
+        return false;
+    if (top.startsWith(".env"))
+        return false;
+    if (rel === PULL_MANIFEST)
+        return false;
+    return true;
+}
+function listPulledFiles(dir) {
+    const out = [];
+    const walk = (abs, rel) => {
+        for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+            const childRel = rel ? path.join(rel, entry.name) : entry.name;
+            if (!isTrackedPullEntry(childRel))
+                continue;
+            const childAbs = path.join(abs, entry.name);
+            if (entry.isDirectory())
+                walk(childAbs, childRel);
+            else if (entry.isFile())
+                out.push(childRel);
+        }
+    };
+    walk(dir, "");
+    return out;
+}
+function hashPulledFile(abs) {
+    return createHash("sha256").update(fs.readFileSync(abs)).digest("hex");
+}
+function writePullManifest(dir, version) {
+    const files = {};
+    for (const rel of listPulledFiles(dir)) {
+        try {
+            files[rel] = hashPulledFile(path.join(dir, rel));
+        }
+        catch {
+            /* skip unreadable */
+        }
+    }
+    try {
+        fs.writeFileSync(path.join(dir, PULL_MANIFEST), JSON.stringify({ version, pulled_at: new Date().toISOString(), files }, null, 2));
+    }
+    catch {
+        /* non-fatal: worst case, the next pull treats the folder as having local edits */
+    }
+}
+// True if the folder has edits relative to its last pull — or if we can't tell (no
+// manifest), in which case we err on the side of preserving whatever's there.
+function hasLocalPullEdits(dir) {
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(path.join(dir, PULL_MANIFEST), "utf-8"));
+    }
+    catch {
+        return true; // no/unreadable manifest — can't verify, treat as having local edits
+    }
+    const recorded = manifest.files || {};
+    // A tracked file the last pull didn't write is a local addition.
+    for (const rel of listPulledFiles(dir)) {
+        if (!(rel in recorded))
+            return true;
+    }
+    // A recorded file that's now missing or changed is a local edit.
+    for (const rel of Object.keys(recorded)) {
+        const abs = path.join(dir, rel);
+        if (!fs.existsSync(abs))
+            return true;
+        try {
+            if (hashPulledFile(abs) !== recorded[rel])
+                return true;
+        }
+        catch {
+            return true;
+        }
+    }
+    return false;
+}
+// Copy the current source (minus node_modules/.git) to a sibling backup folder so a
+// forced re-pull never destroys un-pulled work. Returns the backup path.
+function backupPulledSource(dir) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    let backup = `${dir}.local-backup-${stamp}`;
+    let n = 1;
+    while (fs.existsSync(backup))
+        backup = `${dir}.local-backup-${stamp}-${n++}`;
+    fs.cpSync(dir, backup, {
+        recursive: true,
+        filter: (src) => {
+            const rel = path.relative(dir, src);
+            if (!rel)
+                return true;
+            // Keep everything except dependencies, VCS, and the manifest; do keep .env* so the backup is complete.
+            const top = rel.split(path.sep)[0];
+            if (top === "node_modules" || top === ".git" || rel === PULL_MANIFEST)
+                return false;
+            return true;
+        },
+    });
+    return backup;
+}
+async function promptPullConflict() {
+    const answer = await prompt("This folder has local changes that aren't deployed. [K]eep mine / [r]eplace / [b]ackup then replace? (K/r/b)");
+    const a = answer.trim().toLowerCase();
+    if (a === "r" || a === "replace")
+        return "replace";
+    if (a === "b" || a === "backup")
+        return "backup";
+    return "keep";
+}
 async function pull(slug) {
     if (!slug) {
-        console.error("\n  Usage: npx @overscore/cli pull <dashboard-slug> [--version N] [--force]\n");
+        console.error("\n  Usage: npx @overscore/cli pull <dashboard-slug> [--project <slug>] [--version N] [--force]\n");
         console.error("  Example:");
         console.error("    npx @overscore/cli pull my-dashboard\n");
         process.exit(1);
@@ -923,10 +1039,18 @@ async function pull(slug) {
     const versionParam = versionIndex !== -1 && process.argv[versionIndex + 1]
         ? process.argv[versionIndex + 1]
         : null;
-    // --force skips the "directory exists, overwrite?" confirm — needed for non-interactive
-    // re-pulls (scripted rebuilds / `workspace sync`). Source is versioned in the Hub, and the
-    // clean step below already preserves node_modules + .env, so overwriting is safe.
+    // --force skips the interactive keep/replace/backup prompt for non-interactive re-pulls
+    // (scripted rebuilds / `workspace sync`). It is NOT a license to destroy: if the folder has
+    // un-pulled local edits, the pull backs them up before overwriting (see below).
     const force = process.argv.includes("--force");
+    // --project scopes the api-key mint to the right project. Optional: the dashboard slug is
+    // used as a fallback, correct only when a project has a single same-named dashboard.
+    const projectIndex = process.argv.indexOf("--project");
+    const projectFlag = projectIndex !== -1 &&
+        process.argv[projectIndex + 1] &&
+        !process.argv[projectIndex + 1].startsWith("--")
+        ? process.argv[projectIndex + 1]
+        : null;
     // Resolve API key: device token → auto-create os_ key, else the saved project key, else prompt.
     let apiKey = "";
     const configPath = path.join(process.env.HOME || "", ".overscore", "config");
@@ -935,14 +1059,18 @@ async function pull(slug) {
         : {};
     const deviceToken = cfg.OVERSCORE_DEVICE_TOKEN;
     if (deviceToken) {
+        // Prefer the explicit --project slug; fall back to the dashboard slug (correct only when
+        // a project has a single same-named dashboard). A wrong project slug 404s and leaves
+        // apiKey empty, which we handle explicitly below.
+        const keyProjectSlug = projectFlag || slug;
         try {
-            const keyRes = await fetch(`${HUB_URL}/api/projects/${slug}/api-keys`, {
+            const keyRes = await fetch(`${HUB_URL}/api/projects/${keyProjectSlug}/api-keys`, {
                 method: "POST",
                 headers: {
                     Authorization: `Bearer ${deviceToken}`,
                     "Content-Type": "application/json",
                 },
-                body: JSON.stringify({ name: `${slug} pull key` }),
+                body: JSON.stringify({ name: `${keyProjectSlug} pull key` }),
             });
             if (keyRes.status === 401 || keyRes.status === 403) {
                 console.error("\n  Error: Device token is invalid or expired. Run 'npx @overscore/cli auth login' to re-authenticate.\n");
@@ -957,14 +1085,26 @@ async function pull(slug) {
             // Network error — fall through to the saved key / prompt
         }
     }
-    // The mint above targets /api/projects/<slug>, but `slug` is a DASHBOARD slug — for any
-    // project whose name differs from the dashboard (i.e. any multi-dashboard project) that
-    // 404s and leaves apiKey empty. Fall back to the project API key saved by `auth login`:
-    // it authorizes every dashboard in the logged-in project, which is the common pull case
-    // (and what makes non-interactive `pull` / scripted rebuilds work).
+    // Fall back to the project API key saved by `auth login`, if any: it authorizes every
+    // dashboard in the logged-in project.
     if (!apiKey && cfg.OVERSCORE_API_KEY) {
         apiKey = cfg.OVERSCORE_API_KEY;
     }
+    // A logged-in (device-token) user whose mint failed and who has no saved project key gets a
+    // clear, actionable error instead of a raw "paste an API key" prompt they have no key for.
+    // The interactive prompt below is reserved for the pure API-key path (no device token).
+    if (!apiKey && deviceToken) {
+        if (!projectFlag) {
+            console.error(`\n  Error: Couldn't resolve the project for dashboard "${slug}".`);
+            console.error(`  If it belongs to a multi-dashboard project, pass the project slug:`);
+            console.error(`    npx @overscore/cli pull ${slug} --project <project-slug>\n`);
+        }
+        else {
+            console.error(`\n  Error: Couldn't create a key for project "${projectFlag}".`);
+            console.error(`  Check the project slug and that you have access to it.\n`);
+        }
+        process.exit(1);
+    }
     if (!apiKey) {
         console.log("  Tip: Run 'npx @overscore/cli auth login' to authenticate once and skip this step.");
         apiKey = await prompt("API key (from the Hub):");
@@ -1001,15 +1141,31 @@ async function pull(slug) {
     const zipBuffer = Buffer.from(await res.arrayBuffer());
     // Extract to ./<slug>/
     const targetDir = path.resolve(process.cwd(), slug);
-    if (fs.existsSync(targetDir) && !force) {
-        const yes = await confirm(`Directory "${slug}" already exists. Overwrite source files?`);
-        if (!yes) {
-            console.log("  Cancelled.\n");
-            return;
+    const dirExists = fs.existsSync(targetDir);
+    // Guard against destroying un-pulled local edits before we overwrite the folder.
+    if (dirExists && hasLocalPullEdits(targetDir)) {
+        if (force) {
+            // Non-interactive re-pull (workspace sync / scripts): never destroy silently —
+            // snapshot the local edits first, then proceed.
+            const backup = backupPulledSource(targetDir);
+            console.log(`\n  Local changes detected — backed them up to:\n    ${backup}`);
+        }
+        else {
+            const choice = await promptPullConflict();
+            if (choice === "keep") {
+                console.log("  Cancelled — your local files are untouched.\n");
+                return;
+            }
+            if (choice === "backup") {
+                const backup = backupPulledSource(targetDir);
+                console.log(`  Backed up your changes to:\n    ${backup}`);
+            }
+            // "replace" → fall through to the overwrite
         }
     }
+    // A clean folder (matches its last pull) is safe to overwrite with no prompt.
     // Clean target directory (preserve node_modules and .env)
-    if (fs.existsSync(targetDir)) {
+    if (dirExists) {
         for (const entry of fs.readdirSync(targetDir)) {
             if (entry === "node_modules" || entry.startsWith(".env"))
                 continue;
@@ -1077,6 +1233,9 @@ VITE_OVERSCORE_API_URL=${HUB_URL}/api
     }
     // Pull latest platform rules (includes save-knowledge skill)
     await syncPlatformRules(targetDir, baseUrl, apiKey);
+    // Record what this pull wrote so a future re-pull can detect local edits before
+    // overwriting them (see hasLocalPullEdits / the --force backup above).
+    writePullManifest(targetDir, version);
     // Print context summary so the developer knows what Claude has access to
     const knowledgeDir = path.join(targetDir, ".claude", "knowledge");
     const knowledgeFiles = fs.existsSync(knowledgeDir)

package/package.json

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