molecule-publish

#!/usr/bin/env python3
"""tested_with.py - stamp a `tested-with:<family>` tag at publish (wiki #85).

DECISION (drew2, 2026-08-05): tested-only, NO backfill, NO 'authored' tag.
  - Forward-only: the tag is added by the publishing agent when it ACTUALLY
    exercised the molecule this session (loaded it, verified the render/BOM) -
    never stamped in bulk across existing pages. Absence stays meaningful:
    a `tested-with:` tag present means a model really verified that page.
  - The TAG is the model FAMILY (`claude`, `gpt`, `gemini`) so it stays accurate
    as versions roll (Colby #85). The specific version is recorded in page
    metadata (`metadata.tested_with[]`) for anyone who wants the exact build,
    without multiplying the tag space.
  - There is deliberately NO 'authored-with'/'authored-by' tag. Authorship is not
    a verification signal; only testing is.

  stamp  <package.json> --family <fam> [--version <ver>]
      Idempotently add `tested-with:<family>` to tags[] and append
      {family, version} to metadata.tested_with[] (deduped). Operates on the ONE
      file given - it has no bulk/backfill mode by design.

  check  <package.json>
      Print the tested-with tags/metadata already on the package (exit 0).

Stdlib only. `--family` is normalised (claude-opus-4-8 -> claude).
"""
import argparse
import json
import re
import sys

# model id / name -> family. Extend as new providers are exercised.
FAMILY_RULES = [
    (re.compile(r'claude|anthropic', re.I), "claude"),
    (re.compile(r'gpt|o[0-9]|openai|codex', re.I), "gpt"),
    (re.compile(r'gemini|google', re.I), "gemini"),
    (re.compile(r'llama|meta', re.I), "llama"),
    (re.compile(r'mistral|mixtral', re.I), "mistral"),
    (re.compile(r'grok|xai', re.I), "grok"),
]


def to_family(s):
    """Map a model id/name to its family; fall back to a slug of the input so an
    unknown provider still produces a stable, lowercase tag rather than failing."""
    s = (s or "").strip()
    for rx, fam in FAMILY_RULES:
        if rx.search(s):
            return fam
    slug = re.sub(r'[^a-z0-9]+', '-', s.lower()).strip('-')
    return slug or None


def cmd_stamp(a):
    fam = to_family(a.family)
    if not fam:
        print("FAIL: could not derive a family from --family (give a model id/name)")
        return 1
    pkg = json.load(open(a.package))
    tags = pkg.get("tags") or []
    tag = f"tested-with:{fam}"
    changed = False
    if tag not in tags:
        tags.append(tag)
        pkg["tags"] = tags
        changed = True
    # record the specific version out of the tag space, in metadata
    if a.version:
        meta = pkg.setdefault("metadata", {})
        tw = meta.setdefault("tested_with", [])
        entry = {"family": fam, "version": a.version}
        if entry not in tw:
            tw.append(entry)
            changed = True
    if changed and not a.dry_run:
        json.dump(pkg, open(a.package, "w"), indent=2)
        open(a.package, "a").write("\n")
    verb = "would add" if a.dry_run else ("added" if changed else "already present -")
    print(f"{verb} {tag}" + (f" (version {a.version} -> metadata.tested_with)" if a.version else "")
          + (" [dry-run]" if a.dry_run else ""))
    print("NOTE: tested-only, forward-only. Do NOT run this across existing pages (#85).")
    return 0


def cmd_check(a):
    pkg = json.load(open(a.package))
    tags = [t for t in (pkg.get("tags") or []) if str(t).startswith("tested-with:")]
    tw = (pkg.get("metadata") or {}).get("tested_with") or []
    print("tags:", ", ".join(tags) if tags else "(none)")
    print("metadata.tested_with:", json.dumps(tw) if tw else "(none)")
    return 0


def main():
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = ap.add_subparsers(dest="cmd", required=True)
    s = sub.add_parser("stamp", help="add tested-with:<family> (forward-only, #85)")
    s.add_argument("package")
    s.add_argument("--family", required=True,
                   help="model id or family the agent tested with (e.g. claude-opus-4-8)")
    s.add_argument("--version", help="specific model version -> recorded in metadata, not the tag")
    s.add_argument("--dry-run", action="store_true")
    s.set_defaults(fn=cmd_stamp)
    c = sub.add_parser("check", help="show existing tested-with tags/metadata")
    c.add_argument("package")
    c.set_defaults(fn=cmd_check)
    a = ap.parse_args()
    sys.exit(a.fn(a))


if __name__ == "__main__":
    main()