@stravica-ai/digital-operator-pa 0.1.18 → 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
 
@@ -118,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/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/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,7 +1,7 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.18",
-  "description": "Digital Operator PA \u2014 single-bundled public package surface (bins + library) for the platform.",
+  "version": "0.1.19",
+  "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",
   "exports": {
@@ -49,11 +49,10 @@
   "engines": {
     "node": ">=24"
   },
+  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper — see packages/cli/test/secrets. Counts must never lie.",
   "scripts": {
     "build": "node build.mjs",
-    "prepack": "node build.mjs",
     "test": "node --test --test-isolation=none test/*.test.mjs",
     "dry-publish": "node build.mjs && node scripts/dry-publish.mjs"
-  },
-  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper \u2014 see packages/cli/test/secrets. Counts must never lie."
-}
+  }
+}