@overscore/cli 0.13.19 → 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)
@@ -1155,6 +1314,7 @@ async function listDashboards() {
     }
     const data = (await res.json());
     console.log(`\n  ${data.project} (${data.project_slug})\n`);
+    console.log("  Showing one project — run 'overscore projects' to list them all.\n");
     if (data.dashboards.length === 0) {
         console.log("  No dashboards yet.\n");
         return;
@@ -1173,6 +1333,65 @@ async function listDashboards() {
         console.log();
     }
 }
+// Account-level project list. Uses the CLI DEVICE token (ocli_) rather than a
+// project-scoped API key, so it can enumerate EVERY project on the account —
+// including empty ones a project key could never see.
+async function listProjects() {
+    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    const readToken = () => {
+        const cfg = fs.existsSync(configPath)
+            ? parseEnv(fs.readFileSync(configPath, "utf-8"))
+            : {};
+        return cfg.OVERSCORE_DEVICE_TOKEN;
+    };
+    let deviceToken = readToken();
+    if (!deviceToken) {
+        console.log("\n  No session found. Launching browser login...\n");
+        await authLogin();
+        deviceToken = readToken();
+        if (!deviceToken) {
+            console.error("\n  Could not authenticate.\n");
+            process.exit(1);
+        }
+    }
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const res = await fetch(`${HUB_URL}/api/projects`, {
+            headers: { Authorization: `Bearer ${deviceToken}` },
+        });
+        if (res.ok) {
+            const { projects } = (await res.json());
+            printProjects(projects);
+            return;
+        }
+        // Device token expired — re-auth once, then retry.
+        if (res.status === 401 && attempt === 0) {
+            console.log("\n  Session expired. Launching browser login...\n");
+            await authLogin();
+            deviceToken = readToken();
+            if (!deviceToken)
+                break;
+            continue;
+        }
+        const body = (await res.json().catch(() => ({})));
+        console.error(`\n  Error: ${body.error || `HTTP ${res.status}`}\n`);
+        process.exit(1);
+    }
+    console.error("\n  Could not authenticate.\n");
+    process.exit(1);
+}
+function printProjects(projects) {
+    if (!projects.length) {
+        console.log("\n  No projects yet.\n\n    Create one:  npx create-overscore --dashboard <name> --project <slug>\n");
+        return;
+    }
+    console.log(`\n  Your projects (${projects.length})\n`);
+    for (const p of projects) {
+        const count = p.dashboard_count === 1 ? "1 dashboard" : `${p.dashboard_count} dashboards`;
+        console.log(`  ${p.name}`);
+        console.log(`    slug: ${p.slug}  ·  ${count}  ·  ${p.role}`);
+        console.log();
+    }
+}
 function collectFiles(dir, prefix) {
     const files = [];
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -3056,6 +3275,9 @@ else if (command === "versions") {
 else if (command === "list") {
     listDashboards();
 }
+else if (command === "projects") {
+    listProjects();
+}
 else if (command === "install-skills") {
     installSkills();
 }
@@ -3220,6 +3442,7 @@ else {
     auth logout            Remove saved credentials
     dev                    Start the dev server (injects auth automatically)
     list                   List all dashboards in the project
+    projects               List every project on your account
     deploy                 Build and deploy the dashboard
     pull <slug>            Pull source code from the hub
     versions               List deploy history
@@ -3232,6 +3455,7 @@ else {
     npx @overscore/cli auth login
     npx @overscore/cli dev
     npx @overscore/cli list
+    npx @overscore/cli projects
     npx @overscore/cli deploy --message "description"
     npx @overscore/cli pull <slug>
     npx @overscore/cli pull <slug> --version 3

package/package.json

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