salesprompter-cli 0.1.0 → 0.1.2

package/dist/cli.js

@@ -1,65 +1,386 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { z } from "zod";
-import { EnrichedLeadSchema, IcpSchema, LeadSchema, ScoredLeadSchema, SyncTargetSchema } from "./domain.js";
-import { DryRunSyncProvider, HeuristicEnrichmentProvider, HeuristicLeadProvider, HeuristicScoringProvider } from "./engine.js";
-import { readJsonFile, splitCsv, writeJsonFile } from "./io.js";
+import { clearAuthSession, loginWithDeviceFlow, loginWithToken, requireAuthSession, shouldBypassAuth, verifySession } from "./auth.js";
+import { buildBigQueryLeadLookupSql, executeBigQuerySql, normalizeBigQueryLeadRows, runBigQueryQuery, runBigQueryRows } from "./bigquery.js";
+import { AccountProfileSchema, EnrichedLeadSchema, IcpSchema, LeadSchema, ScoredLeadSchema, SyncTargetSchema } from "./domain.js";
+import { auditDomainDecisions, buildDomainfinderBacklogQueries, buildDomainfinderCandidatesSql, buildDomainfinderInputSql, buildDomainfinderWritebackSql, buildExistingDomainRepairSql, buildExistingDomainAuditQueries, compareDomainSelectionStrategies, selectBestDomains } from "./domainfinder.js";
+import { AccountLeadProvider, DryRunSyncProvider, HeuristicCompanyProvider, HeuristicEnrichmentProvider, HeuristicPeopleSearchProvider, HeuristicScoringProvider, RoutedSyncProvider } from "./engine.js";
+import { analyzeHistoricalQueries } from "./historical-queries.js";
+import { buildHistoricalVendorIcp, buildVendorIcp } from "./icp-templates.js";
+import { InstantlySyncProvider } from "./instantly.js";
+import { buildLeadlistsFunnelQueries } from "./leadlists-funnel.js";
+import { readJsonFile, splitCsv, writeJsonFile, writeTextFile } from "./io.js";
 const program = new Command();
-const leadProvider = new HeuristicLeadProvider();
+const leadProvider = new AccountLeadProvider(new HeuristicCompanyProvider(), new HeuristicPeopleSearchProvider());
 const enrichmentProvider = new HeuristicEnrichmentProvider();
 const scoringProvider = new HeuristicScoringProvider();
-const syncProvider = new DryRunSyncProvider();
+const syncProvider = new RoutedSyncProvider(new DryRunSyncProvider(), new InstantlySyncProvider());
+const runtimeOutputOptions = {
+    json: false,
+    quiet: false
+};
 function printOutput(value) {
-    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    if (runtimeOutputOptions.quiet) {
+        return;
+    }
+    const space = runtimeOutputOptions.json ? undefined : 2;
+    process.stdout.write(`${JSON.stringify(value, null, space)}\n`);
+}
+function applyGlobalOutputOptions(actionCommand) {
+    const globalOptions = actionCommand.optsWithGlobals();
+    runtimeOutputOptions.json = Boolean(globalOptions.json);
+    runtimeOutputOptions.quiet = Boolean(globalOptions.quiet);
+}
+function buildCliError(error) {
+    if (error instanceof z.ZodError) {
+        return {
+            status: "error",
+            code: "invalid_arguments",
+            message: "Invalid arguments",
+            details: error.issues.map((issue) => ({
+                path: issue.path.join("."),
+                message: issue.message
+            }))
+        };
+    }
+    const message = error instanceof Error ? error.message : "Unknown error";
+    if (message.includes("not logged in")) {
+        return {
+            status: "error",
+            code: "auth_required",
+            message
+        };
+    }
+    if (message.includes("session expired")) {
+        return {
+            status: "error",
+            code: "session_expired",
+            message
+        };
+    }
+    return {
+        status: "error",
+        code: "runtime_error",
+        message
+    };
+}
+function exitCodeForError(code) {
+    switch (code) {
+        case "invalid_arguments":
+            return 2;
+        case "auth_required":
+        case "session_expired":
+            return 3;
+        case "runtime_error":
+            return 1;
+    }
+}
+const nullableInt = z.union([z.number().int(), z.string(), z.null()]).transform((value, ctx) => {
+    if (value === null) {
+        return null;
+    }
+    if (typeof value === "number") {
+        if (!Number.isInteger(value)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "Expected an integer-compatible value"
+            });
+            return z.NEVER;
+        }
+        return value;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isInteger(parsed)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Expected an integer-compatible value"
+        });
+        return z.NEVER;
+    }
+    return parsed;
+});
+const domainCandidateArraySchema = z.array(z.object({
+    companyId: nullableInt,
+    crmCompanyId: nullableInt,
+    companyName: z.string(),
+    domain: z.string().nullable(),
+    source: z.string(),
+    type: z.string().nullable(),
+    hunterEmailCount: nullableInt,
+    linkedinDomain: z.string().nullable(),
+    linkedinWebsite: z.string().nullable()
+}));
+const domainDecisionArraySchema = z.array(z.object({
+    companyKey: z.string(),
+    selected: z
+        .object({
+        companyId: nullableInt,
+        crmCompanyId: nullableInt,
+        companyName: z.string(),
+        domain: z.string().nullable(),
+        source: z.string(),
+        type: z.string().nullable(),
+        hunterEmailCount: nullableInt,
+        linkedinDomain: z.string().nullable(),
+        linkedinWebsite: z.string().nullable()
+    })
+        .nullable(),
+    reason: z.enum([
+        "linkedin-domain",
+        "linkedin-website",
+        "highest-hunter-count",
+        "fallback-first-non-null",
+        "no-domain"
+    ]),
+    candidates: domainCandidateArraySchema
+}));
+const existingAuditReportSchema = z.object({
+    market: z.string(),
+    countries: z.array(z.string()),
+    stages: z.array(z.object({
+        key: z.string(),
+        description: z.string(),
+        rows: z.array(z.record(z.string(), z.unknown()))
+    }))
+});
+async function fetchHistoricalQueryRows(tables) {
+    const rows = [];
+    for (const table of tables) {
+        const sql = `SELECT CAST(query AS STRING) AS query, COUNT(*) AS freq FROM \`icpidentifier.SalesPrompter.${table}\` WHERE query IS NOT NULL GROUP BY CAST(query AS STRING)`;
+        const resultRows = await runBigQueryRows(sql);
+        for (const row of resultRows) {
+            rows.push({
+                sourceTable: table,
+                query: String(row.query ?? ""),
+                freq: Number(row.freq ?? 0)
+            });
+        }
+    }
+    return rows;
 }
 program
     .name("salesprompter")
     .description("Sales workflow CLI for ICP definition, lead generation, enrichment, scoring, and sync.")
