generic-gitlab-cicd 0.3.2__tar.gz → 0.3.4__tar.gz

generic_gitlab_cicd-0.3.4/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: generic-gitlab-cicd
+Version: 0.3.4
+Summary: Validated project configuration and reproducible GitLab delivery pipelines
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: PyYAML<7,>=6
+Requires-Dist: tomlkit<1,>=0.13
+Requires-Dist: packaging<27,>=25
+
+# Generic GitLab CI/CD
+
+**Define your projects and checks. Generate a reviewable GitLab pipeline.**
+
+Generic GitLab CI/CD is a Python toolkit that turns a small delivery configuration into a committed `.gitlab-ci.yml`. It connects your existing test commands, application builds, package publication, container builds, and Helm deployments while keeping infrastructure settings separate from application configuration.
+
+The package is named `generic-gitlab-cicd`; the command is `generic-ci`. GitLab and your runners execute the generated pipeline. The CLI validates and generates configuration locally.
+
+[Quick start](#quick-start) · [Workflow guide](docs/workflows-revision-one.md) · [CLI reference](docs/cli-reference.md) · [Examples](examples/workflows) · [Documentation](docs/README.md)
+
+## One repository. Tests, packages, and deployment.
+
+Keep your shared Python package and API together. Generic CI tests them, publishes the package on release, and deploys the API to OpenShift.
+
+```yaml
+version: 1
+
+projects:
+  sdk:
+    path: packages/sdk
+    python: {}
+    checks:
+      tests:
+        script: [uv run --no-sync pytest]
+    package:
+      index: internal
+    release:
+      tag: v{version}
+    workflows:
+      merge-request:
+        checks: [tests]
+      release:
+        checks: [tests]
+        publish: true
+
+  api:
+    path: services/api
+    depends-on: [sdk]
+    python: {}
+    checks:
+      tests:
+        script: [uv run --no-sync pytest]
+    container:
+      dockerfile: Dockerfile
+    release:
+      tag: v{version}
+      needs: [sdk]
+    workflows:
+      merge-request:
+        checks: [tests]
+      release:
+        checks: [tests]
+        build: [container]
+
+deployments:
+  api:
+    target: production
+    chart:
+      path: deploy/chart
+    values: [deploy/values.yaml]
+    images:
+      - from: api.build-image
+        set:
+          repository: apps.api.image.repository
+          tag: apps.api.image.tag
+    workflows:
+      release:
+        when: manual
+```
+
+**What you get:**
+
+- **On merge requests:** test affected projects. SDK changes also select the API for testing.
+- **On a release tag:** run checks, publish the SDK, and build the API image. The API release depends on SDK publication; its tests and image build can run independently.
+- **When you approve deployment:** deploy the built API image through Helm to OpenShift.
+
+Both projects use a shared version: projects at `1.2.0` release under the protected tag `v1.2.0`. Dependency installation follows each project's declared dependencies and committed lockfile; `depends-on` selects work, not package replacements.
+
+Your organization supplies prepared runtime images, registry settings, and the production target in `ci-platform.yml`. The application's `deploy/chart` and `deploy/values.yaml` describe the deployment. Start with the [shared chart](charts/generic-app) and [values example](examples/helm-values.yaml); configure the named `internal` publishing index and CI credentials through your platform.
+
+## Quick start
+
+Use Python **3.11 or newer**. From a checkout of this toolkit, install the CLI into an isolated environment:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install .
+```
+
+Then, from your application repository:
+
+```sh
+generic-ci setup
+```
+
+Setup guides you through organization templates or standalone configuration, previews files before writing, and includes local editor schemas. Start with its single-app configuration and add projects as needed, or choose an organization template for your monorepo. See the [setup guide](docs/setup-revision-one.md) for prepared images, unattended options, and editor integration.
+
+After editing your configuration:
+
+```sh
+generic-ci validate
+generic-ci render -o .gitlab-ci.yml
+```
+
+Review and commit `delivery.yml`, your platform configuration, and the generated `.gitlab-ci.yml` together. Validate the generated pipeline with your GitLab CI Lint, then push your branch.
+
+**Prefer autocomplete?** Setup exports the schemas automatically. You can also refresh them from the installed CLI:
+
+```sh
+generic-ci schema -o .generic-ci/delivery.schema.json
+generic-ci schema --platform-schema -o .generic-ci/platform.schema.json
+```
+
+Associate them with `delivery.yml` and `ci-platform.yml` in your editor. The [editor guide](docs/setup-revision-one.md#editor-completion-and-validation) includes PyCharm instructions.
+
+## Add the delivery features you need
+
+| Goal | Configuration / next step |
+| --- | --- |
+| Test Node, pnpm, or Bun projects | Declare `node.package-manager`, commit the corresponding lockfile, and use your existing commands; see the [workflow guide](docs/workflows-revision-one.md) |
+| Build application artifacts | Set `build.script` and `build.outputs`; select `build: [application]` in the workflow |
+| Retest downstream projects | Add project `depends-on: [sdk]`; this propagates change selection |
+| Transfer generated files to another job | Add check/build `needs: [sdk.build]`; the producer must be enabled in the same event |
+| Build and push containers | Configure `container` and select `build: [container]`; the default builder is Buildah |
+| Publish Python or npm-compatible packages | Configure `package` and workflow `publish`; see [publication behavior](docs/workflows-revision-one.md#package-publication--revision-four) |
+| Coordinate releases | Configure project versions, tag conventions, and optional `release.needs`; see the [release workflow](docs/workflows-revision-one.md#version-bumps-and-release-button) |
+| Deploy to OpenShift | Configure a Helm deployment, target, values, and image bindings; start with the [deployment example](examples/workflows/delivery.yml) and [chart values](examples/helm-values.yaml) |
+
+`depends-on` and `needs` have different jobs: the first selects affected projects; the second transfers explicit same-event outputs. Neither implicitly installs an unreleased package. Candidate dependency testing has a separate contract described in the [workflow guide](docs/workflows-revision-one.md).
+
+## Share organization defaults
+
+An organization source can provide platform defaults and starter templates. Initialize from a reviewed source revision:
+
+```sh
+generic-ci init --repo ssh://git@gitlab.example.internal/platform/ci-config.git \
+  --ref v1.0.0 --template python-service
+```
+
+The repository, ref, and template name above are examples; the source must contain the toolkit's source manifest. Initialization copies starter files and records an exact source commit. Commit the resulting descriptor and lockfile. Later source updates change inherited defaults while preserving consumer-owned template files.
+
+For disconnected authoring, cache the locked source or import a Git bundle, then render with `--offline`. This flag controls configuration-source acquisition; it does not enforce network isolation inside application jobs. See [configuration sources](docs/configuration-sources-revision-two.md) for source layout, registration, updates, and offline setup.
+
+## OpenShift deployment
+
+The bundled [generic-app chart](charts/generic-app) supports multiple applications, Services, OpenShift Routes with TLS, probes, resources, ports, volumes/mounts, and pod labels/annotations. Images use **repository + tag**; Buildah also records the pushed digest as evidence. Security contexts are configurable, with cluster defaults applying when unset.
+
+Helm deployments support complete updates and partial updates that preserve unchanged service images. Partial updates require a compatible existing baseline; chart or configuration changes require a complete deployment. Production requires a protected ref, and candidate dependency runs cannot update persistent deployments.
+
+You supply registry credentials, CA trust, a kubeconfig, namespace resources, and application values. The toolkit does not provision the cluster, issue certificates, create PVCs automatically, or make multi-project publication transactional. Keep release image tags immutable: the shared chart uses `IfNotPresent`.
+
+## Existing component users
+
+The repository also contains [low-level GitLab CI/CD components](templates) and the older compiler, available through `--format legacy`. They are separate interfaces from the workflow configuration above. New users should start with the CLI walkthrough.
+
+Mirror components into your GitLab instance and pin includes to an immutable revision. Consult the [component air-gap guide](docs/airgap.md) for setup. Older BuildKit/digest-only Helm adapters target chart 1.x; the current chart uses OpenShift Routes and repository/tag values. Do not mix those contracts without migrating the configuration.
+
+## Development and validation
+
+From a toolkit checkout with Python, Git, Node/npm, rsync, and Helm available:
+
+```sh
+python -m pip install . build twine uv setuptools
+npm ci --ignore-scripts --no-audit --no-fund
+python scripts/sync_embedded.py --check
+python scripts/sync_authoring_skill.py --check
+python -m unittest discover -s tests -v
+npm run test:ci-local
+```
+
+The local pipeline fixtures use pinned `gitlab-ci-local`. Real GitLab/Runner E2E runs are deliberate, through workflow dispatch or an opt-in PR label. Use focused tests while iterating; see [testing commands and evidence](docs/testing-revision-one.md) for prerequisites, integration tests, release checks, and scenario selection.
+
+Version 0.3.2 passed [fast CI](https://github.com/Heknon/generic-gitlab-cicd/actions/runs/33975049919) and [six real GitLab E2E scenarios](https://github.com/Heknon/generic-gitlab-cicd/actions/runs/33975818144). That evidence covers the tested pipeline fixtures, not deployment to your registry or OpenShift cluster. Qualify Buildah execution, registry access, Route admission, and rollout/rollback on your infrastructure before production use. Workflow runtime execution currently targets Linux; Windows workflow execution is not supported.
+
+## Documentation
+
+- [CLI commands, file ownership, and path rules](docs/cli-reference.md)
+- [Checks, builds, releases, and deployment workflows](docs/workflows-revision-one.md)
+- [Organization configuration sources](docs/configuration-sources-revision-two.md)
+- [AI-assisted authoring and portable skill](docs/ai-authoring-revision-three.md)
+- [Publishing the toolkit to PyPI](docs/pypi-release.md)
+- [Full documentation map](docs/README.md)

generic_gitlab_cicd-0.3.4/README.md

@@ -0,0 +1,183 @@
+# Generic GitLab CI/CD
+
+**Define your projects and checks. Generate a reviewable GitLab pipeline.**
+
+Generic GitLab CI/CD is a Python toolkit that turns a small delivery configuration into a committed `.gitlab-ci.yml`. It connects your existing test commands, application builds, package publication, container builds, and Helm deployments while keeping infrastructure settings separate from application configuration.
+
+The package is named `generic-gitlab-cicd`; the command is `generic-ci`. GitLab and your runners execute the generated pipeline. The CLI validates and generates configuration locally.
+
+[Quick start](#quick-start) · [Workflow guide](docs/workflows-revision-one.md) · [CLI reference](docs/cli-reference.md) · [Examples](examples/workflows) · [Documentation](docs/README.md)
+
+## One repository. Tests, packages, and deployment.
+
+Keep your shared Python package and API together. Generic CI tests them, publishes the package on release, and deploys the API to OpenShift.
+
+```yaml
+version: 1
+
+projects:
+  sdk:
+    path: packages/sdk
+    python: {}
+    checks:
+      tests:
+        script: [uv run --no-sync pytest]
+    package:
+      index: internal
+    release:
+      tag: v{version}
+    workflows:
+      merge-request:
+        checks: [tests]
+      release:
+        checks: [tests]
+        publish: true
+
+  api:
+    path: services/api
+    depends-on: [sdk]
+    python: {}
+    checks:
+      tests:
+        script: [uv run --no-sync pytest]
+    container:
+      dockerfile: Dockerfile
+    release:
+      tag: v{version}
+      needs: [sdk]
+    workflows:
+      merge-request:
+        checks: [tests]
+      release:
+        checks: [tests]
+        build: [container]
+
+deployments:
+  api:
+    target: production
+    chart:
+      path: deploy/chart
+    values: [deploy/values.yaml]
+    images:
+      - from: api.build-image
+        set:
+          repository: apps.api.image.repository
+          tag: apps.api.image.tag
+    workflows:
+      release:
+        when: manual
+```
+
+**What you get:**
+
+- **On merge requests:** test affected projects. SDK changes also select the API for testing.
+- **On a release tag:** run checks, publish the SDK, and build the API image. The API release depends on SDK publication; its tests and image build can run independently.
+- **When you approve deployment:** deploy the built API image through Helm to OpenShift.
+
+Both projects use a shared version: projects at `1.2.0` release under the protected tag `v1.2.0`. Dependency installation follows each project's declared dependencies and committed lockfile; `depends-on` selects work, not package replacements.
+
+Your organization supplies prepared runtime images, registry settings, and the production target in `ci-platform.yml`. The application's `deploy/chart` and `deploy/values.yaml` describe the deployment. Start with the [shared chart](charts/generic-app) and [values example](examples/helm-values.yaml); configure the named `internal` publishing index and CI credentials through your platform.
+
+## Quick start
+
+Use Python **3.11 or newer**. From a checkout of this toolkit, install the CLI into an isolated environment:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install .
+```
+
+Then, from your application repository:
+
+```sh
+generic-ci setup
+```
+
+Setup guides you through organization templates or standalone configuration, previews files before writing, and includes local editor schemas. Start with its single-app configuration and add projects as needed, or choose an organization template for your monorepo. See the [setup guide](docs/setup-revision-one.md) for prepared images, unattended options, and editor integration.
+
+After editing your configuration:
+
+```sh
+generic-ci validate
+generic-ci render -o .gitlab-ci.yml
+```
+
+Review and commit `delivery.yml`, your platform configuration, and the generated `.gitlab-ci.yml` together. Validate the generated pipeline with your GitLab CI Lint, then push your branch.
+
+**Prefer autocomplete?** Setup exports the schemas automatically. You can also refresh them from the installed CLI:
+
+```sh
+generic-ci schema -o .generic-ci/delivery.schema.json
+generic-ci schema --platform-schema -o .generic-ci/platform.schema.json
+```
+
+Associate them with `delivery.yml` and `ci-platform.yml` in your editor. The [editor guide](docs/setup-revision-one.md#editor-completion-and-validation) includes PyCharm instructions.
+
+## Add the delivery features you need
+
+| Goal | Configuration / next step |
+| --- | --- |
+| Test Node, pnpm, or Bun projects | Declare `node.package-manager`, commit the corresponding lockfile, and use your existing commands; see the [workflow guide](docs/workflows-revision-one.md) |
+| Build application artifacts | Set `build.script` and `build.outputs`; select `build: [application]` in the workflow |
+| Retest downstream projects | Add project `depends-on: [sdk]`; this propagates change selection |
+| Transfer generated files to another job | Add check/build `needs: [sdk.build]`; the producer must be enabled in the same event |
+| Build and push containers | Configure `container` and select `build: [container]`; the default builder is Buildah |
+| Publish Python or npm-compatible packages | Configure `package` and workflow `publish`; see [publication behavior](docs/workflows-revision-one.md#package-publication--revision-four) |
+| Coordinate releases | Configure project versions, tag conventions, and optional `release.needs`; see the [release workflow](docs/workflows-revision-one.md#version-bumps-and-release-button) |
+| Deploy to OpenShift | Configure a Helm deployment, target, values, and image bindings; start with the [deployment example](examples/workflows/delivery.yml) and [chart values](examples/helm-values.yaml) |
+
+`depends-on` and `needs` have different jobs: the first selects affected projects; the second transfers explicit same-event outputs. Neither implicitly installs an unreleased package. Candidate dependency testing has a separate contract described in the [workflow guide](docs/workflows-revision-one.md).
+
+## Share organization defaults
+
+An organization source can provide platform defaults and starter templates. Initialize from a reviewed source revision:
+
+```sh
+generic-ci init --repo ssh://git@gitlab.example.internal/platform/ci-config.git \
+  --ref v1.0.0 --template python-service
+```
+
+The repository, ref, and template name above are examples; the source must contain the toolkit's source manifest. Initialization copies starter files and records an exact source commit. Commit the resulting descriptor and lockfile. Later source updates change inherited defaults while preserving consumer-owned template files.
+
+For disconnected authoring, cache the locked source or import a Git bundle, then render with `--offline`. This flag controls configuration-source acquisition; it does not enforce network isolation inside application jobs. See [configuration sources](docs/configuration-sources-revision-two.md) for source layout, registration, updates, and offline setup.
+
+## OpenShift deployment
+
+The bundled [generic-app chart](charts/generic-app) supports multiple applications, Services, OpenShift Routes with TLS, probes, resources, ports, volumes/mounts, and pod labels/annotations. Images use **repository + tag**; Buildah also records the pushed digest as evidence. Security contexts are configurable, with cluster defaults applying when unset.
+
+Helm deployments support complete updates and partial updates that preserve unchanged service images. Partial updates require a compatible existing baseline; chart or configuration changes require a complete deployment. Production requires a protected ref, and candidate dependency runs cannot update persistent deployments.
+
+You supply registry credentials, CA trust, a kubeconfig, namespace resources, and application values. The toolkit does not provision the cluster, issue certificates, create PVCs automatically, or make multi-project publication transactional. Keep release image tags immutable: the shared chart uses `IfNotPresent`.
+
+## Existing component users
+
+The repository also contains [low-level GitLab CI/CD components](templates) and the older compiler, available through `--format legacy`. They are separate interfaces from the workflow configuration above. New users should start with the CLI walkthrough.
+
+Mirror components into your GitLab instance and pin includes to an immutable revision. Consult the [component air-gap guide](docs/airgap.md) for setup. Older BuildKit/digest-only Helm adapters target chart 1.x; the current chart uses OpenShift Routes and repository/tag values. Do not mix those contracts without migrating the configuration.
+
+## Development and validation
+
+From a toolkit checkout with Python, Git, Node/npm, rsync, and Helm available:
+
+```sh
+python -m pip install . build twine uv setuptools
+npm ci --ignore-scripts --no-audit --no-fund
+python scripts/sync_embedded.py --check
+python scripts/sync_authoring_skill.py --check
+python -m unittest discover -s tests -v
+npm run test:ci-local
+```
+
+The local pipeline fixtures use pinned `gitlab-ci-local`. Real GitLab/Runner E2E runs are deliberate, through workflow dispatch or an opt-in PR label. Use focused tests while iterating; see [testing commands and evidence](docs/testing-revision-one.md) for prerequisites, integration tests, release checks, and scenario selection.
+
+Version 0.3.2 passed [fast CI](https://github.com/Heknon/generic-gitlab-cicd/actions/runs/33975049919) and [six real GitLab E2E scenarios](https://github.com/Heknon/generic-gitlab-cicd/actions/runs/33975818144). That evidence covers the tested pipeline fixtures, not deployment to your registry or OpenShift cluster. Qualify Buildah execution, registry access, Route admission, and rollout/rollback on your infrastructure before production use. Workflow runtime execution currently targets Linux; Windows workflow execution is not supported.
+
+## Documentation
+
+- [CLI commands, file ownership, and path rules](docs/cli-reference.md)
+- [Checks, builds, releases, and deployment workflows](docs/workflows-revision-one.md)
+- [Organization configuration sources](docs/configuration-sources-revision-two.md)
+- [AI-assisted authoring and portable skill](docs/ai-authoring-revision-three.md)
+- [Publishing the toolkit to PyPI](docs/pypi-release.md)
+- [Full documentation map](docs/README.md)

{generic_gitlab_cicd-0.3.2 → generic_gitlab_cicd-0.3.4}/generic_ci/__init__.py

@@ -1,3 +1,3 @@
 """Public configuration compiler. Runtime images must carry this exact version."""
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"

{generic_gitlab_cicd-0.3.2 → generic_gitlab_cicd-0.3.4}/generic_ci/cli.py

@@ -13,6 +13,13 @@ from .models import Pipeline, Platform
 
 def main(argv=None):
     argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == 'setup':
+        from .setup import setup_main
+        try:
+            return setup_main(argv[1:])
+        except (ValueError, OSError, EOFError, ValidationError) as error:
+            print(f'generic-ci setup: {error}', file=sys.stderr)
+            return 1
     if argv and argv[0] == 'source':
         from .sources import source_main
         try:
@@ -21,7 +28,7 @@ def main(argv=None):
             print(f'generic-ci: {error}', file=sys.stderr)
             return 1
     parser = argparse.ArgumentParser(prog="generic-ci")
-    parser.add_argument("command", choices=["schema", "validate", "explain", "render", "init"])
+    parser.add_argument("command", choices=["schema", "validate", "explain", "render", "init", "setup"])
     parser.add_argument("--config")
     parser.add_argument("--format", choices=["workflows", "legacy"], default="workflows")
     parser.add_argument("--ecosystem", choices=["python", "npm", "pnpm", "bun"], default="python")

generic_gitlab_cicd-0.3.4/generic_ci/setup.py

@@ -0,0 +1,209 @@
+"""Guided configuration authoring; never executes application commands."""
+import argparse
+import json
+from pathlib import Path
+import sys
+import tempfile
+from urllib.parse import urlsplit
+
+import yaml
+
+from .models import relative
+
+
+def setup_main(argv):
+    parser = argparse.ArgumentParser(prog='generic-ci setup', description=__doc__)
+    parser.add_argument('--root', default='.')
+    parser.add_argument('--mode', choices=['organization', 'standalone'])
+    parser.add_argument('--yes', action='store_true', help='Use supplied/default answers and write without prompting')
+    parser.add_argument('--dry-run', action='store_true', help='Validate and preview without writing project files')
+    parser.add_argument('--offline', action='store_true')
+    for flag in ['repo', 'ref', 'source', 'template', 'app', 'path', 'ecosystem', 'test-command',
+                 'runtime-image', 'builder-image', 'registry', 'preview-registry', 'runner-tag',
+                 'deploy', 'helm-image', 'chart-oci', 'chart-version', 'namespace', 'hostname', 'port', 'tls']:
+        parser.add_argument('--' + flag)
+    args = parser.parse_args(argv)
+    root = Path(args.root).absolute()
+    if not root.is_dir():
+        raise ValueError('--root must be an existing application directory')
+    interactive = not args.yes and sys.stdin.isatty()
+    if not interactive and not args.yes:
+        raise ValueError('non-interactive setup requires --yes (use --dry-run to preview)')
+
+    def ask(key, question, default=None, choices=None):
+        value = getattr(args, key.replace('-', '_'))
+        if value is None:
+            if interactive:
+                value = input(question + (f' [{default}]' if default is not None else '') + ': ').strip() or default
+            else:
+                value = default
+        if value is None or value == '':
+            raise ValueError(f'--{key} is required')
+        if choices and value not in choices:
+            raise ValueError(f'--{key} must be one of: {", ".join(choices)}')
+        return value
+
+    mode = ask('mode', 'Setup path: organization or standalone', 'organization' if args.repo or args.source else 'standalone', ['organization', 'standalone'])
+    with tempfile.TemporaryDirectory(prefix='generic-ci-setup-') as temporary:
+        stage = Path(temporary)
+        if mode == 'organization':
+            from .sources import initialize
+            repo = None if args.source else ask('repo', 'Organization configuration Git repository (GitHub or GitLab URL)')
+            ref = ask('ref', 'Source revision') if repo else None
+            if not args.template:
+                initialize(stage, None, args.source, repo, ref, args.offline)
+            template = ask('template', 'Template name')
+            initialize(stage, template, args.source, repo, ref, args.offline)
+            descriptor = yaml.safe_load((stage / 'generic-ci.yml').read_text())
+            delivery_path = stage / descriptor['delivery']
+            config = yaml.safe_load(delivery_path.read_text())
+            projects = config.get('projects', {})
+            if projects:
+                selected = ask('app', 'Application in template to configure', next(iter(projects)), list(projects))
+                project = projects[selected]
+                project['path'] = relative(ask('path', 'Application directory', project.get('path', '.')))
+                checks = project.get('checks', {})
+                if len(checks) == 1:
+                    check = next(iter(checks.values()))
+                    existing = check.get('script', [])
+                    if len(existing) == 1:
+                        check['script'] = [ask('test-command', 'Confirm template check command', existing[0])]
+                elif args.test_command:
+                    raise ValueError('template has multiple/no checks; edit its delivery configuration to select commands')
+                delivery_path.write_text(yaml.safe_dump(config, sort_keys=False))
+            if any(getattr(args, key) is not None for key in ['ecosystem', 'deploy', 'runtime_image', 'builder_image', 'registry', 'preview_registry', 'runner_tag', 'helm_image', 'chart_oci', 'chart_version', 'namespace', 'hostname', 'port', 'tls']):
+                raise ValueError('organization mode inherits infrastructure/deployment settings from its template; use standalone mode for infrastructure flags')
+        else:
+            if args.repo or args.ref or args.source or args.template:
+                raise ValueError('source options require organization mode')
+            name = ask('app', 'Application name', 'app')
+            path = relative(ask('path', 'Application directory relative to repository', '.'))
+            application = root / path
+            if not application.is_dir() or not application.resolve().is_relative_to(root.resolve()):
+                raise ValueError('application directory must exist inside the repository')
+            detected = 'python' if (application / 'pyproject.toml').exists() else 'npm' if (application / 'package.json').exists() else 'generic'
+            for lock, manager in [('pnpm-lock.yaml', 'pnpm'), ('bun.lock', 'bun')]:
+                if (application / lock).exists():
+                    detected = manager
+            ecosystem = ask('ecosystem', 'Detected ecosystem (confirm or change)', detected, ['python', 'npm', 'pnpm', 'bun', 'generic'])
+            command = None
+            if ecosystem in ['npm', 'pnpm', 'bun'] and (application / 'package.json').exists():
+                if 'test' in json.loads((application / 'package.json').read_text()).get('scripts', {}):
+                    command = ecosystem + ' run test'
+            test = ask('test-command', 'Test command (existing command; never executed by setup)', command)
+            runtime = ask('runtime-image', 'Prepared runtime image containing the matching toolkit')
+            builder = ask('builder-image', 'Prepared Buildah image containing the matching toolkit')
+            registry = ask('registry', 'Release container registry/repository prefix')
+            previews = ask('preview-registry', 'Preview container registry/repository prefix')
+            tag = ask('runner-tag', 'Runner tag')
+            project = {'path': path, 'checks': {'test': {'script': [test]}},
+                       'workflows': {'push': {'checks': ['test']}, 'merge-request': {'checks': ['test']}}}
+            role = 'python' if ecosystem in ['python', 'generic'] else 'bun' if ecosystem == 'bun' else 'node'
+            if ecosystem == 'python':
+                project['python'] = {}
+            elif ecosystem != 'generic':
+                project['node'] = {'package-manager': ecosystem}
+            platform = {'version': 1, 'defaults': {'tags': [tag]}, 'images': {role: runtime},
+                        'container-builder': {'image': builder},
+                        'registries': {'containers': registry, 'previews': previews},
+                        'allowed-hosts': sorted({x.split('/')[0] for x in [runtime, builder, registry, previews]}),
+                        'variables': {'UV_PYTHON_DOWNLOADS': 'never'}}
+            delivery = {'version': 1, 'projects': {name: project}}
+            deploy = ask('deploy', 'Create an OpenShift MR preview deployment? yes/no', 'no', ['yes', 'no'])
+            if deploy == 'yes':
+                if not (application / 'Dockerfile').is_file():
+                    raise ValueError('deployment setup requires an existing Dockerfile in the application directory')
+                helm = ask('helm-image', 'Prepared Helm image containing Git, Python and the toolkit')
+                chart = ask('chart-oci', 'Published generic-app 2.x compatible OCI chart URL')
+                version = ask('chart-version', 'Pinned chart version')
+                namespace = ask('namespace', 'Existing preview namespace')
+                hostname = ask('hostname', 'Route hostname (auto lets OpenShift assign a unique hostname)' )
+                port = int(ask('port', 'Application listening port', '8080'))
+                if not 1 <= port <= 65535:
+                    raise ValueError('--port must be between 1 and 65535')
+                tls = ask('tls', 'Route TLS mode', 'edge', ['edge', 'reencrypt', 'passthrough', 'none'])
+                project['workflows']['merge-request']['build'] = ['container']
+                project['container'] = {'dockerfile': 'Dockerfile', 'context': '.'}
+                platform['images']['helm'] = helm
+                platform['allowed-hosts'] = sorted(set(platform['allowed-hosts'] + [helm.split('/')[0], urlsplit(chart).hostname or '']))
+                platform['targets'] = {'preview': {'namespace': namespace, 'production': False, 'kubeconfig-variable': 'PREVIEW_KUBECONFIG'}}
+                delivery['deployments'] = {name: {'target': 'preview', 'chart': {'oci': chart, 'version': version},
+                    'values': ['deploy/values.yaml'], 'images': [{'from': name + '.build-image',
+                    'set': {'repository': 'apps.' + name + '.image.repository', 'tag': 'apps.' + name + '.image.tag'}}],
+                    'workflows': {'merge-request': {'when': 'manual'}}}}
+                # Helm values are literal: CI variables in a hostname are not expanded.
+                if '$' in hostname:
+                    raise ValueError('Route hostname is literal; use auto for an OpenShift-generated hostname')
+                route = {'enabled': True}
+                if hostname != 'auto':
+                    route['host'] = hostname
+                if tls != 'none':
+                    route['tls'] = {'termination': tls, 'insecureEdgeTerminationPolicy': 'Redirect'}
+                values = {'apps': {name: {'enabled': True, 'replicas': 1, 'image': {'repository': previews + '/' + name, 'tag': 'setup-placeholder'},
+                    'config': {}, 'secretRefs': [], 'service': {'enabled': True, 'port': 80, 'targetPort': port}, 'route': route}}}
+                (stage / 'deploy').mkdir()
+                (stage / 'deploy/values.yaml').write_text(yaml.safe_dump(values, sort_keys=False))
+            for filename, value in [('delivery.yml', delivery), ('ci-platform.yml', platform)]:
+                (stage / filename).write_text(yaml.safe_dump(value, sort_keys=False))
+        from .cli import main
+        schema_dir = stage / '.generic-ci'
+        schema_dir.mkdir(exist_ok=True)
+        for name, extra in [('delivery.schema.json', []), ('platform.schema.json', ['--platform-schema'])]:
+            target = schema_dir / name
+            if target.exists():
+                raise ValueError('template supplies a reserved setup schema path: ' + name)
+            if main(['schema', *extra, '-o', str(target)]):
+                raise ValueError('schema generation failed')
+        import os
+        descriptor = yaml.safe_load((stage / 'generic-ci.yml').read_text()) if (stage / 'generic-ci.yml').exists() else {}
+        for name, schema in [(descriptor.get('delivery', 'delivery.yml'), 'delivery.schema.json'),
+                             (descriptor.get('platform') or 'ci-platform.yml', 'platform.schema.json')]:
+            target = stage / name
+            if target.is_file():
+                reference = Path(os.path.relpath(schema_dir / schema, target.parent)).as_posix()
+                target.write_text('# yaml-language-server: $schema=' + reference + '\n' + target.read_text())
+        if main(['validate', '--root', str(stage), *(['--offline'] if args.offline else [])]):
+            raise ValueError('setup configuration did not validate; no project files written')
+        if main(['render', '--root', str(stage), '-o', str(stage / '.gitlab-ci.yml'), *(['--offline'] if args.offline else [])]):
+            raise ValueError('setup rendering failed; no project files written')
+        notes = stage / 'CI-SETUP.md'
+        if not notes.exists():
+            notes.write_text('# CI setup — revision one\n\nReview delivery.yml and the generated .gitlab-ci.yml before committing.\n\n'
+                '- Provide matching toolkit runtime images, runner tags, registry authentication and CA trust.\n'
+                '- Local schemas: .generic-ci/delivery.schema.json and .generic-ci/platform.schema.json. In PyCharm Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings, associate each schema with its YAML file. YAML-language-server editors can use the generated schema comment.\n'
+                '- Commit package-manager lockfiles and declare the dependencies needed by your checks.\n'
+                '- For previews, provide PREVIEW_KUBECONFIG as a GitLab file variable, an existing namespace, image pull secrets and a published compatible chart.\n'
+                '- Review Route host uniqueness, TLS certificates/backend trust, probes and application secrets in deploy/values.yaml when present.\n'
+                '- Run generic-ci validate and generic-ci render -o .gitlab-ci.yml after editing.\n'
+                '- Validate with your GitLab CI Lint and execute a test pipeline. Setup does not build, publish, provision or deploy anything.\n')
+        files = sorted(p for p in stage.rglob('*') if p.is_file())
+        for file in files:
+            dest = root / file.relative_to(stage)
+            if dest.exists() or dest.is_symlink() or any(p.is_symlink() for p in dest.parents):
+                raise ValueError(f'setup will not overwrite or follow symlinks: {dest}')
+            if any(p.exists() and not p.is_dir() for p in dest.parents):
+                raise ValueError(f'parent is not a directory: {dest}')
+        print('Proposed files:')
+        for file in files:
+            print('  ' + file.relative_to(stage).as_posix())
+        print('\nDelivery configuration:\n' + (stage / descriptor.get('delivery', 'delivery.yml')).read_text())
+        if args.dry_run:
+            print('Dry run: no project files written.')
+            return 0
+        if interactive and input('Write these files? [y/N]: ').strip().lower() not in ['y', 'yes']:
+            print('Cancelled: no project files written.')
+            return 0
+        created = []
+        try:
+            for file in files:
+                dest = root / file.relative_to(stage)
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                with dest.open('xb') as stream:
+                    created.append(dest)
+                    stream.write(file.read_bytes())
+        except OSError:
+            for file in created:
+                file.unlink(missing_ok=True)
+            raise
+        print('Setup complete. Review CI-SETUP.md, validate with GitLab CI Lint, and commit the configuration.')
+        return 0