quoll-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{quoll_cli-0.2.0 → quoll_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quoll-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Production-grade CI, Dockerfiles, Helm charts and delivery for any repository, kept in sync with one quoll.toml
 Project-URL: Homepage, https://github.com/theo-mrn/Quoll
 Project-URL: Repository, https://github.com/theo-mrn/Quoll
@@ -254,7 +254,7 @@ quoll ci add-step -d back     # in a workspace: the project's directory; asks wh
 # .pre-commit-config.yaml
 repos:
   - repo: https://github.com/theo-mrn/Quoll
-    rev: v0.2.0
+    rev: v0.3.0
     hooks:
       - id: quoll-ci          # quoll ci update; also quoll-docker, quoll-cd
 ```
@@ -411,7 +411,7 @@ Every push to the default branch and every `v*` tag:
 | Runs after CI | through branch protection | always: its `publish` stage starts once every CI job passed |
 | Default registry (no secret) | GHCR, with the workflow's token | the project's container registry, with the job token |
 | Build | Buildx, GitHub Actions cache | Docker-in-Docker, a Buildx container builder; Trivy runs next to the image |
-| Signature | artifact attestations (public repositories, or GitHub Enterprise Cloud for private ones) | cosign keyless with the job's OIDC token (gitlab.com: Sigstore's public instance doesn't trust self-managed issuers) |
+| Signature | artifact attestations (public repositories, or GitHub Enterprise Cloud for private ones: `quoll cd init` turns signing off on a private repository, `--sign` keeps it) | cosign keyless with the job's OIDC token (gitlab.com: Sigstore's public instance doesn't trust self-managed issuers) |
 
 Docker Hub (`registry = "dockerhub"`) needs `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN`. Multi-arch images are a `platforms` entry away.
 
@@ -421,16 +421,35 @@ registry = "ghcr"                 # ghcr (GitHub) | gitlab (GitLab) | dockerhub
 image = "ghcr.io/acme/api"
 branches = ["main"]
 release_tags = true
+release_pr = true                 # GitHub: release-please opens the release PR that tags v* (below)
 platforms = ["linux/amd64"]       # e.g. ["linux/amd64", "linux/arm64"]
 scan = true
 severity = ["CRITICAL", "HIGH"]
 ignore_unfixed = true
 sbom = true                       # SBOM of the image: artifact + release asset
-sign = true                       # Sigstore signature and attestations (set false on a private repo without GitHub Enterprise)
+sign = true                       # Sigstore signature and attestations (`cd init` writes false on a private GitHub repo)
 ```
 
 On GitHub, branch protection (set by `quoll ci init`) makes sure only commits that passed CI reach the default branch, and therefore the registry.
 
+### Releases
+
+On GitHub, nobody has to push the `v*` tags: with `release_pr` (the default of `quoll cd init`), [release-please](https://github.com/googleapis/release-please) reads the [Conventional Commits](https://www.conventionalcommits.org/) on the default branch and keeps a **release PR** open with the next version and its `CHANGELOG.md`. Merging it tags `v<version>` and creates the GitHub release, which publishes the image and, with a chart, deploys to production after the approval.
+
+```
+feat: …  fix: …  feat!: …   →   release PR "chore(main): release 1.3.0"   →   merge   →   v1.3.0   →   CD
+```
+
+- `fix:` bumps the patch, `feat:` the minor, a breaking change (`feat!:`, `BREAKING CHANGE:`) the major. Before `1.0.0`, a breaking change bumps the minor.
+- Node projects get their `package.json` (and `package-lock.json`) version bumped, Rust their `Cargo.toml` and `Cargo.lock`. The other stacks keep their version in the tag: release-please can't update every lockfile (`uv.lock` records the project's version).
+- A workspace releases as a whole, under one tag, like a `v*` tag pushed by hand.
+- `release-please-config.json` and `.release-please-manifest.json` are written once, starting from the latest `v*` tag (`0.1.0` for a project never released), and are yours afterwards: release-please updates the manifest at each release.
+- The release PR and the tag are created with the workflow's own token, so they start no workflow by themselves (GitHub's rule against recursive runs). The release workflow dispatches the CI on the release PR and the delivery on the tag. A dispatched run isn't attached to the pull request, so its `CI result` job also reports to the commit as a status, which branch protection reads.
+- On a public repository, GitHub also creates the release PR's `pull_request` run but waits for an approval, since the bot counts as a first-time contributor. It isn't required: the dispatched run already reported.
+- GitHub must let Actions open pull requests (Settings → Actions → General). `quoll new --remote` turns it on.
+
+GitLab has no release PR: push the `v*` tags there.
+
 ## Kubernetes
 
 ```bash
@@ -497,6 +516,8 @@ In a **workspace**, every project deploys to the same namespaces and reaches the
 ```bash
 quoll new                                    # interactive
 quoll new shop --front angular --back express
