gsccli CLAUDE.md

gsccli — Operating Contract

TypeScript ESM CLI for Google Search Console + Indexing API. Senior-grade workflow tooling on top of every GSC API endpoint: auto-pagination, client-side sort, period comparison, parallel batch URL inspection, file-backed query cache, validation guards. Claude operates this repo mostly autonomously.

The 10 rules that break things silently

1. Imports end in .js, never .ts — import { foo } from './bar.service.js'. ESM + moduleResolution: bundler requires it. Hard build break if violated.
2. Every command .action() starts with resolveGlobalOptions(command) — single place where flags + env + project .gsccli.json + global ~/.gsccli/config.json are reconciled (in that priority order).
3. Service results return ReportData ({headers, rows, rowCount}) — even single-value or "Deleted X" responses get coerced into a 1×N row. Formatters depend on it.
4. handleError(err) is terminal (: never) — never wrap, never rethrow, never try-around it. It is the leaf of every action.
5. Pipeline order is inviolable: Commander → resolveGlobalOptions + validate → service → ReportData → formatOutput → writeOutput. No layer-skipping.
6. API clients only via the singletons in searchconsole.service.ts / indexing.service.ts — direct google.webmasters({...}) / google.indexing({...}) bypasses the auth chain and cache.
7. validate(schema, opts) is terminal — process.exit(1) on ZodError. Don't catch ZodError outside validate. New options need a schema in src/validation/schemas.ts.
8. New CLI config key = update CLIConfig interface, CONFIG_KEYS map, AND LOCAL_BY_DEFAULT_KEYS (when site-related/per-project) in src/types/config.ts. Otherwise setConfigValue rejects them and defaultScopeFor mis-routes them.
9. stderr = status (logger/ora). stdout = data (writeOutput). Mixing breaks --format json | jq piping AND breaks the MCP server (which speaks JSON-RPC on stdout).
10. New top-level command = program.addCommand(createXxxCommand()) in src/index.ts or it's invisible at the CLI surface.