@overscore/cli 0.9.13 → 0.10.0

package/dist/index.js

@@ -47,7 +47,29 @@ function loadEnv() {
             };
         }
     }
-    console.error("  Error: No credentials found. Run 'npx @overscore/cli auth login' to set up.");
+    // No creds. Tailor the message based on what kind of folder we're in so the
+    // user gets pointed at the right setup command.
+    const inAnalysisFolder = fs.existsSync(path.resolve(process.cwd(), ".overscore", "analysis.json"));
+    if (inAnalysisFolder) {
+        let analysisSlug = null;
+        try {
+            const meta = JSON.parse(fs.readFileSync(path.resolve(process.cwd(), ".overscore", "analysis.json"), "utf-8"));
+            analysisSlug = typeof meta.slug === "string" ? meta.slug : null;
+        }
+        catch {
+            // Fall through to the generic message.
+        }
+        console.error("\n  Error: No credentials found in this analysis folder.");
+        console.error("  This usually means the analysis hasn't been linked to your account yet.");
+        console.error("  Run:");
+        console.error(`    npx @overscore/cli analysis pull ${analysisSlug || "<slug>"}`);
+        console.error("  to refresh credentials and link this folder, or:");
+        console.error("    npx @overscore/cli auth login");
+        console.error("  if you've never set up the CLI on this machine.\n");
+    }
+    else {
+        console.error("\n  Error: No credentials found. Run 'npx @overscore/cli auth login' to set up.\n");
+    }
     process.exit(1);
 }
 async function apiRequest(method, urlPath, body) {
@@ -423,6 +445,14 @@ function saveQueryResult(sql, data) {
             .slice(0, 40);
         const filename = `${hash}_${snippet}.json`;
         const dataDir = path.resolve(process.cwd(), "data");
+        const fullPath = path.join(dataDir, filename);
+        const relPath = `data/${filename}`;
+        // Hash is content-derived from the SQL — if a file with this hash already
+        // exists, the exact same query was run before. Skip the rewrite so the
+        // data/ folder doesn't accumulate duplicates of identical queries.
+        if (fs.existsSync(fullPath)) {
+            return { path: relPath, cached: true };
+        }
         if (!fs.existsSync(dataDir)) {
             fs.mkdirSync(dataDir, { recursive: true });
         }
@@ -434,27 +464,53 @@ function saveQueryResult(sql, data) {
             columns: data.data.length > 0 ? Object.keys(data.data[0]) : [],
             data: data.data,
         };
-        fs.writeFileSync(path.join(dataDir, filename), JSON.stringify(payload, null, 2));
-        return `data/${filename}`;
+        fs.writeFileSync(fullPath, JSON.stringify(payload, null, 2));
+        return { path: relPath, cached: false };
     }
     catch {
         return null;
     }
 }
 async function queryTest(sql) {
-    if (!sql) {
-        console.error('\n  Usage: npx @overscore/cli query test "<sql>"\n');
-        console.error("  Example:");
-        console.error('    npx @overscore/cli query test "SELECT * FROM dataset.table LIMIT 10"\n');
+    const resolvedSql = resolveSql(sql);
+    if (!resolvedSql) {
+        console.error('\n  Usage: npx @overscore/cli query run "<sql>"\n');
+        console.error("  Or with a file:");
+        console.error("    npx @overscore/cli query run --file queries/foo.sql\n");
         process.exit(1);
     }
     const { projectSlug } = loadEnv();
-    const data = (await apiRequest("POST", `/api/projects/${projectSlug}/test-query`, { sql }));
-    const savedPath = saveQueryResult(sql, data);
+    if (!projectSlug) {
+        const analysisMetaPath = path.resolve(process.cwd(), ".overscore", "analysis.json");
+        if (fs.existsSync(analysisMetaPath)) {
+            let slug = "<slug>";
+            try {
+                const meta = JSON.parse(fs.readFileSync(analysisMetaPath, "utf-8"));
+                if (typeof meta.slug === "string")
+                    slug = meta.slug;
+            }
+            catch {
+                // ignore
+            }
+            console.error("\n  Error: This analysis folder isn't linked to a project yet.");
+            console.error(`  Run: npx @overscore/cli analysis pull ${slug}\n`);
+        }
+        else {
+            console.error("\n  Error: No project slug configured. Run 'npx @overscore/cli auth login' to set one up.\n");
+        }
+        process.exit(1);
+    }
+    const data = (await apiRequest("POST", `/api/projects/${projectSlug}/test-query`, { sql: resolvedSql }));
+    const saved = saveQueryResult(resolvedSql, data);
+    const savedLine = saved
+        ? saved.cached
+            ? `  Cached (already saved earlier): ${saved.path}`
+            : `  Saved to ${saved.path}`
+        : null;
     console.log(`\n  ${data.row_count} rows returned${data.truncated ? " (showing first 200)" : ""}\n`);
     if (data.data.length === 0) {
-        if (savedPath)
-            console.log(`  Saved to ${savedPath}\n`);
+        if (savedLine)
+            console.log(`${savedLine}\n`);
         console.log("  No rows.\n");
         return;
     }
@@ -481,8 +537,8 @@ async function queryTest(sql) {
     if (data.data.length > 10) {
         console.log(`\n  ... and ${data.data.length - 10} more rows`);
     }
-    if (savedPath)
-        console.log(`\n  Saved to ${savedPath}`);
+    if (savedLine)
+        console.log(`\n${savedLine}`);
     console.log();
 }
 function formatCell(value) {
@@ -913,18 +969,22 @@ function scaffoldFromTemplate(templateDir, targetDir, substitutions) {
         }
         return out;
     }
+    const TEMPLATE_RENAMES = {
+        _gitignore: ".gitignore",
+        _overscoreignore: ".overscoreignore",
+    };
     function walk(srcDir, destDir) {
         fs.mkdirSync(destDir, { recursive: true });
         for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
             const srcPath = path.join(srcDir, entry.name);
-            const destName = entry.name === "_gitignore" ? ".gitignore" : entry.name;
+            const destName = TEMPLATE_RENAMES[entry.name] || entry.name;
             const destPath = path.join(destDir, destName);
             if (entry.isDirectory()) {
                 walk(srcPath, destPath);
             }
             else if (entry.isFile()) {
                 const ext = path.extname(entry.name).toLowerCase();
-                if (TEXT_EXTENSIONS.has(ext) || entry.name === "_gitignore") {
+                if (TEXT_EXTENSIONS.has(ext) || TEMPLATE_RENAMES[entry.name]) {
                     const content = fs.readFileSync(srcPath, "utf8");
                     fs.writeFileSync(destPath, substitute(content));
                 }
@@ -1011,23 +1071,77 @@ function loadAnalysisMetadata() {
     }
     return JSON.parse(fs.readFileSync(metaPath, "utf-8"));
 }
-const ANALYSIS_PUBLISH_EXCLUDE = new Set([
+// Always-excluded names — these can never be published regardless of
+// .overscoreignore, so secrets and machine-state can't accidentally ship.
+const ANALYSIS_PUBLISH_BASELINE_EXCLUDE = new Set([
     "node_modules",
     ".git",
     ".DS_Store",
-    ".env",
-    "data",
+    ".overscore",
 ]);
-function collectAnalysisFiles(dir, prefix) {
+function isBaselineExcluded(name) {
+    if (ANALYSIS_PUBLISH_BASELINE_EXCLUDE.has(name))
+        return true;
+    if (name.startsWith(".env"))
+        return true;
+    return false;
+}
+function compileIgnorePattern(raw) {
+    let pattern = raw.trim();
+    if (!pattern || pattern.startsWith("#"))
+        return null;
+    const dirOnly = pattern.endsWith("/");
+    if (dirOnly)
+        pattern = pattern.slice(0, -1);
+    // Escape regex specials except for `*`, then turn `*` into `[^/]*`.
+    const escaped = pattern
+        .split("*")
+        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join("[^/]*");
+    // Anchor to either a full path match or a path that has the pattern as a
+    // path segment somewhere (so `data/` matches `data/foo.json` and `*.email.html`
+    // matches `emails/x.email.html`).
+    const regex = new RegExp(`(^|/)${escaped}(/|$)`);
+    return { raw, regex, dirOnly };
+}
+function loadOverscoreIgnore(dir) {
+    const ignorePath = path.join(dir, ".overscoreignore");
+    if (!fs.existsSync(ignorePath))
+        return [];
+    const content = fs.readFileSync(ignorePath, "utf-8");
+    const patterns = [];
+    for (const line of content.split("\n")) {
+        const compiled = compileIgnorePattern(line);
+        if (compiled)
+            patterns.push(compiled);
+    }
+    return patterns;
+}
+function isIgnored(relativePath, isDirectory, patterns) {
+    for (const p of patterns) {
+        if (p.dirOnly && !isDirectory) {
+            // Directory-only pattern can still match a file *inside* the directory.
+            // The regex handles that case for paths like `data/foo.json`.
+            if (p.regex.test(relativePath))
+                return true;
+        }
+        else if (p.regex.test(relativePath)) {
+            return true;
+        }
+    }
+    return false;
+}
+function collectAnalysisFiles(dir, prefix, patterns) {
+    const userPatterns = patterns ?? loadOverscoreIgnore(dir);
     const files = [];
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-        if (ANALYSIS_PUBLISH_EXCLUDE.has(entry.name))
-            continue;
-        if (entry.name.startsWith(".env"))
+        if (isBaselineExcluded(entry.name))
             continue;
         const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (isIgnored(relativePath, entry.isDirectory(), userPatterns))
+            continue;
         if (entry.isDirectory()) {
-            files.push(...collectAnalysisFiles(path.join(dir, entry.name), relativePath));
+            files.push(...collectAnalysisFiles(path.join(dir, entry.name), relativePath, userPatterns));
         }
         else {
             files.push(relativePath);
@@ -1035,7 +1149,61 @@ function collectAnalysisFiles(dir, prefix) {
     }
     return files;
 }
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+function summarizeFiles(files, baseDir) {
+    const groupMap = new Map();
+    let totalBytes = 0;
+    for (const rel of files) {
+        const fullPath = path.join(baseDir, rel);
+        let size = 0;
+        try {
+            size = fs.statSync(fullPath).size;
+        }
+        catch {
+            // skip stat failures, count as 0
+        }
+        totalBytes += size;
+        const segments = rel.split("/");
+        const group = segments.length > 1 ? segments[0] + "/" : "(root)";
+        let entry = groupMap.get(group);
+        if (!entry) {
+            entry = { group, files: [], totalBytes: 0 };
+            groupMap.set(group, entry);
+        }
+        entry.files.push({ path: rel, size });
+        entry.totalBytes += size;
+    }
+    // Sort groups: (root) first, then alphabetical
+    const groups = Array.from(groupMap.values()).sort((a, b) => {
+        if (a.group === "(root)")
+            return -1;
+        if (b.group === "(root)")
+            return 1;
+        return a.group.localeCompare(b.group);
+    });
+    return { groups, totalFiles: files.length, totalBytes };
+}
+function printBundleSummary(files, baseDir, opts = {}) {
+    const { groups, totalFiles, totalBytes } = summarizeFiles(files, baseDir);
+    for (const group of groups) {
+        const fileWord = group.files.length === 1 ? "file" : "files";
+        console.log(`    ${group.group}  ${group.files.length} ${fileWord}, ${formatBytes(group.totalBytes)}`);
+        if (opts.verbose) {
+            for (const f of group.files) {
+                console.log(`      ${f.path}  (${formatBytes(f.size)})`);
+            }
+        }
+    }
+    console.log(`    ${"─".repeat(20)}\n    Total: ${totalFiles} files, ${formatBytes(totalBytes)}`);
+}
 async function analysisPublish() {
+    const dryRun = process.argv.includes("--dry-run") || process.argv.includes("--preview");
     const meta = loadAnalysisMetadata();
     if (!meta.project_slug) {
         console.error("\n  Error: analysis.json has no project_slug. Check .overscore/analysis.json.\n");
@@ -1045,6 +1213,27 @@ async function analysisPublish() {
         console.error("\n  Error: analysis.json has no slug. Check .overscore/analysis.json.\n");
         process.exit(1);
     }
+    const reportPath = path.resolve(process.cwd(), "report.html");
+    if (!fs.existsSync(reportPath)) {
+        console.error("\n  Error: report.html not found in this folder. Generate it before publishing.\n");
+        process.exit(1);
+    }
+    const reportContent = fs.readFileSync(reportPath, "utf-8");
+    if (reportContent.includes("This analysis is empty")) {
+        console.error("\n  Error: report.html still has placeholder content. Generate the report before publishing.\n");
+        process.exit(1);
+    }
+    // Dry-run: print what would be uploaded, then exit. No network, no auth.
+    if (dryRun) {
+        const files = collectAnalysisFiles(process.cwd(), "");
+        console.log(`\n  Dry run — these files would be uploaded for "${meta.title}":\n`);
+        printBundleSummary(files, process.cwd(), { verbose: true });
+        console.log(`
+  Excluded by .overscoreignore + baseline (.git, node_modules, .env*, .overscore/, .DS_Store).
+  No upload made. Re-run without --dry-run to publish.
+`);
+        return;
+    }
     const cfg = await loadAnalysisConfig();
     // Resolve missing id from the Hub before giving up
     if (!meta.id) {
@@ -1058,16 +1247,6 @@ async function analysisPublish() {
         }
         meta.id = refreshed.id;
     }
-    const reportPath = path.resolve(process.cwd(), "report.html");
-    if (!fs.existsSync(reportPath)) {
-        console.error("\n  Error: report.html not found in this folder. Generate it before publishing.\n");
-        process.exit(1);
-    }
-    const reportContent = fs.readFileSync(reportPath, "utf-8");
-    if (reportContent.includes("This analysis is empty")) {
-        console.error("\n  Error: report.html still has placeholder content. Generate the report before publishing.\n");
-        process.exit(1);
-    }
     console.log(`\n  Publishing analysis: ${meta.title}\n`);
     const files = collectAnalysisFiles(process.cwd(), "");
     console.log(`  Bundling ${files.length} files...`);
@@ -1091,12 +1270,9 @@ async function analysisPublish() {
         console.error(`\n  Publish failed: ${data.error}\n`);
         process.exit(1);
     }
-    console.log(`
-  Published successfully!
-
-  ${data.file_count} files uploaded
-  URL: ${data.url}
-`);
+    console.log(`\n  Published successfully!\n`);
+    printBundleSummary(files, process.cwd());
+    console.log(`\n    URL: ${data.url}\n`);
 }
 /**
  * Ensure analysis.json has a valid id by fetching from the Hub.
@@ -1123,13 +1299,38 @@ async function ensureAnalysisId(targetDir, cfg, slug) {
         // Non-fatal
     }
 }
+/**
+ * Detect if CWD is already an analysis folder matching the given slug.
+ * Returns the in-place target dir if so, or a new sibling dir otherwise.
+ */
+function resolvePullTarget(slug) {
+    const localMetaPath = path.resolve(process.cwd(), ".overscore", "analysis.json");
+    if (fs.existsSync(localMetaPath)) {
+        try {
+            const localMeta = JSON.parse(fs.readFileSync(localMetaPath, "utf-8"));
+            if (localMeta.slug === slug) {
+                return { targetDir: process.cwd(), inPlace: true };
+            }
+        }
+        catch {
+            // ignore parse errors
+        }
+    }
+    return { targetDir: path.resolve(process.cwd(), slug), inPlace: false };
+}
 async function analysisPull(slug) {
     if (!slug) {
         console.error("\n  Usage: npx @overscore/cli analysis pull <slug>\n");
         process.exit(1);
     }
     const cfg = await loadAnalysisConfig();
-    console.log(`\n  Pulling analysis: ${slug}...`);
+    const { targetDir: resolvedTarget, inPlace } = resolvePullTarget(slug);
+    if (inPlace) {
+        console.log(`\n  Pulling analysis: ${slug} (refreshing in place)...`);
+    }
+    else {
+        console.log(`\n  Pulling analysis: ${slug}...`);
+    }
     const baseUrl = cfg.apiUrl.replace(/\/api$/, "");
     const res = await fetch(`${baseUrl}/api/projects/${cfg.projectSlug}/analyses/${slug}/source`, {
         headers: { Authorization: `Bearer ${cfg.apiKey}` },
@@ -1150,6 +1351,19 @@ async function analysisPull(slug) {
         // If the analysis exists but hasn't been published yet, scaffold from
         // the template instead of trying to download a bundle that doesn't exist.
         if (isUnpublished) {
+            const targetDir = resolvedTarget;
+            if (inPlace) {
+                // In-place refresh: only update metadata and hub-managed rules
+                const baseUrl = cfg.apiUrl.replace(/\/api$/, "");
+                await syncHubManagedRules(targetDir, baseUrl, cfg.projectSlug, cfg.apiKey);
+                await ensureAnalysisId(targetDir, cfg, slug);
+                console.log(`  Refreshed in place (not yet published).
+
+  Updated: hub-managed rules, analysis metadata/id.
+  Untouched: report.html, analysis-log.md, data/, and all other local files.
+`);
+                return;
+            }
             console.log("  Not yet published — scaffolding from template...\n");
             const distDir = path.dirname(new URL(import.meta.url).pathname);
             const pkgRoot = path.resolve(distDir, "..");
@@ -1160,7 +1374,6 @@ async function analysisPull(slug) {
             }
             // Fetch analysis metadata from the Hub
             const metaRes = await analysisApiRequest(cfg, "GET", `/api/projects/${cfg.projectSlug}/analyses/${slug}/meta`).catch(() => null);
-            const targetDir = path.resolve(process.cwd(), slug);
             if (fs.existsSync(targetDir)) {
                 const yes = await confirm(`Directory "${slug}" already exists. Overwrite?`);
                 if (!yes) {
@@ -1190,8 +1403,6 @@ async function analysisPull(slug) {
             const baseUrl = cfg.apiUrl.replace(/\/api$/, "");
             await syncHubManagedRules(targetDir, baseUrl, cfg.projectSlug, cfg.apiKey);
             await ensureAnalysisId(targetDir, cfg, slug);
-            // Don't sync dashboard platform rules into analysis folders —
-            // analyses have their own rules in the template (sql-style, report-html, etc.)
             console.log(`  Scaffolded "${title}"
 
   Next steps:
@@ -1212,7 +1423,19 @@ async function analysisPull(slug) {
     // Verify we got a zip back (not an HTML redirect or JSON error)
     const contentType = res.headers.get("Content-Type") || "";
     if (!contentType.includes("zip") && !contentType.includes("octet-stream")) {
-        // Probably an auth redirect or error page — treat as unpublished and scaffold
+        // Probably an auth redirect or error page — treat as unpublished
+        const targetDir = resolvedTarget;
+        if (inPlace) {
+            const baseUrl = cfg.apiUrl.replace(/\/api$/, "");
+            await syncHubManagedRules(targetDir, baseUrl, cfg.projectSlug, cfg.apiKey);
+            await ensureAnalysisId(targetDir, cfg, slug);
+            console.log(`  Refreshed in place.
+
+  Updated: hub-managed rules, analysis metadata/id.
+  Untouched: report.html, analysis-log.md, data/, and all other local files.
+`);
+            return;
+        }
         console.log("  No published bundle found — scaffolding from template...\n");
         const distDir = path.dirname(new URL(import.meta.url).pathname);
         const pkgRoot = path.resolve(distDir, "..");
@@ -1221,7 +1444,6 @@ async function analysisPull(slug) {
             console.error(`\n  Error: Bundled analysis template not found.\n`);
             process.exit(1);
         }
-        const targetDir = path.resolve(process.cwd(), slug);
         if (fs.existsSync(targetDir)) {
             const yes = await confirm(`Directory "${slug}" already exists. Overwrite?`);
             if (!yes) {
@@ -1243,7 +1465,6 @@ async function analysisPull(slug) {
         const baseUrl = cfg.apiUrl.replace(/\/api$/, "");
         await syncHubManagedRules(targetDir, baseUrl, cfg.projectSlug, cfg.apiKey);
         await ensureAnalysisId(targetDir, cfg, slug);
-        // Don't sync dashboard platform rules into analysis folders
         console.log(`  Scaffolded "${slug}"
 
   Next steps:
@@ -1261,40 +1482,74 @@ async function analysisPull(slug) {
     const analysisSlug = res.headers.get("X-OS-Analysis-Slug") || slug;
     const analysisTitle = res.headers.get("X-OS-Analysis-Title") || slug;
     const projectSlug = res.headers.get("X-OS-Project-Slug") || cfg.projectSlug;
-    const zipBuffer = Buffer.from(await res.arrayBuffer());
-    const targetDir = path.resolve(process.cwd(), analysisSlug);
-    if (fs.existsSync(targetDir)) {
-        const yes = await confirm(`Directory "${analysisSlug}" already exists. Overwrite?`);
-        if (!yes) {
-            console.log("  Cancelled.\n");
-            return;
-        }
-        fs.rmSync(targetDir, { recursive: true, force: true });
+    const targetDir = resolvedTarget;
+    if (inPlace) {
+        // In-place refresh: only update metadata and hub-managed rules.
+        // Never overwrite user content (report.html, analysis-log.md, data/, etc.)
+        await syncHubManagedRules(targetDir, baseUrl, projectSlug, cfg.apiKey);
+        await ensureAnalysisId(targetDir, cfg, analysisSlug);
+        console.log(`
+  Refreshed "${analysisTitle}" in place.
+
+  Updated: hub-managed rules, analysis metadata/id.
+  Untouched: report.html, analysis-log.md, data/, and all other local files.
+`);
     }
-    fs.mkdirSync(targetDir, { recursive: true });
-    await extractZip(zipBuffer, targetDir);
-    // Make sure analysis.json reflects the current project (in case the user
-    // pulled into a different machine where their default project is different)
-    const metaPath = path.join(targetDir, ".overscore", "analysis.json");
-    if (fs.existsSync(metaPath)) {
+    else {
+        const zipBuffer = Buffer.from(await res.arrayBuffer());
+        if (fs.existsSync(targetDir)) {
+            const yes = await confirm(`Directory "${analysisSlug}" already exists. Overwrite?`);
+            if (!yes) {
+                console.log("  Cancelled.\n");
+                return;
+            }
+            fs.rmSync(targetDir, { recursive: true, force: true });
+        }
+        fs.mkdirSync(targetDir, { recursive: true });
+        await extractZip(zipBuffer, targetDir);
+        // Make sure analysis.json reflects the current project (in case the user
+        // pulled into a different machine where their default project is different)
+        const metaPath = path.join(targetDir, ".overscore", "analysis.json");
+        if (fs.existsSync(metaPath)) {
+            try {
+                const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+                meta.project_slug = projectSlug;
+                meta.slug = analysisSlug;
+                fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+            }
+            catch {
+                // Non-fatal
+            }
+        }
+        // Refresh hub-managed rule files after restoring from the bundle.
+        await syncHubManagedRules(targetDir, baseUrl, projectSlug, cfg.apiKey);
+        await ensureAnalysisId(targetDir, cfg, analysisSlug);
+    }
+    if (!inPlace) {
+        // Summarize what landed on disk so the user knows what they got.
+        let pulledFileCount = 0;
+        let pulledBytes = 0;
         try {
-            const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
-            meta.project_slug = projectSlug;
-            meta.slug = analysisSlug;
-            fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+            const pulledFiles = collectAnalysisFiles(targetDir, "");
+            pulledFileCount = pulledFiles.length;
+            for (const f of pulledFiles) {
+                try {
+                    pulledBytes += fs.statSync(path.join(targetDir, f)).size;
+                }
+                catch {
+                    // ignore
+                }
+            }
         }
         catch {
-            // Non-fatal
+            // collection failed — fall back to no summary
         }
-    }
-    // Refresh hub-managed rule files after restoring from the bundle. The
-    // bundle contains whatever was set at publish time; this overwrites them
-    // with the latest hub state so company context and SQL style stay in
-    // sync across pulls. Best-effort and non-fatal.
-    await syncHubManagedRules(targetDir, baseUrl, projectSlug, cfg.apiKey);
-    await ensureAnalysisId(targetDir, cfg, analysisSlug);
-    console.log(`
+        const sizeSummary = pulledFileCount > 0
+            ? `  Pulled into ./${analysisSlug} (${pulledFileCount} files, ${formatBytes(pulledBytes)})`
+            : `  Pulled into ./${analysisSlug}`;
+        console.log(`
   Pulled "${analysisTitle}"
+${sizeSummary}
 
   Next steps:
 
@@ -1308,6 +1563,29 @@ async function analysisPull(slug) {
 
     npx @overscore/cli analysis publish
 `);
+    }
+}
+function analysisPreview() {
+    const reportPath = path.resolve(process.cwd(), "report.html");
+    if (!fs.existsSync(reportPath)) {
+        console.error("\n  Error: report.html not found in this folder. Generate it before previewing.\n");
+        process.exit(1);
+    }
+    // Windows `start` needs an empty quoted title before the path arg
+    // (`start "" "C:\path\report.html"`), which is why we prefix it here.
+    const opener = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? 'start ""'
+            : "xdg-open";
+    try {
+        execSync(`${opener} "${reportPath}"`, { stdio: "inherit" });
+        console.log(`\n  Opened ${path.basename(reportPath)} in your default browser.\n`);
+    }
+    catch {
+        console.error(`\n  Error: couldn't run "${opener}". Open ${reportPath} manually.\n`);
+        process.exit(1);
+    }
 }
 // ── auth ────────────────────────────────────────────────────────────
 async function authStatus() {
@@ -1517,19 +1795,26 @@ else if (command === "analysis") {
     else if (subcommand === "pull") {
         analysisPull(process.argv[4]);
     }
+    else if (subcommand === "preview") {
+        analysisPreview();
+    }
     else {
         console.log(`
   overscore analysis — Manage Overscore Analyses (frozen investigations)
 
   Commands:
-    new "<title>"     Create a new analysis in the current directory
-    publish           Upload report.html + bundle from the current analysis folder
-    pull <slug>       Re-download an existing analysis bundle to continue working
+    new "<title>"            Create a new analysis in the current directory
+    publish                  Upload report.html + bundle from the current analysis folder
+    publish --dry-run        Print what would be uploaded without sending it
+    pull <slug>              Re-download an existing analysis bundle to continue working
+    preview                  Open report.html in your default browser
 
   Examples:
     npx @overscore/cli analysis new "Why did Q1 churn spike"
     npx @overscore/cli analysis publish
+    npx @overscore/cli analysis publish --dry-run
     npx @overscore/cli analysis pull why-did-q1-churn-spike
+    npx @overscore/cli analysis preview
 `);
     }
 }
@@ -1557,21 +1842,22 @@ else if (command === "query") {
   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
-    run "<sql>"              Run SQL against BigQuery
-    test "<sql>"             Alias for run
+    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
+    run "<sql>"                   Run SQL against BigQuery
+    run --file <path>             Run SQL from a file (e.g. queries/foo.sql)
+    test                          Alias for run
 
   Examples:
     npx @overscore/cli query list
     npx @overscore/cli query show monthly_revenue
     npx @overscore/cli query add monthly_revenue --file queries/revenue.sql
-    npx @overscore/cli query add monthly_revenue "SELECT ..."
     npx @overscore/cli query update monthly_revenue --file queries/revenue.sql
     npx @overscore/cli query run "SELECT * FROM dataset.table LIMIT 10"
+    npx @overscore/cli query run --file queries/q3-cohort-halo.sql
 `);
     }
 }
@@ -1602,9 +1888,12 @@ else {
     npx @overscore/cli query update <name> "<sql>"
     npx @overscore/cli query remove <name>
     npx @overscore/cli query run "<sql>"
+    npx @overscore/cli query run --file queries/foo.sql
     npx @overscore/cli analysis new "<title>"
     npx @overscore/cli analysis publish
+    npx @overscore/cli analysis publish --dry-run
     npx @overscore/cli analysis pull <slug>
+    npx @overscore/cli analysis preview
     npx @overscore/cli install-skills
 `);
 }

package/package.json

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

package/templates/analysis/.claude/CLAUDE.md

@@ -31,6 +31,12 @@ Use the Overscore CLI to run SQL against the project's BigQuery connection:
 npx @overscore/cli query run "SELECT col1, COUNT(*) FROM \`project.dataset.table\` WHERE date >= '2024-01-01' GROUP BY 1 LIMIT 100"
 ```
 
+For longer queries, write the SQL to a file in `queries/` and pass `--file`:
+
+```bash
+npx @overscore/cli query run --file queries/q3-cohort-halo.sql
+```
+
 The CLI authenticates via `~/.overscore/config` (set up on first use). Credentials are stored in the Hub — never hardcode them locally.
 
 **Rules for exploratory queries:**
@@ -39,7 +45,11 @@ The CLI authenticates via `~/.overscore/config` (set up on first use). Credentia
 - Pre-aggregate before pulling wide result sets
 - Do NOT use `query list`, `query add`, or `query show` — those are for dashboard registered queries, not analysis exploration
 
-**Previous query results are saved automatically.** Every `query run` saves the full result set to `data/` as a JSON file. Before re-running a query, check `data/` — the results may already be there from a previous session. Read them with standard file tools instead of re-querying BigQuery.
+**Previous query results are saved automatically.** Every `query run` saves the full result set to `data/` as a JSON file, keyed by a hash of the SQL. Re-running an identical query is a no-op — the CLI prints `Cached (already saved earlier): data/...` instead of writing a duplicate. Before re-running a query, check `data/` — the results may already be there from a previous session. Read them with standard file tools instead of re-querying BigQuery.
+
+## Saving final queries
+
+The `queries/` directory is for SQL files you want to keep around — the canonical version of each Q-numbered query in `analysis-log.md`, queries the user might want to re-run later, or anything you've iterated on enough to deserve a name. File names like `q3-cohort-halo.sql` cross-reference the Query Log. Exploratory one-offs don't need to live here; they're already saved as JSON in `data/`.
 
 ## Where data context lives
 
@@ -50,13 +60,20 @@ The CLI authenticates via `~/.overscore/config` (set up on first use). Credentia
 To preview the report at any point, open it in the browser:
 
 ```bash
-open report.html        # macOS
-start report.html       # Windows
-xdg-open report.html    # Linux
+npx @overscore/cli analysis preview
 ```
 
+(Or `open report.html` / `start report.html` / `xdg-open report.html` if the CLI isn't handy.)
+
 Preview early and often — don't write the entire report before checking the layout. Build section by section, previewing after each major addition.
 
+## If the user wants a share email or Slack message
+
+If the user asks for a copy-paste email or Slack summary of the analysis, write it to a file like `update-YYYY-MM-DD.email.html` in the analysis root. Two things to know:
+
+- **Email-safe HTML only.** Gmail and most clients strip `<style>` blocks — use inline styles on every element. No `<script>` (most clients block it). Keep layouts simple; complex things (multi-column) want `<table>` for cross-client compatibility.
+- **The `.email.html` suffix keeps it out of the published bundle.** It's matched by `.overscoreignore`, so iterating on email drafts won't pollute the public report.
+
 ## Publishing
 
 When the analysis is ready, **tell the user to run** (do not run it yourself without asking):

package/templates/analysis/.claude/rules/analysis-methodology.md

@@ -77,4 +77,8 @@ When starting `report.html`, read only the **Key Findings** section of `analysis
 
 ## Cached query results
 
-Every `query run` command saves its result to `data/{hash}_{snippet}.json`. At the start of a session, check `data/` for existing results before re-running queries — especially after a context reset or `analysis pull`. The JSON files contain the SQL, timestamp, columns, and full row data. Read them directly instead of re-querying BigQuery.
+Every `query run` command saves its result to `data/{hash}_{snippet}.json`. The hash is derived from the SQL string, so re-running an identical query is a no-op — the CLI prints `Cached (already saved earlier): data/...` instead of writing a duplicate. At the start of a session, check `data/` for existing results before re-running queries — especially after a context reset or `analysis pull`. The JSON files contain the SQL, timestamp, columns, and full row data. Read them directly instead of re-querying BigQuery.
+
+## Saving queries to disk
+
+For any query worth referencing later (each Q-numbered query in this log, queries the user might re-run, longer queries you've iterated on), save the SQL to `queries/qN-short-name.sql` and run it via `npx @overscore/cli query run --file queries/qN-short-name.sql`. The Query Log entry then just needs the file reference instead of a full SQL paste — it keeps the log readable and gives you a single source of truth to edit. Throwaway one-shot exploratory queries don't need a file; their JSON in `data/` is enough.

package/templates/analysis/_overscoreignore

@@ -0,0 +1,11 @@
+# Files matching these patterns are excluded from `analysis publish`.
+# Syntax: one pattern per line. `*` is a glob within a single path segment.
+# Trailing `/` matches a directory and everything inside it.
+# Lines starting with `#` are comments.
+#
+# A baseline set is always excluded regardless of this file:
+#   .git/, node_modules/, .DS_Store, .env*, .overscore/
+
+data/
+*.draft.html
+*.email.html