@movermarketingai/searchlight-cli 0.1.0

package/bin/searchlight.js

@@ -0,0 +1,1471 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { chmod, mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const defaultBaseUrl = "https://searchlight.movermarketing.ai";
+const defaultTokenFilePath = join(homedir(), ".config", "searchlight", "token");
+const scopeLabels = {
+  all: "All pages",
+  content: "Content group",
+  specific: "Specific pages",
+};
+const booleanArgKeys = new Set(["dryRun", "includeNoWebsite", "json", "tokenStdin", "yes"]);
+
+const rootAnnotationCommands = new Set([
+  "sites",
+  "list",
+  "add",
+  "add-from-annotate",
+  "update",
+  "update-from-annotate",
+  "delete",
+]);
+
+function usage(exitCode = 0) {
+  console.log(`Usage:
+  mmai-searchlight help
+  mmai-searchlight setup
+  npm run searchlight -- help
+
+Authentication:
+  mmai-searchlight setup
+  mmai-searchlight auth store --token-stdin [--json]
+  mmai-searchlight auth check [--json]
+  mmai-searchlight auth path [--json]
+  mmai-searchlight auth logout [--yes] [--json]
+
+Clients:
+  mmai-searchlight clients list [--json]
+  mmai-searchlight clients add --name NAME --gsc-property PROPERTY [--site-slug SLUG] [--ga4-property PROPERTY] [--json]
+  mmai-searchlight clients import-report-portal [--dry-run] [--yes] [--json] [--match TEXT] [--limit N] [--property-mode auto|url-prefix|domain] [--ga4-mode auto|off] [--refresh-mode none|gsc|all]
+
+Content runs:
+  mmai-searchlight content-runs list --site SITE [--json]
+  mmai-searchlight content-runs add --site SITE --file content-pipeline/runs/RUN/manifest.json [--dry-run] [--json]
+  mmai-searchlight content-runs ingest --site SITE --file content-pipeline/runs/RUN/manifest.json [--dry-run] [--json]
+
+Annotations:
+  mmai-searchlight annotations sites [--json]
+  mmai-searchlight annotations list --site SITE [--json]
+  mmai-searchlight annotations add --site SITE --title TITLE --summary TEXT [--date YYYY-MM-DD] [--scope all|specific|content] [--page URL_OR_PATH ...] [--dry-run]
+  mmai-searchlight annotations add-from-annotate --site SITE --file FILE|- [--date YYYY-MM-DD] [--dry-run]
+  mmai-searchlight annotations update --site SITE --id ID [--title TITLE] [--summary TEXT] [--date YYYY-MM-DD] [--scope all|specific|content] [--page URL_OR_PATH ...] [--dry-run]
+  mmai-searchlight annotations update-from-annotate --site SITE --id ID --file FILE|- [--date YYYY-MM-DD] [--dry-run]
+  mmai-searchlight annotations delete --site SITE --id ID --yes
+
+SEO tests:
+  mmai-searchlight tests list --site SITE [--json]
+  mmai-searchlight tests refresh --site SITE [--json]
+  mmai-searchlight tests run --site SITE [--json]
+
+Legacy annotation shortcuts are still supported:
+  npm run annotations -- sites
+  npm run annotations -- add-from-annotate --site SITE --file annotation.txt
+
+Environment:
+  SEARCHLIGHT_TOKEN           Preferred explicit bearer token override.
+  SEARCHLIGHT_WORKER_TOKEN    Scoped worker bearer token for internal workers.
+  SEARCHLIGHT_TOKEN_FILE      Optional token file path; defaults to ${defaultTokenFilePath}.
+  SEARCHLIGHT_BASE_URL        Optional; defaults to ${defaultBaseUrl}.
+`);
+  process.exit(exitCode);
+}
+
+function parseArgs(argv) {
+  const [command, ...tokens] = argv;
+  const options = { _: [], command, page: [] };
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+
+    if (!token.startsWith("--")) {
+      options._.push(token);
+      continue;
+    }
+
+    const [rawKey, inlineValue] = token.slice(2).split("=", 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+
+    if (booleanArgKeys.has(key)) {
+      options[key] = inlineValue === undefined ? true : inlineValue !== "false";
+      continue;
+    }
+
+    const value = inlineValue ?? tokens[index + 1];
+
+    if (typeof value !== "string" || value.startsWith("--")) {
+      throw new Error(`--${rawKey} requires a value.`);
+    }
+
+    if (inlineValue === undefined) {
+      index += 1;
+    }
+
+    if (key === "page") {
+      options.page.push(value);
+    } else {
+      options[key] = value;
+    }
+  }
+
+  return options;
+}
+
+function requireOption(options, key) {
+  const value = options[key];
+
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`--${key} is required.`);
+  }
+
+  return value.trim();
+}
+
+function optionalString(value) {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function getBaseUrl(options) {
+  return (options.baseUrl ?? process.env.SEARCHLIGHT_BASE_URL ?? defaultBaseUrl).replace(/\/$/, "");
+}
+
+function getTokenFilePath() {
+  return process.env.SEARCHLIGHT_TOKEN_FILE ?? defaultTokenFilePath;
+}
+
+async function readStoredToken() {
+  const tokenFilePath = getTokenFilePath();
+
+  try {
+    const [contents, fileStats] = await Promise.all([
+      readFile(tokenFilePath, "utf8"),
+      stat(tokenFilePath),
+    ]);
+    const unsafeModeBits = fileStats.mode & 0o077;
+
+    if (unsafeModeBits !== 0) {
+      console.error(
+        `Warning: ${tokenFilePath} is readable by group/other users. Run: chmod 600 ${tokenFilePath}`,
+      );
+    }
+
+    return contents.trim() || undefined;
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return undefined;
+    }
+
+    throw error;
+  }
+}
+
+async function getAuthToken() {
+  const token =
+    process.env.SEARCHLIGHT_TOKEN ??
+    process.env.SEARCHLIGHT_WORKER_TOKEN ??
+    (await readStoredToken());
+
+  if (!token) {
+    throw new Error(
+      `No Searchlight CLI token found. Run "mmai-searchlight setup" for safe storage instructions, set SEARCHLIGHT_TOKEN, or store a token at ${getTokenFilePath()}.`,
+    );
+  }
+
+  return token;
+}
+
+async function hasConfiguredAuthToken() {
+  return Boolean(
+    process.env.SEARCHLIGHT_TOKEN ??
+    process.env.SEARCHLIGHT_WORKER_TOKEN ??
+    (await readStoredToken()),
+  );
+}
+
+function todayApiDate() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function normalizeScope(value = "specific") {
+  const normalized = value.toLowerCase().replace(/\s+/g, "_");
+
+  if (normalized === "all" || normalized === "all_pages") {
+    return scopeLabels.all;
+  }
+
+  if (normalized === "content" || normalized === "content_group") {
+    return scopeLabels.content;
+  }
+
+  return scopeLabels.specific;
+}
+
+function getPagesForScope(scope, pages) {
+  if (scope === scopeLabels.all) {
+    return ["All pages"];
+  }
+
+  return pages.length > 0 ? pages : ["/"];
+}
+
+function createFormData(input) {
+  const formData = new FormData();
+
+  for (const [key, value] of Object.entries(input)) {
+    if (Array.isArray(value)) {
+      formData.set(key, value.join("\n"));
+    } else if (value !== undefined) {
+      formData.set(key, String(value));
+    }
+  }
+
+  return formData;
+}
+
+function parseResponseBody(text) {
+  if (!text) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { rawText: text };
+  }
+}
+
+function getResponseErrorMessage(response, body) {
+  if (typeof body.error === "string" && body.error.trim()) {
+    return body.error;
+  }
+
+  if (typeof body.rawText === "string" && body.rawText.trim()) {
+    const excerpt = body.rawText.replace(/\s+/g, " ").trim().slice(0, 240);
+
+    return `Searchlight API returned ${response.status}: ${excerpt}`;
+  }
+
+  return `Searchlight API returned ${response.status}.`;
+}
+
+async function requestJson(options, path, init = {}) {
+  const response = await fetch(`${getBaseUrl(options)}${path}`, {
+    ...init,
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${await getAuthToken()}`,
+      ...(init.headers ?? {}),
+    },
+  });
+  const text = await response.text();
+  const body = parseResponseBody(text);
+
+  if (!response.ok) {
+    throw new Error(getResponseErrorMessage(response, body));
+  }
+
+  if (body.rawText) {
+    throw new Error("Searchlight API returned a non-JSON response.");
+  }
+
+  return body;
+}
+
+function formatMappingRow(mapping, fallback = {}) {
+  return [
+    mapping.siteSlug,
+    mapping.siteName,
+    mapping.gscPropertyId ?? fallback.gscPropertyId ?? "",
+    mapping.ga4PropertyId ?? fallback.ga4PropertyId ?? "",
+  ].join("\t");
+}
+
+function formatContentRunRow(contentRun) {
+  return `${contentRun.runId}\t${contentRun.status}\t${contentRun.affectedUrls?.join(",") ?? ""}`;
+}
+
+function formatAnnotationTestRow(test) {
+  return [
+    test.annotationId,
+    test.status,
+    test.primaryMetric,
+    test.testRange,
+    test.title,
+  ].join("\t");
+}
+
+function printResult(options, value) {
+  if (options.json) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+
+  if (Array.isArray(value.sites)) {
+    for (const site of value.sites) {
+      console.log(`${site.slug}\t${site.name}\t${site.propertyId}`);
+    }
+    return;
+  }
+
+  if (Array.isArray(value.annotations)) {
+    for (const annotation of value.annotations) {
+      console.log(`${annotation.annotationId}\t${annotation.date}\t${annotation.title}`);
+    }
+    return;
+  }
+
+  if (Array.isArray(value.contentRuns)) {
+    for (const run of value.contentRuns) {
+      console.log(formatContentRunRow(run));
+    }
+    return;
+  }
+
+  if (Array.isArray(value.tests)) {
+    for (const test of value.tests) {
+      console.log(formatAnnotationTestRow(test));
+    }
+    return;
+  }
+
+  if (Array.isArray(value.mappings)) {
+    for (const mapping of value.mappings) {
+      console.log(formatMappingRow(mapping));
+    }
+    return;
+  }
+
+  console.log(JSON.stringify(value, null, 2));
+}
+
+async function listSites(options) {
+  printResult(options, await requestJson(options, "/api/sites"));
+}
+
+async function listAnnotations(options) {
+  const site = requireOption(options, "site");
+
+  printResult(options, await requestJson(options, `/api/sites/${site}/annotations`));
+}
+
+async function listTests(options) {
+  const site = requireOption(options, "site");
+
+  printResult(options, await requestJson(options, `/api/sites/${site}/annotations/tests`));
+}
+
+async function refreshTests(options) {
+  const site = requireOption(options, "site");
+
+  printResult(
+    options,
+    await postJson(options, `/api/sites/${site}/annotations/tests/run`),
+  );
+}
+
+async function listContentRuns(options) {
+  const site = requireOption(options, "site");
+
+  printResult(options, await requestJson(options, `/api/sites/${site}/content-runs`));
+}
+
+async function addContentRun(options) {
+  const site = requireOption(options, "site");
+  const file = requireOption(options, "file");
+  const manifest = JSON.parse(await readTextInput(file));
+
+  if (options.dryRun) {
+    printResult(options, {
+      manifest,
+      site,
+      status: "dry-run",
+    });
+    return;
+  }
+
+  printResult(
+    options,
+    await postJson(options, `/api/sites/${site}/content-runs`, { manifest }),
+  );
+}
+
+function annotationInputFromOptions(options, existing = {}) {
+  const scope = normalizeScope(options.scope ?? existing.scope);
+  const pages = options.page.length > 0 ? options.page : existing.pages ?? [];
+
+  return {
+    date: options.date ?? existing.dateInput ?? todayApiDate(),
+    pages: getPagesForScope(scope, pages),
+    scope,
+    summary: options.summary ?? existing.summary,
+    title: options.title ?? existing.title,
+  };
+}
+
+function validateAnnotationInput(input) {
+  if (!input.title) {
+    throw new Error("--title is required.");
+  }
+
+  if (!input.summary) {
+    throw new Error("--summary is required.");
+  }
+
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(input.date)) {
+    throw new Error("--date must be YYYY-MM-DD.");
+  }
+}
+
+async function submitAnnotation(options, action, input, annotationId) {
+  const site = requireOption(options, "site");
+  validateAnnotationInput(input);
+
+  if (options.dryRun) {
+    return {
+      action,
+      annotation: input,
+      annotationId,
+      site,
+      status: "dry-run",
+    };
+  }
+
+  const formData = createFormData({
+    _action: action,
+    annotationId,
+    ...input,
+  });
+
+  return requestJson(options, `/api/sites/${site}/annotations`, {
+    body: formData,
+    method: "POST",
+  });
+}
+
+async function addAnnotation(options) {
+  const input = annotationInputFromOptions(options);
+  const result = await submitAnnotation(options, "create", input);
+
+  printResult(options, result);
+}
+
+function parseAnnotateText(text) {
+  const titleMatch = text.match(/Annotation title:\s*([\s\S]*?)(?:\n\s*Summary of changes:|$)/i);
+  const summaryMatch = text.match(/Summary of changes:\s*([\s\S]*?)(?:\n\s*URLs affected:|$)/i);
+  const urlsMatch = text.match(/URLs affected:\s*(?:```\w*\s*)?([\s\S]*?)(?:```|$)/i);
+  const pages = (urlsMatch?.[1] ?? "")
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^[-*]\s*/, "").trim())
+    .filter(Boolean);
+
+  return {
+    pages,
+    summary: (summaryMatch?.[1] ?? "").trim(),
+    title: (titleMatch?.[1] ?? "").trim(),
+  };
+}
+
+async function readTextInput(file) {
+  if (!file || file === "-") {
+    const chunks = [];
+
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+
+    return Buffer.concat(chunks).toString("utf8");
+  }
+
+  return readFile(file, "utf8");
+}
+
+function printSetupInstructions() {
+  const tokenFilePath = getTokenFilePath();
+
+  console.log(`Searchlight CLI setup
+
+1. Get a provisioned CLI token from Searchlight Workspace Settings or from your Searchlight admin.
+2. Store it without putting it in shell history:
+
+   read -rsp "Searchlight CLI token: " SEARCHLIGHT_TOKEN && echo && \\
+   printf '%s' "$SEARCHLIGHT_TOKEN" | mmai-searchlight auth store --token-stdin && \\
+   unset SEARCHLIGHT_TOKEN
+
+3. Validate access:
+
+   mmai-searchlight auth check
+   mmai-searchlight annotations sites --json
+
+Token file: ${tokenFilePath}
+Production API: ${defaultBaseUrl}
+
+Anyone can install this CLI, but Searchlight only honors server-issued, scoped, unrevoked tokens.`);
+}
+
+async function storeAuthToken(options) {
+  if (!options.tokenStdin) {
+    throw new Error("Use --token-stdin so the raw token is read from stdin instead of command history.");
+  }
+
+  const token = (await readTextInput("-")).trim();
+
+  if (!token) {
+    throw new Error("No token was provided on stdin.");
+  }
+
+  const tokenFilePath = getTokenFilePath();
+
+  await mkdir(dirname(tokenFilePath), { mode: 0o700, recursive: true });
+  await writeFile(tokenFilePath, `${token}\n`, { mode: 0o600 });
+  await chmod(tokenFilePath, 0o600);
+
+  if (options.json) {
+    console.log(JSON.stringify({ status: "stored", tokenFile: tokenFilePath }, null, 2));
+    return;
+  }
+
+  console.log(`Stored Searchlight CLI token at ${tokenFilePath}`);
+  console.log("Run: mmai-searchlight auth check");
+}
+
+async function checkAuth(options) {
+  const result = await requestJson(options, "/api/sites");
+  const siteCount = result.sites?.length ?? 0;
+
+  if (options.json) {
+    console.log(JSON.stringify({ baseUrl: getBaseUrl(options), siteCount, status: "ok" }, null, 2));
+    return;
+  }
+
+  console.log(`Authenticated against ${getBaseUrl(options)}. Sites available: ${siteCount}`);
+}
+
+async function printAuthPath(options) {
+  const tokenFilePath = getTokenFilePath();
+
+  if (options.json) {
+    console.log(JSON.stringify({ tokenFile: tokenFilePath }, null, 2));
+    return;
+  }
+
+  console.log(tokenFilePath);
+}
+
+async function logoutAuth(options) {
+  const tokenFilePath = getTokenFilePath();
+
+  if (!options.yes) {
+    throw new Error("Refusing to remove the stored token without --yes.");
+  }
+
+  try {
+    await unlink(tokenFilePath);
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ status: "removed", tokenFile: tokenFilePath }, null, 2));
+    return;
+  }
+
+  console.log(`Removed stored Searchlight CLI token from ${tokenFilePath}`);
+}
+
+async function runAuthCommand(command, options) {
+  switch (command) {
+    case "store":
+      await storeAuthToken(options);
+      break;
+    case "check":
+    case "status":
+      await checkAuth(options);
+      break;
+    case "path":
+      await printAuthPath(options);
+      break;
+    case "logout":
+      await logoutAuth(options);
+      break;
+    case "help":
+    case "--help":
+    case undefined:
+      usage(0);
+      break;
+    default:
+      throw new Error(`Unknown auth command: ${command}`);
+  }
+}
+
+function annotateOptions(options, parsed, existing = {}) {
+  return {
+    ...options,
+    page: parsed.pages.length > 0 ? parsed.pages : existing.pages ?? [],
+    scope: parsed.pages.length > 0 ? scopeLabels.specific : existing.scope ?? scopeLabels.all,
+    summary: parsed.summary || existing.summary,
+    title: parsed.title || existing.title,
+  };
+}
+
+async function addFromAnnotate(options) {
+  const parsed = parseAnnotateText(await readTextInput(requireOption(options, "file")));
+  const input = annotationInputFromOptions(annotateOptions(options, parsed));
+  const result = await submitAnnotation(options, "create", input);
+
+  printResult(options, result);
+}
+
+function toInputDate(value) {
+  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return value;
+  }
+
+  const parsed = Date.parse(`${value} UTC`);
+
+  if (Number.isNaN(parsed)) {
+    return todayApiDate();
+  }
+
+  return new Date(parsed).toISOString().slice(0, 10);
+}
+
+async function getExistingAnnotation(options) {
+  const site = requireOption(options, "site");
+  const annotationId = requireOption(options, "id");
+  const annotations = (await requestJson(options, `/api/sites/${site}/annotations`)).annotations;
+  const existing = annotations.find((annotation) => annotation.annotationId === annotationId);
+
+  if (!existing) {
+    throw new Error(`Annotation not found: ${annotationId}`);
+  }
+
+  return { annotationId, existing };
+}
+
+async function updateAnnotation(options) {
+  const { annotationId, existing } = await getExistingAnnotation(options);
+  const input = annotationInputFromOptions(options, {
+    ...existing,
+    dateInput: toInputDate(existing.date),
+  });
+  const result = await submitAnnotation(options, "update", input, annotationId);
+
+  printResult(options, result);
+}
+
+async function updateFromAnnotate(options) {
+  const { annotationId, existing } = await getExistingAnnotation(options);
+  const parsed = parseAnnotateText(await readTextInput(requireOption(options, "file")));
+  const input = annotationInputFromOptions(annotateOptions(options, parsed, existing), {
+    ...existing,
+    dateInput: toInputDate(existing.date),
+  });
+  const result = await submitAnnotation(options, "update", input, annotationId);
+
+  printResult(options, result);
+}
+
+async function deleteAnnotation(options) {
+  const site = requireOption(options, "site");
+  const annotationId = requireOption(options, "id");
+
+  if (options.dryRun) {
+    printResult(options, {
+      action: "delete",
+      annotationId,
+      site,
+      status: "dry-run",
+    });
+    return;
+  }
+
+  if (!options.yes) {
+    throw new Error("Refusing to delete without --yes.");
+  }
+
+  const result = await requestJson(options, `/api/sites/${site}/annotations`, {
+    body: createFormData({ _action: "delete", annotationId }),
+    method: "POST",
+  });
+
+  printResult(options, result);
+}
+
+function slugify(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+}
+
+function normalizeWebsiteUrl(value) {
+  const raw = optionalString(value);
+
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    const withScheme = /^[a-z][a-z0-9+.-]*:/i.test(raw) ? raw : `https://${raw}`;
+    const url = new URL(withScheme);
+    url.hash = "";
+    url.search = "";
+
+    if (!url.pathname || url.pathname === "") {
+      url.pathname = "/";
+    }
+
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+function domainPropertyFromUrl(url) {
+  return `sc-domain:${url.hostname.replace(/^www\./i, "")}`;
+}
+
+function urlPrefixPropertyFromUrl(url) {
+  if (url.pathname === "/") {
+    return `${url.origin}/`;
+  }
+
+  return url.href;
+}
+
+function getAlternateHost(hostname) {
+  if (hostname.startsWith("www.")) {
+    return hostname.replace(/^www\./, "");
+  }
+
+  return `www.${hostname}`;
+}
+
+function urlPrefixPropertyCandidatesFromUrl(url) {
+  const primaryProperty = urlPrefixPropertyFromUrl(url);
+
+  if (url.pathname !== "/") {
+    return [primaryProperty];
+  }
+
+  const alternateUrl = new URL(url.href);
+  alternateUrl.hostname = getAlternateHost(url.hostname);
+
+  return [primaryProperty, urlPrefixPropertyFromUrl(alternateUrl)];
+}
+
+function getChoiceOption(options, key, fallback, allowedValues) {
+  const value = options[key] ?? fallback;
+
+  if (allowedValues.includes(value)) {
+    return value;
+  }
+
+  const flag = key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+  throw new Error(`--${flag} must be ${allowedValues.join(", ")}.`);
+}
+
+function getPropertyMode(options) {
+  return getChoiceOption(
+    options,
+    "propertyMode",
+    "auto",
+    ["auto", "domain", "url-prefix"],
+  );
+}
+
+function getGa4Mode(options) {
+  return getChoiceOption(options, "ga4Mode", "auto", ["auto", "off"]);
+}
+
+function getRefreshMode(options) {
+  return getChoiceOption(options, "refreshMode", "gsc", ["none", "gsc", "all"]);
+}
+
+function getGscOwnersForProperty(inventory, propertyId) {
+  if (!propertyId) {
+    return [];
+  }
+
+  return [...(inventory.gscOwnersByProperty.get(propertyId) ?? new Set())].sort();
+}
+
+function propertyFromWebsiteUrl(url, propertyMode, inventory) {
+  const domainProperty = domainPropertyFromUrl(url);
+  const urlPrefixCandidates = urlPrefixPropertyCandidatesFromUrl(url);
+  const availableProperties = inventory.gscOwnersByProperty;
+
+  if (propertyMode === "domain") {
+    return domainProperty;
+  }
+
+  if (propertyMode === "auto") {
+    if (availableProperties.has(domainProperty)) {
+      return domainProperty;
+    }
+
+    return (
+      urlPrefixCandidates.find((property) => availableProperties.has(property)) ??
+      urlPrefixCandidates[0]
+    );
+  }
+
+  return urlPrefixCandidates[0];
+}
+
+function normalizeDomain(value) {
+  return value.toLowerCase().replace(/^www\./, "");
+}
+
+function getDomainFromUri(value) {
+  const url = normalizeWebsiteUrl(value);
+
+  return url ? normalizeDomain(url.hostname) : null;
+}
+
+function ga4MatchesWebsite(ga4Property, websiteUrl) {
+  if (!websiteUrl) {
+    return false;
+  }
+
+  const domain = normalizeDomain(websiteUrl.hostname);
+  const streamUris = ga4Property.streamUris?.length
+    ? ga4Property.streamUris
+    : [ga4Property.defaultUri];
+
+  return streamUris.some((uri) => getDomainFromUri(uri) === domain);
+}
+
+function normalizeMatchName(value) {
+  return optionalString(value)
+    ?.toLowerCase()
+    .replace(/&/g, " and ")
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()
+    .replace(/\s+/g, " ");
+}
+
+function scoreGa4Candidate(property, siteName) {
+  const normalizedSiteName = normalizeMatchName(siteName);
+  const normalizedDisplayName = normalizeMatchName(property.displayName);
+
+  if (!normalizedSiteName || !normalizedDisplayName) {
+    return 0;
+  }
+
+  if (normalizedDisplayName === normalizedSiteName) {
+    return 2;
+  }
+
+  if (normalizedDisplayName.startsWith(`${normalizedSiteName} `)) {
+    return 1;
+  }
+
+  return 0;
+}
+
+function findGa4PropertyMatch({ ga4Mode, gscPropertyId, inventory, siteName, websiteUrl }) {
+  if (ga4Mode === "off" || !websiteUrl || !gscPropertyId) {
+    return null;
+  }
+
+  const gscOwners = new Set(getGscOwnersForProperty(inventory, gscPropertyId));
+  const candidates = inventory.ga4Properties
+    .filter((property) => gscOwners.has(property.email))
+    .filter((property) => ga4MatchesWebsite(property, websiteUrl));
+
+  candidates.sort((left, right) => {
+    const scoreDelta = scoreGa4Candidate(right, siteName) - scoreGa4Candidate(left, siteName);
+
+    if (scoreDelta !== 0) {
+      return scoreDelta;
+    }
+
+    return `${left.email}:${left.property}`.localeCompare(`${right.email}:${right.property}`);
+  });
+
+  const match = candidates[0];
+
+  if (!match) {
+    return null;
+  }
+
+  return {
+    connectionEmail: match.email,
+    ga4PropertyId: match.property,
+    matchType: "web_stream_domain",
+  };
+}
+
+function canQuerySearchConsoleProperty(property) {
+  return property.permissionLevel !== "siteUnverifiedUser";
+}
+
+function createEmptyGooglePropertyInventory() {
+  return {
+    errors: [],
+    ga4Properties: [],
+    gscOwnersByProperty: new Map(),
+  };
+}
+
+function addGscPropertyOwner(inventory, propertyId, email) {
+  if (!propertyId || !email) {
+    return;
+  }
+
+  const owners = inventory.gscOwnersByProperty.get(propertyId) ?? new Set();
+  owners.add(email);
+  inventory.gscOwnersByProperty.set(propertyId, owners);
+}
+
+async function readAvailableGoogleProperties(options) {
+  const inventory = createEmptyGooglePropertyInventory();
+
+  if (!(await hasConfiguredAuthToken())) {
+    return inventory;
+  }
+
+  try {
+    const { accounts = [] } = await requestJson(options, "/api/ops/google-properties");
+
+    for (const account of accounts) {
+      if (account.errors?.length) {
+        inventory.errors.push({ email: account.email, errors: account.errors });
+      }
+
+      for (const property of account.searchConsoleProperties ?? []) {
+        if (canQuerySearchConsoleProperty(property)) {
+          addGscPropertyOwner(inventory, property.siteUrl, account.email);
+        }
+      }
+
+      for (const property of account.ga4Properties ?? []) {
+        if (property.property && account.email) {
+          inventory.ga4Properties.push({ ...property, email: account.email });
+        }
+      }
+    }
+  } catch (error) {
+    inventory.errors.push({
+      error: error instanceof Error ? error.message : "Unable to read Google properties.",
+    });
+  }
+
+  return inventory;
+}
+
+function getReportPortalClients() {
+  const output = execFileSync(
+    "mmai-report-portal",
+    ["clients", "list", "--active-only", "true", "--json"],
+    { encoding: "utf8", maxBuffer: 20 * 1024 * 1024 },
+  );
+  const parsed = JSON.parse(output);
+
+  if (Array.isArray(parsed)) {
+    return parsed;
+  }
+
+  return parsed.clients ?? parsed.data ?? parsed.items ?? [];
+}
+
+function getClientName(client, websiteUrl) {
+  return (
+    optionalString(client.business_name) ??
+    optionalString(client.businessName) ??
+    optionalString(client.name) ??
+    websiteUrl?.hostname.replace(/^www\./i, "") ??
+    "Unnamed client"
+  );
+}
+
+function matchesFilter(client, mapping, match) {
+  const normalizedMatch = optionalString(match)?.toLowerCase();
+
+  if (!normalizedMatch) {
+    return true;
+  }
+
+  return [
+    client.business_name,
+    client.businessName,
+    client.name,
+    client.website_url,
+    client.websiteUrl,
+    mapping.siteName,
+    mapping.siteSlug,
+    mapping.gscPropertyId,
+    mapping.ga4PropertyId,
+  ]
+    .filter(Boolean)
+    .some((value) => String(value).toLowerCase().includes(normalizedMatch));
+}
+
+function createReportPortalMappings(options, inventory = createEmptyGooglePropertyInventory()) {
+  const clients = getReportPortalClients();
+  const ga4Mode = getGa4Mode(options);
+  const propertyMode = getPropertyMode(options);
+  const seenSlugs = new Set();
+  const skipped = [];
+  const mappings = [];
+
+  for (const client of clients) {
+    const websiteUrl = normalizeWebsiteUrl(client.website_url ?? client.websiteUrl);
+
+    if (!websiteUrl && !options.includeNoWebsite) {
+      skipped.push({ reason: "missing_website_url", reportPortalClientId: client.id, name: getClientName(client) });
+      continue;
+    }
+
+    const siteName = getClientName(client, websiteUrl);
+    const fallbackSlug = websiteUrl ? slugify(websiteUrl.hostname.replace(/^www\./i, "")) : "client";
+    let siteSlug = slugify(siteName) || fallbackSlug;
+
+    if (seenSlugs.has(siteSlug)) {
+      siteSlug = slugify(`${siteSlug}-${fallbackSlug}`) || `${siteSlug}-${mappings.length + 1}`;
+    }
+
+    seenSlugs.add(siteSlug);
+
+    const gscPropertyId = websiteUrl
+      ? propertyFromWebsiteUrl(websiteUrl, propertyMode, inventory)
+      : undefined;
+    const ga4Match = findGa4PropertyMatch({
+      ga4Mode,
+      gscPropertyId,
+      inventory,
+      siteName,
+      websiteUrl,
+    });
+    const connectionEmail = ga4Match?.connectionEmail
+      ?? getGscOwnersForProperty(inventory, gscPropertyId)[0]
+      ?? options.connectionEmail;
+    const mapping = {
+      connectionEmail,
+      ga4MatchType: ga4Match?.matchType,
+      ga4PropertyId: ga4Match?.ga4PropertyId,
+      gscPropertyId,
+      isCustom: true,
+      reportPortalClientId: client.id,
+      siteName,
+      siteSlug,
+      websiteUrl: websiteUrl?.href,
+    };
+
+    if (!matchesFilter(client, mapping, options.match)) {
+      continue;
+    }
+
+    mappings.push(mapping);
+  }
+
+  const limitedMappings = applyLimit(mappings, options.limit);
+
+  return {
+    availableGa4PropertyCount: inventory.ga4Properties.length,
+    availableGscPropertyCount: inventory.gscOwnersByProperty.size,
+    ga4MatchedCount: limitedMappings.filter((mapping) => mapping.ga4PropertyId).length,
+    googlePropertyErrors: inventory.errors,
+    mappings: limitedMappings,
+    skipped,
+    totalActiveClients: clients.length,
+  };
+}
+
+function applyLimit(items, rawLimit) {
+  if (!rawLimit) {
+    return items;
+  }
+
+  const limit = Number.parseInt(rawLimit, 10);
+
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new Error("--limit must be a positive integer.");
+  }
+
+  return items.slice(0, limit);
+}
+
+function getPropertyMatchKeys(propertyId) {
+  const property = optionalString(propertyId);
+
+  if (!property) {
+    return [];
+  }
+
+  if (property.startsWith("sc-domain:")) {
+    return [property, property.replace("sc-domain:", "domain:").replace(/^domain:www\./i, "domain:")];
+  }
+
+  try {
+    const url = new URL(property);
+    return [property, `domain:${url.hostname.replace(/^www\./i, "")}`];
+  } catch {
+    return [property];
+  }
+}
+
+async function reuseExistingSiteSlugs(options, plan) {
+  if (!(await hasConfiguredAuthToken())) {
+    return plan;
+  }
+
+  try {
+    const existingSites = (await requestJson(options, "/api/sites")).sites ?? [];
+    const sitesByKey = new Map();
+
+    for (const site of existingSites) {
+      for (const key of getPropertyMatchKeys(site.propertyId)) {
+        sitesByKey.set(key, site);
+      }
+    }
+
+    const reused = [];
+    const mappings = plan.mappings.map((mapping) => {
+      const existingSite = getPropertyMatchKeys(mapping.gscPropertyId)
+        .map((key) => sitesByKey.get(key))
+        .find(Boolean);
+
+      if (!existingSite || existingSite.slug === mapping.siteSlug) {
+        return mapping;
+      }
+
+      reused.push({
+        from: mapping.siteSlug,
+        propertyId: mapping.gscPropertyId,
+        siteName: mapping.siteName,
+        to: existingSite.slug,
+      });
+
+      return { ...mapping, siteSlug: existingSite.slug };
+    });
+
+    return { ...plan, mappings, reused };
+  } catch {
+    return plan;
+  }
+}
+
+function printImportPlan(options, plan) {
+  if (options.json) {
+    console.log(JSON.stringify(plan, null, 2));
+    return;
+  }
+
+  console.log(`Report Portal active clients: ${plan.totalActiveClients}`);
+  console.log(`Ready to onboard: ${plan.mappings.length}`);
+  console.log(`Skipped: ${plan.skipped.length}`);
+  console.log(`Available GSC properties checked: ${plan.availableGscPropertyCount ?? 0}`);
+  console.log(`Available GA4 properties checked: ${plan.availableGa4PropertyCount ?? 0}`);
+  console.log(`GA4 properties auto-attached: ${plan.ga4MatchedCount ?? 0}`);
+  console.log(`Reusing existing Searchlight slugs: ${plan.reused?.length ?? 0}`);
+
+  for (const mapping of plan.mappings) {
+    console.log(formatMappingRow(mapping, {
+      ga4PropertyId: "no GA4 property",
+      gscPropertyId: "no GSC property",
+    }));
+  }
+
+  if (!options.yes) {
+    console.log("\nDry run only. Re-run with --yes to write these mappings to Searchlight.");
+  }
+}
+
+async function saveClientMappings(options, mappings) {
+  return requestJson(options, "/api/ops/client-mappings", {
+    body: JSON.stringify({ mappings }),
+    headers: { "content-type": "application/json" },
+    method: "POST",
+  });
+}
+
+async function addClient(options) {
+  const siteName = requireOption(options, "name");
+  const gscPropertyId = requireOption(options, "gscProperty");
+  const mapping = {
+    connectionEmail: options.connectionEmail,
+    ga4PropertyId: optionalString(options.ga4Property),
+    gscPropertyId,
+    isCustom: true,
+    siteName,
+    siteSlug: optionalString(options.siteSlug),
+  };
+  const result = await saveClientMappings(options, [mapping]);
+
+  printResult(options, result);
+}
+
+async function postJson(options, path, body = {}) {
+  return requestJson(options, path, {
+    body: JSON.stringify(body),
+    headers: { "content-type": "application/json" },
+    method: "POST",
+  });
+}
+
+function refreshFailure(siteSlug, source, error, fallbackMessage) {
+  return {
+    error: error instanceof Error ? error.message : fallbackMessage,
+    siteSlug,
+    source,
+    status: "failed",
+  };
+}
+
+async function refreshGscMapping(options, mapping) {
+  if (!mapping.gscPropertyId) {
+    return null;
+  }
+
+  try {
+    const result = await postJson(
+      options,
+      `/api/sites/${mapping.siteSlug}/gsc/ensure-fresh`,
+    );
+
+    return {
+      siteSlug: mapping.siteSlug,
+      source: "gsc",
+      status: result.status ?? "requested",
+    };
+  } catch (error) {
+    return refreshFailure(
+      mapping.siteSlug,
+      "gsc",
+      error,
+      "Search Console refresh failed.",
+    );
+  }
+}
+
+async function refreshGa4Mapping(options, mapping) {
+  if (!mapping.ga4PropertyId) {
+    return null;
+  }
+
+  try {
+    const result = await postJson(
+      options,
+      `/api/sites/${mapping.siteSlug}/ga4/refresh`,
+    );
+
+    return {
+      siteSlug: mapping.siteSlug,
+      source: "ga4",
+      status: result.syncStatus?.status ?? "refreshed",
+    };
+  } catch (error) {
+    return refreshFailure(mapping.siteSlug, "ga4", error, "GA4 refresh failed.");
+  }
+}
+
+async function refreshImportedMappings(options, mappings) {
+  const mode = getRefreshMode(options);
+
+  if (mode === "none") {
+    return { mode, results: [] };
+  }
+
+  const results = [];
+
+  for (const mapping of mappings) {
+    const gscResult = await refreshGscMapping(options, mapping);
+    if (gscResult) results.push(gscResult);
+
+    if (mode === "all") {
+      const ga4Result = await refreshGa4Mapping(options, mapping);
+      if (ga4Result) results.push(ga4Result);
+    }
+  }
+
+  return { mode, results };
+}
+
+async function importReportPortalClients(options) {
+  const inventory = await readAvailableGoogleProperties(options);
+  const plan = await reuseExistingSiteSlugs(
+    options,
+    createReportPortalMappings(options, inventory),
+  );
+
+  if (!options.yes || options.dryRun) {
+    printImportPlan(options, plan);
+    return;
+  }
+
+  if (plan.mappings.length === 0) {
+    printImportPlan(options, plan);
+    return;
+  }
+
+  const result = await saveClientMappings(options, plan.mappings);
+  const refresh = await refreshImportedMappings(options, plan.mappings);
+  const output = {
+    ...result,
+    availableGa4PropertyCount: plan.availableGa4PropertyCount,
+    availableGscPropertyCount: plan.availableGscPropertyCount,
+    ga4MatchedCount: plan.ga4MatchedCount,
+    googlePropertyErrors: plan.googlePropertyErrors,
+    refresh,
+    skipped: plan.skipped,
+    totalActiveClients: plan.totalActiveClients,
+  };
+
+  printResult(options, output);
+}
+
+async function runAnnotationCommand(command, options) {
+  switch (command) {
+    case "sites":
+      await listSites(options);
+      break;
+    case "list":
+      await listAnnotations(options);
+      break;
+    case "add":
+      await addAnnotation(options);
+      break;
+    case "add-from-annotate":
+      await addFromAnnotate(options);
+      break;
+    case "update":
+      await updateAnnotation(options);
+      break;
+    case "update-from-annotate":
+      await updateFromAnnotate(options);
+      break;
+    case "delete":
+      await deleteAnnotation(options);
+      break;
+    case "help":
+    case "--help":
+    case undefined:
+      usage(0);
+      break;
+    default:
+      throw new Error(`Unknown annotations command: ${command}`);
+  }
+}
+
+async function runContentRunCommand(command, options) {
+  switch (command) {
+    case "list":
+      await listContentRuns(options);
+      break;
+    case "add":
+    case "ingest":
+      await addContentRun(options);
+      break;
+    case "help":
+    case "--help":
+    case undefined:
+      usage(0);
+      break;
+    default:
+      throw new Error(`Unknown content-runs command: ${command}`);
+  }
+}
+
+async function runTestCommand(command, options) {
+  switch (command) {
+    case "list":
+      await listTests(options);
+      break;
+    case "refresh":
+    case "run":
+      await refreshTests(options);
+      break;
+    case "help":
+    case "--help":
+    case undefined:
+      usage(0);
+      break;
+    default:
+      throw new Error(`Unknown tests command: ${command}`);
+  }
+}
+
+async function runClientCommand(command, options) {
+  switch (command) {
+    case "list":
+      await listSites(options);
+      break;
+    case "add":
+      await addClient(options);
+      break;
+    case "import-report-portal":
+    case "import-rp":
+      await importReportPortalClients(options);
+      break;
+    case "help":
+    case "--help":
+    case undefined:
+      usage(0);
+      break;
+    default:
+      throw new Error(`Unknown clients command: ${command}`);
+  }
+}
+
+async function main() {
+  const [scope, maybeCommand, ...rest] = process.argv.slice(2);
+
+  if (!scope || scope === "help" || scope === "--help") {
+    usage(0);
+  }
+
+  if (scope === "setup") {
+    printSetupInstructions();
+    return;
+  }
+
+  if (scope === "auth") {
+    await runAuthCommand(maybeCommand, parseArgs([maybeCommand, ...rest]));
+    return;
+  }
+
+  if (scope === "annotations") {
+    await runAnnotationCommand(maybeCommand, parseArgs([maybeCommand, ...rest]));
+    return;
+  }
+
+  if (scope === "clients") {
+    await runClientCommand(maybeCommand, parseArgs([maybeCommand, ...rest]));
+    return;
+  }
+
+  if (scope === "content-runs") {
+    await runContentRunCommand(maybeCommand, parseArgs([maybeCommand, ...rest]));
+    return;
+  }
+
+  if (scope === "tests") {
+    await runTestCommand(maybeCommand, parseArgs([maybeCommand, ...rest]));
+    return;
+  }
+
+  if (rootAnnotationCommands.has(scope)) {
+    await runAnnotationCommand(scope, parseArgs([scope, maybeCommand, ...rest].filter(Boolean)));
+    return;
+  }
+
+  throw new Error(`Unknown command group: ${scope}`);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});