@gscdump/cli 3.7.0 → 4.0.0

package/README.md

@@ -28,13 +28,13 @@ gscdump auth login --mode local
 gscdump sites
 
 # Sync 90 days to the Store
-gscdump sync --site sc-domain:example.com --days 90 --tables pages,queries,page_queries,countries,dates
+gscdump sync --site example.com --days 90 --tables pages,queries,page_queries,countries,dates
 
 # Query the Store
-gscdump query --site sc-domain:example.com --dimensions page,query --limit 50
+gscdump query --site example.com --dimensions page,query --limit 50
 
 # Run an Analyzer
-gscdump analyze striking-distance --site sc-domain:example.com
+gscdump analyze striking-distance --site example.com
 
 # Start the MCP server
 gscdump mcp
@@ -44,7 +44,7 @@ gscdump mcp
 
 | Command | Description |
 |---|---|
-| `init` | Full setup (OAuth + dataDir; offers to write a `.env` for later use) |
+| `init` | Full setup (OAuth + dataDir; offers to write a `.env` for later use). `--mode cloud\|local` saves the auth mode. Without a terminal it never prompts |
 | `auth` | Manage authentication (`status`, `login`, `logout`, `refresh`) |
 | `bing` | Connect Bing, list sites, dump datasets, inspect URLs, and check hosted verification |
 | `config` | Manage CLI configuration (`show`, `set`, `unset`, `path`, `validate`) |
@@ -52,18 +52,17 @@ gscdump mcp
 | `sites [--owner-only] [--with-sitemaps]` | List available GSC sites |
 | `sites add <url>` / `sites delete <url> [--yes]` | Register or remove a Site in Search Console (add registers in unverified state) |
 | `sites verify-token <url> [--method]` / `sites verify <url> [--method]` | Get a verification token, then trigger ownership verification (META/FILE/DNS_TXT/DNS_CNAME/ANALYTICS/TAG_MANAGER) |
