@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/environment/probes.mjs

@@ -0,0 +1,302 @@
+// probes.mjs — Node-only environment probes. Cross-platform (macOS + Linux
+// + Windows) — uses only stdlib. No shell scripts, no `which`, no `test -e`,
+// no `curl`, no `wget`. Timeouts on every network probe so a broken
+// resolver / firewall can't stall boot.
+
+import { execFile } from 'node:child_process';
+import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
+import { promisify } from 'node:util';
+import { arch, platform, release, homedir } from 'node:os';
+import { basename, join, resolve, dirname } from 'node:path';
+import { resolve4 } from 'node:dns/promises';
+import { fileURLToPath } from 'node:url';
+
+const execFileP = promisify(execFile);
+
+const NETWORK_TIMEOUT_MS = 3000;
+const VERSION_TIMEOUT_MS = 3000;
+
+/**
+ * Probe platform facts (OS/kernel/shell). Fast — no child process, no
+ * network.
+ */
+export function probePlatform() {
+  return {
+    os: platform(),
+    arch: arch(),
+    kernel: release(),
+    shell: process.env.SHELL || process.env.COMSPEC || null,
+  };
+}
+
+/**
+ * Probe runtime versions (node, pnpm, git). Parallel; each capped at
+ * VERSION_TIMEOUT_MS.
+ */
+export async function probeRuntimes() {
+  const targets = ['node', 'pnpm', 'git'];
+  const results = await Promise.all(targets.map((name) => probeRuntime(name)));
+  const out = {};
+  for (let i = 0; i < targets.length; i++) {
+    out[targets[i]] = results[i];
+  }
+  return out;
+}
+
+async function probeRuntime(name) {
+  if (name === 'node') {
+    // Fast path — we're running under node, no need to shell out.
+    return { version: process.versions.node, path: process.execPath };
+  }
+  return runVersionProbe(name);
+}
+
+async function runVersionProbe(binName) {
+  try {
+    const { stdout } = await execFileP(binName, ['--version'], { timeout: VERSION_TIMEOUT_MS });
+    const version = stdout.trim().split('\n')[0];
+    const path = await resolveBinPath(binName);
+    return { version, path };
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { version: null, path: null, error: 'not installed' };
+    }
+    return { version: null, path: null, error: err.message };
+  }
+}
+
+/**
+ * Resolve a bin path cross-platform without invoking `which`. Walks PATH
+ * looking for a matching executable.
+ */
+async function resolveBinPath(binName) {
+  const isWin = process.platform === 'win32';
+  const pathEnv = process.env.PATH || '';
+  const sep = isWin ? ';' : ':';
+  const exts = isWin ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : [''];
+  const parts = pathEnv.split(sep).filter(Boolean);
+  for (const dir of parts) {
+    for (const ext of exts) {
+      const candidate = join(dir, binName + ext);
+      try {
+        if (existsSync(candidate)) return candidate;
+      } catch {
+        // ignore per-candidate errors — resolution is best-effort
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Introspect the platform CLI surface. Reads `pa` and other bundled bins
+ * from node_modules if available; otherwise reports installed=false.
+ */
+export function probePlatformCli(repoRoot) {
+  const bins = ['pa', 'desk', 'sync', 'secrets', 'scheduler', 'smoke', 'distill', 'memory-sync', 'pa-init', 'slice', 'launch', 'migrate-inspect'];
+  const pkgJsonPath = join(repoRoot, 'node_modules', '@stravica-ai', 'digital-operator-pa', 'package.json');
+  let version = null;
+  if (existsSync(pkgJsonPath)) {
+    try {
+      const meta = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+      version = meta.version ?? null;
+    } catch {
+      version = null;
+    }
+  }
+  const out = {};
+  for (const bin of bins) {
+    const shimPath = join(repoRoot, 'node_modules', '.bin', bin);
+    if (existsSync(shimPath)) {
+      out[bin] = { version, path: shimPath };
+    } else {
+      out[bin] = { version: null, path: null, installed: false };
+    }
+  }
+  return out;
+}
+
+/**
+ * List operator extension tools. Each subdir under
+ * operator/extensions/tools/ counts. Missing dir returns an empty array.
+ */
+export function probeCustomTools(repoRoot) {
+  const dir = join(repoRoot, 'operator', 'extensions', 'tools');
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir)
+      .filter((name) => !name.startsWith('.'))
+      .filter((name) => statSync(join(dir, name)).isDirectory())
+      .map((name) => ({ name, path: join(dir, name) }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Network probes — DNS (github.com by default) and HTTP HEAD (cloudflare
+ * DNS by default). Both capped at NETWORK_TIMEOUT_MS. Failures record an
+ * `error` field but do NOT block the write.
+ */
+export async function probeNetwork({ dnsTarget = 'github.com', httpTarget = 'https://1.1.1.1', skip = false } = {}) {
+  if (skip) {
+    return {
+      dns: { target: dnsTarget, skipped: true },
+      http: { target: httpTarget, skipped: true },
+    };
+  }
+  const [dns, http] = await Promise.all([
+    probeDns(dnsTarget),
+    probeHttp(httpTarget),
+  ]);
+  return { dns, http };
+}
+
+async function probeDns(target) {
+  const start = Date.now();
+  try {
+    const result = await withTimeout(resolve4(target), NETWORK_TIMEOUT_MS);
+    return { target, resolved: result, elapsedMs: Date.now() - start };
+  } catch (err) {
+    return { target, resolved: null, elapsedMs: Date.now() - start, error: err.message };
+  }
+}
+
+async function probeHttp(target) {
+  const start = Date.now();
+  try {
+    const url = new URL(target);
+    const mod = url.protocol === 'https:' ? await import('node:https') : await import('node:http');
+    const res = await withTimeout(new Promise((res, rej) => {
+      const req = mod.request({
+        hostname: url.hostname,
+        port: url.port || (url.protocol === 'https:' ? 443 : 80),
+        path: url.pathname + url.search,
+        method: 'HEAD',
+        timeout: NETWORK_TIMEOUT_MS,
+      }, (r) => {
+        r.resume(); // drain
+        res({ statusCode: r.statusCode });
+      });
+      req.on('error', rej);
+      req.on('timeout', () => {
+        req.destroy(new Error('timeout'));
+      });
+      req.end();
+    }), NETWORK_TIMEOUT_MS);
+    return { target, statusCode: res.statusCode, elapsedMs: Date.now() - start };
+  } catch (err) {
+    return { target, statusCode: null, elapsedMs: Date.now() - start, error: err.message };
+  }
+}
+
+async function withTimeout(promise, ms) {
+  let timer;
+  const timeoutPromise = new Promise((_, rej) => {
+    timer = setTimeout(() => rej(new Error(`timeout after ${ms}ms`)), ms);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Workspace port + reachability. Reads port from operator preferences if
+ * present; probes with a TCP connect (fast — no HTTP round-trip). Timeout
+ * capped at 1s.
+ */
+export async function probeWorkspace(repoRoot) {
+  const port = readWorkspacePort(repoRoot);
+  const net = await import('node:net');
+  const running = await new Promise((res) => {
+    const socket = new net.Socket();
+    let done = false;
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      try { socket.destroy(); } catch { /* ignore */ }
+      res(value);
+    };
+    socket.setTimeout(1000);
+    socket.once('connect', () => finish(true));
+    socket.once('error', () => finish(false));
+    socket.once('timeout', () => finish(false));
+    socket.connect(port, '127.0.0.1');
+  });
+  return {
+    port,
+    running,
+    url: `http://localhost:${port}`,
+  };
+}
+
+function readWorkspacePort(repoRoot) {
+  try {
+    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
+    if (existsSync(prefsPath)) {
+      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
+      if (typeof prefs.workspacePort === 'number') return prefs.workspacePort;
+    }
+  } catch {
+    // fall through
+  }
+  return 4200;
+}
+
+/**
+ * Working directory + project root resolution. Search-upward for an
+ * `agents/<name>/CLAUDE.md` marker or a `.git` ancestor. Env var override
+ * honoured — any `<...>_ROOT` env var whose value is a valid prefix of cwd.
+ */
+export function probeWorkingDirectory(cwd = process.cwd()) {
+  const projectRoot = findProjectRoot(cwd);
+  return {
+    cwd,
+    projectRoot: projectRoot?.path ?? null,
+    resolvedVia: projectRoot?.via ?? 'unresolved',
+  };
+}
+
+function findProjectRoot(cwd) {
+  // 1. Any *_ROOT env var whose value contains cwd.
+  for (const [name, value] of Object.entries(process.env)) {
+    if (!name.endsWith('_ROOT')) continue;
+    if (typeof value !== 'string' || value.length === 0) continue;
+    const abs = resolve(value);
+    if (cwd.startsWith(abs)) {
+      return { path: abs, via: `env:${name}` };
+    }
+  }
+  // 2. Walk upward looking for an agents/<name>/CLAUDE.md marker.
+  let d = cwd;
+  while (d && d !== dirname(d)) {
+    const agentsDir = join(d, 'agents');
+    if (existsSync(agentsDir)) {
+      try {
+        const children = readdirSync(agentsDir);
+        for (const child of children) {
+          if (existsSync(join(agentsDir, child, 'CLAUDE.md'))) {
+            return { path: d, via: 'agents-marker' };
+          }
+        }
+      } catch {
+        // ignore; keep walking
+      }
+    }
+    d = dirname(d);
+  }
+  // 3. Walk upward looking for .git.
+  d = cwd;
+  while (d && d !== dirname(d)) {
+    if (existsSync(join(d, '.git'))) {
+      return { path: d, via: 'git-ancestor' };
+    }
+    d = dirname(d);
+  }
+  return null;
+}
+
+// Test seam — expose the module's own dir for callers that want it.
+export const __moduleDir = dirname(fileURLToPath(import.meta.url));

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

@@ -0,0 +1,148 @@
+// auth.mjs — Service-account credential loading for Google Search Console.
+//
+// Reads the SA JSON from the SOPS vault under the configured key (default
+// GSC_SERVICE_ACCOUNT_KEY) and constructs a JWT-authenticated client
+// scoped for Search Console.
+//
+// All Google SDK imports are lazy — tests inject a mock `googleClient`
+// override and never touch the network. The SA-key read also accepts an
+// override so tests can pass in a synthetic key without going through SOPS.
+
+import { defaultPaths, checkVault, secretsFileExists, sopsDecrypt, VaultError } from '../secrets/vault.mjs';
+
+// Read-only scope: searchanalytics.query + sites.list + sitemaps.list.
+// Read-write scope: sites.add, sitemaps.submit, site verification.
+// We always use the read-write scope — the same client services every verb
+// and the operator has explicitly granted the SA per-property, so there is
+// no privilege-escalation risk inside the SA's own GSC surface.
+export const GSC_SCOPES = [
+  'https://www.googleapis.com/auth/webmasters',
+  'https://www.googleapis.com/auth/siteverification',
+];
+
+const DEFAULT_VAULT_KEY = 'GSC_SERVICE_ACCOUNT_KEY';
+
+/**
+ * Load the service-account JSON object from the SOPS vault.
+ *
+ * @param {object} overrides
+ * @param {object} [overrides.paths]      Vault paths (from defaultPaths()).
+ * @param {string} [overrides.vaultKey]   Vault key name (default GSC_SERVICE_ACCOUNT_KEY).
+ * @param {string} [overrides.serviceAccountKey]
+ *        Raw SA JSON string. If provided, skips vault entirely (testing).
+ * @returns {Promise<object>} Parsed service-account JSON.
+ */
+export async function loadServiceAccountKey(overrides = {}) {
+  if (overrides.serviceAccountKey) {
+    return typeof overrides.serviceAccountKey === 'string'
+      ? JSON.parse(overrides.serviceAccountKey)
+      : overrides.serviceAccountKey;
+  }
+
+  const paths = overrides.paths || defaultPaths();
+  const vaultKey = overrides.vaultKey || DEFAULT_VAULT_KEY;
+
+  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,
+    );
+  }
+  const data = await sopsDecrypt(paths, paths.secretsFile);
+  if (!(vaultKey in data)) {
+    throw new VaultError(
+      `Vault key "${vaultKey}" not found. Store the service-account JSON with:\n  secrets set ${vaultKey} -\n(then paste the JSON, then Ctrl-D)`,
+      1,
+    );
+  }
+  const raw = data[vaultKey];
+  try {
+    return typeof raw === 'string' ? JSON.parse(raw) : raw;
+  } catch (e) {
+    throw new VaultError(
+      `Vault key "${vaultKey}" is not valid JSON: ${e.message}`,
+      2,
+    );
+  }
+}
+
+/**
+ * Build a Google Search Console client (webmasters v3 + siteverification v1).
+ *
+ * The Google SDK packages are imported lazily so the rest of the CLI
+ * (and tests for non-Google paths) work without them being installed.
+ *
+ * @param {object} overrides
+ * @param {object} [overrides.googleClient]  Pre-built client (for tests).
+ *        Shape: { webmasters, siteVerification }
+ * @returns {Promise<{webmasters: object, siteVerification: object}>}
+ */
+export async function buildGscClient(overrides = {}) {
+  if (overrides.googleClient) return overrides.googleClient;
+
+  const key = await loadServiceAccountKey(overrides);
+
+  let googleapis;
+  let googleAuthLibrary;
+  try {
+    googleapis = await import('googleapis');
+    googleAuthLibrary = await import('google-auth-library');
+  } catch (e) {
+    throw Object.assign(
+      new Error(
+        'Google SDK packages not installed. Run `pnpm install` in the ' +
+        'package root so `googleapis` and `google-auth-library` are ' +
+        'available. (' + e.message + ')',
+      ),
+      { exitCode: 3 },
+    );
+  }
+
+  const { JWT } = googleAuthLibrary;
+  const auth = new JWT({
+    email: key.client_email,
+    key: key.private_key,
+    scopes: GSC_SCOPES,
+  });
+
+  const { google } = googleapis;
+  return {
+    webmasters: google.webmasters({ version: 'v3', auth }),
+    siteVerification: google.siteVerification({ version: 'v1', auth }),
+    auth,
+  };
+}
+
+/**
+ * Normalise a domain into the GSC domain-property siteUrl form.
+ *
+ *   foo.com         -> sc-domain:foo.com
+ *   www.foo.com     -> sc-domain:www.foo.com
+ *   sc-domain:foo.com -> sc-domain:foo.com (idempotent)
+ *   https://foo.com -> sc-domain:foo.com (strip scheme + path)
+ *
+ * Domain-property is the modern GSC default (covers https + http + all
+ * subdomains under a single property). URL-prefix properties are legacy.
+ */
+export function toDomainProperty(input) {
+  if (!input) throw new Error('domain is required');
+  let s = String(input).trim();
+  if (s.startsWith('sc-domain:')) return s;
+  // Strip scheme + any path.
+  s = s.replace(/^https?:\/\//i, '');
+  s = s.split('/')[0];
+  // Strip trailing dot if present.
+  s = s.replace(/\.$/, '');
+  return `sc-domain:${s.toLowerCase()}`;
+}
+
+/**
+ * Strip `sc-domain:` prefix from a property URL, returning the bare domain.
+ */
+export function bareDomain(siteUrl) {
+  return String(siteUrl || '').replace(/^sc-domain:/, '');
+}

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

@@ -0,0 +1,93 @@
+// gsc — Google Search Console subcommand router.
+//
+// Wired as `pa gsc <verb>` (verb-second pattern, mirrors `pa workspace`).
+// Each verb routes to a command module under ./commands/.
+//
+// Exit codes (@stravica-ai/engineering-pa-core/docs/standards/tooling.md §6):
+//   0 ok | 1 usage error | 2 operational failure | 3 transport/IO failure
+
+import { runAddProperty } from './commands/add-property.mjs';
+import { runVerifyViaCfDns } from './commands/verify-via-cf-dns.mjs';
+import { runSubmitSitemap } from './commands/submit-sitemap.mjs';
+import { runPullAnalytics } from './commands/pull-analytics.mjs';
+import { runListProperties } from './commands/list-properties.mjs';
+
+const HELP = `pa gsc — Google Search Console automation
+
+Usage:
+  pa gsc add-property <domain>
+      Register a domain-property in Search Console (sites.add).
+      Returns the verification TXT token.
+
+  pa gsc verify-via-cf-dns <domain> [--wait SECONDS] [--account NAME]
+      Plant the GSC verification TXT record at the domain's Cloudflare
+      zone, wait for propagation, then trigger GSC verification.
+      --account selects which Cloudflare account's vault keys to use
+      (e.g. --account stravica, --account clive). Omit for the default
+      (unsuffixed) vault pair.
+
+  pa gsc submit-sitemap <domain> <sitemap-url>
+      Submit a sitemap to GSC for the property.
+
+  pa gsc pull-analytics <domain> [--days N] [--dimensions D1,D2,...] [--rows N]
+      Pull search-analytics rows. Defaults: --days 28 --dimensions query
+      --rows 100. Outputs a JSON array on stdout.
+
+  pa gsc list-properties
+      List every GSC property the service account can see. Useful for
+      verifying SA setup ("did I add the SA email as a user on the right
+      property?").
+
+  pa gsc -h, --help
+      Show this help.
+
+Auth (one-time setup; see docs/gsc.md):
+  - Google service-account JSON stored in the SOPS vault under
+    GSC_SERVICE_ACCOUNT_KEY (entire JSON contents as the value).
+  - SA email added as a user on each GSC property via the GSC dashboard.
+
+Cloudflare DNS planting reads two vault keys. Resolution order:
+  1. With --account <name>: CLOUDFLARE_PAGES_API_KEY_<NAME> +
+                            CLOUDFLARE_PAGES_ACCOUNT_ID_<NAME>
+                            (e.g. --account stravica -> *_STRAVICA pair)
+  2. Without --account:     CLOUDFLARE_PAGES_API_KEY +
+                            CLOUDFLARE_PAGES_ACCOUNT_ID
+  3. Legacy fallback:       CLOUDFLARE_API_TOKEN +
+                            CLOUDFLARE_ACCOUNT_ID
+`;
+
+export async function run(argv, overrides = {}) {
+  const verb = argv[0];
+  const rest = argv.slice(1);
+
+  if (!verb || verb === '--help' || verb === '-h' || verb === 'help') {
+    process.stdout.write(HELP);
+    return verb ? 0 : 1;
+  }
+
+  switch (verb) {
+    case 'add-property':       return runAddProperty(rest, overrides);
+    case 'verify-via-cf-dns':  return runVerifyViaCfDns(rest, overrides);
+    case 'submit-sitemap':     return runSubmitSitemap(rest, overrides);
+    case 'pull-analytics':     return runPullAnalytics(rest, overrides);
+    case 'list-properties':    return runListProperties(rest, overrides);
+    default: {
+      process.stderr.write(`[pa gsc] unknown verb: ${verb}\n`);
+      process.stderr.write(HELP);
+      return 1;
+    }
+  }
+}
+
+export async function main(argv, overrides = {}) {
+  try {
+    const code = await run(argv, overrides);
+    return code ?? 0;
+  } catch (err) {
+    const code = err && typeof err.exitCode === 'number' ? err.exitCode : 2;
+    if (!err || err.exitCode == null) {
+      process.stderr.write(`pa gsc: ${err && err.message ? err.message : err}\n`);
+    }
+    return code;
+  }
+}