-    .version("0.1.0");
+    .version("0.1.1")
+    .option("--json", "Emit compact machine-readable JSON output", false)
+    .option("--quiet", "Suppress successful stdout output", false);
+program
+    .command("auth:login")
+    .description("Authenticate CLI with Salesprompter app credentials.")
+    .option("--token <token>", "App-issued bearer token for direct login")
+    .option("--api-url <url>", "Salesprompter API base URL, defaults to SALESPROMPTER_API_BASE_URL or app.salesprompter.com")
+    .option("--timeout-seconds <number>", "Device flow wait timeout in seconds", "180")
+    .action(async (options) => {
+    const timeoutSeconds = z.coerce.number().int().min(30).max(1800).parse(options.timeoutSeconds);
+    const token = typeof options.token === "string" ? options.token.trim() : "";
+    if (token.length > 0) {
+        const session = await loginWithToken(token, options.apiUrl);
+        printOutput({
+            status: "ok",
+            method: "token",
+            apiBaseUrl: session.apiBaseUrl,
+            user: session.user,
+            expiresAt: session.expiresAt ?? null
+        });
+        return;
+    }
+    const startedAt = new Date().toISOString();
+    process.stderr.write("Starting device login flow. Complete login in the browser.\n");
+    const result = await loginWithDeviceFlow({
+        apiBaseUrl: options.apiUrl,
+        timeoutSeconds
+    });
+    printOutput({
+        status: "ok",
+        method: "device",
+        startedAt,
+        verificationUrl: result.verificationUrl,
+        userCode: result.userCode,
+        apiBaseUrl: result.session.apiBaseUrl,
+        user: result.session.user,
+        expiresAt: result.session.expiresAt ?? null
+    });
+});
+program
+    .command("auth:whoami")
+    .description("Show current authenticated user and session status.")
+    .option("--verify", "Verify token with API before printing", false)
+    .action(async (options) => {
+    const session = await requireAuthSession();
+    const verifiedSession = options.verify ? await verifySession(session) : session;
+    printOutput({
+        status: "ok",
+        apiBaseUrl: verifiedSession.apiBaseUrl,
+        user: verifiedSession.user,
+        expiresAt: verifiedSession.expiresAt ?? null,
+        createdAt: verifiedSession.createdAt
+    });
+});
+program
+    .command("auth:logout")
+    .description("Remove local CLI auth session.")
+    .action(async () => {
+    await clearAuthSession();
+    printOutput({ status: "ok", loggedOut: true });
+});
+program.hook("preAction", async (_thisCommand, actionCommand) => {
+    applyGlobalOutputOptions(actionCommand);
+    const commandName = actionCommand.name();
+    if (commandName.startsWith("auth:")) {
+        return;
+    }
+    if (shouldBypassAuth()) {
+        return;
+    }
+    const session = await requireAuthSession();
+    if (session.expiresAt !== undefined && Date.now() >= Date.parse(session.expiresAt)) {
+        throw new Error("session expired. Run `salesprompter auth:login`.");
+    }
+});
+program
+    .command("account:resolve")
+    .description("Resolve a target company into a normalized account profile.")
+    .requiredOption("--domain <domain>", "Company domain like deel.com")
+    .option("--company-name <name>", "Optional company name override")
+    .option("--icp <path>", "Optional path to ICP JSON for industry/region/title hints")
+    .requiredOption("--out <path>", "Output file path")
+    .action(async (options) => {
+    const icp = options.icp
+        ? await readJsonFile(options.icp, IcpSchema)
+        : IcpSchema.parse({ name: "ad-hoc account resolve" });
+    const result = await leadProvider.generateLeads(icp, 1, {
+        companyDomain: options.domain,
+        companyName: options.companyName
+    });
+    await writeJsonFile(options.out, result.account);
+    printOutput({
+        status: "ok",
+        provider: result.provider,
+        mode: result.mode,
+        account: AccountProfileSchema.parse(result.account),
+        out: options.out,
+        warnings: result.warnings
+    });
+});
 program
     .command("icp:define")
     .description("Define an ideal customer profile and write it to a JSON file.")
     .requiredOption("--name <name>", "Human-readable ICP name")
