bmsdna-devtools 0.2.0__py3-none-any.whl

bmsdna/devtools/ado_auth.py

@@ -0,0 +1,37 @@
+"""Azure DevOps auth: explicit PAT, or fall back to the caller's `az` login."""
+
+from __future__ import annotations
+
+import base64
+import subprocess
+import sys
+
+from .cli_tools import require_az
+
+# Well-known Azure DevOps resource ID for `az account get-access-token`.
+ADO_RESOURCE_ID = "499b84ac-1321-427f-aa17-267ca6975798"
+
+
+def get_az_devops_token() -> str:
+    az = require_az()
+    result = subprocess.run(
+        [az, "account", "get-access-token", "--resource", ADO_RESOURCE_ID, "--query", "accessToken", "-o", "tsv"],
+        capture_output=True,
+        encoding="utf-8",
+    )
+    if result.returncode != 0:
+        sys.exit(f"az login required and no PAT provided.\n{result.stderr.strip()}")
+    return result.stdout.strip()
+
+
+def auth_header(pat: str | None) -> dict[str, str]:
+    """Basic-auth header for an explicit PAT, else Bearer via `az` token.
+
+    Never hardcode a PAT literal in a caller — pass it in from an env var
+    (e.g. AZURE_DEVOPS_PAT) or a CLI flag, or omit it and let `az` supply a
+    short-lived token from the operator's own login.
+    """
+    if pat:
+        token = base64.b64encode(f":{pat}".encode()).decode()
+        return {"Authorization": f"Basic {token}"}
+    return {"Authorization": f"Bearer {get_az_devops_token()}"}

bmsdna/devtools/app_service_logs.py

