@pagebridge/cli 0.0.1 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Soma Somorjai
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Soma Somorjai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,162 +1,157 @@
 # @pagebridge/cli
 
-Command-line interface for PageBridge. Syncs Google Search Console data to Sanity CMS, detects content decay, and generates refresh tasks.
+Command-line interface for PageBridge. Syncs Google Search Console data to your PostgreSQL database, matches URLs to Sanity documents, detects content decay, and generates refresh tasks.
 
 ## Installation
 
-The CLI is a private workspace package. Build and run it from the monorepo root:
+```bash
+pnpm add -D @pagebridge/cli
+```
+
+Or run from the monorepo:
 
 ```bash
-# Build the CLI
 pnpm build --filter=@pagebridge/cli
+```
+
+## Commands
 
-# Run commands
-pnpm --filter @pagebridge/cli start <command>
+### `pagebridge init`
 
-# Or use the binary name directly after building
-./apps/cli/dist/index.js <command>
+Interactive setup wizard. Walks you through configuring credentials, tests each connection, and writes a `.env` file with `PAGEBRIDGE_`-prefixed variables.
+
+```bash
+pagebridge init
 ```
 
-## Commands
+Options:
+
+| Option | Description |
+|--------|-------------|
+| `--skip-db-check` | Skip database connection test |
+| `--skip-sanity-check` | Skip Sanity API test |
+| `--skip-gsc-check` | Skip Google Search Console API test |
+
+### `pagebridge doctor`
 
-### sync
+Diagnose configuration issues. Checks your env file, credentials, database connection, schema, Sanity access, and GSC API access.
+
+```bash
+pagebridge doctor
+pagebridge doctor --verbose
+```
+
+Looks for `.env.local` first, then `.env`. Loads the file and validates all required variables.
+
+### `pagebridge sync`
 
 Sync Google Search Console data and optionally generate refresh tasks for decaying content.
 
 ```bash
-pnpm --filter @pagebridge/cli start sync --site sc-domain:example.com
+pagebridge sync --site sc-domain:example.com
 ```
 
 Options:
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `--site <url>` | GSC site URL (required) | - |
-| `--dry-run` | Preview changes without writing to Sanity | false |
-| `--skip-tasks` | Only sync data, skip task generation | false |
-| `--check-index` | Check Google index status for pages | false |
-| `--quiet-period <days>` | Days to ignore recently published content | 45 |
+| `--site <url>` | GSC site URL **(required)** | — |
+| `--dry-run` | Preview changes without writing to Sanity | `false` |
+| `--skip-tasks` | Only sync data, skip task generation | `false` |
+| `--check-index` | Check Google index status for pages | `false` |
+| `--quiet-period <days>` | Days to ignore recently published content | `45` |
+| `--diagnose` | Show detailed diagnostics for unmatched URLs | `false` |
+| `--diagnose-url <url>` | Diagnose why a specific URL is not matching | — |
+| `--migrate` | Run database migrations before syncing | `false` |
+| `--debug` | Enable debug logging with timing information | `false` |
+
+All credentials can also be passed as flags (`--db-url`, `--sanity-project-id`, etc.) to override env vars.
 
 Examples:
 
 ```bash
-# Basic sync
-pnpm --filter @pagebridge/cli start sync --site sc-domain:example.com
+# First sync — creates tables automatically
+pagebridge sync --site sc-domain:example.com --migrate
 
 # Preview what would be synced
-pnpm --filter @pagebridge/cli start sync --site sc-domain:example.com --dry-run
+pagebridge sync --site sc-domain:example.com --dry-run
 
 # Sync data only, no refresh tasks
-pnpm --filter @pagebridge/cli start sync --site sc-domain:example.com --skip-tasks
-
-# Include index status checks
-pnpm --filter @pagebridge/cli start sync --site sc-domain:example.com --check-index
+pagebridge sync --site sc-domain:example.com --skip-tasks
 
-# Use a shorter quiet period (30 days)
-pnpm --filter @pagebridge/cli start sync --site sc-domain:example.com --quiet-period 30
+# Debug why a URL isn't matching
+pagebridge sync --site sc-domain:example.com --diagnose-url https://example.com/my-page
 ```
 
-### list-sites
+### `pagebridge list-sites`
 
-List all Google Search Console properties accessible by the service account.
+List all Google Search Console properties accessible by the configured service account.
 
 ```bash
-pnpm --filter @pagebridge/cli start list-sites
+pagebridge list-sites
 ```
 
-Output:
+### `pagebridge diagnose`
 
-```
-Available GSC Sites:
-- sc-domain:example.com
-- https://www.example.com/
-- sc-domain:another-site.com
+Show stored diagnostics for unmatched URLs from previous sync runs.
+
+```bash
+pagebridge diagnose --site sc-domain:example.com
 ```
 
 ## Environment Variables
 
-Create a `.env` file in the repository root with:
+Create a `.env.local` or `.env` file. PageBridge uses a `PAGEBRIDGE_` prefix to avoid conflicts with your project's existing env vars:
 
 ```bash