+    .option("--description <text>", "Plain-language ICP description", "")
     .option("--industries <items>", "Comma-separated industries", "")
     .option("--company-sizes <items>", "Comma-separated buckets like 1-49,50-199,200-499,500+", "")
     .option("--regions <items>", "Comma-separated regions", "")
+    .option("--countries <items>", "Comma-separated country codes like DE,AT,CH", "")
     .option("--titles <items>", "Comma-separated titles", "")
     .option("--pains <items>", "Comma-separated pain points", "")
     .option("--required-signals <items>", "Comma-separated required signals", "")
     .option("--excluded-signals <items>", "Comma-separated excluded signals", "")
+    .option("--keywords <items>", "Comma-separated keywords for search matching", "")
+    .option("--excluded-keywords <items>", "Comma-separated keywords to filter out", "")
     .requiredOption("--out <path>", "Output file path")
     .action(async (options) => {
     const icp = IcpSchema.parse({
         name: options.name,
+        description: options.description,
         industries: splitCsv(options.industries),
         companySizes: splitCsv(options.companySizes),
         regions: splitCsv(options.regions),
+        countries: splitCsv(options.countries),
         titles: splitCsv(options.titles),
         pains: splitCsv(options.pains),
         requiredSignals: splitCsv(options.requiredSignals),
-        excludedSignals: splitCsv(options.excludedSignals)
+        excludedSignals: splitCsv(options.excludedSignals),
+        keywords: splitCsv(options.keywords),
+        excludedKeywords: splitCsv(options.excludedKeywords)
     });
     await writeJsonFile(options.out, icp);
     printOutput({ status: "ok", icp });
 });
+program
+    .command("icp:vendor")
+    .description("Create a vendor-specific ICP template.")
+    .requiredOption("--vendor <vendor>", "Vendor template name, currently: deel")
+    .option("--market <market>", "global|europe|dach", "dach")
+    .requiredOption("--out <path>", "Output file path")
+    .action(async (options) => {
+    const vendor = z.enum(["deel"]).parse(options.vendor);
+    const market = z.enum(["global", "europe", "dach"]).parse(options.market);
+    const icp = buildVendorIcp(vendor, market);
+    await writeJsonFile(options.out, icp);
+    printOutput({ status: "ok", icp });
+});
+program
+    .command("icp:from-historical-queries:bq")
+    .description("Build a vendor ICP from historical BigQuery query patterns.")
+    .requiredOption("--vendor <vendor>", "Vendor template name, currently: deel")
+    .option("--market <market>", "global|europe|dach", "dach")
+    .option("--tables <items>", "Comma-separated BigQuery tables with a query column", "leadLists_raw,leadLists_unique,linkedinSearchExport_people_unique,salesNavigatorSearchExport_companies_unique,snse_containers_input")
+    .option("--search-kind <kind>", "all|people|sales-people|sales-company", "sales-people")
+    .option("--include-function <items>", "Comma-separated included function texts to keep", "Human Resources")
+    .requiredOption("--out <path>", "Output ICP file path")
+    .option("--report-out <path>", "Optional output path for the historical report")
+    .action(async (options) => {
+    const vendor = z.enum(["deel"]).parse(options.vendor);
+    const market = z.enum(["global", "europe", "dach"]).parse(options.market);
+    const searchKind = z.enum(["all", "people", "sales-people", "sales-company"]).parse(options.searchKind);
+    const tables = splitCsv(options.tables);
+    if (tables.length === 0) {
+        throw new Error("at least one table is required");
+    }
+    const rows = await fetchHistoricalQueryRows(tables);
+    const report = analyzeHistoricalQueries(rows, {
+        searchKind,
+        includeFunctionText: splitCsv(options.includeFunction)
+    });
+    const icp = buildHistoricalVendorIcp(vendor, market, report);
+    await writeJsonFile(options.out, icp);
+    if (options.reportOut) {
+        await writeJsonFile(options.reportOut, report);
+    }
+    printOutput({
+        status: "ok",
+        icp,
+        out: options.out,
+        reportOut: options.reportOut ?? null,
+        distinctQueryRowsAnalyzed: report.distinctQueryRowsAnalyzed,
+        weightedQueryVolume: report.weightedQueryVolume,
+        sourceTables: report.sourceTables
+    });
+});
 program
     .command("leads:generate")