@@ -0,0 +1,76 @@
+"""Download an Azure App Service log archive and filter it for errors/warnings.
+
+Pulls the log zip via `az webapp log download`, unpacks it in memory, and
+writes every line matching common error/warning markers to a filtered file.
+The webapp/resource-group/slot for a given `--env` come from the consuming
+repo's pyproject.toml (see env_config.py) rather than being baked in here.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import subprocess
+import sys
+import zipfile
+
+from .cli_tools import require_az
+
+# Matches common error/warning markers across granian, uvicorn, and python tracebacks.
+ERROR_RE = re.compile(r"\b(ERROR|CRITICAL|WARNING|Traceback|Exception|\b[45]\d\d\b|FAILED|FATAL)\b")
+
+
+def run_az(args: list[str]) -> str:
+    az = require_az()
+    proc = subprocess.run([az, *args], capture_output=True, encoding="utf-8")
+    if proc.returncode != 0:
+        sys.exit(proc.stderr.strip() or proc.stdout.strip())
+    return proc.stdout
+
+
+def download_logs(webapp: str, resource_group: str, slot: str, archive: pathlib.Path) -> None:
+    print(f"Downloading logs for {webapp}/{slot}...", flush=True)
+    run_az([
+        "webapp", "log", "download",
+        "--name", webapp,
+        "--resource-group", resource_group,
+        "--slot", slot,
+        "--log-file", str(archive),
+    ])
+
+
+def extract_errors(archive: pathlib.Path, error_file: pathlib.Path) -> int:
+    """Unzip the archive and write all matching lines to error_file. Returns count."""
+    count = 0
+    with zipfile.ZipFile(archive) as zf, error_file.open("w") as out:
+        for member in zf.namelist():
+            if member.endswith("/"):
+                continue
+            with zf.open(member) as fh:
+                for raw in fh:
+                    line = raw.decode("utf-8", "replace")
+                    if ERROR_RE.search(line):
+                        out.write(f"{member}: {line}")
+                        count += 1
+    return count
+
+
+def fetch(
+    webapp: str,
+    resource_group: str,
+    slot: str,
+    out_dir: pathlib.Path,
+    keep_archive: bool = False,
+) -> pathlib.Path:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    archive = out_dir / f"{slot}_logs.zip"
+    error_file = out_dir / f"{slot}_errors.log"
+
+    download_logs(webapp, resource_group, slot, archive)
+    count = extract_errors(archive, error_file)
+
+    if not keep_archive:
+        archive.unlink()
+
+    print(f"✓ {count} error/warning lines → {error_file}")
+    return error_file

bmsdna/devtools/cli.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+
+from . import app_service_logs, commit as commit_mod
+from . import env_config
+from . import gh_pr
+from . import logs as logs_mod
+from . import pr_build, worktree as worktree_mod
+from .cli_tools import require_az, require_gh
+from .gitrepo import GitHubRemote, current_branch, current_remote
+
+# Non-ASCII output (checkmarks, en-dashes in ADO project names, etc.) needs a
+# UTF-8 stream — the default Windows console codepage isn't UTF-8, and would
+# otherwise raise UnicodeEncodeError on the first ✓/✗ printed.
+if sys.platform == "win32":
+    sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+    sys.stderr.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+
+app = typer.Typer(name="bdt", help="Shared BMS developer tooling: PRs/builds (Azure DevOps or GitHub), worktrees, commits, logs")
+
+pr_app = typer.Typer(name="pr", help="Pull request commands (Azure DevOps or GitHub, auto-detected from the git remote)")
+app.add_typer(pr_app, name="pr")
+
+logs_app = typer.Typer(name="logs", help="Application Insights / Log Analytics queries")
+app.add_typer(logs_app, name="logs")
+
+
+@pr_app.command("create")
+def pr_create(
+    target: str = typer.Option("main", "--target", help="Target branch (e.g. main, test)"),
+    args: list[str] = typer.Argument(None, help="Extra args passed through to `az repos pr create` / `gh pr create`"),
+) -> None:
+    """Create a PR from the current branch into --target (Azure DevOps or GitHub, auto-detected)."""
+    remote = current_remote()
+    if isinstance(remote, GitHubRemote):
+        raise typer.Exit(gh_pr.create(require_gh(), target, args or []))
+
+    az = require_az()
+    cmd = [
+        az, "repos", "pr", "create",
+        "--target-branch", target,
+        "--source-branch", current_branch(),
+        "--auto-complete", "false",
+        *(args or []),
+    ]
+    raise typer.Exit(subprocess.run(cmd).returncode)
+
+
+@pr_app.command("status")
+def pr_status(
+    target_branch: str = typer.Option("main", "--target-branch", help="Target branch of the PR (Azure DevOps only — gh has no equivalent filter, it always resolves the PR for the current branch)"),
+    wait: bool = typer.Option(False, "--wait", help="Poll until all pipelines/checks are completed"),
+    pat: str | None = typer.Option(None, "--pat", envvar="AZURE_DEVOPS_PAT", help="Azure DevOps PAT (else falls back to `az` login)"),
+) -> None:
+    """Show build/check status for the PR opened from the current branch (Azure DevOps or GitHub, auto-detected)."""
+    remote = current_remote()
+    if isinstance(remote, GitHubRemote):
+        gh_pr.run(require_gh(), wait)
+        return
+    pr_build.run(remote, pat, target_branch, wait)
+
+
+@app.command()
+def worktree(
+    name: str,
+    base: str = typer.Option("dev", "--base", help="Branch to base the new worktree on"),
+    env_file: str | None = typer.Option(None, "--env-file", help="File to copy into the worktree as .env (default: auto-detect .local_env then .env)"),
+    submodules: bool = typer.Option(True, "--submodules/--no-submodules", help="Run `git submodule update --init` in the new worktree"),
+    install: str | None = typer.Option(None, "--install", help="Shell command to run inside the new worktree after creation, e.g. 'just install'"),
+) -> None:
+    """Create a git worktree under .worktrees/<name>, mirroring the `just worktree` recipe."""
+    install_cmd = install.split() if install else None
+    worktree_mod.create(name, base=base, env_file=env_file, submodules=submodules, install_cmd=install_cmd)
+
+
+@app.command()
+def commit(
+    message: str,
+    files: list[str],
+    json_output: bool = typer.Option(False, "--json", help="Structured JSON output for AI-agent callers"),
+    no_verify: bool = typer.Option(False, "--no-verify", help="Skip pre-commit hooks"),
+    subrepo: list[str] = typer.Option([], "--subrepo", help="Submodule directory name to split matching files into (repeatable)"),
+    skip_message_check: bool = typer.Option(False, "--skip-message-check", help="Don't require a conventional-commit-style message"),
+    allow_main: bool = typer.Option(False, "--allow-main", help="Allow committing directly on main/master"),
+) -> None:
+    """Stage, commit, and push files, with pre-flight checks and a pre-commit-hook retry."""
+    result = commit_mod.commit_and_push(
+        message,
+        files,
+        no_verify=no_verify,
+        require_message_quality=not skip_message_check,
+        require_feature_branch=not allow_main,
+        subrepos=subrepo,
+    )
+    commit_mod.emit(result, use_json=json_output)
+
+
+@logs_app.command("roles")
+def logs_roles(
+    resource_group: str = typer.Option(..., "--resource-group", envvar="AZURE_RESOURCE_GROUP"),
+    app_insights: str = typer.Option(..., "--app-insights", envvar="AZURE_APP_INSIGHTS"),
+    minutes: int = typer.Option(30, "--minutes"),
+) -> None:
+    """List cloud_RoleName values seen in the last N minutes (to pick a --role for `logs tail`)."""
+    logs_mod.print_roles(app_insights, resource_group, minutes)
+
+
+@logs_app.command("tail")
+def logs_tail(
+    role: str = typer.Option(..., "--role", help="cloud_RoleName to filter; 'all' for no filter"),
+    resource_group: str = typer.Option(..., "--resource-group", envvar="AZURE_RESOURCE_GROUP"),
+    app_insights: str = typer.Option(..., "--app-insights", envvar="AZURE_APP_INSIGHTS"),
+    minutes: int = typer.Option(30, "--minutes"),
+    level: str = typer.Option("verbose", "--level", help=f"Minimum severity: {', '.join(logs_mod.SEVERITY_MAP)}"),
+    no_color: bool = typer.Option(False, "--no-color"),
+) -> None:
+    """Fetch recent traces/exceptions for a role from Application Insights."""
+    logs_mod.print_logs(app_insights, resource_group, minutes, level, role, no_color)
+
+
+@logs_app.command("fetch")
+def logs_fetch(
+    env: str = typer.Option(..., "--env", help="Named environment configured under tool.bdt.envs in pyproject.toml"),
+    out: Path = typer.Option(Path("logs"), "--out", help="Output directory for the extracted error log"),
+    keep_archive: bool = typer.Option(False, "--keep-archive", help="Keep the downloaded .zip instead of deleting it"),
+) -> None:
+    """Download an App Service log archive and extract error/warning lines."""
+    cfg = env_config.resolve_env(env)
+    app_service_logs.fetch(cfg["webapp"], cfg["resource_group"], cfg["slot"], out, keep_archive=keep_archive)
+
+
+if __name__ == "__main__":
+    app()

bmsdna/devtools/cli_tools.py

@@ -0,0 +1,31 @@
+"""Locating required external CLIs (az, gh) with clear errors when missing.
+
+Uses `shutil.which` rather than a bare command name so Windows .cmd/.bat/.exe
+shims (e.g. az.cmd from the MSI installer) resolve correctly via PATHEXT —
+the same lookup `where`/`Get-Command` would do — instead of guessing an
+extension or relying on shell=True (which also avoids any shell-quoting
+concerns for arguments that come from user input, e.g. PR titles).
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+
+AZ_INSTALL_HINT = "Install the Azure CLI: https://learn.microsoft.com/cli/azure/install-azure-cli"
+GH_INSTALL_HINT = "Install the GitHub CLI: https://cli.github.com"
+
+
+def require_tool(name: str, install_hint: str) -> str:
+    path = shutil.which(name)
+    if not path:
+        sys.exit(f"'{name}' is required for this command but wasn't found on PATH.\n{install_hint}")
+    return path
+
+
+def require_az() -> str:
+    return require_tool("az", AZ_INSTALL_HINT)
+
+
+def require_gh() -> str:
+    return require_tool("gh", GH_INSTALL_HINT)

