@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/release_publish.py

@@ -0,0 +1,486 @@
+#!/usr/bin/env python3
+"""release_publish.py -- Flip a draft GitHub release to public (#716).
+
+Companion to ``scripts/release.py`` per the #716 safety hardening.
+``task release`` lands the release as a draft so the *artifact
+production* phase (release.yml CI + binary upload) is decoupled from
+the *consumer-visibility* phase. After manually reviewing the draft's
+binaries / notes / asset list, the operator runs::
+
+    task release:publish -- <version>
+
+which dispatches this script to flip the release out of draft state.
+
+Pipeline
+--------
+1. Pre-flight: verify the release exists and is in draft state via the
+   GitHub REST API. The lookup uses a paginated list+filter against
+   ``GET /repos/{owner}/{repo}/releases?per_page=100`` (with
+   ``gh api --paginate`` following ``Link: rel="next"`` headers) and
+   matches the first entry whose ``tag_name`` equals ``v<version>``.
+   State machine:
+
+   - **not-found** -> exit 1 (cannot publish a release that does not exist)
+   - **already-published** -> exit 0 no-op (publish is idempotent; running
+     it twice is safe)
+   - **draft** -> proceed
+2. Flip the draft state via REST PATCH:
+   ``PATCH /repos/{owner}/{repo}/releases/{id}`` with ``draft=false``.
+3. Re-read the release and verify the draft state actually flipped.
+4. Print summary line; return exit 0.
+
+REST internals (#961, #1016)
+----------------------------
+The v0.26.1 publish failed (2026-05-07) at the GraphQL bucket
+exhaustion mid-cascade: the legacy ``gh release view --json ...`` and
+``gh release edit ... --draft=false`` subcommands both routed through
+GraphQL and failed hard when the bucket hit zero. Per ``meta/lessons.md``
+``## gh CLI GraphQL Bucket Exhaustion + REST Fallback + UTF-8 Payload
+Pattern (2026-05)`` and the canonical preamble in
+``templates/agent-prompt-preamble.md`` S5 (REST-by-default rule), this
+script uses ``gh api`` directly against REST endpoints, which bill
+the ``core`` bucket (independent of ``graphql``).
+
+#1016 follow-up: the v0.27.0 publish (2026-05-10) failed against a
+DRAFT release because the original #961 implementation called
+``GET /repos/{owner}/{repo}/releases/tags/{tag}``, which the GitHub
+REST docs explicitly limit to PUBLISHED releases ("This returns the
+latest published release for the specified tag"). DRAFT releases were
+filtered out at the API layer, so ``release_publish.py`` 404'd on the
+canonical case it was supposed to handle. The fix (option 2 from #1016)
+replaces the single ``/releases/tags/{tag}`` call with a paginated
+list+filter against ``GET /repos/{owner}/{repo}/releases?per_page=100``
+(via ``gh api --paginate``), then matches the first entry whose
+``tag_name`` equals the target. This stays within the REST core bucket
+and surfaces drafts.
+
+Release helpers are intentionally NOT routed through
+``scripts/gh_rest.py`` (#961) because the issue body explicitly carves
+releases out as ``task release`` (#74) territory; this module owns its
+two inline REST calls without extending the cross-cutting helper
+surface. See module docstring of ``scripts/gh_rest.py`` for the
+rationale.
+
+The internal ``payload`` shape returned by :func:`view_release` is
+normalised to the legacy field names (``isDraft``, ``tagName``,
+``url``, ``name``) regardless of which REST keys the upstream API
+uses, so :func:`run_publish` and existing tests do not care that the
+underlying transport changed.
+
+Exit codes
+----------
+    0 -- release published (or already-published no-op)
+    1 -- pre-flight or step-level violation (release missing, gh failure,
+         post-edit verification mismatch)
+    2 -- config / argument error (malformed version, repo unresolvable, ...)
+
+Refs #716 (canonical spec; safety hardening Item 2 of 7),
+#74 (foundation), #233, #642, #635, #709, #710,
+#961 (REST internals; v0.26.1 publish failure motivating incident),
+#798 (PS 5.1 non-ASCII discipline applied to JSON-payload pattern).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil  # noqa: F401  -- kept for tests that monkeypatch release_publish.shutil.which
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+# Make sibling scripts importable so we can re-use _resolve_repo /
+# _resolve_project_root / _validate_version + the EXIT_* constants from
+# release.py without duplicating them.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _stdio_utf8 import reconfigure_stdio  # noqa: E402
+
+reconfigure_stdio()
+
+import release  # noqa: E402
+
+# Re-export the exit codes so callers (tests + downstream) get a single
+# source of truth identical to scripts/release.py.
+EXIT_OK = release.EXIT_OK
+EXIT_VIOLATION = release.EXIT_VIOLATION
+EXIT_CONFIG_ERROR = release.EXIT_CONFIG_ERROR
+
+
+# ---- Data classes -----------------------------------------------------------
+
+
+@dataclass
+class PublishConfig:
+    version: str
+    repo: str
+    project_root: Path
+    dry_run: bool
+
+
+# ---- argument parsing -------------------------------------------------------
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="release_publish",
+        description=(
+            "Flip a draft GitHub release to public (#716 safety hardening). "
+            "Companion to `task release` -- after reviewing the draft's "
+            "binaries / notes / asset list, run `task release:publish -- "
+            "<version>` to publish."
+        ),
+    )
+    parser.add_argument(
+        "version",
+        help="Release version, e.g. 0.21.0 (no leading 'v', strict X.Y.Z).",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the publish plan without invoking gh release edit.",
+    )
+    parser.add_argument(
+        "--repo",
+        default=None,
+        metavar="OWNER/REPO",
+        help=(
+            "Override the GitHub repository (default: resolved from "
+            "`git remote get-url origin`, falling back to "
+            f"{release.DEFAULT_REPO!r})."
+        ),
+    )
+    parser.add_argument(
+        "--project-root",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help=(
+            "Repository root (default: $DEFT_PROJECT_ROOT or the parent of "
+            "the scripts/ directory)."
+        ),
+    )
+    return parser
+
+
+# ---- gh helpers -------------------------------------------------------------
+
+
+def _normalise_release_payload(rest_payload: dict) -> dict:
+    """Map the REST release object to the legacy-shape internal payload.
+
+    The REST endpoint returns ``draft`` / ``tag_name`` / ``html_url``
+    while the legacy ``gh release view --json ...`` form returned
+    ``isDraft`` / ``tagName`` / ``url``. :func:`run_publish` and the
+    existing test fixtures consume the legacy field names; we normalise
+    once here so the transport change is an internal-implementation
+    detail. The REST ``id`` field is added (it had no pre-#961 analogue)
+    because :func:`edit_release_publish` needs it for the PATCH URL.
+    """
+    return {
+        "isDraft": bool(rest_payload.get("draft", False)),
+        "name": rest_payload.get("name"),
+        "tagName": rest_payload.get("tag_name"),
+        "url": rest_payload.get("html_url"),
+        "id": rest_payload.get("id"),
+    }
+
+
+# Endpoint used by the paginated list+filter lookup (#1016). Exposed as a
+# module-level constant so tests can pin the argv shape without
+# duplicating the literal.
+_RELEASES_LIST_ENDPOINT_TEMPLATE = "repos/{repo}/releases?per_page=100"
+
+
+def _gh_api_find_release_by_tag(
+    gh_path: str, repo: str, tag: str
+) -> tuple[str, dict | None, str]:
+    """Find a release by ``tag_name`` via paginated REST list (#1016).
+
+    The original #961 implementation called
+    ``GET /repos/<owner>/<repo>/releases/tags/<tag>``, which the GitHub
+    REST docs explicitly limit to PUBLISHED releases ("This returns the
+    latest published release for the specified tag"). DRAFT releases
+    were filtered out at the API layer, so the publish flow 404'd on
+    its canonical input. The fix (option 2 from #1016) lists ALL
+    releases via ``GET /repos/<owner>/<repo>/releases?per_page=100``
+    (paginated; ``gh api --paginate`` follows ``Link: rel="next"``
+    headers automatically and concatenates page arrays into one) and
+    filters client-side for ``tag_name == tag``. The first match wins;
+    if no entry matches, the helper returns ``not-found``.
+
+    Returns ``(state, payload, reason)`` matching
+    :func:`view_release`'s contract:
+
+    - ``"draft"`` -- matching release with ``draft=true`` (proceed)
+    - ``"published"`` -- matching release with ``draft=false`` (no-op)
+    - ``"not-found"`` -- no entry with ``tag_name == tag`` in the list
+    - ``"gh-error"`` -- gh failure (CLI missing, auth, network); the
+      ``reason`` carries the diagnostic
+
+    ``payload`` is normalised via :func:`_normalise_release_payload` so
+    callers see the legacy ``isDraft`` / ``tagName`` / ``url`` / ``id``
+    keys regardless of REST transport.
+    """
+    endpoint = _RELEASES_LIST_ENDPOINT_TEMPLATE.format(repo=repo)
+    # ``--paginate`` instructs gh to follow Link: rel="next" headers and
+    # emit a single concatenated JSON array for array endpoints. Bumped
+    # timeout vs the single-tag form because multi-page traversal can
+    # legitimately take longer on repos with hundreds of releases.
+    cmd = [gh_path, "api", "--paginate", endpoint]
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=120,
+            check=False,
+            env=os.environ.copy(),
+        )
+    except FileNotFoundError:
+        return "gh-error", None, "gh CLI not found on PATH"
+    if result.returncode != 0:
+        stderr = (result.stderr or "").strip()
+        return "gh-error", None, f"gh api {endpoint} failed: {stderr}"
+    try:
+        rest_payload = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        return "gh-error", None, f"gh api {endpoint} returned non-JSON: {exc}"
+    if not isinstance(rest_payload, list):
+        return "gh-error", None, (
+            f"gh api {endpoint} returned non-list "
+            f"({type(rest_payload).__name__})"
+        )
+    # First match wins. Drafts have no canonical SHA so equality on
+    # tag_name is the practical key per the #1016 issue body.
+    for entry in rest_payload:
+        if not isinstance(entry, dict):
+            continue
+        if entry.get("tag_name") != tag:
+            continue
+        payload = _normalise_release_payload(entry)
+        if payload.get("isDraft", False):
+            return "draft", payload, ""
+        return "published", payload, ""
+    return "not-found", None, f"release {tag} not found on {repo}"
+
+
+def view_release(version: str, repo: str) -> tuple[str, dict | None, str]:
+    """Probe the current state of the GitHub release for ``v<version>``.
+
+    REST-routed since #961, paginated list+filter since #1016 -- uses
+    ``gh api --paginate repos/<owner>/<repo>/releases?per_page=100``
+    against the ``core`` bucket so a depleted ``graphql`` bucket cannot
+    stall the publish, and so DRAFT releases (which the
+    ``/releases/tags/{tag}`` endpoint hides) are surfaced. The internal
+    ``payload`` shape is normalised to the legacy field names
+    (``isDraft`` / ``tagName`` / ``url`` / ``name`` plus ``id`` for the
+    downstream PATCH).
+
+    Returns ``(state, payload, reason)`` where ``state`` is one of:
+
+    - ``"draft"`` -- release exists with isDraft=true (proceed to publish)
+    - ``"published"`` -- release exists with isDraft=false (already done)
+    - ``"not-found"`` -- no list entry matches the requested tag
+    - ``"gh-error"`` -- gh failed for an unexpected reason (CLI missing,
+      auth, network); ``reason`` carries the diagnostic
+    """
+    gh_path = release._resolve_gh()
+    if gh_path is None:
+        return "gh-error", None, "gh CLI not found on PATH"
+    tag = f"v{version}"
+    return _gh_api_find_release_by_tag(gh_path, repo, tag)
+
+
+def edit_release_publish(
+    version: str, repo: str, release_id: int | None = None
+) -> tuple[bool, str]:
+    """Flip the release out of draft via REST PATCH (#961, #1016).
+
+    Replaces the legacy ``gh release edit ... --draft=false`` form
+    (which routed through GraphQL and failed under bucket exhaustion).
+    Up to two REST calls under the ``core`` bucket: (1) paginated GET
+    ``releases?per_page=100`` to resolve the release id (skipped when
+    ``release_id`` is supplied by the caller; the list+filter form
+    surfaces DRAFT releases that ``/releases/tags/<tag>`` would hide,
+    per #1016), then (2) PATCH ``releases/<id>`` with ``draft=false``.
+    The ``-F draft=false`` flag on ``gh api`` parses the literal
+    ``false`` as a boolean (not a string) per the gh CLI documentation,
+    so no JSON-payload tempfile is required for this single-field
+    mutation.
+
+    Args:
+        version: Release version (no leading ``v``); the tag is derived
+            as ``v<version>``.
+        repo: ``"owner/repo"`` slug.
+        release_id: Optional pre-resolved REST release id. When the
+            caller already has the id from a prior :func:`view_release`
+            call (the common case under :func:`run_publish`), supplying
+            it here elides the redundant GET. When ``None`` (default),
+            the helper performs the GET as before. Greptile P2-2 (#961).
+    """
+    gh_path = release._resolve_gh()
+    if gh_path is None:
+        return False, "gh CLI not found on PATH"
+    tag = f"v{version}"
+    # Step 1: resolve the release id via REST (only when caller did not
+    # supply one). Backward-compatible: existing callers passing only
+    # (version, repo) still get the lookup behaviour. Uses the same
+    # paginated list+filter form as :func:`view_release` so DRAFT
+    # releases are surfaced (#1016).
+    if release_id is None:
+        state, payload, reason = _gh_api_find_release_by_tag(
+            gh_path, repo, tag
+        )
+        if state == "not-found":
+            return False, f"release {tag} not found on {repo}"
+        if state == "gh-error":
+            return False, f"could not resolve release id: {reason}"
+        if not payload or payload.get("id") is None:
+            return False, f"release {tag} payload missing 'id' field"
+        release_id = payload["id"]
+    # Step 2: PATCH the release to flip draft=false.
+    endpoint = f"repos/{repo}/releases/{release_id}"
+    cmd = [
+        gh_path, "api", endpoint,
+        "--method", "PATCH",
+        "-F", "draft=false",
+    ]
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+            env=os.environ.copy(),
+        )
+    except FileNotFoundError:
+        return False, "gh CLI not found on PATH"
+    if result.returncode != 0:
+        return False, f"gh api {endpoint} (PATCH) failed: {result.stderr.strip()}"
+    return True, f"flipped {tag} to published"
+
+
+# ---- Pipeline ---------------------------------------------------------------
+
+
+def _emit(label: str, status: str) -> None:
+    # Resolve sys.stderr at call time (matches scripts/release.py emit pattern
+    # so test capture via capsys works).
+    print(f"[publish] {label}... {status}", file=sys.stderr)
+
+
+def run_publish(config: PublishConfig) -> int:
+    """Execute the publish pipeline; returns the process exit code."""
+    version = config.version
+    repo = config.repo
+    tag = f"v{version}"
+
+    # Step 1: view current state.
+    label = f"View {tag} on {repo}"
+    if config.dry_run:
+        # Dry-run text mirrors the post-#1016 REST surface: a paginated
+        # GET against `releases?per_page=100` (core bucket) filtered
+        # client-side for tag_name == <tag>, followed by a PATCH against
+        # `releases/<id>` carrying `-F draft=false`. The single-tag form
+        # `releases/tags/<tag>` was removed in #1016 because it 404s on
+        # DRAFT releases (the canonical publish input). The legacy
+        # GraphQL `gh release view` / `gh release edit` forms were
+        # removed in #961.
+        _emit(
+            label,
+            (
+                f"DRYRUN (would run "
+                f"`gh api --paginate repos/{repo}/releases?per_page=100` "
+                f"and filter for tag_name == {tag})"
+            ),
+        )
+        _emit(
+            f"Edit {tag}",
+            (
+                f"DRYRUN (would run "
+                f"`gh api -X PATCH repos/{repo}/releases/<id> -F draft=false`)"
+            ),
+        )
+        return EXIT_OK
+
+    state, payload, reason = view_release(version, repo)
+    if state == "not-found":
+        _emit(label, f"FAIL (release {tag} not found on {repo}: {reason})")
+        return EXIT_VIOLATION
+    if state == "gh-error":
+        _emit(label, f"FAIL ({reason})")
+        return EXIT_VIOLATION
+    if state == "published":
+        _emit(label, f"NOOP ({tag} is already published; nothing to do)")
+        return EXIT_OK
+    # state == "draft" -> proceed.
+    assert payload is not None
+    _emit(label, f"OK (draft found at {payload.get('url', '<no url>')})")
+
+    # Step 2: edit to flip draft=false. Pass the already-resolved release
+    # id from step 1 so edit_release_publish does not re-GET (P2-2).
+    label = f"Edit {tag} (--draft=false)"
+    ok, reason = edit_release_publish(
+        version, repo, release_id=payload.get("id")
+    )
+    if not ok:
+        _emit(label, f"FAIL ({reason})")
+        return EXIT_VIOLATION
+    _emit(label, f"OK ({reason})")
+
+    # Step 3: verify the edit actually flipped the draft state. A successful
+    # exit from `gh release edit` does not by itself prove the state changed
+    # (e.g. a stale cache, a permissions silently-noop, a wrong tag); the
+    # post-edit re-read is defense in depth so the script never reports
+    # success unless the consumer-visible state matches.
+    label = f"Verify {tag} is published"
+    state2, payload2, reason2 = view_release(version, repo)
+    if state2 != "published":
+        _emit(
+            label,
+            (
+                f"FAIL (post-edit state is {state2!r}; expected 'published'; "
+                f"reason: {reason2})"
+            ),
+        )
+        return EXIT_VIOLATION
+    _emit(label, f"OK ({tag} is now public)")
+
+    print(
+        f"Release {tag} published successfully on {repo}.",
+        file=sys.stderr,
+    )
+    return EXIT_OK
+
+
+# ---- main -------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        release._validate_version(args.version)
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return EXIT_CONFIG_ERROR
+
+    project_root = release._resolve_project_root(args.project_root)
+    repo = release._resolve_repo(args.repo, project_root)
+
+    config = PublishConfig(
+        version=args.version,
+        repo=repo,
+        project_root=project_root,
+        dry_run=args.dry_run,
+    )
+    return run_publish(config)
+
+
+if __name__ == "__main__":
+    sys.exit(main())