refactor: split into Python package, concat for release

Single-file helmfile2compose.py is now a build artifact produced by
build.py. Source lives in src/helmfile2compose/ (pacts/, core/, io/).
CI builds and uploads the single file on tag push.

Author: baptisterajaut

.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Build & Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install pyyaml
+
+      - name: Build single-file distribution
+        run: python build.py
+
+      - name: Upload release asset
+        uses: softprops/action-gh-release@v2
+        with:
+          files: helmfile2compose.py

.gitignore

@@ -14,6 +14,9 @@ CLAUDE.local.md
 # Regression test outputs (contain resolved secrets)
 tests/regression/
 
+# Build artifact (produced by build.py)
+helmfile2compose.py
+
 # Python
 __pycache__/
 *.pyc

CLAUDE.md

@@ -7,17 +7,36 @@ Part of the [helmfile2compose](https://github.com/helmfile2compose) org. This re
 - [helmfile2compose.github.io](https://github.com/helmfile2compose/helmfile2compose.github.io) — full documentation site
 - Extension repos: [h2c-provider-keycloak](https://github.com/helmfile2compose/h2c-provider-keycloak), [h2c-provider-servicemonitor](https://github.com/helmfile2compose/h2c-provider-servicemonitor), [h2c-converter-cert-manager](https://github.com/helmfile2compose/h2c-converter-cert-manager), [h2c-converter-trust-manager](https://github.com/helmfile2compose/h2c-converter-trust-manager), [h2c-transform-bitnami](https://github.com/helmfile2compose/h2c-transform-bitnami)
 
-## Workflow
+## Package structure
 
-Lint often: run `pylint helmfile2compose.py` and `pyflakes helmfile2compose.py` after any change. Fix real issues (unused imports, actual bugs, f-strings without placeholders). Pylint style warnings (too-many-locals, line-too-long, etc.) are acceptable.
+Python package under `src/helmfile2compose/` with three layers:
 
-Complexity: run `radon cc helmfile2compose.py -a -s -n C` to check cyclomatic complexity. Target: no D/E/F ratings. Current: 14 C-rated functions, average C (~14).
+- **`pacts/`** — public contracts for extensions (`ConvertContext`, `ConvertResult`, `IngressRewriter`, helpers). Stable API — extensions import from here (or from `helmfile2compose` directly via re-exports).
+- **`core/`** — internal conversion engine (`constants`, `env`, `volumes`, `services`, `workloads`, `ingress`, `extensions`, `convert`). Not public API.
+- **`io/`** — input/output (`parsing`, `config`, `output`). Not public API.
+- **`cli.py`** — CLI entry point.
 
-**Null-safe YAML access:** `.get("key", {})` returns `None` when the key exists with an explicit `null` value (Helm conditional blocks). Always use `.get("key") or {}` / `.get("key") or []` for fields that Helm may render as null (`annotations`, `ports`, `initContainers`, `data`, `rules`, `selector`, etc.).
+The single-file `helmfile2compose.py` is a **build artifact** produced by `build.py` (concat script). It is not committed — CI builds it on tag push and uploads as a release asset. Users and h2c-manager see no change.
+
+```bash
+# Development: run from package
+PYTHONPATH=src python -m helmfile2compose --from-dir /tmp/rendered --output-dir .
+
+# Build single-file distribution
+python build.py
+# → helmfile2compose.py (gitignored)
 
-## What exists
+# Validate with testsuite
+cd ../h2c-testsuite && ./run-tests.sh --local-core ../h2c-core/helmfile2compose.py
+```
 
-Single script `helmfile2compose.py` (~1860 lines). No packages, no setup.py. Dependency: `pyyaml`.
+Dependency: `pyyaml`.
+
+## Workflow
+
+Lint often: run `pylint src/helmfile2compose/` and `pyflakes src/helmfile2compose/` after any change. Fix real issues (unused imports, actual bugs, f-strings without placeholders). Pylint style warnings (too-many-locals, line-too-long, etc.) are acceptable.
+
+**Null-safe YAML access:** `.get("key", {})` returns `None` when the key exists with an explicit `null` value (Helm conditional blocks). Always use `.get("key") or {}` / `.get("key") or []` for fields that Helm may render as null (`annotations`, `ports`, `initContainers`, `data`, `rules`, `selector`, etc.).
 
 ### CLI
 
@@ -70,10 +89,10 @@ Three extension types, loaded from the same `--extensions-dir`:
 
 Extensions import `ConvertContext`/`ConvertResult`/`IngressRewriter` from `helmfile2compose`. `get_ingress_class(manifest, ingress_types)` and `resolve_backend(path_entry, manifest, ctx)` are public helpers for rewriters. `apply_replacements(text, replacements)` and `resolve_env(container, configmaps, secrets, workload_name, warnings, replacements=None, service_port_map=None)` are also public — available to extensions that need string replacement or env resolution. Available extensions:
 - **keycloak** — provider: `Keycloak`, `KeycloakRealmImport` (priority 50)
-- **cert-manager** — converter: `Certificate`, `ClusterIssuer`, `Issuer` (priority 10, requires `cryptography`)
+- **cert-manager** — converter: `Certificate`, `ClusterIssuer`, `Issuer` (priority 10, requires `cryptography`, incompatible with flatten-internal-urls)
 - **trust-manager** — converter: `Bundle` (priority 20, depends on cert-manager)
 - **servicemonitor** — provider: `Prometheus`, `ServiceMonitor` (priority 60, requires `pyyaml`)
-- **flatten-internal-urls** — transform: strip aliases, rewrite FQDNs (priority 200, incompatible with cert-manager)
+- **flatten-internal-urls** — transform: strip aliases, rewrite FQDNs (priority 200)
 - **bitnami** — transform: Bitnami Redis, PostgreSQL, Keycloak workarounds (priority 150)
 - **nginx** — ingress rewriter: Nginx annotations (rewrite-target, backend-protocol, CORS, proxy-body-size)
 - **traefik** — ingress rewriter: Traefik annotations (router.tls, standard path rules). POC.

README.md

@@ -56,6 +56,20 @@ CRDs (Keycloak, cert-manager, trust-manager) are handled by [external extensions
 - `helmfile2compose.yaml` — persistent config (volumes, excludes, overrides)
 - `configmaps/` / `secrets/` — generated files from volume mounts
 
+## Development
+
+The codebase is a Python package under `src/helmfile2compose/`. The single-file `helmfile2compose.py` is a build artifact produced by `build.py` — it concatenates the package into one file for distribution.
+
+```bash
+# Run from the package
+PYTHONPATH=src python -m helmfile2compose --help
+
+# Build the single-file distribution
+python build.py
+```
+
+See the [core architecture docs](https://helmfile2compose.github.io/developer/core-architecture/) for the full package structure.
+
 ## Documentation
 
 Full docs at [helmfile2compose.github.io](https://helmfile2compose.github.io).

build.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Concatenate the helmfile2compose package into a single-file distribution."""
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+SRC = Path(__file__).parent / "src" / "helmfile2compose"
+OUTPUT = Path(__file__).parent / "helmfile2compose.py"
+
+# Module order respects the dependency graph (no forward references)
+MODULES = [
+    "core/constants.py",
+    "pacts/types.py",
+    "pacts/helpers.py",
+    "pacts/ingress.py",
+    "core/env.py",
+    "core/volumes.py",
+    "core/services.py",
+    "core/workloads.py",
+    "core/ingress.py",
+    "core/extensions.py",
+    "core/convert.py",
+    "io/parsing.py",
+    "io/config.py",
+    "io/output.py",
+    "cli.py",
+]
+
+# Imports to strip (internal cross-references, any indentation level)
+INTERNAL_IMPORT_RE = re.compile(
+    r'^\s*(?:from helmfile2compose[\w.]* import .+|import helmfile2compose[\w.]*)\s*$'
+)
+
+SHEBANG = "#!/usr/bin/env python3\n"
+DOCSTRING = '"""helmfile2compose — convert helmfile template output to compose.yml + Caddyfile."""\n'
+PYLINT_DISABLE = "# pylint: disable=too-many-locals\n"
+
+
+def collect_imports_and_body(path: Path) -> tuple[list[str], list[str]]:
+    """Split a module into stdlib/external imports and body lines."""
+    imports = []
+    body = []
+    in_docstring = False
+    docstring_delim = None
+    in_internal_import = False  # inside a multi-line internal import
+
+    for line in path.read_text().splitlines(keepends=True):
+        stripped = line.strip()
+
+        # Skip module docstrings
+        if not in_docstring and not body and not imports:
+            if stripped.startswith(('"""', "'''")):
+                delim = stripped[:3]
+                if stripped.count(delim) >= 2:
+                    continue  # single-line docstring
+                in_docstring = True
+                docstring_delim = delim
+                continue
+        if in_docstring:
+            if docstring_delim in stripped:
+                in_docstring = False
+            continue
+
+        # Skip multi-line internal imports (continuation after opening paren)
+        if in_internal_import:
+            if ")" in stripped:
+                in_internal_import = False
+            continue
+
+        # Skip internal imports (single-line or start of multi-line)
+        if INTERNAL_IMPORT_RE.match(line):
+            if "(" in stripped and ")" not in stripped:
+                in_internal_import = True
+            continue
+
+        # Collect stdlib/external imports
+        if stripped.startswith(("import ", "from ")) and not stripped.startswith("from ."):
+            imports.append(line)
+            continue
+
+        body.append(line)
+
+    return imports, body
+
+
+def main():
+    all_imports: dict[str, str] = {}  # dedup by stripped content
+    all_bodies: list[str] = []
+
+    for mod_path in MODULES:
+        full_path = SRC / mod_path
+        if not full_path.exists():
+            print(f"Error: {full_path} not found", file=sys.stderr)
+            sys.exit(1)
+
+        imports, body = collect_imports_and_body(full_path)
+
+        for imp in imports:
+            key = imp.strip()
+            if key and key not in all_imports:
+                all_imports[key] = imp
+
+        # Add section comment + body
+        section = mod_path.replace(".py", "").replace("/", ".")
+        all_bodies.append(f"\n# --- {section} ---\n")
+        all_bodies.extend(body)
+
+    # Assemble
+    lines = [SHEBANG, DOCSTRING, PYLINT_DISABLE, "\n"]
+    lines.extend(all_imports.values())
+    lines.append("\n")
+    lines.extend(all_bodies)
+
+    # Add __main__ guard
+    lines.append('\n\nif __name__ == "__main__":\n')
+    lines.append("    main()\n")
+
+    OUTPUT.write_text("".join(lines))
+    print(f"Built {OUTPUT} ({sum(1 for l in lines if l.strip())} non-empty lines)")
+
+    # Smoke test
+    result = subprocess.run(
+        [sys.executable, str(OUTPUT), "--help"],
+        capture_output=True, text=True,
+    )
+    if result.returncode != 0:
+        print(f"Smoke test FAILED:\n{result.stderr}", file=sys.stderr)
+        sys.exit(1)
+    print("Smoke test passed (--help)")
+
+
+if __name__ == "__main__":
+    main()