-| `sitemaps` | List, submit, or delete Google sitemaps; probe live URLs; read hosted snapshots (`current`, `history`, `membership`, `lastmod`, `export`) |
-| `inspect <url>` / `inspect batch [--concurrency]` | URL inspection (single URL or batch from file/stdin); renders Indexing Evidence, rich results, and AMP |
-| `indexing` | Notify Google about URL changes (`submit`, `remove`, `status`, `batch`, `batch-status`, `quota`); supports `--retries` |
-| `sync` | Sync GSC data to the local Parquet Store; `--retry-failed`, `--dry-run` |
-| `query` | Run a search analytics query (Store by default; `--live` hits GSC API). Filters: `--query`, `--page`, `--country`, `--device`, `--search-appearance`, `--type`, `--data-state`, `--aggregation-type`. `--explain` previews the request body; `--output -` writes to stdout. |
-| `dump` | Export from the Store to a directory (`--format parquet\|json\|ndjson\|csv`, `--tables`, `--all-sites`) |
-| `analyze <tool>` | Run an SEO Analyzer against the Store (`--live` for row-based against fresh API) |
-| `entities` | Snapshot URL inspections and indexing metadata into the local entity store |
+| `sitemaps` | List, submit, or delete Google sitemaps; probe live URLs; read hosted snapshots (`current`, `history`, `membership`, `lastmod`, `export`) with `--site` |
+| `inspect <url...> [--file]` | URL inspection for one or more URLs; renders Indexing Evidence, rich results, and AMP, and saves each result to the Store |
+| `indexing` | Notify Google about URL changes (`submit`, `remove`, `status`, `batch`, `batch-status`, `quota`); supports `--retries`. `indexing urls --status not_indexed` lists hosted URL Inspection results |
+| `sync` | Sync GSC data, sitemaps, and URL Inspection results to the local Store; `--inspect-limit`, `--max-calls`, `--all-sites`, `--no-sitemaps`, `--no-inspections`, `--retry-failed`, `--dry-run` |
+| `query` | Run a search analytics query (the Store when it covers the dates, see [Routing](#routing); `--live` hits GSC API). Filters: `--query`, `--page`, `--country`, `--device`, `--search-appearance`, `--type`, `--data-state`, `--aggregation-type`. `--explain` previews the request body; `--output -` writes to stdout. `--sql` runs DuckDB SQL over the Store views; `--schema` lists them. |
+| `dump` | Export the Store, inspections, sitemaps, and Bing data (`--format parquet\|csv\|json\|ndjson\|sqlite\|duckdb`, `--tables`, `--all-sites`, `--no-bing`). Every row has `site` and `search_type` |
+| `analyze <tool>` | Run an SEO Analyzer against the Store, or live when the Site has no Store data (`--live` forces live for row-based Analyzers) |
+| `entities` | Read saved URL inspections and snapshot indexing metadata into the local entity store |
 | `store stats` | Show row/byte counts per table and on-disk footprint |
 | `store compact` | Compact older data into weekly, monthly, and quarterly tiers (`--dry-run`) |
 | `store gc` | Delete orphaned objects past the grace window (`--dry-run`) |
-| `store export` | Export the live store to a single `.duckdb` file |
 | `store rm-site` / `store reset` | Delete one Site's data or reset the Store; inspect `--help` before use |
 | `store rollups rebuild` | Rebuild post-sync rollup tables |
 | `report <id>` / `report list` | Run or list Reports; `--explain` previews a plan |
@@ -85,7 +84,7 @@ gscdump auth status --json
 
 # Google uses the connection on gscdump.com
 gscdump sites --json
-gscdump query --live --site sc-domain:example.com --dimensions page
+gscdump query --live --site example.com --dimensions page
 
 # Connect Bing through gscdump.com, then read its data
 gscdump bing sites --json
@@ -117,6 +116,7 @@ If you change a saved API root, supply the API key explicitly.
 | Bing connection and CNAME verification | Uses `bing login`, `bing status`, and `bing verify` | Verify sites in Bing Webmaster Tools |
 | Hosted sitemap membership and history | Supported | Requires hosted authentication |
 | Store queries and exports | Reads the local Store | Reads the local Store |
+| Hosted sync progress | `status` and `sites` show it | Not available |
 
 Hosted Bing access follows the API's plan and preview access rules.
 `auth logout` removes the saved mode and saved Google and Bing credentials.
@@ -178,7 +178,7 @@ Bing Indexing Evidence preserves uncertainty and does not imply an indexed verdi
 
 ```bash
 # pages under /blog/ with brand mentions in the query
-gscdump query --live --site sc-domain:example.com \
+gscdump query --live --site example.com \
   --page '~/blog/' --query '~brand' --dimensions page,query
 ```
 
@@ -186,16 +186,64 @@ gscdump query --live --site sc-domain:example.com \
 Without saved values, queries use 1000 rows and JSON.
 Limits must be positive integers. Formats must be `json` or `csv`.
 
-`--start` and `--end` work independently. An omitted date keeps its default.
-Non-interactive queries default to 31 days ago through three days ago, using UTC dates.
+Without dates, a query reads the last 28 days that end on the newest synced day of the table it reads.
+With `--live`, the window ends three days ago, Pacific time: the newest final GSC date.
+`--start` alone runs to that end date. `--end` alone reads the 28 days that end on it.
 Dates must use `YYYY-MM-DD`, and `--start` cannot follow `--end`.
 
+`--page` accepts a path or a full URL. The Store compares paths, so `https://example.com/a` matches `/a`.
+Live queries expand a path to the Site's origin. For a domain property, a path matches that path on any host.
+Filtered dimensions choose the Store table too: `-d query --page /a` reads `page_queries`.
+If no Store table holds every dimension and filter, the query fails and names `--live`.
+
 ```bash
 # Export query rows with a CSV header.
-gscdump query --live --site sc-domain:example.com \
+gscdump query --live --site example.com \
   --dimensions page,query --format csv --output rows.csv
 ```
 
+### SQL over the Store
+
+`query --sql` runs DuckDB SQL over one view per Store table.
+Run `query --schema` to list the views, their columns, and their date ranges.
+
+```bash
+gscdump query --format json --sql "
+  SELECT p.page, SUM(q.clicks) AS clicks, gsc_position(q.sum_position, q.impressions) AS position
+  FROM pages p JOIN page_queries q USING (site, search_type, url, date)
+  WHERE p.search_type = 'web' AND p.date >= DATE '2026-08-01'
+  GROUP BY p.page ORDER BY clicks DESC LIMIT 20"
+```
+
+| Column | Meaning |
+| --- | --- |
+| `site` | The Site URL, such as `sc-domain:example.com` |
+| `search_type` | `web`, `image`, `video`, `news`, `discover`, or `googleNews` |
+| `url`, `page` | The page path. `page` is the same value as `url` |
+| `sum_position` | Zero-based position multiplied by impressions |
+
+- The Store keeps every search type. Filter or group by `search_type`, or a `SUM` adds web, image, and Discover rows together.
+- `gsc_position(sum_position, impressions)` returns the impression-weighted average position. Use it with `GROUP BY`.
+- The views cover every Site in the Store. `--site` and `--type` narrow them.
+- Dates return as `YYYY-MM-DD`. Integers return as numbers, and an integer past 2^53 returns as a string.
+- If the SQL names a table with no synced data, the CLI prints a warning.
+
+### Export formats
+
+`dump` reads only the Store. It never calls Google to fill a gap.
+Every exported row has `site` and `search_type` columns.
+
+| `--format` | Output |
+| --- | --- |
+| `parquet` (default) | `<site>/<search_type>/<table>.parquet` |
+| `csv`, `json`, `ndjson` | `<site>/<search_type>/<table>.<ext>`, plus a per-row `position` |
+| `sqlite` | One `gscdump.sqlite` file. Dates are `YYYY-MM-DD` text |
+| `duckdb` | One `gscdump.duckdb` file |
+
+Inspections, sitemaps, and Indexing API metadata go to `<site>/<dataset>.<ext>`, or to their own tables in a database file.
+`manifest.json` lists every dataset with its row count, and the same coverage that `sync --status` reports.
+`--format sqlite` needs Node.js 22.13 or later.
+
 ### Global flags
 
 - `--no-color` / `NO_COLOR` env: strip ANSI from stdout (stderr keeps colour for interactive use).
@@ -212,38 +260,73 @@ Saved config rejects invalid values and unknown keys. If parsing fails, fix the
 `gscdump analyze <tool>` runs one of 29 Analyzers from `@gscdump/analysis`.
 See the [full list](../../README.md#analyzers) and [Source support](../analysis/README.md#sources).
 
-Each Analyzer accepts `--site`, `--start`, `--end`, `--limit`, and output flags.
-`movers` and `decay` also accept `--prev-start` and `--prev-end`.
+Each Analyzer accepts `--site`, `--period`, `--start`, `--end`, `--limit`, `--fetch-budget`, and output flags.
+Windows default to the last 28 days that end on the newest synced day.
+`movers` and `decay` compare with the previous period by default. Override it with `--prev-start` and `--prev-end` together.
+`movers` also accepts `--sort-by`: `clicksDelta` (default) sorts by absolute click change, `clicksDeltaPercent` by percent change.
+`--limit` caps the rows shown. `--fetch-budget` caps the rows each live fetch reads (default 25000, max 100000).
+If a fetch reaches the budget, the output shows a partial-data warning.
 Use `gscdump analyze <tool> --help` for additional options.
 
-The CLI requires local data unless you pass `--live`.
+`analyze` and `report` follow the [routing rules](#routing).
 Pass `--live` to use Google explicitly.
 SQL-only Analyzers require local data.
 
+## Routing
+
+Login is optional. Log in with Google or a hosted key, or sync a local Store.
+`query`, `analyze`, and `report` pick one source for each run:
+
+- If the Store covers every date the run needs, the run reads the Store. This is also true while a sync runs.
+- If the Store has no data for the tables the run needs, and Google is connected, the run asks the live Search Console API.
+  stderr prints `No synced data for SITE; answering from the live Search Console API.` JSON output has `meta.source: "live"`.
+- If the Store has no data and Google is not connected, the run stops and names `gscdump init`.
+- If some dates are missing, the run stops and prints the `gscdump sync` command for the missing dates and tables. Pass `--live` to ask Google instead.
+- If a sync for the Site is running and the dates are not covered yet, the run stops with `Sync running: 41 of 90 days done.`
+  A sync without a heartbeat in the last 2 minutes counts as stopped.
+
+One run never mixes Store rows and live rows. Live results hold the top rows of each request, and synced data keeps more of the long tail.
+`query --sql` reads the Store only.
+With `--format json` or `--json`, a stop prints `{ "error": { "code", "message", "nextCommand" } }` on stdout and exits 1.
+
+Every Search Analytics, URL Inspection, and Indexing API call goes through the quota ledger in the data dir, so all commands share one daily budget.
+When a quota is spent, the command stops and says when the quota resets.
+
 ## Sync
 
 ```bash
-# Default: three days ending three days ago; skip completed dates
-gscdump sync --site sc-domain:example.com --tables pages,queries,page_queries,countries,dates
+# Default: catch every table and search type up to the latest final date.
+# A table with no history starts 28 days back. Newest dates come first.
+# Also saves sitemaps and inspects up to 50 due URLs. Skips completed dates.
+gscdump sync --site example.com
+
+# Backfill the 16 months Google keeps, plus 14 days Google often still serves
+gscdump sync --site example.com --full
+
+# Cap one run at 2,000 Search Analytics calls; the next run continues
+gscdump sync --site example.com --full --max-calls 2000
 
-# Backfill from 450 days ago to three days ago
-gscdump sync --site sc-domain:example.com --full --tables pages,queries,page_queries,countries,dates
+# Every verified Site, one after another
+gscdump sync --all-sites
 
 # Custom range
-gscdump sync --site sc-domain:example.com --start 2026-08-01 --end 2026-08-31 \
+gscdump sync --site example.com --start 2026-08-01 --end 2026-08-31 \
   --tables pages,queries,page_queries,countries,dates
 
-# Check sync state and watermarks
-gscdump sync --site sc-domain:example.com --status
+# Coverage, missing and failed dates per table, and a running sync
+gscdump sync --site example.com --status
 
 # Limit concurrent day requests per table
-gscdump sync --site sc-domain:example.com --concurrency 4 \
+gscdump sync --site example.com --concurrency 4 \
   --tables pages,queries,page_queries,countries,dates
 ```
 
 Sync skips completed dates; `--force` refreshes them.
+A day Google still updates stays `pending`, and the next sync fetches it again.
+Sync records Google calls in a quota ledger in the Store directory.
+If Google refuses a call for quota, sync stops, keeps the rest `pending`, and exits 0. The next run continues.
 Cross-process locks coordinate `sync`, `compact`, and `gc`.
-Pagination follows Google's 25,000-row pages, subject to [Google's data limits](https://developers.google.com/webmaster-tools/v1/how-tos/all-your-data).
+Pagination follows Google's 25,000-row pages and stops at the first short page, subject to [Google's data limits](https://developers.google.com/webmaster-tools/v1/how-tos/all-your-data).
 
 ## MCP server
 

package/bin/gscdump.mjs

@@ -2,7 +2,27 @@
 
 import process from 'node:process'
 
-import ('../dist/cli.mjs').then(({ runCli }) => runCli()).catch((error) => {
+// Node does not flush pending pipe writes on process.exit. Drain a stream
+// first so a failed run cannot truncate piped output.
+function drained(stream) {
+  return new Promise((resolve) => {
+    stream.once('error', resolve)
+    if (stream.write(''))
+      resolve()
+    else
+      stream.once('drain', resolve)
+  })
+}
+
+import ('../dist/cli.mjs').then(async ({ runCli }) => {
+  const code = await runCli()
+  // A failed command may leave handles open (DuckDB, sockets). Exit now.
+  // On success the process ends by itself, so a server command stays up.
+  if (code !== 0) {
+    await Promise.all([drained(process.stdout), drained(process.stderr)])
+    process.exit(code)
+  }
+}).catch((error) => {
   console.error(error instanceof Error ? error.message : String(error))
   process.exitCode = 1
 })

package/dist/analysis-local.mjs

@@ -1,33 +1,127 @@
+import { LocalStoreUnsupportedError } from "./error-handler.mjs";
+import { useCliRuntime } from "./runtime.mjs";
 import { logger } from "./utils.mjs";
-import { createLocalStore } from "./local-store.mjs";
+import { inferTable } from "./local-store.mjs";
 import { createCommandContext } from "./context.mjs";
-import { LocalStoreUnsupportedError } from "./error-handler.mjs";
-import process from "node:process";
-import { readdir } from "node:fs/promises";
-import { join } from "node:path";
+import { decideRoute, liveNote, readRouteState, readSiteStates, resolveReadSite, stopAtRoute } from "./route.mjs";
+import { newestDoneDate } from "./window.mjs";
+import { extractDateRange } from "gscdump/query";
+import { getLatestGscDate } from "gscdump/dates";
+import { err, ok, unwrapResult } from "gscdump/result";
 import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
 import { createGscApiQuerySource } from "@gscdump/engine-gsc-api";
 import { AnalyzerCapabilityError, runAnalyzerFromSource } from "@gscdump/engine/analyzer";
 import { createEngineQuerySource } from "@gscdump/engine/source";
-import { err, ok, unwrapResult } from "gscdump/result";
-import { decodeSiteId, normalizeSiteUrl } from "gscdump/tenant";
-async function hasLocalData(store, siteUrl) {
-	return (await store.engine.listLive({
-		userId: store.userId,
-		siteId: store.siteIdFor(siteUrl)
-	})).length > 0;
+const PLACEHOLDER_DATE = "2000-01-01";
+const DAILY_PARTITION_RE = /^daily\/(\d{4}-\d{2}-\d{2})$/;
+function sqlPlanReads(params) {
+	const analyzer = defaultAnalyzerRegistry.getAnalyzerVariants(params.type)?.sql;
+	if (!analyzer) return void 0;
+	let plan;
+	try {
+		plan = analyzer.build(params);
+	} catch (error) {
+		logger.debug(`Cannot plan ${params.type}: ${error.message}`);
+		return;
+	}
+	if (plan.kind !== "sql") return void 0;
+	return [
+		{
+			period: "current",
+			fileSet: plan.current
+		},
+		...plan.previous ? [{
+			period: "comparison",
+			fileSet: plan.previous
+		}] : [],
+		...Object.values(plan.extraFiles ?? {}).map((fileSet) => ({
+			period: "current",
+			fileSet
+		}))
+	];
+}
+function analyzerTables(params) {
+	const reads = sqlPlanReads({
+		startDate: PLACEHOLDER_DATE,
+		endDate: PLACEHOLDER_DATE,
+		prevStartDate: PLACEHOLDER_DATE,
+		prevEndDate: PLACEHOLDER_DATE,
+		...params
+	});
+	return [...new Set((reads ?? []).map((read) => read.fileSet.table))];
+}
+function isAdapterPlanned(type) {
+	return defaultAnalyzerRegistry.getAnalyzerVariants(type)?.sql?.requires.includes("adapter") ?? false;
+}
+function isBuilderState(value) {
+	return Boolean(value) && typeof value === "object" && Array.isArray(value.dimensions);
 }
-async function listLocalSites(dataDir, userId = "local") {
-	const tenantDir = join(dataDir, `u_${userId}`);
-	return readdir(tenantDir, { withFileTypes: true }).then((entries) => entries.filter((e) => e.isDirectory() && (e.name.startsWith("d_") || e.name.startsWith("h_"))).map((e) => decodeSiteId(e.name))).catch(() => []);
+function builderStateNeed(state, period) {
+	const table = inferTable(state.dimensions);
+	const { startDate, endDate } = extractDateRange(state.filter);
+	const searchType = state.searchType && state.searchType !== "web" ? state.searchType : void 0;
+	if (startDate && endDate) return {
+		kind: "window",
+		period,
+		table,
+		searchType: searchType ?? "web",
+		window: {
+			start: startDate,
+			end: endDate
+		}
+	};
+	return {
+		kind: "any",
+		tables: [table],
+		...searchType ? { searchType } : {}
+	};
+}
+function builderStateNeeds(params) {
+	if (!isAdapterPlanned(params.type)) return [];
+	if (!isBuilderState(params.q)) return [{
+		kind: "any",
+		tables: []
+	}];
+	const needs = [builderStateNeed(params.q, "current")];
+	if (isBuilderState(params.qc)) needs.push(builderStateNeed(params.qc, "comparison"));
+	return needs;
+}
+function analysisNeeds(params) {
+	const needs = [];
+	for (const { period, fileSet } of sqlPlanReads(params) ?? []) {
+		const dates = fileSet.partitions.flatMap((partition) => DAILY_PARTITION_RE.exec(partition)?.[1] ?? []).sort();
+		if (dates.length === 0) {
+			needs.push({
+				kind: "any",
+				tables: [fileSet.table]
+			});
+			continue;
+		}
+		needs.push({
+			kind: "window",
+			period,
+			table: fileSet.table,
+			searchType: "web",
+			window: {
+				start: dates[0],
+				end: dates.at(-1)
+			}
+		});
+	}
+	if (needs.length > 0) return needs;
+	const builderNeeds = builderStateNeeds(params);
+	if (builderNeeds.length > 0) return builderNeeds;
+	return [{
+		kind: "any",
+		tables: []
+	}];
 }
-function pickLocalSite(siteUrls, hint) {
-	if (siteUrls.length === 0) return null;
-	if (!hint) return siteUrls.length === 1 ? siteUrls[0] : null;
-	const normalized = normalizeSiteUrl(hint);
-	const exact = siteUrls.find((s) => s === normalized || s === hint);
-	if (exact) return exact;
-	return siteUrls.find((s) => s.includes(hint) || hint.includes(s)) ?? null;
+function analyzerSources(types) {
+	const variants = types.map((type) => defaultAnalyzerRegistry.getAnalyzerVariants(type));
+	return {
+		local: variants.every((variant) => Boolean(variant?.sql)),
+		live: variants.every((variant) => Boolean(variant?.rows))
+	};
 }
 async function runAnalysisResult(source, params, mode) {
 	return runAnalyzerFromSource(source, params, defaultAnalyzerRegistry).then(ok).catch((e) => {
@@ -36,56 +130,81 @@ async function runAnalysisResult(source, params, mode) {
 	});
 }
 function makeRunAnalysis(source, mode) {
-	return async (params) => unwrapResult(await runAnalysisResult(source, params, mode), (e) => e);
+	return async (params) => {
+		const result = unwrapResult(await runAnalysisResult(source, params, mode), (e) => e);
+		return {
+			...result,
+			meta: {
+				...result.meta,
+				source: mode
+			}
+		};
+	};
 }
 async function resolveAnalysisSource(args) {
-	const isLive = !!args.live;
-	const format = args.json ? "json" : args.format ? String(args.format) : "table";
-	if (!isLive) {
-		const { config, dataDir } = await createCommandContext();
-		const store = createLocalStore({ dataDir });
-		const siteHint = args.site ? String(args.site) : config.defaultSite;
-		const localSites = await listLocalSites(dataDir, store.userId);
-		const siteUrl = pickLocalSite(localSites, siteHint);
-		if (!siteUrl) {
-			if (localSites.length === 0) logger.error(`No local data found in ${dataDir}. Run \`gscdump sync\` first, or pass --live.`);
-			else logger.error(`Could not resolve site${siteHint ? ` from "${siteHint}"` : ""}. Local sites: ${localSites.join(", ")}`);
-			process.exit(1);
-		}
-		if (!await hasLocalData(store, siteUrl).catch(() => false)) {
-			logger.error(`No local data for ${siteUrl}. Run \`gscdump sync\` first, or pass --live.`);
-			process.exit(1);
-		}
+	const forceLive = Boolean(args.live);
+	const ctx = await createCommandContext({ needsStore: true });
+	const store = ctx.store;
+	let live;
+	const connect = () => live ??= createCommandContext({
+		needsAuth: true,
+		needsStore: false
+	});
+	const { site, siteHint, auth } = await resolveReadSite(ctx, args.site ? String(args.site) : void 0, {
+		forceLive,
+		connect
+	});
+	const states = site ? await readSiteStates(store, site) : [];
+	const anchor = forceLive ? getLatestGscDate() : newestDoneDate(states, args.anchorTables) ?? getLatestGscDate();
+	const sources = args.sources ?? analyzerSources(args.types);
+	const req = {
+		site,
+		siteHint,
+		label: args.label,
+		localCapable: sources.local,
+		liveCapable: sources.live,
+		forceLive,
+		argv: useCliRuntime().rawArgs
+	};
+	const state = await readRouteState({
+		store,
+		site,
+		needs: args.needs(anchor),
+		states,
+		auth
+	});
+	const route = decideRoute(req, state);
+	if (route.kind === "syncing" || route.kind === "prompt") stopAtRoute(route, req, state.auth, { json: Boolean(args.json) });
+	if (route.kind === "local") {
 		const source = createEngineQuerySource({
 			engine: store.engine,
 			ctx: {
 				userId: store.userId,
-				siteId: store.siteIdFor(siteUrl)
+				siteId: store.siteIdFor(site)
 			}
 		});
 		return {
 			source,
-			siteUrl,
-			format,
-			isLive,
+			siteUrl: site,
+			isLive: false,
+			anchor,
 			runAnalysis: makeRunAnalysis(source, "local")
 		};
 	}
-	const ctx = await createCommandContext({
-		needsAuth: true,
-		needsStore: false
-	});
-	const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+	const liveCtx = await connect();
+	const siteUrl = site ?? await liveCtx.resolveSite(void 0);
+	if (route.reason === "no-store-data") logger.warn(liveNote(siteUrl));
 	const source = createGscApiQuerySource({
-		client: ctx.client,
+		client: liveCtx.client,
 		siteUrl
 	});
 	return {
 		source,
 		siteUrl,
-		format,
-		isLive,
+		isLive: true,
+		liveReason: route.reason,
+		anchor,
 		runAnalysis: makeRunAnalysis(source, "live")
 	};
 }
-export { hasLocalData, listLocalSites, resolveAnalysisSource };
+export { analysisNeeds, analyzerSources, analyzerTables, resolveAnalysisSource };

package/dist/auth-state.mjs

@@ -1,7 +1,9 @@
+import { HOSTED_KEY_REJECTED } from "./error-handler.mjs";
 import { useCliRuntime } from "./runtime.mjs";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { gscdumpAvailableSiteSchema } from "@gscdump/contracts";
 import { z } from "zod";
 const apiRootSchema = z.url().transform((value) => value.replace(/\/+$/, "")).refine((value) => {
 	const url = new URL(value);
@@ -97,11 +99,14 @@ async function cloudRequest(state, route, options = {}) {
 		signal: options.signal ?? AbortSignal.timeout(3e4),
 		redirect: "error"
 	});
-	if (!response.ok) throw Object.assign(/* @__PURE__ */ new Error(`Hosted request failed (${response.status}) for ${route.split("?")[0]}. Check \`gscdump auth status\`.`), {
-		statusCode: response.status,
-		retryAfter: response.headers.get("retry-after"),
-		response
-	});
+	if (!response.ok) {
+		const message = response.status === 401 ? HOSTED_KEY_REJECTED : `Hosted request failed (${response.status}) for ${route.split("?")[0]}. Check \`gscdump auth status\`.`;
+		throw Object.assign(new Error(message), {
+			statusCode: response.status,
+			retryAfter: response.headers.get("retry-after"),
+			response
+		});
+	}
 	return response.status === 204 ? void 0 : response.json();
 }
 async function getCloudAccount(state) {
@@ -109,4 +114,14 @@ async function getCloudAccount(state) {
 	if (!result.success) throw new Error("The hosted API returned invalid account data.");
 	return result.data;
 }
-export { clearAuthentication, cloudRequest, getCloudAccount, parseAuthMode, parseAuthentication, resolveAuthentication, saveAuthentication };
+async function getCloudSites(state) {
+	const result = gscdumpAvailableSiteSchema.array().safeParse(await cloudRequest(state, "/cli/sites/available"));
+	if (!result.success) throw new Error("The hosted API returned invalid Site data.");
+	return result.data;
+}
+function formatHostedSync(site) {
+	if (!site.registered) return void 0;
+	const status = site.syncStatus ?? "pending";
+	return `${status}${site.syncProgress && site.syncProgress.total > 0 && status !== "synced" ? `: ${site.syncProgress.completed.toLocaleString("en-US")} of ${site.syncProgress.total.toLocaleString("en-US")} days (${Math.round(site.syncProgress.percent)}%)` : ""}${status === "synced" && site.oldestDateSynced && site.newestDateSynced ? `: ${site.oldestDateSynced} to ${site.newestDateSynced}` : ""}`;
+}
+export { clearAuthentication, cloudRequest, formatHostedSync, getCloudAccount, getCloudSites, parseAuthMode, parseAuthentication, resolveAuthentication, saveAuthentication };