@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/gsc/commands/verify-via-cf-dns.mjs

@@ -0,0 +1,189 @@
+// verify-via-cf-dns — End-to-end GSC verification via Cloudflare DNS.
+//
+// Steps:
+//   1. Get the TXT verification token from Site Verification API.
+//   2. Resolve the Cloudflare zone id for the domain.
+//   3. Plant a TXT record at the apex (idempotent — see plantTxtRecord).
+//   4. Wait for DNS propagation (default 60s, --wait N overrides).
+//   5. Call siteVerification.webResource.insert to confirm ownership.
+//   6. Call webmasters.sites.add to register the domain-property in
+//      Search Console.
+//
+// On any failure the command returns the underlying exit code and prints
+// what it managed to do so the operator can resume from the failure point.
+
+import { buildGscClient, toDomainProperty, bareDomain } from '../auth.mjs';
+import { loadCloudflareCreds, resolveZoneId, plantTxtRecord, sleep } from '../cloudflare.mjs';
+
+const DEFAULT_WAIT_SECONDS = 60;
+
+function parseFlags(args) {
+  const out = { positional: [], wait: DEFAULT_WAIT_SECONDS, account: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--wait') {
+      const n = Number(args[++i]);
+      if (!Number.isFinite(n) || n < 0) {
+        throw Object.assign(new Error(`--wait expects a non-negative number, got "${args[i]}"`), { exitCode: 1 });
+      }
+      out.wait = n;
+    } else if (a.startsWith('--wait=')) {
+      const n = Number(a.slice('--wait='.length));
+      if (!Number.isFinite(n) || n < 0) {
+        throw Object.assign(new Error(`--wait expects a non-negative number, got "${a}"`), { exitCode: 1 });
+      }
+      out.wait = n;
+    } else if (a === '--account') {
+      const v = args[++i];
+      if (!v || v.startsWith('--')) {
+        throw Object.assign(new Error('--account expects a value (e.g. --account stravica)'), { exitCode: 1 });
+      }
+      out.account = v;
+    } else if (a.startsWith('--account=')) {
+      const v = a.slice('--account='.length);
+      if (!v) {
+        throw Object.assign(new Error('--account expects a value (e.g. --account=stravica)'), { exitCode: 1 });
+      }
+      out.account = v;
+    } else {
+      out.positional.push(a);
+    }
+  }
+  return out;
+}
+
+export async function runVerifyViaCfDns(args, overrides = {}) {
+  let flags;
+  try { flags = parseFlags(args); } catch (e) {
+    process.stderr.write(`[gsc verify-via-cf-dns] ${e.message}\n`);
+    return e.exitCode || 1;
+  }
+
+  const domain = flags.positional[0];
+  if (!domain) {
+    process.stderr.write('Usage: pa gsc verify-via-cf-dns <domain> [--wait SECONDS] [--account NAME]\n');
+    return 1;
+  }
+
+  const siteUrl = toDomainProperty(domain);
+  const bare = bareDomain(siteUrl);
+  const out = overrides.stdout || process.stdout;
+  const log = (msg) => out.write(`[gsc verify] ${msg}\n`);
+
+  const trace = {
+    domain: bare,
+    siteUrl,
+    account: flags.account || null,
+    steps: [],
+  };
+
+  // ── Step 1: get the verification token. ──
+  let client;
+  try {
+    client = await buildGscClient(overrides);
+  } catch (e) {
+    process.stderr.write(`[gsc verify-via-cf-dns] auth failed: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  let token;
+  try {
+    log('fetching verification token...');
+    const res = await client.siteVerification.webResource.getToken({
+      requestBody: {
+        verificationMethod: 'DNS_TXT',
+        site: { type: 'INET_DOMAIN', identifier: bare },
+      },
+    });
+    token = res?.data?.token;
+    if (!token) throw new Error('no token returned');
+    trace.steps.push({ step: 'getToken', ok: true });
+    log(`token obtained (${token.length} chars)`);
+  } catch (e) {
+    trace.steps.push({ step: 'getToken', ok: false, error: e.message });
+    process.stderr.write(`[gsc verify-via-cf-dns] getToken failed: ${e.message}\n`);
+    return 2;
+  }
+
+  // ── Step 2: resolve zone id. ──
+  // The `account` flag is plumbed through `overrides.account` so the vault
+  // lookup resolves the right suffixed key pair. An explicit override here
+  // wins over anything the dispatcher might set in `overrides`.
+  const credOverrides = flags.account ? { ...overrides, account: flags.account } : overrides;
+  let creds;
+  let zone;
+  try {
+    creds = await loadCloudflareCreds(credOverrides);
+    if (creds.account) {
+      log(`using CF account "${creds.account}" (vault keys: ${creds.vaultKeys.tokenKey}, ${creds.vaultKeys.accountIdKey})`);
+    }
+    zone = await resolveZoneId(creds, bare, overrides.fetchImpl);
+    trace.steps.push({ step: 'resolveZone', ok: true, zoneId: zone.zoneId, zoneName: zone.zoneName });
+    log(`zone: ${zone.zoneName} (${zone.zoneId})`);
+  } catch (e) {
+    trace.steps.push({ step: 'resolveZone', ok: false, error: e.message });
+    process.stderr.write(`[gsc verify-via-cf-dns] CF zone lookup failed: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  // ── Step 3: plant TXT at apex. ──
+  let plantResult;
+  try {
+    plantResult = await plantTxtRecord(creds, zone.zoneId, bare, token, overrides.fetchImpl);
+    trace.steps.push({ step: 'plantTxt', ok: true, action: plantResult.action });
+    log(`TXT record ${plantResult.action} at apex (${bare})`);
+  } catch (e) {
+    trace.steps.push({ step: 'plantTxt', ok: false, error: e.message });
+    process.stderr.write(`[gsc verify-via-cf-dns] DNS planting failed: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  // ── Step 4: wait for propagation. ──
+  if (flags.wait > 0) {
+    log(`waiting ${flags.wait}s for DNS propagation...`);
+    await sleep(flags.wait * 1000, overrides.sleepImpl);
+  }
+
+  // ── Step 5: verify ownership. ──
+  try {
+    log('calling siteVerification.webResource.insert...');
+    await client.siteVerification.webResource.insert({
+      verificationMethod: 'DNS_TXT',
+      requestBody: {
+        site: { type: 'INET_DOMAIN', identifier: bare },
+      },
+    });
+    trace.steps.push({ step: 'verify', ok: true });
+    log('verification succeeded');
+  } catch (e) {
+    trace.steps.push({ step: 'verify', ok: false, error: e.message });
+    process.stderr.write(
+      `[gsc verify-via-cf-dns] verification failed: ${e.message}\n` +
+      `  The TXT record may not have propagated yet. Retry with: pa gsc verify-via-cf-dns ${bare} --wait 120\n`,
+    );
+    return 2;
+  }
+
+  // ── Step 6: register property in Search Console. ──
+  try {
+    log(`registering ${siteUrl} in Search Console...`);
+    await client.webmasters.sites.add({ siteUrl });
+    trace.steps.push({ step: 'sitesAdd', ok: true });
+    log('property registered');
+  } catch (e) {
+    // 409 already-exists is benign; surface it as ok.
+    const code = e?.code || e?.response?.status;
+    if (code === 409 || /already exists/i.test(e.message || '')) {
+      trace.steps.push({ step: 'sitesAdd', ok: true, note: 'already exists' });
+      log('property already registered (idempotent)');
+    } else {
+      trace.steps.push({ step: 'sitesAdd', ok: false, error: e.message });
+      process.stderr.write(`[gsc verify-via-cf-dns] sites.add failed: ${e.message}\n`);
+      return 2;
+    }
+  }
+
+  trace.verified = true;
+  out.write(JSON.stringify(trace, null, 2) + '\n');
+  return 0;
+}

package/dist/engineering-pa-cli/src/knowledge/call-log.mjs

@@ -0,0 +1,59 @@
+// call-log.mjs — best-effort JSONL logger for `pa knowledge` invocations.
+//
+// Purpose (Deliverable B, w-2026-07-06-020): the eval set proves the
+// system CAN retrieve; this log shows whether sessions DO retrieve.
+// Written to `<repoRoot>/.session/knowledge-calls.jsonl` — per-host,
+// gitignored. The Librarian periodically scans the tail to spot queries
+// that repeatedly miss; those become new eval cases.
+//
+// Line schema (camelCase per estate convention):
+//   { timestamp, query, verb, resultCount, sessionId }
+//
+// Discipline: this file MUST NOT throw or reject. A broken .session dir,
+// permission error, or missing repo root are all silent no-ops — the log
+// is an observability aid, not a critical path.
+
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { getRepoRoot } from '../pa/repo-root.mjs';
+
+const LOG_RELATIVE_PATH = '.session/knowledge-calls.jsonl';
+
+// Session id: a short random tag captured once per process. The intent
+// is grouping — the Librarian wants to see "which queries came from the
+// same shell / same task", not to correlate across restarts.
+let sessionId = null;
+function ensureSessionId() {
+  if (sessionId) return sessionId;
+  if (process.env.CLAUDE_SESSION_ID) {
+    sessionId = process.env.CLAUDE_SESSION_ID.slice(0, 32);
+    return sessionId;
+  }
+  if (process.env.PA_SESSION_ID) {
+    sessionId = process.env.PA_SESSION_ID.slice(0, 32);
+    return sessionId;
+  }
+  sessionId = Math.random().toString(36).slice(2, 10) + '-' + process.pid;
+  return sessionId;
+}
+
+export async function appendCallLog({ verb, query, resultCount, timestamp } = {}) {
+  const repoRoot = await getRepoRoot().catch(() => null);
+  if (!repoRoot) return;
+  const target = join(repoRoot, LOG_RELATIVE_PATH);
+  const line = JSON.stringify({
+    timestamp: timestamp ?? new Date().toISOString(),
+    query: query ?? null,
+    verb,
+    resultCount,
+    sessionId: ensureSessionId(),
+  }) + '\n';
+  try {
+    await mkdir(join(repoRoot, '.session'), { recursive: true });
+    await appendFile(target, line, 'utf8');
+  } catch { /* no-op — see file header */ }
+}
+
+// Test seams.
+export const _internals = { LOG_RELATIVE_PATH, ensureSessionId };

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

@@ -0,0 +1,242 @@
+// cli.mjs — argv router for `pa knowledge <verb>`.
+//
+// Verbs (6):
+//   pa knowledge related <slug> [--in|--out]
+//   pa knowledge search  <term> [--full] [--strict]
+//   pa knowledge domain  <name>
+//   pa knowledge orphans [--exclude-stubs]
+//   pa knowledge path    <a> <b>
+//   pa knowledge eval    [--fixture PATH] [--out DIR] [--full] [--format ...]
+//
+// Global flag:
+//   --format <table|json|mermaid>   default: table
+//
+// Repo-root resolution: DAVE_REPO_ROOT / PA_REPO_ROOT env var, else walk
+// upward from cwd until a `.git` ancestor is found (same as `pa work` /
+// `pa project` via `pa/repo-root.mjs`).
+//
+// Exit codes (tooling standard §6):
+//   0 ok  |  1 usage  |  2 unknown-slug / ambiguous / unknown-domain
+//   3 IO (graph missing or unreadable)
+
+import { getRepoRoot, loadGraph, related, search, searchCascade, domain, orphans, path } from './graph.mjs';
+import { formatRelated, formatSearch, formatDomain, formatOrphans, formatPath } from './formatters.mjs';
+import { appendCallLog } from './call-log.mjs';
+
+const USAGE = `pa knowledge — query the operator's knowledge graph
+
+Usage:
+  pa knowledge related <slug>          1-hop neighbourhood for a doc
+                       [--in|--out]     limit to inbound / outbound edges
+  pa knowledge search  <term>          Find docs matching a term. Multi-word
+                                       terms AND-match: every word must appear
+                                       in the doc's id or title (or body with
+                                       --full) — e.g. search "barry voice".
+                                       On a zero-result AND-match, the default
+                                       cascade retries with body (--full) and
+                                       then as OR-match ranked by hits, then
+                                       prints a guided miss with nearest
+                                       domains — never a bare "(no matches)".
+                       [--full]        Include doc body (default: title only)
+                       [--strict]      Disable the cascade — restores the
+                                       AND-only behaviour for scripted callers
+  pa knowledge domain  <name>          All docs in a domain + internal edges
+  pa knowledge orphans                 Docs with no inbound edges
+                       [--exclude-stubs]  Skip null-domain nodes
+  pa knowledge path    <a> <b>         Shortest path between two docs
+  pa knowledge eval    [--fixture P]   Score the retrieval eval set (hit@1/5,
+                       [--out D]        orphan gauge, delta vs last run);
+                       [--full]         persists to
+                       [--format ...]   operator/knowledge/_meta/retrieval-eval-runs/
+  pa knowledge -h, --help              Show this help
+
+Global flags:
+  --format <table|json|mermaid>        Output format (default: table)
+
+Slug resolution: <slug> matches against node id (exact, or path-suffix)
+and node title (case-insensitive substring). Ambiguous matches exit 2.
+
+Domains (from the current operator graph):
+  claude-code-learnings, clients, engineering, hr, principles.md, systems, writing
+
+Graph location: <repo-root>/operator/knowledge/.graph.json.
+Repo-root resolution: \$DAVE_REPO_ROOT / \$PA_REPO_ROOT, else walk upward
+from cwd looking for a .git entry.
+
+JSON output shape (stable-by-convention — consumed by dispatch-briefer):
+  { "verb": "<name>", ...verb-specific fields }
+
+Exit codes (tooling standard §6):
+  0 ok | 1 usage error | 2 unknown/ambiguous slug or domain | 3 IO failure
+`;
+
+export async function run(argv) {
+  if (!argv.length || argv[0] === '-h' || argv[0] === '--help') {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const verb = argv[0];
+  const rest = argv.slice(1);
+  try {
+    switch (verb) {
+      case 'related':  return await doRelated(rest);
+      case 'search':   return await doSearch(rest);
+      case 'domain':   return await doDomain(rest);
+      case 'orphans':  return await doOrphans(rest);
+      case 'path':     return await doPath(rest);
+      case 'eval': {
+        const { run: runEval } = await import('./eval.mjs');
+        return await runEval(rest);
+      }
+      default:
+        process.stderr.write(`[pa knowledge] unknown verb: ${verb}\n`);
+        process.stderr.write(USAGE);
+        return 1;
+    }
+  } catch (err) {
+    process.stderr.write(`[pa knowledge] ${err.message || err}\n`);
+    return err.exitCode || 2;
+  }
+}
+
+// Best-effort call-log append. Failures are swallowed — a broken .session
+// dir must never break `pa knowledge`. Awaited (not fire-and-forget) so
+// the append lands before the CLI process exits; the underlying write is
+// on the order of 1-2 ms so this is not a user-perceptible delay.
+async function logCall(entry) {
+  try { await appendCallLog(entry); } catch { /* see file header */ }
+}
+
+// --- flag parser (bespoke to keep zero-dep) -------------------------------
+
+function parseFlags(args) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const peek = args[i + 1];
+      if (peek == null || peek.startsWith('--')) {
+        flags[key] = true;
+      } else {
+        flags[key] = peek;
+        i += 1;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+
+function resolveFormat(flags) {
+  const raw = flags.format;
+  if (raw == null || raw === true) return 'table';
+  if (raw !== 'table' && raw !== 'json' && raw !== 'mermaid') {
+    const err = new Error(`unknown --format: ${raw} (expected table | json | mermaid)`);
+    err.exitCode = 1;
+    throw err;
+  }
+  return raw;
+}
+
+async function loadGraphOrExplain() {
+  const repoRoot = await getRepoRoot();
+  const graph = await loadGraph({ repoRoot });
+  return { repoRoot, graph };
+}
+
+// --- verbs ----------------------------------------------------------------
+
+async function doRelated(args) {
+  const { positional, flags } = parseFlags(args);
+  const format = resolveFormat(flags);
+  if (positional.length === 0) {
+    process.stderr.write('usage: pa knowledge related <slug> [--in|--out] [--format ...]\n');
+    return 1;
+  }
+  if (flags.in && flags.out) {
+    process.stderr.write('usage: pa knowledge related — --in and --out are mutually exclusive\n');
+    return 1;
+  }
+  const direction = flags.in ? 'in' : flags.out ? 'out' : 'both';
+  const { graph } = await loadGraphOrExplain();
+  const result = related(graph, positional[0], { direction });
+  process.stdout.write(formatRelated(result, format));
+  await logCall({ verb: 'related', query: positional[0], resultCount: result.neighbours.length });
+  return 0;
+}
+
+async function doSearch(args) {
+  const { positional, flags } = parseFlags(args);
+  const format = resolveFormat(flags);
+  if (positional.length === 0) {
+    process.stderr.write('usage: pa knowledge search <term> [--full] [--strict] [--format ...]\n');
+    return 1;
+  }
+  const full = flags.full === true;
+  const strict = flags.strict === true;
+  // Accept both `search "barry voice"` and unquoted `search barry voice` —
+  // all positionals form the query; tokenisation happens in search().
+  const term = positional.join(' ');
+  const { repoRoot, graph } = await loadGraphOrExplain();
+  if (strict) {
+    // Scripted-caller escape hatch. Preserves the pre-cascade shape —
+    // results-only, table renders "(no matches)" on empty, JSON envelope
+    // omits `mode` and `hint`. Byte-identical to the pre-Deliverable-A world.
+    const results = await search(graph, term, { full, repoRoot });
+    process.stdout.write(formatSearch(results, format, { term }));
+    await logCall({ verb: 'search', query: term, resultCount: results.length });
+    return 0;
+  }
+  const envelope = await searchCascade(graph, term, { full, repoRoot });
+  process.stdout.write(formatSearch(envelope.results, format, { term, envelope }));
+  await logCall({ verb: 'search', query: term, resultCount: envelope.results.length });
+  return 0;
+}
+
+async function doDomain(args) {
+  const { positional, flags } = parseFlags(args);
+  const format = resolveFormat(flags);
+  if (positional.length === 0) {
+    process.stderr.write('usage: pa knowledge domain <name> [--format ...]\n');
+    return 1;
+  }
+  const { graph } = await loadGraphOrExplain();
+  const result = domain(graph, positional[0]);
+  process.stdout.write(formatDomain(result, format));
+  await logCall({ verb: 'domain', query: positional[0], resultCount: result.nodes.length });
+  return 0;
+}
+
+async function doOrphans(args) {
+  const { flags } = parseFlags(args);
+  const format = resolveFormat(flags);
+  const includeStubs = !(flags['exclude-stubs'] === true);
+  const { graph } = await loadGraphOrExplain();
+  const results = orphans(graph, { includeStubs });
+  process.stdout.write(formatOrphans(results, format));
+  await logCall({ verb: 'orphans', query: null, resultCount: results.length });
+  return 0;
+}
+
+async function doPath(args) {
+  const { positional, flags } = parseFlags(args);
+  const format = resolveFormat(flags);
+  if (positional.length < 2) {
+    process.stderr.write('usage: pa knowledge path <a> <b> [--format ...]\n');
+    return 1;
+  }
+  const { graph } = await loadGraphOrExplain();
+  const result = path(graph, positional[0], positional[1]);
+  process.stdout.write(formatPath(result, format));
+  await logCall({
+    verb: 'path',
+    query: `${positional[0]} → ${positional[1]}`,
+    resultCount: result.path ? result.path.length : 0,
+  });
+  return 0;
+}
+
+export { USAGE };