@stravica-ai/digital-operator-pa 0.1.17 → 0.1.19

package/dist/engineering-pa-cli/docs/gsc.md

@@ -6,8 +6,9 @@ domain whose DNS lives on Cloudflare in an account the operator controls.
 ## Status
 
 Implemented: `add-property`, `verify-via-cf-dns`, `submit-sitemap`,
-`pull-analytics`, `list-properties`. Auth via Google service-account JSON
-loaded from the SOPS vault. Cloudflare planting via the CF v4 REST API.
+`sitemap-status`, `pull-analytics`, `list-properties`. Auth via Google
+service-account JSON loaded from the SOPS vault. Cloudflare planting via
+the CF v4 REST API.
 
 ## Dependencies
 
@@ -37,10 +38,20 @@ Two npm packages (declared in `@stravica-ai/digital-operator-pa`):
 
 5. **Store the SA key in the SOPS vault**:
    ```bash
+   # Legacy single-file vault:
    pnpm exec secrets set GSC_SERVICE_ACCOUNT_KEY -
+   # Scoped-vault estate (workspace or canonical layout):
+   pnpm exec secrets set --scope <scope> GSC_SERVICE_ACCOUNT_KEY -
    # paste the entire JSON contents, then Ctrl-D
    ```
 
+   On scoped-vault hosts, `pa gsc` reads the key from whichever pot
+   `secrets get` would use — i.e. it honours (in order) `SECRETS_DEFAULT_SCOPE`,
+   the `defaultScope` in `~/.config/stravica-pa/defaults.json`, or the
+   calling PA's `identity.json` — before falling back to the legacy
+   single-file vault. Store the key in the pot the host is already
+   configured to read; no `pa gsc`-specific configuration is needed.
+
 6. **Store Cloudflare credentials** (also one-time). Two key shapes are
    supported; pick whichever fits your setup:
 
@@ -70,6 +81,10 @@ Two npm packages (declared in `@stravica-ai/digital-operator-pa`):
    no `--account` flag is passed and the `CLOUDFLARE_PAGES_*` unsuffixed
    pair is absent. Don't rely on it — set the `CLOUDFLARE_PAGES_*` keys.
 
+   Same scoped-vault note as the SA key: on scoped hosts these live in
+   whichever pot `secrets get` reads (see step 5); use `secrets set --scope
+   <scope> ...` to store them there.
+
 ## Per-domain setup (each time you onboard a new property)
 
 7. **Grant the service-account access to the GSC property.** Until the
@@ -104,6 +119,11 @@ pnpm exec pa gsc verify-via-cf-dns besafetraining.co.uk --account clive
 # Submit a sitemap
 pnpm exec pa gsc submit-sitemap stravica.ai https://stravica.ai/sitemap.xml
 
+# Read sitemap state (list every sitemap the property has)
+pnpm exec pa gsc sitemap-status stravica.ai
+# Read state for one named sitemap
+pnpm exec pa gsc sitemap-status stravica.ai https://stravica.ai/sitemap.xml
+
 # Pull search analytics (default 28d, top queries, 100 rows)
 pnpm exec pa gsc pull-analytics stravica.ai
 pnpm exec pa gsc pull-analytics stravica.ai --days 90 --dimensions query,page --rows 500

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

@@ -8,7 +8,7 @@
 // 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';