+quoll new shop --front react --back fastapi --python 3.13
+quoll new shop --front nextjs --back go
 quoll new shop --front angular@18 --back express@4 --node 20 --platform gitlab --cd --k8s --remote
 quoll new shop --front angular --back none --service orders=express --service users=express@4
 ```
@@ -510,9 +531,13 @@ From nothing to a repository whose pipeline passes on its first push:
 | Starter | Role | How |
 |---|---|---|
 | `angular` | front | Angular's own CLI (`ng new`) at the chosen major — `angular@18` — plus ESLint (angular-eslint) |
+| `react` | front | Vite's own generator (`create-vite`, TypeScript), React's major with `react@18`; Vitest + Testing Library, Prettier |
+| `nextjs` | front | Next.js' own generator (`create-next-app`: App Router, ESLint, Tailwind), `nextjs@15`; standalone build, Vitest, Prettier |
 | `express` | back | quoll's template: Express (`express@4` for 4) and TypeScript, Vitest + Supertest, ESLint, `/health`, graceful shutdown |
+| `fastapi` | back | quoll's template: FastAPI with uv, pytest (TestClient), ruff, `/health` |
+| `go` | back | quoll's template: the standard library's `net/http` (Go 1.22+ routing), httptest, graceful shutdown, `/health` |
 
-**Versions.** `name@version` picks the framework's major; `--node 20` the runtime: the generators then run in `node:20` (so the dependencies and the lockfile match it), and `.nvmrc` makes the CI and the Dockerfile use it too. A version its maintainers no longer support is flagged at creation: the CI's dependency audit would fail on its known vulnerabilities.
+**Versions.** `name@version` picks the framework's major; `--node 22`, `--python 3.13`, `--go 1.26` the runtime: the generators then run in that runtime's image (so the dependencies and the lockfile match it), and `.nvmrc`, `.python-version` or `go.mod` make the CI and the Dockerfile use it too. Asked interactively, each framework offers its latest version and the older majors its maintainers still fix (Angular 22 to 20, React 19 and 18, Next.js 16 and 15, Express 5 and 4), or any other. A version they no longer fix is flagged at creation: the CI's dependency audit would fail on its known vulnerabilities.
 
 ### Microservices
 
@@ -530,7 +555,7 @@ quoll remove service billing --keep-files    # only takes it out of the workspac
 
 `quoll remove service` does the opposite: the project leaves the members, its jobs, its compose service and `BILLING_URL`, its delivery and setup action are removed. It refuses to delete a directory with uncommitted changes.
 
-**Front-end → API.** With a front-end and a back-end, `quoll new` makes the front-end call the API on its own origin, at `/api/` (no CORS, no URL baked into the build): `ng serve` forwards there (`proxy.conf.json`), and so does nginx in the image, to the URL in `BACK_URL`, which the root `compose.yaml` sets:
+**Front-end → API.** With a front-end and a back-end, `quoll new` makes the front-end call the API on its own origin, at `/api/` (no CORS, no URL baked into the build). In development, the dev server forwards there (`proxy.conf.json` for Angular, Vite's `server.proxy`); deployed, to the URL in `BACK_URL`, which the root `compose.yaml` and the charts set — through nginx for a static site, through Next.js' own `proxy.ts` (read on each request) for Next.js:
 
 ```toml
 # front/quoll.toml

{quoll_cli-0.2.0 → quoll_cli-0.3.0}/README.md

@@ -205,7 +205,7 @@ quoll ci add-step -d back     # in a workspace: the project's directory; asks wh
 # .pre-commit-config.yaml
 repos:
   - repo: https://github.com/theo-mrn/Quoll
-    rev: v0.2.0
+    rev: v0.3.0
     hooks:
       - id: quoll-ci          # quoll ci update; also quoll-docker, quoll-cd
 ```
@@ -362,7 +362,7 @@ Every push to the default branch and every `v*` tag:
 | Runs after CI | through branch protection | always: its `publish` stage starts once every CI job passed |
 | Default registry (no secret) | GHCR, with the workflow's token | the project's container registry, with the job token |
 | Build | Buildx, GitHub Actions cache | Docker-in-Docker, a Buildx container builder; Trivy runs next to the image |
-| Signature | artifact attestations (public repositories, or GitHub Enterprise Cloud for private ones) | cosign keyless with the job's OIDC token (gitlab.com: Sigstore's public instance doesn't trust self-managed issuers) |
+| Signature | artifact attestations (public repositories, or GitHub Enterprise Cloud for private ones: `quoll cd init` turns signing off on a private repository, `--sign` keeps it) | cosign keyless with the job's OIDC token (gitlab.com: Sigstore's public instance doesn't trust self-managed issuers) |
 
 Docker Hub (`registry = "dockerhub"`) needs `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN`. Multi-arch images are a `platforms` entry away.
 
@@ -372,16 +372,35 @@ registry = "ghcr"                 # ghcr (GitHub) | gitlab (GitLab) | dockerhub
 image = "ghcr.io/acme/api"
 branches = ["main"]
 release_tags = true
+release_pr = true                 # GitHub: release-please opens the release PR that tags v* (below)
 platforms = ["linux/amd64"]       # e.g. ["linux/amd64", "linux/arm64"]
 scan = true
 severity = ["CRITICAL", "HIGH"]
 ignore_unfixed = true
 sbom = true                       # SBOM of the image: artifact + release asset
-sign = true                       # Sigstore signature and attestations (set false on a private repo without GitHub Enterprise)
+sign = true                       # Sigstore signature and attestations (`cd init` writes false on a private GitHub repo)
 ```
 
 On GitHub, branch protection (set by `quoll ci init`) makes sure only commits that passed CI reach the default branch, and therefore the registry.
 
