generic-gitlab-cicd 0.3.2__py3-none-any.whl

generic_ci/workflows/ecosystems.py

@@ -0,0 +1,185 @@
+"""Workspace-aware package preparation and ecosystem version ordering."""
+import contextlib
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import tempfile
+import tarfile
+import shutil
+import tomllib
+import yaml
+from packaging.version import Version
+from generic_ci.dependencies import prepared
+from generic_ci.runtime import path_in
+from generic_ci.config import allowed_url
+
+
+def read_version(directory, release):
+    source = release['version']
+    path = path_in(directory, source['file'])
+    return extract_version(path.read_text(), source)
+
+
+def extract_version(text, source):
+    data = json.loads(text) if source['file'].endswith('.json') else tomllib.loads(text)
+    for key in source['field'].split('.'):
+        data = data[key]
+    if not isinstance(data, str):
+        raise ValueError('version field must be a string')
+    version_key(data, source['file'].endswith('.json'))
+    return data
+
+
+def version_key(value, node=False):
+    if not node:
+        v = Version(value)
+        if v.local:
+            raise ValueError('release versions cannot have local suffixes')
+        return v
+    # SemVer precedence: build metadata does not change precedence.
+    match = re.fullmatch(r'(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?', value)
+    if not match:
+        raise ValueError(f'invalid SemVer: {value}')
+    pre = match[4]
+    for sequence in (pre, match[5]):
+        if sequence is not None and any(not part for part in sequence.split('.')):
+            raise ValueError('empty SemVer identifier')
+    if pre and any(part.isdigit() and len(part) > 1 and part.startswith('0') for part in pre.split('.')):
+        raise ValueError('numeric SemVer prerelease identifiers cannot have leading zeroes')
+    return (int(match[1]), int(match[2]), int(match[3]), pre is None,
+            tuple((0, int(part)) if part.isdigit() else (1, part) for part in pre.split('.')) if pre else ())
+
+
+def node_workspace(directory, root, settings):
+    if settings['workspace'] is not None:
+        result = path_in(root, settings['workspace'])
+        if not directory.is_relative_to(result):
+            raise ValueError('Node workspace must contain project directory')
+        return result
+    for parent in (directory, *directory.parents):
+        if not parent.is_relative_to(root):
+            break
+        manifest = parent / 'package.json'
+        if not manifest.is_file():
+            continue
+        metadata = json.loads(manifest.read_text())
+        patterns = metadata.get('workspaces', [])
+        if isinstance(patterns, dict):
+            patterns = patterns.get('packages', [])
+        if (parent / 'pnpm-workspace.yaml').is_file():
+            patterns = yaml.safe_load((parent / 'pnpm-workspace.yaml').read_text()).get('packages', [])
+        members = {p.resolve() for pattern in patterns if not pattern.startswith('!') for p in parent.glob(pattern)}
+        excluded = {p.resolve() for pattern in patterns if pattern.startswith('!') for p in parent.glob(pattern[1:])}
+        if directory in members - excluded:
+            return parent
+    return directory
+
+
+@contextlib.contextmanager
+def environment(project, check, root, name, candidates, hosts, out):
+    directory = path_in(root, project['path'])
+    if check.get('dependencies') is False:
+        yield {'manager': 'none'}
+    elif project['python'] is not None:
+        policy = {**project['python'], **(check.get('dependencies') or {}), 'manager': 'uv', 'python': os.environ.get('PYTHON_VERSION')}
+        with prepared(directory, root, policy, candidates, name, hosts, out) as record:
+            yield record
+    elif project['node'] is not None:
+        settings = project['node']
+        manager = settings['package_manager']
+        workspace = node_workspace(directory, root, settings)
+        lock_name = {'npm': 'package-lock.json', 'pnpm': 'pnpm-lock.yaml', 'bun': 'bun.lock'}[manager]
+        lock = workspace / lock_name
+        if not lock.is_file():
+            raise ValueError(f'commit {lock_name} at Node workspace root; binary Bun lockfiles must be migrated')
+        metadata = json.loads((workspace / 'package.json').read_text())
+        requested = metadata.get('packageManager')
+        if requested:
+            match = re.fullmatch(r'(npm|pnpm|bun)@([^+]+)(?:\+.*)?', requested)
+            if not match or match[1] != manager:
+                raise ValueError('packageManager metadata conflicts with selected manager')
+            actual = subprocess.check_output([manager, '--version'], text=True).strip()
+            if actual != match[2]:
+                raise ValueError(f'prepared image needs {requested}; found {actual}; no automatic tool download')
+        selected = [c for c in candidates if name in c['projects']]
+        if selected and manager == 'pnpm' and (workspace / 'pnpm-workspace.yaml').is_file():
+            pnpm_settings = yaml.safe_load((workspace / 'pnpm-workspace.yaml').read_text())
+            if pnpm_settings.get('overrides'):
+                raise ValueError('candidate overrides with pnpm-workspace.yaml overrides require reconciliation; refusing ambiguous precedence')
+        # Require an explicitly configured internal default registry. Scope-specific registries
+        # and lifecycle-script network access additionally need the platform network boundary.
+        registry = os.environ.get('NPM_CONFIG_REGISTRY') or os.environ.get('npm_config_registry')
+        if not registry:
+            result = subprocess.run(['npm', 'config', 'get', 'registry'], cwd=workspace, text=True, capture_output=True, check=True)
+            registry = result.stdout.strip()
+        allowed_url(registry, hosts)
+        original = lock.read_bytes()
+        manifests = {p: p.read_bytes() for p in [workspace / 'package.json', directory / 'package.json']}
+        candidate_dir = tempfile.TemporaryDirectory()
+        env = {**os.environ, 'npm_config_registry': registry, 'NPM_CONFIG_REGISTRY': registry,
+               'COREPACK_ENABLE_NETWORK': '0', 'CI': 'true'}
+        command = ['npm', 'ci'] if manager == 'npm' else [manager, 'install', '--frozen-lockfile']
+        try:
+            candidate_files = []
+            for index, candidate in enumerate(selected):
+                clone = Path(candidate_dir.name) / str(index)
+                subprocess.run(['git', 'clone', '--no-checkout', candidate['repository'], str(clone)], check=True)
+                subprocess.run(['git', 'checkout', '--detach', candidate['commit']], cwd=clone, check=True)
+                actual_sha = subprocess.check_output(['git', 'rev-parse', 'HEAD'], cwd=clone, text=True).strip()
+                if actual_sha != candidate['commit']:
+                    raise ValueError('candidate checkout identity mismatch')
+                candidate_root = path_in(clone, candidate['subdirectory'] or '.')
+                package_metadata = json.loads((candidate_root / 'package.json').read_text())
+                if package_metadata['name'] != candidate['package']:
+                    raise ValueError('candidate package name does not match package.json')
+                packed = clone / 'packed'; packed.mkdir()
+                # Candidate repository must carry publishable output. Never run unverified
+                # prepare scripts with publishing credentials to silently build it.
+                subprocess.run(['npm', 'pack', '--ignore-scripts', '--pack-destination', str(packed)], cwd=candidate_root, env=env, check=True)
+                archives = list(packed.glob('*.tgz'))
+                if len(archives) != 1:
+                    raise ValueError('candidate pack must produce exactly one tarball')
+                archive = archives[0]
+                candidate_files.append((candidate, archive))
+                uri = 'file:' + str(archive)
+                for path in manifests:
+                    document = json.loads(path.read_text())
+                    for section in ('dependencies', 'devDependencies', 'optionalDependencies'):
+                        if candidate['package'] in document.get(section, {}):
+                            document[section][candidate['package']] = uri
+                    if path == workspace / 'package.json':
+                        owner = document.setdefault('pnpm', {}) if manager == 'pnpm' else document
+                        owner.setdefault('overrides', {})[candidate['package']] = uri
+                    path.write_text(json.dumps(document, indent=2) + '\n')
+            if selected:
+                refresh = ['npm', 'install', '--package-lock-only', '--ignore-scripts'] if manager == 'npm' else [manager, 'install', '--lockfile-only', '--ignore-scripts']
+                subprocess.run(refresh, cwd=workspace, env=env, check=True)
+            resolved_lock = lock.read_bytes()
+            subprocess.run(command, cwd=workspace, env=env, check=True)
+            if lock.read_bytes() != resolved_lock:
+                raise ValueError('frozen install unexpectedly changed lockfile')
+            for candidate, archive in candidate_files:
+                locations = [parent / 'node_modules' / candidate['package'] for parent in (directory, *directory.parents) if parent.is_relative_to(workspace)]
+                installed = next((p.resolve() for p in locations if (p / 'package.json').is_file()), None)
+                if installed is None:
+                    raise ValueError('candidate is not installed in the consuming project')
+                with tarfile.open(archive) as tar:
+                    for member in tar.getmembers():
+                        if not member.isfile():
+                            continue
+                        relative = Path(member.name).relative_to('package')
+                        target = path_in(installed, str(relative))
+                        if not target.is_file() or target.read_bytes() != tar.extractfile(member).read():
+                            raise ValueError('installed candidate differs from packed candidate commit')
+            yield {'manager': manager, 'workspace': workspace.relative_to(root).as_posix(),
+                   'lock_sha256': hashlib.sha256(resolved_lock).hexdigest(), 'candidates': selected}
+        finally:
+            candidate_dir.cleanup()
+            lock.write_bytes(original)
+            for path, content in manifests.items():
+                path.write_bytes(content)
+    else:
+        yield {'manager': 'none'}

