@aiguru/google-web-operations 0.6.4

package/packages/core/src/doctor.js

@@ -0,0 +1,39 @@
+/**
+ * Human-readable health check: the same facts as setupStatus(), laid out as
+ * a checklist a person can act on. Used by `gwo doctor` and, in text form,
+ * by the chat when the operator asks "is everything set up?".
+ */
+import { setupStatus } from "./admin.js";
+import { HOME_DIR, IS_CHECKOUT, ROOT } from "./paths.js";
+const OK = '  [ok] ', MISSING = '  [--] ', OPT = '  [..] ';
+export function renderDoctor(s = setupStatus()) {
+    const out = [];
+    const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
+    out.push('Google Web Operations: doctor', '');
+    out.push(`${major > 22 || (major === 22 && minor >= 18) ? OK : MISSING}Node ${process.versions.node} (needs 22.18+)`);
+    out.push(`${OK}package ${ROOT}`);
+    out.push(`${OK}state ${IS_CHECKOUT ? 'next to the code (repository checkout)' : HOME_DIR}`);
+    out.push('', 'Google');
+    out.push(`${s.google.clientFile ? OK : MISSING}OAuth client ${s.google.clientFile ?? 'not installed (google_setup_oauth_client, or gwo auth login after saving secrets/oauth-client.json)'}`);
+    out.push(`${s.google.authorised ? OK : MISSING}authorised ${s.google.authorised ? `as ${s.google.email ?? 'unknown account'}` : 'no (google_auth_login or gwo auth login)'}`);
+    for (const [k, v] of Object.entries(s.google.writeScopes))
+        out.push(`${v ? OK : OPT}write scope ${k}${v ? '' : ' (optional; add when that write is needed)'}`);
+    out.push('', 'Environment (.env)');
+    for (const [k, v] of Object.entries(s.env))
+        out.push(`${v ? OK : OPT}${k}${v ? '' : ' not set'}`);
+    out.push('', `Sites (${s.sites.length})`);
+    if (!s.sites.length)
+        out.push(`${MISSING}none registered (ops_add_site or gwo add-site <url> --name "...")`);
+    for (const site of s.sites) {
+        out.push(`  ${site.enabled ? '*' : ' '} ${site.id.padEnd(16)} ${site.host.padEnd(34)} ${site.platform}/${site.tier}, adapter ${site.adapter}${site.adapterConfigured ? '' : ' (not configured)'}`);
+        out.push(`      Search Console ${site.searchConsole ? 'ok' : '--'}   GA4 ${site.ga4PropertyId ? 'ok' : '--'}   Tag Manager ${site.gtm ? 'ok' : '--'}   suppressions ${site.suppressions}`);
+        for (const m of site.missing)
+            out.push(`      missing: ${m}`);
+    }
+    out.push('', 'Next steps');
+    if (!s.nextSteps.length)
+        out.push(`${OK}nothing required`);
+    for (const n of s.nextSteps)
+        out.push(`  - ${n}`);
+    return out.join('\n');
+}

package/packages/core/src/escalate.js

@@ -0,0 +1,36 @@
+const SITE_RULE_KINDS = {
+    'robots.search-blocked': 'crawler-blocked',
+    'geo.ai-blocked': 'crawler-blocked',
+    'host.multiple-live': 'host-split',
+    'sitemap.unreachable': 'sitemap-unreachable',
+};
+/** Pure. Given the previous and current snapshots and their diff, list what must be triaged. */
+export function escalations(before, after, diff) {
+    const out = [];
+    for (const { url, changes } of diff.pageChanges) {
+        for (const c of changes) {
+            const b = c.before, a = c.after;
+            if (c.field === 'status' && typeof b === 'number' && typeof a === 'number' && b < 400 && a >= 400) {
+                out.push({ kind: 'page-broken', url, detail: `was ${b}, now ${a}` });
+            }
+            if (c.field === 'noindex' && b === false && a === true)
+                out.push({ kind: 'noindex-gained', url, detail: 'page is now noindex' });
+            if (c.field === 'canonical' && b && !a)
+                out.push({ kind: 'canonical-lost', url, detail: `canonical ${String(b)} removed` });
+            if ((c.field === 'ga4' || c.field === 'gtm') && Array.isArray(b) && b.length && Array.isArray(a) && !a.length) {
+                out.push({ kind: 'tracking-lost', url, detail: `${c.field.toUpperCase()} id ${b.join(',')} no longer on the page` });
+            }
+        }
+    }
+    // Site-level findings that appeared since last time.
+    for (const id of diff.newFindings) {
+        const rule = id.split('|')[0] ?? '';
+        const kind = SITE_RULE_KINDS[rule];
+        if (kind)
+            out.push({ kind, url: null, detail: `new finding ${rule}` });
+    }
+    if (before.sitemapCount > 0 && after.sitemapCount < before.sitemapCount * 0.8) {
+        out.push({ kind: 'sitemap-shrunk', url: null, detail: `sitemap went from ${before.sitemapCount} to ${after.sitemapCount} URLs` });
+    }
+    return out;
+}