+### Releases
+
+On GitHub, nobody has to push the `v*` tags: with `release_pr` (the default of `quoll cd init`), [release-please](https://github.com/googleapis/release-please) reads the [Conventional Commits](https://www.conventionalcommits.org/) on the default branch and keeps a **release PR** open with the next version and its `CHANGELOG.md`. Merging it tags `v<version>` and creates the GitHub release, which publishes the image and, with a chart, deploys to production after the approval.
+
+```
+feat: …  fix: …  feat!: …   →   release PR "chore(main): release 1.3.0"   →   merge   →   v1.3.0   →   CD
+```
+
+- `fix:` bumps the patch, `feat:` the minor, a breaking change (`feat!:`, `BREAKING CHANGE:`) the major. Before `1.0.0`, a breaking change bumps the minor.
+- Node projects get their `package.json` (and `package-lock.json`) version bumped, Rust their `Cargo.toml` and `Cargo.lock`. The other stacks keep their version in the tag: release-please can't update every lockfile (`uv.lock` records the project's version).
+- A workspace releases as a whole, under one tag, like a `v*` tag pushed by hand.
+- `release-please-config.json` and `.release-please-manifest.json` are written once, starting from the latest `v*` tag (`0.1.0` for a project never released), and are yours afterwards: release-please updates the manifest at each release.
+- The release PR and the tag are created with the workflow's own token, so they start no workflow by themselves (GitHub's rule against recursive runs). The release workflow dispatches the CI on the release PR and the delivery on the tag. A dispatched run isn't attached to the pull request, so its `CI result` job also reports to the commit as a status, which branch protection reads.
+- On a public repository, GitHub also creates the release PR's `pull_request` run but waits for an approval, since the bot counts as a first-time contributor. It isn't required: the dispatched run already reported.
+- GitHub must let Actions open pull requests (Settings → Actions → General). `quoll new --remote` turns it on.
+
+GitLab has no release PR: push the `v*` tags there.
+
 ## Kubernetes
 
 ```bash
@@ -448,6 +467,8 @@ In a **workspace**, every project deploys to the same namespaces and reaches the
 ```bash
 quoll new                                    # interactive
 quoll new shop --front angular --back express
+quoll new shop --front react --back fastapi --python 3.13
+quoll new shop --front nextjs --back go
 quoll new shop --front angular@18 --back express@4 --node 20 --platform gitlab --cd --k8s --remote
 quoll new shop --front angular --back none --service orders=express --service users=express@4
 ```
@@ -461,9 +482,13 @@ From nothing to a repository whose pipeline passes on its first push:
 | Starter | Role | How |
 |---|---|---|
 | `angular` | front | Angular's own CLI (`ng new`) at the chosen major — `angular@18` — plus ESLint (angular-eslint) |
+| `react` | front | Vite's own generator (`create-vite`, TypeScript), React's major with `react@18`; Vitest + Testing Library, Prettier |
+| `nextjs` | front | Next.js' own generator (`create-next-app`: App Router, ESLint, Tailwind), `nextjs@15`; standalone build, Vitest, Prettier |
 | `express` | back | quoll's template: Express (`express@4` for 4) and TypeScript, Vitest + Supertest, ESLint, `/health`, graceful shutdown |
+| `fastapi` | back | quoll's template: FastAPI with uv, pytest (TestClient), ruff, `/health` |
+| `go` | back | quoll's template: the standard library's `net/http` (Go 1.22+ routing), httptest, graceful shutdown, `/health` |
 
-**Versions.** `name@version` picks the framework's major; `--node 20` the runtime: the generators then run in `node:20` (so the dependencies and the lockfile match it), and `.nvmrc` makes the CI and the Dockerfile use it too. A version its maintainers no longer support is flagged at creation: the CI's dependency audit would fail on its known vulnerabilities.
+**Versions.** `name@version` picks the framework's major; `--node 22`, `--python 3.13`, `--go 1.26` the runtime: the generators then run in that runtime's image (so the dependencies and the lockfile match it), and `.nvmrc`, `.python-version` or `go.mod` make the CI and the Dockerfile use it too. Asked interactively, each framework offers its latest version and the older majors its maintainers still fix (Angular 22 to 20, React 19 and 18, Next.js 16 and 15, Express 5 and 4), or any other. A version they no longer fix is flagged at creation: the CI's dependency audit would fail on its known vulnerabilities.
 
 ### Microservices
 
@@ -481,7 +506,7 @@ quoll remove service billing --keep-files    # only takes it out of the workspac
 
 `quoll remove service` does the opposite: the project leaves the members, its jobs, its compose service and `BILLING_URL`, its delivery and setup action are removed. It refuses to delete a directory with uncommitted changes.
 
-**Front-end → API.** With a front-end and a back-end, `quoll new` makes the front-end call the API on its own origin, at `/api/` (no CORS, no URL baked into the build): `ng serve` forwards there (`proxy.conf.json`), and so does nginx in the image, to the URL in `BACK_URL`, which the root `compose.yaml` sets:
+**Front-end → API.** With a front-end and a back-end, `quoll new` makes the front-end call the API on its own origin, at `/api/` (no CORS, no URL baked into the build). In development, the dev server forwards there (`proxy.conf.json` for Angular, Vite's `server.proxy`); deployed, to the URL in `BACK_URL`, which the root `compose.yaml` and the charts set — through nginx for a static site, through Next.js' own `proxy.ts` (read on each request) for Next.js:
 
 ```toml
 # front/quoll.toml

