itw-python-builder 0.2.12__py3-none-any.whl → 0.2.14__py3-none-any.whl

itw_python_builder/task_utils.py

@@ -1,7 +1,13 @@
 import re
+from difflib import SequenceMatcher
 
 from itw_python_builder.utils import _gitlab_api_call
 
+SIMILARITY_THRESHOLD = 0.95
+
+DATE_PLACEHOLDER = 'YYYY-MM-DD'
+
+DEFAULT_LABEL_COLOR = '#428BCA'
 
 DEFAULT_ACCEPTANCE_CRITERIA = (
     '- [ ] U kryen testet manuale në ndërfaqe\n'
@@ -10,7 +16,6 @@ DEFAULT_ACCEPTANCE_CRITERIA = (
     '- [ ] U kontrollua cilësia e kodit'
 )
 
-
 _RE_AC_HEADER = re.compile(r'(?im)^##\s*acceptance\s+criteria\s*$')
 _RE_COMMENT_HEADER = re.compile(r'(?im)^##\s*comment\s*$')
 _RE_AC_BLOCK = re.compile(
@@ -20,9 +25,9 @@ _RE_COMMENT_BLOCK = re.compile(
     r'(?ims)^##\s*comment\s*$(.*?)^##\s*comment\s*$'
 )
 
-
 _COLOR_GREEN = '\033[92m'
 _COLOR_RED = '\033[91m'
+_COLOR_WHITE = '\033[97m'
 _COLOR_RESET = '\033[0m'
 
 
@@ -34,10 +39,37 @@ def log_red(msg: str) -> None:
     print(f'{_COLOR_RED}{msg}{_COLOR_RESET}')
 
 
+def log_white(msg: str) -> None:
+    print(f'{_COLOR_WHITE}{msg}{_COLOR_RESET}')
+
+
 def log_info(msg: str) -> None:
     print(msg)
 
 
+def _normalize_title(value: str) -> str:
+    return ' '.join((value or '').lower().split())
+
+
+def is_similar(left: str, right: str, threshold: float = SIMILARITY_THRESHOLD) -> bool:
+    """True when two titles are at least `threshold` similar (default 95%)."""
+    a = _normalize_title(left)
+    b = _normalize_title(right)
+    if not a or not b:
+        return False
+    if a == b:
+        return True
+    return SequenceMatcher(None, a, b).ratio() >= threshold
+
+
+def find_similar(value: str, items: list, key: str = 'title', threshold: float = SIMILARITY_THRESHOLD):
+    """Return the first item whose `key` is ~threshold similar to `value`, else None."""
+    for item in items:
+        if is_similar(value, item.get(key, ''), threshold):
+            return item
+    return None
+
+
 def _list_group_projects(api_host: str, group_path: str, token: str) -> list:
     from urllib.parse import quote
     encoded = quote(group_path, safe='')
@@ -87,26 +119,30 @@ def get_project_by_path(api_host: str, project_path: str, token: str) -> dict:
 
 
 def find_project_milestone(api_host: str, project_id: int, title: str, token: str):
-    from urllib.parse import quote
-    encoded = quote(title, safe='')
     results = _gitlab_api_call(
         api_host,
-        f'/projects/{project_id}/milestones?search={encoded}',
+        f'/projects/{project_id}/milestones?per_page=100',
         token,
     )
-    for m in results:
-        if m.get('title') == title:
-            return m
-    return None
+    return find_similar(title, results)
+
+
+def find_project_issue(api_host: str, project_id: int, title: str, token: str, milestone: str = None):
+    """Look for a ~matching title within this milestone ('None' = the no-milestone bucket)."""
+    from urllib.parse import quote
+    endpoint = f'/projects/{project_id}/issues?per_page=100'
+    endpoint += f'&milestone={quote(milestone, safe="") if milestone else "None"}'
+    results = _gitlab_api_call(api_host, endpoint, token)
+    return find_similar(title, results)
 
 
 def create_project_milestone(
-    api_host: str,
-    project_id: int,
-    title: str,
-    start_date: str = None,
-    due_date: str = None,
-    token: str = None,
+        api_host: str,
+        project_id: int,
+        title: str,
+        start_date: str = None,
+        due_date: str = None,
+        token: str = None,
 ) -> dict:
     payload = {'title': title}
     if start_date:
@@ -122,6 +158,20 @@ def create_project_milestone(
     )
 
 
+def list_project_labels(api_host: str, project_id: int, token: str) -> list:
+    return _gitlab_api_call(api_host, f'/projects/{project_id}/labels?per_page=100', token)
+
+
+def create_project_label(api_host: str, project_id: int, name: str, token: str) -> dict:
+    return _gitlab_api_call(
+        api_host,
+        f'/projects/{project_id}/labels',
+        token,
+        method='POST',
+        payload={'name': name, 'color': DEFAULT_LABEL_COLOR},
+    )
+
+
 def create_issue_note(api_host: str, project_id: int, issue_iid: int, body: str, token: str) -> dict:
     return _gitlab_api_call(
         api_host,
@@ -132,6 +182,21 @@ def create_issue_note(api_host: str, project_id: int, issue_iid: int, body: str,
     )
 
 
+def _normalize_repo(raw: str) -> str:
+    value = (raw or '').strip()
+    if not value:
+        return ''
+    m = re.match(r'^[a-z][a-z0-9+.-]*://[^/]+/(.*)$', value, re.IGNORECASE)
+    if m:
+        value = m.group(1)
+    else:
+        m = re.match(r'^[^/\s]+@[^:/\s]+:(.*)$', value)
+        if m:
+            value = m.group(1)
+    value = re.sub(r'\.git$', '', value.strip(), flags=re.IGNORECASE)
+    return value.strip('/')
+
+
 def _strip_milestone_wrap(raw: str) -> str:
     raw = raw.strip()
     if raw.startswith('%"') and raw.endswith('"'):
@@ -143,6 +208,30 @@ def _strip_milestone_wrap(raw: str) -> str:
 
 _CRED_KEYS = ('glab_host', 'glab_username', 'glab_token')
 
+_RE_MARKER_COMMENT = re.compile(r'^<!--.*-->$')
+_RE_EMPTY_CHECKBOX = re.compile(r'^[-*]\s*\[[ xX]?\]\s*$')
+
+
+def _block_has_content(text: str) -> bool:
+    """False when a section holds only blank lines or empty checklist placeholders."""
+    for line in (text or '').splitlines():
+        stripped = line.strip()
+        if not stripped or _RE_EMPTY_CHECKBOX.match(stripped):
+            continue
+        return True
+    return False
+
+
+def _match_directive(line: str, name: str):
+    """None when the line is not this directive, '' when it carries no value."""
+    m = re.match(rf'^/{name}(?![\w-])\s*(.*)$', line, re.IGNORECASE)
+    if not m:
+        return None
+    value = m.group(1).strip()
+    if value.upper() == DATE_PLACEHOLDER:
+        return ''
+    return value
+
 
 def extract_glab_credentials(file_path: str) -> dict:
     """Scan md file for /glab_host, /glab_username, /glab_token top-level directives."""
@@ -152,9 +241,9 @@ def extract_glab_credentials(file_path: str) -> dict:
     for line in content.splitlines():
         stripped = line.strip()
         for key in _CRED_KEYS:
-            m = re.match(rf'^/{key}\s+(\S+)\s*$', stripped, re.IGNORECASE)
-            if m:
-                creds[key] = m.group(1)
+            value = _match_directive(stripped, key)
+            if value is not None:
+                creds[key] = value or None
                 break
     return creds
 
@@ -162,7 +251,7 @@ def extract_glab_credentials(file_path: str) -> dict:
 def strip_glab_credentials_lines(content: str) -> str:
     """Remove /glab_* lines so they don't leak into issue bodies."""
     pattern = re.compile(
-        rf'(?im)^\s*/(?:{"|".join(_CRED_KEYS)})\s+\S+\s*$\n?'
+        rf'(?im)^[ \t]*/(?:{"|".join(_CRED_KEYS)})(?![\w-])[^\n]*(?:\n|$)'
     )
     return pattern.sub('', content)
 
@@ -204,14 +293,16 @@ def _parse_single_issue(block: str, idx: int, file_path: str) -> dict:
     if len(cm_headers) >= 2:
         m = _RE_COMMENT_BLOCK.search(remaining)
         if m:
-            comment_text = m.group(1).strip()
+            if _block_has_content(m.group(1)):
+                comment_text = m.group(1).strip()
             remaining = _RE_COMMENT_BLOCK.sub('', remaining, count=1)
 
     acceptance_text = None
     if len(ac_headers) >= 2:
         m = _RE_AC_BLOCK.search(remaining)
         if m:
-            acceptance_text = m.group(1).strip()
+            if _block_has_content(m.group(1)):
+                acceptance_text = m.group(1).strip()
             remaining = _RE_AC_BLOCK.sub('', remaining, count=1)
 
     title = None
@@ -220,6 +311,7 @@ def _parse_single_issue(block: str, idx: int, file_path: str) -> dict:
     milestone_start = None
     milestone_end = None
     assignee = None
+    labels = []
     has_estimate = False
     has_due = False
     body_lines = []
@@ -227,35 +319,52 @@ def _parse_single_issue(block: str, idx: int, file_path: str) -> dict:
     for line in remaining.splitlines():
         stripped = line.strip()
 
-        m = re.match(r'^/title\s+(.+)$', stripped, re.IGNORECASE)
-        if m:
-            title = m.group(1).strip()
+        if _RE_MARKER_COMMENT.match(stripped):
             continue
-        m = re.match(r'^/repo\s+(\S+)\s*$', stripped, re.IGNORECASE)
-        if m:
-            repo = m.group(1)
+
+        value = _match_directive(stripped, 'title')
+        if value is not None:
+            title = value or None
             continue
-        m = re.match(r'^/milestone-start\s+(\S+)\s*$', stripped, re.IGNORECASE)
-        if m:
-            milestone_start = m.group(1)
+        value = _match_directive(stripped, 'repo')
+        if value is not None:
+            repo = _normalize_repo(value) or None
             continue
-        m = re.match(r'^/milestone-end\s+(\S+)\s*$', stripped, re.IGNORECASE)
-        if m:
-            milestone_end = m.group(1)
+        value = _match_directive(stripped, 'milestone-start')
+        if value is not None:
+            milestone_start = value or None
             continue
-        m = re.match(r'^/milestone\s+(.+)$', stripped, re.IGNORECASE)
-        if m:
-            milestone = _strip_milestone_wrap(m.group(1))
+        value = _match_directive(stripped, 'milestone-end')
+        if value is not None:
+            milestone_end = value or None
             continue
-        m = re.match(r'^/assignee\s+(.+)$', stripped, re.IGNORECASE)
-        if m:
-            assignee = m.group(1).strip()
-            body_lines.append(f'/assign {assignee}')
+        value = _match_directive(stripped, 'milestone')
+        if value is not None:
+            milestone = _strip_milestone_wrap(value) or None
+            continue
+        value = _match_directive(stripped, 'label')
+        if value is not None:
+            labels = [p.strip().lstrip('~').strip('"') for p in value.split(',') if p.strip()]
+            labels = [p for p in labels if p]
+            continue
+        value = _match_directive(stripped, 'assignee')
+        if value is not None:
+            if value:
+                assignee = value
+                body_lines.append(f'/assign {assignee}')
+            continue
+        value = _match_directive(stripped, 'estimate')
+        if value is not None:
+            if value:
+                has_estimate = True
+                body_lines.append(f'/estimate {value}')
+            continue
+        value = _match_directive(stripped, 'due')
+        if value is not None:
+            if value:
+                has_due = True
+                body_lines.append(f'/due {value}')
             continue
-        if re.match(r'^/estimate\s+\S+', stripped, re.IGNORECASE):
-            has_estimate = True
-        if re.match(r'^/due\s+\S+', stripped, re.IGNORECASE):
-            has_due = True
 
         body_lines.append(line)
 
@@ -273,6 +382,7 @@ def _parse_single_issue(block: str, idx: int, file_path: str) -> dict:
         'milestone_start': milestone_start,
         'milestone_end': milestone_end,
         'assignee': assignee,
+        'labels': labels,
         'has_estimate': has_estimate,
         'has_due': has_due,
         'has_acceptance_criteria': acceptance_text is not None,

itw_python_builder/tasks.py

@@ -29,6 +29,8 @@ from itw_python_builder.utils import (
     TOKEN_CACHE_PATH,
     maybe_override_release_version,
     ensure_gitlab_token,
+    tag_exists,
+    latest_staging_rc,
 )
 from itw_python_builder.task_utils import (
     resolve_pm_repo,
@@ -38,11 +40,16 @@ from itw_python_builder.task_utils import (
     build_issue_description,
     get_project_by_path,
     find_project_milestone,
+    find_project_issue,
     create_project_milestone,
+    list_project_labels,
+    create_project_label,
     create_issue_note,
     log_green,
     log_red,
     log_info,
+    log_white,
+    find_similar,
 )
 from itw_python_builder.version import Version
 
@@ -201,12 +208,27 @@ def create_task(ctx: Context, file=None):
             if not issue['has_due']:
                 log_red('No due date is defined for this issue. Use /due in you md file to define a due date')
 
-            milestone_id = _resolve_milestone(api_host, project['id'], issue, token)
+            milestone_id, milestone_title = _resolve_milestone(api_host, project['id'], issue, token)
+
+            duplicate = find_project_issue(
+                api_host, project['id'], issue['title'], token, milestone_title
+            )
+            if duplicate:
+                scope = f'milestone {milestone_title}' if milestone_title else 'issues without a milestone'
+                log_white(
+                    f'Issue "{issue["title"]}" was not created because it already exists '
+                    f'in this project for {scope}: {duplicate["web_url"]}'
+                )
+                continue
+
+            labels = _resolve_labels(api_host, project['id'], issue, token)
 
             description = build_issue_description(issue)
             payload = {'title': issue['title'], 'description': description}
             if milestone_id is not None:
                 payload['milestone_id'] = milestone_id
+            if labels:
+                payload['labels'] = ','.join(labels)
 
             result = create_gitlab_issue(api_host, project['id'], payload, token)
             print(f'[itw] Created: {result["web_url"]}')
@@ -264,6 +286,24 @@ def _resolve_target_project(api_host: str, project_path: str, issue: dict, token
         print('Invalid choice, try again.')
 
 
+def _resolve_labels(api_host: str, project_id: int, issue: dict, token: str) -> list:
+    if not issue['labels']:
+        return []
+    existing = list_project_labels(api_host, project_id, token)
+    resolved = []
+    for name in issue['labels']:
+        match = find_similar(name, existing, key='name')
+        if match:
+            log_white(f'Using existing label {match["name"]}')
+            resolved.append(match['name'])
+            continue
+        created = create_project_label(api_host, project_id, name, token)
+        log_green(f'Created new label {created["name"]}')
+        resolved.append(created['name'])
+        existing.append(created)
+    return resolved
+
+
 def _resolve_milestone(api_host: str, project_id: int, issue: dict, token: str):
     title = issue['milestone']
     if not title:
@@ -271,12 +311,12 @@ def _resolve_milestone(api_host: str, project_id: int, issue: dict, token: str):
             'There is no milestone defined for this issue. '
             'Use /milestone in your md file to define a milestone'
         )
-        return None
+        return None, None
 
     existing = find_project_milestone(api_host, project_id, title, token)
     if existing:
-        log_info(f'Using existing milestone {title}')
-        return existing['id']
+        log_info(f'Using existing milestone {existing["title"]}')
+        return existing['id'], existing['title']
 
     start = issue['milestone_start']
     end = issue['milestone_end']
@@ -289,7 +329,7 @@ def _resolve_milestone(api_host: str, project_id: int, issue: dict, token: str):
             f'Created new milestone {title} | No start date or end date is defined for this '
             'new milestone. Use /milestone-start and /milestone-end in your md file to define them '
         )
-    return created['id']
+    return created['id'], created['title']
 
 
 def build_frontend(ctx: Context, branch: str, ssr: bool = False) -> None:
@@ -415,9 +455,11 @@ def push(ctx: Context):
 
 
 def buildimage(ctx: Context):
+    token = load_cached_token()
+    username = get_gitlab_username(ctx)
     current_branch = get_current_branch(ctx)
     container_registry_path = generate_image_path(ctx, current_branch)
-    ctx.run(f'podman build . --tag={container_registry_path}')
+    ctx.run(f'podman build --build-arg GITLAB_USERNAME={username} --build-arg GITLAB_TOKEN={token} --tag={container_registry_path} .')
 
 
 def pushimage(ctx: Context):
@@ -461,16 +503,24 @@ def tag_build_push(ctx: Context, version: Version, skip_pipeline: bool = False,
 
 @task(name='tag-init')
 def taginit(ctx: Context) -> None:
-    """Initialize version tagging"""
-    check_branch(ctx)
-    version = Version(0, 0, 1, 1)
+    """Initialize version tagging — release candidate on staging, release on master."""
+    production = check_branch(ctx)
+    if production:
+        version = latest_staging_rc(ctx)
+        log_info(f'Latest release candidate on staging: {version}')
+        version.reset_release_candidate(release=True)
+    else:
+        version = Version(0, 0, 1, 1)
+    if tag_exists(ctx, version):
+        raise RuntimeError(f'Tag {version} already exists — nothing to initialize.')
     tag(ctx, version)
     save_version(version)
+    log_green(f'Initialized {version} on {get_current_branch(ctx)}')
 
 
 def _ensure_unique_tag(ctx: Context, version: Version) -> None:
     """If the tag already exists, auto-increment RC (RC tags) or patch (release tags)."""
-    while ctx.run(f'git rev-parse -q --verify "refs/tags/{version}"', warn=True, hide=True).ok:
+    while tag_exists(ctx, version):
         if version.release_candidate == 0:
             print(f"[itw] Tag {version} already exists, auto-incrementing patch...")
             version.increment_patch(release=True)
@@ -743,10 +793,20 @@ def pipelinelocal(ctx: Context, settings='backend.test_settings', pylintrc=None)
     print("=" * 60)
 
 
+def _ensure_changelog() -> None:
+    if os.path.exists('CHANGELOG.md'):
+        return
+    with open('CHANGELOG.md', 'w') as f:
+        f.write('# Changelog\n')
+    log_green('Created CHANGELOG.md')
+
+
 @task
 def changelog(ctx: Context, version: Version = None):
     """Generate changelog from commits with Changelog trailer"""
 
+    _ensure_changelog()
+
     exclude = f'--exclude={version}' if version else ''
     last_tag_result = ctx.run(f'git describe --tags --abbrev=0 {exclude}', hide=True, warn=True)
     if last_tag_result.ok and last_tag_result.stdout.strip():
@@ -831,9 +891,7 @@ def changelog(ctx: Context, version: Version = None):
                 changelog_entry += f"{commit}\n"
             changelog_entry += "\n"
 
-    if not os.path.exists('CHANGELOG.md'):
-        with open('CHANGELOG.md', 'w') as f:
-            f.write('# Changelog\n')
+    _ensure_changelog()
 
     with open('CHANGELOG.md', 'r') as f:
         existing = f.read()

itw_python_builder/templates/task_template.md

@@ -1,18 +1,19 @@
 <!-- OPTIONAL -->
-/glab_host <gitlab-host>
-/glab_username <gitlab-username>
-/glab_token <personal-access-token>
+/glab_host 
+/glab_username 
+/glab_token 
 
 <!-- REQUIRED -->
-/title <issue title>
+/title 
 
 <!-- OPTIONAL -->
-/repo namespace/project
-/milestone %"Milestone name"
+/repo 
+/milestone 
 /milestone-start YYYY-MM-DD
 /milestone-end YYYY-MM-DD
-/assignee @username
-/estimate 2h
+/assignee 
+/label 
+/estimate 
 /due YYYY-MM-DD
 
 <!-- OPTIONAL -->

itw_python_builder/utils.py

@@ -254,6 +254,51 @@ def get_latest_tag(ctx: Context) -> Version:
     return Version.parse(tags[0])
 
 
+STAGING_REFS = ('staging', 'origin/staging')
+
+
+def ref_exists(ctx: Context, ref: str) -> bool:
+    return ctx.run(f'git rev-parse -q --verify "{ref}"', warn=True, hide=True).ok
+
+
+def tag_exists(ctx: Context, version: Version) -> bool:
+    return ctx.run(f'git rev-parse -q --verify "refs/tags/{version}"', warn=True, hide=True).ok
+
+
+def list_rc_tags(ctx: Context, ref: str) -> list:
+    result = ctx.run(f'git tag --list "v.*-rc*" --merged {ref}', hide=True)
+    versions = []
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            versions.append(Version.parse(line))
+        except ValueError:
+            continue
+    return versions
+
+
+def latest_staging_rc(ctx: Context) -> Version:
+    """Highest release candidate reachable from staging."""
+    ctx.run('git fetch origin --tags', warn=True, hide=True)
+    refs = [ref for ref in STAGING_REFS if ref_exists(ctx, ref)]
+    if not refs:
+        raise RuntimeError(
+            'No staging branch found locally or on origin, so there is no release '
+            'candidate to promote. Run `itw tag-init` on staging first.'
+        )
+    versions = []
+    for ref in refs:
+        versions.extend(list_rc_tags(ctx, ref))
+    if not versions:
+        raise RuntimeError(
+            f'No release candidate tag found on {" or ".join(refs)}. '
+            'Run `itw tag-init` on staging first.'
+        )
+    return max(versions, key=lambda v: (v.major, v.minor, v.patch, v.release_candidate))
+
+
 def _update_package_json_version(version: Version) -> None:
     """Update the top-level `version` in package.json (preserves key order)."""
     pkg_path = os.path.join(os.getcwd(), 'package.json')

itw_python_builder-0.2.14.dist-info/METADATA

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: itw_python_builder
+Version: 0.2.14
+Summary: Standardized Django deployment pipeline with Docker, testing, and SonarQube integration
+Author-email: IT-Works <contact@it-works.io>
+License: MIT
+Project-URL: Homepage, https://git.it-works.io/
+Project-URL: Repository, https://git.it-works.io/
+Project-URL: Issues, https://git.it-works.io/
+Keywords: django,deployment,docker,ci-cd,sonarqube
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: invoke>=2.0.0
+Requires-Dist: pylint>=3.0.0
+Requires-Dist: pylint-django>=2.5.0
+Requires-Dist: python-decouple>=3.8
+Requires-Dist: requests>=2.28.0
+Dynamic: license-file
+
+# ITW Python Builder
+
+Standardized Django and Angular deployment pipeline with Docker, testing, SonarQube integration, automatic changelog generation, GitLab issue creation, and code quality enforcement.
+
+## Features
+
+- Automated deployment with semantic versioning
+- Docker/Podman-based build and push pipeline (backend)
+- Angular build, packaging and upload to the GitLab Package Registry (frontend)
+- Angular SSR scaffolding and SSR builds
+- Automated testing with coverage
+- SonarQube static code analysis
+- Pylint linting with SonarQube integration
+- Quality gates - deploy only when tests pass
+- Automatic changelog generation from commit trailers
+- Automatic `CHANGELOG.md` creation and propagation to `staging`/`develop`
+- GitLab issue creation from a markdown file
+- Cached GitLab authentication
+- Support for local and production pipelines
+- Global CLI tool
+- Automatic venv detection per project
+
+## Installation
+```bash
+pip install itw-python-builder
+```
+
+Install globally (outside any project venv). The `itw` command becomes available system-wide.
+
+Check the installed version:
+```bash
+itw --version
+```
+
+## Quick Start
+
+1. Navigate to your project directory (Django projects must have a `.venv` or `venv`):
+
+2. Authenticate with GitLab:
+```bash
+itw login
+```
+
+3. Initialize versioning — run it on `staging` first, then on `master`:
+```bash
+git checkout staging && itw tag-init   # creates v.0.0.1-rc1
+git checkout master  && itw tag-init   # promotes the latest staging RC to -release
+```
+
+4. Run local pipeline:
+```bash
+itw pipelinelocal
+```
+
+5. Deploy to staging:
+```bash
+itw incrementrc
+```
+
+6. Deploy to production:
+```bash
+itw incrementpatch
+```
+
+## Available Commands
+
+### Deployment Commands
+
+- `itw incrementpatch` — Increment patch version and deploy
+- `itw incrementminor` — Increment minor version and deploy
+- `itw incrementmajor` — Increment major version and deploy
+- `itw incrementrc` — Increment release candidate (staging)
+- `itw release` — Promote RC to stable release (master)
+
+### Authentication Commands
+
+- `itw login` — Capture and cache a GitLab token (backend also logs into the container registry)
+- `itw logout` — Forget the cached token and log out of the container registry
+
+### GitLab Issue Commands
+
+- `itw task-init` — Create a `TASK.md` template in the current directory
+- `itw task --file=TASK.md` — Create GitLab issues from a markdown file
+
+### Local Development Commands
+
+- `itw pipelinelocal` — Run full local pipeline (lint → test → analyze → build)
+- `itw lintlocal` — Run pylint with human-readable output
+- `itw lint` — Run pylint and generate SonarQube report files
+- `itw buildlocal` — Build Docker image locally
+- `itw test` — Run tests with coverage
+- `itw analyze` — Run SonarQube analysis
+- `itw changelog` — Generate changelog manually
+- `itw tag-init` — Initialize version tagging (see below)
+- `itw ssr-init` — Scaffold Angular SSR (one-time, frontend only)
+
+### Version Initialization
+
+`itw tag-init` is branch-aware and must be run from `staging` or `master`:
+
+- On **staging** it creates the first release candidate, `v.0.0.1-rc1`.
+- On **master** it reads the latest `-rc` tag reachable from `staging` (local or `origin/staging`, after fetching tags) and creates that same version as a release. For example `v.0.0.2-rc10` on staging becomes `v.0.0.2-release` on master.
+
+The `VERSION` file is written with the tag that was created. The command stops with a clear error when there is no staging branch, no release candidate to promote, or when the tag already exists.
+
+### Skip Pipeline
+```bash
+itw incrementpatch --skip-pipeline
+```
+
+### Run a Subset of Tests
+```bash
+# Django: an app or a single test module
+itw test --target=users
+itw test --target=users.test_views
+
+# Angular: a directory or a spec name
+itw test --target=core
+itw test --target=core.service
+```
+
+### SSR Builds
+
+Frontend projects scaffolded with `itw ssr-init` build through the SSR npm scripts when `--ssr` is passed:
+```bash
+itw incrementrc --ssr
+itw incrementpatch --ssr
+```
+
+## Virtual Environment Detection
+
+`itw` is installed globally but automatically detects the project's virtual environment (`.venv` or `venv`) in the current directory. Tasks that need Python/Django dependencies (test, lint, analyze) activate the venv automatically — no need to manually activate it.
+
+If no venv is found, those tasks will error with a clear message. Tasks that only use git (like `changelog`, `tag-init`, `buildlocal`) work without a venv.
+
+## Linting
+
+The pipeline runs pylint automatically on every deployment and generates report files for SonarQube. The `.pylintrc` configuration is shipped with the package — no config files needed in your project.
+```bash
+# Review issues with human-readable output
+itw lintlocal
+
+# Generate report files for SonarQube
+itw lint
+
+# Use a custom pylint configuration
+itw lint --pylintrc=.pylintrc
+```
+
+Add this to your `sonar-project.properties`:
+```properties
+sonar.python.pylint.reportPaths=pylint-report.txt
+```
+
+## Changelog Generation
+
+Changelog entries are generated automatically on every deployment based on commit messages. To categorize a commit, add a `Changelog:` trailer to the commit body:
+```
+add user authentication
+
+Changelog: added
+```
+
+Available categories: `added`, `fixed`, `changed`, `deprecated`, `removed`, `security`, `performance`, `tests`, `docs`, `refactor`
+
+Commits without a trailer appear under `Other Changes`. The `CHANGELOG.md` file is committed and pushed automatically with each deployment.
+
+If `CHANGELOG.md` does not exist in the current directory it is created automatically — including when there are no new commits since the last tag, so the deployment never fails on a missing file.
+
+### Changelog Propagation
+
+After a successful deployment the changelog is synced forward through a temporary git worktree:
+
+- from `master` → `staging` and `develop`
+- from `staging` → `develop`
+
+Propagation is skipped when the working tree is not clean or when there is nothing new to sync.
+
+## GitLab Issue Creation
+
+Create GitLab issues from a markdown file instead of the web UI.
+
+Generate the template:
+```bash
+itw task-init
+```
+
+Then fill it in and run:
+```bash
+itw task --file=TASK.md
+```
+
+`task-init` refuses to overwrite an existing `TASK.md`.
+
+### Template
+
+```markdown
+<!-- OPTIONAL -->
+/glab_host 
+/glab_username 
+/glab_token 
+
+<!-- REQUIRED -->
+/title 
+
+<!-- OPTIONAL -->
+/repo 
+/milestone 
+/milestone-start YYYY-MM-DD
+/milestone-end YYYY-MM-DD
+/assignee 
+/label 
+/estimate 
+/due YYYY-MM-DD
+
+<!-- OPTIONAL -->
+## Acceptance Criteria
+- [ ] 
+- [ ] 
+## Acceptance Criteria
+
+<!-- OPTIONAL -->
+## Comment
+
+## Comment
+```
+
+Every key except `/title` is optional. Leaving a key empty is allowed — empty keys are simply not sent to GitLab. The date keys keep the `YYYY-MM-DD` format in the template and are treated as empty until you replace them.
+
+Any text outside the directives becomes the issue description. Create several issues from one file by separating the blocks with a line containing only `===`.
+
+### Directives
+
+| Directive | Description |
+| --- | --- |
+| `/glab_host` | GitLab host to authenticate against |
+| `/glab_username` | GitLab username |
+| `/glab_token` | GitLab personal access token |
+| `/title` | Issue title (required) |
+| `/repo` | Target project path |
+| `/milestone` | Milestone title |
+| `/milestone-start` | Milestone start date, used only when the milestone is created |
+| `/milestone-end` | Milestone due date, used only when the milestone is created |
+| `/assignee` | Username to assign the issue to |
+| `/label` | Comma-separated labels |
+| `/estimate` | Time estimate (e.g. `3h`) |
+| `/due` | Issue due date |
+
+### Authentication
+
+Either provide all three of `/glab_host`, `/glab_username` and `/glab_token`, or none of them. Providing only some of them is an error.
+
+When no credentials are given, `itw` uses the `.git` directory in the current folder to detect the GitLab host and project, and the token cached by `itw login`.
+
+### Target Repository
+
+With no `/repo`, the target is resolved by walking the current repository's namespace upward looking for a `_pm` project. If several are found you are prompted to pick one.
+
+With `/repo`, leading and trailing slashes are stripped automatically, and full URLs or SSH remotes are accepted:
+
+```
+/repo /tools/itw_python_builder/          → tools/itw_python_builder
+/repo https://git.it-works.io/tools/x.git → tools/x
+/repo git@git.it-works.io:tools/x.git     → tools/x
+```
+
+### Milestones, Labels and Duplicates
+
+Milestones, labels and issue titles are matched with a shared fuzzy comparison at 95% similarity, so small differences in spacing or casing still count as a match. The threshold is a single constant (`SIMILARITY_THRESHOLD` in `task_utils.py`) if you need to tune it.
+
+- **Milestone** — a similar existing milestone is reused; otherwise it is created (with the start/end dates when both are given).
+- **Label** — a similar existing label is linked and logged in white; a new one is created and logged in green. An empty `/label` is never sent to GitLab.
+- **Duplicate issues** — before creating, the target project is checked for a similar title *within the same milestone* (or among issues with no milestone). If one exists the issue is not created and a white log line reports it.
+
+### Acceptance Criteria and Comments
+
+The `## Acceptance Criteria` section must be opened and closed with the same header. When omitted or left with empty checkboxes, a default checklist is applied.
+
+The `## Comment` section, opened and closed the same way, is posted as a note on the issue after it is created.
+
+## Requirements
+
+- Python 3.10+
+- Podman
+- Git
+- SonarQube server
+- Node.js and npm (frontend projects)
+
+## Configuration
+
+### Environment Variables
+
+Add to your project `.env`:
+```
+SONAR_HOST_URL=https://your-sonar-server
+SONAR_TOKEN=your-token
+GIT_DEPTH=0
+```
+
+### Project Files Required
+
+- Git repository with `develop`, `staging`, and `master` branches
+- `VERSION` file in project root (backend) or `package.json` (frontend)
+- `Dockerfile` (backend)
+- `sonar-project.properties`
+
+## License
+
+MIT

{itw_python_builder-0.2.12.dist-info → itw_python_builder-0.2.14.dist-info}/RECORD

@@ -3,18 +3,18 @@ itw_python_builder/__init__.py,sha256=0HwEqonfK8w1kx80BOX80fvxSL8ov1hmUD2Zi4SU75
 itw_python_builder/cli.py,sha256=UKnswr7vzLC6SnB5YgxWu8ZLbOe8WGStdUHCgkzkyqM,939
 itw_python_builder/notify.py,sha256=Rv1RA9QdDo00bvjMMSDq-oQh2pjDmjjj97yzzhgiwpM,3011
 itw_python_builder/ssr_tasks.py,sha256=TqkuGLH9XJqDkTPBuRnFAKJywYqvdf0lSlSMXtVPM5Y,15730
-itw_python_builder/task_utils.py,sha256=LULsN7EoPe4ainxcdJ9eWhuUGono8bXQFJyaBpvLauQ,8887
-itw_python_builder/tasks.py,sha256=ZdvG4d43Hg0tcmy5sAZEgB5Gf0umtVpZOhpxh_8L7YE,31399
-itw_python_builder/utils.py,sha256=exgIMPN5lsxMfW2XeRdqbF9vzresyAEEQ3evMwYx5K0,19766
+itw_python_builder/task_utils.py,sha256=qohNLpIaodGmm9-FOOPL697Q3QZrrQkcK63AKhJcKZY,12683
+itw_python_builder/tasks.py,sha256=_I-hbfHzA7JRkleX7MkmxKi3lLzcrxTh8MIqgQzbCpQ,33617
+itw_python_builder/utils.py,sha256=wKNJM64Vl3O3KbyTSNYu6RelhWgmlapGOUGUokap9Pk,21294
 itw_python_builder/version.py,sha256=RCSKNU4eblCP38-PH5hT6qMDKOyQq5YGCoT2mgpfZkE,3165
 itw_python_builder/_pyruntime/sitecustomize.py,sha256=cjTrKErMdAFI-uVuW60BNNF8X41NrH9XDrIHJlNlEtY,805
 itw_python_builder/templates/new_version_email.html,sha256=I0RuZ8UMBavXTaSzQJQP1wNjsDY5TtxrASgeGiX0NGo,2854
 itw_python_builder/templates/server.sitemap.snippet.ts,sha256=qjRCLiAqzDUTqsWxJLeqlr-jOluK0IE2IoN_lbSx0ec,669
 itw_python_builder/templates/sitemap.routes.ts,sha256=yOXZ8TpHq_-QKH7y_u75XpL8paCF4AEv5z5cvWeI7yY,1323
-itw_python_builder/templates/task_template.md,sha256=MmMQegimJCU5S6n0qtLtsU4QHmrOFGRTsV8HSnkDLOA,448
-itw_python_builder-0.2.12.dist-info/licenses/LICENSE,sha256=WZ75-earCxnov77gsH4vckNf7Ag8RPst-7y9dPaZTCU,1063
-itw_python_builder-0.2.12.dist-info/METADATA,sha256=VFy21nfZ7WqpVGh10UlbRhkyJvG96QodaJEL546QXZg,4928
-itw_python_builder-0.2.12.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-itw_python_builder-0.2.12.dist-info/entry_points.txt,sha256=Rx2zlbaCxl954YX8kF4hey3Y25fxsaxiEPXjBPw3ky0,52
-itw_python_builder-0.2.12.dist-info/top_level.txt,sha256=9djpWUrRa0vuSfdVrHc4-3gvAHbBvzh_lbyzgTHtkJA,19
-itw_python_builder-0.2.12.dist-info/RECORD,,
+itw_python_builder/templates/task_template.md,sha256=SxoaWOuQVru6xNTLmhICkDoOSuHPM2B5FiVO67i7ciM,345
+itw_python_builder-0.2.14.dist-info/licenses/LICENSE,sha256=WZ75-earCxnov77gsH4vckNf7Ag8RPst-7y9dPaZTCU,1063
+itw_python_builder-0.2.14.dist-info/METADATA,sha256=glERXhS_LroSe7QZ97_kRZ-utfjkSfdtScqtPstZsKw,11297
+itw_python_builder-0.2.14.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+itw_python_builder-0.2.14.dist-info/entry_points.txt,sha256=Rx2zlbaCxl954YX8kF4hey3Y25fxsaxiEPXjBPw3ky0,52
+itw_python_builder-0.2.14.dist-info/top_level.txt,sha256=9djpWUrRa0vuSfdVrHc4-3gvAHbBvzh_lbyzgTHtkJA,19
+itw_python_builder-0.2.14.dist-info/RECORD,,

{itw_python_builder-0.2.12.dist-info → itw_python_builder-0.2.14.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (83.0.0)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

itw_python_builder-0.2.12.dist-info/METADATA

@@ -1,166 +0,0 @@
-Metadata-Version: 2.4
-Name: itw_python_builder
-Version: 0.2.12
-Summary: Standardized Django deployment pipeline with Docker, testing, and SonarQube integration
-Author-email: IT-Works <contact@it-works.io>
-License: MIT
-Project-URL: Homepage, https://git.it-works.io/
-Project-URL: Repository, https://git.it-works.io/
-Project-URL: Issues, https://git.it-works.io/
-Keywords: django,deployment,docker,ci-cd,sonarqube
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Build Tools
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: invoke>=2.0.0
-Requires-Dist: pylint>=3.0.0
-Requires-Dist: pylint-django>=2.5.0
-Requires-Dist: python-decouple>=3.8
-Requires-Dist: requests>=2.28.0
-Dynamic: license-file
-
-# ITW Python Builder
-
-Standardized Django deployment pipeline with Docker, testing, SonarQube integration, automatic changelog generation, and code quality enforcement.
-
-## Features
-
-- Automated deployment with semantic versioning
-- Docker/Podman-based build and push pipeline
-- Automated testing with coverage
-- SonarQube static code analysis
-- Pylint linting with SonarQube integration
-- Quality gates - deploy only when tests pass
-- Automatic changelog generation from commit trailers
-- Support for local and production pipelines
-- Global CLI tool
-- Automatic venv detection per project
-
-## Installation
-```bash
-pip install itw-python-builder
-```
-
-Install globally (outside any project venv). The `itw` command becomes available system-wide.
-
-## Quick Start
-
-1. Navigate to your Django project directory (must have a `.venv` or `venv`):
-
-2. Initialize versioning:
-```bash
-itw tag-init
-```
-
-3. Run local pipeline:
-```bash
-itw pipelinelocal
-```
-
-4. Deploy to staging:
-```bash
-itw incrementrc
-```
-
-5. Deploy to production:
-```bash
-itw incrementpatch
-```
-
-## Available Commands
-
-### Deployment Commands
-
-- `itw incrementpatch` — Increment patch version and deploy
-- `itw incrementminor` — Increment minor version and deploy
-- `itw incrementmajor` — Increment major version and deploy
-- `itw incrementrc` — Increment release candidate (staging)
-- `itw release` — Promote RC to stable release (master)
-
-### Local Development Commands
-
-- `itw pipelinelocal` — Run full local pipeline (lint → test → analyze → build)
-- `itw lintlocal` — Run pylint with human-readable output
-- `itw lint` — Run pylint and generate SonarQube report files
-- `itw buildlocal` — Build Docker image locally
-- `itw testlocal` — Run tests locally
-- `itw analyzelocal` — Run SonarQube analysis locally
-- `itw changelog` — Generate changelog manually
-- `itw tag-init` — Initialize version tagging
-
-### Skip Pipeline
-```bash
-itw incrementpatch --skip-pipeline
-```
-
-## Virtual Environment Detection
-
-`itw` is installed globally but automatically detects the project's virtual environment (`.venv` or `venv`) in the current directory. Tasks that need Python/Django dependencies (test, lint, analyze) activate the venv automatically — no need to manually activate it.
-
-If no venv is found, those tasks will error with a clear message. Tasks that only use git (like `changelog`, `tag-init`, `buildlocal`) work without a venv.
-
-## Linting
-
-The pipeline runs pylint automatically on every deployment and generates report files for SonarQube. The `.pylintrc` configuration is shipped with the package — no config files needed in your project.
-```bash
-# Review issues with human-readable output
-itw lintlocal
-
-# Generate report files for SonarQube
-itw lint
-```
-
-Add this to your `sonar-project.properties`:
-```properties
-sonar.python.pylint.reportPaths=pylint-report.txt
-```
-
-## Changelog Generation
-
-Changelog entries are generated automatically on every deployment based on commit messages. To categorize a commit, add a `Changelog:` trailer to the commit body:
-```
-add user authentication
-
-Changelog: added
-```
-
-Available categories: `added`, `fixed`, `changed`, `deprecated`, `removed`, `security`, `performance`, `tests`, `docs`, `refactor`
-
-Commits without a trailer appear under `Other Changes`. The `CHANGELOG.md` file is committed and pushed automatically with each deployment.
-
-## Requirements
-
-- Python 3.10+
-- Podman
-- Git
-- SonarQube server
-
-## Configuration
-
-### Environment Variables
-
-Add to your project `.env`:
-```
-SONAR_HOST_URL=https://your-sonar-server
-SONAR_TOKEN=your-token
-GIT_DEPTH=0
-```
-
-### Project Files Required
-
-- Git repository with `develop`, `staging`, and `master` branches
-- `VERSION` file in project root
-- `Dockerfile`
-- `sonar-project.properties`
-
-## License
-
-MIT