@topy-ai/maggie 0.7.53 → 0.7.55

package/bundled-tools/clis/maggie_ops_routines.py

@@ -0,0 +1,352 @@
+#!/usr/bin/env python3
+"""Check an agents repository's routines.json and build the admin sync payload.
+
+A routine is a scheduled agent run (Claude Routines, Codex Automations). The
+agents repository keeps one `routines.json` plus the skills the routines run
+(`.claude/skills/<name>/SKILL.md` or `skills/<name>/SKILL.md`). This module is
+offline: it reads files, never calls an agent platform or the host.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+SCHEMA = "maggie-agent-routines.v1"
+SLUG = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
+# Claude Routines runs per day by plan at the time of writing; check the current limits.
+PLAN_CAPS = {"pro": 5, "max": 15, "team": 25, "enterprise": 25}
+DAYS = ("mon", "tue", "wed", "thu", "fri", "sat", "sun")
+DAY_NAMES = {name: index for index, name in enumerate(DAYS)} | {
+    "monday": 0, "tuesday": 1, "wednesday": 2, "thursday": 3, "friday": 4, "saturday": 5, "sunday": 6,
+}
+# Writes a routine should hold only when the owner named them with a number.
+PUBLIC_WORDS = ("publish", "approve", "reply", "delete", "send", "remove", "revoke", "pay")
+# A routine starting this many minutes before, or this many after, a server job collides with it.
+BEFORE_WINDOW = 30
+AFTER_WINDOW = 10
+
+
+def parse_time(value: str) -> int:
+    match = re.fullmatch(r"(\d{1,2}):(\d{2})", value.strip())
+    if not match or int(match.group(1)) > 23 or int(match.group(2)) > 59:
+        raise ValueError(f"time must be HH:MM: {value!r}")
+    return int(match.group(1)) * 60 + int(match.group(2))
+
+
+def parse_days(value) -> set[int]:
+    if value in (None, "", "daily", "*", "every day"):
+        return set(range(7))
+    if value == "weekdays":
+        return set(range(5))
+    if value == "weekends":
+        return {5, 6}
+    items = value if isinstance(value, list) else re.split(r"[,\s]+", str(value).strip().lower())
+    days: set[int] = set()
+    for item in items:
+        item = str(item).strip().lower()
+        if not item:
+            continue
+        if item not in DAY_NAMES:
+            raise ValueError(f"unknown day: {item!r}")
+        days.add(DAY_NAMES[item])
+    return days
+
+
+def cron_field(value: str, low: int, high: int) -> list[int] | None:
+    """Expand one cron field of plain numbers, lists and ranges; None for anything else."""
+    if value == "*":
+        return list(range(low, high + 1))
+    out: list[int] = []
+    for part in value.split(","):
+        if re.fullmatch(r"\d+", part):
+            out.append(int(part))
+        elif re.fullmatch(r"\d+-\d+", part):
+            start, end = (int(x) for x in part.split("-"))
+            out.extend(range(start, end + 1))
+        elif re.fullmatch(r"\*/\d+", part):
+            out.extend(range(low, high + 1, int(part[2:])))
+        else:
+            return None
+    return out if all(low <= item <= high for item in out) else None
+
+
+def parse_schedule(text: str) -> tuple[set[int], list[int]] | None:
+    """(days 0=Mon..6=Sun, start minutes of the day) or None when not machine-readable.
+
+    Accepts a 5-field cron expression or `daily|weekdays|weekends|<days> HH:MM[,HH:MM]`.
+    """
+    text = (text or "").strip()
+    if not text:
+        return None
+    fields = text.split()
+    if len(fields) == 5 and not re.search(r"[a-z]{4,}", fields[0].lower()):
+        minutes = cron_field(fields[0], 0, 59)
+        hours = cron_field(fields[1], 0, 23)
+        if minutes is None or hours is None or fields[2] != "*" or fields[3] != "*":
+            return None
+        dow = fields[4].lower()
+        if dow == "*":
+            days = set(range(7))
+        else:
+            named = [DAY_NAMES.get(part) for part in re.split(r"[,]", dow)] if re.search(r"[a-z]", dow) else None
+            if named is not None:
+                if None in named:
+                    return None
+                days = set(named)  # type: ignore[arg-type]
+            else:
+                numbers = cron_field(dow, 0, 7)
+                if numbers is None:
+                    return None
+                days = {(number - 1) % 7 for number in numbers}  # cron 0/7 = Sunday, 1 = Monday
+        return days, sorted({hour * 60 + minute for hour in hours for minute in minutes})
+    lowered = text.lower()
+    if lowered.startswith("hourly") or lowered.startswith("every hour"):
+        return set(range(7)), list(range(0, 24 * 60, 60))
+    match = re.fullmatch(r"(?:(daily|weekdays|weekends|every day|[a-z,\s]+?)\s+)?(?:at\s+)?((?:\d{1,2}:\d{2})(?:\s*,\s*\d{1,2}:\d{2})*)", lowered)
+    if not match:
+        return None
+    try:
+        days = parse_days((match.group(1) or "daily").strip())
+        times = sorted(parse_time(item) for item in match.group(2).split(","))
+    except ValueError:
+        return None
+    return days, times
+
+
+def clock(minutes: int) -> str:
+    return f"{minutes // 60:02d}:{minutes % 60:02d}"
+
+
+def find_skill(repo: Path, name: str) -> Path | None:
+    for candidate in (repo / ".claude" / "skills" / name / "SKILL.md", repo / "skills" / name / "SKILL.md"):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def routine_mode_section(text: str) -> str:
+    match = re.search(r"^#{2,3}\s+Routine mode\b.*?(?=^#{1,2}\s|\Z)", text, re.M | re.S | re.I)
+    return match.group(0) if match else ""
+
+
+def load_server_jobs(path: Path | None) -> list[dict]:
+    if path is None:
+        return []
+    data = json.loads(path.read_text(encoding="utf-8"))
+    jobs = data.get("jobs", []) if isinstance(data, dict) else data
+    out = []
+    for job in jobs:
+        if "at" not in job:
+            raise ValueError(f"server job {job!r} needs at: HH:MM")
+        out.append({"job": str(job.get("job") or job.get("id") or "job"), "at": parse_time(str(job["at"])), "days": parse_days(job.get("days", "daily"))})
+    return out
+
+
+def check_routines(path: Path, server_jobs: list[dict] | None = None, plan: str | None = None) -> dict:
+    repo = path.parent
+    data = json.loads(path.read_text(encoding="utf-8"))
+    errors: list[str] = []
+    warnings: list[str] = []
+    if not isinstance(data, dict):
+        raise ValueError("routines.json must be an object")
+    if data.get("schemaVersion") not in (None, SCHEMA):
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    connectors = data.get("connectors") or {}
+    if not isinstance(connectors, dict):
+        errors.append("connectors must be an object keyed by connector id")
+        connectors = {}
+    for cid, connector in connectors.items():
+        if not SLUG.match(cid):
+            errors.append(f"connector id {cid!r} must be a lowercase slug")
+        if not str((connector or {}).get("url", "")).startswith("https://"):
+            errors.append(f"connector {cid}: url must be https://")
+    routines = data.get("routines")
+    if not isinstance(routines, list) or not routines:
+        errors.append("routines must be a non-empty list")
+        routines = []
+    if len(routines) > 50:
+        errors.append("at most 50 routines")
+    seen: set[str] = set()
+    per_day = [0] * 7
+    summary = []
+    for routine in routines:
+        rid = str(routine.get("id", ""))
+        label = rid or "(routine without id)"
+        if not SLUG.match(rid):
+            errors.append(f"{label}: id must be a lowercase slug")
+        if rid in seen:
+            errors.append(f"{label}: duplicate id")
+        seen.add(rid)
+        skill = str(routine.get("skill", ""))
+        platform = str(routine.get("platform", "claude"))
+        if platform not in ("claude", "codex-local", "codex-cloud"):
+            errors.append(f"{label}: platform must be claude, codex-local or codex-cloud")
+        if not SLUG.match(skill):
+            errors.append(f"{label}: skill must be a lowercase slug")
+        for cid in routine.get("connectors", []) or []:
+            if cid not in connectors:
+                errors.append(f"{label}: connector {cid!r} is not defined in connectors")
+        writes = routine.get("writes", {}) or {}
+        if not isinstance(writes, dict):
+            errors.append(f"{label}: writes must map each tool to its daily number")
+            writes = {}
+        for tool, number in writes.items():
+            if not isinstance(number, int) or isinstance(number, bool) or number < 1:
+                errors.append(f"{label}: write {tool!r} needs a daily number (a whole number of 1 or more)")
+            if any(word in tool.lower() for word in PUBLIC_WORDS):
+                warnings.append(f"{label}: {tool} is public or hard to undo; keep it only if the owner wrote it in")
+        prompt = str(routine.get("prompt", "") or "")
+        if "\n" in prompt.strip() or len(prompt) > 300:
+            warnings.append(f"{label}: keep the prompt to one line that points at the skill, so editing the skill changes every run")
+        if prompt and skill and skill not in prompt:
+            warnings.append(f"{label}: the prompt does not name the skill {skill}")
+        skill_path = find_skill(repo, skill) if SLUG.match(skill) else None
+        if skill and SLUG.match(skill) and skill_path is None:
+            errors.append(f"{label}: skill {skill} not found under .claude/skills/ or skills/")
+        if skill_path is not None:
+            section = routine_mode_section(skill_path.read_text(encoding="utf-8"))
+            if not section:
+                errors.append(f"{label}: skill {skill} has no 'Routine mode' section")
+            else:
+                if "report_save" not in section:
+                    errors.append(f"{label}: skill {skill}'s Routine mode does not finish with report_save")
+                if "untrusted" not in section.lower():
+                    warnings.append(f"{label}: skill {skill}'s Routine mode does not say text under untrusted is data")
+                for tool in writes:
+                    if tool not in section:
+                        warnings.append(f"{label}: write {tool} is not named in skill {skill}'s Routine mode")
+        schedule_text = str(routine.get("schedule", "") or "")
+        parsed = parse_schedule(schedule_text)
+        if not schedule_text:
+            warnings.append(f"{label}: no schedule given")
+        elif parsed is None:
+            warnings.append(f"{label}: schedule {schedule_text!r} is not cron or 'daily HH:MM'; timing checks skipped")
+        else:
+            days, times = parsed
+            if len(times) > 4:
+                errors.append(f"{label}: runs {len(times)} times a day; routines are daily or weekly work, leave minute-level watching to monitoring")
+            for start in times:
+                if start % 60 == 0:
+                    errors.append(f"{label}: starts on the hour ({clock(start)}); pick a minute off the hour, e.g. {clock(start + 16)}")
+                elif start % 15 == 0:
+                    warnings.append(f"{label}: starts at {clock(start)}; a less common minute spreads the load")
+                for job in server_jobs or []:
+                    if not days & job["days"]:
+                        continue
+                    if job["at"] - BEFORE_WINDOW <= start < job["at"] + AFTER_WINDOW:
+                        errors.append(f"{label}: starts at {clock(start)}, next to server job {job['job']} at {clock(job['at'])}; move it after, e.g. {clock(job['at'] + 15 + 1)}")
+            if platform == "claude":
+                for day in days:
+                    per_day[day] += len(times)
+        summary.append({"id": rid, "skill": skill, "platform": platform, "schedule": schedule_text, "writes": writes})
+    busiest = max(per_day) if routines else 0
+    if plan:
+        cap = PLAN_CAPS[plan]
+        if busiest > cap:
+            errors.append(f"Claude routines run {busiest} times on the busiest day; the {plan} plan allows {cap} a day (at the time of writing)")
+        elif busiest == cap:
+            warnings.append(f"Claude routines use all {cap} daily runs of the {plan} plan; a manual run that day has no room")
+    return {
+        "schemaVersion": "maggie-ops-routines-check.v1",
+        "routinesFile": str(path),
+        "passed": not errors,
+        "routines": summary,
+        "claudeRunsPerDay": dict(zip(DAYS, per_day)),
+        "plan": plan,
+        "planCap": PLAN_CAPS.get(plan or ""),
+        "errors": errors,
+        "warnings": warnings,
+    }
+
+
+def frontmatter_description(text: str) -> str:
+    match = re.match(r"^---\n(.*?)\n---", text, re.S)
+    if not match:
+        return ""
+    found = re.search(r"^description:\s*(.+)$", match.group(1), re.M)
+    return found.group(1).strip().strip("\"'") if found else ""
+
+
+def build_payload(path: Path, repo_name: str, commit: str | None = None) -> dict:
+    """The body the admin's routines sync endpoint takes: repo, commit, connectors, routines, skills."""
+    repo = path.parent
+    if not re.fullmatch(r"[\w.-]+/[\w.-]+", repo_name):
+        raise ValueError("--repo must be owner/name")
+    if commit is None:
+        completed = subprocess.run(["git", "-C", str(repo), "rev-parse", "HEAD"], capture_output=True, text=True, check=False)
+        if completed.returncode:
+            raise ValueError("not a git repository; pass --commit")
+        commit = completed.stdout.strip()
+    if not re.fullmatch(r"[0-9a-f]{7,40}", commit):
+        raise ValueError("commit must be a git sha")
+    data = json.loads(path.read_text(encoding="utf-8"))
+    routines = []
+    skills = []
+    for routine in data.get("routines", []):
+        skill = routine.get("skill", "")
+        routines.append({key: routine[key] for key in ("id", "name", "skill", "schedule", "connectors", "prompt") if key in routine})
+        skill_path = find_skill(repo, skill)
+        if skill_path is not None and skill not in {item["name"] for item in skills}:
+            body = skill_path.read_text(encoding="utf-8")
+            skills.append({"name": skill, "description": frontmatter_description(body), "body": body})
+    return {"repo": repo_name, "commit": commit, "connectors": data.get("connectors", {}), "routines": routines, "skills": skills}
+
+
+def command_check(args: argparse.Namespace) -> int:
+    jobs = load_server_jobs(Path(args.server_jobs)) if args.server_jobs else []
+    result = check_routines(Path(args.file), jobs, args.plan)
+    text = json.dumps(result, indent=2, ensure_ascii=False)
+    if args.output:
+        Path(args.output).write_text(text + "\n", encoding="utf-8")
+    print(text)
+    return 0 if result["passed"] else 1
+
+
+def command_payload(args: argparse.Namespace) -> int:
+    result = check_routines(Path(args.file))
+    if not result["passed"]:
+        print(json.dumps({"passed": False, "errors": result["errors"]}, indent=2), file=sys.stderr)
+        return 1
+    payload = build_payload(Path(args.file), args.repo, args.commit)
+    text = json.dumps(payload, ensure_ascii=False)
+    if args.output:
+        Path(args.output).write_text(text + "\n", encoding="utf-8")
+        print(json.dumps({"passed": True, "output": args.output, "routines": len(payload["routines"]), "skills": len(payload["skills"])}))
+    else:
+        print(text)
+    return 0
+
+
+def add_parsers(sub) -> None:
+    check = sub.add_parser("routines-check", help="check an agents repository's routines.json (schedule, plan cap, writes, Routine mode)")
+    check.add_argument("file", help="routines.json at the agents repository root")
+    check.add_argument("--server-jobs", help="JSON list of the server's own jobs: [{job, at: HH:MM, days}]")
+    check.add_argument("--plan", choices=sorted(PLAN_CAPS), help="Claude plan whose daily routine runs to check against")
+    check.add_argument("--output")
+    check.set_defaults(func=command_check)
+    payload = sub.add_parser("routines-payload", help="build the admin sync body (repo, commit, connectors, routines, skills)")
+    payload.add_argument("file")
+    payload.add_argument("--repo", required=True, help="owner/name of the agents repository")
+    payload.add_argument("--commit", help="commit sha (default: git HEAD of the repository)")
+    payload.add_argument("--output")
+    payload.set_defaults(func=command_payload)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    add_parsers(parser.add_subparsers(dest="command", required=True))
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (OSError, ValueError, KeyError, json.JSONDecodeError, subprocess.CalledProcessError) as error:
+        parser.error(str(error))
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_product_release.py

