gozu 0.3.7__tar.gz

gozu-0.3.7/.dockerignore

@@ -0,0 +1,12 @@
+# Copyright (c) 2026 Calfus Inc.
+# Author: Wasiullah Rafeeq S
+
+.git
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.scannerwork
+.env

gozu-0.3.7/.env.example

@@ -0,0 +1,58 @@
+# Copyright (c) 2026 Calfus Inc.
+# Author: Wasiullah Rafeeq S
+
+# --- Phase 1 infrastructure (docker-compose.yml) ---
+# Don't fill these in by hand - run `python src/scripts/bootstrap_env.py` once
+# to generate a real .env with a random Postgres password and a fresh
+# Fernet key. See README.md's "Phase 1: Infrastructure" section.
+POSTGRES_USER=sonarjira
+POSTGRES_PASSWORD=
+POSTGRES_DB=sonarjira
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+
+# Fernet key used by crypto_utils.py to encrypt/decrypt secrets stored in
+# the configs table (sonar_token, jira_api_token, webhook_secret).
+FERNET_KEY=
+
+# Temporal server address. docker-compose.yml overrides this to
+# temporal:7233 for the worker container.
+TEMPORAL_HOST=localhost:7233
+
+# --- SonarQube webhook ---
+# Shared secret configured in the SonarQube webhook settings (Administration > Webhooks).
+# SonarQube signs each webhook payload with this secret and sends the signature in the
+# X-Sonar-Webhook-HMAC-SHA256 header.
+SONAR_WEBHOOK_SECRET=changeme
+
+# --- Scanner backend ---
+# "sonarqube" = self-hosted SonarQube Community Build (SonarQubeServerClient)
+# "sonarqube-cloud" = SonarQube Cloud (SonarQubeCloudClient) - not implemented yet
+# (SONAR_MODE "local"/"cloud" is still read as a fallback if this is unset)
+SCANNER_TYPE=sonarqube
+
+# Base URL of your SonarQube instance
+SONAR_HOST_URL=http://localhost:9000
+
+# User token generated in SonarQube (My Account > Security > Generate Tokens)
+SONAR_TOKEN=
+
+# Only used when SONAR_MODE=cloud
+SONAR_ORGANIZATION=
+
+# --- Ticket backend ---
+# "jira" = Jira Cloud (JiraClient) - the only implementation right now
+TICKET_BACKEND=jira
+
+# --- Jira ---
+# Base URL of your Jira Cloud site, e.g. https://your-domain.atlassian.net
+JIRA_URL=
+
+# Email address of the Jira account the API token belongs to
+JIRA_EMAIL=
+
+# API token generated at https://id.atlassian.com/manage-profile/security/api-tokens
+JIRA_API_TOKEN=
+
+# Key of the Jira project tickets should be created in, e.g. "SONAR"
+JIRA_PROJECT_KEY=

gozu-0.3.7/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+# Copyright (c) 2026 Calfus Inc.
+# Author: Prakrit Mohanty
+# Editor: Wasiullah Rafeeq S
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest -v

gozu-0.3.7/.github/workflows/release.yml

@@ -0,0 +1,69 @@
+# Copyright (c) 2026 Calfus Inc.
+# Author: Prakrit Mohanty
+# Editor: Wasiullah Rafeeq S
+
+name: Release
+
+# Triggered by pushing a version tag, e.g.:
+#   git tag v0.1.0 && git push origin v0.1.0
+# The tag (minus its leading "v") must match pyproject.toml's [project]
+# version exactly - the version-check step below fails fast if they drift,
+# rather than silently publishing a release with the wrong version string.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build-and-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Check tag matches pyproject.toml version
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version="$(uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          if [ "$tag_version" != "$pkg_version" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME (version $tag_version) doesn't match pyproject.toml's version $pkg_version"
+            exit 1
+          fi
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest -v
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      # Trusted publishing (OIDC): the "gozu" project on PyPI trusts this
+      # repo's release.yml, so no PyPI token/secret is needed - uv exchanges
+      # the id-token permission above for a short-lived upload credential.
+      # Runs before the GitHub Release so a failed upload leaves no release.
+      - name: Publish to PyPI
+        run: uv publish
+
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes

gozu-0.3.7/.github/workflows/sonar-to-jira-main.yml