generic_ci/workflows/helm.py

@@ -0,0 +1,168 @@
+"""Helm image mapping with an explicit baseline for partial shared releases."""
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import tempfile
+import yaml
+from generic_ci.runtime import path_in, write_json
+from generic_ci.compiler import digest
+
+
+def get_value(data, path):
+    for key in path.split('.'):
+        if not isinstance(data, dict) or key not in data:
+            raise ValueError(f'previous release has no image value at {path}; use complete deployment')
+        data = data[key]
+    return data
+
+
+def set_value(data, path, value):
+    parts = path.split('.')
+    for key in parts[:-1]:
+        data = data.setdefault(key, {})
+    data[parts[-1]] = value
+
+
+def overlay_images(bindings, images, previous, partial):
+    overlay = {}
+    for binding in bindings:
+        project = binding['from_'].split('.')[0]
+        image = images.get(project)
+        for field, path in binding['set'].items():
+            if path is None:
+                continue
+            if image is not None:
+                value = image[field]
+            elif partial:
+                value = get_value(previous, path)
+            else:
+                raise ValueError(f'missing image build for {project}')
+            if not isinstance(value, str) or not value:
+                raise ValueError(f'image value at {path} must be a nonempty string')
+            set_value(overlay, path, value)
+    return overlay
+
+
+def require_forward_commit(root, previous, current):
+    """Recover shallow history before distinguishing stale commits from Git errors."""
+    if not all(re.fullmatch(r'[a-f0-9]{40}', value) for value in (previous, current)):
+        raise ValueError('deployment history requires full Git commit IDs')
+    command = ['git', 'merge-base', '--is-ancestor', previous, current]
+    result = subprocess.run(command, cwd=root, capture_output=True)
+    if result.returncode:
+        shallow = subprocess.check_output(['git', 'rev-parse', '--is-shallow-repository'], cwd=root, text=True).strip()
+        if shallow == 'true':
+            subprocess.run(['git', 'fetch', '--unshallow', '--no-tags', 'origin'], cwd=root, check=True, capture_output=True)
+            result = subprocess.run(command, cwd=root, capture_output=True)
+    if result.returncode == 1:
+        raise ValueError('stale/nonlinear image update; explicit rollback or reconciliation required')
+    if result.returncode:
+        raise ValueError('cannot verify deployment ancestry; ensure both commits are available from origin')
+
+
+def deploy(data, node, root, out, records, plan, stop=False):
+    settings, infra = node['settings'], data['platform']
+    target = infra['targets'][settings['target']]
+    preview = node['event'] == 'merge-request'
+    if not preview and target['production'] and os.environ.get('CI_COMMIT_REF_PROTECTED') != 'true':
+        raise ValueError('production requires a protected ref')
+    if not preview and plan.get('candidates'):
+        raise ValueError('candidate runs cannot update persistent deployments')
+    release = target['release'] or node['deployment']
+    if preview:
+        release += '-mr-' + os.environ['CI_PROJECT_ID'] + '-' + os.environ['CI_MERGE_REQUEST_IID']
+    if len(release) > 53:
+        release = release[:40].rstrip('-') + '-' + hashlib.sha256(release.encode()).hexdigest()[:12]
+    if not re.fullmatch(r'[a-z0-9](?:[a-z0-9-]*[a-z0-9])?', release):
+        raise ValueError('invalid Helm release name')
+    namespace = os.path.expandvars(target['namespace'])
+    env = {**os.environ, 'KUBECONFIG': os.environ[target['kubeconfig_variable']]}
+    url = os.path.expandvars(target['url'])
+    if stop:
+        subprocess.run(['helm', 'uninstall', release, '--namespace', namespace, '--ignore-not-found', '--wait'], env=env, check=True)
+        return {'release': release, 'url': url}
+    chart = settings['chart']
+    with tempfile.TemporaryDirectory() as tmp:
+        if chart['path']:
+            chart_path = path_in(root, chart['path'])
+            chart_hash = digest({str(f.relative_to(chart_path)): hashlib.sha256(f.read_bytes()).hexdigest() for f in sorted(chart_path.rglob('*')) if f.is_file()})
+        else:
+            args = ['helm', 'pull', chart['oci'] or chart['name'], '--version', chart['version'], '--destination', tmp]
+            if chart['repository']:
+                args += ['--repo', chart['repository']]
+            # Registry config and CA are injected as environment/file configuration.
+            if os.environ.get('TOOLKIT_HELM_CA_FILE'):
+                args += ['--ca-file', os.environ['TOOLKIT_HELM_CA_FILE']]
+            if chart['repository'] and os.environ.get('TOOLKIT_HELM_USERNAME'):
+                args += ['--username', os.environ['TOOLKIT_HELM_USERNAME'], '--password', os.environ['TOOLKIT_HELM_PASSWORD']]
+            subprocess.run(args, env=env, check=True)
+            archives = list(Path(tmp).glob('*.tgz'))
+            if len(archives) != 1:
+                raise ValueError('Helm pull must produce exactly one chart archive')
+            chart_path = archives[0]
+            chart_hash = hashlib.sha256(chart_path.read_bytes()).hexdigest()
+        value_files = [path_in(root, p) for p in settings['values']]
+        baseline = digest({'chart': chart_hash, 'values': [hashlib.sha256(f.read_bytes()).hexdigest() for f in value_files], 'bindings': settings['images']})
+        listing = json.loads(subprocess.check_output(['helm', 'list', '--all', '--namespace', namespace, '--filter', '^' + re.escape(release) + '$', '--output', 'json'], env=env, text=True))
+        previous = {}
+        old_meta = {}
+        if listing:
+            if len(listing) != 1 or listing[0]['status'] != 'deployed':
+                raise ValueError('previous Helm release is not deployed; reconcile failed/pending state first')
+            previous = json.loads(subprocess.check_output(['helm', 'get', 'values', release, '--namespace', namespace, '--output', 'json'], env=env, text=True)) or {}
+            old_meta = previous.get('genericCiMetadata', {})
+        partial = settings['update'] == 'partial'
+        if partial and listing and old_meta.get('baseline') != baseline:
+            raise ValueError('partial update cannot change chart/configuration; perform a complete deployment')
+        images = {r['project']: r['image'] for r in records if 'image' in r}
+        if not images:
+            raise ValueError('no selected images for this deployment')
+        for name in images:
+            prior = old_meta.get('services', {}).get(name, {})
+            old_commit = prior.get('commit')
+            current = os.environ['CI_COMMIT_SHA']
+            if old_commit and old_commit != current:
+                require_forward_commit(root, old_commit, current)
+        overlay = overlay_images(settings['images'], images, previous, partial and bool(listing))
+        services = dict(old_meta.get('services', {})) if partial else {}
+        for name in images:
+            services[name] = {'commit': os.environ['CI_COMMIT_SHA'], 'pipeline': os.environ['CI_PIPELINE_ID']}
+        overlay['genericCiMetadata'] = {'baseline': baseline, 'services': services}
+        # Metadata is Helm values state, not a separate desired-state repository.
+        generated = Path(tmp) / 'images.json'
+        write_json(generated, overlay)
+        args = [release, str(chart_path), '--namespace', namespace]
+        for path in value_files:
+            args += ['--values', str(path)]
+        args += ['--values', str(generated)]
+        rendered = subprocess.check_output(['helm', 'template', *args], env=env, text=True)
+        workload_images = set()
+        def scan(value):
+            if isinstance(value, dict):
+                for key, child in value.items():
+                    if key in {'containers', 'initContainers'} and isinstance(child, list):
+                        workload_images.update(v.get('image') for v in child if isinstance(v, dict))
+                    scan(child)
+            elif isinstance(value, list):
+                for child in value:
+                    scan(child)
+        for document in yaml.safe_load_all(rendered):
+            scan(document)
+        for binding in settings['images']:
+            name = binding['from_'].split('.')[0]
+            if name not in images:
+                continue
+            image = images[name]
+            expected = image['repository'] + ('@' + image['digest'] if binding['set']['digest'] else ':' + image['tag'])
+            if expected not in workload_images:
+                raise ValueError(f'chart does not consume mapped image for {name}: {expected}')
+        major = subprocess.check_output(['helm', 'version', '--template', '{{.Version}}'], text=True)
+        flag = '--atomic' if major.startswith('v3.') else '--rollback-on-failure' if major.startswith('v4.') else None
+        if not flag:
+            raise ValueError('supported Helm versions: 3 and 4')
+        subprocess.run(['helm', 'upgrade', '--install', *args, '--wait', '--timeout', '10m', flag], env=env, check=True)
+        write_json(out / 'images.json', images)
+        return {'release': release, 'namespace': namespace, 'url': url, 'images': images, 'baseline': baseline}