-# Google Service Account (required)
-# JSON stringified credentials from Google Cloud Console
-GOOGLE_SERVICE_ACCOUNT='{"type":"service_account","project_id":"...","private_key":"..."}'
+# Google Service Account JSON (stringified)
+PAGEBRIDGE_GOOGLE_SERVICE_ACCOUNT='{"type":"service_account","project_id":"..."}'
 
-# PostgreSQL Database (required)
-DATABASE_URL=postgresql://user:password@localhost:5432/content_keep
+# PostgreSQL connection string
+PAGEBRIDGE_DATABASE_URL='postgresql://user:password@localhost:5432/pagebridge'
 
-# Sanity Configuration (required)
-SANITY_PROJECT_ID=your-project-id
-SANITY_DATASET=production
-SANITY_TOKEN=your-write-token
+# Sanity configuration
+PAGEBRIDGE_SANITY_PROJECT_ID='your-project-id'
+PAGEBRIDGE_SANITY_DATASET='production'
+PAGEBRIDGE_SANITY_TOKEN='sk...'
 
-# Site URL for URL matching (required)
-SITE_URL=https://example.com
+# Your website base URL (used for URL matching)
+PAGEBRIDGE_SITE_URL='https://example.com'
 ```
 
-## Workflow
+Unprefixed names (`DATABASE_URL`, `SANITY_TOKEN`, etc.) are also supported as a fallback. The `PAGEBRIDGE_`-prefixed version always takes priority.
+
+## Sync Workflow
 
 The `sync` command performs these steps:
 
-1. **Validate environment** - Checks all required variables are set
-2. **Find or create gscSite** - Ensures a Sanity document exists for the site
-3. **Fetch GSC data** - Retrieves 90 days of search analytics (skipping last 3 days for data stability)
-4. **Store metrics** - Writes page and query metrics to PostgreSQL
-5. **Match URLs** - Maps GSC pages to Sanity documents by slug
-6. **Write snapshots** - Creates gscSnapshot documents in Sanity with metrics and top queries
-7. **Check index status** (optional) - Queries Google URL Inspection API
-8. **Detect decay** - Analyzes metrics for decay patterns
-9. **Generate tasks** - Creates gscRefreshTask documents for pages showing decay
-
-## Programmatic Usage
-
-The CLI uses `@pagebridge/core` under the hood. For programmatic access:
-
-```typescript
-import { GSCClient, SyncEngine, DecayDetector, TaskGenerator } from '@pagebridge/core';
-import { createDb } from '@pagebridge/db';
-import { createClient } from '@sanity/client';
-
-const gscClient = new GSCClient({
-  serviceAccountJson: process.env.GOOGLE_SERVICE_ACCOUNT,
-});
-
-const db = createDb(process.env.DATABASE_URL);
-
-const sanityClient = createClient({
-  projectId: process.env.SANITY_PROJECT_ID,
-  dataset: process.env.SANITY_DATASET,
-  token: process.env.SANITY_TOKEN,
-  apiVersion: '2024-01-01',
-  useCdn: false,
-});
-
-const engine = new SyncEngine({ gscClient, db, sanityClient });
-const result = await engine.sync({
-  siteUrl: 'sc-domain:example.com',
-  siteId: 'sanity-site-id',
-});
-```
+1. **Validate connections** — Tests database, Sanity, and GSC access
+2. **Find or create gscSite** — Ensures a Sanity document exists for the site
+3. **Fetch GSC data** — Retrieves 90 days of search analytics (skipping last 3 days for data stability)
+4. **Store metrics** — Writes page and query metrics to PostgreSQL
+5. **Match URLs** — Maps GSC pages to Sanity documents by slug
+6. **Detect decay** — Analyzes metrics for position drops, CTR issues, and traffic decline
+7. **Generate tasks** — Creates `gscRefreshTask` documents for pages showing decay
+8. **Write snapshots** — Creates `gscSnapshot` documents in Sanity with metrics and top queries
 
 ## Dependencies
 
-- `@pagebridge/core` - Business logic
-- `@pagebridge/db` - Database operations
-- `@sanity/client` - Sanity API
-- `commander` - CLI framework
-- `dotenv` - Environment variable loading
+- `@pagebridge/core` — Sync engine, decay detection, URL matching
+- `@pagebridge/db` — PostgreSQL schema and queries
+- `@sanity/client` — Sanity API client
+- `commander` — CLI framework
 
 ## Development
 
 ```bash
 # Watch mode
-pnpm --filter @pagebridge/cli dev
+pnpm dev --filter=@pagebridge/cli
 
 # Build
-pnpm --filter @pagebridge/cli build
+pnpm build --filter=@pagebridge/cli
 
 # Type check