-    .description("Generate seed leads against an ICP.")
+    .description("Generate leads for a target account or from fallback seeds.")
     .requiredOption("--icp <path>", "Path to ICP JSON")
     .option("--count <number>", "Number of leads to generate", "10")
-    .option("--company-domain <domain>", "Target a specific company domain like deel.com")
+    .option("--domain <domain>", "Target a specific company domain like deel.com")
+    .option("--company-domain <domain>", "Deprecated alias for --domain")
     .option("--company-name <name>", "Optional company name override for a targeted domain")
     .requiredOption("--out <path>", "Output file path")
     .action(async (options) => {
     const icp = await readJsonFile(options.icp, IcpSchema);
     const count = z.coerce.number().int().min(1).max(1000).parse(options.count);
+    const domain = options.domain ?? options.companyDomain;
     const target = {
-        companyDomain: options.companyDomain,
+        companyDomain: domain,
         companyName: options.companyName
     };
-    const leads = await leadProvider.generateLeads(icp, count, target);
-    await writeJsonFile(options.out, leads);
-    printOutput({ status: "ok", generated: leads.length, out: options.out, target: target.companyDomain ?? null });
+    const result = await leadProvider.generateLeads(icp, count, target);
+    await writeJsonFile(options.out, result.leads);
+    printOutput({
+        status: "ok",
+        generated: result.leads.length,
+        out: options.out,
+        target: result.account.domain,
+        provider: result.provider,
+        mode: result.mode,
+        account: result.account,
+        warnings: result.warnings
+    });
 });
 program
     .command("leads:enrich")
@@ -98,17 +419,491 @@ program
 });
 program
     .command("sync:outreach")
-    .description("Dry-run sync scored leads into an outreach platform.")
+    .description("Sync scored leads into an outreach platform. Instantly supports real writes and defaults to dry-run.")
     .requiredOption("--target <target>", "apollo|instantly|outreach")
     .requiredOption("--in <path>", "Path to scored lead JSON array")
+    .option("--campaign-id <id>", "Instantly campaign id, or set INSTANTLY_CAMPAIGN_ID")
+    .option("--apply", "Create leads in Instantly instead of dry-run", false)
+    .option("--allow-duplicates", "Do not skip emails already present in the Instantly campaign", false)
     .action(async (options) => {
     const target = SyncTargetSchema.parse(options.target);
     const leads = await readJsonFile(options.in, z.array(ScoredLeadSchema));
-    const result = await syncProvider.sync(target, leads);
+    const result = await syncProvider.sync(target, leads, {
+        apply: Boolean(options.apply),
+        instantlyCampaignId: options.campaignId,
+        allowDuplicates: Boolean(options.allowDuplicates)
+    });
     printOutput({ status: "ok", ...result });
 });