{quoll_cli-0.2.0 → quoll_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quoll-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Production-grade CI, Dockerfiles, Helm charts and delivery for any repository, kept in sync with one quoll.toml"
 readme = "README.md"
 license = { text = "MIT" }
@@ -78,6 +78,8 @@ testpaths = ["tests"]
 [tool.ruff]
 line-length = 120
 target-version = "py39"
+# Starters' templates are the generated projects' code, checked there (with their own settings).
+extend-exclude = ["quoll/languages/*/frameworks/*/template", "quoll/languages/*/templates"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "B"]

{quoll_cli-0.2.0 → quoll_cli-0.3.0}/quoll/cd/config.py

@@ -27,6 +27,9 @@ class CDConfig(Section, PlatformField):
     branches: List[str] = Field(default_factory=lambda: ["main"])
     # Git tags v1.2.3 publish :1.2.3 and :1.2.
     release_tags: bool = True
+    # GitHub: release-please keeps a release pull request open from the Conventional Commits on the default branch
+    # (next version, CHANGELOG.md); merging it tags v<version>, which publishes the image and deploys to production.
+    release_pr: bool = False
     platforms: List[str] = Field(default_factory=lambda: ["linux/amd64"])
     # Trivy scans the image before it is pushed; findings of these severities block the push.
     scan: bool = True
@@ -60,6 +63,10 @@ class CDConfig(Section, PlatformField):
             raise ValueError(f"unknown severity '{unknown[0]}' (expected some of: {', '.join(SEVERITIES)})")
         if self.scan and not self.severity:
             raise ValueError("severity must list at least one level when scan is true")
+        if self.release_pr and self.platform != "github":
+            raise ValueError("release_pr is GitHub only (release-please): push the v* tags yourself")
+        if self.release_pr and not self.release_tags:
+            raise ValueError("release_pr needs release_tags: the release it tags is what publishes")
         if not self.branches and not self.release_tags:
             raise ValueError("nothing would publish the image: set branches or release_tags")
         if not self.platforms:

{quoll_cli-0.2.0 → quoll_cli-0.3.0}/quoll/ci/custom.py

@@ -16,8 +16,10 @@ def extend(cfg: CIConfig, job: str, items: List[Item]) -> List[Item]:
     after = [_step(s) for s in cfg.steps if s.job == job and s.when == "after"]
     if not before and not after:
         return items
-    installed = cfg.language.ci.install(cfg)
-    last = max((i for i, item in enumerate(items) if item in installed), default=-1)
+    # By name: a job may run its own variant of the install step (C/C++ configures the test build with
+    # coverage and sanitizers, the release build optimised), still the step that installs the dependencies.
+    installed = {item.name for item in cfg.language.ci.install(cfg)} - {""}
+    last = max((i for i, item in enumerate(items) if item.name in installed), default=-1)
     return [*items[: last + 1], *before, *items[last + 1 :], *after]
 
 

{quoll_cli-0.2.0 → quoll_cli-0.3.0}/quoll/commands/_common.py

@@ -38,22 +38,30 @@ def check_platform(name: Optional[str]) -> None:
         raise typer.Exit(1)
 
 
-def ensure_token(platform: str, host: Optional[str] = None) -> bool:
-    """A token for `platform` in settings: from the environment, the platform's CLI (gh, glab: the session the user
-    keeps fresh), the one stored in ~/.config/quoll, or asked."""
+def find_token(platform: str, host: Optional[str] = None) -> bool:
+    """A token for `platform` in settings, without asking: from the environment, the platform's CLI (gh, glab: the
+    session the user keeps fresh) or the one stored in ~/.config/quoll."""
     attr = f"{platform}_token"
     if getattr(settings, attr):
         return True
     token = _cli_token(platform, host) or load_stored_token(platform)
+    if token:
+        setattr(settings, attr, token)
+    return bool(token)
+
+
+def ensure_token(platform: str, host: Optional[str] = None) -> bool:
+    """A token for `platform` in settings: found (see `find_token`), or asked."""
+    if find_token(platform, host):
+        return True
+    label = platforms.get(platform).label
+    scope = "repo" if platform == "github" else "api"
+    token = ask(questionary.password(f"{label} token ({scope} scope)"))
     if not token:
-        label = platforms.get(platform).label
-        scope = "repo" if platform == "github" else "api"
-        token = ask(questionary.password(f"{label} token ({scope} scope)"))
-        if not token:
-            return False
-        save_token(token, platform)
-        console.print("[dim]Token saved to ~/.config/quoll/config.toml[/dim]")
-    setattr(settings, attr, token)
+        return False
+    save_token(token, platform)
+    console.print("[dim]Token saved to ~/.config/quoll/config.toml[/dim]")
+    setattr(settings, f"{platform}_token", token)
     return True
 
 

{quoll_cli-0.2.0 → quoll_cli-0.3.0}/quoll/commands/add.py

@@ -37,7 +37,9 @@ def service(
     spec: str = typer.Argument(..., help="NAME=STARTER[@VERSION], e.g. orders=express or orders=express@4."),
     project_dir: Path = DirOption,
     within: str = typer.Option(SERVICES_DIRECTORY, "--in", help="Directory holding the services."),
-    node: Optional[str] = typer.Option(None, "--node", help="Node.js version, e.g. 20."),
+    node: Optional[str] = typer.Option(None, "--node", help="Node.js version, e.g. 22."),
+    python: Optional[str] = typer.Option(None, "--python", help="Python version, e.g. 3.13."),
+    go: Optional[str] = typer.Option(None, "--go", help="Go version, e.g. 1.26."),
 ) -> None:
     """Create a service in services/<name>, and add it to the workspace's CI, compose.yaml and delivery."""
     root = find_root(resolve_dir(project_dir))
@@ -67,7 +69,8 @@ def service(
     platform = configured_platform(root) or platforms.detect(root, platforms.remote(root))
     before = snapshot(root, platform) if workspace else Snapshot(set(), None)
     with Progress(SpinnerColumn(), TextColumn("{task.description}"), console=console) as progress:
-        notes = create_part(root, root.name, Part(directory, starter, version, name), {"node": node or ""}, progress)
+        runtimes = {"node": node or "", "python": python or "", "go": go or ""}
+        notes = create_part(root, root.name, Part(directory, starter, version, name), runtimes, progress)
         quiet("Docker", docker_init(root / directory), progress)
 
         task = progress.add_task("Adding it to the workspace...")
@@ -85,7 +88,7 @@ def service(
             reference = next(load_cd_config(root / m) for m in members if "cd" in quoll_toml.read(root / m))
             quiet("CD", lambda: cd_command._configure(
                 root / directory, root, member_name(directory), yes=True, force=False, platform=platform,
-                registry=reference.registry, image=None,
+                registry=reference.registry, image=None, release_pr=reference.release_pr, sign=reference.sign,
             ), progress)
 
         # And its chart, deployed with the others: same namespaces.

{quoll_cli-0.2.0 → quoll_cli-0.3.0}/quoll/commands/cd.py

@@ -16,6 +16,7 @@ from quoll.commands._common import (
     check_files,
     check_platform,
     confirm_overwrite,
+    find_token,
     platform_option,
     resolve_dir,
     update_files,
@@ -39,6 +40,15 @@ def init(
         None, help="ghcr (GitHub) or gitlab (GitLab) — the default —, or dockerhub."
     ),
     image: Optional[str] = typer.Option(None, help="Image name, e.g. ghcr.io/acme/api."),
+    release_pr: Optional[bool] = typer.Option(
+        None, "--release-pr/--no-release-pr",
+        help="GitHub: a release PR from the Conventional Commits (release-please) tags the releases (default: yes).",
+    ),
+    sign: Optional[bool] = typer.Option(
+        None, "--sign/--no-sign",
+        help="Sign the image and its SBOM with Sigstore (default: yes, but no for a private GitHub repository: "
+        "artifact attestations need GitHub Enterprise Cloud there).",
+    ),
 ) -> None:
     """Write [cd] in quoll.toml and generate the delivery pipeline.
 
@@ -53,7 +63,7 @@ def init(
         raise typer.Exit(1)
     if workspace is None:
         cfg = _configure(project_dir, root, "", yes=yes, force=force, platform=platform, registry=registry,
-                         image=image)
+                         image=image, release_pr=release_pr, sign=sign)
         if cfg is None:
             raise typer.Exit(0)
         deliveries: List[Delivery] = [Delivery("", ".", cfg)]
@@ -70,11 +80,16 @@ def init(
             raise typer.Exit(1)
         for member in members:
             _configure(root / member, root, member_name(member), yes=yes, force=force, platform=platform,
-                       registry=registry, image=image)
+                       registry=registry, image=image, release_pr=release_pr, sign=sign)
+            # A workspace releases as a whole, from one repository: asked once.
+            if release_pr is None:
+                release_pr = _read(root / member).get("cd", {}).get("release_pr", False)
+            if sign is None and "cd" in _read(root / member):
+                sign = _read(root / member)["cd"].get("sign", True)
         deliveries = _deliveries(root)
 
     cfg = deliveries[0].cfg
-    files = _plan(root, deliveries)
+    files = _writable(_plan(root, deliveries))
     if not confirm_overwrite(files, yes=yes, force=force):
         raise typer.Exit(1)
     for delivery in deliveries:
@@ -94,6 +109,16 @@ def init(
         console.print(f"Set the {names} {target.label} {target.secrets_label}.")
     if cfg.platform == "gitlab":
         _check_gitlab_include(root)
+    if any(d.cfg.release_pr for d in deliveries):
+        console.print(RELEASE_NOTE)
+
+
+RELEASE_NOTE = (
+    "\nReleases: commit with Conventional Commits ([bold]feat:[/bold], [bold]fix:[/bold], [bold]feat!:[/bold]); "
+    "release-please keeps a release PR open, and merging it tags the version, which publishes and deploys.\n"
+    "GitHub must let Actions open pull requests: Settings → Actions → General → "
+    "[bold]Allow GitHub Actions to create and approve pull requests[/bold] (`quoll new --remote` turns it on)."
+)
 
 
 def _configure(
@@ -106,6 +131,8 @@ def _configure(
     platform: Optional[str],
     registry: Optional[str],
     image: Optional[str],
+    release_pr: Optional[bool] = None,
+    sign: Optional[bool] = None,
 ) -> Optional[CDConfig]:
     """The [cd] of one project, asked or defaulted; saved in its quoll.toml. None when kept as it was."""
     console.print(f"\n[bold]quoll cd[/bold] — {member or project_dir.name}\n")
@@ -134,12 +161,27 @@ def _configure(
     if image is None:
         image = default_image if yes else ask(questionary.text("Image", default=default_image))
 
-    note = " (private GitHub repositories need GitHub Enterprise Cloud)" if name == "github" else ""
-    sign = True if yes else ask(questionary.confirm(f"Sign the image and its SBOM with Sigstore{note}?", default=True))
+    if sign is None:
+        private = _private_repo(name, remote)
+        if private:
+            console.print("[dim]Private GitHub repository: artifact attestations need GitHub Enterprise Cloud there, "
+                          "so signing defaults to off (--sign turns it on).[/dim]")
+        note = " (private GitHub repositories need GitHub Enterprise Cloud)" if name == "github" else ""
+        sign = not private if yes else ask(
+            questionary.confirm(f"Sign the image and its SBOM with Sigstore{note}?", default=not private)
+        )
+    if name != "github":
+        release_pr = False
+    elif release_pr is None:
+        release_pr = True if yes else ask(questionary.confirm(
+            "Open a release PR from the Conventional Commits (release-please)? Merging it tags the version.",
+            default=True,
+        ))
 
     try:
         cfg = CDConfig(
-            platform=name, registry=registry, image=image.lower(), branches=[default_branch(root)], sign=sign
+            platform=name, registry=registry, image=image.lower(), branches=[default_branch(root)], sign=sign,
+            release_pr=release_pr,
         )
     except ValueError as e:
         console.print(f"[red]Error:[/red] {e}")
@@ -150,6 +192,15 @@ def _configure(
     return cfg
 
 
+def _private_repo(name: str, remote: Optional[platforms.Remote]) -> bool:
+    """True when the remote is a private repository on github.com, where a signed delivery would fail: artifact
+    attestations need GitHub Enterprise Cloud on private repositories. Looked up only with a token already at hand
+    (never asked); unknown counts as public."""
+    if name != "github" or remote is None or remote.host != "github.com" or not find_token("github"):
+        return False
+    return platforms.get("github").api().is_private(remote.path) is True
+
+
 @app.command()
 def update(
     project_dir: Path = DirOption,
@@ -158,14 +209,14 @@ def update(
 ) -> None:
     """Regenerate the delivery workflow from quoll.toml (the workspace's, from any of its directories)."""
     root = find_root(resolve_dir(project_dir))
-    update_files(root, _plan(root, _deliveries(root)), yes=yes, force=force, what="CD is")
+    update_files(root, _writable(_plan(root, _deliveries(root))), yes=yes, force=force, what="CD is")
 
 
 @app.command()
 def check(project_dir: Path = DirOption) -> None:
     """Fail if the delivery pipeline differs from what quoll.toml describes."""
     root = find_root(resolve_dir(project_dir))
-    check_files(_plan(root, _deliveries(root)), "cd")
+    check_files([f for f in _plan(root, _deliveries(root)) if not f.create_only], "cd")
 
 
 def _plan(root: Path, deliveries: List[Delivery]) -> List[PlannedFile]:
@@ -173,6 +224,11 @@ def _plan(root: Path, deliveries: List[Delivery]) -> List[PlannedFile]:
     return platforms.get(deliveries[0].cfg.platform).cd_files(root, target)
 
 
+def _writable(files: List[PlannedFile]) -> List[PlannedFile]:
+    """Without release-please's configuration and manifest once written: they are the project's then."""
+    return [f for f in files if not (f.create_only and f.existing is not None)]
+
+
 def _deliveries(root: Path) -> List[Delivery]:
     try:
         return load_deliveries(root)
@@ -204,6 +260,8 @@ def _print_config(cfg: CDConfig) -> None:
     table.add_row("Platforms", ", ".join(cfg.platforms))
     table.add_row("SBOM", "artifact + release asset" if cfg.sbom else "off")
     table.add_row("Signature", "Sigstore" if cfg.sign else "off")
+    if cfg.platform == "github":
+        table.add_row("Releases", "release PR (release-please)" if cfg.release_pr else "v* tags pushed by hand")
     console.print(table)
 
 

{quoll_cli-0.2.0 → quoll_cli-0.3.0}/quoll/commands/new.py

@@ -29,6 +29,12 @@ from quoll.workspace import member_name
 # Where each part goes when the repository holds several.
 DIRECTORIES = {"front": "front", "back": "back"}
 SERVICES_DIRECTORY = "services"
+# Runtime versions offered when none is given: (label, versions), the default first.
+RUNTIME_CHOICES = {
+    "node": ("Node.js", ["26", "24", "22"]),
+    "python": ("Python", ["3.14", "3.13", "3.12"]),
+    "go": ("Go", ["1.27", "1.26"]),
+}
 
 @dataclass
 class Part:
@@ -64,7 +70,9 @@ def new(
     services: List[str] = typer.Option(
         [], "--service", help="A service in services/<name>: NAME=STARTER[@VERSION], e.g. orders=express (repeatable)."
     ),
-    node: Optional[str] = typer.Option(None, "--node", help="Node.js version of the Node-based parts, e.g. 20."),
+    node: Optional[str] = typer.Option(None, "--node", help="Node.js version of the Node-based parts, e.g. 22."),
+    python: Optional[str] = typer.Option(None, "--python", help="Python version of the Python parts, e.g. 3.13."),
+    go: Optional[str] = typer.Option(None, "--go", help="Go version of the Go parts, e.g. 1.26."),
     platform: Optional[str] = platform_option(),
     delivery: Optional[bool] = typer.Option(None, "--cd/--no-cd", help="Also publish the images (quoll cd)."),
     kubernetes: Optional[bool] = typer.Option(
@@ -101,11 +109,14 @@ def new(
         Part(DIRECTORIES[role] if several else ".", starter, version, f"{name}-{role}" if several else name)
         for role, starter, version in picked
     ] + [Part(f"{SERVICES_DIRECTORY}/{n}" if several else ".", s, v, n) for n, s, v in picked_services]
-    if node is None and not yes and any(p.starter.runtime == "node" for p in parts):
-        node = ask(questionary.select(
-            "Node.js version", choices=["24", "22", "20"], default=parts[0].starter.runtime_default or "24"
-        ))
-    runtimes = {"node": node or ""}
+    runtimes = {"node": node, "python": python, "go": go}
+    for runtime, version in runtimes.items():
+        used = [p.starter for p in parts if p.starter.runtime == runtime]
+        if version is None and not yes and used:
+            label, choices = RUNTIME_CHOICES[runtime]
+            runtimes[runtime] = ask(questionary.select(f"{label} version", choices=choices,
+                                                       default=used[0].runtime_default or choices[0]))
+    runtimes = {runtime: version or "" for runtime, version in runtimes.items()}
     if platform is None:
         platform = "github" if yes else ask(questionary.select(
             "Hosting platform",
@@ -168,8 +179,12 @@ def new(
             # Before the delivery: it deploys the charts.
             steps.append(("Kubernetes", lambda: k8s_command.init(project_dir=root, yes=True, force=False)))
         if delivery:
+            # The repository just created says its visibility: a private one on GitHub can't hold attestations
+            # (without Enterprise Cloud). Otherwise cd init looks it up from the remote.
+            sign = False if repo and private and platform == "github" else None
             steps.append(("CD", lambda: cd_command.init(
-                project_dir=root, yes=True, force=False, platform=platform, registry=None, image=None
+                project_dir=root, yes=True, force=False, platform=platform, registry=None, image=None, release_pr=None,
+                sign=sign,
             )))
         for label, run in steps:
             quiet(label, run, progress)
@@ -186,6 +201,8 @@ def new(
                 try:
                     api = target.api()
                     warnings = api.protect_branch(repo.path, "main", required_checks=target.required_checks)
+                    if delivery:
+                        warnings += api.allow_release_prs(repo.path)
                     if target.schedules_via_api:
                         api.ensure_schedule(repo.path, "main", "0 6 * * 1")
                 except PlatformError as e:
@@ -207,11 +224,12 @@ def create_part(root: Path, name: str, part: Part, runtimes: Dict[str, str], pro
     where = root / part.directory
     where.mkdir(parents=True, exist_ok=True)
     runtime = runtimes.get(part.starter.runtime, "")
-    details = f" (Node.js {runtime})" if runtime else ""
+    details = f" ({RUNTIME_CHOICES[part.starter.runtime][0]} {runtime})" if runtime else ""
     shown = f"{name}/" if part.directory == "." else f"{name}/{part.directory}/"
     task = progress.add_task(f"Creating {part.label}{details} in {shown}...")
     try:
         notes = part.starter.create(where, StarterOptions(part.package, part.version, runtime)) or []
+        notes += [n for n in [unmaintained(part.starter, part.version)] if n]
     except StarterError as e:
         progress.stop()
         console.print(f"\n[red]Error:[/red] {e}")
@@ -225,19 +243,20 @@ def docker_init(directory: Path) -> Callable[[], None]:
 
 
 def proxy_api(root: Path, front: Part, back: Part) -> Callable[[], None]:
-    """The front-end calls the back-end at /api/, on its own origin (no CORS): its dev server forwards there, and
-    so does nginx in its image, to BACK_URL (set by the workspace's compose.yaml)."""
+    """The front-end calls the back-end at /api/, on its own origin (no CORS): in development, through its dev
+    server; deployed, to BACK_URL (set by the workspace's compose.yaml and charts) — through nginx for a static
+    site, the app's own server otherwise."""
 
     def run() -> None:
-        docker = docker_command._load(root / front.directory)
-        if not docker.static:  # a server-rendered front-end calls the API itself
-            return
+        variable = f"{member_name(back.directory).upper().replace('-', '_')}_URL"
         if front.starter.proxy:
             port = docker_command._load(root / back.directory).port
-            front.starter.proxy(root / front.directory, "/api", f"http://localhost:{port}")
-        docker.proxy = {"/api/": f"{member_name(back.directory).upper().replace('-', '_')}_URL"}
-        save_docker_config(root / front.directory, docker)
-        docker_command.update(project_dir=root / front.directory, yes=True, force=False)
+            front.starter.proxy(root / front.directory, "/api", f"http://localhost:{port}", variable)
+        docker = docker_command._load(root / front.directory)
+        if docker.static:
+            docker.proxy = {"/api/": variable}
+            save_docker_config(root / front.directory, docker)
+            docker_command.update(project_dir=root / front.directory, yes=True, force=False)
 
     return run
 
@@ -288,11 +307,31 @@ def _pick(role: str, choice: Optional[str], yes: bool) -> Optional[Tuple[str, St
         console.print(f"[red]Error:[/red] unknown {role}-end '{starter_name}' (expected one of: {', '.join(by_name)}).")
         raise typer.Exit(1)
     starter = by_name[starter_name]
-    if asked:
-        version = ask(questionary.text(f"{starter.label} version (Enter: the latest)", default=""))
+    if asked and starter.versions:
+        version = ask(questionary.select(f"{starter.label} version", choices=[
+            questionary.Choice(f"Latest ({starter.versions[0]})", ""),
+            *(questionary.Choice(v, v) for v in starter.versions[1:]),
+            questionary.Choice("Other…", OTHER),
+        ]))
+        if version == OTHER:
+            version = ask(questionary.text(f"{starter.label} version, e.g. {starter.versions[-1]}"))
     return role, starter, version.strip()
 
 
+OTHER = "other"
+
+
+def unmaintained(starter: Starter, version: str) -> str:
+    """A note when `version` is older than the majors `starter`'s maintainers still fix."""
+    major = version.split(".")[0]
+    if not starter.versions or not major.isdigit() or int(major) >= int(starter.versions[-1]):
+        return ""
+    return (
+        f"{starter.label} {major} no longer gets security fixes: the CI's dependency audit will fail on its known "
+        f"vulnerabilities. Maintained: {', '.join(starter.versions)}."
+    )
+
+
 def _valid_name(value: str):
     if re.fullmatch(r"[a-z][a-z0-9-]*", value or ""):
         return True
@@ -329,8 +368,8 @@ def _summary(root: Path, name: str, parts: List[Part], repo) -> None:
     console.print("\n[dim]Next steps:[/dim]")
     for part in parts:
         where = name if part.directory == "." else f"{name}/{part.directory}"
-        run = "npm start" if part.starter.role == "front" else "npm run dev"
-        console.print(f"  cd {where} && {run}")
+        if part.starter.dev:
+            console.print(f"  cd {where} && {part.starter.dev}")
     if len(parts) > 1:
         console.print(f"  cd {name} && docker compose up --build   # everything, with the databases")
     else: