feat(gtm): write tools — create/update/delete tags + triggers + publish

[illia-sapryga]

Depends on #29

This PR is stacked on top of #29 ("feat(gtm): Tag Manager API integration with three-way tracking audit"). The current diff against main shows #29's changes + this PR's additions; once #29 merges, the diff will narrow to just the GTM write tools added here.

Summary

Builds on #29 (GTM read tools) to add the full write surface — create / update / delete for tags + triggers, plus workspace publish. Pattern matches the existing AdLoop safety model (draft + ChangePlan + confirm_and_apply).

Tools added (7)

Tool	Notes
draft_gtm_tag	Create tag (googtag, gclidw, html, gaawe, awcc, awud, awcr, awct, fls, flc, ua, img). Auto-resolves Default Workspace when workspace_id is omitted.
draft_gtm_trigger	Create trigger (pageview, click, linkClick, formSubmission, customEvent, elementVisibility, etc.).
draft_update_gtm_tag	Partial update of an existing tag — preserves the tag's fingerprint for optimistic concurrency, and any field the caller doesn't pass keeps its current value.
draft_update_gtm_trigger	Same pattern for triggers. Trigger type itself is immutable (delete + create instead).
draft_delete_gtm_tag	Hard delete; warns it's irreversible.
draft_delete_gtm_trigger	Hard delete; warns it's irreversible AND that GTM rejects the delete if any tag still references the trigger.
publish_gtm_workspace	Compile workspace into a ContainerVersion + publish to live. The actual go-live moment, separated from drafting.

Tag types accepted

The validator includes both Google's built-in template IDs (googtag, awcc, awud, gaawe, …) and the verbose long-form aliases (google_ads_calls_from_website, google_ads_user_provided_data, …). Floodlight templates (flc, fls) are included for legacy advertisers.

OAuth scopes

auth.py extends _GTM_SCOPES (and _ALL_SCOPES) from tagmanager.readonly to also include:

• tagmanager.edit.containers (create/update/delete tags + triggers)
• tagmanager.edit.containerversions (compile workspace into a version)
• tagmanager.publish (set the version live)

Migration: existing OAuth tokens issued under #29's read-only scope set will need to be deleted from ~/.adloop/token.json so the next API call triggers a re-auth that picks up the new scopes. Service-account auth needs the SA email upgraded from "Read" to "Publish" on the container in GTM Admin → User Management.

Dispatch routing

A small block at the top of _execute_plan in ads/write.py detects GTM operations and routes them to the GTM apply handlers (which fetch their own GTM client instead of reusing the Google Ads client). The dispatch list:

create_gtm_tag, create_gtm_trigger, publish_gtm_workspace,
update_gtm_tag, update_gtm_trigger,
delete_gtm_tag, delete_gtm_trigger

Workspace handling

GTM auto-creates a fresh "Default Workspace" after every publish; the old one becomes immutable (Workspace is already submitted). The _resolve_workspace() helper grabs the current Default Workspace by name on every apply call so callers don't need to track which numeric workspace ID is currently active.

Validated end-to-end

This batch was used to build out conversion tracking on a real GTM container (GTM-T68KKNMK, BGI Tint):

• Created Google Tag (AW-11437481610), Conversion Linker, GFN Phone Snippet (awcc template), GA4 Event tags (phone_click, form_submit_contact, cta_buttons_click)
• Updated tag names + parameters (renamed all tags + triggers to the Beaver Brothers {Platform} - {Type} - {Event} - {Scope} convention)
• Deleted a Custom HTML tag (the old GFN snippet) and replaced with the dedicated awcc template
• Published 4 container versions (8, 9, 10, 11)

Test plan

• Full suite passes: 255/255 tests (PR feat(gtm): Tag Manager API integration with three-way tracking audit #29 baseline 234 + 21 new GTM-write tests)
• tests/test_gtm_write.py covers:
  • All 4 draft validators (invalid types, required fields, duplicate-update rejection, custom-event-name requirement)
  • Real Google template IDs accepted (googtag, awcc, awud, etc.)
  • Long-name rejection
  • Filter persistence on triggers
  • Partial-update semantics on tags + triggers
  • Delete warnings (irreversible) for both tags + triggers
  • Publish warning (LIVE on next refresh)
  • MCP registration of all 7 tools
  • Dispatch wiring contains all 7 ops
• Service-account write path verified end-to-end against live container
• OAuth scope expansion compatible with existing PR feat(gtm): Tag Manager API integration with three-way tracking audit #29 auth flow

Why no other modules are touched

This PR is intentionally scoped to just the GTM write surface. Conversion-action management, asset extension tools, and other Google Ads write tools live in separate PRs (#34) so the diff here stays focused and reviewable.

[illia-sapryga]

Hey @kLOsk, just rebased onto main — CI is catching up but the merge is clean (333 tests passing). This builds on #29, so the natural merge order would be #29 first then this one. Is there anything I can address to help get these in?

[kLOsk]

Holding this behind #29. Beyond the rebase there are three blockers: (1) every _apply_* handler calls load_config() instead of using the config _execute_plan passes; under v0.10's multi-tenant runtime that would run one tenant's publish with another's credentials. (2) Custom-HTML tags plus publish is an arbitrary-JS-to-production path gated only by advisory warnings; it needs a real safety gate (a default blocked_operations entry or enforced double-confirm). (3) The write scopes land in _ALL_SCOPES, so every user grants publish authority whether they use these tools or not. Plus the apply handlers have zero test coverage; the dispatch test greps source strings. Happy to re-review after those.

[kLOsk]

Addendum to my July 7 blockers, from a deeper pass — items the rebase needs beyond what's already listed:

1. All 19 registrations reference the removed module-level _config — post-v0.10 they'd NameError on every call. Use current_config(). (This class of bug has now bitten two merges, so main carries a static regression test that scans server.py for stale _config tokens — your rebase will fail CI until they're all ported, which is the point.)
2. OAuth scope migration UX: existing token.json files were granted without the tagmanager scopes, so after upgrade every GTM call 403s with a raw Google error. Needs a mapping in _structured_error (insufficient-scope → 'delete ~/.adloop/token.json and re-auth') plus the README note about enabling the Tag Manager API.
3. tests/test_gtm_write.py's autouse fixture uses preview_store._pending_plans, which v0.10 replaced with the tenant-scoped store — use set_plan_store(InMemoryPlanStore()) like test_ads_write.py does. As-is the whole module errors on collection.
4. List params should use the coercion aliases (_StrListOpt/_DictListOpt) — parameters/filters are exactly the deeply-nested params that JSON-string-encoding clients break on (issue run_ga4_report — dimensions and metrics parameters fail Pydantic validation when passed as JSON arrays #28).
5. _apply_update_gtm_tag is a full replace that rebuilds from a fixed field list — it silently wipes priority, consentSettings, tagFiringOption, schedule fields, and folder on tags that have them. Your trigger updater already preserves extras; mirror that.
6. The long-form tag-type aliases (google_analytics_4_event etc.) pass validation but aren't valid GTM template IDs — they preview clean and then fail at apply with an opaque 400. Normalize to canonical IDs (gaawe, awct, ...) or drop the aliases. (Also awcr vs read.py's sp for Ads remarketing.)

Heads-up on sequencing: I'm bringing #29 up to v0.10 maintainer-side now (with attribution), so the read layer should be on main shortly — rebase this on top of that once it lands, which also shrinks this PR's diff to just the write surface.

The safety-model design here is still the strongest part — draft→plan→confirm with per-op blocklist names, _DESTRUCTIVE in the right places, and the compiler-error refusal on publish is exactly right.