@aiguru/google-web-operations 0.6.4

package/packages/connectors/docx/src/index.js

@@ -0,0 +1,122 @@
+/**
+ * Word document writer.
+ *
+ * Builds a .docx from a small block model (headings, paragraphs, bullets,
+ * tables), either inside a company .dotx template so the result carries the
+ * template's header, footer, fonts and styles, or as a minimal standalone
+ * package when no template is configured. Only the document body is
+ * generated; everything else in a template is kept byte for byte.
+ *
+ * Right-to-left documents set <w:bidi/> on every paragraph, <w:rtl/> on
+ * every run and <w:bidiVisual/> on tables, which is what Word itself writes
+ * for Hebrew text.
+ */
+import { readFileSync } from 'node:fs';
+import JSZip from 'jszip';
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+function run(text, rtl, bold = false) {
+    const props = [bold ? '<w:b/><w:bCs/>' : '', rtl ? '<w:rtl/>' : ''].join('');
+    return `<w:r>${props ? `<w:rPr>${props}</w:rPr>` : ''}<w:t xml:space="preserve">${esc(text)}</w:t></w:r>`;
+}
+function para(text, rtl, opts = {}) {
+    const pPr = [
+        opts.style ? `<w:pStyle w:val="${opts.style}"/>` : '',
+        opts.indent ? '<w:ind w:left="360" w:hanging="360"/>' : '',
+        rtl ? '<w:bidi/>' : '',
+    ].join('');
+    return `<w:p>${pPr ? `<w:pPr>${pPr}</w:pPr>` : ''}${run(text, rtl, opts.bold)}</w:p>`;
+}
+function table(header, rows, rtl) {
+    const cols = Math.max(header.length, ...rows.map((r) => r.length));
+    const width = Math.floor(9026 / Math.max(cols, 1));
+    const cell = (text, bold) => `<w:tc><w:tcPr><w:tcW w:w="${width}" w:type="dxa"/></w:tcPr>${para(text, rtl, { bold })}</w:tc>`;
+    const row = (cells, bold) => `<w:tr>${Array.from({ length: cols }, (_, i) => cell(cells[i] ?? '', bold)).join('')}</w:tr>`;
+    return `<w:tbl><w:tblPr><w:tblStyle w:val="TableGrid"/><w:tblW w:w="0" w:type="auto"/>${rtl ? '<w:bidiVisual/>' : ''}` +
+        `<w:tblLook w:val="04A0" w:firstRow="1" w:lastRow="0" w:firstColumn="1" w:lastColumn="0" w:noHBand="0" w:noVBand="1"/></w:tblPr>` +
+        `<w:tblGrid>${Array.from({ length: cols }, () => `<w:gridCol w:w="${width}"/>`).join('')}</w:tblGrid>` +
+        row(header, true) + rows.map((r) => row(r, false)).join('') + `</w:tbl>${para('', rtl)}`;
+}
+/** The body content (without <w:body> and without sectPr). Pure. */
+export function bodyXml(model) {
+    const { rtl } = model;
+    const out = [];
+    for (const b of model.blocks) {
+        switch (b.kind) {
+            case 'title':
+                out.push(para(b.text, rtl, { style: 'Title' }));
+                break;
+            case 'subtitle':
+                out.push(para(b.text, rtl, { style: 'Subtitle' }));
+                break;
+            case 'heading':
+                out.push(para(b.text, rtl, { style: `Heading${b.level}` }));
+                break;
+            case 'paragraph':
+                out.push(para(b.text, rtl, { bold: b.bold }));
+                break;
+            case 'bullets':
+                for (const item of b.items)
+                    out.push(para(`• ${item}`, rtl, { style: 'ListParagraph', indent: true }));
+                break;
+            case 'table':
+                out.push(table(b.header, b.rows, rtl));
+                break;
+        }
+    }
+    return out.join('');
+}
+const W_NS = 'xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"';
+/** Minimal styles for the standalone package: the same style ids the template uses. */
+function standaloneStyles(rtl) {
+    const font = rtl ? 'Arial' : 'Calibri';
+    const h = (id, name, size, color) => `<w:style w:type="paragraph" w:styleId="${id}"><w:name w:val="${name}"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:pPr><w:keepNext/><w:spacing w:before="240" w:after="80"/></w:pPr><w:rPr><w:b/><w:bCs/><w:color w:val="${color}"/><w:sz w:val="${size}"/><w:szCs w:val="${size}"/></w:rPr></w:style>`;
+    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:styles ${W_NS}>` +
+        `<w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:ascii="${font}" w:hAnsi="${font}" w:cs="${font}"/><w:sz w:val="22"/><w:szCs w:val="22"/><w:lang w:val="en-IL" w:bidi="he-IL"/></w:rPr></w:rPrDefault><w:pPrDefault><w:pPr><w:spacing w:after="120" w:line="276" w:lineRule="auto"/></w:pPr></w:pPrDefault></w:docDefaults>` +
+        `<w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style>` +
+        h('Title', 'Title', 44, '1F3864') + h('Subtitle', 'Subtitle', 26, '595959') + h('Heading1', 'heading 1', 32, '1F3864') + h('Heading2', 'heading 2', 26, '2F5496') + h('Heading3', 'heading 3', 24, '2F5496') +
+        `<w:style w:type="paragraph" w:styleId="ListParagraph"><w:name w:val="List Paragraph"/><w:basedOn w:val="Normal"/><w:pPr><w:spacing w:after="60"/></w:pPr></w:style>` +
+        `<w:style w:type="table" w:default="1" w:styleId="TableNormal"><w:name w:val="Normal Table"/><w:tblPr><w:tblCellMar><w:top w:w="0" w:type="dxa"/><w:left w:w="108" w:type="dxa"/><w:bottom w:w="0" w:type="dxa"/><w:right w:w="108" w:type="dxa"/></w:tblCellMar></w:tblPr></w:style>` +
+        `<w:style w:type="table" w:styleId="TableGrid"><w:name w:val="Table Grid"/><w:basedOn w:val="TableNormal"/><w:tblPr><w:tblBorders><w:top w:val="single" w:sz="4" w:color="BFBFBF"/><w:left w:val="single" w:sz="4" w:color="BFBFBF"/><w:bottom w:val="single" w:sz="4" w:color="BFBFBF"/><w:right w:val="single" w:sz="4" w:color="BFBFBF"/><w:insideH w:val="single" w:sz="4" w:color="BFBFBF"/><w:insideV w:val="single" w:sz="4" w:color="BFBFBF"/></w:tblBorders></w:tblPr></w:style>` +
+        `</w:styles>`;
+}
+const DOC_CT = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml';
+/** Build the .docx package. Returns the file bytes. */
+export async function buildDocx(model, opts = {}) {
+    const body = bodyXml(model);
+    if (opts.templatePath) {
+        const zip = await JSZip.loadAsync(readFileSync(opts.templatePath));
+        const docFile = zip.file('word/document.xml');
+        if (!docFile)
+            throw new Error(`${opts.templatePath}: no word/document.xml; not a Word template`);
+        const doc = await docFile.async('string');
+        const open = doc.indexOf('<w:body>'), sect = doc.lastIndexOf('<w:sectPr');
+        if (open < 0 || sect < 0)
+            throw new Error(`${opts.templatePath}: body or section properties not found`);
+        // Keep the template's section (page size, margins, header and footer references); replace its sample content.
+        zip.file('word/document.xml', doc.slice(0, open + '<w:body>'.length) + body + doc.slice(sect));
+        // A template part becomes a document part.
+        const ct = await zip.file('[Content_Types].xml').async('string');
+        zip.file('[Content_Types].xml', ct.replace(/wordprocessingml\.template\.main\+xml/, 'wordprocessingml.document.main+xml'));
+        const core = zip.file('docProps/core.xml');
+        if (core && model.title) {
+            const c = await core.async('string');
+            const titleXml = `<dc:title>${esc(model.title)}</dc:title>`;
+            zip.file('docProps/core.xml', /<dc:title>.*?<\/dc:title>/s.test(c) ? c.replace(/<dc:title>.*?<\/dc:title>/s, titleXml) : c.replace('</cp:coreProperties>', `${titleXml}</cp:coreProperties>`));
+        }
+        return zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+    }
+    const zip = new JSZip();
+    zip.file('[Content_Types].xml', `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="${DOC_CT}"/><Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/><Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/></Types>`);
+    zip.file('_rels/.rels', `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/><Relationship Id="rId2" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" Target="docProps/core.xml"/></Relationships>`);
+    zip.file('word/_rels/document.xml.rels', `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/></Relationships>`);
+    zip.file('word/styles.xml', standaloneStyles(model.rtl));
+    zip.file('docProps/core.xml', `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><dc:title>${esc(model.title ?? '')}</dc:title><dc:creator>Google Web Operations</dc:creator><dcterms:created xsi:type="dcterms:W3CDTF">${new Date().toISOString()}</dcterms:created></cp:coreProperties>`);
+    zip.file('word/document.xml', `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document ${W_NS}><w:body>${body}<w:sectPr>${model.rtl ? '<w:bidi/>' : ''}<w:pgSz w:w="11906" w:h="16838"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="708" w:footer="708" w:gutter="0"/></w:sectPr></w:body></w:document>`);
+    return zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+}
+/** Read the visible text of a .docx (for verification and tests). */
+export async function docxText(bytes) {
+    const zip = await JSZip.loadAsync(bytes);
+    const doc = await zip.file('word/document.xml').async('string');
+    return doc.replace(/<\/w:p>/g, '\n').replace(/<[^>]+>/g, '').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&amp;/g, '&');
+}