bmsdna/devtools/commit.py

@@ -0,0 +1,204 @@
+"""Commit-and-push helper: pre-flight checks, one retry after a pre-commit
+reformat, optional JSON output for AI-agent callers, optional subrepo split
+for repos that vendor a submodule (e.g. a `database/` git submodule).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from dataclasses import dataclass, field
+
+IS_SANDBOX_ENV_VAR = "IS_BMS_AI_SANDBOX"
+
+
+def _run(cmd: list[str], cwd: str | None = None) -> subprocess.CompletedProcess:
+    try:
+        return subprocess.run(cmd, capture_output=True, encoding="utf-8", cwd=cwd)
+    except FileNotFoundError:
+        sys.exit("'git' is required for this command but wasn't found on PATH.")
+
+
+def _sha(cwd: str | None = None) -> str | None:
+    r = _run(["git", "rev-parse", "--short", "HEAD"], cwd=cwd)
+    return r.stdout.strip() if r.returncode == 0 else None
+
+
+def _in_sandbox() -> bool:
+    return os.getenv(IS_SANDBOX_ENV_VAR, "0").lower() in ("1", "true", "yes")
+
+
+@dataclass
+class CommitResult:
+    success: bool
+    committed: bool
+    pushed: bool
+    message: str
+    files: list[str]
+    commit_sha: str | None = None
+    error: str | None = None
+    hint: str | None = None
+    extra: dict = field(default_factory=dict)
+
+    def as_dict(self) -> dict:
+        d = {
+            "success": self.success,
+            "committed": self.committed,
+            "pushed": self.pushed,
+            "message": self.message,
+            "files": self.files,
+            "commit_sha": self.commit_sha,
+            "error": self.error,
+            "hint": self.hint,
+        }
+        d.update(self.extra)
+        return d
+
+
+def _git_commit(message: str, cwd: str | None = None, no_verify: bool = False) -> subprocess.CompletedProcess:
+    cmd = ["git", "commit", "-m", message]
+    if no_verify:
+        cmd.append("--no-verify")
+    return _run(cmd, cwd=cwd)
+
+
+def _commit_with_retry(
+    message: str, files: list[str], cwd: str | None, no_verify: bool
+) -> tuple[bool, subprocess.CompletedProcess | None]:
+    """Commit, retrying once (re-`git add`) if a pre-commit hook reformatted files."""
+    _run(["git", "add", *files], cwd=cwd)
+    r = _git_commit(message, cwd=cwd, no_verify=no_verify)
+    if r.returncode == 0:
+        return True, None
+    if "nothing to commit" in r.stdout + r.stderr:
+        return False, None
+    _run(["git", "add", *files], cwd=cwd)
+    r2 = _git_commit(message, cwd=cwd, no_verify=no_verify)
+    if r2.returncode == 0:
+        return True, None
+    return False, r2
+
+
+def commit_and_push(
+    message: str,
+    files: list[str],
+    *,
+    no_verify: bool = False,
+    require_message_quality: bool = True,
+    require_feature_branch: bool = True,
+    subrepos: list[str] | None = None,
+) -> CommitResult:
+    """Stage, commit, and push `files`, applying the same pre-flight checks
+    and pre-commit-hook retry as the per-repo `commit.py` scripts.
+
+    `subrepos` is a list of submodule directory names (e.g. ["database"]);
+    files under one of those prefixes are committed/pushed inside the
+    submodule first, then the submodule bump is staged in the parent repo.
+    """
+    # Normalize to forward slashes so subrepo-prefix matching below works the
+    # same whether a caller passes "database/x.sql" or "database\x.sql" (both
+    # os.path.exists and git accept either separator fine on Windows).
+    files = [f.replace("\\", "/") for f in files]
+    subrepos = subrepos or []
+    print("pre-flight checks:", flush=True)
+
+    def check(ok: bool, label: str) -> bool:
+        print(f"  {'✓' if ok else '✗'} {label}", file=sys.stdout if ok else sys.stderr)
+        return ok
+
+    missing = [f for f in files if not os.path.exists(f)]
+    if not check(not missing, "files exist"):
+        return CommitResult(
+            False, False, False, message, files,
+            error=f"File not found: {missing[0]} — did you typo the path? Run `git status` to see changed files",
+            hint=f"Run `git status` to see what files are actually changed. Missing: {missing}",
+        )
+
+    msg_ok = not require_message_quality or (len(message) >= 20 and ":" in message)
+    if not check(msg_ok, "commit message quality (len>=20, has colon)"):
+        return CommitResult(
+            False, False, False, message, files,
+            error=f"Commit message too short or missing type prefix (e.g. 'feat(x): ...') — got: {message!r}",
+            hint="Use conventional commits format: 'feat(scope): description' or 'fix: description'",
+        )
+
+    current_branch = _run(["git", "rev-parse", "--abbrev-ref", "HEAD"]).stdout.strip()
+    branch_ok = not require_feature_branch or current_branch not in ("main", "master")
+    if not check(branch_ok, f"not on main/master (branch: {current_branch})"):
+        return CommitResult(
+            False, False, False, message, files,
+            error=f"Direct push to {current_branch} blocked — create a feature branch first",
+            hint="Run `git checkout -b feat/my-branch` to create a feature branch first.",
+        )
+
+    main_files = list(files)
+    for subrepo in subrepos:
+        prefix = subrepo + "/"
+        subrepo_files = [f[len(prefix):] for f in files if f.startswith(prefix)]
+        main_files = [f for f in main_files if not f.startswith(prefix) and f != subrepo]
+        if not subrepo_files:
+            continue
+
+        ok, failure = _commit_with_retry(message, subrepo_files, cwd=subrepo, no_verify=no_verify)
+        if failure is not None:
+            return CommitResult(
+                False, False, False, message, subrepo_files,
+                error=(failure.stdout + failure.stderr).strip(),
+                hint="Pre-commit hook may have failed in the subrepo. Check the error output above.",
+            )
+        if ok and not _in_sandbox():
+            pr = _run(["git", "push"], cwd=subrepo)
+            if pr.returncode != 0:
+                return CommitResult(
+                    False, True, False, message, subrepo_files,
+                    commit_sha=_sha(cwd=subrepo),
+                    error=(pr.stdout + pr.stderr).strip(),
+                    hint=f"Push failed. Try `git pull --rebase` in the {subrepo} submodule.",
+                )
+            print(f"  ✓ {subrepo} subrepo pushed", flush=True)
+        if ok:
+            main_files.append(subrepo)
+
+    ok, failure = _commit_with_retry(message, main_files, cwd=None, no_verify=no_verify)
+    if failure is not None:
+        return CommitResult(
+            False, False, False, message, files,
+            error=(failure.stdout + failure.stderr).strip(),
+            hint="Pre-commit hook may have reformatted files and failed. Check output.",
+        )
+    committed = ok
+    print("  ✓ committed", flush=True)
+
+    if _in_sandbox():
+        return CommitResult(True, committed, False, message, files, commit_sha=_sha())
+
+    pr = _run(["git", "push"])
+    if pr.returncode != 0:
+        return CommitResult(
+            True, committed, False, message, files,
+            commit_sha=_sha(),
+            error=(pr.stdout + pr.stderr).strip(),
+            hint="Push rejected. Run `git pull --rebase`, resolve conflicts, then retry.",
+        )
+
+    print("  ✓ pushed", flush=True)
+    return CommitResult(True, committed, True, message, files, commit_sha=_sha())
+
+
+def emit(result: CommitResult, *, use_json: bool) -> None:
+    if use_json:
+        print(json.dumps(result.as_dict(), indent=2))
+    elif result.success:
+        if not result.committed:
+            print("nothing to commit")
+        elif not result.pushed:
+            print("committed (sandbox mode, push handled separately)")
+        else:
+            print("committed & pushed")
+    else:
+        print(f"ERROR: {result.error}", file=sys.stderr)
+        if result.hint:
+            print(f"HINT: {result.hint}", file=sys.stderr)
+    sys.exit(0 if result.success else 1)

bmsdna/devtools/env_config.py

@@ -0,0 +1,61 @@
+"""Named environments for `bdt logs fetch`, configured in the consuming repo's
+pyproject.toml under [tool.bdt.envs.<name>].
+
+This lets a repo define its webapp/resource-group/slot combinations once
+(e.g. "prod", "staging") instead of passing all three flags on every call.
+"""
+
+from __future__ import annotations
+
+import sys
+import tomllib
+from pathlib import Path
+
+REQUIRED_KEYS = ("webapp", "resource_group", "slot")
+
+CONFIG_EXAMPLE = """\
+[tool.bdt.envs.prod]
+webapp = "my-app"
+resource_group = "my-app-rg"
+slot = "production"
+"""
+
+
+def _find_pyproject(start: Path) -> Path | None:
+    for directory in (start, *start.parents):
+        candidate = directory / "pyproject.toml"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load_envs(start: Path | None = None) -> dict[str, dict[str, str]]:
+    path = _find_pyproject(start or Path.cwd())
+    if path is None:
+        return {}
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+    envs = data.get("tool", {}).get("bdt", {}).get("envs", {})
+    return envs if isinstance(envs, dict) else {}
+
+
+def resolve_env(name: str, start: Path | None = None) -> dict[str, str]:
+    """Look up a named environment, exiting with an actionable message if it's missing."""
+    envs = load_envs(start)
+    if not envs:
+        sys.exit(
+            "ERROR: no environments configured. Add a [tool.bdt.envs.<name>] table "
+            f"to pyproject.toml, e.g.:\n\n{CONFIG_EXAMPLE}"
+        )
+    if name not in envs:
+        available = ", ".join(sorted(envs))
+        sys.exit(f"ERROR: unknown --env '{name}'. Configured environments: {available}")
+
+    env = envs[name]
+    missing = [k for k in REQUIRED_KEYS if k not in env]
+    if missing:
+        sys.exit(
+            f"ERROR: [tool.bdt.envs.{name}] in pyproject.toml is missing required "
+            f"key(s): {', '.join(missing)}"
+        )
+    return env