@topy-ai/maggie 0.7.45 → 0.7.47

package/bundled-tools/runtime/external_write.py

@@ -0,0 +1,122 @@
+"""Validate bounded, hash-only evidence for an external provider write."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import urlsplit
+
+
+SCHEMA = "maggie-external-write-readback.v1"
+PROVIDERS = {"ga4", "gtm", "gsc", "google-ads", "firebase"}
+STATUSES = {"created", "updated", "no-op"}
+FINGERPRINT = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def _safe_text(value: Any, field: str, errors: list[str], pattern: str | None = None) -> str | None:
+    if not isinstance(value, str) or not value.strip() or len(value) > 200 or "@" in value or re.search(r"(?:token|secret|password|BEGIN PRIVATE)", value, re.I):
+        errors.append(f"{field} must be a bounded redacted identifier")
+        return None
+    if pattern and not re.fullmatch(pattern, value):
+        errors.append(f"{field} has an invalid format")
+        return None
+    return value
+
+
+def validate(value: Any) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(value, dict):
+        return {"schemaVersion": "maggie-external-write-readback-result.v1", "passed": False, "errors": ["evidence must be an object"], "mutation": "not executed"}
+    if value.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    if value.get("provider") not in PROVIDERS:
+        errors.append("provider is unsupported")
+    _safe_text(value.get("generatedAt"), "generatedAt", errors)
+    resource = _safe_text(value.get("resource"), "resource", errors)
+    _safe_text(value.get("operation"), "operation", errors, r"[a-z][a-z0-9_.-]{1,63}")
+    key = _safe_text(value.get("idempotencyKey"), "idempotencyKey", errors, r"[A-Za-z0-9][A-Za-z0-9_.:-]{2,127}")
+
+    retry = value.get("retry")
+    if not isinstance(retry, dict) or set(retry) != {"attempt", "maxAttempts", "sameKeyOnRetry"}:
+        errors.append("retry must contain attempt, maxAttempts, and sameKeyOnRetry")
+        retry = {}
+    else:
+        attempt, maximum = retry.get("attempt"), retry.get("maxAttempts")
+        if not isinstance(attempt, int) or not 1 <= attempt <= 3:
+            errors.append("retry.attempt must be between 1 and 3")
+        if not isinstance(maximum, int) or not 1 <= maximum <= 3 or (isinstance(attempt, int) and isinstance(maximum, int) and attempt > maximum):
+            errors.append("retry.maxAttempts must be between attempt and 3")
+        if retry.get("sameKeyOnRetry") is not True:
+            errors.append("retry.sameKeyOnRetry must be true")
+
+    mutation = value.get("mutation")
+    if not isinstance(mutation, dict) or set(mutation) != {"status", "statusCode", "explicitConfirmation"}:
+        errors.append("mutation must contain status, statusCode, and explicitConfirmation")
+        mutation = {}
+    else:
+        if mutation.get("status") not in STATUSES:
+            errors.append("mutation.status is unsupported")
+        if not isinstance(mutation.get("statusCode"), int) or not 200 <= mutation["statusCode"] <= 299:
+            errors.append("mutation.statusCode must be a successful HTTP status")
+        if mutation.get("explicitConfirmation") is not True:
+            errors.append("mutation requires explicit confirmation")
+    if value.get("mutationExecuted") is not True:
+        errors.append("mutationExecuted must be true")
+
+    readback = value.get("readback")
+    safe_checks: list[dict[str, Any]] = []
+    if not isinstance(readback, dict) or set(readback) != {"passed", "endpoint", "checks"}:
+        errors.append("readback must contain passed, endpoint, and checks")
+        readback = {}
+    else:
+        if readback.get("passed") is not True:
+            errors.append("readback.passed must be true")
+        endpoint = readback.get("endpoint")
+        parsed = urlsplit(endpoint) if isinstance(endpoint, str) else None
+        if not parsed or parsed.scheme != "https" or not parsed.netloc or parsed.query or parsed.fragment or parsed.username or parsed.password:
+            errors.append("readback.endpoint must be an HTTPS URL without credentials/query")
+        checks = readback.get("checks")
+        if not isinstance(checks, list) or not checks:
+            errors.append("readback.checks must be a non-empty array")
+            checks = []
+        for index, check in enumerate(checks):
+            prefix = f"readback.checks[{index}]"
+            if not isinstance(check, dict) or set(check) != {"name", "expectedFingerprint", "observedFingerprint", "passed"}:
+                errors.append(f"{prefix} must contain name and hash-only invariant fields")
+                continue
+            name = _safe_text(check.get("name"), f"{prefix}.name", errors)
+            expected = check.get("expectedFingerprint")
+            observed = check.get("observedFingerprint")
+            if not isinstance(expected, str) or not FINGERPRINT.fullmatch(expected):
+                errors.append(f"{prefix}.expectedFingerprint must be sha256")
+            if not isinstance(observed, str) or not FINGERPRINT.fullmatch(observed):
+                errors.append(f"{prefix}.observedFingerprint must be sha256")
+            if check.get("passed") is not True or expected != observed:
+                errors.append(f"{prefix} does not match its expected readback")
+            safe_checks.append({"name": name, "passed": check.get("passed") is True})
+
+    duplicates = value.get("duplicates")
+    orphaned = value.get("orphaned")
+    if not isinstance(duplicates, list) or duplicates:
+        errors.append("duplicates must be an empty array after reconciliation")
+    if not isinstance(orphaned, list) or orphaned:
+        errors.append("orphaned must be an empty array after cleanup")
+    cleanup = value.get("cleanup")
+    if not isinstance(cleanup, dict) or set(cleanup) != {"status", "checked"} or cleanup.get("status") not in {"not-needed", "passed"} or cleanup.get("checked") is not True:
+        errors.append("cleanup must be checked and not-needed or passed")
+
+    return {
+        "schemaVersion": "maggie-external-write-readback-result.v1",
+        "passed": not errors,
+        "errors": sorted(set(errors)),
+        "provider": value.get("provider"),
+        "resource": resource,
+        "operation": value.get("operation"),
+        "idempotencyKey": key,
+        "retry": {"attempt": retry.get("attempt"), "maxAttempts": retry.get("maxAttempts"), "sameKeyOnRetry": retry.get("sameKeyOnRetry") is True},
+        "readback": {"passed": readback.get("passed") is True, "checks": safe_checks} if isinstance(readback, dict) else {"passed": False, "checks": []},
+        "duplicates": [],
+        "orphaned": [],
+        "cleanup": cleanup if isinstance(cleanup, dict) else {},
+        "mutation": "not executed",
+    }

package/bundled-tools/runtime/google_capabilities.py

@@ -7,7 +7,7 @@ from typing import Any
 from urllib.parse import urlsplit
 
 
-SCHEMA_VERSION = "maggie-google-capability-report.v1"
+SCHEMA_VERSION = "maggie-google-capability-report.v2"
 CAPABILITY_NAMES = ("read", "report", "edit", "publish")
 CAPABILITY_STATES = {"verified", "not_tested", "not_available", "blocked"}
 PROVIDERS = {"gsc", "ga4", "gtm", "google-ads", "firebase"}
@@ -112,6 +112,34 @@ def _write_test(value: Any, field: str, errors: list[str]) -> bool:
     return valid and not unknown
 
 
+def _verified_reference(value: Any, field: str, errors: list[str]) -> dict[str, Any]:
+    if not isinstance(value, dict) or set(value) != {"id", "verified"}:
+        errors.append(f"{field} must contain only id and verified")
+        return {"id": None, "verified": False}
+    identifier = value.get("id")
+    if not isinstance(identifier, str) or not identifier.strip() or len(identifier) > 200 or re.search(r"[@\s]", identifier):
+        errors.append(f"{field}.id must be a redacted non-email identifier")
+    if value.get("verified") is not True:
+        errors.append(f"{field}.verified must be true")
+    return {"id": identifier if isinstance(identifier, str) else None, "verified": value.get("verified") is True}
+
+
+def _target_reference(value: Any, resource: str, field: str, errors: list[str]) -> dict[str, Any]:
+    if not isinstance(value, dict) or set(value) != {"id", "kind", "verified"}:
+        errors.append(f"{field} must contain only id, kind, and verified")
+        return {"id": None, "kind": None, "verified": False}
+    identifier = value.get("id")
+    if not isinstance(identifier, str) or not identifier.strip() or len(identifier) > 200 or re.search(r"[@\s]", identifier):
+        errors.append(f"{field}.id must be a redacted non-email identifier")
+    if identifier != resource:
+        errors.append(f"{field}.id must equal the selected resource")
+    if value.get("kind") not in {"property", "container", "customer", "project", "site", "account"}:
+        errors.append(f"{field}.kind is unsupported")
+    if value.get("verified") is not True:
+        errors.append(f"{field}.verified must be true")
+    return {"id": identifier if isinstance(identifier, str) else None, "kind": value.get("kind"), "verified": value.get("verified") is True}
+
+
 def _required_scope(provider: str, capability: str) -> str | None:
     if capability == "read" or capability == "report":
         return READ_SCOPES[provider]
@@ -124,9 +152,9 @@ def validate_report(report: Any) -> dict[str, Any]:
     """Return safe validation output; never returns arbitrary input fields."""
     errors: list[str] = []
     if not isinstance(report, dict):
-        return {"schemaVersion": "maggie-google-capability-report-result.v1", "passed": False, "errors": ["report must be an object"], "providerResults": []}
+        return {"schemaVersion": "maggie-google-capability-report-result.v2", "passed": False, "errors": ["report must be an object"], "providerResults": []}
     if report.get("schemaVersion") != SCHEMA_VERSION:
-        errors.append("schemaVersion must be maggie-google-capability-report.v1")
+        errors.append("schemaVersion must be maggie-google-capability-report.v2; v1 reports lack target guard evidence")
     if not _string(report.get("generatedAt"), "generatedAt", errors):
         pass
     if report.get("mutationsAllowed") is not False:
@@ -143,7 +171,7 @@ def validate_report(report: Any) -> dict[str, Any]:
         if not isinstance(row, dict):
             errors.append(f"{prefix} must be an object")
             continue
-        required = {"provider", "resource", "authMode", "scopes", "productRole", "evidence", "capabilities", "nextAction"}
+        required = {"provider", "resource", "activeAccount", "target", "authMode", "scopes", "productRole", "evidence", "capabilities", "nextAction"}
         unknown = sorted(set(row) - required)
         if unknown:
             errors.append(f"{prefix} contains unsupported fields")
@@ -154,6 +182,8 @@ def validate_report(report: Any) -> dict[str, Any]:
             continue
         if not _string(resource, f"{prefix}.resource", errors, max_length=200):
             continue
+        active_account = _verified_reference(row.get("activeAccount"), f"{prefix}.activeAccount", errors)
+        target = _target_reference(row.get("target"), resource, f"{prefix}.target", errors)
         key = (provider, resource)
         if key in seen:
             errors.append(f"{prefix} duplicates provider/resource")
@@ -226,6 +256,8 @@ def validate_report(report: Any) -> dict[str, Any]:
         normalized.append({
             "provider": provider,
             "resource": resource,
+            "activeAccount": active_account,
+            "target": target,
             "authMode": row.get("authMode"),
             "scopes": sorted(scopes),
             "productRole": row.get("productRole"),
@@ -241,7 +273,7 @@ def validate_report(report: Any) -> dict[str, Any]:
         })
 
     return {
-        "schemaVersion": "maggie-google-capability-report-result.v1",
+        "schemaVersion": "maggie-google-capability-report-result.v2",
         "passed": not errors,
         "errors": sorted(set(errors)),
         "providerResults": normalized,

package/bundled-tools/runtime/maggie_memory.py

@@ -73,7 +73,16 @@ def write(project: str | Path, kind: str, payload: dict[str, Any]) -> Path:
 
 
 def init(project: str | Path) -> dict[str, str]:
-    return {kind: str(write(project, kind, read(project, kind))) for kind in KINDS}
+    paths: dict[str, str] = {}
+    for kind in KINDS:
+        path = memory_path(project, kind)
+        if path.exists():
+            # Validate existing state, but keep its bytes and mtime unchanged.
+            read(project, kind)
+        else:
+            write(project, kind, empty(kind))
+        paths[kind] = str(path)
+    return paths
 
 
 def _text(value: Any, field: str, required: bool = False) -> str:
@@ -176,11 +185,13 @@ def _active(item: dict[str, Any], project_id: str = "") -> bool:
     return not expires or expires > now()
 
 
-def relevant(project: str | Path, *, skill: str = "", query: str = "", project_id: str = "", status: str | None = None) -> dict[str, list[dict[str, Any]]]:
+def relevant(project: str | Path, *, skill: str = "", query: str = "", project_id: str = "", status: str | None = None, include_shared: bool = False) -> dict[str, list[dict[str, Any]]]:
     terms = set(re.findall(r"[a-z0-9_-]+", f"{skill} {query}".lower()))
     result: dict[str, list[dict[str, Any]]] = {kind: [] for kind in KINDS}
     for kind in KINDS:
         for item in read(project, kind)["items"]:
+            if not include_shared and item.get("scope") != "project":
+                continue
             if status is not None:
                 if item.get("status") != status:
                     continue
@@ -194,6 +205,10 @@ def relevant(project: str | Path, *, skill: str = "", query: str = "", project_i
     return result
 
 
+def initialized(project: str | Path) -> bool:
+    return all(memory_path(project, kind).is_file() for kind in KINDS)
+
+
 def transition(project: str | Path, kind: str, item_id: str, status: str) -> dict[str, Any]:
     if status not in STATUSES:
         raise ValueError(f"invalid status: {status}")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.45",
+  "version": "0.7.47",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/browser-inspection.md

@@ -14,6 +14,23 @@ The browser capability must support:
 - slow scrolling, click, hover, keyboard focus, and back/forward navigation;
 - reading computed CSS, media sources, links, and visible accessibility labels.
 
+Before navigation, Maggie runs a capability preflight against the configured
+adapter. The report is `maggie-browser-capability.v1` and classifies the
+adapter as `ready`, `missing`, or `incompatible`. This prevents a system
+`browse`/`xdg-open` desktop opener from being mistaken for a browser adapter:
+
+```bash
+maggie browser-audit https://example.com \
+  --browse "$HOME/.codex/skills/gstack/browse/dist/browse" \
+  --output .maggie/browser-audit --required body --check-browser
+```
+
+The report contains only the adapter name, path fingerprints, capability
+checks, and bounded installation/fallback guidance. If it is `missing` or
+`incompatible`, install or enable an authorized Chrome/Playwright/gstack
+adapter and pass its executable path. Maggie does not silently install a
+browser runtime or use a desktop opener as a fallback.
+
 The minimum extraction result for a target is:
 
 ```text

package/references/google-integrations-runbook.md

@@ -111,8 +111,13 @@ maggie ops google-capabilities \
 ```
 
 The report contract is
-[`capability-report-v1.json`](../bundled-contracts/google-integrations/capability-report-v1.json).
+[`capability-report-v2.schema.json`](../bundled-contracts/google-integrations/capability-report-v2.schema.json).
 The CLI writes a normalized result and never copies arbitrary input fields.
+Every provider row must also identify the redacted active account and selected
+target resource, both with `verified: true`; the target ID must equal the
+selected `resource`. A report that only proves account discovery, or comes from
+the wrong browser account/property, is rejected before a write workflow can use
+it.
 
 ## Capability matrix
 
@@ -121,6 +126,8 @@ Every provider/resource row must expose this shape:
 | Field | Meaning |
 |---|---|
 | `provider` / `resource` | The Google product and scoped resource being checked |
+| `activeAccount` | Redacted account/principal reference confirmed by the current auth session |
+| `target` | Resource ID and kind confirmed in the current account; must match `resource` |
 | `authMode` | `desktop-oauth`, `service-account-impersonation`, or `none` |
 | `scopes` | Exact allowlisted OAuth scopes, never token values |
 | `productRole` | Role granted in the product, distinct from Cloud IAM |

package/references/memory-hook.md

@@ -1,23 +1,36 @@
 # Maggie Memory Hook
 
-Every Maggie skill invocation has an automatic memory lifecycle when the host
-project contains `tools/clis/maggie_memory.py`.
+Every Maggie skill invocation uses the current project's Maggie Memory by
+default. Project initialization creates `.maggie/memory/` for that repository.
 
 ## Before work
 
-Run:
+Use the project-local adapter when it is present:
 
 ```bash
 python3 tools/clis/maggie_memory.py context --project . --skill <current-skill>
 ```
 
+If that adapter is absent, use the installed CLI:
+
+```bash
+maggie memory context --project . --skill <current-skill>
+```
+
 Load the returned active preferences, conventions, lessons, and matching error
 history into the current decision context. Surface material rules and verify
 them against current project evidence. Memory never replaces inspection,
 approval, bootstrap, or production gates.
 
-If the command is unavailable, report that memory is unavailable and continue
-with the normal workflow. Do not invent or silently reconstruct memory.
+The context response reports `status: "uninitialized"` when Maggie Memory is
+available but the project has not initialized its store. In that case, explain
+that `maggie init --scope project` initializes it; do not call memory
+unavailable. Report unavailable only when neither the project adapter nor the
+installed `maggie` CLI can run. Do not invent or silently reconstruct memory.
+
+Context includes only active project-scope items for the current repository.
+Include user/workspace entries only after a separate explicit opt-in with
+`--include-shared`.
 
 ## After work