@topy-ai/maggie 0.7.61 → 0.8.1

package/bundled-tools/clis/maggie_security_scan.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""``maggie security scan`` — one command that runs the right detectors for the
+site's profile and then builds a report.
+
+The suite has many focused detectors; chaining them by hand (vuln-watch → deps →
+secrets → headers → tls → host-quick → … → report) is the main source of workflow
+friction, and it is what a scheduled routine or an MCP agent would otherwise have
+to script. ``scan`` reads the profile (from the inventory, or ``--profile``), runs
+exactly the detectors that profile expects, and finishes with a report — each
+detector in its own process, best-effort, so one that degrades or refuses does not
+abort the scan. It never does anything the individual commands would not: web
+checks still need a verified domain, host checks still need ``--ssh`` consent.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import maggie_security_core as core
+import maggie_security_report as report
+
+CLI = Path(__file__).resolve().parent / "maggie_security.py"
+
+# Detectors that need a target beyond the project tree.
+WEB = {"headers", "tls", "web-scan"}                       # need a verified domain
+HOST = {"host-quick", "host-nginx-config", "host-impact"}  # need --ssh ALIAS=user@host
+# Interactive / heavy / uncontrolled-target commands are never auto-run by scan.
+NEVER_AUTORUN = {"logs-remote", "host-audit", "zap-baseline", "public-check", "web-scan", "hosted-job"}
+# Project detectors worth running for any profile even if EXPECTED omits them.
+ALWAYS = ["secrets", "code-scan"]
+
+
+def _argv_for(command: str, args: argparse.Namespace) -> tuple[list[str] | None, str | None]:
+    """The sub-command argv for this scan, or (None, reason) to skip it."""
+    if command in WEB:
+        if not args.domain:
+            return None, "needs a verified domain (pass --domain)"
+        return [command, "--domain", args.domain], None
+    if command in HOST:
+        if not args.ssh:
+            return None, "needs a server (pass --ssh ALIAS=user@host)"
+        return [command, "--ssh", args.ssh], None
+    return [command], None
+
+
+def _findings_count(data: dict) -> int | None:
+    summary = (data or {}).get("summary") or {}
+    if not summary:
+        return None
+    return int(summary.get("new", 0)) + int(summary.get("open", 0))
+
+
+def scan(ctx: core.Context) -> dict:
+    args = ctx.args
+    project = ctx.project
+    import maggie_security as dispatch
+
+    built = set(dispatch.area_commands())
+
+    def run_cmd(argv: list[str]) -> tuple[int, dict, str]:
+        full = [sys.executable, str(CLI), *argv, "--project", str(project), "--format", "json", "--max-items", "200"]
+        if args.offline:
+            full.append("--offline")
+        proc = subprocess.run(full, capture_output=True, text=True, timeout=1800, check=False)
+        try:
+            data = json.loads(proc.stdout) if proc.stdout.strip() else {}
+        except ValueError:
+            data = {}
+        return proc.returncode, (data if isinstance(data, dict) else {}), proc.stderr
+
+    steps: list[dict] = []
+    skipped: list[dict] = []
+
+    # 1. Inventory first, so the profile and every later detector see the same stack.
+    code, data, _ = run_cmd(["inventory"])
+    steps.append({"command": "inventory", "exit": code, "degraded": bool(data.get("degraded"))})
+
+    # 2. Decide the profile.
+    stack_path = ctx.state.path("inventory", "stack.json")
+    profile = args.profile
+    if not profile:
+        if stack_path.is_file():
+            profile = (core.read_json(stack_path).get("site") or {}).get("type") or "unknown"
+        else:
+            profile = core.detect_site_type(project)
+
+    # 3. Build the ordered detector plan from the profile, plus the always-useful ones.
+    plan: list[str] = []
+    for command in list(report.EXPECTED.get(profile, report.EXPECTED["unknown"])) + ALWAYS:
+        if command in built and command not in NEVER_AUTORUN and command not in plan:
+            plan.append(command)
+
+    # 4. Run each detector, best-effort.
+    for command in plan:
+        argv, reason = _argv_for(command, args)
+        if argv is None:
+            skipped.append({"command": command, "reason": reason})
+            continue
+        code, data, _ = run_cmd(argv)
+        steps.append({"command": command, "exit": code, "degraded": bool(data.get("degraded")),
+                      "findings": _findings_count(data),
+                      "refused": code in (core.EXIT_USAGE, core.EXIT_POLICY, core.EXIT_TOOL)})
+
+    # 5. Report (and optionally a fix-plan).
+    rcode, rdata, _ = run_cmd(["report"] + (["--kind", args.kind] if args.kind else []))
+    verdict = ((rdata.get("report") or {}).get("verdict") or {}) if rdata else {}
+    out: dict = {
+        "schema": "maggie-security-scan.v1", "site": ctx.site, "profile": profile,
+        "ran": [s["command"] for s in steps], "skipped": skipped, "steps": steps,
+        "degraded": [s["command"] for s in steps if s.get("degraded")],
+        "verdict": verdict, "report": rdata.get("report") if rdata else None,
+    }
+    if args.fix_plan:
+        _c, fdata, _e = run_cmd(["fix-plan"])
+        out["fix_plan"] = {"actions": fdata.get("actions"), "tiers": fdata.get("tiers")} if fdata else None
+
+    out["markdown"] = render_scan(out, rdata.get("markdown") if rdata else None)
+    # exit code: actionable report -> 1; else degraded -> 3; else 0
+    if verdict.get("code") in ("act-today", "possible-break-in"):
+        out["exit_code"] = core.EXIT_FINDINGS
+    elif out["degraded"]:
+        out["exit_code"] = core.EXIT_DEGRADED
+    return out
+
+
+def render_scan(out: dict, report_md: str | None) -> str:
+    lines = [f"# Security scan — {out['site']} ({out['profile']})", ""]
+    ran = [s for s in out["steps"] if not s.get("refused")]
+    lines.append(f"Ran {len(ran)} checks" + (f", {len(out['degraded'])} degraded" if out["degraded"] else "")
+                 + (f", {len(out['skipped'])} skipped." if out["skipped"] else "."))
+    lines.append("")
+    lines += ["| Check | Result |", "|---|---|"]
+    for step in out["steps"]:
+        if step["command"] == "inventory":
+            result = "degraded" if step["degraded"] else "ok"
+        elif step.get("refused"):
+            result = "refused"
+        elif step.get("findings"):
+            result = f"{step['findings']} finding(s)"
+        elif step["degraded"]:
+            result = "incomplete"
+        else:
+            result = "no issues"
+        lines.append(f"| {step['command']} | {result} |")
+    for skip in out["skipped"]:
+        lines.append(f"| {skip['command']} | skipped: {skip['reason']} |")
+    lines.append("")
+    if out.get("verdict"):
+        lines += [f"**Verdict:** {out['verdict'].get('text', '')}", ""]
+    if report_md:
+        lines += ["---", "", report_md]
+    return "\n".join(lines)
+
+
+def configure(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--profile", choices=sorted(report.EXPECTED), help="override the detected site profile")
+    parser.add_argument("--domain", help="verified domain for the web checks (headers, tls)")
+    parser.add_argument("--ssh", help="ALIAS=user@host for the host checks (needs ssh-read consent)")
+    parser.add_argument("--kind", choices=["weekly", "daily_ops"], help="report kind to build at the end (default: weekly)")
+    parser.add_argument("--fix-plan", action="store_true", dest="fix_plan", help="also build a remediation fix-plan")
+
+
+COMMANDS = [core.Command("scan", "run the detectors for the site's profile, then build a report (one-shot; each detector best-effort)", [],
+                         configure, scan, findings=False)]

package/bundled-tools/clis/maggie_security_web.py

@@ -453,6 +453,50 @@ def csp_problems(value: str) -> list[str]:
     return problems
 
 
+# Letter grade for HTTP security headers, using the additive model from
+# mdn-http-observatory (MPL-2.0; score table and grade chart ported as data):
+# start at 100, apply the single worst penalty per category, map to a letter.
+GRADE_CHART = [(100, "A+"), (85, "A"), (80, "B+"), (70, "B"), (65, "B-"),
+               (60, "C+"), (50, "C"), (45, "C-"), (40, "D+"), (30, "D"), (25, "D-"), (0, "F")]
+# rule_id stem (after the `header-` prefix) -> (category, penalty). Worst per category counts once.
+HEADER_PENALTIES = {
+    "csp-missing": ("csp", -25), "csp-": ("csp", -10),
+    "hsts-missing": ("hsts", -20), "hsts-short": ("hsts", -10),
+    "xcto": ("xcto", -5),
+    "framing": ("framing", -20), "xfo-allow-from": ("framing", -20),
+    "referrer-missing": ("referrer", -5), "referrer-weak": ("referrer", -5),
+    "cors-wildcard-credentials": ("cors", -50),
+    "cookie-": ("cookie", -20),
+    "version-": ("disclosure", -5),
+}
+
+
+def header_grade(findings: list[dict]) -> dict:
+    """Observatory-style score (0–100) and letter grade from the header findings."""
+    worst: dict[str, int] = {}
+    for finding in findings:
+        stem = (finding["source"]["rule_id"] or "").removeprefix("header-")
+        match = HEADER_PENALTIES.get(stem) or next((v for k, v in HEADER_PENALTIES.items() if k.endswith("-") and stem.startswith(k)), None)
+        if match:
+            category, penalty = match
+            worst[category] = min(worst.get(category, 0), penalty)
+    score = max(0, min(100, 100 + sum(worst.values())))
+    grade = next(letter for threshold, letter in GRADE_CHART if score >= threshold)
+    return {"score": score, "grade": grade, "deductions": sorted(worst.items(), key=lambda kv: kv[1])}
+
+
+def grade_finding(ctx: core.Context, url: str, findings: list[dict]) -> dict:
+    g = header_grade(findings)
+    gaps = ", ".join(c for c, _ in g["deductions"]) or "nothing major"
+    summary = (f"Security-header grade {g['grade']} ({g['score']}/100). "
+               + (f"Biggest gaps: {gaps}. Fix the items below to raise it." if g["deductions"] else "No major header gaps."))
+    return core.make_finding(
+        kind="header", command="headers", primary_id="header-grade", site=ctx.site,
+        title=f"HTTP security headers grade: {g['grade']} ({g['score']}/100)", severity="info", severity_source="maggie",
+        confidence="confirmed", target={"url": url, "host": host_of(url)}, rule_id="header-grade",
+        remediation={"summary": summary, "steps": [], "snippets": [], "references": [], "cheat_sheet": None})
+
+
 def grade_response(ctx: core.Context, url: str, response: dict, layer: str, https: bool) -> list[dict]:
     headers = response["headers"]
     first = lambda name: (headers.get(name) or [None])[0]  # noqa: E731
@@ -530,7 +574,7 @@ def grade_response(ctx: core.Context, url: str, response: dict, layer: str, http
     if origin and origin.strip() == "*" and (first("access-control-allow-credentials") or "").lower() == "true":
         add("cors-wildcard-credentials", "CORS allows any origin with credentials", "high", ["V3.4.2"], kind="misconfiguration",
             evidence="Access-Control-Allow-Origin: *; Allow-Credentials: true")
-    return findings
+    return [grade_finding(ctx, url, findings)] + findings
 
 
 def headers_cmd(ctx: core.Context):

package/bundled-tools/clis/maggie_spirit.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""maggie_spirit — generate an AI brand's pixel spirit (sprite) system.
+
+One flat-pixel visual language for an agent brand:
+  * a logo "mark" that animates through a fixed 32-state base set, and
+  * per-agent avatar faces that animate through the same 32 states.
+
+Everything is deterministic (seeded by accent + persona) and self-contained
+(Pillow only). See skills/maggie-spirit/SKILL.md for the workflow.
+
+Subcommands:
+  mark   --out DIR [--name mark] [--accent #ff1212] [--title ONEMAN] [--scale 9]
+         Logo mark + 32-state animated base set + sprite sheet + states.json.
+  agent  --out DIR --name cto --accent #3b82f6 --spec persona.json
+         One agent avatar animated through all 32 states (+ sheet + states.json).
+  avatar --out FILE.png --accent #3b82f6 --spec persona.json [--scale 10]
+         A single still avatar face (no animation).
+  demo   --out DIR
+         The reference spirit base set: the default mark + 8 example agents +
+         founder — a starter kit to copy and recolour.
+
+persona.json (agent/avatar), all keys optional except noted:
+  {"gender":"m|f","hair":"#2a2018","skin":"light|mid|tan|deep",
+   "hairstyle":"short|slick|spiky|buzz|longwavy|longstraight|longbob|ponytail",
+   "eyes":"round|wide|lash|happy","mouth":"flat|smile|smirk|lips|open",
+   "prop":"glasses|shades|cigar|headset|earbuds|monocle|pen|bandana",
+   "propcol":"#f2c75a","hoodie":true,"band":"#e23b3b","mask":"#12201a","specs":true}
+"""
+import argparse, json, os, sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+RUNTIME = os.path.normpath(os.path.join(HERE, "..", "runtime"))
+if RUNTIME not in sys.path:
+    sys.path.insert(0, RUNTIME)
+
+try:
+    import spirit_base as B
+    import spirit_face as F
+    import spirit_agent as A
+except ImportError as e:  # pragma: no cover
+    sys.stderr.write(
+        "maggie_spirit needs Pillow and the spirit_* runtime modules.\n"
+        f"  {e}\n  pip install pillow\n")
+    raise SystemExit(2)
+
+
+def _load_spec(path):
+    if not path:
+        return {}
+    with open(path, "r", encoding="utf-8") as fh:
+        spec = json.load(fh)
+    if not isinstance(spec, dict):
+        raise SystemExit("persona spec must be a JSON object")
+    return spec
+
+
+def cmd_mark(a):
+    B.OUT_BASE = os.path.abspath(a.out)
+    os.makedirs(B.OUT_BASE, exist_ok=True)
+    meta = B.generate(B.Motif.oneman(), accent=a.accent, out=a.name,
+                      title=a.title, scale=a.scale)
+    print(f"{a.title}: {len(meta['states'])} states -> {os.path.join(a.out, a.name)}/")
+    print("groups:", ", ".join(meta.get("groups", [])))
+
+
+def _persona(spec):
+    gender = spec.get("gender", "m")
+    params = {k: v for k, v in spec.items() if k != "gender"}
+    params.setdefault("hair", "#1c1c22")
+    params.setdefault("skin", "mid")
+    return gender, params
+
+
+def cmd_agent(a):
+    A.OUT_BASE = os.path.abspath(a.out)
+    os.makedirs(A.OUT_BASE, exist_ok=True)
+    gender, params = _persona(_load_spec(a.spec))
+    meta = A.gen_agent(a.name.lower(), a.accent, gender, params, scale=a.scale)
+    print(f"{a.name} {a.accent} {gender}: {len(meta['states'])} states -> "
+          f"{os.path.join(a.out, a.name.lower())}/")
+
+
+def cmd_avatar(a):
+    gender, params = _persona(_load_spec(a.spec))
+    img = F.render(F.face(a.accent, gender=gender, **params), a.scale)
+    out = os.path.abspath(a.out)
+    os.makedirs(os.path.dirname(out) or ".", exist_ok=True)
+    img.save(out)
+    print(f"avatar -> {a.out} ({img.size[0]}x{img.size[1]})")
+
+
+def cmd_demo(a):
+    base = os.path.abspath(a.out)
+    os.makedirs(base, exist_ok=True)
+    B.OUT_BASE = base
+    A.OUT_BASE = base
+    B.generate(B.Motif.oneman(), accent="#ff1212", out="oneman", title="ONEMAN")
+    made = ["oneman (mark)"]
+    for role, acc, g, p in list(F.CAST) + [F.FOUNDER]:
+        A.gen_agent(role.lower(), acc, g, p)
+        made.append(role.lower())
+    print(f"spirit base set -> {a.out}/")
+    print("generated:", ", ".join(made))
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="maggie_spirit", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    m = sub.add_parser("mark", help="logo mark + 32-state animated base set")
+    m.add_argument("--out", required=True)
+    m.add_argument("--name", default="mark")
+    m.add_argument("--accent", default="#ff1212")
+    m.add_argument("--title", default="ONEMAN")
+    m.add_argument("--scale", type=int, default=9)
+    m.set_defaults(fn=cmd_mark)
+
+    ag = sub.add_parser("agent", help="one agent avatar through all 32 states")
+    ag.add_argument("--out", required=True)
+    ag.add_argument("--name", required=True)
+    ag.add_argument("--accent", required=True)
+    ag.add_argument("--spec", help="persona.json")
+    ag.add_argument("--scale", type=int, default=8)
+    ag.set_defaults(fn=cmd_agent)
+
+    av = sub.add_parser("avatar", help="a single still avatar face")
+    av.add_argument("--out", required=True)
+    av.add_argument("--accent", required=True)
+    av.add_argument("--spec", help="persona.json")
+    av.add_argument("--scale", type=int, default=10)
+    av.set_defaults(fn=cmd_avatar)
+
+    d = sub.add_parser("demo", help="reference spirit base set (mark + examples)")
+    d.add_argument("--out", required=True)
+    d.set_defaults(fn=cmd_demo)
+
+    a = ap.parse_args(argv)
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()

package/bundled-tools/clis/security_data/tools.lock.json

@@ -1,6 +1,7 @@
 {
   "schema": "maggie-security-tools-lock.v1",
   "updated": "2026-10-24",
+  "generated_at": "2026-10-24T00:00:00Z",
   "tools": {
     "osv-scanner": {
       "version": "2.6.0",
@@ -104,7 +105,7 @@
       "assets": {
         "linux-amd64": {
           "url": "https://github.com/projectdiscovery/nuclei/releases/download/v3.4.10/nuclei_3.4.10_linux_amd64.zip",
-          "sha256": "UNPINNED",
+          "sha256": "234c12cc5288af071abdcd6f854245b6067345556e1235cf96b76725c1004357",
           "archive": "zip",
           "member": "nuclei"
         }
@@ -137,7 +138,7 @@
       "assets": {
         "linux-amd64": {
           "url": "https://github.com/projectdiscovery/httpx/releases/download/v1.7.1/httpx_1.7.1_linux_amd64.zip",
-          "sha256": "UNPINNED",
+          "sha256": "865806a4eec321368e365b419baa3abdc0deb0d4ba598fe85a548a7c8682eb30",
           "archive": "zip",
           "member": "httpx"
         }
@@ -240,7 +241,7 @@
       "assets": {
         "linux-amd64": {
           "url": "https://github.com/anchore/syft/releases/download/v1.33.0/syft_1.33.0_linux_amd64.tar.gz",
-          "sha256": "UNPINNED",
+          "sha256": "adc1b944a827ed3432bcd9f1dbdbc8fa3c0dca7d3d449e7084c90248c2c6cb50",
           "archive": "tar.gz",
           "member": "syft"
         }
@@ -259,7 +260,7 @@
       "assets": {
         "linux-amd64": {
           "url": "https://github.com/anchore/grype/releases/download/v0.100.0/grype_0.100.0_linux_amd64.tar.gz",
-          "sha256": "UNPINNED",
+          "sha256": "9f4ed948b596a1978ec609eaa5538a9f2558836799b7b0a81f729408daf23e03",
           "archive": "tar.gz",
           "member": "grype"
         }
@@ -271,14 +272,14 @@
       }
     },
     "trivy": {
-      "version": "0.67.2",
+      "version": "0.76.1",
       "licence": "Apache-2.0",
       "class": "bundle-ok",
       "homepage": "https://github.com/aquasecurity/trivy",
       "assets": {
         "linux-amd64": {
-          "url": "https://github.com/aquasecurity/trivy/releases/download/v0.67.2/trivy_0.67.2_Linux-64bit.tar.gz",
-          "sha256": "UNPINNED",
+          "url": "https://github.com/aquasecurity/trivy/releases/download/v0.76.1/trivy_0.76.1_Linux-64bit.tar.gz",
+          "sha256": "c7cbe3137fb8a48a17574bede3dd6beb16742d1e9772929940fc90082c39d9c0",
           "archive": "tar.gz",
           "member": "trivy"
         }
@@ -290,11 +291,38 @@
         "--server"
       ]
     },
+    "copa": {
+      "version": "0.15.0",
+      "licence": "Apache-2.0",
+      "class": "bundle-ok",
+      "homepage": "https://github.com/project-copacetic/copacetic",
+      "binary": "copa",
+      "notes": "Patches OS-package CVEs in a container image from a Trivy report. Needs Docker/buildkit at run time. Used by `image-patch` (plan only; Maggie never runs it).",
+      "assets": {
+        "linux-amd64": {
+          "url": "https://github.com/project-copacetic/copacetic/releases/download/v0.15.0/copa_0.15.0_linux_amd64.tar.gz",
+          "sha256": "cff3fe9320f3bd24bafcfd0ce877ef57e23acad0836da0ac6c253919f71c9cad",
+          "archive": "tar.gz",
+          "member": "copa"
+        }
+      },
+      "required_flags": [],
+      "forbidden_flags": ["--push"]
+    },
     "dockle": {
       "version": "0.4.15",
       "licence": "Apache-2.0",
       "class": "bundle-ok",
       "homepage": "https://github.com/goodwithtech/dockle",
+      "binary": "dockle",
+      "assets": {
+        "linux-amd64": {
+          "url": "https://github.com/goodwithtech/dockle/releases/download/v0.4.15/dockle_0.4.15_Linux-64bit.tar.gz",
+          "sha256": "8bfc9183d1d3d67800edb45bea4bb63ddf1d28bec5f89944075a07007d79caad",
+          "archive": "tar.gz",
+          "member": "dockle"
+        }
+      },
       "required_flags": [],
       "forbidden_flags": []
     },
@@ -329,6 +357,7 @@
       "licence": "MIT",
       "class": "bundle-ok",
       "homepage": "https://github.com/perplexityai/bumblebee",
+      "notes": "Optional deferred preinstall engine; not bundled. Install it yourself if you want it; preinstall works without it.",
       "required_flags": [],
       "forbidden_flags": []
     },

package/bundled-tools/runtime/maggie_dash_pg.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""PostgreSQL backend for the MaggieDash content store.
+
+A thin compatibility shim that mimics the subset of the stdlib sqlite3
+connection API that MaggieDashStore uses, so the same store code runs on
+Postgres unchanged. It translates `?` placeholders to `%s`, intercepts the few
+SQLite-only statements (PRAGMA foreign_keys / table_info / user_version and
+`sqlite_master`), and returns rows that support both name and positional access
+plus `dict(row)` — exactly like `sqlite3.Row`.
+
+Used when a Postgres DSN is supplied (ONEMAN forbids SQLite anywhere); the
+SQLite path in MaggieDashStore is untouched. Requires psycopg2 (imported
+lazily, only when a Postgres backend is actually requested).
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Sequence
+
+
+class Row(dict):
+    """A dict that also supports positional access and `dict(row)`, like sqlite3.Row."""
+    __slots__ = ("_cols",)
+
+    def __init__(self, cols: Sequence[str], values: Sequence[Any]):
+        super().__init__(zip(cols, values))
+        self._cols = list(cols)
+
+    def __getitem__(self, key):
+        if isinstance(key, int):
+            return super().__getitem__(self._cols[key])
+        return super().__getitem__(key)
+
+
+class Result:
+    """Cursor-like result supporting fetchone/fetchall/iteration over Row objects."""
+    def __init__(self, rows: list[Row]):
+        self._rows = rows
+        self._idx = 0
+
+    def fetchone(self):
+        if self._idx < len(self._rows):
+            row = self._rows[self._idx]
+            self._idx += 1
+            return row
+        return None
+
+    def fetchall(self):
+        rows = self._rows[self._idx:]
+        self._idx = len(self._rows)
+        return rows
+
+    def __iter__(self):
+        rows = self._rows[self._idx:]
+        self._idx = len(self._rows)
+        return iter(rows)
+
+
+_PRAGMA_TABLE_INFO = re.compile(r"PRAGMA\s+table_info\s*\(\s*([^)]+?)\s*\)", re.IGNORECASE)
+_USER_VERSION_SET = re.compile(r"PRAGMA\s+user_version\s*=\s*(\d+)", re.IGNORECASE)
+
+
+class PgConnection:
+    """sqlite3.Connection-compatible shim backed by psycopg2."""
+    def __init__(self, dsn: str):
+        import psycopg2  # lazy: only when a Postgres backend is requested
+        self._conn = psycopg2.connect(dsn)
+        self._conn.autocommit = False
+
+    # -- the sqlite3.Connection surface MaggieDashStore relies on --
+    def execute(self, sql: str, params: Sequence[Any] | None = None) -> Result:
+        s = sql.strip()
+        up = s.upper()
+        if up.startswith("PRAGMA FOREIGN_KEYS"):
+            return Result([])
+        m = _PRAGMA_TABLE_INFO.search(s)
+        if m:
+            table = m.group(1).strip().strip('"').strip("'")
+            rows = self._run(
+                "SELECT column_name FROM information_schema.columns "
+                "WHERE table_schema='public' AND table_name=%s ORDER BY ordinal_position",
+                (table,))
+            # sqlite PRAGMA table_info columns: (cid, name, ...) -> row[1] is the name
+            return Result([Row(["cid", "name"], [i, r[0]]) for i, r in enumerate(rows)])
+        m = _USER_VERSION_SET.search(s)
+        if m:
+            self._run("CREATE TABLE IF NOT EXISTS maggiedash_meta (key TEXT PRIMARY KEY, value TEXT)")
+            self._run("INSERT INTO maggiedash_meta (key,value) VALUES ('user_version',%s) "
+                      "ON CONFLICT (key) DO UPDATE SET value=EXCLUDED.value", (str(m.group(1)),))
+            return Result([])
+        if "FROM SQLITE_MASTER" in up:
+            rows = self._run("SELECT table_name FROM information_schema.tables WHERE table_schema='public'")
+            return Result([Row(["name"], [r[0]]) for r in rows])
+        # ordinary statement: translate placeholders and run
+        query = s.replace("?", "%s")
+        cur = self._conn.cursor()
+        try:
+            cur.execute(query, tuple(params) if params else None)
+            if cur.description is None:
+                return Result([])
+            cols = [d[0] for d in cur.description]
+            return Result([Row(cols, rec) for rec in cur.fetchall()])
+        finally:
+            cur.close()
+
+    def executescript(self, script: str) -> None:
+        cur = self._conn.cursor()
+        try:
+            cur.execute(script)        # psycopg2 runs multiple ';'-separated statements
+        finally:
+            cur.close()
+
+    def _run(self, query: str, params: Sequence[Any] | None = None) -> list[tuple]:
+        cur = self._conn.cursor()
+        try:
+            cur.execute(query, tuple(params) if params else None)
+            return cur.fetchall() if cur.description is not None else []
+        finally:
+            cur.close()
+
+    def commit(self) -> None:
+        self._conn.commit()
+
+    def close(self) -> None:
+        if not self._conn.closed:
+            self._conn.close()

package/bundled-tools/runtime/maggie_dash_store.py

@@ -38,11 +38,23 @@ def checksum(value: dict[str, Any]) -> str:
 
 
 class MaggieDashStore:
-    def __init__(self, path: Path):
-        self.path = path.resolve()
-        self.path.parent.mkdir(parents=True, exist_ok=True)
-        self.connection = sqlite3.connect(self.path)
-        self.connection.row_factory = sqlite3.Row
+    def __init__(self, path: Path | None = None, *, dsn: str | None = None):
+        # Postgres backend (ONEMAN forbids SQLite) when a DSN is supplied;
+        # otherwise the stdlib SQLite backend, unchanged.
+        if dsn:
+            from maggie_dash_pg import PgConnection
+            self.backend = "postgres"
+            self.path = dsn
+            # Never expose credentials in contracts/reports/CLI output.
+            self.storage_label = "env:MAGGIEDASH_DATABASE_URL"
+            self.connection = PgConnection(dsn)
+        else:
+            self.backend = "sqlite"
+            self.path = path.resolve()
+            self.storage_label = str(self.path)
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.connection = sqlite3.connect(self.path)
+            self.connection.row_factory = sqlite3.Row
         self.connection.execute("PRAGMA foreign_keys = ON")
         self.connection.executescript(
             """