@deftai/directive-content 0.58.0 → 0.60.0

package/scripts/release_publish.py

@@ -1,486 +0,0 @@
-#!/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())