@pagebridge/cli 0.0.2 → 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/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"}

package/dist/commands/doctor.js

@@ -0,0 +1,353 @@
+import { Command } from "commander";
+import { createClient as createSanityClient } from "@sanity/client";
+import { GSCClient } from "@pagebridge/core";
+import { createDb, sql, searchAnalytics, queryAnalytics, syncLog, pageIndexStatus, unmatchDiagnostics, } from "@pagebridge/db";
+import { resolve } from "../resolve-config.js";
+import { log } from "../logger.js";
+import { existsSync, readFileSync } from "fs";
+import { resolve as resolvePath } from "path";
+const ENV_FILES = [".env.local", ".env"];
+function loadEnvFile(filePath) {
+    const content = readFileSync(filePath, "utf-8");
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+        // Strip surrounding quotes
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        // Don't overwrite existing env vars
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+}
+async function checkEnvFile() {
+    for (const name of ENV_FILES) {
+        const envPath = resolvePath(process.cwd(), name);
+        if (existsSync(envPath)) {
+            loadEnvFile(envPath);
+            return {
+                name: "Environment File",
+                status: "pass",
+                message: `${name} file found and loaded`,
+            };
+        }
+    }
+    return {
+        name: "Environment File",
+        status: "fail",
+        message: "No .env file found",
+        details: "Run 'pagebridge init' to create one (looks for .env.local, .env)",
+    };
+}
+async function checkEnvVars() {
+    const required = [
+        "GOOGLE_SERVICE_ACCOUNT",
+        "DATABASE_URL",
+        "SANITY_PROJECT_ID",
+        "SANITY_DATASET",
+        "SANITY_TOKEN",
+        "SITE_URL",
+    ];
+    const missing = required.filter((key) => !process.env[`PAGEBRIDGE_${key}`] && !process.env[key]);
+    if (missing.length > 0) {
+        return {
+            name: "Environment Variables",
+            status: "fail",
+            message: `Missing ${missing.length} required variables`,
+            details: `Missing: ${missing.map((k) => `PAGEBRIDGE_${k}`).join(", ")}`,
+        };
+    }
+    return {
+        name: "Environment Variables",
+        status: "pass",
+        message: "All required variables are set",
+    };
+}
+async function checkDatabase() {
+    const dbUrl = resolve(undefined, "DATABASE_URL");
+    if (!dbUrl) {
+        return {
+            name: "Database Connection",
+            status: "skip",
+            message: "DATABASE_URL not set",
+        };
+    }
+    try {
+        const { db, close } = createDb(dbUrl);
+        await db.execute(sql `SELECT 1`);
+        await close();
+        return {
+            name: "Database Connection",
+            status: "pass",
+            message: "Connected successfully",
+        };
+    }
+    catch (error) {
+        return {
+            name: "Database Connection",
+            status: "fail",
+            message: "Connection failed",
+            details: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function checkDatabaseSchema() {
+    const dbUrl = resolve(undefined, "DATABASE_URL");
+    if (!dbUrl) {
+        return {
+            name: "Database Schema",
+            status: "skip",
+            message: "DATABASE_URL not set",
+        };
+    }
+    try {
+        const { db, close } = createDb(dbUrl);
+        // Check if tables exist by trying to query them
+        const tables = [
+            { name: "search_analytics", table: searchAnalytics },
+            { name: "query_analytics", table: queryAnalytics },
+            { name: "sync_log", table: syncLog },
+            { name: "page_index_status", table: pageIndexStatus },
+            { name: "unmatch_diagnostics", table: unmatchDiagnostics },
+        ];
+        const missingTables = [];
+        for (const { name, table } of tables) {
+            try {
+                await db.select().from(table).limit(1);
+            }
+            catch {
+                missingTables.push(name);
+            }
+        }
+        await close();
+        if (missingTables.length > 0) {
+            return {
+                name: "Database Schema",
+                status: "fail",
+                message: `Missing ${missingTables.length} tables`,
+                details: `Run 'pnpm db:push' or 'pagebridge sync --migrate'. Missing: ${missingTables.join(", ")}`,
+            };
+        }
+        return {
+            name: "Database Schema",
+            status: "pass",
+            message: "All tables exist",
+        };
+    }
+    catch (error) {
+        return {
+            name: "Database Schema",
+            status: "fail",
+            message: "Schema check failed",
+            details: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function checkSanity() {
+    const projectId = resolve(undefined, "SANITY_PROJECT_ID");
+    const dataset = resolve(undefined, "SANITY_DATASET");
+    const token = resolve(undefined, "SANITY_TOKEN");
+    if (!projectId || !dataset || !token) {
+        return {
+            name: "Sanity Connection",
+            status: "skip",
+            message: "Sanity credentials not set",
+        };
+    }
+    try {
+        const sanity = createSanityClient({
+            projectId,
+            dataset,
+            token,
+            apiVersion: "2024-01-01",
+            useCdn: false,
+        });
+        await sanity.fetch('*[_type == "gscSite"][0]{ _id }');
+        return {
+            name: "Sanity Connection",
+            status: "pass",
+            message: "Connected successfully",
+        };
+    }
+    catch (error) {
+        return {
+            name: "Sanity Connection",
+            status: "fail",
+            message: "Connection failed",
+            details: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function checkGoogleServiceAccount() {
+    const serviceAccount = resolve(undefined, "GOOGLE_SERVICE_ACCOUNT");
+    if (!serviceAccount) {
+        return {
+            name: "Google Service Account",
+            status: "skip",
+            message: "GOOGLE_SERVICE_ACCOUNT not set",
+        };
+    }
+    try {
+        const credentials = JSON.parse(serviceAccount);
+        if (!credentials.private_key || !credentials.client_email) {
+            return {
+                name: "Google Service Account",
+                status: "fail",
+                message: "Invalid service account format",
+                details: "Missing private_key or client_email",
+            };
+        }
+        return {
+            name: "Google Service Account",
+            status: "pass",
+            message: `Valid (${credentials.client_email})`,
+        };
+    }
+    catch {
+        return {
+            name: "Google Service Account",
+            status: "fail",
+            message: "Invalid JSON",
+            details: "Service account must be valid JSON",
+        };
+    }
+}
+async function checkGSCAccess() {
+    const serviceAccount = resolve(undefined, "GOOGLE_SERVICE_ACCOUNT");
+    if (!serviceAccount) {
+        return {
+            name: "GSC API Access",
+            status: "skip",
+            message: "Service account not configured",
+        };
+    }
+    try {
+        const credentials = JSON.parse(serviceAccount);
+        const gsc = new GSCClient({ credentials });
+        const sites = await gsc.listSites();
+        if (sites.length === 0) {
+            return {
+                name: "GSC API Access",
+                status: "warn",
+                message: "No sites found",
+                details: "Make sure the service account has access to your Search Console properties",
+            };
+        }
+        return {
+            name: "GSC API Access",
+            status: "pass",
+            message: `Found ${sites.length} site${sites.length > 1 ? "s" : ""}`,
+        };
+    }
+    catch (error) {
+        return {
+            name: "GSC API Access",
+            status: "fail",
+            message: "API access failed",
+            details: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function checkNodeVersion() {
+    const version = process.version;
+    const major = parseInt(version.slice(1).split(".")[0] ?? "0");
+    if (major < 18) {
+        return {
+            name: "Node.js Version",
+            status: "fail",
+            message: `Node.js ${version} is too old`,
+            details: "PageBridge requires Node.js 18 or higher",
+        };
+    }
+    return {
+        name: "Node.js Version",
+        status: "pass",
+        message: `Node.js ${version}`,
+    };
+}
+function getStatusIcon(status) {
+    switch (status) {
+        case "pass":
+            return "✅";
+        case "fail":
+            return "❌";
+        case "warn":
+            return "⚠️";
+        case "skip":
+            return "⏭️";
+    }
+}
+export const doctorCommand = new Command("doctor")
+    .description("Diagnose PageBridge setup and configuration issues")
+    .option("--verbose", "Show detailed information")
+    .action(async (options) => {
+    log.info("🏥 PageBridge Health Check\n");
+    const checks = [
+        checkNodeVersion,
+        checkEnvFile,
+        checkEnvVars,
+        checkDatabase,
+        checkDatabaseSchema,
+        checkSanity,
+        checkGoogleServiceAccount,
+        checkGSCAccess,
+    ];
+    const results = [];
+    for (const check of checks) {
+        try {
+            const result = await check();
+            results.push(result);
+            const icon = getStatusIcon(result.status);
+            log.info(`${icon} ${result.name}: ${result.message}`);
+            if (options.verbose && result.details) {
+                log.info(`   ${result.details}`);
+            }
+            else if (!options.verbose &&
+                result.status === "fail" &&
+                result.details) {
+                log.info(`   ${result.details}`);
+            }
+        }
+        catch (error) {
+            results.push({
+                name: "Unknown Check",
+                status: "fail",
+                message: "Check failed",
+                details: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // Summary
+    const passed = results.filter((r) => r.status === "pass").length;
+    const failed = results.filter((r) => r.status === "fail").length;
+    const warned = results.filter((r) => r.status === "warn").length;
+    const skipped = results.filter((r) => r.status === "skip").length;
+    log.info("\n📊 Summary:");
+    log.info(`   ✅ Passed: ${passed}`);
+    if (failed > 0)
+        log.error(`   ❌ Failed: ${failed}`);
+    if (warned > 0)
+        log.warn(`   ⚠️  Warnings: ${warned}`);
+    if (skipped > 0)
+        log.info(`   ⏭️  Skipped: ${skipped}`);
+    if (failed === 0 && warned === 0) {
+        log.info("\n🎉 All checks passed! PageBridge is ready to use.");
+        log.info("Run 'pagebridge sync --site <url> --migrate' to start syncing.");
+    }
+    else if (failed > 0) {
+        log.error("\n⚠️  Some checks failed. Fix the issues above and run 'pagebridge doctor' again.");
+    }
+    else {
+        log.warn("\n⚠️  Some warnings detected. PageBridge may still work, but review the warnings above.");
+    }
+    process.exit(failed > 0 ? 1 : 0);
+});

package/dist/commands/init.d.ts

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

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

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