@topy-ai/maggie 0.7.54 → 0.7.55

package/bundled-tools/clis/maggie_social_share.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import argparse
 import json
 import sys
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from urllib.error import HTTPError, URLError
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
@@ -169,6 +169,96 @@ def picture_groups(value: dict) -> dict:
     return {"valid": not errors, "errors": errors, "ideas": report}
 
 
+REUSE_DAYS = 30
+SHARED_STATUSES = {"approved", "scheduled", "publishing", "published"}
+OPEN_STATUSES = {"draft", "queued", "held", "needs_review", "pending"}
+
+
+def article_key(item: dict) -> str:
+    """The article a post shares: its source id, else its address without tracking parameters."""
+    if item.get("source_content_id"):
+        return "id:" + str(item["source_content_id"])
+    url = str(item.get("canonical_url") or item.get("url") or "")
+    parts = urlsplit(url)
+    query = urlencode([(key, value) for key, value in parse_qsl(parts.query) if not key.startswith("utm_")])
+    return "url:" + urlunsplit((parts.scheme, parts.netloc.lower().removeprefix("www."), parts.path.rstrip("/"), query, ""))
+
+
+def shared_on(history: list[dict], now: datetime, days: int = REUSE_DAYS) -> dict[str, dict[str, str]]:
+    """Article key -> {channel: last shared instant} within the rolling window."""
+    used: dict[str, dict[str, str]] = {}
+    for post in history:
+        if post.get("status", "published") not in SHARED_STATUSES:
+            continue
+        stamp = post.get("posted_at") or post.get("published_at") or post.get("scheduled_at")
+        if not stamp or not post.get("channel"):
+            continue
+        when = parse_instant(stamp, "history posted_at")
+        if (now - when).total_seconds() > days * 86400 or when > now + timedelta(days=days):
+            continue
+        channels = used.setdefault(article_key(post), {})
+        channel = str(post["channel"])
+        channels[channel] = max(channels.get(channel, ""), stamp)
+    return used
+
+
+def sources_used_on(document: dict, now: datetime) -> dict:
+    """Each article with the channels it was shared to in the last 30 days (rolling)."""
+    used = shared_on(document.get("history") or [], now, int(document.get("reuse_days") or REUSE_DAYS))
+    articles = []
+    for article in document.get("articles") or []:
+        channels = used.get(article_key(article), {})
+        articles.append({**article, "used_on": sorted(channels), "last_shared": channels})
+    return {"valid": True, "reuse_days": int(document.get("reuse_days") or REUSE_DAYS), "articles": articles}
+
+
+def queue_check(document: dict, now: datetime) -> dict:
+    """What an automatic run and "Approve all" may do with the open posts.
+
+    * reuse is per channel: an article shared on a channel in the last 30 days
+      (rolling) is not shared there again — other channels are free;
+    * every new post carries a picture;
+    * in auto mode a hold raised only by optional checks does not block a post;
+      a failing required check always does;
+    * "Approve all" covers every open post, held ones included.
+    """
+    mode = str(document.get("approval_mode") or "manual")
+    if mode not in {"auto", "manual"}:
+        raise ValueError("approval_mode must be auto or manual")
+    days = int(document.get("reuse_days") or REUSE_DAYS)
+    used = shared_on(document.get("history") or [], now, days)
+    planned: dict[tuple[str, str], str] = {}
+    posts, approve_all, blocked = [], [], []
+    for post in document.get("posts") or []:
+        if post.get("status", "draft") not in OPEN_STATUSES:
+            continue
+        pid, channel, key = str(post.get("id")), str(post.get("channel") or ""), article_key(post)
+        reasons, notes = [], []
+        last = used.get(key, {}).get(channel)
+        if last:
+            reasons.append(f"this article was shared on {channel} at {last}, within {days} days")
+        elif (channel, key) in planned:
+            reasons.append(f"post {planned[(channel, key)]} already shares this article on {channel}")
+        planned.setdefault((channel, key), pid)
+        if not post.get("image_url"):
+            reasons.append("needs a picture: every new post carries one (use the picture of its idea)")
+        for hold in post.get("holds") or []:
+            name = str(hold.get("check") or hold.get("reason") or "check")
+            if hold.get("required"):
+                reasons.append(f"required check failed: {name}")
+            elif mode == "auto":
+                notes.append(f"optional check {name} does not hold the post in auto mode")
+            else:
+                notes.append(f"held for review by optional check {name}; Approve all includes it")
+        held = bool(post.get("holds")) or post.get("status") in {"held", "needs_review"}
+        entry = {"id": pid, "channel": channel, "held": held, "blocked": bool(reasons), "reasons": reasons, "notes": notes}
+        if mode == "auto":
+            entry["auto_publish"] = not reasons
+        posts.append(entry)
+        (blocked if reasons else approve_all).append(pid)
+    return {"valid": not blocked, "approval_mode": mode, "reuse_days": days, "approve_all": approve_all, "blocked": blocked, "posts": posts}
+
+
 def validate(value: dict) -> list[str]:
     errors = [f"missing {key}" for key in REQUIRED if not value.get(key)]
     if value.get("status") not in {"draft", "approved", "scheduled", "publishing", "published", "failed", "cancelled"}:
@@ -220,6 +310,12 @@ def main() -> int:
     links.add_argument("input", help="JSON: a list of URLs or article objects with canonical_url, or {\"articles\": [...]}")
     links.add_argument("--cache", default=".maggie/social-link-cache.json", help="verdict cache (default: .maggie/social-link-cache.json); 'none' disables it")
     links.add_argument("--ttl-hours", type=float, default=6.0)
+    used_on = sub.add_parser("used-on", help="list, per article, the channels it was shared to in the last 30 days (rolling)")
+    used_on.add_argument("input", help='JSON: {"articles": [...], "history": [{"channel", "source_content_id"|"canonical_url", "posted_at", "status"}]}')
+    used_on.add_argument("--now")
+    qcheck = sub.add_parser("queue-check", help="decide what auto mode and Approve all may do: per-channel 30-day reuse, a picture on every post, optional holds")
+    qcheck.add_argument("input", help='JSON: {"approval_mode": "auto"|"manual", "posts": [...], "history": [...]}')
+    qcheck.add_argument("--now")
     check = sub.add_parser("validate", help="validate a draft channel contract")
     check.add_argument("input")
     adapters = sub.add_parser("adapters", help="check canonical OAuth scope sets and shared OAuth clients")
@@ -258,6 +354,10 @@ def main() -> int:
             result = validate_adapters(value)
         elif args.command == "connections":
             result = connection_health(value, parse_instant(args.now, "--now") if args.now else now)
+        elif args.command == "used-on":
+            result = sources_used_on(value, parse_instant(args.now, "--now") if args.now else now)
+        elif args.command == "queue-check":
+            result = queue_check(value, parse_instant(args.now, "--now") if args.now else now)
         elif args.command == "pictures":
             result = picture_groups(value if isinstance(value, dict) else {"drafts": value})
         elif args.command == "reconcile":

package/bundled-tools/clis/maggie_version_sources.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Check that every version source of a package agrees, and that generated data is current.
+
+A packager that writes its own version constant over a hand-bumped manifest
+(or the reverse) ships one version in one place and another elsewhere; a site
+built from generated data that was not regenerated then fails to deploy. This
+check never writes a version: it reads each source and refuses on a mismatch.
+
+Sources:
+  FILE             a plain VERSION file (first line)
+  FILE:dotted.key  a JSON value, e.g. package.json:version or manifest.json:meta.version
+  FILE~NAME        a code constant NAME = "x.y.z" / NAME: "x.y.z" / export const NAME = 'x.y.z'
+
+Generated data:
+  --generated OUT --command "node scripts/gen.mjs {out}"
+  runs the generator into a temporary file ({out}) and fails when OUT differs.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shlex
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def read_source(root: Path, spec: str) -> str:
+    if "~" in spec:
+        name, constant = spec.split("~", 1)
+        text = (root / name).read_text(encoding="utf-8")
+        match = re.search(rf"\b{re.escape(constant)}\b\s*[:=]\s*['\"]([^'\"]+)['\"]", text)
+        if not match:
+            raise ValueError(f"{spec}: constant {constant} not found")
+        return match.group(1)
+    if ":" in spec and not re.match(r"^[A-Za-z]:[\\/]", spec):
+        name, dotted = spec.split(":", 1)
+        value: object = json.loads((root / name).read_text(encoding="utf-8"))
+        for key in dotted.split("."):
+            if not isinstance(value, dict) or key not in value:
+                raise ValueError(f"{spec}: key {dotted} not found")
+            value = value[key]
+        return str(value)
+    return (root / spec).read_text(encoding="utf-8").splitlines()[0].strip()
+
+
+def check_generated(root: Path, output: str, command: str) -> dict:
+    with tempfile.TemporaryDirectory() as directory:
+        fresh = Path(directory) / Path(output).name
+        argv = [part.replace("{out}", str(fresh)) for part in shlex.split(command)]
+        completed = subprocess.run(argv, cwd=root, capture_output=True, text=True, check=False)
+        if completed.returncode:
+            return {"file": output, "current": False, "error": f"generator exited {completed.returncode}: {(completed.stderr or completed.stdout).strip()[-300:]}"}
+        if not fresh.is_file():
+            return {"file": output, "current": False, "error": "generator did not write {out}"}
+        current = (root / output).is_file() and (root / output).read_bytes() == fresh.read_bytes()
+        return {"file": output, "current": current, **({} if current else {"error": "out of date: regenerate and commit it before deploying"})}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0], formatter_class=argparse.RawDescriptionHelpFormatter, epilog="\n".join(__doc__.splitlines()[2:]))
+    parser.add_argument("command", choices=["check"])
+    parser.add_argument("--project", default=".")
+    parser.add_argument("--source", action="append", default=[], required=True, help="a version source (repeat; the first is the one to follow)")
+    parser.add_argument("--generated", action="append", default=[], help="generated file that must be current")
+    parser.add_argument("--generator", action="append", default=[], help="command that writes the matching --generated file to {out}")
+    args = parser.parse_args()
+    root = Path(args.project).resolve()
+    errors: list[str] = []
+    versions: dict[str, str | None] = {}
+    for spec in args.source:
+        try:
+            versions[spec] = read_source(root, spec)
+        except (OSError, ValueError, json.JSONDecodeError, IndexError) as error:
+            versions[spec] = None
+            errors.append(str(error))
+    found = {value for value in versions.values() if value}
+    if len(found) > 1:
+        first = versions[args.source[0]]
+        errors.extend(f"{spec} is {value}; {args.source[0]} is {first}" for spec, value in versions.items() if value and value != first)
+    if len(args.generated) != len(args.generator):
+        errors.append("give one --generator per --generated file")
+    generated = [check_generated(root, output, command) for output, command in zip(args.generated, args.generator)]
+    errors.extend(f"{item['file']}: {item['error']}" for item in generated if not item["current"])
+    result = {"valid": not errors, "version": versions.get(args.source[0]) if not errors else None, "sources": versions, "generated": generated, "errors": errors}
+    print(json.dumps(result, indent=2))
+    return 0 if result["valid"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/integrations/maggie-api-pull.md

@@ -89,13 +89,40 @@ back to an older stored URL, which after a platform move answers 404. So:
    `maggie blog live-urls match --sitemap https://example.com/sitemap.xml --write --report-body .maggie/live-urls-report.json`,
    then send that body with `maggie api report-state --body-file … --execute`.
 
-Matching is **additive**: a post that already has a live URL keeps it, and a
+Every post without a live URL is a candidate, including one already tracked
+with an empty value; when the record has no slug, the last path segment of its
+delivered address is used. Matching is **additive**: a post that already has a live URL keeps it, and a
 post this run did not find is left as it was — never marked unmatched — so the
 match can run daily without retiring earlier matches. When translated copies
 share the slug (`/blog/x`, `/zh-hans/blog/x`), the URL **without a locale
 segment** wins. The same two rules apply to the platform's own sitemap
 matching for API Pull destinations.
 
+## Rewrites on pull sites
+
+A pull site receives rewrites the same way it receives posts: `GET /updates`
+on the same schedule as `/posts` (one rewrite per call, charged like a post;
+the answer is `{delivered, updates: [...]}`). Without this path a rewrite
+requested for a pulled post never reaches the site. Each rewrite is applied to
+the post it is for, never stored as a new post:
+
+1. Find the post by `source_content_id` (the id `/posts` delivered it under),
+   else by its slug or address, previous slugs included.
+2. Replace only the body. Title, slug, status, topics and the live URL stay as
+   the site has them.
+3. Keep the replaced body (and its checksum) so the rewrite can be undone.
+4. A rewrite with `publication_status: "draft"` is held for review, and one
+   with no matching post here is kept as `unmatched`; neither is applied.
+5. Translations of a rewritten post are stale: queue them again.
+6. Report the outcome with `POST /content-tracking/report-state`.
+
+`maggie api lifecycle --execute --allow-quota --pull-updates` does steps 1, 2,
+4 locally: the rewrite lands on the original record in
+`.maggie/ai-cmo-lifecycle.json` (`rewrite_pending`, a `rewrites` history with
+the previous checksum), held ones are listed without changing the body, and
+unmatched ones go to `rewrites_unmatched`. A later `/posts` re-delivery keeps
+the record's live URL and rewrite history.
+
 ## Project context synchronization
 
 `GET /project-context` returns sanitized, read-only context scoped by the API

package/package.json

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