@mmerterden/multi-agent-pipeline 20.6.0 → 20.7.0

package/pipeline/skills/shared/external/localization-reuse-map/scripts/publish-confluence.py

@@ -1,38 +1,13 @@
 #!/usr/bin/env python3
-"""Publish (or UPDATE) one screen's localization map to Confluence  -  live, idempotent.
-
-Targets a Confluence **Server/Data Center** instance with a **Bearer Personal Access
-Token** (Server/DC auth  -  NOT Atlassian Cloud `user:token`). Nothing about your wiki is
-baked in: pass `--base-url`, `--space` and `--parent`, or set `CONFLUENCE_BASE_URL`,
-`CONFLUENCE_SPACE` and `CONFLUENCE_PARENT` once in the environment.
-
-Idempotent by title under a parent page:
-  * search `space=<SPACE> and title="<title>"` (CQL);
-  * **exists → PUT** `/rest/api/content/<id>` with `version.number+1` → updates the
-    SAME page in place (re-running the mapper on a screen refreshes its page, never
-    duplicates it);
-  * **absent → POST** `/rest/api/content` under `--parent`.
-Then attaches `screenshot.png` + the overlay PNG + (via `--keyshots <manifest>`) every
-per-key screenpiece PNG from render-key-shots.py (the `<ac:image ri:filename=...>`
-references in the body resolve to these), creating or updating each by filename.
-`--attach <file>` (repeatable) attaches any additional document  -  e.g. the content
-team's `<slug>.localization.xlsx` (build-spreadsheet.py)  -  and, for office/spreadsheet
-files, appends a `view-file` macro section so it also renders inline on the page.
-
-HTTP goes through **curl** on purpose: curl uses the system trust store, so it works
-behind a corporate TLS proxy where Python's `urllib` fails cert verification. The token
-is read from the keychain (item `CONFLUENCE_API_TOKEN`) and passed to curl via a
-`chmod 600` `-K` config file  -  never on the argv / `ps`.
-
-The skill asks the user for the target (space / parent / formats) and passes them here.
-Read-only against the local artifacts; the only writes are to Confluence.
-
-Examples:
-  python3 publish-confluence.py --xml out/<slug>.confluence.xml --screen "<name>" \
-      --base-url https://wiki.example.com --space ENG --parent 12345 \
-      --screenshot out/screenshot.png --overlay out/<slug>.overlay.png
-  python3 publish-confluence.py --xml ... --title "Custom Title"   # base/space/parent from env
-  python3 publish-confluence.py --xml ... --screen "<name>" --dry-run
+"""Publish the reuse-map page to Confluence Server / Data Center, creating or updating it.
+
+The page is located through the database-backed `content?spaceKey=&title=`
+lookup rather than CQL, because the CQL index lags and would let a second copy
+be created. An existing page is updated in place with the next version number;
+otherwise a new one is created under the parent. Attachments are then added
+or replaced. curl carries every request, which keeps the system trust store in
+play, and the Bearer token sits in a curl config file with mode 600 instead of
+on the command line.
 """
 import argparse
 import json
@@ -41,223 +16,194 @@ import subprocess
 import sys
 import tempfile
 import urllib.parse
+from xml.sax.saxutils import quoteattr
 
-DEFAULT_BASE = os.environ.get("CONFLUENCE_BASE_URL", "")
-DEFAULT_SPACE = os.environ.get("CONFLUENCE_SPACE", "")
-DEFAULT_PARENT = os.environ.get("CONFLUENCE_PARENT", "")
-KEYCHAIN_ITEM = "CONFLUENCE_API_TOKEN"
+EMBED_EXTENSIONS = {".xlsx", ".xls", ".csv", ".docx", ".pdf"}
+EMBED_HEADING = "CMS Aktar\u0131m Dosyas\u0131"
+CONTENT = "/rest/api/content"
 
 
-def get_token(args):
-    if args.token:
-        return args.token
-    v = os.environ.get("CONFLUENCE_API_TOKEN")
-    if v:
-        return v.strip()
-    try:
-        r = subprocess.run(
-            ["security", "find-generic-password", "-s", args.keychain_name, "-w"],
-            capture_output=True, text=True)
-        if r.returncode == 0 and r.stdout.strip():
-            return r.stdout.strip()
-    except Exception:
-        pass
-    sys.exit(f"No Confluence token  -  add keychain item '{args.keychain_name}', set "
-             "CONFLUENCE_API_TOKEN, or pass --token.")
-
-
-class Cf:
-    """Thin curl-backed Confluence Server REST client (Bearer auth via -K config)."""
-
+class Client:
     def __init__(self, base, token):
         self.base = base.rstrip("/")
-        self._cfg = tempfile.NamedTemporaryFile("w", suffix=".curlrc", delete=False)
-        os.chmod(self._cfg.name, 0o600)
-        self._cfg.write(f'header = "Authorization: Bearer {token}"\n')
-        self._cfg.close()
+        self.tmp = tempfile.mkdtemp(prefix="confluence-")
+        self.config = os.path.join(self.tmp, "auth.curlrc")
+        quoted = token.replace("\\", "\\\\").replace('"', '\\"')
+        descriptor = os.open(self.config, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(descriptor, "w") as sink:
+            sink.write(f'header = "Authorization: Bearer {quoted}"\n')
 
     def close(self):
+        for leftover in os.listdir(self.tmp):
+            os.remove(os.path.join(self.tmp, leftover))
+        os.rmdir(self.tmp)
+
+    def call(self, method, path, body=None, form_file=None):
+        argv = ["curl", "-sS", "-K", self.config, "-X", method]
+        if body is not None:
+            payload = os.path.join(self.tmp, "body.json")
+            with open(payload, "w", encoding="utf-8") as sink:
+                json.dump(body, sink, ensure_ascii=False)
+            argv += ["--data", "@" + payload, "-H", "Content-Type: application/json"]
+        if form_file is not None:
+            argv += ["-F", "file=@" + form_file, "-H", "X-Atlassian-Token: nocheck"]
+        argv.append(self.base + path)
+        done = subprocess.run(argv, text=True, capture_output=True)
+        if done.returncode != 0:
+            sys.exit(f"curl did not complete: {done.stderr.strip()}")
         try:
-            os.unlink(self._cfg.name)
-        except OSError:
-            pass
-
-    def _run(self, args):
-        r = subprocess.run(["curl", "-sS", "-K", self._cfg.name, *args],
-                           capture_output=True, text=True)
-        if r.returncode != 0:
-            sys.exit(f"curl failed: {r.stderr.strip()}")
-        return r.stdout
-
-    def _json(self, args):
-        out = self._run(args)
-        try:
-            data = json.loads(out)
-        except json.JSONDecodeError:
-            sys.exit(f"Confluence returned non-JSON (auth/endpoint?):\n{out[:400]}")
-        if isinstance(data, dict) and data.get("statusCode") and data.get("message"):
-            sys.exit(f"Confluence error {data['statusCode']}: {data['message']}")
-        return data
-
-    def find_by_title(self, space, title):
-        # DB-backed content query (NOT /content/search  -  CQL hits the async search
-        # index, which lags seconds behind a just-created page and breaks idempotency).
-        qs = urllib.parse.urlencode({"spaceKey": space, "title": title, "type": "page",
-                                     "expand": "version", "limit": "5"})
-        data = self._json([f"{self.base}/rest/api/content?{qs}"])
-        results = data.get("results") or []
-        return results[0] if results else None
-
-    def create(self, space, parent, title, storage):
-        body = {"type": "page", "title": title, "space": {"key": space},
-                "ancestors": [{"id": str(parent)}],
-                "body": {"storage": {"value": storage, "representation": "storage"}}}
-        return self._post_json("POST", f"{self.base}/rest/api/content", body)
-
-    def update(self, page_id, title, storage, new_version, space):
-        body = {"id": str(page_id), "type": "page", "title": title,
-                "space": {"key": space},
-                "version": {"number": new_version},
-                "body": {"storage": {"value": storage, "representation": "storage"}}}
-        return self._post_json("PUT", f"{self.base}/rest/api/content/{page_id}", body)
-
-    def _post_json(self, method, url, body):
-        with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False, encoding="utf-8") as bf:
-            json.dump(body, bf, ensure_ascii=False)
-            bpath = bf.name
-        try:
-            return self._json(["-X", method, "-H", "Content-Type: application/json",
-                               "--data", f"@{bpath}", url])
-        finally:
-            os.unlink(bpath)
-
-    def existing_attachment(self, page_id, filename):
-        q = urllib.parse.quote(filename)
-        data = self._json([f"{self.base}/rest/api/content/{page_id}/child/attachment?filename={q}&limit=1"])
-        results = data.get("results") or []
-        return results[0] if results else None
-
-    def attach(self, page_id, path):
-        fn = os.path.basename(path)
-        existing = self.existing_attachment(page_id, fn)
-        if existing:
-            url = f"{self.base}/rest/api/content/{page_id}/child/attachment/{existing['id']}/data"
-        else:
-            url = f"{self.base}/rest/api/content/{page_id}/child/attachment"
-        return self._json(["-H", "X-Atlassian-Token: nocheck",
-                           "-F", f"file=@{path}", "-X", "POST", url])
-
-
-EMBED_EXTS = (".xlsx", ".xls", ".csv", ".docx", ".pdf")
-
-
-def attachment_section(paths):
-    """Storage-format section embedding a `view-file` macro for each office/spreadsheet
-    attachment, so the file renders inline on the page (not only in the drawer). Returns
-    "" when no path is an embeddable document."""
-    docs = [p for p in paths if os.path.splitext(p)[1].lower() in EMBED_EXTS]
-    if not docs:
-        return ""
-    macros = "".join(
-        '<p><ac:structured-macro ac:name="view-file">'
-        '<ac:parameter ac:name="name">'
-        f'<ri:attachment ri:filename="{os.path.basename(p)}"/>'
-        '</ac:parameter></ac:structured-macro></p>'
-        for p in docs
-    )
-    return "<h2>CMS Aktarım Dosyası</h2>" + macros
+            reply = json.loads(done.stdout)
+        except ValueError:
+            sys.exit(f"Expected JSON from Confluence, got: {done.stdout[:400]}")
+        if isinstance(reply, dict) and "statusCode" in reply and "message" in reply:
+            sys.exit(f"Confluence answered {reply['statusCode']}: {reply['message']}")
+        return reply
+
+
+def resolve_token(explicit, keychain_name):
+    if explicit:
+        return explicit
+    if os.environ.get("CONFLUENCE_API_TOKEN"):
+        return os.environ["CONFLUENCE_API_TOKEN"]
+    try:
+        lookup = subprocess.run(
+            ["security", "find-generic-password", "-s", keychain_name, "-w"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    secret = lookup.stdout.strip()
+    return secret if lookup.returncode == 0 and secret else None
+
+
+def view_file_macro(path):
+    target = f"<ri:attachment ri:filename={quoteattr(os.path.basename(path))}/>"
+    parameter = f'<ac:parameter ac:name="name">{target}</ac:parameter>'
+    return f'<p><ac:structured-macro ac:name="view-file">{parameter}</ac:structured-macro></p>'
+
+
+def embed_block(files):
+    return f"<h2>{EMBED_HEADING}</h2>" + "".join(map(view_file_macro, files))
+
+
+def keyshot_files(manifest_path):
+    with open(manifest_path, encoding="utf-8") as stream:
+        manifest = json.load(stream)
+    folder = os.path.dirname(os.path.abspath(manifest_path))
+    names = [str(shot.get("file", "")) for shot in manifest.get("shots") or []]
+    return [os.path.join(folder, name) for name in names if name.endswith(".png")]
+
+
+def page_fields(title, space):
+    return {"type": "page", "title": title, "space": {"key": space}}
+
+
+def build_cli():
+    cli = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    cli.add_argument("--xml", required=True, help="page body in storage format (<slug>.confluence.xml)")
+    cli.add_argument("--screen", help="name of the screen; feeds the default title")
+    cli.add_argument("--title", help="explicit page title; otherwise '<title-prefix> - <screen>'")
+    cli.add_argument("--title-prefix", default=os.environ.get("LOCALIZATION_PAGE_PREFIX", "Localization"))
+    cli.add_argument("--screenshot", help="screen image to upload as an attachment")
+    cli.add_argument("--overlay", help="key-map overlay PNG to upload as an attachment")
+    cli.add_argument("--keyshots", metavar="MANIFEST", help="keyshots manifest; each .png it lists is uploaded")
+    cli.add_argument("--attach", metavar="FILE", action="append", default=[], help="additional file to upload; may be repeated")
+    cli.add_argument("--base", "--base-url", dest="base", default=os.environ.get("CONFLUENCE_BASE_URL"))
+    cli.add_argument("--space", default=os.environ.get("CONFLUENCE_SPACE"))
+    cli.add_argument("--parent", default=os.environ.get("CONFLUENCE_PARENT"), help="id of the parent page")
+    cli.add_argument("--token", help="Bearer PAT; CONFLUENCE_API_TOKEN or the keychain is safer since other processes can read argv")
+    cli.add_argument("--keychain-name", default="CONFLUENCE_API_TOKEN", help="keychain service that stores the PAT")
+    cli.add_argument("--dry-run", action="store_true", help="report the planned actions without touching Confluence")
+    return cli
+
+
+def check_inputs(cli, opts):
+    if not opts.title and not opts.screen:
+        cli.error("supply --title or --screen")
+    if not opts.dry_run:
+        target = {"--base": opts.base, "--space": opts.space, "--parent": opts.parent}
+        missing = [flag for flag, value in target.items() if not value]
+        if missing:
+            cli.error(f"missing {', '.join(missing)} (or set CONFLUENCE_BASE_URL / CONFLUENCE_SPACE / CONFLUENCE_PARENT)")
+    named = [("--xml", opts.xml), ("--keyshots", opts.keyshots), ("--screenshot", opts.screenshot), ("--overlay", opts.overlay)]
+    named += [("--attach", extra) for extra in opts.attach]
+    for label, path in named:
+        if path and not os.path.isfile(path):
+            cli.error(f"{label} file not found: {path}")
+
+
+def upsert_page(client, opts, title, body):
+    lookup = urllib.parse.urlencode({"spaceKey": opts.space, "title": title, "type": "page", "expand": "version", "limit": 5})
+    matches = client.call("GET", f"{CONTENT}?{lookup}").get("results") or []
+    storage = {"storage": {"value": body, "representation": "storage"}}
+    if not matches:
+        page = client.call("POST", CONTENT, {
+            **page_fields(title, opts.space), "ancestors": [{"id": opts.parent}], "body": storage,
+        })
+        return page, "created"
+    page_id = matches[0]["id"]
+    version = int((matches[0].get("version") or {}).get("number", 1))
+    page = client.call("PUT", f"{CONTENT}/{page_id}", {
+        "id": page_id, **page_fields(title, opts.space), "version": {"number": version + 1}, "body": storage,
+    })
+    return page, f"updated (v{version}->{version + 1})"
+
+
+def upload(client, page_id, path):
+    name = os.path.basename(path)
+    attachments = f"{CONTENT}/{page_id}/child/attachment"
+    query = urllib.parse.urlencode({"filename": name, "limit": 1})
+    present = client.call("GET", f"{attachments}?{query}").get("results") or []
+    endpoint = f"{attachments}/{present[0]['id']}/data" if present else attachments
+    client.call("POST", endpoint, form_file=path)
+    return name
 
 
 def main():
-    ap = argparse.ArgumentParser(description=__doc__,
-                                 formatter_class=argparse.RawDescriptionHelpFormatter)
-    ap.add_argument("--xml", required=True, help="<slug>.confluence.xml (storage body)")
-    ap.add_argument("--screen", help="screen name (used in the default title)")
-    ap.add_argument("--title", help="page title (default: '<title-prefix>  -  <screen>')")
-    ap.add_argument("--title-prefix", default=os.environ.get("LOCALIZATION_PAGE_PREFIX", "Localization"),
-                    help="prefix for the default title; set it to your wiki's wording "
-                         "(env LOCALIZATION_PAGE_PREFIX)")
-    ap.add_argument("--screenshot", help="screenshot PNG to attach")
-    ap.add_argument("--overlay", help="overlay PNG to attach")
-    ap.add_argument("--keyshots", metavar="MANIFEST",
-                    help="<slug>.keyshots.manifest.json (render-key-shots.py)  -  attaches every "
-                         "per-key screenpiece PNG it lists, so the table's Ekran Görüntüsü "
-                         "cells (<ri:attachment> refs) render on the page")
-    ap.add_argument("--attach", action="append", default=[], metavar="FILE",
-                    help="extra file to attach (repeatable); e.g. <slug>.localization.xlsx. "
-                         "Office/spreadsheet files also get a view-file macro on the page.")
-    ap.add_argument("--base", "--base-url", dest="base", default=DEFAULT_BASE,
-                    help="Confluence base URL, e.g. https://wiki.example.com (env CONFLUENCE_BASE_URL)")
-    ap.add_argument("--space", default=DEFAULT_SPACE, help="space key (env CONFLUENCE_SPACE)")
-    ap.add_argument("--parent", default=DEFAULT_PARENT,
-                    help="parent pageId the screen pages hang under (env CONFLUENCE_PARENT)")
-    ap.add_argument("--token", help="Confluence PAT (else keychain / env)")
-    ap.add_argument("--keychain-name", default=KEYCHAIN_ITEM)
-    ap.add_argument("--dry-run", action="store_true", help="print the plan, write nothing")
-    args = ap.parse_args()
-
-    title = args.title or (f"{args.title_prefix}  -  {args.screen}" if args.screen else None)
-    if not title:
-        ap.error("supply --title or --screen")
-    missing = [flag for flag, value in (("--base-url", args.base), ("--space", args.space),
-                                        ("--parent", args.parent)) if not value]
-    if missing and not args.dry_run:
-        ap.error("no Confluence target configured  -  pass " + ", ".join(missing) +
-                 " (or set CONFLUENCE_BASE_URL / CONFLUENCE_SPACE / CONFLUENCE_PARENT)")
-    if not os.path.isfile(args.xml):
-        ap.error(f"--xml not found: {args.xml}")
-    storage = open(args.xml, encoding="utf-8").read()
-
-    keyshot_files = []
-    if args.keyshots:
-        if not os.path.isfile(args.keyshots):
-            ap.error(f"--keyshots manifest not found: {args.keyshots}")
-        with open(args.keyshots, encoding="utf-8") as fh:
-            man = json.load(fh)
-        base = os.path.dirname(os.path.abspath(args.keyshots))
-        keyshot_files = [os.path.join(base, s["file"]) for s in man.get("shots", [])
-                         if s.get("file", "").endswith(".png")]
-
-    attachments = [p for p in (args.screenshot, args.overlay, *keyshot_files, *args.attach) if p]
-    for p in attachments:
-        if not os.path.isfile(p):
-            ap.error(f"attachment not found: {p}")
-
-    # Embed a view-file macro for the spreadsheet/office attachments so they render on the page.
-    storage += attachment_section(args.attach)
-
-    if args.dry_run:
-        print(json.dumps({
-            "base": args.base, "space": args.space, "parent": args.parent,
-            "title": title, "xmlBytes": len(storage),
-            "attachments": [os.path.basename(p) for p in attachments],
-            "action": "search-then-create-or-update (idempotent by title)",
-        }, ensure_ascii=False, indent=2))
+    cli = build_cli()
+    opts = cli.parse_args()
+    check_inputs(cli, opts)
+    title = opts.title or f"{opts.title_prefix} - {opts.screen}"
+
+    files = [p for p in (opts.screenshot, opts.overlay) if p]
+    if opts.keyshots:
+        files += keyshot_files(opts.keyshots)
+    files += opts.attach
+
+    with open(opts.xml, encoding="utf-8") as stream:
+        body = stream.read()
+    embedded = [p for p in opts.attach if os.path.splitext(p)[1].lower() in EMBED_EXTENSIONS]
+    if embedded:
+        body += embed_block(embedded)
+
+    if opts.dry_run:
+        plan = {
+            "base": opts.base, "space": opts.space, "parent": opts.parent, "title": title,
+            "xmlBytes": len(body.encode("utf-8")), "attachments": files, "action": "dry-run",
+        }
+        print(json.dumps(plan, indent=2, ensure_ascii=False))
         return
 
-    cf = Cf(args.base, get_token(args))
+    token = resolve_token(opts.token, opts.keychain_name)
+    if not token:
+        sys.exit(
+            "No Confluence token available. Put a Server/DC personal access token in the keychain "
+            f"(service '{opts.keychain_name}') or export CONFLUENCE_API_TOKEN."
+        )
+
+    client = Client(opts.base, token)
     try:
-        existing = cf.find_by_title(args.space, title)
-        if existing:
-            cur = int(existing.get("version", {}).get("number", 1))
-            page = cf.update(existing["id"], title, storage, cur + 1, args.space)
-            action = f"updated (v{cur}→v{cur + 1})"
-        else:
-            page = cf.create(args.space, args.parent, title, storage)
-            action = "created"
+        page, action = upsert_page(client, opts, title, body)
         page_id = page["id"]
-
-        attached = []
-        for p in attachments:
-            cf.attach(page_id, p)
-            attached.append(os.path.basename(p))
-
-        webui = (page.get("_links") or {}).get("webui", "")
-        url = f"{args.base}{webui}" if webui else f"{args.base}/pages/viewpage.action?pageId={page_id}"
-        print(json.dumps({"action": action, "id": page_id, "title": title,
-                          "attachments": attached, "url": url}, ensure_ascii=False, indent=2))
+        uploaded = [upload(client, page_id, path) for path in files]
     finally:
-        cf.close()
+        client.close()
+
+    root = opts.base.rstrip("/")
+    link = (page.get("_links") or {}).get("webui")
+    url = root + link if link else f"{root}/pages/viewpage.action?pageId={page_id}"
+    report = {"action": action, "id": page_id, "title": title, "attachments": uploaded, "url": url}
+    print(json.dumps(report, indent=2, ensure_ascii=False))
 
 
 if __name__ == "__main__":