itw-python-builder 0.1.30__tar.gz → 0.1.32__tar.gz

{itw_python_builder-0.1.30 → itw_python_builder-0.1.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: itw_python_builder
-Version: 0.1.30
+Version: 0.1.32
 Summary: Standardized Django deployment pipeline with Docker, testing, and SonarQube integration
 Author-email: IT-Works <contact@it-works.io>
 License: MIT

itw_python_builder-0.1.32/itw_python_builder/ssr_tasks.py

@@ -0,0 +1,348 @@
+"""SSR scaffolding tasks. One-time `itw ssr-init` for Angular SSR + ngx-seo-helper.
+
+The build/version tasks (`incrementrc`, `release`, etc.) live in tasks.py and
+take an `ssr=False` kwarg. With --ssr they invoke:
+  - `npm run build:ssr`          on master
+  - `npm run build:ssr:staging`  on any other branch
+
+These two scripts are a contract the project owner defines in package.json.
+ssr-init intentionally does NOT write them, because the right command depends
+on which Angular SSR setup the project ended up with:
+
+  legacy browser builder   →  ng build --configuration=X && ng run <name>:server:X
+  modern application builder (Angular 17+, fresh `ng add @angular/ssr`)
+                           →  ng build --configuration=X
+"""
+import json
+import os
+import re
+from pathlib import Path
+
+from invoke import task, Context
+
+from itw_python_builder.utils import detect_project_type, _read_package_name, is_ssr_project
+
+
+def _angular_major_version() -> int:
+    """Read @angular/core's major version from package.json. Returns 0 if not found."""
+    pkg_path = os.path.join(os.getcwd(), 'package.json')
+    with open(pkg_path, 'r', encoding='utf-8') as fp:
+        data = json.load(fp)
+    deps = {**data.get('dependencies', {}), **data.get('devDependencies', {})}
+    spec = deps.get('@angular/core', '')
+    match = re.match(r'[\^~>=<]*(\d+)', spec)
+    return int(match.group(1)) if match else 0
+
+
+def _angular_core_installed_version() -> str:
+    """Return the exact installed @angular/core version from node_modules, or '' if not found."""
+    pkg_path = os.path.join(os.getcwd(), 'node_modules', '@angular', 'core', 'package.json')
+    if not os.path.isfile(pkg_path):
+        return ''
+    with open(pkg_path, 'r', encoding='utf-8') as fp:
+        return json.load(fp).get('version', '')
+
+
+def _read_angular_json() -> dict:
+    """Read angular.json from cwd. Returns empty dict if missing/invalid."""
+    path = os.path.join(os.getcwd(), 'angular.json')
+    if not os.path.isfile(path):
+        return {}
+    try:
+        with open(path, 'r', encoding='utf-8') as fp:
+            return json.load(fp)
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _detect_angular_project(angular_json: dict) -> tuple:
+    """Return (project_name, project_data) for the project SSR was scaffolded into.
+
+    Priority: package.json `name` match → defaultProject → only project in repo.
+    Returns (None, None) if angular.json has no usable projects.
+    """
+    projects = angular_json.get('projects') or {}
+    if not projects:
+        return (None, None)
+    try:
+        pkg_name = _read_package_name()
+        if pkg_name in projects:
+            return (pkg_name, projects[pkg_name])
+    except Exception:
+        pass
+    default = angular_json.get('defaultProject')
+    if default and default in projects:
+        return (default, projects[default])
+    if len(projects) == 1:
+        name = next(iter(projects))
+        return (name, projects[name])
+    return (None, None)
+
+
+def _maybe_add_ssr_scripts(ctx: Context) -> None:
+    """Add build:ssr, build:ssr:staging, build:ssr:dev npm scripts based on angular.json.
+
+    Reads angular.json to detect:
+      - The builder (legacy `:browser` + separate `server` target, or modern `:application`)
+      - The project name (for `ng run <name>:server:<config>` in the legacy form)
+      - Which configurations exist (only writes scripts for configs that exist in both
+        `build` and, for legacy, `server` targets)
+
+    Never overwrites a script that already exists in package.json. Prints a summary
+    of what was added vs preserved vs skipped (no matching config).
+    """
+    angular_json = _read_angular_json()
+    if not angular_json:
+        print('[itw] No angular.json found — skipping SSR script setup.')
+        return
+
+    project_name, project = _detect_angular_project(angular_json)
+    if not project:
+        print('[itw] Could not detect Angular project in angular.json — skipping SSR script setup.')
+        return
+
+    arch = project.get('architect') or project.get('targets') or {}
+    build = arch.get('build') or {}
+    server = arch.get('server') or {}
+    builder = build.get('builder', '')
+
+    is_legacy = builder == '@angular-devkit/build-angular:browser' and bool(server)
+    is_modern = builder == '@angular-devkit/build-angular:application'
+    if not (is_legacy or is_modern):
+        print(f'[itw] Unrecognized build builder {builder!r} — skipping SSR script setup.')
+        return
+
+    build_configs = set((build.get('configurations') or {}).keys())
+    if is_legacy:
+        server_configs = set((server.get('configurations') or {}).keys())
+        usable_configs = build_configs & server_configs
+        builder_label = 'legacy (browser + server targets)'
+    else:
+        usable_configs = build_configs
+        builder_label = 'modern (application builder)'
+
+    print(f"[itw] Detected {builder_label} for project '{project_name}'.")
+
+    def cmd_for(config: str) -> str:
+        if is_legacy:
+            return f'ng build --configuration={config} && ng run {project_name}:server:{config}'
+        return f'ng build --configuration={config}'
+
+    script_map = {
+        'production': 'build:ssr',
+        'staging': 'build:ssr:staging',
+        'development': 'build:ssr:dev',
+    }
+
+    pkg_path = os.path.join(os.getcwd(), 'package.json')
+    with open(pkg_path, 'r', encoding='utf-8') as fp:
+        data = json.load(fp)
+    scripts = data.setdefault('scripts', {})
+
+    added, preserved, skipped = [], [], []
+    for config_name, script_name in script_map.items():
+        if config_name not in usable_configs:
+            skipped.append((script_name, config_name))
+            continue
+        if script_name in scripts:
+            preserved.append(script_name)
+            continue
+        scripts[script_name] = cmd_for(config_name)
+        added.append((script_name, scripts[script_name]))
+
+    if added:
+        with open(pkg_path, 'w', encoding='utf-8') as fp:
+            json.dump(data, fp, indent=2)
+            fp.write('\n')
+
+    print('[itw] SSR npm scripts:')
+    if added:
+        for name, cmd in added:
+            print(f'       + added:     {name}  →  {cmd}')
+    if preserved:
+        for name in preserved:
+            print(f'       = preserved: {name}  (already in package.json, not overwritten)')
+    if skipped:
+        for name, cfg in skipped:
+            print(f"       - skipped:   {name}  (no '{cfg}' config in angular.json)")
+    if not (added or preserved):
+        print('       (nothing added)')
+
+
+def _pin_ssr_deps_in_package_json(target_version: str) -> list:
+    """Pin @angular/ssr and @angular/platform-server in package.json to exact target_version.
+
+    Returns the list of packages whose entries were changed (or added). Does NOT touch
+    other @angular/* packages — only the two that @angular/ssr's install touches and
+    which carry strict peer-dependencies. This prevents npm from re-resolving them to
+    a newer patch that wouldn't match the installed @angular/core.
+    """
+    pkg_path = os.path.join(os.getcwd(), 'package.json')
+    with open(pkg_path, 'r', encoding='utf-8') as fp:
+        data = json.load(fp)
+    deps = data.setdefault('dependencies', {})
+    changed = []
+    for pkg in ('@angular/ssr', '@angular/platform-server'):
+        if deps.get(pkg) != target_version:
+            deps[pkg] = target_version
+            changed.append(pkg)
+    if changed:
+        with open(pkg_path, 'w', encoding='utf-8') as fp:
+            json.dump(data, fp, indent=2)
+            fp.write('\n')
+    return changed
+
+
+TEMPLATES_DIR = Path(__file__).parent / 'templates'
+
+SITEMAP_IMPORT_LINE = "import {sitemapEntries} from './src/sitemap.routes';"
+
+
+def _load_template(name: str) -> str:
+    """Read a template file, stripping the leading `// @ts-nocheck` editor hint."""
+    content = (TEMPLATES_DIR / name).read_text(encoding='utf-8')
+    lines = content.splitlines(keepends=True)
+    if lines and lines[0].lstrip().startswith('// @ts-nocheck'):
+        lines = lines[1:]
+        if lines and lines[0].strip() == '':
+            lines = lines[1:]
+    return ''.join(lines)
+
+
+def _run_ng_add_ssr(ctx: Context) -> None:
+    """Pin SSR deps to the installed @angular/core version, then run `ng add @angular/ssr`.
+
+    Why: @angular/platform-server (pulled in by @angular/ssr) has strict per-patch
+    peer-deps — platform-server@X.Y.Z demands @angular/core@X.Y.Z *exactly*. If
+    package.json declares platform-server as a range like ^X.Y.0, npm resolves to
+    the latest patch (often newer than the installed core), which breaks the install.
+
+    The fix is to pin only the two new packages (@angular/ssr and @angular/platform-server)
+    in package.json to the exact patch that matches the installed @angular/core. This
+    leaves every other @angular/* package alone — no upgrades, no downgrades — and
+    lets ng add → npm install resolve cleanly without --legacy-peer-deps or --force.
+
+    Flags on `ng add`:
+    - Angular 18 and earlier: no `--server-routing` flag (schematic rejects it).
+    - Angular 19+: pass `--server-routing=false` to keep the classic setup.
+    """
+    major = _angular_major_version()
+    installed_core = _angular_core_installed_version()
+
+    if installed_core:
+        changed = _pin_ssr_deps_in_package_json(installed_core)
+        if changed:
+            pkgs = ', '.join(changed)
+            print(f'[itw] Pinned {pkgs} to {installed_core} in package.json (matches installed @angular/core).')
+        package_spec = f'@angular/ssr@{installed_core}'
+    else:
+        package_spec = '@angular/ssr'
+
+    flags = '--skip-confirmation'
+    if major >= 19:
+        flags += ' --server-routing=false'
+    print(f'[itw] Running `ng add {package_spec}` (Angular {major}, this may take a minute)...')
+    ctx.run(f'npx ng add {package_spec} {flags}')
+
+
+def _install_ngx_seo_helper(ctx: Context) -> None:
+    print('[itw] Installing ngx-seo-helper...')
+    ctx.run('npm install ngx-seo-helper')
+
+
+def _write_sitemap_template() -> None:
+    path = os.path.join(os.getcwd(), 'src', 'sitemap.routes.ts')
+    if os.path.exists(path):
+        print(f'[itw] Skipping sitemap template — {path} already exists.')
+        return
+    with open(path, 'w', encoding='utf-8') as fp:
+        fp.write(_load_template('sitemap.routes.ts'))
+    print('[itw] Wrote src/sitemap.routes.ts (empty tree — fill in your routes).')
+
+
+def _patch_server_ts() -> None:
+    """Inject sitemap import + /sitemap.xml handler into server.ts (idempotent)."""
+    path = os.path.join(os.getcwd(), 'server.ts')
+    if not os.path.exists(path):
+        raise RuntimeError('server.ts missing after `ng add @angular/ssr` — cannot patch.')
+
+    with open(path, 'r', encoding='utf-8') as fp:
+        content = fp.read()
+
+    if 'sitemap.routes' in content:
+        print('[itw] server.ts already references sitemap.routes — skipping patch.')
+        return
+
+    lines = content.splitlines(keepends=True)
+    last_import_idx = -1
+    for i, line in enumerate(lines):
+        if line.startswith('import '):
+            last_import_idx = i
+    if last_import_idx == -1:
+        raise RuntimeError('server.ts has no imports — unexpected shape, aborting patch.')
+    lines.insert(last_import_idx + 1, SITEMAP_IMPORT_LINE + '\n')
+    content = ''.join(lines)
+
+    match = re.search(r"(server\.set\('views',\s*distFolder\);\s*\n)", content)
+    if not match:
+        match = re.search(r"(const\s+commonEngine\s*=\s*new\s+CommonEngine\(\);\s*\n)", content)
+    if not match:
+        raise RuntimeError(
+            'Could not find an injection point in server.ts (looked for `server.set(\'views\', ...)` '
+            'or `new CommonEngine()`). Patch sitemap handler manually.'
+        )
+    insert_at = match.end()
+    content = content[:insert_at] + _load_template('server.sitemap.snippet.ts') + content[insert_at:]
+
+    with open(path, 'w', encoding='utf-8') as fp:
+        fp.write(content)
+    print('[itw] Patched server.ts with /sitemap.xml handler.')
+
+
+def _print_next_steps(project_name: str) -> None:
+    print()
+    print('=' * 70)
+    print('[itw] SSR scaffolding complete.')
+    print('=' * 70)
+    print('Next steps you must do manually:')
+    print()
+    print('  1. Add `NgxSeoModule` to your AppModule imports.')
+    print('  2. Fill in src/sitemap.routes.ts with your route tree.')
+    print('  3. If `build:ssr:staging` was skipped above, add a `staging` configuration')
+    print(f'     to angular.json (and the `server` target, if legacy builder), then re-run')
+    print('     `itw ssr-init --force` to add the missing scripts.')
+    print('  4. Verify locally: npm run build:ssr && npm run serve:ssr')
+    print('  5. Commit the new files.')
+    print('  6. Deploy with: itw incrementrc --ssr  (or incrementpatch/release --ssr)')
+    print('=' * 70)
+
+
+@task(name='ssr-init')
+def ssr_init(ctx: Context, force: bool = False) -> None:
+    """One-time SSR scaffold: ng add @angular/ssr, ngx-seo-helper, sitemap stub, server.ts patch.
+
+    Auto-adds the build:ssr / build:ssr:staging / build:ssr:dev npm scripts based
+    on angular.json (detects builder type and available configs). Existing scripts
+    are never overwritten.
+    """
+    if detect_project_type() != 'frontend':
+        raise RuntimeError('ssr-init only runs on frontend (Angular) projects.')
+
+    if is_ssr_project() and not force:
+        raise RuntimeError(
+            'SSR scaffolding already present (server.ts + tsconfig.server.json exist). '
+            'Re-run with --force to re-apply the sitemap stub and server.ts patch.'
+        )
+
+    name = _read_package_name()
+    print(f'[itw] Scaffolding SSR for project: {name}')
+
+    if not is_ssr_project():
+        _run_ng_add_ssr(ctx)
+
+    _maybe_add_ssr_scripts(ctx)
+    _install_ngx_seo_helper(ctx)
+    _write_sitemap_template()
+    _patch_server_ts()
+
+    _print_next_steps(name)

{itw_python_builder-0.1.30 → itw_python_builder-0.1.32}/itw_python_builder.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: itw_python_builder
-Version: 0.1.30
+Version: 0.1.32
 Summary: Standardized Django deployment pipeline with Docker, testing, and SonarQube integration
 Author-email: IT-Works <contact@it-works.io>
 License: MIT

{itw_python_builder-0.1.30 → itw_python_builder-0.1.32}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "itw_python_builder"
-version = "0.1.30"
+version = "0.1.32"
 description = "Standardized Django deployment pipeline with Docker, testing, and SonarQube integration"
 readme = "README.md"
 requires-python = ">=3.10"

itw_python_builder-0.1.30/itw_python_builder/ssr_tasks.py

@@ -1,210 +0,0 @@
-"""SSR scaffolding tasks. One-time `itw ssr-init` for Angular SSR + ngx-seo-helper.
-
-The build/version tasks (`incrementrc`, `release`, etc.) live in tasks.py and
-take an `ssr=False` kwarg. With --ssr they invoke:
-  - `npm run build:ssr`          on master
-  - `npm run build:ssr:staging`  on any other branch
-
-These two scripts are a contract the project owner defines in package.json.
-ssr-init intentionally does NOT write them, because the right command depends
-on which Angular SSR setup the project ended up with:
-
-  legacy browser builder   →  ng build --configuration=X && ng run <name>:server:X
-  modern application builder (Angular 17+, fresh `ng add @angular/ssr`)
-                           →  ng build --configuration=X
-"""
-import json
-import os
-import re
-from pathlib import Path
-
-from invoke import task, Context
-
-from itw_python_builder.utils import detect_project_type, _read_package_name, is_ssr_project
-
-
-def _angular_major_version() -> int:
-    """Read @angular/core's major version from package.json. Returns 0 if not found."""
-    pkg_path = os.path.join(os.getcwd(), 'package.json')
-    with open(pkg_path, 'r', encoding='utf-8') as fp:
-        data = json.load(fp)
-    deps = {**data.get('dependencies', {}), **data.get('devDependencies', {})}
-    spec = deps.get('@angular/core', '')
-    match = re.match(r'[\^~>=<]*(\d+)', spec)
-    return int(match.group(1)) if match else 0
-
-
-def _angular_core_installed_version() -> str:
-    """Return the exact installed @angular/core version from node_modules, or '' if not found.
-
-    Used to pin `ng add @angular/ssr@<this>` so platform-server's strict peer-deps
-    (which demand the same patch across all @angular/* packages) align with what's
-    already installed — no need for --legacy-peer-deps or --force.
-    """
-    pkg_path = os.path.join(os.getcwd(), 'node_modules', '@angular', 'core', 'package.json')
-    if not os.path.isfile(pkg_path):
-        return ''
-    with open(pkg_path, 'r', encoding='utf-8') as fp:
-        return json.load(fp).get('version', '')
-
-
-TEMPLATES_DIR = Path(__file__).parent / 'templates'
-
-SITEMAP_IMPORT_LINE = "import {sitemapEntries} from './src/sitemap.routes';"
-
-
-def _load_template(name: str) -> str:
-    """Read a template file, stripping the leading `// @ts-nocheck` editor hint."""
-    content = (TEMPLATES_DIR / name).read_text(encoding='utf-8')
-    lines = content.splitlines(keepends=True)
-    if lines and lines[0].lstrip().startswith('// @ts-nocheck'):
-        lines = lines[1:]
-        if lines and lines[0].strip() == '':
-            lines = lines[1:]
-    return ''.join(lines)
-
-
-def _run_ng_add_ssr(ctx: Context) -> None:
-    """Run `ng add @angular/ssr` pinned to the project's installed @angular/core patch.
-
-    Angular's @angular/platform-server (pulled in by @angular/ssr) has strict
-    peer-dependencies — every patch version demands the exact same patch across
-    all @angular/* packages. Without pinning, `ng add` grabs the latest patch and
-    breaks any project not on that exact patch. Pinning to the installed core
-    version aligns everything cleanly without bypassing npm's resolver.
-
-    Flags:
-    - Angular 18 and earlier: no `--server-routing` flag (schematic rejects it).
-    - Angular 19+: pass `--server-routing=false` to keep the classic setup,
-      matching the layout itw expects (single `server` target, not the new
-      server router).
-    """
-    major = _angular_major_version()
-    installed_core = _angular_core_installed_version()
-    if installed_core:
-        package_spec = f'@angular/ssr@{installed_core}'
-    else:
-        package_spec = '@angular/ssr'
-    flags = '--skip-confirmation'
-    if major >= 19:
-        flags += ' --server-routing=false'
-    print(f'[itw] Running `ng add {package_spec}` (Angular {major}, this may take a minute)...')
-    ctx.run(f'npx ng add {package_spec} {flags}')
-
-
-def _install_ngx_seo_helper(ctx: Context) -> None:
-    print('[itw] Installing ngx-seo-helper...')
-    ctx.run('npm install ngx-seo-helper')
-
-
-def _write_sitemap_template() -> None:
-    path = os.path.join(os.getcwd(), 'src', 'sitemap.routes.ts')
-    if os.path.exists(path):
-        print(f'[itw] Skipping sitemap template — {path} already exists.')
-        return
-    with open(path, 'w', encoding='utf-8') as fp:
-        fp.write(_load_template('sitemap.routes.ts'))
-    print('[itw] Wrote src/sitemap.routes.ts (empty tree — fill in your routes).')
-
-
-def _patch_server_ts() -> None:
-    """Inject sitemap import + /sitemap.xml handler into server.ts (idempotent)."""
-    path = os.path.join(os.getcwd(), 'server.ts')
-    if not os.path.exists(path):
-        raise RuntimeError('server.ts missing after `ng add @angular/ssr` — cannot patch.')
-
-    with open(path, 'r', encoding='utf-8') as fp:
-        content = fp.read()
-
-    if 'sitemap.routes' in content:
-        print('[itw] server.ts already references sitemap.routes — skipping patch.')
-        return
-
-    lines = content.splitlines(keepends=True)
-    last_import_idx = -1
-    for i, line in enumerate(lines):
-        if line.startswith('import '):
-            last_import_idx = i
-    if last_import_idx == -1:
-        raise RuntimeError('server.ts has no imports — unexpected shape, aborting patch.')
-    lines.insert(last_import_idx + 1, SITEMAP_IMPORT_LINE + '\n')
-    content = ''.join(lines)
-
-    match = re.search(r"(server\.set\('views',\s*distFolder\);\s*\n)", content)
-    if not match:
-        match = re.search(r"(const\s+commonEngine\s*=\s*new\s+CommonEngine\(\);\s*\n)", content)
-    if not match:
-        raise RuntimeError(
-            'Could not find an injection point in server.ts (looked for `server.set(\'views\', ...)` '
-            'or `new CommonEngine()`). Patch sitemap handler manually.'
-        )
-    insert_at = match.end()
-    content = content[:insert_at] + _load_template('server.sitemap.snippet.ts') + content[insert_at:]
-
-    with open(path, 'w', encoding='utf-8') as fp:
-        fp.write(content)
-    print('[itw] Patched server.ts with /sitemap.xml handler.')
-
-
-def _print_next_steps(project_name: str) -> None:
-    print()
-    print('=' * 70)
-    print('[itw] SSR scaffolding complete.')
-    print('=' * 70)
-    print('Next steps you must do manually:')
-    print()
-    print('  1. Add `NgxSeoModule` to your AppModule imports.')
-    print('  2. Fill in src/sitemap.routes.ts with your route tree.')
-    print('  3. Add `staging` (and optionally `development`) configurations to')
-    print('     angular.json under projects.' + project_name + '.architect.build.configurations.')
-    print('     ng add @angular/ssr only creates the `production` configuration.')
-    print()
-    print('  4. Add these two npm scripts to package.json — the deploy pipeline')
-    print('     calls them by name:')
-    print()
-    print('       "build:ssr":          "<build command for production>"')
-    print('       "build:ssr:staging":  "<build command for staging>"')
-    print()
-    print('     The exact command depends on which builder angular.json uses:')
-    print()
-    print('     • Modern application builder (default for fresh ng add @angular/ssr):')
-    print('         "build:ssr":         "ng build --configuration=production"')
-    print('         "build:ssr:staging": "ng build --configuration=staging"')
-    print()
-    print('     • Legacy browser builder (older projects with a separate server target):')
-    print(f'         "build:ssr":         "ng build --configuration=production && ng run {project_name}:server:production"')
-    print(f'         "build:ssr:staging": "ng build --configuration=staging && ng run {project_name}:server:staging"')
-    print()
-    print('  5. Verify locally: npm run build:ssr && npm run serve:ssr')
-    print('  6. Commit the new files.')
-    print('  7. Deploy with: itw incrementrc --ssr  (or incrementpatch/release --ssr)')
-    print('=' * 70)
-
-
-@task(name='ssr-init')
-def ssr_init(ctx: Context, force: bool = False) -> None:
-    """One-time SSR scaffold: ng add @angular/ssr, ngx-seo-helper, sitemap stub, server.ts patch.
-
-    Does NOT write package.json scripts — those depend on which builder Angular
-    chose. The post-run message tells you the two scripts the pipeline expects.
-    """
-    if detect_project_type() != 'frontend':
-        raise RuntimeError('ssr-init only runs on frontend (Angular) projects.')
-
-    if is_ssr_project() and not force:
-        raise RuntimeError(
-            'SSR scaffolding already present (server.ts + tsconfig.server.json exist). '
-            'Re-run with --force to re-apply the sitemap stub and server.ts patch.'
-        )
-
-    name = _read_package_name()
-    print(f'[itw] Scaffolding SSR for project: {name}')
-
-    if not is_ssr_project():
-        _run_ng_add_ssr(ctx)
-
-    _install_ngx_seo_helper(ctx)
-    _write_sitemap_template()
-    _patch_server_ts()
-
-    _print_next_steps(name)