+program
+    .command("leads:lookup:bq")
+    .description("Build a BigQuery lead lookup from an ICP and optionally execute it with the bq CLI.")
+    .requiredOption("--icp <path>", "Path to ICP JSON")
+    .option("--table <table>", "Fully qualified BigQuery table or view", "icpidentifier.SalesGPT.leadPool_new")
+    .option("--company-field <field>", "Company name field", "companyName")
+    .option("--domain-field <field>", "Company domain field", "domain")
+    .option("--region-field <field>", "Region field if your table has one")
+    .option("--keyword-fields <items>", "Comma-separated text fields used for keyword matching", "companyName,industry,description,tagline,specialties")
+    .option("--title-field <field>", "Contact title field", "jobTitle")
+    .option("--industry-field <field>", "Industry field", "industry")
+    .option("--company-size-field <field>", "Company size field", "companySize")
+    .option("--country-field <field>", "Country or region field", "company_countryCode")
+    .option("--first-name-field <field>", "First name field", "firstName")
+    .option("--last-name-field <field>", "Last name field", "lastName")
+    .option("--email-field <field>", "Email field", "email")
+    .option("--additional-where <sql>", "Extra WHERE predicate to append")
+    .option("--limit <number>", "Max rows to return", "200")
+    .option("--sql-out <path>", "Optional file path for generated SQL")
+    .option("--out <path>", "Optional file path for query results JSON")
+    .option("--lead-out <path>", "Optional file path for normalized lead JSON")
+    .option("--execute", "Run the generated query via bq")
+    .option("--no-salesprompter-guards", "Disable default leadPool_new quality guards")
+    .action(async (options) => {
+    const icp = await readJsonFile(options.icp, IcpSchema);
+    const limit = z.coerce.number().int().min(1).max(5000).parse(options.limit);
+    const sql = buildBigQueryLeadLookupSql(icp, {
+        table: options.table,
+        companyField: options.companyField,
+        domainField: options.domainField,
+        regionField: options.regionField,
+        keywordFields: splitCsv(options.keywordFields),
+        titleField: options.titleField,
+        industryField: options.industryField,
+        companySizeField: options.companySizeField,
+        countryField: options.countryField,
+        firstNameField: options.firstNameField,
+        lastNameField: options.lastNameField,
+        emailField: options.emailField,
+        limit,
+        additionalWhere: options.additionalWhere,
+        useSalesprompterGuards: Boolean(options.salesprompterGuards)
+    });
+    if (options.sqlOut) {
+        await writeTextFile(options.sqlOut, `${sql}\n`);
+    }
+    if (!options.execute) {
+        printOutput({
+            status: "ok",
+            mode: "sql-only",
+            table: options.table,
+            sql,
+            sqlOut: options.sqlOut ?? null
+        });
+        return;
+    }
+    const rows = await runBigQueryQuery(sql, { maxRows: limit });
+    if (options.out) {
+        await writeJsonFile(options.out, rows);
+    }
+    if (options.leadOut) {
+        const normalizedLeads = normalizeBigQueryLeadRows(z.array(z.record(z.string(), z.unknown())).parse(rows));
+        await writeJsonFile(options.leadOut, normalizedLeads);
+    }
+    printOutput({
+        status: "ok",
+        mode: "executed",
+        table: options.table,
+        rowCount: Array.isArray(rows) ? rows.length : null,
+        out: options.out ?? null,
+        leadOut: options.leadOut ?? null,
+        sqlOut: options.sqlOut ?? null
+    });
+});
+program
+    .command("queries:analyze:bq")
+    .description("Analyze historical query parameters from BigQuery tables.")
+    .option("--tables <items>", "Comma-separated BigQuery tables with a query column", "leadLists_raw,leadLists_unique,linkedinSearchExport_people_unique,salesNavigatorSearchExport_companies_unique,snse_containers_input")
+    .option("--search-kind <kind>", "all|people|sales-people|sales-company", "all")
+    .option("--include-function <items>", "Comma-separated included function texts to keep, e.g. Human Resources", "")
+    .requiredOption("--out <path>", "Output report path")
+    .action(async (options) => {
+    const searchKind = z.enum(["all", "people", "sales-people", "sales-company"]).parse(options.searchKind);
+    const tables = splitCsv(options.tables);
+    if (tables.length === 0) {
+        throw new Error("at least one table is required");
+    }
+    const rows = await fetchHistoricalQueryRows(tables);
+    const report = analyzeHistoricalQueries(rows, {
+        searchKind,
+        includeFunctionText: splitCsv(options.includeFunction)
+    });
+    await writeJsonFile(options.out, report);
+    printOutput({
+        status: "ok",
+        distinctQueryRowsAnalyzed: report.distinctQueryRowsAnalyzed,
+        weightedQueryVolume: report.weightedQueryVolume,
+        out: options.out,
+        sourceTables: report.sourceTables
+    });
+});
+program
+    .command("leadlists:funnel:bq")
+    .description("Build an upstream lead-list funnel report for a vendor/market.")
+    .requiredOption("--vendor <vendor>", "Vendor template name, currently: deel")
+    .option("--market <market>", "global|europe|dach", "dach")
+    .requiredOption("--out <path>", "Output report path")
+    .action(async (options) => {
+    const vendor = z.enum(["deel"]).parse(options.vendor);
+    const market = z.enum(["global", "europe", "dach"]).parse(options.market);
+    const definition = buildLeadlistsFunnelQueries(vendor, market);
+    const stages = [];
+    for (const stage of definition.stages) {
+        const rows = await runBigQueryRows(stage.sql, { maxRows: 1000 });
+        const result = rows[0] ?? {};
+        stages.push({
+            key: stage.key,
+            description: stage.description,
+            result
+        });
+    }
+    const report = {
+        vendor,
+        market,
+        queryTerms: definition.queryTerms,
+        stages,
+        notes: definition.notes,
+        requiredFields: {
+            upstreamPeople: ["profileUrl", "companyUrl", "firstName", "lastName", "jobTitle"],
+            upstreamCompany: ["companyUrl", "handle", "domain", "countryCode", "companySize"],
+            downstreamContact: ["firstName_cleaned", "lastName_cleaned", "domain", "email", "email_invalid"]
+        }
+    };
+    await writeJsonFile(options.out, report);
+    printOutput({
+        status: "ok",
+        vendor,
+        market,
+        out: options.out,
+        stages: stages.map((stage) => ({ key: stage.key, result: stage.result }))
+    });
+});
+program
+    .command("domainfinder:backlog:bq")
+    .description("Analyze the domain finder backlog and its input bottleneck.")
+    .option("--market <market>", "global|europe|dach", "dach")
+    .requiredOption("--out <path>", "Output report path")
+    .action(async (options) => {
+    const market = z.enum(["global", "europe", "dach"]).parse(options.market);
+    const definition = buildDomainfinderBacklogQueries(market);
+    const stages = [];
+    for (const stage of definition.stages) {
+        const rows = await runBigQueryRows(stage.sql, { maxRows: 1000 });
+        stages.push({
+            key: stage.key,
+            description: stage.description,
+            result: rows[0] ?? {}
+        });
+    }
+    const report = {
+        market,
+        countries: definition.countries,
+        stages,
+        notes: definition.notes
+    };
+    await writeJsonFile(options.out, report);
+    printOutput({
+        status: "ok",
+        market,
+        out: options.out,
+        stages: stages.map((stage) => ({ key: stage.key, result: stage.result }))
+    });
+});
+program
+    .command("domainfinder:candidates:bq")
+    .description("Fetch real domain candidates from BigQuery for backlog companies.")
+    .option("--market <market>", "global|europe|dach", "dach")
+    .option("--limit <number>", "Max candidate rows to fetch", "500")
+    .requiredOption("--out <path>", "Output candidate JSON path")
+    .option("--sql-out <path>", "Optional SQL output path")
+    .action(async (options) => {
+    const market = z.enum(["global", "europe", "dach"]).parse(options.market);
+    const limit = z.coerce.number().int().min(1).max(50000).parse(options.limit);
+    const sql = buildDomainfinderCandidatesSql(market, limit);
+    if (options.sqlOut) {
+        await writeTextFile(options.sqlOut, `${sql}\n`);
+    }
+    const rows = await runBigQueryRows(sql, { maxRows: limit });
+    await writeJsonFile(options.out, rows);
+    printOutput({
+        status: "ok",
+        market,
+        candidates: rows.length,
+        out: options.out,
+        sqlOut: options.sqlOut ?? null
+    });
+});
+program
+    .command("domainfinder:input-sql")
+    .description("Generate improved SQL for the domainFinder input view.")
+    .option("--market <market>", "global|europe|dach", "dach")
+    .requiredOption("--out <path>", "Output SQL file path")
+    .action(async (options) => {
+    const market = z.enum(["global", "europe", "dach"]).parse(options.market);
+    const sql = buildDomainfinderInputSql(market);
+    await writeTextFile(options.out, `${sql}\n`);
+    printOutput({ status: "ok", market, out: options.out });
+});
+program
+    .command("domainfinder:select")
+    .description("Select the best domain per company from candidate rows using improved logic.")
+    .requiredOption("--in <path>", "Path to candidate JSON array")
+    .requiredOption("--out <path>", "Output file path")
+    .action(async (options) => {
+    const candidates = await readJsonFile(options.in, domainCandidateArraySchema);
+    const decisions = selectBestDomains(candidates);
+    await writeJsonFile(options.out, decisions);
+    printOutput({
+        status: "ok",
+        companies: decisions.length,
+        out: options.out,
+        reasons: decisions.reduce((acc, decision) => {
+            acc[decision.reason] = (acc[decision.reason] ?? 0) + 1;
+            return acc;
+        }, {})
+    });
+});
+program
+    .command("domainfinder:audit")
+    .description("Audit selected domain decisions and surface risky writeback cases.")
+    .requiredOption("--in <path>", "Path to decision JSON array")
+    .requiredOption("--out <path>", "Output audit JSON path")
+    .action(async (options) => {
+    const decisions = await readJsonFile(options.in, domainDecisionArraySchema);
+    const report = auditDomainDecisions(decisions);
+    await writeJsonFile(options.out, report);
+    printOutput({
+        status: "ok",
+        out: options.out,
+        summary: report.summary
+    });
+});
+program
+    .command("domainfinder:compare-pipedream")
+    .description("Compare the legacy Pipedream selector against the improved CLI selector.")
+    .requiredOption("--in <path>", "Path to candidate JSON array")
+    .requiredOption("--out <path>", "Output comparison JSON path")
+    .action(async (options) => {
+    const candidates = await readJsonFile(options.in, domainCandidateArraySchema);
+    const report = compareDomainSelectionStrategies(candidates);
+    await writeJsonFile(options.out, report);
+    printOutput({
+        status: "ok",
+        out: options.out,
+        summary: report.summary
+    });
+});
+program
+    .command("domainfinder:audit-existing:bq")
+    .description("Audit currently exposed linkedin_companies domains against LinkedIn references in BigQuery.")
+    .option("--market <market>", "global|europe|dach", "dach")
+    .requiredOption("--out <path>", "Output audit JSON path")
+    .action(async (options) => {
+    const market = z.enum(["global", "europe", "dach"]).parse(options.market);
+    const definition = buildExistingDomainAuditQueries(market);
+    const stages = [];
+    for (const stage of definition.stages) {
+        const rows = await runBigQueryRows(stage.sql, { maxRows: stage.key === "samples" ? 100 : 1000 });
+        stages.push({
+            key: stage.key,
+            description: stage.description,
+            rows
+        });
+    }
+    const report = {
+        market,
+        countries: definition.countries,
+        stages
+    };
+    await writeJsonFile(options.out, report);
+    printOutput({
+        status: "ok",
+        out: options.out,
+        market,
+        summary: stages.find((stage) => stage.key === "summary")?.rows[0] ?? {}
+    });
+});
+program
+    .command("domainfinder:audit-delta")
+    .description("Compare two domainfinder audit-existing reports and compute metric deltas.")
+    .requiredOption("--before <path>", "Path to previous audit-existing report")
+    .requiredOption("--after <path>", "Path to newer audit-existing report")
+    .requiredOption("--out <path>", "Output delta JSON path")
+    .action(async (options) => {
+    const before = await readJsonFile(options.before, existingAuditReportSchema);
+    const after = await readJsonFile(options.after, existingAuditReportSchema);
+    const beforeSummary = before.stages.find((stage) => stage.key === "summary")?.rows[0] ?? {};
+    const afterSummary = after.stages.find((stage) => stage.key === "summary")?.rows[0] ?? {};
+    const keys = [
+        "companies",
+        "with_chosen_domain",
+        "with_linkedin_domain",
+        "with_linkedin_website",
+        "chosen_blacklisted",
+        "chosen_starts_with_www",
+        "chosen_differs_from_linkedin_domain",
+        "chosen_differs_from_linkedin_website"
+    ];
+    const delta = {};
+    for (const key of keys) {
+        const beforeValue = Number(beforeSummary[key] ?? 0);
+        const afterValue = Number(afterSummary[key] ?? 0);
+        delta[key] = {
+            before: beforeValue,
+            after: afterValue,
+            delta: afterValue - beforeValue
+        };
+    }
+    const report = {
+        before: {
+            path: options.before,
+            market: before.market
+        },
+        after: {
+            path: options.after,
+            market: after.market
+        },
+        delta
+    };
+    await writeJsonFile(options.out, report);
+    printOutput({
+        status: "ok",
+        out: options.out,
+        delta
+    });
+});
+program
+    .command("domainfinder:repair-existing:bq")
+    .description("Generate targeted repair SQL for existing chosen domains and optionally execute it in BigQuery.")
+    .option("--market <market>", "global|europe|dach", "dach")
+    .option("--limit <number>", "Max companies to repair in this batch", "5000")
+    .option("--mode <mode>", "conservative|aggressive|mismatch-only", "conservative")
+    .requiredOption("--out <path>", "Output SQL file path")
+    .option("--trace-id <traceId>", "Trace id for this repair batch")
+    .option("--execute", "Execute the generated SQL in BigQuery", false)
+    .action(async (options) => {
+    const market = z.enum(["global", "europe", "dach"]).parse(options.market);
+    const limit = z.coerce.number().int().min(1).max(500000).parse(options.limit);
+    const mode = z.enum(["conservative", "aggressive", "mismatch-only"]).parse(options.mode);
+    const traceId = z.string().min(1).parse(options.traceId ?? `salesprompter-cli-repair-${market}-${Date.now()}`);
+    const sql = buildExistingDomainRepairSql(market, traceId, limit, mode);
+    await writeTextFile(options.out, `${sql}\n`);
+    let execution = null;
+    if (options.execute) {
+        const stdout = await executeBigQuerySql(sql);
+        execution = { executed: true, stdout };
+    }
+    printOutput({
+        status: "ok",
+        market,
+        limit,
+        mode,
+        traceId,
+        out: options.out,
+        execution
+    });
+});
+program
+    .command("domainfinder:writeback-sql")
+    .description("Generate conservative writeback SQL for domainFinder_output from audited decisions.")
+    .requiredOption("--in <path>", "Path to decision JSON array")
+    .requiredOption("--out <path>", "Output SQL file path")
+    .option("--trace-id <traceId>", "Trace id for this writeback batch")
+    .action(async (options) => {
+    const decisions = await readJsonFile(options.in, domainDecisionArraySchema);
+    const traceId = z.string().min(1).parse(options.traceId ?? `salesprompter-cli-${Date.now()}`);
+    const sql = buildDomainfinderWritebackSql(decisions, traceId);
+    await writeTextFile(options.out, `${sql}\n`);
+    const report = auditDomainDecisions(decisions);
+    printOutput({
+        status: "ok",
+        out: options.out,
+        traceId,
+        acceptedForWriteback: report.summary.acceptedForWriteback,
+        rejectedForWriteback: report.summary.rejectedForWriteback
+    });
+});
+program
+    .command("domainfinder:writeback:bq")
+    .description("Generate writeback SQL and optionally execute it against domainFinder_output.")
+    .requiredOption("--in <path>", "Path to decision JSON array")
+    .requiredOption("--out <path>", "Output SQL file path")
+    .option("--trace-id <traceId>", "Trace id for this writeback batch")
+    .option("--execute", "Execute the generated SQL in BigQuery", false)
+    .action(async (options) => {
+    const decisions = await readJsonFile(options.in, domainDecisionArraySchema);
+    const traceId = z.string().min(1).parse(options.traceId ?? `salesprompter-cli-${Date.now()}`);
+    const sql = buildDomainfinderWritebackSql(decisions, traceId);
+    await writeTextFile(options.out, `${sql}\n`);
+    const report = auditDomainDecisions(decisions);
+    let execution = null;
+    if (options.execute) {
+        const stdout = await executeBigQuerySql(sql);
+        execution = { executed: true, stdout };
+    }
+    printOutput({
+        status: "ok",
+        out: options.out,
+        traceId,
+        acceptedForWriteback: report.summary.acceptedForWriteback,
+        rejectedForWriteback: report.summary.rejectedForWriteback,
+        execution
+    });
+});
+program
+    .command("domainfinder:run:bq")
+    .description("Run the full domainfinder pipeline: candidates, select, audit, writeback SQL, optional BigQuery execution.")
+    .option("--market <market>", "global|europe|dach", "dach")
+    .option("--limit <number>", "Max candidate rows to fetch", "500")
+    .requiredOption("--out-dir <path>", "Output directory for artifacts")
+    .option("--trace-id <traceId>", "Trace id for this pipeline batch")
+    .option("--execute-writeback", "Execute the generated writeback SQL in BigQuery", false)
+    .action(async (options) => {
+    const market = z.enum(["global", "europe", "dach"]).parse(options.market);
+    const limit = z.coerce.number().int().min(1).max(50000).parse(options.limit);
+    const outDir = z.string().min(1).parse(options.outDir);
+    const traceId = z.string().min(1).parse(options.traceId ?? `salesprompter-cli-${market}-${Date.now()}`);
+    const candidatesPath = `${outDir}/domain-candidates-${market}.json`;
+    const candidatesSqlPath = `${outDir}/domain-candidates-${market}.sql`;
+    const decisionsPath = `${outDir}/domain-decisions-${market}.json`;
+    const auditPath = `${outDir}/domain-audit-${market}.json`;
+    const writebackSqlPath = `${outDir}/domain-writeback-${market}.sql`;
+    const candidateSql = buildDomainfinderCandidatesSql(market, limit);
+    await writeTextFile(candidatesSqlPath, `${candidateSql}\n`);
+    const candidateRows = await runBigQueryRows(candidateSql, { maxRows: limit });
+    await writeJsonFile(candidatesPath, candidateRows);
+    const candidates = domainCandidateArraySchema.parse(candidateRows);
+    const decisions = selectBestDomains(candidates);
+    await writeJsonFile(decisionsPath, decisions);
+    const audit = auditDomainDecisions(decisions);
+    await writeJsonFile(auditPath, audit);
+    const writebackSql = buildDomainfinderWritebackSql(decisions, traceId);
+    await writeTextFile(writebackSqlPath, `${writebackSql}\n`);
+    let execution = null;
+    if (options.executeWriteback) {
+        const stdout = await executeBigQuerySql(writebackSql);
+        execution = { executed: true, stdout };
+    }
+    printOutput({
+        status: "ok",
+        market,
+        limit,
+        traceId,
+        candidatesPath,
+        decisionsPath,
+        auditPath,
+        writebackSqlPath,
+        summary: audit.summary,
+        execution
+    });
+});
 program.parseAsync(process.argv).catch((error) => {
-    const message = error instanceof Error ? error.message : "Unknown error";
-    process.stderr.write(`${message}\n`);
-    process.exitCode = 1;
+    const cliError = buildCliError(error);
+    const space = runtimeOutputOptions.json ? undefined : 2;
+    if (runtimeOutputOptions.json) {
+        process.stderr.write(`${JSON.stringify(cliError, null, space)}\n`);
+    }
+    else {
+        process.stderr.write(`${cliError.message}\n`);
+    }
+    process.exitCode = exitCodeForError(cliError.code);
 });