package/packages/connectors/github/src/index.js

@@ -0,0 +1,102 @@
+/**
+ * GitHub: turn manifest changes in a site's local checkout into a pull request.
+ *
+ * Branch, commit and push use the git CLI in the checkout. The pull request
+ * is opened through the REST API with GITHUB_TOKEN (a fine-grained token with
+ * "Pull requests: write" and "Contents: write" on the site repositories).
+ * Policy: github.pr.create (approval required). Runs inside performWrite:
+ * before = clean/dirty state, after = the PR read back from the API.
+ */
+import { execFileSync } from 'node:child_process';
+import { performWrite } from "../../../core/src/writes.js";
+import { getSite } from "../../../core/src/registry.js";
+function git(cwd, ...args) {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+/** owner/repo from a GitHub URL. Pure. */
+export function parseRepo(url) {
+    const m = url.replace(/\.git$/, '').match(/github\.com[/:]([^/]+)\/([^/]+)$/);
+    if (!m)
+        throw new Error(`Not a GitHub repository URL: ${url}`);
+    return { owner: m[1], repo: m[2] };
+}
+/** Deterministic branch name for a site and day. Pure. */
+export function branchName(siteId, date = new Date()) {
+    return `gwo/${siteId}/${date.toISOString().slice(0, 10)}`;
+}
+/** PR body from the site's recent audit entries. Pure. */
+export function prBody(siteId, changes) {
+    return [
+        `Automated SEO metadata changes for **${siteId}** proposed by Google Web Operations.`,
+        '', 'Changes:', ...changes.map((c) => `- ${c}`), '',
+        'Every change was validated, applied through the site adapter and verified by reading the stored value back. See the audit log for before/after values.',
+        '', '🤖 Generated with [Claude Code](https://claude.com/claude-code)',
+    ].join('\n');
+}
+async function ghJson(path, init = {}) {
+    const token = process.env['GITHUB_TOKEN']?.trim();
+    if (!token)
+        throw new Error('GITHUB_TOKEN is not set. Create a fine-grained token with Contents and Pull requests write access on the site repositories.');
+    const res = await fetch(`https://api.github.com${path}`, {
+        ...init,
+        headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json', 'content-type': 'application/json', 'x-github-api-version': '2022-11-28', ...(init.headers ?? {}) },
+    });
+    const body = await res.text();
+    if (!res.ok)
+        throw new Error(`GitHub ${res.status} ${path}: ${body.slice(0, 400)}`);
+    return JSON.parse(body);
+}
+/**
+ * Commit whatever changed in the checkout (normally gwo.seo.json), push a
+ * branch and open a pull request. Idempotent per day: reuses an open PR for
+ * the same branch.
+ */
+export async function openPullRequest(siteIdOrHost, { approval, changes = [] } = {}) {
+    const site = getSite(siteIdOrHost);
+    const repo = site.write?.repo;
+    if (!repo?.local_path || !repo.url)
+        throw new Error(`Site ${site.site_id}: github needs write.repo.local_path and write.repo.url.`);
+    const cwd = repo.local_path, base = repo.branch ?? 'main';
+    const { owner, repo: name } = parseRepo(repo.url);
+    const branch = branchName(site.site_id);
+    const findOpenPr = async () => {
+        const prs = await ghJson(`/repos/${owner}/${name}/pulls?state=open&head=${owner}:${branch}`);
+        const p = prs[0];
+        return p ? { number: p.number, url: p.html_url, branch } : null;
+    };
+    return performWrite(site, {
+        action: 'github.pr.create',
+        operation: 'github.open_pull_request',
+        summary: `Opened pull request for ${site.site_id} from ${branch}`,
+        ...(approval ? { approval } : {}),
+        async before() {
+            const dirty = git(cwd, 'status', '--porcelain').split('\n').filter(Boolean);
+            return { dirty, branch, openPr: await findOpenPr() };
+        },
+        async execute(before) {
+            if (!before.dirty.length && before.openPr)
+                return; // nothing new, PR exists
+            if (!before.dirty.length)
+                throw new Error('Nothing to propose: the checkout has no changes.');
+            const current = git(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');
+            if (current !== branch) {
+                try {
+                    git(cwd, 'checkout', '-b', branch);
+                }
+                catch {
+                    git(cwd, 'checkout', branch);
+                }
+            }
+            git(cwd, 'add', '-A');
+            git(cwd, 'commit', '-m', `SEO metadata updates for ${site.site_id}\n\nProposed by Google Web Operations.\n\nCo-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>`);
+            git(cwd, 'push', '-u', 'origin', branch);
+            if (!before.openPr) {
+                await ghJson(`/repos/${owner}/${name}/pulls`, { method: 'POST', body: JSON.stringify({
+                        title: `SEO metadata updates (${new Date().toISOString().slice(0, 10)})`, head: branch, base, body: prBody(site.site_id, changes),
+                    }) });
+            }
+        },
+        after: findOpenPr,
+        verify: (_b, after) => (after ? null : 'no open pull request found for the branch after push'),
+    });
+}

package/packages/connectors/google/src/auth.js

@@ -0,0 +1,73 @@
+/**
+ * Google API authentication.
+ *
+ * Connector code only ever asks the active TokenProvider for a bearer token.
+ * Provider resolution order, decided once per process:
+ *   1. GWO_GOOGLE_AUTH=env      force the development bridge
+ *   2. a stored OAuth authorisation (secrets/, see oauth.ts)
+ *   3. GOOGLE_ACCESS_TOKEN       development bridge, expires hourly
+ *   4. none                      clear error naming the fix
+ */
+/** Development bridge: GOOGLE_ACCESS_TOKEN from the environment. */
+export const envTokenProvider = {
+    async accessToken() {
+        const token = process.env['GOOGLE_ACCESS_TOKEN']?.trim();
+        if (!token) {
+            throw new Error('Google access is not configured. Run "npm run cli -- auth login" once for the operations account, ' +
+                'or set GOOGLE_ACCESS_TOKEN for a short development session.');
+        }
+        return token;
+    },
+    describe() { return process.env['GOOGLE_ACCESS_TOKEN'] ? 'env bearer token (development bridge)' : 'not configured'; },
+};
+let provider = null;
+/** Replace the active provider (tests, or a future keychain-backed store). */
+export function setTokenProvider(p) { provider = p; }
+/** The active provider, resolving lazily so importing this module has no side effects. */
+export function tokenProvider() {
+    if (provider)
+        return provider;
+    if (process.env['GWO_GOOGLE_AUTH'] !== 'env') {
+        try {
+            // Lazy import keeps the crawler-only paths free of any OAuth code.
+            const { makeOauthProvider } = require_oauth();
+            const oauth = makeOauthProvider();
+            if (oauth.status().authorised)
+                return (provider = oauth);
+        }
+        catch { /* fall through to env */ }
+    }
+    return (provider = envTokenProvider);
+}
+// Synchronous require shim for the lazy import above (ESM has no sync import;
+// the module is small and already loaded by the time any Google tool runs).
+import * as oauthModule from "./oauth.js";
+function require_oauth() { return oauthModule; }
+export class GoogleApiError extends Error {
+    status;
+    endpoint;
+    constructor(status, endpoint, body) {
+        super(`Google API ${status} at ${endpoint}: ${body.slice(0, 600)}`);
+        this.name = 'GoogleApiError';
+        this.status = status;
+        this.endpoint = endpoint;
+    }
+}
+/**
+ * Authenticated JSON request. Throws GoogleApiError on non-2xx.
+ * Some Google endpoints answer 204 with no body (sitemap submit, deletes);
+ * those resolve to null rather than failing on an empty parse.
+ */
+export async function googleJson(url, init = {}) {
+    const token = await tokenProvider().accessToken();
+    const res = await fetch(url, {
+        ...init,
+        headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', ...(init.headers ?? {}) },
+    });
+    const body = await res.text();
+    if (!res.ok)
+        throw new GoogleApiError(res.status, new URL(url).pathname, body);
+    if (res.status === 204 || body.trim() === '')
+        return null;
+    return JSON.parse(body);
+}

package/packages/connectors/google/src/discover.js

@@ -0,0 +1,135 @@
+/**
+ * Property discovery: after consent, find which Search Console properties,
+ * GA4 properties and Tag Manager containers the operations account can see,
+ * and match them to registered sites by host.
+ *
+ * The matching is a pure function so it can be tested without Google.
+ * Applying the result to site YAML files preserves comments and layout.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseDocument } from 'yaml';
+import { googleJson } from "./auth.js";
+import { SITES_DIR } from "../../../core/src/paths.js";
+import { listSites } from "../../../core/src/registry.js";
+// ---------------------------------------------------------------- fetch inventory
+export async function fetchInventory() {
+    const gsc = ((await googleJson('https://www.googleapis.com/webmasters/v3/sites')).siteEntry ?? []);
+    const summaries = await googleJson('https://analyticsadmin.googleapis.com/v1beta/accountSummaries?pageSize=200');
+    const ga4 = [];
+    for (const acc of summaries.accountSummaries ?? []) {
+        for (const p of acc.propertySummaries ?? []) {
+            let hosts = [];
+            try {
+                const streams = await googleJson(`https://analyticsadmin.googleapis.com/v1beta/${p.property}/dataStreams`);
+                hosts = (streams.dataStreams ?? []).map((s) => hostOf(s.webStreamData?.defaultUri)).filter((h) => !!h);
+            }
+            catch { /* no permission on streams; match by name later */ }
+            ga4.push({ property: p.property, displayName: p.displayName, account: acc.account, hosts });
+        }
+    }
+    const gtm = [];
+    try {
+        const accounts = await googleJson('https://tagmanager.googleapis.com/tagmanager/v2/accounts');
+        for (const a of accounts.account ?? []) {
+            const cs = await googleJson(`https://tagmanager.googleapis.com/tagmanager/v2/accounts/${a.accountId}/containers`);
+            for (const c of cs.container ?? [])
+                gtm.push({ accountId: a.accountId, containerId: c.containerId, publicId: c.publicId, name: c.name, domains: c.domainName ?? [] });
+        }
+    }
+    catch { /* GTM scope may not be granted yet */ }
+    return { gsc, ga4, gtm };
+}
+/** Fuzzy name match: a token of 4+ letters shared between the property name and the host label. */
+export function nameMatchesHost(displayName, host) {
+    const label = (host.split('.')[0] ?? '').toLowerCase();
+    if (label.length < 4)
+        return false;
+    const tokens = displayName.toLowerCase().split(/[^a-z0-9֐-׿]+/).filter((t) => t.length >= 4);
+    return tokens.some((t) => label.includes(t) || t.includes(label));
+}
+export function hostOf(u) {
+    if (!u)
+        return null;
+    try {
+        return new URL(u.includes('://') ? u : `https://${u}`).host.toLowerCase().replace(/^www\./, '');
+    }
+    catch {
+        return null;
+    }
+}
+/** Match inventory to sites by bare host (www stripped). Pure, testable. */
+export function matchInventory(sites, inv) {
+    return sites.map((site) => {
+        const host = hostOf(site.production_url) ?? '';
+        const unmatched = [];
+        // Search Console: the domain property, else a URL-prefix property on the same host. Both exact.
+        const gscHit = inv.gsc.find((s) => s.siteUrl === `sc-domain:${host}`)
+            ?? inv.gsc.find((s) => !s.siteUrl.startsWith('sc-domain:') && hostOf(s.siteUrl) === host) ?? null;
+        if (!gscHit)
+            unmatched.push('search_console');
+        // GA4: exact by data-stream host; otherwise a name guess the operator must confirm.
+        const ga4ByHost = inv.ga4.find((p) => p.hosts.includes(host));
+        const ga4ByName = ga4ByHost ? undefined : inv.ga4.find((p) => nameMatchesHost(p.displayName, host));
+        const ga4Hit = ga4ByHost ?? ga4ByName ?? null;
+        if (!ga4Hit)
+            unmatched.push('ga4');
+        // GTM: exact by declared domain, exact by a public id the site file already knows.
+        const knownPublic = site.google.tag_manager?.public_id ?? null;
+        const gtmByDomain = inv.gtm.find((c) => c.domains.some((d) => hostOf(d) === host));
+        const gtmById = gtmByDomain ? undefined : (knownPublic ? inv.gtm.find((c) => c.publicId === knownPublic) : undefined);
+        const gtmHit = gtmByDomain ?? gtmById ?? null;
+        if (!gtmHit)
+            unmatched.push('tag_manager');
+        return {
+            site_id: site.site_id,
+            gsc: gscHit ? { property: gscHit.siteUrl, via: 'host', current: site.google.search_console?.property ?? null } : null,
+            ga4: ga4Hit ? { property_id: ga4Hit.property.replace(/^properties\//, ''), displayName: ga4Hit.displayName, via: ga4ByHost ? 'host' : 'name', current: site.google.ga4?.property_id ?? null } : null,
+            gtm: gtmHit ? { public_id: gtmHit.publicId, account_id: gtmHit.accountId, container_id: gtmHit.containerId, via: gtmByDomain ? 'host' : 'id', current: knownPublic } : null,
+            unmatched,
+        };
+    });
+}
+// ---------------------------------------------------------------- apply to YAML
+/**
+ * Write matched ids into sites/<file>.yaml, keeping comments and order.
+ * Name-based guesses are never applied automatically; the operator sets them by hand
+ * after checking. Returns the files changed.
+ */
+export function applyMatches(matches) {
+    const changed = [];
+    const byId = new Map(listSites({ includeDisabled: true }).map((s) => [s.site_id, s]));
+    for (const m of matches) {
+        const site = byId.get(m.site_id);
+        if (!site)
+            continue;
+        const file = path.join(SITES_DIR, site._file);
+        const doc = parseDocument(readFileSync(file, 'utf8'));
+        let touched = false;
+        const set = (p, v) => { if (doc.getIn(p) !== v) {
+            doc.setIn(p, v);
+            touched = true;
+        } };
+        if (m.gsc && m.gsc.via !== 'name')
+            set(['google', 'search_console', 'property'], m.gsc.property);
+        if (m.ga4 && m.ga4.via !== 'name')
+            set(['google', 'ga4', 'property_id'], m.ga4.property_id);
+        if (m.gtm && m.gtm.via !== 'name') {
+            set(['google', 'tag_manager', 'public_id'], m.gtm.public_id);
+            set(['google', 'tag_manager', 'account_id'], m.gtm.account_id);
+            set(['google', 'tag_manager', 'container_id'], m.gtm.container_id);
+        }
+        if (touched) {
+            writeFileSync(file, doc.toString());
+            changed.push(site._file);
+        }
+    }
+    return changed;
+}
+/** Fetch, match, and optionally apply. */
+export async function discover({ apply = false } = {}) {
+    const inventory = await fetchInventory();
+    const matches = matchInventory(listSites({ includeDisabled: true }), inventory);
+    const applied = apply ? applyMatches(matches) : [];
+    return { inventory, matches, applied };
+}

package/packages/connectors/google/src/ga4.js

@@ -0,0 +1,42 @@
+/**
+ * Google Analytics 4. Data API for reports, Admin API for configuration.
+ * Read-only in v0.2; ga4.key_event.create is the planned first write.
+ */
+import { googleJson } from "./auth.js";
+const DATA = 'https://analyticsdata.googleapis.com/v1beta';
+const ADMIN = 'https://analyticsadmin.googleapis.com/v1beta';
+export function runReport(propertyId, body) {
+    return googleJson(`${DATA}/properties/${encodeURIComponent(propertyId)}:runReport`, {
+        method: 'POST', body: JSON.stringify({ limit: 100, ...body }),
+    });
+}
+export function runRealtime(propertyId, body) {
+    return googleJson(`${DATA}/properties/${encodeURIComponent(propertyId)}:runRealtimeReport`, {
+        method: 'POST', body: JSON.stringify({ limit: 50, ...body }),
+    });
+}
+export function listKeyEvents(propertyId) {
+    return googleJson(`${ADMIN}/properties/${encodeURIComponent(propertyId)}/keyEvents`);
+}
+export function listDataStreams(propertyId) {
+    return googleJson(`${ADMIN}/properties/${encodeURIComponent(propertyId)}/dataStreams`);
+}
+/**
+ * Mark an event as a key event (conversion). Policy: ga4.key_event.create
+ * (approval required). Needs the analytics.edit scope; without it Google
+ * answers 403 and the caller should run `auth login --scope ga4_write`.
+ */
+export function createKeyEvent(propertyId, eventName, countingMethod = 'ONCE_PER_EVENT') {
+    return googleJson(`${ADMIN}/properties/${encodeURIComponent(propertyId)}/keyEvents`, {
+        method: 'POST', body: JSON.stringify({ eventName, countingMethod }),
+    });
+}
+/** Sessions, users, key events by channel for a window. Bounded output. */
+export async function summariseTraffic(propertyId, startDate, endDate) {
+    return runReport(propertyId, {
+        dateRanges: [{ startDate, endDate }],
+        dimensions: [{ name: 'sessionDefaultChannelGroup' }],
+        metrics: [{ name: 'sessions' }, { name: 'totalUsers' }, { name: 'keyEvents' }, { name: 'engagementRate' }],
+        limit: 20,
+    });
+}

package/packages/connectors/google/src/gsc.js

@@ -0,0 +1,49 @@
+/**
+ * Google Search Console. Read-only in v0.2.
+ *
+ * Search Analytics can return up to 25,000 rows per call. The raw call is
+ * exposed for completeness, but hosts should prefer summarise*() helpers,
+ * which keep results inside a model's context budget.
+ */
+import { googleJson } from "./auth.js";
+const V3 = 'https://www.googleapis.com/webmasters/v3';
+const V1 = 'https://searchconsole.googleapis.com/v1';
+export function searchAnalytics(siteUrl, body) {
+    return googleJson(`${V3}/sites/${encodeURIComponent(siteUrl)}/searchAnalytics/query`, {
+        method: 'POST', body: JSON.stringify({ rowLimit: 1000, ...body }),
+    });
+}
+export function listSitemaps(siteUrl) {
+    return googleJson(`${V3}/sites/${encodeURIComponent(siteUrl)}/sitemaps`);
+}
+/** Submit (or resubmit) a sitemap. Policy class: gsc.sitemap.submit (auto). */
+export async function submitSitemap(siteUrl, feedpath) {
+    await googleJson(`${V3}/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, { method: 'PUT' });
+}
+export function inspectUrl(siteUrl, inspectionUrl, languageCode = 'en-US') {
+    return googleJson(`${V1}/urlInspection/index:inspect`, {
+        method: 'POST', body: JSON.stringify({ inspectionUrl, siteUrl, languageCode }),
+    });
+}
+/**
+ * Top queries and pages for a window, plus totals. Bounded output.
+ */
+export async function summarisePerformance(siteUrl, startDate, endDate, top = 20) {
+    const [byQuery, byPage, totals] = await Promise.all([
+        searchAnalytics(siteUrl, { startDate, endDate, dimensions: ['query'], rowLimit: 5000 }),
+        searchAnalytics(siteUrl, { startDate, endDate, dimensions: ['page'], rowLimit: 5000 }),
+        searchAnalytics(siteUrl, { startDate, endDate, rowLimit: 1 }),
+    ]);
+    const shape = (rows = []) => rows.map((r) => ({ key: r.keys[0] ?? '', clicks: r.clicks, impressions: r.impressions, ctr: r.ctr, position: r.position }));
+    const q = shape(byQuery.rows), p = shape(byPage.rows), t = totals.rows?.[0];
+    return {
+        window: { startDate, endDate },
+        totals: t ? { clicks: t.clicks, impressions: t.impressions, ctr: t.ctr, position: t.position } : null,
+        queries: q.length, pages: p.length,
+        topQueriesByClicks: [...q].sort((a, b) => b.clicks - a.clicks).slice(0, top),
+        topPagesByClicks: [...p].sort((a, b) => b.clicks - a.clicks).slice(0, top),
+        // Position 4-15 with real impressions: the weekly playbook's "striking distance".
+        strikingDistance: q.filter((r) => r.position >= 4 && r.position <= 15 && r.impressions >= 50)
+            .sort((a, b) => b.impressions - a.impressions).slice(0, top),
+    };
+}