package/packages/core/src/gtm-ops.js

@@ -0,0 +1,311 @@
+/**
+ * Tag Manager operations: reads (containers, versions, snapshot, diff) and
+ * the staged write path.
+ *
+ * Staging protocol, enforced here and not by the host:
+ *   1. gtmStage      every change lands in a workspace named <prefix><date>
+ *                    (policy write_rules.gtm.workspace_name_prefix). Each
+ *                    entity is one performWrite: read, create or update,
+ *                    read back, verify. Policy action gtm.stage.
+ *   2. gtmWorkspaceDiff   workspace status against the live version, with a
+ *                    review token bound to exactly those changes.
+ *   3. gtmPublish    policy action gtm.publish plus the review token. If the
+ *                    workspace or the live version moved since the review,
+ *                    the token no longer matches and nothing is published.
+ *
+ * Nothing here calls a connector's mutating function outside performWrite().
+ */
+import { gtm } from "../../connectors/google/src/index.js";
+import * as storage from "../../storage/src/index.js";
+import { writeRules } from "../../policy/src/index.js";
+import { getSite } from "./registry.js";
+import { performWrite } from "./writes.js";
+/** Resolve a site's container ids, by configured ids or by looking up its public id. */
+export async function gtmContainerFor(siteIdOrHost) {
+    const site = getSite(siteIdOrHost);
+    const tm = site.google.tag_manager ?? {};
+    if (tm.account_id && tm.container_id)
+        return { site, accountId: tm.account_id, containerId: tm.container_id, publicId: tm.public_id ?? null };
+    if (!tm.public_id)
+        throw new Error(`Site ${site.site_id} has no Tag Manager container configured (google.tag_manager.public_id).`);
+    const hit = (await gtm.listAllContainers()).find((c) => c.publicId === tm.public_id);
+    if (!hit)
+        throw new Error(`Container ${tm.public_id} is not visible to the operations account. Ask the client to grant access.`);
+    return { site, accountId: hit.accountId, containerId: hit.containerId, publicId: hit.publicId };
+}
+// ---------------------------------------------------------------- reads
+/** Every container the operations account can see. */
+export async function gtmContainers() {
+    return gtm.listAllContainers();
+}
+/** Version headers for a site's container: who published what, and when a new one appeared. */
+export async function gtmVersions(siteIdOrHost) {
+    const { accountId, containerId, publicId } = await gtmContainerFor(siteIdOrHost);
+    const headers = await gtm.listVersionHeaders(accountId, containerId);
+    return { publicId, versions: headers.filter((h) => !h.deleted).map((h) => ({ id: h.containerVersionId, name: h.name ?? null, tags: Number(h.numTags ?? 0), triggers: Number(h.numTriggers ?? 0), variables: Number(h.numVariables ?? 0) })) };
+}
+/** Snapshot the live container version, persist it, return the rendered summary. */
+export async function gtmSnapshot(siteIdOrHost) {
+    const { site, accountId, containerId, publicId } = await gtmContainerFor(siteIdOrHost);
+    const live = await gtm.getLiveVersion(accountId, containerId);
+    const snap = gtm.shapeSnapshot(live, { accountId, containerId, publicId });
+    const file = storage.saveNamed(site.site_id, 'gtm', snap);
+    storage.appendAudit({ siteId: site.site_id, operation: 'gtm.snapshot', status: 'observed', risk: 'auto',
+        summary: `GTM ${publicId ?? containerId} live version ${snap.versionId}: ${snap.counts.tags} tags, ${snap.counts.paused} paused`, data: snap.counts });
+    return { snapshot: snap, file, rendered: gtm.renderSnapshot(snap) };
+}
+/** Diff the two most recent GTM snapshots of a site. */
+export function gtmDiff(siteIdOrHost) {
+    const site = getSite(siteIdOrHost);
+    const names = storage.listNamed(site.site_id, 'gtm');
+    if (names.length < 2)
+        return { error: `Only ${names.length} GTM snapshot(s) for ${site.site_id}; two are needed.` };
+    const b = storage.loadNamed(site.site_id, 'gtm', names.at(-2));
+    const a = storage.loadNamed(site.site_id, 'gtm', names.at(-1));
+    if (!b || !a)
+        return { error: 'GTM snapshot file missing.' };
+    return { before: names.at(-2), after: names.at(-1), diff: gtm.diffSnapshots(b, a) };
+}
+/** Workspaces of a site's container with their pending change counts. Shows staged work and clutter. */
+export async function gtmWorkspaces(siteIdOrHost) {
+    const { accountId, containerId, publicId } = await gtmContainerFor(siteIdOrHost);
+    const out = [];
+    for (const w of await gtm.listWorkspaces(accountId, containerId)) {
+        const st = await gtm.workspaceStatus(accountId, containerId, w.workspaceId);
+        const changes = (st.workspaceChange ?? []).filter((c) => c.changeStatus !== 'none').length;
+        out.push({ id: w.workspaceId, name: w.name, description: w.description ?? null, changes, conflicts: st.mergeConflict?.length ?? 0, ours: w.name.startsWith(prefix()) });
+    }
+    return { publicId, workspaces: out };
+}
+// ---------------------------------------------------------------- staging
+function prefix() {
+    const rules = writeRules();
+    return rules.gtm?.workspace_name_prefix ?? 'gwo-';
+}
+function scopeHint(e, scope) {
+    const msg = e.message ?? String(e);
+    if (/403|PERMISSION_DENIED|insufficient/i.test(msg)) {
+        return new Error(`${msg}\nThe stored authorisation lacks the Tag Manager ${scope === 'gtm_edit' ? 'edit' : 'publish'} scope. Run: npm run cli -- auth login --scope ${scope}`);
+    }
+    return e;
+}
+/** Find our workspace to stage into: an existing <prefix>* workspace (empty ones first), else null. */
+async function findOurWorkspace(ids, workspaceId) {
+    const all = await gtm.listWorkspaces(ids.accountId, ids.containerId);
+    if (workspaceId) {
+        const w = all.find((x) => x.workspaceId === workspaceId);
+        if (!w)
+            throw new Error(`Workspace ${workspaceId} does not exist in container ${ids.publicId ?? ids.containerId}.`);
+        if (!w.name.startsWith(prefix()))
+            throw new Error(`Workspace "${w.name}" is not a ${prefix()} workspace. Policy: always_use_workspace with prefix ${prefix()}.`);
+        return w;
+    }
+    const ours = all.filter((w) => w.name.startsWith(prefix()));
+    if (!ours.length)
+        return null;
+    // Prefer a workspace that already holds staged changes so a multi-step
+    // change stays together; otherwise any of ours.
+    for (const w of ours) {
+        const st = await gtm.workspaceStatus(ids.accountId, ids.containerId, w.workspaceId);
+        if ((st.workspaceChange ?? []).some((c) => c.changeStatus !== 'none'))
+            return w;
+    }
+    return ours[0] ?? null;
+}
+const isNumeric = (s) => /^\d+$/.test(s);
+/** Tags may name their triggers; resolve names to ids against the workspace and the built-ins. */
+function resolveTriggerRefs(body, triggers) {
+    const byName = new Map(Object.entries(gtm.BUILT_IN_TRIGGERS));
+    for (const t of triggers)
+        if (t.triggerId)
+            byName.set(t.name, t.triggerId);
+    const out = { ...body };
+    for (const k of ['firingTriggerId', 'blockingTriggerId']) {
+        const refs = body[k];
+        if (!refs)
+            continue;
+        out[k] = refs.map((r) => {
+            if (isNumeric(r))
+                return r;
+            const id = byName.get(r);
+            if (!id)
+                throw new Error(`${k}: no trigger named "${r}" in the workspace. Stage the trigger first or use its id.`);
+            return id;
+        });
+    }
+    return out;
+}
+/**
+ * Stage entities into the site's gwo- workspace. Policy: gtm.stage (approval required).
+ * Each entity is its own write with its own audit record. Returns the workspace diff and review token.
+ */
+export async function gtmStage(siteIdOrHost, entities, opts = {}) {
+    const ids = await gtmContainerFor(siteIdOrHost);
+    const { site, accountId, containerId } = ids;
+    const approval = opts.approval ? { approval: opts.approval } : {};
+    for (const e of entities)
+        if (!e.body?.name)
+            throw new Error(`Every staged ${e.kind ?? 'entity'} needs a name.`);
+    const results = [];
+    // 1. Workspace. Creating one is the first mutation, so it is a write of its own.
+    let ws = await findOurWorkspace(ids, opts.workspaceId);
+    if (!ws) {
+        const name = `${prefix()}${new Date().toISOString().slice(0, 10)}`;
+        const w = await performWrite(site, {
+            action: 'gtm.stage', operation: 'gtm.workspace.create',
+            summary: `Created Tag Manager workspace "${name}" in ${ids.publicId ?? containerId}${opts.reason ? ` (${opts.reason})` : ''}`,
+            ...approval,
+            before: () => gtm.listWorkspaces(accountId, containerId),
+            async execute() { try {
+                await gtm.createWorkspace(accountId, containerId, name, `Google Web Operations staging. ${opts.reason ?? ''}`.trim());
+            }
+            catch (e) {
+                throw scopeHint(e, 'gtm_edit');
+            } },
+            after: () => gtm.listWorkspaces(accountId, containerId),
+            verify: (_b, after) => (after.some((x) => x.name === name) ? null : `workspace "${name}" not listed after create`),
+            summarise: (list) => list.map((x) => x.name),
+        });
+        if (w.status !== 'success') {
+            return { workspace: null, results: [{ kind: 'tag', name, op: 'none', status: w.status, verified: false, reason: w.reason }], diff: null, reviewToken: null,
+                rendered: `Workspace not created: ${w.reason ?? w.status}` };
+        }
+        ws = (w.after ?? []).find((x) => x.name === name) ?? null;
+        if (!ws)
+            throw new Error('workspace created but not found');
+    }
+    const wsId = ws.workspaceId;
+    // 2. Entities, one write each. Triggers before tags so tags can reference them by name.
+    const order = ['variable', 'trigger', 'tag'];
+    const sorted = [...entities].sort((a, b) => order.indexOf(a.kind) - order.indexOf(b.kind));
+    for (const { kind, body } of sorted) {
+        const list = () => gtm.listEntities(accountId, containerId, wsId, kind);
+        const existing = (await list()).find((x) => x.name === body.name) ?? null;
+        const idField = gtm.ID_FIELD[kind];
+        const op = existing ? 'update' : 'create';
+        let sent = body;
+        const r = await performWrite(site, {
+            action: 'gtm.stage', operation: `gtm.stage.${kind}`,
+            summary: `${op === 'create' ? 'Staged new' : 'Staged update to'} ${kind} "${body.name}" in workspace "${ws.name}"`,
+            ...approval,
+            before: async () => existing,
+            async execute(before) {
+                try {
+                    const triggers = kind === 'tag' ? await gtm.listEntities(accountId, containerId, wsId, 'trigger') : [];
+                    const resolved = kind === 'tag' ? resolveTriggerRefs(body, triggers) : body;
+                    if (before) {
+                        sent = gtm.mergeEntity(before, resolved);
+                        await gtm.updateEntity(accountId, containerId, wsId, kind, before[idField], sent, before.fingerprint);
+                    }
+                    else {
+                        sent = resolved;
+                        await gtm.createEntity(accountId, containerId, wsId, kind, sent);
+                    }
+                }
+                catch (e) {
+                    throw scopeHint(e, 'gtm_edit');
+                }
+            },
+            after: async () => (await list()).find((x) => x.name === body.name) ?? null,
+            verify: (_b, after) => gtm.entityMatches(sent, after),
+            summarise: (e) => (e ? { id: e[idField] ?? null, name: e.name, type: e.type ?? null, paused: e.paused ?? false, firingTriggerId: e.firingTriggerId ?? [], parameter: e.parameter ?? [] } : null),
+        });
+        results.push({ kind, name: body.name, op, status: r.status, verified: r.verified, reason: r.reason });
+        if (r.status === 'blocked')
+            break; // same token for every entity; no point continuing
+    }
+    // 3. Diff and review token, so the operator sees exactly what would publish.
+    const blocked = results.some((r) => r.status === 'blocked');
+    const diff = blocked ? null : await workspaceDiff(ids, wsId);
+    const token = diff ? gtm.reviewToken(diff) : null;
+    if (diff)
+        storage.saveNamed(site.site_id, 'gtm-stage', { workspace: { id: wsId, name: ws.name }, results, diff, reviewToken: token });
+    const rendered = [
+        ...results.map((r) => `- ${r.status.toUpperCase()} ${r.op} ${r.kind} "${r.name}"${r.verified ? ' (verified)' : ''}${r.reason ? `: ${r.reason}` : ''}`),
+        '',
+        diff ? gtm.renderWorkspaceDiff(diff, { workspaceId: wsId, name: ws.name }) : 'Blocked: nothing staged.',
+    ].join('\n');
+    return { workspace: { id: wsId, name: ws.name }, results, diff, reviewToken: token, rendered };
+}
+async function workspaceDiff(ids, workspaceId) {
+    const [status, live] = await Promise.all([
+        gtm.workspaceStatus(ids.accountId, ids.containerId, workspaceId),
+        gtm.getLiveVersion(ids.accountId, ids.containerId),
+    ]);
+    return gtm.shapeWorkspaceDiff(status, live);
+}
+/** Diff a workspace (ours by default) against the live version. Read-only; returns the review token for gtmPublish. */
+export async function gtmWorkspaceDiff(siteIdOrHost, workspaceId) {
+    const ids = await gtmContainerFor(siteIdOrHost);
+    const ws = await findOurWorkspace(ids, workspaceId);
+    if (!ws)
+        return { error: `No ${prefix()} workspace in container ${ids.publicId ?? ids.containerId}. Nothing is staged.` };
+    const diff = await workspaceDiff(ids, ws.workspaceId);
+    const token = gtm.reviewToken(diff);
+    storage.appendAudit({ siteId: ids.site.site_id, operation: 'gtm.workspace.diff', status: 'observed', risk: 'auto',
+        summary: `Reviewed workspace "${ws.name}": ${diff.counts.added} added, ${diff.counts.updated} updated, ${diff.counts.deleted} deleted; review ${token}`, data: diff.counts });
+    return { workspace: { id: ws.workspaceId, name: ws.name }, diff, reviewToken: token, rendered: gtm.renderWorkspaceDiff(diff, ws) };
+}
+/**
+ * Publish a reviewed workspace. Policy: gtm.publish (approval required) AND the review token
+ * from gtmWorkspaceDiff or gtmStage must match the workspace's current diff.
+ * Verified by reading the live version after and finding the new version id.
+ */
+export async function gtmPublish(siteIdOrHost, opts) {
+    const ids = await gtmContainerFor(siteIdOrHost);
+    const { site, accountId, containerId } = ids;
+    const ws = await findOurWorkspace(ids, opts.workspaceId);
+    if (!ws)
+        throw new Error(`No ${prefix()} workspace in container ${ids.publicId ?? containerId}. Stage changes first.`);
+    const versionName = opts.versionName ?? `${ws.name} ${new Date().toISOString().slice(0, 16).replace('T', ' ')}`;
+    let created = null;
+    const state = async () => {
+        const diff = await workspaceDiff(ids, ws.workspaceId);
+        return { liveVersionId: diff.liveVersionId, pending: diff.changes.length, reviewToken: gtm.reviewToken(diff) };
+    };
+    const r = await performWrite(site, {
+        action: 'gtm.publish', operation: 'gtm.publish',
+        summary: `Published workspace "${ws.name}" of ${ids.publicId ?? containerId} as version "${versionName}"`,
+        ...(opts.approval ? { approval: opts.approval } : {}),
+        before: state,
+        async execute(before) {
+            // Preconditions live inside execute so a refusal is recorded as a failed write with its reason.
+            if (before.pending === 0)
+                throw new Error('workspace has no changes; nothing to publish');
+            if (before.reviewToken !== opts.review) {
+                throw new Error(`review token ${opts.review} does not match the workspace's current changes (${before.reviewToken}). Run gtm_workspace_diff, review, and publish with the new token.`);
+            }
+            try {
+                const sync = await gtm.syncWorkspace(accountId, containerId, ws.workspaceId);
+                if (sync.syncStatus?.mergeConflict || sync.mergeConflict?.length)
+                    throw new Error('workspace has merge conflicts with the latest version; resolve them in the GTM UI, then diff and publish again');
+                if (sync.syncStatus?.syncError)
+                    throw new Error('workspace sync failed');
+                // The sync may have changed the diff (someone else published); the token must still hold.
+                const now = await state();
+                if (now.reviewToken !== opts.review)
+                    throw new Error(`live version moved to ${now.liveVersionId} during sync; the review token no longer matches. Diff and publish again.`);
+                const v = await gtm.createVersion(accountId, containerId, ws.workspaceId, { name: versionName, notes: opts.notes ?? 'Google Web Operations' });
+                const errs = Array.isArray(v.compilerError) ? v.compilerError : v.compilerError ? [{ message: 'compiler error' }] : [];
+                if (errs.length)
+                    throw new Error(`container did not compile: ${errs.map((e) => `${e.entityName ?? ''} ${e.message ?? ''}`.trim()).join('; ')}`);
+                if (!v.containerVersion)
+                    throw new Error('create_version returned no version');
+                created = v.containerVersion.containerVersionId;
+                const p = await gtm.publishVersion(accountId, containerId, created);
+                const perrs = Array.isArray(p.compilerError) ? p.compilerError : p.compilerError ? [{ message: 'compiler error' }] : [];
+                if (perrs.length)
+                    throw new Error(`version ${created} created but publish failed: ${perrs.map((e) => e.message ?? '').join('; ')}`);
+            }
+            catch (e) {
+                throw scopeHint(e, 'gtm_publish');
+            }
+        },
+        after: async () => ({ liveVersionId: (await gtm.getLiveVersion(accountId, containerId)).containerVersionId }),
+        verify: (_b, after) => (created && after.liveVersionId === created ? null : `live version is ${after.liveVersionId}, expected ${created ?? 'a new version'}`),
+    });
+    // A successful publish is also a new live version: snapshot it so the daily diff attributes it to us.
+    if (r.status === 'success')
+        await gtmSnapshot(siteIdOrHost);
+    return { status: r.status, verified: r.verified, reason: r.reason, version: created, audit: r.audit };
+}