generic_ci/workflows/models.py

@@ -0,0 +1,222 @@
+"""Public workflow schema. No hidden test names or raw GitLab rules."""
+from typing import Literal
+from pydantic import Field, model_validator, field_validator
+from generic_ci.models import Model, Name, relative
+
+class Python(Model):
+    groups: Literal['all'] | list[str] | None = Field(default=None, description='Omit to respect uv defaults; all selects all groups, not all workspace members.')
+    extras: Literal['all'] | list[str] = Field(default_factory=list)
+    upgrade: Literal['none', 'all'] = 'none'
+
+class Node(Model):
+    package_manager: Literal['npm', 'pnpm', 'bun']
+    workspace: str | None = Field(default=None, description='Explicit repository-relative workspace root; otherwise discover membership.')
+    _path = field_validator('workspace')(lambda v: relative(v) if v is not None else v)
+
+class Execution(Model):
+    image: str | None = None
+    tags: list[str] | None = None
+    timeout: str | None = None
+    variables: dict[str, str] = Field(default_factory=dict)
+    services: list[str] | None = None
+    parallel: dict | None = None
+    artifacts: dict = Field(default_factory=dict)
+    @field_validator('variables')
+    @classmethod
+    def variables_safe(cls, v):
+        if any(k.startswith(('CI_', 'TOOLKIT_')) or k in {'PYTHONPATH', 'PYTHONHOME', 'DEPLOYMENT_URL'} for k in v):
+            raise ValueError('CI_*, TOOLKIT_*, Python bootstrap and DEPLOYMENT_URL variables are reserved')
+        return v
+
+class Check(Execution):
+    script: list[str] = Field(min_length=1, description='Team-owned commands, executed after preparation.')
+    dependencies: Python | Literal[False] | None = None
+    needs: list[str] = Field(default_factory=list, description='Checks or project.build outputs required in the same event.')
+    outputs: list[str] = Field(default_factory=list, description='Project-relative files passed to consumers; matrices cannot produce shared files.')
+    _paths = field_validator('outputs')(lambda v: [relative(p) for p in v])
+
+class Build(Model):
+    script: list[str] = Field(min_length=1)
+    outputs: list[str] = Field(min_length=1)
+    needs: list[str] = Field(default_factory=list)
+    _paths = field_validator('outputs')(lambda v: [relative(p) for p in v])
+
+class Container(Model):
+    dockerfile: str = 'Dockerfile'
+    context: str = '.'
+    repository: str | None = None
+    needs: list[str] = Field(default_factory=list)
+    build_args: dict[str, str] = Field(default_factory=dict)
+    secrets: dict[str, str] = Field(default_factory=dict, description='Secret ID to file-type CI variable name.')
+    target: str | None = None
+    dependency_bundle: bool = Field(default=False, description='Python Dockerfile consumes named ci-dependencies wheelhouse context; required for candidate previews.')
+    _paths = field_validator('dockerfile', 'context')(relative)
+
+class PreviewPackage(Model):
+    index: str | None = Field(default=None, description="Optional Python named uv index override for development publication.")
+    registry: str | None = Field(default=None, description="Optional Node registry override for development publication.")
+
+    @model_validator(mode='after')
+    def one_destination(self):
+        if bool(self.index) == bool(self.registry):
+            raise ValueError('preview requires exactly one of index (Python) or registry (Node)')
+        return self
+
+class Publication(Model):
+    channel: Literal["development", "auto"]
+
+class Package(Model):
+    directory: str = '.'
+    preview: PreviewPackage | None = None
+    index: str | None = Field(default=None, description='Python named uv publishing index; Node reads publishConfig.registry.')
+    needs: list[str] = Field(default_factory=list)
+    _path = field_validator('directory')(relative)
+
+class VersionSource(Model):
+    file: str
+    field: str
+    _path = field_validator('file')(relative)
+
+class CreateRelease(Model):
+    branch: str = 'main'
+    when: Literal['manual'] = 'manual'
+
+class Release(Model):
+    version: VersionSource | None = None
+    require_bump: bool = True
+    tag: str
+    create: CreateRelease | None = None
+    needs: list[str] = Field(default_factory=list, description='Other projects whose matching release publication must finish first.')
+    @field_validator('tag')
+    @classmethod
+    def pattern(cls, v):
+        if v.count('{version}') != 1 or '{' in v.replace('{version}', ''):
+            raise ValueError('tag requires exactly one {version}')
+        return v
+
+class Workflow(Model):
+    checks: list[str] = Field(default_factory=list)
+    build: bool | list[Literal['application', 'container', 'package']] = False
+    publish: bool | Publication = False
+
+Event = Literal['push', 'merge-request', 'release', 'manual', 'schedule']
+
+class Project(Model):
+    path: str = '.'
+    python: Python | None = None
+    node: Node | None = None
+    defaults: Execution = Field(default_factory=Execution)
+    checks: dict[Name, Check] = Field(default_factory=dict)
+    build: Build | None = None
+    container: Container | None = None
+    package: Package | None = None
+    release: Release | None = None
+    workflows: dict[Event, Workflow] = Field(default_factory=dict)
+    depends_on: list[Name] = Field(default_factory=list, description='Changes to these projects select this consumer. Installation follows package metadata.')
+    watch: list[str] = Field(default_factory=list)
+    _paths = field_validator('path')(relative)
+    @model_validator(mode='after')
+    def ecosystem(self):
+        if self.python is not None and self.node is not None:
+            raise ValueError('use separate project identities for Python and Node outputs sharing a path')
+        if self.package and self.package.preview:
+            if ((self.python is not None and not self.package.preview.index)
+                    or (self.node is not None and not self.package.preview.registry)
+                    or (self.python is None and self.node is None)):
+                raise ValueError('preview destination must match the project ecosystem')
+        if self.release and not self.release.version:
+            if self.python is not None:
+                self.release.version = VersionSource(file='pyproject.toml', field='project.version')
+            elif self.node is not None:
+                self.release.version = VersionSource(file='package.json', field='version')
+            else:
+                raise ValueError('release.version is required without a Python or Node ecosystem')
+        return self
+
+class Chart(Model):
+    path: str | None = None
+    repository: str | None = None
+    name: str | None = None
+    oci: str | None = None
+    version: str | None = None
+    @model_validator(mode='after')
+    def source(self):
+        if sum(bool(v) for v in (self.path, self.repository, self.oci)) != 1:
+            raise ValueError('choose exactly one chart source: path, repository, oci')
+        if self.path:
+            relative(self.path)
+            if self.name or self.version:
+                raise ValueError('local chart cannot specify name/version')
+        elif not self.version or (self.repository and not self.name):
+            raise ValueError('remote chart requires pinned version; Helm repository also requires name')
+        if self.oci and (not self.oci.startswith('oci://') or self.name):
+            raise ValueError('OCI chart requires oci:// reference and no name')
+        return self
+
+class Binding(Model):
+    repository: str | None = None
+    tag: str | None = None
+    digest: str | None = None
+    @model_validator(mode='after')
+    def paths(self):
+        import re
+        if not self.tag and not self.digest:
+            raise ValueError('map at least tag or digest')
+        for v in (self.repository, self.tag, self.digest):
+            if v and not re.fullmatch(r'[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*', v):
+                raise ValueError('image paths support dotted mapping keys; array indices and literal dots are not supported')
+        return self
+
+class Image(Model):
+    from_: str = Field(alias='from')
+    set: Binding
+
+class CheckList(Model):
+    checks: list[str] = Field(default_factory=list)
+
+class DeployWorkflow(Model):
+    when: Literal['manual', 'automatic'] = 'manual'
+
+class Deployment(Model):
+    target: str = Field(description='Platform target containing namespace, kubeconfig variable and URL.')
+    chart: Chart
+    values: list[str] = Field(default_factory=list)
+    images: list[Image] = Field(min_length=1)
+    update: Literal['complete', 'partial'] = 'complete'
+    before: CheckList = Field(default_factory=CheckList)
+    after: CheckList = Field(default_factory=CheckList)
+    workflows: dict[Literal['release', 'merge-request'], DeployWorkflow] = Field(default_factory=dict)
+    auto_stop_in: str = '2 days'
+    _paths = field_validator('values')(lambda v: [relative(p) for p in v])
+
+class Pipeline(Model):
+    version: Literal[1] = 1
+    projects: dict[Name, Project] = Field(min_length=1)
+    deployments: dict[Name, Deployment] = Field(default_factory=dict)
+
+class Builder(Model):
+    engine: Literal['buildah'] = 'buildah'
+    image: str
+    tags: list[str] | None = None
+
+class Registries(Model):
+    containers: str
+    previews: str
+
+class Target(Model):
+    namespace: str
+    kubeconfig_variable: str = 'KUBECONFIG'
+    url: str = ''
+    production: bool = True
+    release: str | None = None
+
+class Platform(Model):
+    version: Literal[1] = 1
+    defaults: Execution = Field(default_factory=Execution)
+    images: dict[str, str] = Field(description='Prepared images for python, node, bun, helm, and optional control role; all include toolkit Python runtime.')
+    container_builder: Builder
+    registries: Registries
+    allowed_hosts: list[str] = Field(min_length=1)
+    targets: dict[Name, Target] = Field(default_factory=dict)
+    variables: dict[str, str] = Field(default_factory=dict)
+    max_jobs: int = Field(default=150, ge=1, le=1000)

