@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/gsc/cloudflare.mjs

@@ -0,0 +1,318 @@
+// cloudflare.mjs — Cloudflare API helpers for DNS planting.
+//
+// Scope is intentionally narrow: GSC verification flow only needs
+//   1. resolve the zone id for a domain
+//   2. find an existing TXT record by name (idempotency)
+//   3. create or update a TXT record
+//
+// Credentials are read from the SOPS vault. The vault holds two key
+// shapes for Cloudflare:
+//
+//   - Account-suffixed pair (preferred — multi-account safe):
+//       CLOUDFLARE_PAGES_API_KEY_<SUFFIX>
+//       CLOUDFLARE_PAGES_ACCOUNT_ID_<SUFFIX>
+//     The caller picks the suffix via the `account` option (lower-cased
+//     externally; matched case-insensitively to the upper-case suffix).
+//
+//   - Unsuffixed pair (single-account default):
+//       CLOUDFLARE_PAGES_API_KEY
+//       CLOUDFLARE_PAGES_ACCOUNT_ID
+//
+//   - Legacy bare pair (back-compat fallback):
+//       CLOUDFLARE_API_TOKEN
+//       CLOUDFLARE_ACCOUNT_ID
+//
+// `fetchImpl` and `now` are injectable for tests.
+
+import { defaultPaths, checkVault, secretsFileExists, sopsDecrypt, VaultError } from '../secrets/vault.mjs';
+
+const CF_API = 'https://api.cloudflare.com/client/v4';
+
+// Vault-key shapes. `*_TEMPLATE` uses `<S>` as the suffix placeholder.
+const VAULT_KEYS = Object.freeze({
+  // Account-suffixed (preferred).
+  tokenTemplate: 'CLOUDFLARE_PAGES_API_KEY_<S>',
+  accountIdTemplate: 'CLOUDFLARE_PAGES_ACCOUNT_ID_<S>',
+  // Unsuffixed (single-account default).
+  tokenUnsuffixed: 'CLOUDFLARE_PAGES_API_KEY',
+  accountIdUnsuffixed: 'CLOUDFLARE_PAGES_ACCOUNT_ID',
+  // Legacy bare (back-compat fallback).
+  tokenLegacy: 'CLOUDFLARE_API_TOKEN',
+  accountIdLegacy: 'CLOUDFLARE_ACCOUNT_ID',
+});
+
+/**
+ * Normalise an `--account` value to the upper-case suffix used in the
+ * vault keys. Letters + digits only — anything else is rejected so a
+ * stray "/" or " " can't smuggle into a vault key lookup.
+ *
+ * @param {string} account
+ * @returns {string} upper-case suffix
+ * @throws {VaultError} on invalid input
+ */
+export function accountSuffix(account) {
+  const raw = String(account || '').trim();
+  if (!raw) {
+    throw new VaultError('--account: value is required', 1);
+  }
+  if (!/^[A-Za-z0-9]+$/.test(raw)) {
+    throw new VaultError(
+      `--account: "${raw}" is invalid. Use letters/digits only (e.g. stravica, clive).`,
+      1,
+    );
+  }
+  return raw.toUpperCase();
+}
+
+/**
+ * Build the vault key names a given `account` selection resolves to.
+ * If `account` is omitted, returns the unsuffixed pair (with a legacy
+ * fallback list for back-compat).
+ *
+ * @param {string} [account]
+ * @returns {{ tokenKey: string, accountIdKey: string, fallbacks?: Array<{tokenKey: string, accountIdKey: string}> }}
+ */
+export function resolveVaultKeys(account) {
+  if (account) {
+    const s = accountSuffix(account);
+    return {
+      tokenKey: VAULT_KEYS.tokenTemplate.replace('<S>', s),
+      accountIdKey: VAULT_KEYS.accountIdTemplate.replace('<S>', s),
+    };
+  }
+  return {
+    tokenKey: VAULT_KEYS.tokenUnsuffixed,
+    accountIdKey: VAULT_KEYS.accountIdUnsuffixed,
+    fallbacks: [
+      { tokenKey: VAULT_KEYS.tokenLegacy, accountIdKey: VAULT_KEYS.accountIdLegacy },
+    ],
+  };
+}
+
+/**
+ * Load Cloudflare credentials from the SOPS vault. Override paths or
+ * provide raw credentials for tests.
+ *
+ * Resolution order:
+ *   1. Test overrides (`cloudflareToken` + `cloudflareAccountId`).
+ *   2. If `account` provided: only the suffixed pair, hard-fail if missing.
+ *   3. Otherwise: unsuffixed pair, then the legacy bare pair as fallback.
+ *
+ * @param {object} overrides
+ * @param {object} [overrides.paths]
+ * @param {string} [overrides.cloudflareToken]
+ * @param {string} [overrides.cloudflareAccountId]
+ * @param {string} [overrides.account]            Account selector (e.g. "stravica").
+ * @param {object} [overrides.vaultData]          Pre-decrypted vault map (test seam).
+ *        When provided, the function uses this instead of running the SOPS
+ *        check + decrypt. Lets tests cover the suffix-resolution and
+ *        fallback paths without touching the filesystem.
+ * @returns {Promise<{token: string, accountId: string, account: string|null, vaultKeys: {tokenKey: string, accountIdKey: string}}>}
+ */
+export async function loadCloudflareCreds(overrides = {}) {
+  if (overrides.cloudflareToken && overrides.cloudflareAccountId) {
+    return {
+      token: overrides.cloudflareToken,
+      accountId: overrides.cloudflareAccountId,
+      account: overrides.account || null,
+      vaultKeys: null,
+    };
+  }
+  let data;
+  if (overrides.vaultData) {
+    data = overrides.vaultData;
+  } else {
+    const paths = overrides.paths || defaultPaths();
+    const state = checkVault(paths);
+    if (!state.ok) throw new VaultError(state.message, state.exitCode ?? 1);
+    if (!secretsFileExists(paths)) {
+      throw new VaultError(
+        `No secrets file at ${paths.secretsFile}. Run 'secrets init' first.`,
+        1,
+      );
+    }
+    data = await sopsDecrypt(paths, paths.secretsFile);
+  }
+
+  const plan = resolveVaultKeys(overrides.account);
+
+  // Account-suffixed: must hit exactly the suffixed pair.
+  if (overrides.account) {
+    const token = data[plan.tokenKey];
+    const accountId = data[plan.accountIdKey];
+    if (!token || !accountId) {
+      const missing = [];
+      if (!token) missing.push(plan.tokenKey);
+      if (!accountId) missing.push(plan.accountIdKey);
+      throw new VaultError(
+        `--account "${overrides.account}" expects vault keys [${missing.join(', ')}] but they are not set. ` +
+        `Store them with:\n  secrets set ${plan.tokenKey} <token>\n  secrets set ${plan.accountIdKey} <id>`,
+        1,
+      );
+    }
+    return {
+      token,
+      accountId,
+      account: overrides.account,
+      vaultKeys: { tokenKey: plan.tokenKey, accountIdKey: plan.accountIdKey },
+    };
+  }
+
+  // No --account: try unsuffixed pair first, then legacy bare pair.
+  const candidates = [
+    { tokenKey: plan.tokenKey, accountIdKey: plan.accountIdKey },
+    ...(plan.fallbacks || []),
+  ];
+  for (const cand of candidates) {
+    const token = data[cand.tokenKey];
+    const accountId = data[cand.accountIdKey];
+    if (token && accountId) {
+      return { token, accountId, account: null, vaultKeys: cand };
+    }
+  }
+  // None matched — error message lists the primary pair the operator
+  // is expected to set; legacy fallback is a back-compat courtesy, not
+  // a thing we advertise.
+  throw new VaultError(
+    `Cloudflare vault keys not found. Pass --account <name> (e.g. --account stravica) ` +
+    `to use the per-account pair, or store the default pair:\n` +
+    `  secrets set ${VAULT_KEYS.tokenUnsuffixed} <token>\n` +
+    `  secrets set ${VAULT_KEYS.accountIdUnsuffixed} <id>`,
+    1,
+  );
+}
+
+/**
+ * Tiny wrapper around fetch with CF auth headers + structured error handling.
+ * Returns the parsed JSON body on 2xx; throws an Error with .exitCode on
+ * non-2xx or on a CF `success: false` payload.
+ */
+export async function cfFetch(token, path, init = {}, fetchImpl) {
+  const fetchFn = fetchImpl || globalThis.fetch;
+  if (typeof fetchFn !== 'function') {
+    throw Object.assign(new Error('fetch is not available in this runtime'), { exitCode: 3 });
+  }
+  const url = path.startsWith('http') ? path : `${CF_API}${path}`;
+  const res = await fetchFn(url, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      ...(init.headers || {}),
+    },
+  });
+  const text = await res.text();
+  let body;
+  try { body = text ? JSON.parse(text) : {}; } catch {
+    throw Object.assign(
+      new Error(`Cloudflare API: non-JSON response (HTTP ${res.status}): ${text.slice(0, 200)}`),
+      { exitCode: 3 },
+    );
+  }
+  if (!res.ok || body.success === false) {
+    const detail = (body.errors || [])
+      .map((e) => `${e.code}: ${e.message}`)
+      .join('; ') || `HTTP ${res.status}`;
+    throw Object.assign(
+      new Error(`Cloudflare API ${init.method || 'GET'} ${path} failed: ${detail}`),
+      { exitCode: 2, status: res.status, body },
+    );
+  }
+  return body;
+}
+
+/**
+ * Resolve a Cloudflare zone id for `domain`. Caller can pass either the
+ * exact zone name (foo.com) or a subdomain — we try exact match first,
+ * then walk up the domain segments.
+ */
+export async function resolveZoneId(creds, domain, fetchImpl) {
+  const candidates = candidateZoneNames(domain);
+  for (const candidate of candidates) {
+    const q = new URLSearchParams({ name: candidate, 'account.id': creds.accountId });
+    const body = await cfFetch(creds.token, `/zones?${q.toString()}`, {}, fetchImpl);
+    if (body.result && body.result.length > 0) {
+      return { zoneId: body.result[0].id, zoneName: body.result[0].name };
+    }
+  }
+  throw Object.assign(
+    new Error(
+      `No Cloudflare zone matches "${domain}" in account ${creds.accountId}. ` +
+      `Tried candidates: ${candidates.join(', ')}`,
+    ),
+    { exitCode: 1 },
+  );
+}
+
+/** Build descending zone-name candidates from a domain. */
+export function candidateZoneNames(domain) {
+  const stripped = String(domain || '')
+    .toLowerCase()
+    .replace(/^sc-domain:/, '')
+    .replace(/^https?:\/\//, '')
+    .split('/')[0]
+    .replace(/\.$/, '');
+  const parts = stripped.split('.');
+  if (parts.length < 2) return [stripped];
+  // Try most-specific first (e.g. foo.example.com), then parent zones.
+  // Stop at two labels — single-label TLDs don't host CF zones.
+  const out = [];
+  for (let i = 0; i <= parts.length - 2; i++) {
+    out.push(parts.slice(i).join('.'));
+  }
+  return out;
+}
+
+/**
+ * Find a TXT record by exact name within a zone. Returns the record object
+ * or null if not found. Cloudflare returns names without trailing dots.
+ */
+export async function findTxtRecord(creds, zoneId, name, fetchImpl) {
+  const q = new URLSearchParams({ type: 'TXT', name });
+  const body = await cfFetch(creds.token, `/zones/${zoneId}/dns_records?${q.toString()}`, {}, fetchImpl);
+  return (body.result && body.result[0]) || null;
+}
+
+/**
+ * Plant (create or update) a TXT record. Idempotent:
+ *   - identical content => no-op, returns { action: 'unchanged', record }
+ *   - same name, different content => PATCH, returns { action: 'updated', record }
+ *   - missing => POST, returns { action: 'created', record }
+ */
+export async function plantTxtRecord(creds, zoneId, name, content, fetchImpl) {
+  const existing = await findTxtRecord(creds, zoneId, name, fetchImpl);
+  // CF stores TXT values quoted in API responses ("value"); strip quotes
+  // before comparison so we don't churn on a benign formatting diff.
+  const stripQuotes = (v) => String(v || '').replace(/^"|"$/g, '');
+  if (existing) {
+    if (stripQuotes(existing.content) === content) {
+      return { action: 'unchanged', record: existing };
+    }
+    const body = await cfFetch(
+      creds.token,
+      `/zones/${zoneId}/dns_records/${existing.id}`,
+      {
+        method: 'PATCH',
+        body: JSON.stringify({ content, ttl: 1, proxied: false }),
+      },
+      fetchImpl,
+    );
+    return { action: 'updated', record: body.result };
+  }
+  const body = await cfFetch(
+    creds.token,
+    `/zones/${zoneId}/dns_records`,
+    {
+      method: 'POST',
+      body: JSON.stringify({ type: 'TXT', name, content, ttl: 1, proxied: false }),
+    },
+    fetchImpl,
+  );
+  return { action: 'created', record: body.result };
+}
+
+/** Sleep helper — injectable for tests so timeouts don't slow the suite. */
+export function sleep(ms, sleepImpl) {
+  if (typeof sleepImpl === 'function') return sleepImpl(ms);
+  return new Promise((res) => setTimeout(res, ms));
+}

package/dist/engineering-pa-cli/src/gsc/commands/add-property.mjs

@@ -0,0 +1,70 @@
+// add-property — Obtain the verification TXT token for a domain property.
+//
+// GSC domain-property verification (the modern, recommended kind) is
+// gated by Google's Site Verification API, not the Search Console
+// `sites.add` call directly. The two-stage flow is:
+//
+//   1. siteVerification.webResource.getToken({verificationMethod: DNS_TXT,
+//      site: {type: INET_DOMAIN, identifier: <domain>}})
+//        -> returns the TXT token to plant (string like "google-site-verification=...")
+//   2. operator plants TXT at apex
+//   3. siteVerification.webResource.insert(...) confirms ownership
+//   4. (optional) webmasters.sites.add(siteUrl="sc-domain:<domain>") registers
+//      the property in Search Console explicitly. In practice it surfaces
+//      automatically post-verification.
+//
+// This verb covers step 1 — it's the entry point. `verify-via-cf-dns`
+// chains 1→2→3→4 in one call.
+//
+// URL-prefix properties (legacy https://foo.com/ shape) are not supported
+// here — domain-property is the default for new properties.
+
+import { buildGscClient, toDomainProperty, bareDomain } from '../auth.mjs';
+
+export async function runAddProperty(args, overrides = {}) {
+  const domain = args[0];
+  if (!domain) {
+    process.stderr.write('Usage: pa gsc add-property <domain>\n');
+    return 1;
+  }
+  const siteUrl = toDomainProperty(domain);
+  const bare = bareDomain(siteUrl);
+
+  let client;
+  try {
+    client = await buildGscClient(overrides);
+  } catch (e) {
+    process.stderr.write(`[gsc add-property] auth failed: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  let token;
+  try {
+    const res = await client.siteVerification.webResource.getToken({
+      requestBody: {
+        verificationMethod: 'DNS_TXT',
+        site: { type: 'INET_DOMAIN', identifier: bare },
+      },
+    });
+    token = res?.data?.token;
+  } catch (e) {
+    process.stderr.write(`[gsc add-property] getToken failed: ${e.message}\n`);
+    return 2;
+  }
+
+  if (!token) {
+    process.stderr.write('[gsc add-property] no token returned from siteVerification API\n');
+    return 2;
+  }
+
+  const out = overrides.stdout || process.stdout;
+  const result = {
+    domain: bare,
+    siteUrl,
+    verificationMethod: 'DNS_TXT',
+    txtRecordName: bare,
+    txtRecordValue: token,
+  };
+  out.write(JSON.stringify(result, null, 2) + '\n');
+  return 0;
+}

package/dist/engineering-pa-cli/src/gsc/commands/list-properties.mjs

@@ -0,0 +1,33 @@
+// list-properties — Enumerate all GSC properties the SA can see.
+//
+// Wraps webmasters.sites.list. Useful as the canonical "did I add the
+// service-account email as a user on the right property?" check.
+
+import { buildGscClient } from '../auth.mjs';
+
+export async function runListProperties(_args, overrides = {}) {
+  let client;
+  try {
+    client = await buildGscClient(overrides);
+  } catch (e) {
+    process.stderr.write(`[gsc list-properties] auth failed: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  let response;
+  try {
+    response = await client.webmasters.sites.list({});
+  } catch (e) {
+    process.stderr.write(`[gsc list-properties] sites.list failed: ${e.message}\n`);
+    return 2;
+  }
+
+  const entries = (response?.data?.siteEntry || []).map((s) => ({
+    siteUrl: s.siteUrl,
+    permissionLevel: s.permissionLevel,
+  }));
+
+  const out = overrides.stdout || process.stdout;
+  out.write(JSON.stringify({ count: entries.length, properties: entries }, null, 2) + '\n');
+  return 0;
+}

package/dist/engineering-pa-cli/src/gsc/commands/pull-analytics.mjs

@@ -0,0 +1,130 @@
+// pull-analytics — Search-analytics rows for a property.
+//
+// Wraps webmasters.searchanalytics.query. Defaults to last 28 days, top
+// queries, 100 rows. JSON array on stdout — one element per row, with
+// dimensions hydrated into named fields.
+
+import { buildGscClient, toDomainProperty } from '../auth.mjs';
+
+const VALID_DIMENSIONS = new Set(['query', 'page', 'country', 'device', 'date', 'searchAppearance']);
+
+function parseFlags(args) {
+  const out = {
+    positional: [],
+    days: 28,
+    dimensions: ['query'],
+    rows: 100,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--days') {
+      out.days = Number(args[++i]);
+    } else if (a.startsWith('--days=')) {
+      out.days = Number(a.slice('--days='.length));
+    } else if (a === '--dimensions') {
+      out.dimensions = String(args[++i] || '').split(',').map((s) => s.trim()).filter(Boolean);
+    } else if (a.startsWith('--dimensions=')) {
+      out.dimensions = a.slice('--dimensions='.length).split(',').map((s) => s.trim()).filter(Boolean);
+    } else if (a === '--rows') {
+      out.rows = Number(args[++i]);
+    } else if (a.startsWith('--rows=')) {
+      out.rows = Number(a.slice('--rows='.length));
+    } else {
+      out.positional.push(a);
+    }
+  }
+
+  if (!Number.isInteger(out.days) || out.days < 1 || out.days > 16 * 30) {
+    throw Object.assign(new Error('--days must be an integer between 1 and 480'), { exitCode: 1 });
+  }
+  if (!Number.isInteger(out.rows) || out.rows < 1 || out.rows > 25000) {
+    throw Object.assign(new Error('--rows must be an integer between 1 and 25000'), { exitCode: 1 });
+  }
+  for (const d of out.dimensions) {
+    if (!VALID_DIMENSIONS.has(d)) {
+      throw Object.assign(
+        new Error(`--dimensions: unknown dimension "${d}". Valid: ${[...VALID_DIMENSIONS].join(',')}`),
+        { exitCode: 1 },
+      );
+    }
+  }
+  return out;
+}
+
+/** Format a Date as YYYY-MM-DD (UTC). */
+export function ymd(date) {
+  const y = date.getUTCFullYear();
+  const m = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const d = String(date.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+export async function runPullAnalytics(args, overrides = {}) {
+  let flags;
+  try { flags = parseFlags(args); } catch (e) {
+    process.stderr.write(`[gsc pull-analytics] ${e.message}\n`);
+    return e.exitCode || 1;
+  }
+
+  const domain = flags.positional[0];
+  if (!domain) {
+    process.stderr.write('Usage: pa gsc pull-analytics <domain> [--days N] [--dimensions D1,D2,...] [--rows N]\n');
+    return 1;
+  }
+
+  const siteUrl = toDomainProperty(domain);
+  const now = overrides.now ? new Date(overrides.now) : new Date();
+  // GSC data lags ~2 days. Always end "today" — server-side, GSC will
+  // simply return zeros for the trailing rows; the API has no minimum-lag
+  // requirement on the request side.
+  const endDate = ymd(now);
+  const start = new Date(now.getTime() - flags.days * 24 * 60 * 60 * 1000);
+  const startDate = ymd(start);
+
+  let client;
+  try {
+    client = await buildGscClient(overrides);
+  } catch (e) {
+    process.stderr.write(`[gsc pull-analytics] auth failed: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  let response;
+  try {
+    response = await client.webmasters.searchanalytics.query({
+      siteUrl,
+      requestBody: {
+        startDate,
+        endDate,
+        dimensions: flags.dimensions,
+        rowLimit: flags.rows,
+      },
+    });
+  } catch (e) {
+    process.stderr.write(`[gsc pull-analytics] searchanalytics.query failed: ${e.message}\n`);
+    return 2;
+  }
+
+  const rows = (response?.data?.rows || []).map((row) => {
+    const hydrated = {};
+    for (let i = 0; i < flags.dimensions.length; i++) {
+      hydrated[flags.dimensions[i]] = row.keys?.[i];
+    }
+    hydrated.clicks = row.clicks ?? 0;
+    hydrated.impressions = row.impressions ?? 0;
+    hydrated.ctr = row.ctr ?? 0;
+    hydrated.position = row.position ?? 0;
+    return hydrated;
+  });
+
+  const out = overrides.stdout || process.stdout;
+  out.write(JSON.stringify({
+    siteUrl,
+    startDate,
+    endDate,
+    dimensions: flags.dimensions,
+    rowCount: rows.length,
+    rows,
+  }, null, 2) + '\n');
+  return 0;
+}

package/dist/engineering-pa-cli/src/gsc/commands/submit-sitemap.mjs

@@ -0,0 +1,41 @@
+// submit-sitemap — Submit a sitemap to GSC for a property.
+//
+// Wraps webmasters.sitemaps.submit. The property must already be
+// verified (see `pa gsc verify-via-cf-dns`).
+
+import { buildGscClient, toDomainProperty } from '../auth.mjs';
+
+export async function runSubmitSitemap(args, overrides = {}) {
+  const domain = args[0];
+  const sitemapUrl = args[1];
+
+  if (!domain || !sitemapUrl) {
+    process.stderr.write('Usage: pa gsc submit-sitemap <domain> <sitemap-url>\n');
+    return 1;
+  }
+  if (!/^https?:\/\//i.test(sitemapUrl)) {
+    process.stderr.write(`[gsc submit-sitemap] sitemap-url must be an absolute http(s) URL, got "${sitemapUrl}"\n`);
+    return 1;
+  }
+
+  const siteUrl = toDomainProperty(domain);
+
+  let client;
+  try {
+    client = await buildGscClient(overrides);
+  } catch (e) {
+    process.stderr.write(`[gsc submit-sitemap] auth failed: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  try {
+    await client.webmasters.sitemaps.submit({ siteUrl, feedpath: sitemapUrl });
+  } catch (e) {
+    process.stderr.write(`[gsc submit-sitemap] sitemaps.submit failed: ${e.message}\n`);
+    return 2;
+  }
+
+  const out = overrides.stdout || process.stdout;
+  out.write(JSON.stringify({ siteUrl, sitemap: sitemapUrl, submitted: true }, null, 2) + '\n');
+  return 0;
+}