package/packages/core/src/index.js

@@ -0,0 +1,13 @@
+/** Public surface of the core package. Apps import from here. */
+export { operations, scanSite, inspectUrl, inspectRendered, diffLatest, classifyAction, submitSitemap } from "./operations.js";
+export { performWrite } from "./writes.js";
+export { setMetaDescription, setTitle, setSchema, validateMetaDescription, validateTitle, validateJsonLd, canonicalJson, TITLE_BOUNDS } from "./content.js";
+export { setupStatus, installOauthClient, authLogin, discoverApply, addSite, updateSite, addSuppression, renderSiteFile, siteIdFor } from "./admin.js";
+export { renderClientReport, composeClientReport, collectMonthly, monthWindows, defaultMonth } from "./report/monthly.js";
+export { gtmStage, gtmWorkspaceDiff, gtmPublish, gtmWorkspaces, gtmContainerFor } from "./gtm-ops.js";
+export { createKeyEvent } from "./operations.js";
+export { adapterFor, NoAdapter } from "./adapters.js";
+export { listSites, getSite, publicView } from "./registry.js";
+export { renderScan } from "./scan/render.js";
+export { pageRules, siteRules, rank, summarise, SEVERITY_ORDER } from "./scan/rules.js";
+export * from "./paths.js";

