@overscore/cli 0.13.20 → 0.13.22

package/dist/homes.js

@@ -0,0 +1,134 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+const SCHEMA_VERSION = 1;
+const CONFIG_DIR = path.join(os.homedir(), ".overscore");
+const HOMES_PATH = path.join(CONFIG_DIR, "homes.json");
+const LOCK_PATH = HOMES_PATH + ".lock";
+const LOCK_STALE_MS = 10000;
+// Managed workspace root. Project-nested from day one so that graduating a project to a
+// dbt workspace is purely additive: the workspace wrapper drops in at the project root
+// and `overscore/<slug>/` never has to move.
+export function managedRoot() {
+    return path.join(os.homedir(), "Overscore");
+}
+export function managedProjectDir(projectSlug) {
+    return path.join(managedRoot(), projectSlug);
+}
+export function managedOverscoreDir(projectSlug) {
+    return path.join(managedProjectDir(projectSlug), "overscore");
+}
+export function managedDashboardDir(projectSlug, dashboardSlug) {
+    return path.join(managedOverscoreDir(projectSlug), dashboardSlug);
+}
+function readHomesFile() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(HOMES_PATH, "utf-8"));
+        if (parsed && typeof parsed === "object" && parsed.homes) {
+            return { schema_version: parsed.schema_version ?? SCHEMA_VERSION, homes: parsed.homes };
+        }
+    }
+    catch {
+        // Missing or corrupt. Atomic rename means a reader never sees a torn write, so a parse
+        // failure means no file yet (or a truly hand-mangled one) — start fresh.
+    }
+    return { schema_version: SCHEMA_VERSION, homes: {} };
+}
+// Reads are lock-free: writes rename atomically, so a reader sees either the old or the new
+// complete file, never a partial one. Returns null if the project has no home recorded yet.
+export function getHome(projectSlug) {
+    return readHomesFile().homes[projectSlug] ?? null;
+}
+// A cross-process advisory lock so a read-modify-write from `overscore open` can't lose an
+// update raced against a concurrent `workspace` write. Exclusive-create the lockfile; if
+// it's held, wait, and reclaim it only if it's gone stale.
+function withLock(fn) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    const start = Date.now();
+    // Small synchronous sleep without pulling in a dependency.
+    const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    for (;;) {
+        try {
+            const fd = fs.openSync(LOCK_PATH, "wx");
+            fs.writeSync(fd, String(process.pid));
+            fs.closeSync(fd);
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            let age = Infinity;
+            try {
+                age = Date.now() - fs.statSync(LOCK_PATH).mtimeMs;
+            }
+            catch {
+                continue; // lock vanished between openSync and statSync — retry immediately
+            }
+            if (age > LOCK_STALE_MS) {
+                try {
+                    fs.rmSync(LOCK_PATH, { force: true });
+                }
+                catch {
+                    /* someone else reclaimed it */
+                }
+                continue;
+            }
+            if (Date.now() - start > LOCK_STALE_MS) {
+                throw new Error("Timed out waiting for the homes.json lock");
+            }
+            sleep(50);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            fs.rmSync(LOCK_PATH, { force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+function writeAtomic(data) {
+    const tmp = `${HOMES_PATH}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+    // On Windows a rename can transiently fail with EPERM/EBUSY if a lock-free reader has the
+    // file open; retry briefly rather than crash after side effects.
+    for (let attempt = 0;; attempt++) {
+        try {
+            fs.renameSync(tmp, HOMES_PATH);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            if (process.platform === "win32" && (code === "EPERM" || code === "EBUSY") && attempt < 5) {
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+                continue;
+            }
+            try {
+                fs.rmSync(tmp, { force: true });
+            }
+            catch {
+                /* best effort */
+            }
+            throw err;
+        }
+    }
+}
+// Record (or update) where a project lives: locked read-modify-write + atomic replace. Refuses
+// to write over a homes.json written by a newer CLI, so an old binary can't downgrade/corrupt it.
+export function setHome(projectSlug, entry) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    withLock(() => {
+        const file = readHomesFile();
+        if (file.schema_version > SCHEMA_VERSION) {
+            throw new Error(`~/.overscore/homes.json is version ${file.schema_version}, but this Overscore CLI only ` +
+                `understands version ${SCHEMA_VERSION}. Update the CLI (npm i -g @overscore/cli).`);
+        }
+        file.schema_version = SCHEMA_VERSION;
+        file.homes[projectSlug] = entry;
+        writeAtomic(file);
+    });
+}

package/dist/index.js

@@ -9,6 +9,7 @@ import { createInterface } from "readline";
 import { createHash, randomBytes } from "crypto";
 import yauzl from "yauzl";
 import { templatePush } from "./template-push.js";
+import { getHome, setHome, managedProjectDir, managedOverscoreDir, managedDashboardDir, } from "./homes.js";
 // ── 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
@@ -75,7 +76,7 @@ async function loadEnv() {
         }
         // .env has project context but no API key — generate one via device token
         if (projectSlug) {
-            const globalCfgPath = path.join(process.env.HOME || "", ".overscore", "config");
+            const globalCfgPath = path.join(os.homedir(), ".overscore", "config");
             const globalCfg = fs.existsSync(globalCfgPath)
                 ? parseEnv(fs.readFileSync(globalCfgPath, "utf-8"))
                 : {};
@@ -98,7 +99,7 @@ async function loadEnv() {
         }
     }
     // (2) Global config (works from analysis folders or anywhere)
-    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath = path.join(os.homedir(), ".overscore", "config");
     if (fs.existsSync(configPath)) {
         const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
         if (cfg.OVERSCORE_API_KEY) {
@@ -125,7 +126,7 @@ async function loadEnv() {
     // No creds — trigger browser auth inline, then re-check
     console.log("\n  No Overscore credentials found. Launching browser login...\n");
     await authLogin();
-    const configPath2 = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath2 = path.join(os.homedir(), ".overscore", "config");
     if (fs.existsSync(configPath2)) {
         const cfg2 = parseEnv(fs.readFileSync(configPath2, "utf-8"));
         if (cfg2.OVERSCORE_API_KEY) {
@@ -229,7 +230,7 @@ function prompt(message) {
     });
 }
 async function refreshApiKey(projectSlug) {
-    const configDir = path.join(process.env.HOME || "", ".overscore");
+    const configDir = path.join(os.homedir(), ".overscore");
     const configPath = path.join(configDir, "config");
     let cfg = fs.existsSync(configPath)
         ? parseEnv(fs.readFileSync(configPath, "utf-8"))
@@ -911,9 +912,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,26 +1040,38 @@ 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");
+    const configPath = path.join(os.homedir(), ".overscore", "config");
     const cfg = fs.existsSync(configPath)
         ? parseEnv(fs.readFileSync(configPath, "utf-8"))
         : {};
     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 +1086,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 +1142,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 +1234,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)
@@ -1178,7 +1338,7 @@ async function listDashboards() {
 // 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 configPath = path.join(os.homedir(), ".overscore", "config");
     const readToken = () => {
         const cfg = fs.existsSync(configPath)
             ? parseEnv(fs.readFileSync(configPath, "utf-8"))
@@ -1334,7 +1494,7 @@ async function loadAnalysisConfig() {
         }
     }
     // (2) ~/.overscore/config
-    const configDir = path.join(process.env.HOME || "", ".overscore");
+    const configDir = path.join(os.homedir(), ".overscore");
     const configPath = path.join(configDir, "config");
     if (fs.existsSync(configPath)) {
         const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
@@ -2722,7 +2882,7 @@ async function dev() {
     // "Invalid API key".
     assertHubMatchesEnv();
     // Get device token from global config
-    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath = path.join(os.homedir(), ".overscore", "config");
     if (!fs.existsSync(configPath)) {
         console.error("\n  Error: Not authenticated. Run 'npx @overscore/cli auth login' first.\n");
         process.exit(1);
@@ -2819,7 +2979,7 @@ async function dev() {
 }
 // ── auth ────────────────────────────────────────────────────────────
 async function authStatus() {
-    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath = path.join(os.homedir(), ".overscore", "config");
     if (fs.existsSync(configPath)) {
         const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
         const deviceToken = cfg.OVERSCORE_DEVICE_TOKEN;
@@ -2845,7 +3005,7 @@ async function authStatus() {
 `);
 }
 async function authLogin() {
-    const configDir = path.join(process.env.HOME || "", ".overscore");
+    const configDir = path.join(os.homedir(), ".overscore");
     const configPath = path.join(configDir, "config");
     const state = randomBytes(16).toString("hex");
     // Find a free port in range 9876–9886
@@ -2924,11 +3084,13 @@ async function authLogin() {
     const { token: deviceToken, project: projectSlug } = await callbackPromise;
     clearTimeout(timeout);
     server.close();
-    // Preserve any existing os_ API key so dashboard .env fallback still works
+    // Preserve any existing os_ API key + saved tool preference so re-login doesn't drop them
     let existingApiKey = "";
+    let existingTool = "";
     if (fs.existsSync(configPath)) {
         const existing = parseEnv(fs.readFileSync(configPath, "utf-8"));
         existingApiKey = existing.OVERSCORE_API_KEY || "";
+        existingTool = existing.OVERSCORE_TOOL || "";
     }
     fs.mkdirSync(configDir, { recursive: true });
     const lines = [
@@ -2939,6 +3101,8 @@ async function authLogin() {
         lines.push(`OVERSCORE_PROJECT_SLUG=${projectSlug}`);
     if (existingApiKey)
         lines.push(`OVERSCORE_API_KEY=${existingApiKey}`);
+    if (existingTool)
+        lines.push(`OVERSCORE_TOOL=${existingTool}`);
     fs.writeFileSync(configPath, lines.join("\n") + "\n", { mode: 0o600 });
     console.log(`
   Authenticated!
@@ -2949,7 +3113,7 @@ async function authLogin() {
 `);
 }
 async function authLogout() {
-    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath = path.join(os.homedir(), ".overscore", "config");
     if (fs.existsSync(configPath)) {
         // Attempt server-side revocation of the device token (non-fatal)
         try {
@@ -2983,7 +3147,7 @@ async function installSkills() {
         console.error(`\n  Error: Bundled skills directory not found at ${skillsSrc}\n`);
         process.exit(1);
     }
-    const homeSkills = path.join(process.env.HOME || "", ".claude", "skills");
+    const homeSkills = path.join(os.homedir(), ".claude", "skills");
     fs.mkdirSync(homeSkills, { recursive: true });
     const installed = [];
     for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
@@ -3030,7 +3194,7 @@ async function templatePull(slug) {
         res = await fetch(url, {
             // Optional: attach device token if available, for attribution in install counting
             headers: (() => {
-                const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+                const configPath = path.join(os.homedir(), ".overscore", "config");
                 if (fs.existsSync(configPath)) {
                     const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
                     if (cfg.OVERSCORE_DEVICE_TOKEN) {
@@ -3101,6 +3265,263 @@ async function templatePull(slug) {
 // ── Routing ─────────────────────────────────────────────────────────
 const command = process.argv[2];
 const subcommand = process.argv[3];
+const OPEN_TOOL_LABELS = {
+    code: "VS Code",
+    cursor: "Cursor",
+    claude: "Claude Code (terminal)",
+    codex: "Codex",
+};
+const OPEN_TOOLS = ["code", "cursor", "claude", "codex"];
+const DASHBOARD_STARTER = "Build me a professional dashboard for this data.";
+const WORKSPACE_STARTER = "Read the catalog first, then help me build or update a dashboard for this client.";
+function openCmdOnPath(cmd) {
+    try {
+        execSync(process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`, {
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function detectOpenTools() {
+    return OPEN_TOOLS.filter((t) => openCmdOnPath(t));
+}
+function saveConfigValue(key, value) {
+    const dir = path.join(os.homedir(), ".overscore");
+    const configPath = path.join(dir, "config");
+    const cfg = fs.existsSync(configPath)
+        ? parseEnv(fs.readFileSync(configPath, "utf-8"))
+        : {};
+    cfg[key] = value;
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(configPath, Object.entries(cfg)
+        .map(([k, v]) => `${k}=${v}`)
+        .join("\n") + "\n", { mode: 0o600 });
+}
+// Which tool to open in: an explicit --tool wins, then a remembered choice, then detection
+// (one installed → use it; several → ask once and remember). Null if nothing is installed.
+async function chooseOpenTool(explicit) {
+    if (explicit && OPEN_TOOLS.includes(explicit))
+        return explicit;
+    const configPath = path.join(os.homedir(), ".overscore", "config");
+    const cfg = fs.existsSync(configPath)
+        ? parseEnv(fs.readFileSync(configPath, "utf-8"))
+        : {};
+    const saved = cfg.OVERSCORE_TOOL;
+    if (saved && OPEN_TOOLS.includes(saved))
+        return saved;
+    const available = detectOpenTools();
+    if (available.length === 0)
+        return null;
+    let chosen;
+    if (available.length === 1) {
+        chosen = available[0];
+    }
+    else {
+        console.log("\n  Which tool do you build with?");
+        available.forEach((t, i) => console.log(`    ${i + 1}) ${OPEN_TOOL_LABELS[t]}`));
+        const ans = await prompt(`Choose 1-${available.length}:`);
+        chosen = available[parseInt(ans, 10) - 1] ?? available[0];
+    }
+    saveConfigValue("OVERSCORE_TOOL", chosen);
+    return chosen;
+}
+function launchUrl(url) {
+    try {
+        if (process.platform === "darwin")
+            execSync(`open '${url}'`);
+        else if (process.platform === "win32")
+            execSync(`start "" "${url}"`);
+        else
+            execSync(`xdg-open '${url}'`);
+    }
+    catch {
+        /* best effort */
+    }
+}
+// Open a folder in the chosen tool. GUI editors open cleanly by spawning their launcher;
+// terminal agents can't be launched cleanly everywhere, so we hand back a copy-paste hint.
+function openFolderInTool(tool, dir, starter) {
+    try {
+        if (tool === "code") {
+            execSync(`code -r "${dir}"`, { stdio: "ignore" });
+            return { opened: true, hint: "" };
+        }
+        if (tool === "cursor") {
+            execSync(`cursor "${dir}"`, { stdio: "ignore" });
+            return { opened: true, hint: "" };
+        }
+        if (tool === "claude") {
+            // Opens a terminal running claude in the folder (pre-fills, does not send, the prompt).
+            // The handler only registers after the first interactive claude session, so also give
+            // the manual fallback.
+            launchUrl(`claude-cli://open?cwd=${encodeURIComponent(dir)}&q=${encodeURIComponent(starter)}`);
+            return { opened: true, hint: `If Claude didn't open, run:  cd "${dir}" && claude` };
+        }
+        // codex: no folder deep link — hand over the exact command.
+        return { opened: false, hint: `cd "${dir}" && codex` };
+    }
+    catch {
+        return { opened: false, hint: `Open "${dir}" in ${OPEN_TOOL_LABELS[tool]} to start building.` };
+    }
+}
+function runOpenChild(cmd, cwd) {
+    try {
+        execSync(cmd, { cwd, stdio: "inherit" });
+    }
+    catch {
+        console.error(`\n  Error: setup step failed:\n    ${cmd}\n`);
+        process.exit(1);
+    }
+}
+async function probeDashboard(deviceToken, projectSlug, dashboardSlug) {
+    let apiKey = "";
+    try {
+        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: `${projectSlug} open key` }),
+        });
+        if (keyRes.status === 401 || keyRes.status === 403)
+            return { state: "unauthorized", apiKey };
+        if (!keyRes.ok)
+            return { state: "error", apiKey };
+        apiKey = (await keyRes.json()).raw_key || "";
+    }
+    catch {
+        return { state: "error", apiKey };
+    }
+    if (!apiKey)
+        return { state: "error", apiKey };
+    try {
+        const vRes = await fetch(`${HUB_URL}/api/dashboards/${dashboardSlug}/versions`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (vRes.status === 401 || vRes.status === 403)
+            return { state: "unauthorized", apiKey };
+        if (vRes.status === 404)
+            return { state: "new", apiKey };
+        if (!vRes.ok)
+            return { state: "error", apiKey };
+        const data = (await vRes.json());
+        const deployed = Array.isArray(data.versions) && data.versions.length > 0;
+        return { state: deployed ? "deployed" : "new", apiKey };
+    }
+    catch {
+        return { state: "error", apiKey };
+    }
+}
+function finishOpen(res, dir) {
+    console.log(res.opened ? `\n  Opened in your tool:\n    ${dir}` : `\n  Ready at:\n    ${dir}`);
+    if (res.hint)
+        console.log(`\n  ${res.hint}`);
+    console.log(`\n  Tell your AI tool what to build. When it looks right, say "deploy it".\n`);
+}
+async function open(dashboardSlug) {
+    if (!dashboardSlug || dashboardSlug.startsWith("--")) {
+        console.error("\n  Usage: npx @overscore/cli open <dashboard-slug> --project <slug> [--tool code|cursor|claude|codex]\n");
+        process.exit(1);
+    }
+    const projIdx = process.argv.indexOf("--project");
+    const projectSlug = projIdx !== -1 && process.argv[projIdx + 1] && !process.argv[projIdx + 1].startsWith("--")
+        ? process.argv[projIdx + 1]
+        : null;
+    if (!projectSlug) {
+        console.error(`\n  Error: --project <slug> is required.`);
+        console.error(`    npx @overscore/cli open ${dashboardSlug} --project <project-slug>\n`);
+        process.exit(1);
+    }
+    // Slugs get interpolated into shell commands and filesystem paths below, so validate them
+    // strictly (lowercase alphanumeric + hyphens) — this also blocks command injection.
+    const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+    if (!SLUG_RE.test(dashboardSlug) || !SLUG_RE.test(projectSlug)) {
+        console.error("\n  Error: project and dashboard slugs must be lowercase letters, numbers, and hyphens.\n");
+        process.exit(1);
+    }
+    const toolIdx = process.argv.indexOf("--tool");
+    const toolFlag = toolIdx !== -1 ? process.argv[toolIdx + 1] : undefined;
+    // 1. Ensure a device token (browser login if needed) — the same file every tool reads.
+    const configPath = path.join(os.homedir(), ".overscore", "config");
+    const readToken = () => (fs.existsSync(configPath) ? parseEnv(fs.readFileSync(configPath, "utf-8")) : {})
+        .OVERSCORE_DEVICE_TOKEN;
+    let deviceToken = readToken();
+    if (!deviceToken) {
+        console.log("\n  No session found. Signing you in...\n");
+        await authLogin();
+        deviceToken = readToken();
+        if (!deviceToken) {
+            console.error("\n  Could not authenticate.\n");
+            process.exit(1);
+        }
+    }
+    // 2. Coexistence: if a dbt workspace already owns this project, open it there instead of
+    //    making a second, divergent copy.
+    const existing = getHome(projectSlug);
+    if (existing?.mode === "workspace") {
+        console.log(`\n  Project "${projectSlug}" is managed by a workspace at:\n    ${existing.path}`);
+        const tool = await chooseOpenTool(toolFlag);
+        if (!tool) {
+            console.log(`\n  Install an AI coding tool, then open that folder to build.\n`);
+            return;
+        }
+        finishOpen(openFolderInTool(tool, existing.path, WORKSPACE_STARTER), existing.path);
+        return;
+    }
+    const dashDir = managedDashboardDir(projectSlug, dashboardSlug);
+    const parentDir = managedOverscoreDir(projectSlug);
+    // A folder counts as "ready" only if a complete scaffold/pull left a package.json — a dir
+    // that exists without one is a half-finished setup (Ctrl-C, crash, lost network) we redo.
+    const isReady = (d) => fs.existsSync(path.join(d, "package.json"));
+    // 3. Make sure the source is present locally.
+    if (isReady(dashDir)) {
+        console.log(`\n  Opening your local copy of "${dashboardSlug}"...`);
+    }
+    else {
+        // Clear away any half-written folder left by a previous interrupted run.
+        if (fs.existsSync(dashDir))
+            fs.rmSync(dashDir, { recursive: true, force: true });
+        fs.mkdirSync(parentDir, { recursive: true });
+        let probe = await probeDashboard(deviceToken, projectSlug, dashboardSlug);
+        if (probe.state === "unauthorized") {
+            console.log("\n  Your session expired. Signing you in again...\n");
+            await authLogin();
+            deviceToken = readToken() || deviceToken;
+            probe = await probeDashboard(deviceToken, projectSlug, dashboardSlug);
+        }
+        if (probe.state === "error" || probe.state === "unauthorized") {
+            console.error(`\n  Error: couldn't reach the Hub for project "${projectSlug}".`);
+            console.error(`  Check the project slug and your access, then try again.\n`);
+            process.exit(1);
+        }
+        const selfCli = process.argv[1];
+        if (probe.state === "deployed") {
+            console.log(`\n  Fetching "${dashboardSlug}" from the Hub...`);
+            runOpenChild(`node "${selfCli}" pull ${dashboardSlug} --project ${projectSlug} --force`, parentDir);
+        }
+        else {
+            console.log(`\n  Setting up a new dashboard "${dashboardSlug}"...`);
+            // Reuse the key we already minted so the scaffold doesn't mint a second one.
+            const keyArg = probe.apiKey ? ` --key ${probe.apiKey}` : "";
+            runOpenChild(`npx --yes create-overscore --dashboard ${dashboardSlug} --project ${projectSlug}${keyArg}`, parentDir);
+        }
+        if (!isReady(dashDir)) {
+            console.error(`\n  Error: setup did not complete for:\n    ${dashDir}\n`);
+            process.exit(1);
+        }
+    }
+    // 4. Record the project's home so re-opens and workspace graduation stay coherent.
+    setHome(projectSlug, { path: managedProjectDir(projectSlug), mode: "flat" });
+    // 5. Open it in the user's tool.
+    const tool = await chooseOpenTool(toolFlag);
+    if (!tool) {
+        console.log(`\n  Your dashboard is ready at:\n    ${dashDir}`);
+        console.log(`\n  Install Claude Code, Codex, VS Code, or Cursor, then open that folder to build.\n`);
+        return;
+    }
+    finishOpen(openFolderInTool(tool, dashDir, DASHBOARD_STARTER), dashDir);
+}
 if (command === "dev") {
     dev();
 }
@@ -3110,6 +3531,9 @@ else if (command === "deploy") {
 else if (command === "pull") {
     pull(process.argv[3]);
 }
+else if (command === "open") {
+    open(process.argv[3]);
+}
 else if (command === "versions") {
     versions();
 }
@@ -3281,6 +3705,7 @@ else {
     auth                   Check authentication status
     auth login             Authenticate via browser (one time per machine)
     auth logout            Remove saved credentials
+    open <slug>            Set up or fetch a dashboard and open it in your AI tool
     dev                    Start the dev server (injects auth automatically)
     list                   List all dashboards in the project
     projects               List every project on your account
@@ -3294,6 +3719,7 @@ else {
 
   Usage:
     npx @overscore/cli auth login
+    npx @overscore/cli open <slug> --project <project-slug>
     npx @overscore/cli dev
     npx @overscore/cli list
     npx @overscore/cli projects

package/package.json

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