-pnpm --filter @pagebridge/cli check-types
+pnpm check-types --filter=@pagebridge/cli
 ```
 
 ## License

package/dist/commands/diagnose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../src/commands/diagnose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,eAAO,MAAM,eAAe,SAyFxB,CAAC"}
+{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../src/commands/diagnose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,eAAO,MAAM,eAAe,SA2GxB,CAAC"}

package/dist/commands/diagnose.js

@@ -1,19 +1,32 @@
 import { Command } from "commander";
-import postgres from "postgres";
-import { createDbWithClient, unmatchDiagnostics, eq, desc, } from "@pagebridge/db";
+import { createDb, unmatchDiagnostics, eq, desc, } from "@pagebridge/db";
+import { resolve, requireConfig } from "../resolve-config.js";
+import { log } from "../logger.js";
+import { migrateIfRequested } from "../migrate.js";
 export const diagnoseCommand = new Command("diagnose")
     .description("View diagnostics for unmatched URLs")
     .requiredOption("--site <url>", "GSC site URL (e.g., sc-domain:example.com)")
     .option("--reason <reason>", "Filter by unmatch reason")
     .option("--limit <n>", "Limit number of results", "20")
     .option("--json", "Output as JSON")
+    .option("--migrate", "Run database migrations before querying")
+    .option("--db-url <url>", "PostgreSQL connection string")
     .action(async (options) => {
-    if (!process.env.DATABASE_URL) {
-        console.error("Missing required environment variable: DATABASE_URL");
-        process.exit(1);
-    }
-    const sql = postgres(process.env.DATABASE_URL);
-    const db = createDbWithClient(sql);
+    const dbUrl = resolve(options.dbUrl, "DATABASE_URL");
+    requireConfig([
+        { name: "DATABASE_URL", flag: "--db-url <url>", envVar: "DATABASE_URL", value: dbUrl },
+    ]);
+    // Run migrations if requested
+    await migrateIfRequested(!!options.migrate, dbUrl);
+    const { db, close } = createDb(dbUrl);
+    // Register shutdown handlers
+    const shutdown = async () => {
+        log.warn("Received shutdown signal, closing connections...");
+        await close();
+        process.exit(130);
+    };
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
     try {
         const query = db
             .select()
@@ -27,8 +40,8 @@ export const diagnoseCommand = new Command("diagnose")
             return;
         }
         if (results.length === 0) {
-            console.log(`No unmatched URLs found for ${options.site}`);
-            console.log(`Run 'sync --site ${options.site}' first to generate diagnostics.`);
+            log.info(`No unmatched URLs found for ${options.site}`);
+            log.info(`Run 'sync --site ${options.site}' first to generate diagnostics.`);
             return;
         }
         // Group by reason
@@ -38,23 +51,22 @@ export const diagnoseCommand = new Command("diagnose")
             existing.push(r);
             byReason.set(r.unmatchReason, existing);
         }
-        console.log(`\nUnmatched URL Diagnostics for ${options.site}\n`);
-        console.log(`Total: ${results.length} unmatched URLs\n`);
+        log.info(`\nUnmatched URL Diagnostics for ${options.site}\n`);
+        log.info(`Total: ${results.length} unmatched URLs\n`);
         for (const [reason, items] of byReason) {
-            console.log(`${getReasonEmoji(reason)} ${getReasonDescription(reason)} (${items.length}):`);
-            console.log();
+            log.info(`${getReasonEmoji(reason)} ${getReasonDescription(reason)} (${items.length}):`);
             for (const item of items) {
-                console.log(`  ${item.gscUrl}`);
+                log.info(`  ${item.gscUrl}`);
                 if (item.extractedSlug) {
-                    console.log(`    Extracted slug: "${item.extractedSlug}"`);
+                    log.info(`    Extracted slug: "${item.extractedSlug}"`);
                 }
                 if (item.similarSlugs) {
                     try {
                         const similar = JSON.parse(item.similarSlugs);
                         if (similar.length > 0) {
-                            console.log(`    Similar slugs in Sanity:`);
+                            log.info(`    Similar slugs in Sanity:`);
                             for (const s of similar) {
-                                console.log(`      - ${s}`);
+                                log.info(`      - ${s}`);
                             }
                         }
                     }
@@ -62,17 +74,23 @@ export const diagnoseCommand = new Command("diagnose")
                         // Ignore parse errors
                     }
                 }
-                console.log();
             }
         }
-        console.log(`\nTo fix unmatched URLs:`);
-        console.log(`  1. Check if the Sanity document exists with the correct slug`);
-        console.log(`  2. Verify the document type is in the contentTypes list`);
-        console.log(`  3. Ensure the slug field name matches your configuration`);
-        console.log(`  4. If using a path prefix, verify it matches your URL structure`);
+        log.info(`\nTo fix unmatched URLs:`);
+        log.info(`  1. Check if the Sanity document exists with the correct slug`);
+        log.info(`  2. Verify the document type is in the contentTypes list`);
+        log.info(`  3. Ensure the slug field name matches your configuration`);
+        log.info(`  4. If using a path prefix, verify it matches your URL structure`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log.error(`Diagnose failed: ${message}`);
+        process.exitCode = 1;
     }
     finally {
-        await sql.end();
+        await close();
+        process.removeListener("SIGTERM", shutdown);
+        process.removeListener("SIGINT", shutdown);
     }
 });
 function getReasonEmoji(reason) {

package/dist/commands/doctor.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare const doctorCommand: Command;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+UpC,eAAO,MAAM,aAAa,SA0EtB,CAAC"}