package/packages/core/src/operations.js

@@ -0,0 +1,239 @@
+/**
+ * Operations engine: the one place hosts, the worker and the CLI call into.
+ *
+ * Every operation here follows the loop from docs/operations-model:
+ *   observe -> classify -> (authorise) -> execute -> verify -> record.
+ * Read operations record themselves as "observed". Write operations, when
+ * they arrive in phase 3, must call policy.enforce() first and record
+ * before/after/verified in the audit log.
+ */
+import * as crawler from "../../connectors/web-crawler/src/index.js";
+import { classify, approvalToken, limits } from "../../policy/src/index.js";
+import * as storage from "../../storage/src/index.js";
+import { getSite, listSites, publicView } from "./registry.js";
+import { pageRules, siteRules, rank, summarise } from "./scan/rules.js";
+import { renderScan } from "./scan/render.js";
+import { applySuppressions } from "./scan/suppress.js";
+import { performWrite } from "./writes.js";
+import { adapterFor } from "./adapters.js";
+import { setMetaDescription, setTitle, setSchema, validateMetaDescription, validateTitle, validateJsonLd } from "./content.js";
+import { renderClientReport } from "./report/monthly.js";
+import { gtmContainers, gtmVersions, gtmSnapshot, gtmDiff, gtmWorkspaces, gtmStage, gtmWorkspaceDiff, gtmPublish } from "./gtm-ops.js";
+import { ga4, gsc } from "../../connectors/google/src/index.js";
+function contextFor(site) {
+    return { canonicalHost: site.production_url, locales: site.locales, defaultLocale: site.default_locale };
+}
+/** Full site scan: robots, agent policy, llms.txt, host probe, sitemap, pages, rules. */
+export async function scanSite(siteIdOrHost, opts = {}) {
+    const site = getSite(siteIdOrHost);
+    const lim = limits().crawl ?? {};
+    const maxPages = Math.min(opts.maxPages ?? 50, lim.max_pages_per_scan ?? 200);
+    const origin = new URL(site.production_url).origin;
+    const ctx = contextFor(site);
+    const t0 = Date.now();
+    const robots = await crawler.robots(origin);
+    const robotsChecks = await crawler.checkAgents(robots);
+    const llms = await crawler.get(new URL('/llms.txt', origin).toString(), { timeout: 15_000 });
+    const hostProbe = await crawler.probeHosts(site);
+    const sitemapUrl = new URL(site.seo.sitemap, origin).toString();
+    const sitemapResult = await crawler.sitemap(robots.sitemaps[0] ?? sitemapUrl, { timeout: 30_000 });
+    let urls = opts.urls?.length ? [...opts.urls] : sitemapResult.urls.map((u) => u.loc);
+    if (!urls.includes(origin + '/'))
+        urls.unshift(origin + '/');
+    urls = [...new Set(urls)].slice(0, maxPages);
+    const pages = await crawler.fetchPages(urls, {
+        concurrency: lim.concurrency ?? 4,
+        delayMs: lim.politeness_delay_ms ?? 250,
+    });
+    const findings = [];
+    for (const p of pages)
+        findings.push(...pageRules(p, ctx));
+    findings.push(...siteRules({ origin, robots, robotsChecks, llmsTxt: { ok: llms.ok }, sitemap: sitemapResult, pages, hostProbe }));
+    // Site decisions first (findings the owner declared intentional), then rank what is left.
+    const sup = applySuppressions(findings, site.findings?.suppress);
+    const ranked = rank(sup.kept);
+    const scan = {
+        siteId: site.site_id, origin, at: new Date().toISOString(), durationMs: Date.now() - t0,
+        pagesCrawled: pages.length,
+        sitemap: { url: sitemapResult.url, ok: sitemapResult.ok, status: sitemapResult.status, count: sitemapResult.urls.length, urls: sitemapResult.urls },
+        robots: { ok: robots.ok, status: robots.status, sitemaps: robots.sitemaps, groups: robots.groups },
+        robotsChecks, llmsTxt: { ok: llms.ok, status: llms.status, bytes: llms.bytes }, hostProbe,
+        summary: summarise(ranked), findings: ranked, suppressed: { count: sup.suppressed.length, rules: sup.rules }, pages,
+    };
+    const { scanPath } = storage.saveScan(scan);
+    storage.appendAudit({
+        siteId: site.site_id, operation: 'web.scan', status: 'observed', risk: 'auto',
+        summary: `Scanned ${pages.length} pages: ${scan.summary.blocker} blocker, ${scan.summary.high} high, ${scan.summary.medium} medium${sup.suppressed.length ? `, ${sup.suppressed.length} suppressed by site decisions` : ''}`,
+        data: { pages: pages.length, summary: scan.summary, suppressed: scan.suppressed, durationMs: scan.durationMs },
+    });
+    return { scan, scanPath };
+}
+/** One page: fetch, parse, page-level rules. Used for spot checks and post-fix verification. */
+export async function inspectUrl(url, siteIdOrHost) {
+    const site = siteIdOrHost ? getSite(siteIdOrHost) : null;
+    const ctx = site ? contextFor(site) : { canonicalHost: new URL(url).origin, locales: [], defaultLocale: 'he' };
+    const page = await crawler.fetchPage(url);
+    return { page, findings: pageRules(page, ctx) };
+}
+/** Static HTML versus the DOM a browser renders. Needs Playwright; the error says how to install it. */
+export async function inspectRendered(url, siteIdOrHost) {
+    const browser = await import("../../connectors/browser/src/index.js");
+    const site = siteIdOrHost ? getSite(siteIdOrHost) : null;
+    const r = await crawler.get(url, { timeout: 30_000 });
+    const c = await browser.inspectRendered(url, r.body ?? '');
+    if (site)
+        storage.appendAudit({ siteId: site.site_id, operation: 'web.inspect_rendered', status: 'observed', risk: 'auto', summary: `${url}: ${c.verdict} (${c.delta.words.static}/${c.delta.words.rendered} words)`, data: c.delta });
+    return { comparison: c, rendered: browser.renderComparison(c) };
+}
+/** Diff the two most recent snapshots of a site. */
+export function diffLatest(siteIdOrHost) {
+    const site = getSite(siteIdOrHost);
+    const snaps = storage.listSnapshots(site.site_id);
+    if (snaps.length < 2)
+        return { error: `Only ${snaps.length} snapshot(s) for ${site.site_id}; two are needed.` };
+    const before = snaps.at(-2), after = snaps.at(-1);
+    const b = storage.loadSnapshot(site.site_id, before), a = storage.loadSnapshot(site.site_id, after);
+    if (!b || !a)
+        return { error: 'Snapshot file missing.' };
+    return { before, after, diff: storage.diffSnapshots(b, a) };
+}
+/** Policy answer for a proposed action, with the token the operator would need. */
+export function classifyAction(action, siteIdOrHost) {
+    const site = siteIdOrHost ? getSite(siteIdOrHost) : undefined;
+    const d = classify(action, site);
+    return { ...d, approvalTokenIfNeeded: d.risk === 'approval_required' && site ? approvalToken(site.site_id, action) : null };
+}
+// ---------------------------------------------------------------- site adapters (read)
+/** Connectivity check for a site's write adapter. */
+export async function adapterPing(siteIdOrHost) {
+    const site = getSite(siteIdOrHost);
+    const a = await adapterFor(site);
+    const r = await a.ping();
+    return { kind: a.kind, target: a.describe(), ...r };
+}
+/** Pages the adapter can address. */
+export async function adapterPages(siteIdOrHost) {
+    const site = getSite(siteIdOrHost);
+    const a = await adapterFor(site);
+    return { kind: a.kind, target: a.describe(), pages: await a.listPages() };
+}
+/** SEO fields of one page as the site stores them, plus what the live page shows, for comparison. */
+export async function adapterPageSeo(siteIdOrHost, pagePath) {
+    const site = getSite(siteIdOrHost);
+    const a = await adapterFor(site);
+    const stored = await a.readPageSeo(pagePath);
+    const live = await crawler.fetchPage(new URL(pagePath, site.production_url).toString());
+    return {
+        kind: a.kind, path: pagePath, stored,
+        live: live.signals ? { status: live.status, title: live.signals.title, description: live.signals.description, canonical: live.signals.canonicalAbs } : { status: live.status },
+    };
+}
+/** Managed JSON-LD blocks of one page as the site stores them, next to every JSON-LD type the live page emits. */
+export async function adapterPageSchema(siteIdOrHost, pagePath) {
+    const site = getSite(siteIdOrHost);
+    const a = await adapterFor(site);
+    const stored = await a.readPageSchema(pagePath);
+    const live = await crawler.fetchPage(new URL(pagePath, site.production_url).toString());
+    return {
+        kind: a.kind, path: pagePath,
+        stored: stored === null ? null : stored.map((b) => ({ type: b['@type'] ?? null, block: b })),
+        live: { status: live.status, jsonldTypes: live.signals?.jsonldTypes ?? [], blocks: live.signals?.jsonld ?? [] },
+    };
+}
+/**
+ * Mark a GA4 event as a key event. Policy: ga4.key_event.create (approval required).
+ * Verified by listing key events after and finding the name.
+ */
+export async function createKeyEvent(siteIdOrHost, eventName, { approval } = {}) {
+    const site = getSite(siteIdOrHost);
+    const pid = site.google.ga4?.property_id;
+    if (!pid)
+        throw new Error(`Site ${site.site_id} has no google.ga4.property_id configured.`);
+    const read = async () => (await ga4.listKeyEvents(pid)).keyEvents ?? [];
+    return performWrite(site, {
+        action: 'ga4.key_event.create',
+        operation: 'ga4.create_key_event',
+        summary: `Marked "${eventName}" as a key event on GA4 property ${pid}`,
+        ...(approval ? { approval } : {}),
+        before: read,
+        async execute(before) {
+            if ((before ?? []).some((k) => k.eventName === eventName))
+                return; // idempotent
+            try {
+                await ga4.createKeyEvent(pid, eventName);
+            }
+            catch (e) {
+                const msg = e.message;
+                if (/403|PERMISSION_DENIED|insufficient/i.test(msg))
+                    throw new Error(`${msg}\nThe stored authorisation lacks analytics.edit. Run: npm run cli -- auth login --scope ga4_write`);
+                throw e;
+            }
+        },
+        after: read,
+        verify: (_b, after) => ((after ?? []).some((k) => k.eventName === eventName) ? null : `"${eventName}" not present after create`),
+        summarise: (list) => (list ?? []).map((k) => k.eventName),
+    });
+}
+/**
+ * Submit the site's declared sitemap to Search Console. Policy: gsc.sitemap.submit (auto).
+ * Verified by reading the sitemap list back and finding the entry with a fresh lastSubmitted.
+ */
+export async function submitSitemap(siteIdOrHost, { approval } = {}) {
+    const site = getSite(siteIdOrHost);
+    const property = site.google.search_console?.property;
+    if (!property)
+        throw new Error(`Site ${site.site_id} has no google.search_console.property configured.`);
+    const feedpath = new URL(site.seo.sitemap, site.production_url).toString();
+    const startedAt = Date.now();
+    const read = async () => (await gsc.listSitemaps(property)).sitemap ?? [];
+    const find = (list) => list.find((s) => s.path === feedpath) ?? null;
+    return performWrite(site, {
+        action: 'gsc.sitemap.submit',
+        operation: 'gsc.submit_sitemap',
+        summary: `Submitted sitemap ${feedpath} to ${property}`,
+        approval,
+        before: read,
+        execute: () => gsc.submitSitemap(property, feedpath),
+        after: read,
+        // Verify the intended end state: the sitemap is listed and was submitted
+        // within the last few minutes. A strict "timestamp advanced" check would
+        // fail a legitimate resubmit that Google coalesces into the same second.
+        verify(_before, after) {
+            const entry = find(after);
+            if (!entry)
+                return 'sitemap not present in Search Console after submit';
+            const submitted = entry.lastSubmitted ? Date.parse(entry.lastSubmitted) : 0;
+            if (!submitted)
+                return 'Search Console reports no lastSubmitted for the sitemap';
+            if (submitted < startedAt - 5 * 60_000)
+                return `lastSubmitted ${entry.lastSubmitted} predates this run`;
+            return null;
+        },
+        summarise: (list) => list.map((s) => ({ path: s.path, lastSubmitted: s.lastSubmitted, errors: s.errors, warnings: s.warnings })),
+    });
+}
+export const operations = {
+    submitSitemap, createKeyEvent,
+    setMetaDescription, setTitle, setSchema, validateMetaDescription, validateTitle, validateJsonLd,
+    gtmContainers, gtmVersions, gtmSnapshot, gtmDiff, gtmWorkspaces, gtmStage, gtmWorkspaceDiff, gtmPublish,
+    adapterPing, adapterPages, adapterPageSeo, adapterPageSchema,
+    renderClientReport,
+    listSites: (opts) => listSites(opts).map(publicView),
+    getSite: (id) => publicView(getSite(id)),
+    siteState: (id) => {
+        const site = getSite(id);
+        const scan = storage.loadScan(site.site_id);
+        return {
+            site: publicView(site),
+            lastScan: scan ? { at: scan.at, pages: scan.pagesCrawled, summary: scan.summary } : null,
+            snapshots: storage.listSnapshots(site.site_id).length,
+        };
+    },
+    scanSite,
+    inspectUrl,
+    inspectRendered,
+    diffLatest,
+    classifyAction,
+    auditLog: (id, limit = 50) => storage.readAudit(getSite(id).site_id, { limit }),
+    renderScan,
+};