@overscore/cli 0.6.0

package/dist/index.js

@@ -0,0 +1,711 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { createInterface } from "readline";
+import yauzl from "yauzl";
+// ── Shared helpers ──────────────────────────────────────────────────
+function parseEnv(content) {
+    const env = {};
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex);
+        const value = trimmed.slice(eqIndex + 1);
+        env[key] = value;
+    }
+    return env;
+}
+function loadEnv() {
+    const envPath = path.resolve(process.cwd(), ".env");
+    if (!fs.existsSync(envPath)) {
+        console.error("  Error: No .env file found. Run npx create-overscore first.");
+        process.exit(1);
+    }
+    const env = parseEnv(fs.readFileSync(envPath, "utf-8"));
+    const apiUrl = env.VITE_OVERSCORE_API_URL;
+    const apiKey = env.VITE_OVERSCORE_API_KEY;
+    const dashboardSlug = env.VITE_OVERSCORE_DASHBOARD_SLUG || path.basename(process.cwd());
+    if (!apiUrl || !apiKey) {
+        console.error("  Error: Missing VITE_OVERSCORE_API_URL or VITE_OVERSCORE_API_KEY in .env");
+        process.exit(1);
+    }
+    const projectSlug = env.VITE_OVERSCORE_PROJECT_SLUG || "";
+    return { apiUrl, apiKey, dashboardSlug, projectSlug };
+}
+async function apiRequest(method, urlPath, body) {
+    const { apiUrl, apiKey } = loadEnv();
+    const baseUrl = apiUrl.replace(/\/api$/, "");
+    const url = `${baseUrl}${urlPath}`;
+    const headers = {
+        Authorization: `Bearer ${apiKey}`,
+    };
+    if (body !== undefined) {
+        headers["Content-Type"] = "application/json";
+    }
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        console.error(`\n  Error: ${data.error || `HTTP ${res.status}`}\n`);
+        process.exit(1);
+    }
+    return data;
+}
+function confirm(message) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`  ${message} (y/N) `, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === "y");
+        });
+    });
+}
+function prompt(message) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`  ${message} `, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+const SOURCE_EXCLUDE = new Set([
+    "node_modules",
+    "dist",
+    ".git",
+    ".DS_Store",
+    ".aws",
+    ".ssh",
+    ".kube",
+    ".docker",
+    ".gnupg",
+    ".overscore",
+]);
+const SECRET_FILE_EXTENSIONS = new Set([
+    ".pem",
+    ".key",
+    ".p12",
+    ".pfx",
+    ".jks",
+    ".keystore",
+]);
+function collectSourceFiles(dir, prefix) {
+    const files = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        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))
+            continue;
+        const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            files.push(...collectSourceFiles(path.join(dir, entry.name), relativePath));
+        }
+        else {
+            files.push(relativePath);
+        }
+    }
+    return files;
+}
+function extractZip(zipBuffer, targetDir) {
+    return new Promise((resolve, reject) => {
+        yauzl.fromBuffer(zipBuffer, { lazyEntries: true }, (err, zipfile) => {
+            if (err || !zipfile)
+                return reject(err || new Error("Failed to open zip"));
+            zipfile.readEntry();
+            zipfile.on("entry", (entry) => {
+                const fullPath = path.resolve(targetDir, entry.fileName);
+                if (!fullPath.startsWith(path.resolve(targetDir) + path.sep) && fullPath !== path.resolve(targetDir)) {
+                    return reject(new Error(`Zip entry escapes target directory: ${entry.fileName}`));
+                }
+                if (entry.fileName.endsWith("/")) {
+                    // Directory
+                    fs.mkdirSync(fullPath, { recursive: true });
+                    zipfile.readEntry();
+                }
+                else {
+                    // File
+                    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+                    zipfile.openReadStream(entry, (err2, readStream) => {
+                        if (err2 || !readStream)
+                            return reject(err2 || new Error("Failed to read entry"));
+                        const writeStream = fs.createWriteStream(fullPath);
+                        readStream.pipe(writeStream);
+                        writeStream.on("close", () => zipfile.readEntry());
+                        writeStream.on("error", reject);
+                    });
+                }
+            });
+            zipfile.on("end", resolve);
+            zipfile.on("error", reject);
+        });
+    });
+}
+// ── Commands ────────────────────────────────────────────────────────
+async function deploy() {
+    const { apiUrl, apiKey, dashboardSlug } = loadEnv();
+    // Parse --message flag
+    const msgIndex = process.argv.indexOf("--message");
+    const commitMessage = msgIndex !== -1 && process.argv[msgIndex + 1]
+        ? process.argv[msgIndex + 1]
+        : null;
+    console.log(`\n  Deploying dashboard: ${dashboardSlug}\n`);
+    // Build (strip API key from the bundle — it's for local dev only)
+    console.log("  Building...");
+    try {
+        execSync("npm run build", {
+            stdio: "inherit",
+            env: { ...process.env, VITE_OVERSCORE_API_KEY: "" },
+        });
+    }
+    catch {
+        console.error("\n  Build failed. Fix errors and try again.");
+        process.exit(1);
+    }
+    // Collect dist files
+    const distDir = path.resolve(process.cwd(), "dist");
+    if (!fs.existsSync(distDir)) {
+        console.error("  Error: No dist/ directory found after build.");
+        process.exit(1);
+    }
+    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.`);
+    // Upload via deploy API
+    console.log("  Uploading...");
+    const formData = new FormData();
+    formData.append("dashboard_slug", dashboardSlug);
+    if (commitMessage) {
+        formData.append("commit_message", commitMessage);
+    }
+    // Built files
+    for (const file of builtFiles) {
+        const filePath = path.join(distDir, file);
+        const content = fs.readFileSync(filePath);
+        const blob = new Blob([content]);
+        formData.append(`file:${file}`, blob, file);
+    }
+    // Source files
+    for (const file of sourceFiles) {
+        const filePath = path.join(process.cwd(), file);
+        const content = fs.readFileSync(filePath);
+        const blob = new Blob([content]);
+        formData.append(`source:${file}`, blob, file);
+    }
+    const deployUrl = apiUrl.replace(/\/api$/, "") + "/api/deploy";
+    const res = await fetch(deployUrl, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${apiKey}` },
+        body: formData,
+    });
+    const data = (await res.json());
+    if (!res.ok) {
+        console.error(`\n  Deploy failed: ${data.error}`);
+        process.exit(1);
+    }
+    console.log(`
+  Deployed successfully!
+
+  ${data.file_count} built files uploaded${data.source_uploaded ? " + source code saved" : ""}
+  URL: ${data.url}
+`);
+    // Sync context files to Hub
+    const { projectSlug } = loadEnv();
+    const baseUrl = apiUrl.replace(/\/api$/, "");
+    // Sync company context (with conflict detection)
+    const companyCtxPath = path.resolve(process.cwd(), ".claude/rules/company-context.md");
+    if (fs.existsSync(companyCtxPath)) {
+        const content = fs.readFileSync(companyCtxPath, "utf-8");
+        const hashPath = path.resolve(process.cwd(), ".claude/rules/.context-hash");
+        const storedHash = fs.existsSync(hashPath) ? fs.readFileSync(hashPath, "utf-8").trim() : null;
+        try {
+            // Check if Hub version has changed since we pulled
+            const checkRes = await fetch(`${baseUrl}/api/projects/${projectSlug}/context`, {
+                headers: { Authorization: `Bearer ${apiKey}` },
+            });
+            const checkData = checkRes.ok ? (await checkRes.json()) : null;
+            const hubHash = checkData?.context_md_hash || null;
+            if (storedHash && hubHash && storedHash !== hubHash) {
+                console.log("  ⚠ Company context was updated in the Hub since you pulled.");
+                console.log(`    Review at: ${baseUrl}/projects/${projectSlug}/context`);
+                console.log("    Your local changes were NOT uploaded to avoid overwriting.");
+            }
+            else {
+                const putRes = await fetch(`${baseUrl}/api/projects/${projectSlug}/context`, {
+                    method: "PUT",
+                    headers: {
+                        Authorization: `Bearer ${apiKey}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({ context_md: content }),
+                });
+                if (putRes.ok) {
+                    const putData = (await putRes.json());
+                    // Update stored hash
+                    if (putData.context_md_hash) {
+                        fs.mkdirSync(path.dirname(hashPath), { recursive: true });
+                        fs.writeFileSync(hashPath, putData.context_md_hash);
+                    }
+                    console.log("  Company context synced.");
+                }
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    // Sync dashboard context (no conflict detection needed — per-dashboard)
+    const dashCtxPath = path.resolve(process.cwd(), ".claude/rules/dashboard-context.md");
+    if (fs.existsSync(dashCtxPath)) {
+        const content = fs.readFileSync(dashCtxPath, "utf-8");
+        try {
+            await fetch(`${baseUrl}/api/dashboards/${dashboardSlug}/context`, {
+                method: "PUT",
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ context_md: content }),
+            });
+            console.log("  Dashboard context synced.");
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+}
+async function queryList() {
+    const { dashboardSlug } = loadEnv();
+    const data = (await apiRequest("GET", `/api/dashboards/${dashboardSlug}/queries`));
+    console.log(`\n  Dashboard: ${data.dashboard}\n`);
+    if (data.queries.length === 0) {
+        console.log("  No queries registered yet.\n");
+        console.log("  Add one with:");
+        console.log('    npx overscore query add <name> "SELECT ..."\n');
+        return;
+    }
+    for (const q of data.queries) {
+        const rowInfo = q.row_count !== null ? ` (~${q.row_count.toLocaleString()} rows)` : "";
+        console.log(`  ${q.query_name}${rowInfo}`);
+        console.log(`    useQuery("${q.query_name}")`);
+        if (q.sample_row) {
+            const cols = Object.keys(q.sample_row).join(", ");
+            console.log(`    columns: ${cols}`);
+        }
+        console.log();
+    }
+}
+async function queryShow(name) {
+    if (!name) {
+        console.error("\n  Usage: npx overscore query show <name>\n");
+        process.exit(1);
+    }
+    const { dashboardSlug } = loadEnv();
+    const data = (await apiRequest("GET", `/api/dashboards/${dashboardSlug}/queries`));
+    const query = data.queries.find((q) => q.query_name === name);
+    if (!query) {
+        console.error(`\n  Error: Query "${name}" not found.\n`);
+        console.error("  Available queries:");
+        for (const q of data.queries) {
+            console.error(`    - ${q.query_name}`);
+        }
+        console.error();
+        process.exit(1);
+    }
+    console.log(`\n  ${query.query_name}`);
+    if (query.row_count !== null) {
+        console.log(`  ~${query.row_count.toLocaleString()} rows\n`);
+    }
+    else {
+        console.log();
+    }
+    console.log(`  SQL:`);
+    console.log(`  ${query.sql}\n`);
+    if (query.sample_row) {
+        console.log(`  Sample row:`);
+        console.log(`  ${JSON.stringify(query.sample_row, null, 2).split("\n").join("\n  ")}\n`);
+    }
+}
+function resolveSql(sqlOrNext) {
+    // Check for --file flag anywhere in argv
+    const fileIndex = process.argv.indexOf("--file");
+    if (fileIndex !== -1 && process.argv[fileIndex + 1]) {
+        const filePath = path.resolve(process.cwd(), process.argv[fileIndex + 1]);
+        if (!fs.existsSync(filePath)) {
+            console.error(`\n  Error: File not found: ${filePath}\n`);
+            process.exit(1);
+        }
+        return fs.readFileSync(filePath, "utf-8").trim();
+    }
+    return sqlOrNext;
+}
+async function queryAdd(name, sql) {
+    const resolvedSql = resolveSql(sql);
+    if (!name || !resolvedSql) {
+        console.error('\n  Usage: npx overscore query add <name> "<sql>"\n');
+        console.error("  Or with a file:");
+        console.error("    npx overscore query add <name> --file query.sql\n");
+        process.exit(1);
+    }
+    if (!/^[a-z][a-z0-9_]*$/.test(name) || name.length > 100) {
+        console.error("\n  Error: Query name must start with a lowercase letter and contain only lowercase letters, numbers, and underscores.\n");
+        process.exit(1);
+    }
+    const { dashboardSlug } = loadEnv();
+    const data = (await apiRequest("POST", `/api/dashboards/${dashboardSlug}/queries`, { query_name: name, sql_text: resolvedSql }));
+    console.log(`\n  Query "${data.query_name}" created.\n`);
+    console.log(`  Use it in your dashboard:`);
+    console.log(`    const { data } = useQuery("${data.query_name}");\n`);
+}
+async function queryUpdate(name, sql) {
+    const resolvedSql = resolveSql(sql);
+    if (!name || !resolvedSql) {
+        console.error('\n  Usage: npx overscore query update <name> "<sql>"\n');
+        console.error("  Or with a file:");
+        console.error("    npx overscore query update <name> --file query.sql\n");
+        process.exit(1);
+    }
+    const { dashboardSlug } = loadEnv();
+    const data = (await apiRequest("PUT", `/api/dashboards/${dashboardSlug}/queries/${encodeURIComponent(name)}`, { sql_text: resolvedSql }));
+    console.log(`\n  Query "${data.query_name}" updated.`);
+    console.log("  Cache has been invalidated — fresh data on next load.\n");
+}
+async function queryRemove(name) {
+    if (!name) {
+        console.error("\n  Usage: npx overscore query remove <name>\n");
+        process.exit(1);
+    }
+    const yes = await confirm(`Delete query "${name}"? This cannot be undone.`);
+    if (!yes) {
+        console.log("  Cancelled.\n");
+        return;
+    }
+    const { dashboardSlug } = loadEnv();
+    await apiRequest("DELETE", `/api/dashboards/${dashboardSlug}/queries/${encodeURIComponent(name)}`);
+    console.log(`\n  Query "${name}" deleted.\n`);
+}
+async function queryTest(sql) {
+    if (!sql) {
+        console.error('\n  Usage: npx overscore query test "<sql>"\n');
+        console.error("  Example:");
+        console.error('    npx overscore query test "SELECT * FROM dataset.table LIMIT 10"\n');
+        process.exit(1);
+    }
+    const { dashboardSlug } = loadEnv();
+    const data = (await apiRequest("POST", `/api/dashboards/${dashboardSlug}/test-query`, { sql }));
+    console.log(`\n  ${data.row_count} rows returned${data.truncated ? " (showing first 200)" : ""}\n`);
+    if (data.data.length === 0) {
+        console.log("  No rows.\n");
+        return;
+    }
+    // Print first 10 rows as a simple table
+    const rows = data.data.slice(0, 10);
+    const cols = Object.keys(rows[0]);
+    // Calculate column widths
+    const widths = cols.map((col) => {
+        const values = rows.map((r) => formatCell(r[col]));
+        return Math.max(col.length, ...values.map((v) => v.length));
+    });
+    // Header
+    const header = cols.map((col, i) => col.padEnd(widths[i])).join("  ");
+    const divider = cols.map((_, i) => "─".repeat(widths[i])).join("──");
+    console.log(`  ${header}`);
+    console.log(`  ${divider}`);
+    // Rows
+    for (const row of rows) {
+        const line = cols
+            .map((col, i) => formatCell(row[col]).padEnd(widths[i]))
+            .join("  ");
+        console.log(`  ${line}`);
+    }
+    if (data.data.length > 10) {
+        console.log(`\n  ... and ${data.data.length - 10} more rows`);
+    }
+    console.log();
+}
+function formatCell(value) {
+    if (value === null || value === undefined)
+        return "—";
+    if (typeof value === "object" && value !== null && "value" in value) {
+        return String(value.value);
+    }
+    if (typeof value === "number")
+        return value.toLocaleString();
+    return String(value);
+}
+async function pull(slug) {
+    if (!slug) {
+        console.error("\n  Usage: npx overscore pull <dashboard-slug> [--version N]\n");
+        console.error("  Example:");
+        console.error("    npx overscore pull my-dashboard\n");
+        process.exit(1);
+    }
+    // Parse --version flag
+    const versionIndex = process.argv.indexOf("--version");
+    const versionParam = versionIndex !== -1 && process.argv[versionIndex + 1]
+        ? process.argv[versionIndex + 1]
+        : null;
+    // Interactive prompts for credentials
+    const apiKey = await prompt("API key (from the Hub):");
+    if (!apiKey || !apiKey.startsWith("os_")) {
+        console.error("\n  Error: API key should start with os_\n");
+        process.exit(1);
+    }
+    const apiUrl = "https://overscore.dev/api";
+    const baseUrl = apiUrl.replace(/\/api$/, "");
+    const versionQuery = versionParam ? `?version=${versionParam}` : "";
+    const url = `${baseUrl}/api/dashboards/${slug}/source${versionQuery}`;
+    console.log(`\n  Pulling source for: ${slug}${versionParam ? ` (v${versionParam})` : ""}...`);
+    const res = await fetch(url, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok) {
+        let errorMsg = `HTTP ${res.status}`;
+        try {
+            const body = await res.json();
+            errorMsg = body.error || errorMsg;
+        }
+        catch {
+            // not JSON
+        }
+        console.error(`\n  Error: ${errorMsg}\n`);
+        process.exit(1);
+    }
+    const projectSlug = res.headers.get("X-VD-Project-Slug") || "";
+    const dashboardSlug = res.headers.get("X-VD-Dashboard-Slug") || slug;
+    const version = res.headers.get("X-VD-Version") || "?";
+    const commitMsg = res.headers.get("X-VD-Commit-Message") || "";
+    // Download the zip
+    const zipBuffer = Buffer.from(await res.arrayBuffer());
+    // Extract to ./<slug>/
+    const targetDir = path.resolve(process.cwd(), slug);
+    if (fs.existsSync(targetDir)) {
+        const yes = await confirm(`Directory "${slug}" already exists. Overwrite source files?`);
+        if (!yes) {
+            console.log("  Cancelled.\n");
+            return;
+        }
+    }
+    // Clean target directory (preserve node_modules and .env)
+    if (fs.existsSync(targetDir)) {
+        for (const entry of fs.readdirSync(targetDir)) {
+            if (entry === "node_modules" || entry.startsWith(".env"))
+                continue;
+            const entryPath = path.join(targetDir, entry);
+            fs.rmSync(entryPath, { recursive: true, force: true });
+        }
+    }
+    else {
+        fs.mkdirSync(targetDir, { recursive: true });
+    }
+    await extractZip(zipBuffer, targetDir);
+    // Generate .env (only overscore config — user adds their own API keys)
+    const envContent = `# Overscore Configuration
+VITE_OVERSCORE_PROJECT_SLUG=${projectSlug}
+VITE_OVERSCORE_DASHBOARD_SLUG=${dashboardSlug}
+VITE_OVERSCORE_API_KEY=${apiKey}
+VITE_OVERSCORE_API_URL=https://overscore.dev/api
+`;
+    fs.writeFileSync(path.join(targetDir, ".env"), envContent, { mode: 0o600 });
+    // Fetch latest project context from Hub (may be newer than what's in the source zip)
+    try {
+        const ctxRes = await fetch(`${baseUrl}/api/projects/${projectSlug}/context`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (ctxRes.ok) {
+            const ctxData = (await ctxRes.json());
+            if (ctxData.context_md) {
+                const rulesDir = path.join(targetDir, ".claude", "rules");
+                fs.mkdirSync(rulesDir, { recursive: true });
+                fs.writeFileSync(path.join(rulesDir, "company-context.md"), ctxData.context_md);
+                // Store hash for conflict detection on next deploy
+                if (ctxData.context_md_hash) {
+                    fs.writeFileSync(path.join(rulesDir, ".context-hash"), ctxData.context_md_hash);
+                }
+                console.log("  Updated company context from Hub.");
+            }
+        }
+    }
+    catch {
+        // Non-fatal — the version from the source zip is fine
+    }
+    console.log(`
+  Pulled v${version}${commitMsg ? ` — "${commitMsg}"` : ""}
+
+  Next steps:
+
+    cd ${slug}
+    npm install
+    code .
+    claude
+
+  Note: If this dashboard uses third-party APIs, add your
+  API keys to .env before running.
+
+  When ready to deploy:
+
+    npx overscore deploy --message "your changes"
+`);
+}
+async function versions() {
+    const { dashboardSlug } = loadEnv();
+    const data = (await apiRequest("GET", `/api/dashboards/${dashboardSlug}/versions`));
+    console.log(`\n  Dashboard: ${dashboardSlug}\n`);
+    if (data.versions.length === 0) {
+        console.log("  No deployments yet.\n");
+        return;
+    }
+    for (const v of data.versions) {
+        const date = new Date(v.deployed_at).toLocaleDateString("en-US", {
+            month: "short",
+            day: "numeric",
+            year: "numeric",
+        });
+        const size = v.bundle_size_bytes >= 1024 * 1024
+            ? `${(v.bundle_size_bytes / 1024 / 1024).toFixed(1)} MB`
+            : `${Math.round(v.bundle_size_bytes / 1024)} KB`;
+        const source = v.source_available ? "\u2713 source" : "\u2717 source";
+        const msg = v.commit_message ? `  "${v.commit_message}"` : "";
+        const by = v.deployed_by ? `  by ${v.deployed_by}` : "";
+        console.log(`  v${v.version_number}  ${date}  ${v.file_count} files  ${size}  ${source}${msg}${by}`);
+    }
+    console.log(`\n  Pull a version: npx overscore pull ${dashboardSlug} --version N\n`);
+}
+async function listDashboards() {
+    const { apiUrl, apiKey } = loadEnv();
+    const baseUrl = apiUrl.replace(/\/api$/, "");
+    const res = await fetch(`${baseUrl}/api/dashboards`, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        console.error(`\n  Error: ${body.error || `HTTP ${res.status}`}\n`);
+        process.exit(1);
+    }
+    const data = (await res.json());
+    console.log(`\n  ${data.project} (${data.project_slug})\n`);
+    if (data.dashboards.length === 0) {
+        console.log("  No dashboards yet.\n");
+        return;
+    }
+    for (const d of data.dashboards) {
+        const version = d.latest_version;
+        const deployed = version
+            ? `v${version.version_number} · ${new Date(version.deployed_at).toLocaleDateString("en-US", { month: "short", day: "numeric" })}`
+            : "not deployed";
+        const queries = d.query_count === 1 ? "1 query" : `${d.query_count} queries`;
+        console.log(`  ${d.name}`);
+        console.log(`    slug: ${d.slug}  ·  ${queries}  ·  ${deployed}`);
+        if (version?.commit_message) {
+            console.log(`    "${version.commit_message}"`);
+        }
+        console.log();
+    }
+}
+function collectFiles(dir, prefix) {
+    const files = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            files.push(...collectFiles(path.join(dir, entry.name), relativePath));
+        }
+        else {
+            files.push(relativePath);
+        }
+    }
+    return files;
+}
+// ── Routing ─────────────────────────────────────────────────────────
+const command = process.argv[2];
+const subcommand = process.argv[3];
+if (command === "deploy") {
+    deploy();
+}
+else if (command === "pull") {
+    pull(process.argv[3]);
+}
+else if (command === "versions") {
+    versions();
+}
+else if (command === "list") {
+    listDashboards();
+}
+else if (command === "query") {
+    if (subcommand === "list") {
+        queryList();
+    }
+    else if (subcommand === "show") {
+        queryShow(process.argv[4]);
+    }
+    else if (subcommand === "add") {
+        queryAdd(process.argv[4], process.argv[5]);
+    }
+    else if (subcommand === "update") {
+        queryUpdate(process.argv[4], process.argv[5]);
+    }
+    else if (subcommand === "remove") {
+        queryRemove(process.argv[4]);
+    }
+    else if (subcommand === "test") {
+        queryTest(process.argv[4]);
+    }
+    else {
+        console.log(`
+  overscore query — Manage dashboard queries
+
+  Commands:
+    list                     List all queries
+    show <name>              Show a query's SQL and sample data
+    add <name> "<sql>"       Add a new query
+    update <name> "<sql>"    Update a query's SQL
+    remove <name>            Delete a query
+    test "<sql>"             Test SQL without saving
+
+  Examples:
+    npx overscore query list
+    npx overscore query show monthly_revenue
+    npx overscore query add monthly_revenue --file queries/revenue.sql
+    npx overscore query add monthly_revenue "SELECT ..."
+    npx overscore query update monthly_revenue --file queries/revenue.sql
+    npx overscore query test "SELECT * FROM dataset.table LIMIT 10"
+`);
+    }
+}
+else {
+    console.log(`
+  overscore — Overscore CLI
+
+  Commands:
+    list                List all dashboards in the project
+    deploy              Build and deploy the dashboard
+    pull <slug>         Pull source code from the hub
+    versions            List deploy history
+    query <subcommand>  Manage dashboard queries
+
+  Usage:
+    npx overscore list
+    npx overscore deploy --message "description"
+    npx overscore pull <slug>
+    npx overscore pull <slug> --version 3
+    npx overscore versions
+    npx overscore query list
+    npx overscore query add <name> "<sql>"
+    npx overscore query update <name> "<sql>"
+    npx overscore query remove <name>
+    npx overscore query test "<sql>"
+`);
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@overscore/cli",
+  "version": "0.6.0",
+  "description": "CLI for deploying Overscore dashboards",
+  "bin": {
+    "overscore": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@types/yauzl": "^2.10.3",
+    "yauzl": "^3.3.0"
+  }
+}