@@ -0,0 +1,69 @@
+# Copyright (c) 2026 Calfus Inc.
+# Author: Prakrit Mohanty
+
+name: Sonar to Jira (main)
+
+# Reacts to SonarQube Cloud's Automatic Analysis (which scans `main` on
+# every push automatically, no scan step needed here - see
+# docs.sonarsource.com/sonarqube-cloud/analyzing-source-code/automatic-analysis)
+# by waiting for that analysis to land, then creating Jira tickets for new
+# findings - see src/github_action/main.py.
+#
+# Deliberately scoped to `main` only: SonarQube Cloud's Free plan rejects
+# querying issue data for any other branch ("Organization is not allowed
+# to access data from non main branches" - confirmed live, see
+# src/cli/scan_runner/scanner_exec.py's comment), so a PR-time equivalent of
+# this workflow cannot work on Free.
+#
+# Runs entirely inside GitHub's own runner - unlike gozu's webhook trigger
+# mode, this needs no receiver reachable from the public internet, only
+# outbound calls to SonarQube Cloud's and Jira's APIs.
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: sonar-to-jira-main
+  cancel-in-progress: false
+
+jobs:
+  create-tickets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # Installs from this exact checkout, not a GitHub Release URL -
+      # this repo is private, and pip has no credentials to fetch a
+      # private repo's release asset (confirmed live: a plain
+      # `pip install <release url>` 404s here even though the release
+      # itself exists - GitHub returns 404, not 401/403, for a private
+      # resource fetched unauthenticated). Installing from the checkout
+      # also means this never drifts from whatever version is actually on
+      # main. Swap for `pip install gozu` once this is published to PyPI.
+      - name: Install gozu
+        run: pip install .
+
+      - name: Wait for analysis and create Jira tickets
+        env:
+          SCANNER_TYPE: sonarqube-cloud
+          SONAR_HOST_URL: https://sonarcloud.io
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_ORGANIZATION: ${{ secrets.SONAR_ORGANIZATION }}
+          SONAR_PROJECT_KEY: ${{ secrets.SONAR_PROJECT_KEY }}
+          TICKET_BACKEND: jira
+          JIRA_URL: ${{ secrets.JIRA_URL }}
+          JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
+          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
+          JIRA_PROJECT_KEY: ${{ secrets.JIRA_PROJECT_KEY }}
+          COMMIT_TIMESTAMP: ${{ github.event.head_commit.timestamp }}
+          # Optional - blank/unset disables LLM-generated ticket explanations
+          # for Blocker/Critical/High findings (see src/llm/enrich.py); tickets
+          # fall back to today's templated description either way.
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: gozu-github-action

gozu-0.3.7/.gitignore

@@ -0,0 +1,17 @@
+# Copyright (c) 2026 Calfus Inc.
+# Author: Wasiullah Rafeeq S
+
+.env
+docker-compose.override.yml
+.venv/
+venv/
+__pycache__/
+*.pyc
+.ruff_cache/
+.scannerwork/
+
+# ARCHITECTURE.md and Setup.md live here now - kept on disk for local
+# reference but no longer tracked (README.md/CLAUDE.md stay at repo root,
+# tracked, since GitHub's repo homepage and Claude Code's own context
+# loading both depend on those two specific paths).
+docs/

gozu-0.3.7/CLAUDE.md