@@ -27,6 +27,7 @@ import json
 import re
 import shutil
 import subprocess
+import time
 import sys
 import tempfile
 from datetime import date, datetime, timezone
@@ -264,6 +265,44 @@ def review_status(reviews_path: Path, package_version: str | None, chatgpt_plugi
     return {"schemaVersion": "maggie-product-review-status.v1", "passed": not errors, "reviews": rows, "errors": errors, "warnings": warnings}
 
 
+STAGED_ERROR = re.compile(r"cannot publish over (?:the )?previously (?:staged|published) version", re.I)
+
+
+def npm_view(package: str, npm_bin: str) -> dict:
+    completed = subprocess.run([npm_bin, "view", package, "dist-tags", "versions", "--json"], capture_output=True, text=True, check=False, timeout=60)
+    if completed.returncode:
+        return {}
+    try:
+        value = json.loads(completed.stdout or "{}")
+    except json.JSONDecodeError:
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def published(package: str, version: str, tag: str, wait: int, interval: float, publish_log: Path | None, view=None, sleep=time.sleep) -> dict:
+    """Wait until `version` is the registry's `tag` (latest). A staged publish can lag for minutes."""
+    npm_bin = shutil.which("npm") or "npm"
+    view = view or (lambda: npm_view(package, npm_bin))
+    log_says_staged = bool(publish_log and publish_log.is_file() and STAGED_ERROR.search(publish_log.read_text(encoding="utf-8", errors="replace")))
+    deadline = time.monotonic() + wait
+    checks = 0
+    while True:
+        checks += 1
+        data = view()
+        tags = data.get("dist-tags") or {}
+        versions = data.get("versions") or []
+        listed = version in (versions if isinstance(versions, list) else [versions])
+        current = tags.get(tag)
+        if current == version:
+            return {"passed": True, "package": package, "version": version, "tag": tag, "state": "live", "checks": checks,
+                    "note": "the earlier publish attempt was already accepted (staged), not a failure" if log_says_staged else None}
+        if time.monotonic() >= deadline:
+            state = "staged" if listed or log_says_staged else "missing"
+            return {"passed": False, "package": package, "version": version, "tag": tag, "state": state, "registryTag": current, "checks": checks,
+                    "note": "still propagating: check again before reporting it" if state == "staged" else "not on the registry: the publish did not happen"}
+        sleep(interval)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="maggie product", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     sub = parser.add_subparsers(dest="command", required=True)
@@ -281,9 +320,18 @@ def main(argv: list[str] | None = None) -> int:
     review.add_argument("--reviews", type=Path, required=True, help="maggie-product-reviews.v1 JSON")
     review.add_argument("--package", type=Path)
     review.add_argument("--chatgpt-plugin", type=Path, help="ChatGPT app plugin.json with review.test_cases")
+    pub = sub.add_parser("published", help="wait until a just-published version is the registry's latest (staged publishes lag)")
+    pub.add_argument("--package-name", required=True)
+    pub.add_argument("--version", required=True)
+    pub.add_argument("--tag", default="latest")
+    pub.add_argument("--wait", type=int, default=600, help="seconds to keep checking (default 600)")
+    pub.add_argument("--interval", type=float, default=20)
+    pub.add_argument("--publish-log", type=Path, help="output of the publish command; 'Cannot publish over previously staged version' means it was already accepted")
     args = parser.parse_args(argv)
     try:
-        if args.command == "release-check":
+        if args.command == "published":
+            report = published(args.package_name, args.version, args.tag, args.wait, args.interval, args.publish_log)
+        elif args.command == "release-check":
             report = release_check(args.package.resolve(), args.server_json, args.changelog, args.pack)
         elif args.command == "smoke":
             report = smoke(args.package.resolve(), args.timeout)

package/bundled-tools/clis/maggie_query_ideas.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Turn Search Console queries into topic ideas, without the ones that are not topics.
+
+Input rows are Search Console query rows (``query``, ``position``,
+``impressions``, ``clicks``). A query becomes an idea only when it is a real
+topic the site does not cover yet:
+
+* never from search operators (``site:example.com``, ``inurl:``, ``"..."``-only,
+  ``-term``), bare domains or URLs, or the brand name on its own (optionally
+  with the domain or a TLD);
+* covered when its words — singular and plural forms treated alike — are all in
+  an existing post title or keyword, or in a waiting idea;
+* short real words are kept (``seo``, ``crm``, ``ux``): only one-character
+  tokens and numbers alone are dropped as noise;
+* "striking distance" by default: positions 4–15 with at least 10 impressions,
+  at most 5 new ideas per run.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+OPERATOR = re.compile(r"(?:^|\s)-?(?:site|inurl|intitle|intext|allinurl|allintitle|filetype|ext|related|cache|info|link|define|before|after|source):", re.I)
+DOMAIN = re.compile(r"^(?:https?://)?(?:www\.)?[a-z0-9-]+(?:\.[a-z0-9-]+)*\.[a-z]{2,}(?:/\S*)?$", re.I)
+URL_PART = re.compile(r"https?://|www\.|\b[a-z0-9-]+\.(?:com|net|org|io|co|uk|so|ai|app|dev|xyz)\b", re.I)
+TLDS = {"com", "net", "org", "io", "co", "uk", "so", "ai", "app", "dev", "xyz", "www"}
+WORD = re.compile(r"[^\W_]+", re.UNICODE)
+
+
+def singular(word: str) -> str:
+    if len(word) > 4 and word.endswith("ies"):
+        return word[:-3] + "y"
+    if len(word) > 4 and word.endswith(("ses", "xes", "zes", "ches", "shes")):
+        return word[:-2]
+    if len(word) > 3 and word.endswith("s") and not word.endswith(("ss", "us", "is")):
+        return word[:-1]
+    return word
+
+
+def words(text: str) -> list[str]:
+    return [singular(word) for word in WORD.findall(text.lower())]
+
+
+def brand_tokens(brands: list[str]) -> set[str]:
+    tokens: set[str] = set()
+    for brand in brands:
+        tokens.update(words(brand))
+        tokens.add(re.sub(r"[^a-z0-9]", "", brand.lower()))
+    tokens.discard("")
+    return tokens
+
+
+def reject_reason(query: str, brands: set[str]) -> str | None:
+    text = " ".join(query.split())
+    if not text:
+        return "empty"
+    if OPERATOR.search(text) or text.startswith("-") or re.fullmatch(r'"[^"]*"', text):
+        return "search-operator"
+    if DOMAIN.match(text) or URL_PART.search(text):
+        return "domain-or-url"
+    tokens = words(text)
+    if not tokens or all(token.isdigit() or len(token) == 1 for token in tokens):
+        return "noise"
+    if brands and all(token in brands or token in TLDS for token in tokens):
+        return "brand-only"
+    return None
+
+
+def covered(tokens: list[str], coverage: list[set[str]]) -> bool:
+    wanted = {token for token in tokens if len(token) > 1}
+    return bool(wanted) and any(wanted <= item for item in coverage)
+
+
+def build(rows: list[dict], coverage_texts: list[str], brands: list[str], *, min_position: float, max_position: float, min_impressions: int, limit: int) -> dict:
+    brand_set = brand_tokens(brands)
+    coverage = [set(words(text)) for text in coverage_texts if text]
+    ideas, dropped, seen = [], [], set()
+    ordered = sorted((row for row in rows if isinstance(row, dict)), key=lambda row: -float(row.get("impressions") or 0))
+    for row in ordered:
+        keys = row.get("keys") if isinstance(row.get("keys"), list) else []
+        query = " ".join(str(row.get("query") or (keys[0] if keys else "")).split())
+        reason = reject_reason(query, brand_set)
+        position = float(row.get("position") or 0)
+        impressions = int(row.get("impressions") or 0)
+        tokens = words(query)
+        key = " ".join(sorted(set(tokens)))
+        if reason is None and key in seen:
+            reason = "duplicate"
+        if reason is None and covered(tokens, coverage):
+            reason = "already-covered"
+        if reason is None and not (min_position <= position <= max_position and impressions >= min_impressions):
+            reason = "outside-striking-distance"
+        if reason is None and len(ideas) >= limit:
+            reason = "daily-limit"
+        if reason:
+            dropped.append({"query": query, "reason": reason})
+            continue
+        seen.add(key)
+        coverage.append(set(tokens))  # plural/singular variants of this query now count as covered
+        ideas.append({"query": query, "position": round(position, 1), "impressions": impressions, "clicks": int(row.get("clicks") or 0), "type": "gsc"})
+    counts: dict[str, int] = {}
+    for item in dropped:
+        counts[item["reason"]] = counts.get(item["reason"], 0) + 1
+    return {"ideas": ideas, "dropped": dropped, "counts": {"ideas": len(ideas), **counts}}
+
+
+def load_rows(path: str) -> list[dict]:
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if isinstance(data, dict):
+        data = data.get("rows") or data.get("queries") or []
+    return data if isinstance(data, list) else []
+
+
+def load_coverage(path: str | None) -> list[str]:
+    if not path:
+        return []
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    items = data.get("items") or data.get("posts") or data.get("ideas") or [] if isinstance(data, dict) else data
+    texts = []
+    for item in items:
+        if isinstance(item, str):
+            texts.append(item)
+        elif isinstance(item, dict):
+            texts.append(str(item.get("title") or ""))
+            keywords = item.get("keywords") or item.get("keyword") or []
+            texts.extend([keywords] if isinstance(keywords, str) else [str(value) for value in keywords])
+    return texts
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("rows", help="Search Console query rows (JSON list, or {rows: [...]})")
+    parser.add_argument("--coverage", help="existing post titles/keywords and waiting ideas (JSON list of strings or {title, keywords})")
+    parser.add_argument("--brand", action="append", default=[], help="brand name or domain stem; repeatable")
+    parser.add_argument("--min-position", type=float, default=4)
+    parser.add_argument("--max-position", type=float, default=15)
+    parser.add_argument("--min-impressions", type=int, default=10)
+    parser.add_argument("--limit", type=int, default=5, help="new ideas per run")
+    parser.add_argument("--project", default=".")
+    args = parser.parse_args()
+    try:
+        result = build(load_rows(args.rows), load_coverage(args.coverage), args.brand, min_position=args.min_position, max_position=args.max_position, min_impressions=args.min_impressions, limit=args.limit)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"maggie seo query-ideas: {error}", file=sys.stderr)
+        return 1
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_skill_catalog.py

