@topy-ai/maggie 0.7.46 → 0.7.48

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.46",
+  "version": "0.7.48",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/browser-inspection.md

@@ -75,3 +75,28 @@ appearance. For every stateful component capture state A and state B and
 record the trigger and transition. Keep screenshots and extracted data under
 the target's namespaced research root so multiple URLs cannot overwrite one
 another.
+
+## Network interception and write safety
+
+Any skill that drives a browser against a running app (QA, clone, design
+review) must assume the app may talk to a real API. A local development build
+is often configured with the production API base URL, so a click in local QA
+can change live accounts.
+
+- Do not rely on page-level stubs such as overriding `window.fetch` from the
+  console or an injected script. Bundled API clients usually capture `fetch`
+  at module load, use `XMLHttpRequest`, or run in a service worker, so the
+  override never sees their requests.
+- Intercept at the network layer instead: Playwright `page.route()` /
+  `context.route()`, Puppeteer request interception, or CDP `Fetch.enable`.
+  Deny by default every non-GET request to a production origin and let only
+  explicitly listed reads through.
+- Verify the interception before any write flow: trigger one harmless request
+  and confirm in the browser's network log that it was intercepted, not sent.
+- Without network-layer interception, run write flows only against a
+  non-production API, or after the user gives explicit consent naming the
+  account and the data that will change. Record a backup or restore path first.
+
+`maggie qa start --api-base URL --production-api URL` records the API target.
+Scenarios marked `"mutates": true` are blocked against a production API unless
+`--allow-production-writes` is given. See the `maggie-qa-workflow` skill.

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
 

package/references/provider-adapter-contract.md

@@ -150,6 +150,39 @@ image-processing contract: optimisation may use Cloudflare Images
 transformations, Astro build tooling or a provider-specific implementation
 behind the same interface.
 
+## OAuth connections
+
+A provider connection is only as reliable as its weakest connect path:
+
+- Each adapter declares one canonical OAuth scope set. Every client that
+  starts the flow (dashboard, mobile app, CLI) requests exactly that set.
+  LinkedIn invalidates a member's earlier tokens when a later sign-in asks for
+  a different scope set, so a mobile app that omits `email` silently revokes
+  the dashboard's token while the database still says `active`.
+- Prefer one OAuth client per product. When a client ID is shared with other
+  products or callbacks, record it as `client_shared_with`; their sign-ins can
+  revoke this product's tokens unless they use the identical scope set.
+- Treat stored connection status as a cache. A token that the provider has
+  revoked, or that the serving host cannot decrypt, is `needs_reconnect`
+  before anything is scheduled on it — not when a post fails.
+- Provider media URLs (for example `media.licdn.com` with an `e=` expiry) are
+  signed and expire. Cache the bytes in owned storage or refresh on readback.
+
+`maggie tool maggie_social_share.py adapters` and `connections` check these
+rules from a redacted JSON manifest; see the Social Share skill for shapes.
+
+## Structured model output
+
+Keep structured-output schemas small. Gemini rejected a JSON schema whose enum
+had 125 values with `400 INVALID_ARGUMENT`, and the caller silently fell back
+for every request. For a large vocabulary (styles, categories, catalogue IDs):
+
+1. ask for a free string (optionally with a short list of examples in the
+   prompt) instead of a large `enum`;
+2. validate the returned value server-side against the authoritative list;
+3. treat a schema rejection or an unknown value as a visible, counted failure —
+   never a silent fallback to a default.
+
 ## Adding a provider
 
 1. Implement the relevant interface in `src/lib/providers/`.