generic_ci/workflows/publication.py

@@ -0,0 +1,82 @@
+"""Package version generation and user-selected publication destinations."""
+import json
+import os
+import re
+import tomllib
+from urllib.parse import urlsplit, urlunsplit
+from packaging.version import Version
+import tomlkit
+from generic_ci.config import allowed_url
+from .ecosystems import version_key
+
+
+def snapshot_version(value, node=False):
+    pipeline = os.environ.get('CI_PIPELINE_ID', '')
+    if not re.fullmatch(r'[1-9][0-9]*', pipeline):
+        raise ValueError('development versions require a numeric CI_PIPELINE_ID')
+    if node:
+        version_key(value, True)
+        return value.split('-')[0].split('+')[0] + '-dev.' + pipeline
+    version = Version(value)
+    if version.local or version.post is not None:
+        raise ValueError('development builds require a version without local/post suffixes')
+    return version.base_version + '.dev' + pipeline
+
+
+def release_channel(value, node=False):
+    if node:
+        version_key(value, True)
+        pre = value.split('+')[0].partition('-')[2]
+        label = pre.split('.')[0] if pre else 'latest'
+        return 'next' if label.isdigit() else label
+    version = Version(value)
+    if version.is_devrelease:
+        return 'dev'
+    return {'a': 'alpha', 'b': 'beta', 'rc': 'rc'}[version.pre[0]] if version.pre else 'latest'
+
+
+def endpoint(value, hosts):
+    allowed_url(value, hosts)
+    parsed = urlsplit(value)
+    return urlunsplit(('https', parsed.netloc.lower().removesuffix(':443'), parsed.path.rstrip('/'), '', ''))
+
+
+def destination(project, directory, hosts, development=False):
+    settings = project['package']
+    preview = settings.get('preview') or {}
+    if project['python'] is not None:
+        rows = tomllib.loads((directory / 'pyproject.toml').read_text()).get('tool', {}).get('uv', {}).get('index', [])
+        name = (preview.get('index') or settings['index']) if development else settings['index']
+        selected = [row for row in rows if row.get('name') == name and row.get('publish-url')]
+        if len(selected) != 1:
+            raise ValueError('select one named uv index with publish-url in pyproject.toml')
+        row = selected[0]
+        url = endpoint(row['publish-url'], hosts)
+        return {'index': name, 'url': url, 'check_url': endpoint(row['url'], hosts)}
+    meta = json.loads((directory / 'package.json').read_text())
+    normal = preview.get('registry') if development else None
+    normal = normal or meta.get('publishConfig', {}).get('registry')
+    if not normal:
+        raise ValueError('package.json publishConfig.registry is required')
+    normal = endpoint(normal, hosts)
+    return {'url': normal}
+
+
+def rewrite_snapshot(directory, node, target):
+    path = directory / ('package.json' if node else 'pyproject.toml')
+    meta = json.loads(path.read_text()) if node else tomlkit.parse(path.read_text())
+    package = meta if node else meta['project']
+    original = package.get('version')
+    if not isinstance(original, str):
+        raise ValueError('development publication requires a static manifest version')
+    package['version'] = snapshot_version(original, node)
+    if node:
+        # npm can prefer the archive's publishConfig over command-line options.
+        meta['publishConfig'] = {**meta.get('publishConfig', {}), 'registry': target['url'], 'tag': 'dev'}
+    path.write_text(json.dumps(meta, indent=2) + '\n' if node else tomlkit.dumps(meta))
+    return package['version']
+
+
+def check_development_context(plan):
+    if plan['event'] == 'release' or os.environ.get('CI_COMMIT_TAG'):
+        raise ValueError('development publication generates a snapshot; use auto to publish the tagged version')