@@ -0,0 +1,187 @@
+# Project conventions
+
+## The product
+
+This repo is being built into a commercial CLI tool called **Gozu** (the
+name is decided, not a placeholder - use it consistently: the command is
+`gozu`, host-side dirs like `~/.gozu/`). The repo/working directory stays
+`sonar-to-jira` for now - don't rename it without checking first, since
+that's a separate decision from the product's own name.
+It's scanner- and ticket-backend-agnostic by design: users scan code with
+a pluggable choice of scanners (currently SonarQube, Trivy, and Semgrep) and get
+tickets auto-created in a pluggable choice of ticket-tracking backends
+(currently Jira), orchestrated with Temporal. These are the first concrete
+implementations, not the definition of the tool - don't write new
+docs/help text that implies gozu is confined to either. The build is happening in
+phases (Phase 1: Docker Compose infra + encrypted config store. Phase 2:
+`gozu init`, the setup wizard - see README.md for both); check with
+the user before assuming a later phase's scope (e.g. `gozu run`,
+actually running a scan) is open to work on.
+
+## CLI conventions (Phase 2+)
+
+- The `src/cli/` package holds everything CLI-specific: `main.py` (the typer
+  app), `init_wizard/`, `scan_runner/`, `prerequisites/` (each a small
+  package, one file per step/concern - see their own docstrings), plus
+  `help_links.py` and `stack.py`.
+- Every interactive select/confirm prompt uses **questionary** (arrow-key
+  menus), not typed option strings or plain `input()` - this is a fixed
+  choice for this project, not a per-prompt toss-up, given how many
+  branching selects the wizard has.
+- Packaging is **uv**, not pip/`requirements.txt` (removed). Dependencies
+  live in `pyproject.toml`'s `[project.dependencies]`, pinned via
+  `uv.lock`. Install with `uv sync`; run things with `uv run <cmd>` or an
+  activated `.venv`. The worker `Dockerfile` builds via `uv sync --frozen`
+  against the same `pyproject.toml`/`uv.lock`, not a separate
+  requirements file - keep it that way rather than hand-maintaining two
+  dependency lists.
+- A credential/doc-link helper (`src/cli/help_links.py`'s `HELP_LINKS`) must
+  use real, current URLs looked up live (WebSearch or equivalent) - never
+  a plausible-looking guessed URL.
+
+## Naming: "configs", not "profiles"
+
+A saved, named set of scanner + ticket-backend credentials (see
+`db/migrations/versions/0001_initial_schema.py`'s `configs` table, `src/config/store.py`) is called a **config**,
+never a "profile". Docker Compose already has an unrelated built-in concept
+called profiles (`docker-compose.yml`'s `profiles: [...]` on the
+`sonarqube` service, for conditionally starting services) - reusing "profile"
+for credential sets would be confusing throughout the codebase and docs
+given both concepts exist side by side in this project.
+
+## Data models
+
+Use **Pydantic `BaseModel`** for every data model in this project - never
+`dataclasses.dataclass` or plain classes. This includes types that cross a
+Temporal workflow/activity boundary (`Finding`, `CreatedTicket`,
+`TicketResult`, `SonarToJiraInput`, `ScreenshotAttachInput`) and any new
+ones added later (e.g. `ScannerRequirements`, `FindingExtraction`). The
+Pydantic-aware data converter (`src/temporal/data_converter.py`) serializes
+`BaseModel`s across that boundary automatically - a plain dataclass or
+dict does not, and needs manual conversion, which is exactly what we
+removed by standardizing on Pydantic.
+
+## Logging
+
+Use **exactly one** logging mechanism inside the Temporal-executed pipeline:
+
+- `workflow.logger` (from `temporalio.workflow`) inside workflow code
+  (`src/temporal/workflows/`).
+- `activity.logger` (from `temporalio.activity`) everywhere else that runs
+  inside an activity - the activity functions themselves
+  (`src/temporal/activities/`) and every module they call into
+  (`src/scanner/`, `src/ticket/`).
+
+Both are Temporal's contextual loggers - they tag every line with
+workflow/activity id, run id, attempt number, etc, and route to the same
+place `workflow.logger`/`activity.logger` already do. Don't create a plain
+`logging.getLogger(__name__)` logger in any file that runs inside an
+activity or workflow.
+
+The only exception is the two process entrypoints, which run before any
+Temporal workflow/activity context exists: `src/receiver/app.py` (Flask, before
+a workflow is started) and `src/temporal/worker.py` (bootstrap, before
+`worker.run()`). Those use plain `logging.basicConfig`/`logging.getLogger`
+because there's nothing to attach Temporal context to yet.
+
+Do not introduce a third logging approach (e.g. `print`, a custom logger
+wrapper, structlog, etc) anywhere in this project.
+
+## Code style: modular, reusable, no needless duplication
+
+Favor small, single-responsibility functions over long ones, and pull out
+a shared helper the moment the same shape of logic appears twice - don't
+wait for a third copy. Concretely, follow the patterns already in this
+codebase rather than inventing new ones:
+
+- **Pure-builder + env-reading-wrapper split**, for anything that can be
+  configured either explicitly or from the environment: `src/scanner/factory.py`'s
+  `build_scanner_client(scanner_type, scanner_mode, credentials)` (no env
+  reads) vs `get_scanner_client()` (reads env vars, delegates to the
+  builder); `src/ticket/factory.py`'s `build_ticket_client()`/`get_ticket_client()`
+  mirror it. When adding a new backend or a new per-config code path, add
+  to the pure builder and let the env-reading wrapper stay a thin
+  translation layer - don't duplicate the branching in both.
+- **Extract shared download/verify logic**, not per-tool copies: see
+  `src/cli/prerequisites/archive.py`'s `download_archive()`/`extract_archive()`/
+  `make_tree_executable()`/`verify_runnable()`, shared by `java.py`'s
+  `ensure_java()` and `sonar_scanner.py`'s `ensure_sonar_scanner()`. A third
+  `ensure_*()` for a new host dependency should reuse these, not reimplement
+  its own download loop. Same idea for small derived values used in more
+  than one place - e.g. `src/cli/scan_runner/config_fields.py`'s
+  `scanner_host_url(config)`, computed once and reused rather than
+  recomputed per call site.
+- **Dedicated, narrow Pydantic models per activity boundary** (interface
+  segregation) rather than one bloated shared input model: `fetch_findings_activity`
+  takes `FetchFindingsInput`, `create_tickets_activity` takes
+  `CreateTicketsInput`, not the full `SonarToJiraInput` - each activity
+  only sees the fields it actually needs.
+
+This isn't a call for premature abstraction - three near-identical lines
+inline are still fine. It's specifically about not letting the same
+piece of logic (a download-and-verify flow, a client-construction
+branch, a derived value) exist in more than one place at a time.
+
+## File headers: copyright/author on every file, every machine
+
+Every source file in this repo carries a header, added retroactively in
+one pass and required on every new file since - this must happen the same
+way regardless of who's working or which machine, not something to
+remember case-by-case:
+
+```
+# Copyright (c) 2026 Calfus Inc.
+# Author: <original author's real name>
+# Editor: <anyone else who has since modified this file, comma-separated>
+```
+
+No license line - ownership is still being confirmed with the company;
+don't add one until that's resolved. Comment syntax matches the file
+(`#` for Python/YAML/TOML/Dockerfile/plain config files, `--` for
+`.sql` files, `//` for anything C-style). Place it after a
+shebang line where one exists (the shebang must stay the very first
+line), before everything else - including a module docstring - otherwise.
+
+- **Author** is whoever actually wrote the file first - for a brand new
+  file being created in this session, that's the user driving the
+  session, by their real name (check the git identity/context for this
+  repo rather than guessing or using "Claude"). Never invent a name.
+- **Editor** is anyone else who has since modified that same file -
+  omit the line entirely if there isn't one yet. When someone other than
+  the original author changes an existing file, add their name to the
+  Editor line if it isn't already there (comma-separate multiple
+  editors); don't touch Author once it's set. Same rule as Author:
+  real people only, by their real name (check the git identity/context
+  for this repo) - never "Claude", even when Claude is the one literally
+  typing the edit. Claude is a tool the person is using, not a credited
+  contributor. If the resulting editor would be the same person as
+  Author, don't add an Editor line at all - that's already covered by
+  Author.
+- **Dependency line** (optional, added under a blank `#`): a factual,
+  one-line "Depends on: X (Vendor) - what for" note, ONLY for a file that
+  directly talks to one of the four things this product's identity
+  depends on - SonarQube (SonarSource), Jira (Atlassian), Temporal
+  (Temporal Technologies), or PostgreSQL - and only when that file is
+  actually doing the talking (a direct API/SDK call), not just adjacent
+  to one. No language implying partnership, endorsement, or certification
+  by the third party - state the dependency, nothing more. Most files get
+  no dependency line at all; don't force one in where it doesn't apply.
+- **In-house dependency line(s)** (same block, one line per dependency):
+  a file with a genuine load-bearing dependency on another module
+  *within this repo* also gets its own "Depends on: <repo-relative file
+  path> - what for" line - e.g. "Depends on: src/config/store.py - reads/
+  writes the configs table". Repo-relative file path, not an import
+  statement or module dotted-path. Same bar as the vendor line above:
+  only the specific module(s) a file is actually built on top of to do
+  its own job (what it calls into), not every module it happens to
+  import - a shared status/glyph/constants helper doesn't count. One
+  line per dependency when there's more than one. Most files still get
+  none.
+- Markdown files (`README.md`, `ARCHITECTURE.md`, this file) are
+  deliberately excluded - no comment syntax was ever specified for them,
+  and guessing one (e.g. an HTML comment block) isn't this convention's
+  call to make unilaterally. Generated/vendored files (e.g. `uv.lock`)
+  are excluded too - never hand-edit those anyway.
+- Skip this convention only if the user explicitly asks to - never
+  silently omit a header because a file feels too small or too generated
+  to bother.

gozu-0.3.7/Dockerfile

@@ -0,0 +1,37 @@
+# Copyright (c) 2026 Calfus Inc.
+# Author: Wasiullah Rafeeq S
+
+FROM ghcr.io/astral-sh/uv:latest AS uv
+
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app/src
+ENV UV_PROJECT_ENVIRONMENT=/usr/local
+ENV UV_LINK_MODE=copy
+
+WORKDIR /app
+
+COPY --from=uv /uv /uvx /usr/local/bin/
+
+# src/scanner/screenshot.py's render_finding_snippet() needs Pygments'
+# ImageFormatter to find an actual monospace font - confirmed live that
+# python:3.12-slim has neither fontconfig (`fc-list`) nor any font at
+# all, which makes ImageFormatter raise FileNotFoundError outright, not
+# just render ugly. fonts-dejavu-core is the specific package that
+# provides DejaVu Sans Mono, the font ImageFormatter looks for first;
+# both packages together add a few MB, nowhere near what the Chromium
+# install this replaced used to cost.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        fontconfig fonts-dejavu-core \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml uv.lock ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-install-project --no-group dev
+
+COPY . .
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-group dev
+
+CMD ["python", "-m", "temporal.worker"]