+import { resolveCommandPaths, 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.
@@ -25,9 +25,26 @@ const DEFAULT_VAULT_KEY = 'GSC_SERVICE_ACCOUNT_KEY';
 /**
  * Load the service-account JSON object from the SOPS vault.
  *
+ * Vault path resolution goes through `resolveCommandPaths` — the same
+ * resolver `secrets get`/`set` use — so this honours all the same layouts
+ * without duplicating logic: an explicit `overrides.paths` (from a
+ * pre-resolved `--scope`/`--file`) is a pass-through; otherwise the
+ * default-scope resolver runs (SECRETS_DEFAULT_SCOPE env, defaultScope in
+ * ~/.config/stravica-pa/defaults.json, or the calling PA's identity.json)
+ * and points at a scoped `.vault/scopes/<scope>.enc.json`; if nothing is
+ * configured anywhere it falls back to the legacy single-file vault.
+ *
+ * A stderr `note: writing to '<scope>' pot ...` line is printed by the
+ * resolver on the default-scope path — same behaviour as `secrets get`,
+ * kept intentionally consistent so operators see the same routing signal
+ * from every consumer of the vault.
+ *
  * @param {object} overrides
- * @param {object} [overrides.paths]      Vault paths (from defaultPaths()).
+ * @param {object} [overrides.paths]      Vault paths already resolved (e.g. from --scope upstream).
  * @param {string} [overrides.vaultKey]   Vault key name (default GSC_SERVICE_ACCOUNT_KEY).
+ * @param {string} [overrides.cwd]        Test seam — cwd used for workspace resolution.
+ * @param {object} [overrides.env]        Test seam — env used for scope-default resolution.
+ * @param {string} [overrides.home]       Test seam — home used for keyfile + defaults.json lookup.
  * @param {string} [overrides.serviceAccountKey]
  *        Raw SA JSON string. If provided, skips vault entirely (testing).
  * @returns {Promise<object>} Parsed service-account JSON.
@@ -39,34 +56,39 @@ export async function loadServiceAccountKey(overrides = {}) {
       : overrides.serviceAccountKey;
   }
 
-  const paths = overrides.paths || defaultPaths();
+  const paths = resolveCommandPaths(overrides);
   const vaultKey = overrides.vaultKey || DEFAULT_VAULT_KEY;
 
   const state = checkVault(paths);
   if (!state.ok) {
+    // Print then throw — main() suppresses messages for errors that carry
+    // an exitCode (the throw-site is expected to have reported), so
+    // omitting the console.error would exit silently through the pa gsc
+    // binary.
+    console.error(state.message);
     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 message = `No secrets file at ${paths.secretsFile}.` + (paths.scoped
+      ? ` Store the service-account JSON with:\n  secrets set --scope ${paths.scope} ${vaultKey} -\n(then paste the JSON, then Ctrl-D)`
+      : " Run 'secrets init' first.");
+    console.error(message);
+    throw new VaultError(message, 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 scopeHint = paths.scoped ? ` --scope ${paths.scope}` : '';
+    const message = `Vault key "${vaultKey}" not found in ${paths.secretsFile}. Store the service-account JSON with:\n  secrets set${scopeHint} ${vaultKey} -\n(then paste the JSON, then Ctrl-D)`;
+    console.error(message);
+    throw new VaultError(message, 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,
-    );
+    const message = `Vault key "${vaultKey}" is not valid JSON: ${e.message}`;
+    console.error(message);
+    throw new VaultError(message, 2);
   }
 }
 

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

@@ -9,6 +9,7 @@
 import { runAddProperty } from './commands/add-property.mjs';
 import { runVerifyViaCfDns } from './commands/verify-via-cf-dns.mjs';
 import { runSubmitSitemap } from './commands/submit-sitemap.mjs';
+import { runSitemapStatus } from './commands/sitemap-status.mjs';
 import { runPullAnalytics } from './commands/pull-analytics.mjs';
 import { runListProperties } from './commands/list-properties.mjs';
 
@@ -29,6 +30,12 @@ Usage:
   pa gsc submit-sitemap <domain> <sitemap-url>
       Submit a sitemap to GSC for the property.
 
+  pa gsc sitemap-status <domain> [sitemap-url]
+      Read sitemap state for the property (sitemaps.list) or one named
+      sitemap (sitemaps.get). Reports path, lastSubmitted, lastDownloaded,
+      isPending, warnings, errors, and per-type contents[] submitted/indexed
+      counts. Read-only.
+
   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.
@@ -69,6 +76,7 @@ export async function run(argv, overrides = {}) {
     case 'add-property':       return runAddProperty(rest, overrides);
     case 'verify-via-cf-dns':  return runVerifyViaCfDns(rest, overrides);
     case 'submit-sitemap':     return runSubmitSitemap(rest, overrides);
+    case 'sitemap-status':     return runSitemapStatus(rest, overrides);
     case 'pull-analytics':     return runPullAnalytics(rest, overrides);
     case 'list-properties':    return runListProperties(rest, overrides);
     default: {

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

@@ -24,7 +24,7 @@
 //
 // `fetchImpl` and `now` are injectable for tests.
 
-import { defaultPaths, checkVault, secretsFileExists, sopsDecrypt, VaultError } from '../secrets/vault.mjs';
+import { resolveCommandPaths, checkVault, secretsFileExists, sopsDecrypt, VaultError } from '../secrets/vault.mjs';
 
 const CF_API = 'https://api.cloudflare.com/client/v4';
 
@@ -122,14 +122,23 @@ export async function loadCloudflareCreds(overrides = {}) {
   if (overrides.vaultData) {
     data = overrides.vaultData;
   } else {
-    const paths = overrides.paths || defaultPaths();
+    // resolveCommandPaths honours --scope/--file (via a pre-resolved
+    // overrides.paths), the SECRETS_DEFAULT_SCOPE env, defaults.json's
+    // defaultScope, and the calling PA's identity.json, before falling
+    // back to the legacy single-file vault. Same routing as `secrets get`
+    // and `pa gsc`'s SA-key loader — one resolver, one routing signal.
+    const paths = resolveCommandPaths(overrides);
     const state = checkVault(paths);
-    if (!state.ok) throw new VaultError(state.message, state.exitCode ?? 1);
+    if (!state.ok) {
+      console.error(state.message);
+      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 message = `No secrets file at ${paths.secretsFile}.` + (paths.scoped
+        ? ` Store Cloudflare credentials with 'secrets set --scope ${paths.scope} <KEY> <value>'.`
+        : " Run 'secrets init' first.");
+      console.error(message);
+      throw new VaultError(message, 1);
     }
     data = await sopsDecrypt(paths, paths.secretsFile);
   }

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

@@ -0,0 +1,95 @@
+// sitemap-status — Read sitemap state for a GSC property.
+//
+// Wraps webmasters.sitemaps.list (no sitemap-url) and
+// webmasters.sitemaps.get (with sitemap-url). Both are read-only.
+//
+// Every previous "did the release-time submit take?" check was a one-off
+// workaround — this verb makes it a first-class subcommand so the pattern
+// is repeatable and auditable.
+//
+// Usage:
+//   pa gsc sitemap-status <domain>
+//       List every sitemap the property has, with lastSubmitted,
+//       lastDownloaded, isPending, warnings, errors, and per-type
+//       contents[] submitted/indexed counts.
+//
+//   pa gsc sitemap-status <domain> <sitemap-url>
+//       Same shape, but only for the named sitemap (webmasters.sitemaps.get).
+
+import { buildGscClient, toDomainProperty } from '../auth.mjs';
+
+/**
+ * Normalise a Sitemap resource from the GSC API into a stable shape.
+ * The GSC API returns warnings/errors/submitted/indexed as strings; we
+ * keep them as strings (matches the wire format so operators reading the
+ * JSON see exactly what the API said).
+ */
+function normaliseSitemap(s = {}) {
+  const contents = Array.isArray(s.contents)
+    ? s.contents.map((c) => ({
+      type: c.type ?? null,
+      submitted: c.submitted ?? null,
+      indexed: c.indexed ?? null,
+    }))
+    : [];
+  return {
+    path: s.path ?? null,
+    lastSubmitted: s.lastSubmitted ?? null,
+    lastDownloaded: s.lastDownloaded ?? null,
+    isPending: s.isPending ?? null,
+    isSitemapsIndex: s.isSitemapsIndex ?? null,
+    type: s.type ?? null,
+    warnings: s.warnings ?? null,
+    errors: s.errors ?? null,
+    contents,
+  };
+}
+
+export async function runSitemapStatus(args, overrides = {}) {
+  const domain = args[0];
+  const sitemapUrl = args[1];
+
+  if (!domain) {
+    process.stderr.write('Usage: pa gsc sitemap-status <domain> [sitemap-url]\n');
+    return 1;
+  }
+  if (sitemapUrl && !/^https?:\/\//i.test(sitemapUrl)) {
+    process.stderr.write(`[gsc sitemap-status] 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 sitemap-status] auth failed: ${e.message}\n`);
+    return e.exitCode || 2;
+  }
+
+  let sitemaps;
+  try {
+    if (sitemapUrl) {
+      const res = await client.webmasters.sitemaps.get({ siteUrl, feedpath: sitemapUrl });
+      // sitemaps.get returns the Sitemap resource directly (no wrapper).
+      sitemaps = [normaliseSitemap(res?.data || {})];
+    } else {
+      const res = await client.webmasters.sitemaps.list({ siteUrl });
+      sitemaps = (res?.data?.sitemap || []).map(normaliseSitemap);
+    }
+  } catch (e) {
+    const verb = sitemapUrl ? 'sitemaps.get' : 'sitemaps.list';
+    process.stderr.write(`[gsc sitemap-status] ${verb} failed: ${e.message}\n`);
+    return 2;
+  }
+
+  const out = overrides.stdout || process.stdout;
+  out.write(JSON.stringify({
+    siteUrl,
+    sitemapUrl: sitemapUrl || null,
+    count: sitemaps.length,
+    sitemaps,
+  }, null, 2) + '\n');
+  return 0;
+}

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

@@ -23,7 +23,7 @@ Usage:
   pa workspace <verb>         Workspace server lifecycle (start | stop | status | open)
   pa project <verb>           Project state writes (create | status | doc add/rm | list)
   pa work <verb>              Work-item state writes (create | status | list)
-  pa gsc <verb>               Google Search Console automation (add-property | verify-via-cf-dns | submit-sitemap | pull-analytics | list-properties)
+  pa gsc <verb>               Google Search Console automation (add-property | verify-via-cf-dns | submit-sitemap | sitemap-status | pull-analytics | list-properties)
   pa knowledge <verb>         Query the operator's knowledge graph (related | search | domain | orphans | path)
   pa research <verb>          Deep-research session store (run | list | show | gates | prune | mark | paths)
   pa autonomy <verb>          Per-agent per-task-type approval state (init | get | set | list)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",