@gscdump/cli 4.0.0 → 4.0.1

package/README.md

@@ -195,6 +195,8 @@ Dates must use `YYYY-MM-DD`, and `--start` cannot follow `--end`.
 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`.
+If the matching table exists but has no synced rows, an authenticated query can answer live instead.
+Check `meta.source` before describing a result as saved Store data.
 
 ```bash
 # Export query rows with a CSV header.

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "4.0.0";
+var version = "4.0.1";
 export { version };

package/dist/route.mjs

@@ -79,11 +79,13 @@ function decideRoute(req, state) {
 	const connected = auth !== "none";
 	const syncCommand = syncCommandFor(req.site ?? req.siteHint, coverage);
 	const tables = [...new Set(coverage.flatMap((need) => need.kind === "window" ? [need.table] : need.tables))];
+	const searchTypes = [...new Set(coverage.flatMap((need) => need.searchType && need.searchType !== "web" ? [need.searchType] : []))];
 	const notConnected = {
 		kind: "prompt",
 		reason: {
 			kind: "not-connected",
-			tables
+			tables,
+			...searchTypes.length > 0 ? { searchTypes } : {}
 		},
 		nextCommand: CONNECT_COMMAND
 	};
@@ -162,7 +164,11 @@ function routeMessage(route, req, auth) {
 	}
 	const next = route.nextCommand;
 	switch (route.reason.kind) {
-		case "not-connected": return `${route.reason.tables.length > 0 ? `The Store has no ${route.reason.tables.join(", ")} data for ${site}, and Google is not connected.` : `\`${req.label}\` needs Search Console, and Google is not connected.`} Run \`${next}\` to connect Google and sync the Site, or \`${LOGIN_COMMAND}\` to query Search Console directly.`;
+		case "not-connected": {
+			const types = route.reason.searchTypes ?? [];
+			const slice = types.length > 0 ? `${types.join(", ")} ` : "";
+			return `${route.reason.tables.length > 0 ? `The Store has no ${slice}${route.reason.tables.join(", ")} data for ${site}, and Google is not connected.` : `\`${req.label}\` needs Search Console, and Google is not connected.`} Run \`${next}\` to connect Google and sync the Site, or \`${LOGIN_COMMAND}\` to query Search Console directly.`;
+		}
 		case "no-data": return `The Store has no ${route.reason.tables.join(", ")} data for ${site}. \`${req.label}\` reads synced data only. Run \`${next}\` first.`;
 		case "live-only": return `\`${req.label}\` runs against the live Search Console API only. Run \`${next}\`.`;
 		case "store-only": return `\`${req.label}\` reads synced data only. Remove --live. If the Store has no data for ${site}, run \`${next}\` first.`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "CLI for Google Search Console and Bing with hosted or local authentication, data exports, and an MCP server",
   "author": {
     "name": "Harlan Wilton",
@@ -44,16 +44,16 @@
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "@duckdb/node-api": "1.5.5-r.5",
-    "@gscdump/analysis": "^4.0.0",
-    "@gscdump/contracts": "^4.0.0",
-    "@gscdump/engine": "^4.0.0",
-    "@gscdump/engine-gsc-api": "^4.0.0",
-    "@gscdump/sdk": "^4.0.0",
+    "@gscdump/analysis": "^4.0.1",
+    "@gscdump/contracts": "^4.0.1",
+    "@gscdump/engine": "^4.0.1",
+    "@gscdump/engine-gsc-api": "^4.0.1",
+    "@gscdump/sdk": "^4.0.1",
     "@modelcontextprotocol/sdk": "^1.30.1",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.1.0",
-    "gscdump": "^4.0.0",
+    "gscdump": "^4.0.1",
     "ofetch": "^1.5.1",
     "open": "^11.0.4",
     "proper-lockfile": "^4.1.2",

package/skills/gscdump/SKILL.md

@@ -20,8 +20,10 @@ Example: `gscdump query --site=SITE --start=DATE --end=DATE -d page -f json`.
 2. Keep the requested Site, dates, dimensions, and task scope. A request for pages does not need query dimensions.
 3. Before local queries, check coverage with `gscdump store stats --site SITE --json`.
    Use `gscdump sync --site SITE --status --json` when you need coverage, gaps, or sync-state details.
+   On a fresh Store, `store stats` exits 1 and says it has no data. Continue with the bounded sync.
 4. Read the table dimensions and watermarks. Sync only missing tables and the requested dates, once per task.
 5. Use `sync --json`. Read its completion result before deciding what to do next. Never repeat a successful sync.
+6. If the user asks for saved rows, check `meta.source: "local"` in the query result. A successful query can answer live when its table has no synced data.
 
 If the task only asks about deletion, explain the scope and ask for consent.
 You may read Store metadata with `store stats` and `sync --status`.
@@ -268,6 +270,7 @@ gscdump sync --site example.com --json
 - `--dry-run` prints the planned dates and the fewest calls without calling Google.
 - `--all-sites` syncs every verified Site, one after another.
 - Use the user's date range. If the user names a range, pass `--start` and `--end`, not `--full`.
+- If the user excludes rollups, pass `--no-rollups` on the sync command.
 - Empty Store metadata is expected before the first sync. It does not prove zero traffic.
 
 ## Query rows
@@ -278,6 +281,8 @@ gscdump query --site example.com --dimensions page,query \
 ```
 
 - Dimension names are singular: `page`, `query`, `date`, `country`, `device`.
+- A page breakdown uses `--tables pages` for sync and `-d page` for query.
+  `-d page,query` needs `page_queries`; syncing only `pages` does not fill that table.
 - Filters: `--query`, `--page`, `--country`, `--device`,
   `--search-appearance`. Prefixes: bare equals, `~` contains, `!~` not
   contains, `re:` regex, `!re:` not regex, `!` not equals.