@@ -159,6 +159,20 @@ def scaffold(root: Path, name: str, description: str, category: str | None) -> P
     return target
 
 
+def release_version(explicit: str | None, sources: list[str]) -> str:
+    """One version source: never fall back to a built-in constant, refuse on disagreement."""
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    from maggie_version_sources import read_source
+    found = {spec: read_source(Path.cwd(), spec) for spec in sources}
+    if explicit:
+        found["--version"] = explicit
+    if not found:
+        raise ValueError("give --version or --version-from (the packager has no version of its own)")
+    if len(set(found.values())) > 1:
+        raise ValueError("version sources disagree: " + ", ".join(f"{spec}={value}" for spec, value in found.items()))
+    return next(iter(found.values()))
+
+
 def package(root: Path, out: Path, prefix: str, owner: str, version: str, all_name: str | None, force: bool) -> dict:
     report = validate(root, False, None)
     if not report["passed"]:
@@ -237,7 +251,7 @@ def main(argv: list[str] | None = None) -> int:
     sub = parser.add_subparsers(dest="command", required=True)
     new = sub.add_parser("scaffold"); new.add_argument("--root", type=Path, required=True); new.add_argument("--name", required=True); new.add_argument("--description", required=True); new.add_argument("--category")
     check = sub.add_parser("validate"); check.add_argument("--root", type=Path, required=True); check.add_argument("--require-pinned", action="store_true", help="references must pin a 40-character commit"); check.add_argument("--catalog", type=Path, help="catalog index JSON with skills[].id or .name")
-    pack = sub.add_parser("package"); pack.add_argument("--root", type=Path, required=True); pack.add_argument("--out", type=Path, required=True); pack.add_argument("--prefix", required=True, help="plugin name prefix and marketplace name"); pack.add_argument("--owner", required=True); pack.add_argument("--version", default="0.1.0"); pack.add_argument("--all-name", help="name of the all-in-one plugin (default <prefix>-all)"); pack.add_argument("--no-all", action="store_true"); pack.add_argument("--force", action="store_true")
+    pack = sub.add_parser("package"); pack.add_argument("--root", type=Path, required=True); pack.add_argument("--out", type=Path, required=True); pack.add_argument("--prefix", required=True, help="plugin name prefix and marketplace name"); pack.add_argument("--owner", required=True); pack.add_argument("--version", help="release version; must equal --version-from when both are given"); pack.add_argument("--version-from", action="append", default=[], help="version source to follow: FILE, FILE:json.key or FILE~CONSTANT (repeat to require several to agree)"); pack.add_argument("--all-name", help="name of the all-in-one plugin (default <prefix>-all)"); pack.add_argument("--no-all", action="store_true"); pack.add_argument("--force", action="store_true")
     test = sub.add_parser("smoke"); test.add_argument("--out", type=Path, required=True); test.add_argument("--claude", action="store_true", help="also run `claude plugin validate`")
     args = parser.parse_args(argv)
     try:
@@ -248,7 +262,7 @@ def main(argv: list[str] | None = None) -> int:
             report = validate(args.root, args.require_pinned, args.catalog)
             report.pop("records", None)
         elif args.command == "package":
-            report = package(args.root, args.out, args.prefix, args.owner, args.version, False if args.no_all else args.all_name, args.force)
+            report = package(args.root, args.out, args.prefix, args.owner, release_version(args.version, args.version_from), False if args.no_all else args.all_name, args.force)
         else:
             report = smoke(args.out, args.claude)
     except (OSError, ValueError, json.JSONDecodeError, subprocess.SubprocessError) as error: