quoll-cli 0.2.0__py3-none-any.whl

quoll/commands/new.py

@@ -0,0 +1,337 @@
+"""`quoll new`: a project from nothing — a front-end, a back-end, services, or several of them in one repository
+(front/, back/, services/<name>/) — with its CI, Dockerfiles and, optionally, its delivery and its GitHub/GitLab
+repository."""
+from __future__ import annotations
+
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Tuple
+
+import questionary
+import typer
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from quoll import languages, platforms
+from quoll.commands import cd as cd_command
+from quoll.commands import ci as ci_command
+from quoll.commands import docker as docker_command
+from quoll.commands import k8s as k8s_command
+from quoll.commands._common import ask, check_platform, ensure_token, platform_option
+from quoll.console import console
+from quoll.docker.config import save_config as save_docker_config
+from quoll.languages.base import Starter, StarterOptions
+from quoll.platforms import PlatformError
+from quoll.starters import StarterError
+from quoll.workspace import member_name
+
+# Where each part goes when the repository holds several.
+DIRECTORIES = {"front": "front", "back": "back"}
+SERVICES_DIRECTORY = "services"
+
+@dataclass
+class Part:
+    """A project of the repository to create: where, from which starter."""
+
+    directory: str
+    starter: Starter
+    version: str
+    package: str
+
+    @property
+    def label(self) -> str:
+        return self.starter.label + (f" {self.version}" if self.version else "")
+
+
+_GITIGNORE = """# Each project ignores its own files (front/.gitignore, back/.gitignore...).
+.env
+.DS_Store
+.idea/
+.vscode/
+"""
+
+
+def new(
+    name: Optional[str] = typer.Argument(None, help="Project name: lowercase letters, digits and dashes."),
+    parent: Path = typer.Option(Path("."), "--dir", "-d", help="Where to create the project's directory."),
+    front: Optional[str] = typer.Option(
+        None, help="Front-end starter, e.g. angular, or angular@18 for a version ('none' for no front-end)."
+    ),
+    back: Optional[str] = typer.Option(
+        None, help="Back-end starter, e.g. express, or express@4 ('none' for no back-end)."
+    ),
+    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."),
+    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(
+        None, "--k8s/--no-k8s", help="A Helm chart per project, deployed by the delivery (quoll k8s)."
+    ),
+    remote: Optional[bool] = typer.Option(
+        None, "--remote/--local", help="Create the GitHub/GitLab repository, push, protect the default branch."
+    ),
+    private: bool = typer.Option(True, "--private/--public", help="Visibility of the created repository."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Don't ask: use the options and defaults."),
+) -> None:
+    """Create a project from nothing: front/, back/, services/<name>/ (or one of them), CI, Dockerfiles, delivery,
+    repository."""
+    check_platform(platform)
+    console.print("\n[bold]quoll new[/bold]\n")
+
+    if name is None:
+        name = "app" if yes else ask(questionary.text("Project name", validate=_valid_name))
+    if _valid_name(name) is not True:
+        console.print(f"[red]Error:[/red] {_valid_name(name)}")
+        raise typer.Exit(1)
+    root = parent.resolve() / name
+    if root.exists() and any(root.iterdir()):
+        console.print(f"[red]Error:[/red] {root} exists and isn't empty.")
+        raise typer.Exit(1)
+
+    picked = [p for p in (_pick("front", front, yes), _pick("back", back, yes)) if p]
+    picked_services = [parse_service(spec) for spec in services]
+    if not picked and not picked_services:
+        console.print("[red]Error:[/red] nothing to create: choose a front-end, a back-end or services.")
+        raise typer.Exit(1)
+    several = len(picked) + len(picked_services) > 1
+    parts = [
+        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 ""}
+    if platform is None:
+        platform = "github" if yes else ask(questionary.select(
+            "Hosting platform",
+            choices=[questionary.Choice(platforms.get(n).label, n) for n in platforms.NAMES],
+        ))
+    if delivery is None:
+        delivery = not yes and ask(questionary.confirm("Publish the images (build, scan, push)?", default=True))
+    if kubernetes is None:
+        kubernetes = not yes and ask(questionary.confirm(
+            "Deploy to Kubernetes (Helm charts; staging on each push, production on v* tags)?", default=delivery
+        ))
+    if remote is None:
+        label = platforms.get(platform).label
+        remote = not yes and ask(questionary.confirm(f"Create the {label} repository and push?", default=True))
+
+    # One part: the repository is the project. Several: a workspace, one directory each.
+    notes: List[str] = []
+    root.mkdir(parents=True, exist_ok=True)
+    target = platforms.get(platform)
+    repo = None
+
+    with Progress(SpinnerColumn(), TextColumn("{task.description}"), console=console, transient=False) as progress:
+        for part in parts:
+            notes += create_part(root, name, part, runtimes, progress)
+
+        if several:
+            (root / ".gitignore").write_text(_GITIGNORE)
+            (root / "README.md").write_text(_readme(name, parts))
+        _git(root, "init", "-q", "-b", "main")
+
+        if remote:
+            task = progress.add_task(f"Creating the {target.label} repository...")
+            if not ensure_token(platform):
+                progress.stop()
+                console.print(f"[red]Error:[/red] no {target.label} token.")
+                raise typer.Exit(1)
+            try:
+                repo = target.api().create_repo(name, private=private)
+            except PlatformError as e:
+                progress.stop()
+                console.print(f"[red]{target.label} error:[/red] {e}")
+                raise typer.Exit(1)
+            # Before the CI and the delivery: their defaults (image names...) come from the remote.
+            _git(root, "remote", "add", "origin", repo.clone_url)
+            progress.update(task, description=f"[green]✓[/green] {target.label} repository: {repo.web_url}")
+
+        task = progress.add_task("Generating the CI, the Dockerfiles" + (" and the delivery..." if delivery else "..."))
+        # Docker first: the CI then builds and scans the images.
+        steps: List[Tuple[str, Callable[[], None]]] = [("Docker", docker_init(root / p.directory)) for p in parts]
+        by_role = {p.starter.role: p for p in parts if p.directory in DIRECTORIES.values()}
+        if "front" in by_role and "back" in by_role:
+            steps.append(("Docker", proxy_api(root, by_role["front"], by_role["back"])))
+        steps.append(
+            ("CI", lambda: ci_command.init(project_dir=root, yes=True, force=True, platform=platform, local=True))
+        )
+        if several:
+            # Now a workspace: the compose.yaml running every project.
+            steps.append(("Docker", docker_init(root)))
+        if kubernetes:
+            # Before the delivery: it deploys the charts.
+            steps.append(("Kubernetes", lambda: k8s_command.init(project_dir=root, yes=True, force=False)))
+        if delivery:
+            steps.append(("CD", lambda: cd_command.init(
+                project_dir=root, yes=True, force=False, platform=platform, registry=None, image=None
+            )))
+        for label, run in steps:
+            quiet(label, run, progress)
+        done = "CI, Dockerfiles" + (", Helm charts" if kubernetes else "") + (", delivery" if delivery else "")
+        progress.update(task, description=f"[green]✓[/green] {done}")
+
+        _git(root, "add", "-A")
+        committed = _git(root, "commit", "-q", "-m", f"chore: create {name} with quoll", check=False)
+        if remote and repo and committed:
+            task = progress.add_task("Pushing and protecting the default branch...")
+            pushed = _git(root, "push", "-q", "-u", "origin", "main", check=False)
+            warnings = []
+            if pushed:
+                try:
+                    api = target.api()
+                    warnings = api.protect_branch(repo.path, "main", required_checks=target.required_checks)
+                    if target.schedules_via_api:
+                        api.ensure_schedule(repo.path, "main", "0 6 * * 1")
+                except PlatformError as e:
+                    warnings.append(str(e))
+            progress.update(task, description="[green]✓[/green] Pushed, main protected" if pushed
+                            else "[yellow]![/yellow] Push failed: push the main branch yourself")
+            for warning in warnings:
+                progress.console.print(f"[yellow]![/yellow] {warning}")
+
+    for note in notes:
+        console.print(f"[yellow]![/yellow] {note}")
+    if not committed:
+        console.print("[yellow]![/yellow] Nothing committed (is git's user.name / user.email set?): commit yourself.")
+    _summary(root, name, parts, repo)
+
+
+def create_part(root: Path, name: str, part: Part, runtimes: Dict[str, str], progress: Progress) -> List[str]:
+    """Run `part`'s starter in its directory; the starter's notes."""
+    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 ""
+    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 []
+    except StarterError as e:
+        progress.stop()
+        console.print(f"\n[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+    progress.update(task, description=f"[green]✓[/green] {part.label}{details} in {shown}")
+    return notes
+
+
+def docker_init(directory: Path) -> Callable[[], None]:
+    return lambda: docker_command.init(project_dir=directory, yes=True, force=False, command="")
+
+
+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)."""
+
+    def run() -> None:
+        docker = docker_command._load(root / front.directory)
+        if not docker.static:  # a server-rendered front-end calls the API itself
+            return
+        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)
+
+    return run
+
+
+def quiet(label: str, run: Callable[[], None], progress: Progress) -> None:
+    """Run another quoll command; its own report would drown this one: shown only when something goes wrong."""
+    with console.capture() as captured:
+        try:
+            run()
+            failed = False
+        except typer.Exit as e:
+            failed = bool(e.exit_code)
+    if failed:
+        progress.stop()
+        console.print(captured.get())
+        console.print(f"[red]Error:[/red] quoll {label.lower()} failed.")
+        raise typer.Exit(1)
+
+
+def parse_service(spec: str) -> Tuple[str, Starter, str]:
+    """NAME=STARTER[@VERSION] -> (name, starter, version)."""
+    service, _, choice = spec.partition("=")
+    if _valid_name(service) is not True or not choice:
+        console.print(f"[red]Error:[/red] --service {spec}: expected NAME=STARTER, e.g. orders=express")
+        raise typer.Exit(1)
+    starter_name, _, version = choice.partition("@")
+    by_name = {s.name: s for s in languages.starters()}
+    if starter_name not in by_name:
+        console.print(f"[red]Error:[/red] unknown starter '{starter_name}' (expected one of: {', '.join(by_name)}).")
+        raise typer.Exit(1)
+    return service, by_name[starter_name], version
+
+
+def _pick(role: str, choice: Optional[str], yes: bool) -> Optional[Tuple[str, Starter, str]]:
+    """(role, starter, version) for `role`: from `choice` ("angular", "angular@18"), else asked."""
+    starters = languages.starters(role)
+    by_name = {s.name: s for s in starters}
+    asked = choice is None and not yes
+    if asked:
+        choice = ask(questionary.select(
+            f"{role.capitalize()}-end",
+            choices=[*(questionary.Choice(s.label, s.name) for s in starters), questionary.Choice("None", "none")],
+        ))
+    if choice in (None, "none"):
+        return None
+    starter_name, _, version = choice.partition("@")
+    if starter_name not in by_name:
+        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=""))
+    return role, starter, version.strip()
+
+
+def _valid_name(value: str):
+    if re.fullmatch(r"[a-z][a-z0-9-]*", value or ""):
+        return True
+    return "lowercase letters, digits and dashes, starting with a letter"
+
+
+def _git(root: Path, *args: str, check: bool = True) -> bool:
+    result = subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
+    if result.returncode != 0 and check:
+        console.print(f"[red]Error:[/red] git {args[0]} failed: {result.stderr.strip()}")
+        raise typer.Exit(1)
+    return result.returncode == 0
+
+
+def _readme(name: str, parts: List[Part]) -> str:
+    listed = "\n".join(f"- [`{p.directory}/`]({p.directory}/): {p.label}" for p in parts)
+    return f"""# {name}
+
+{listed}
+
+`docker compose up --build` runs them all, with their databases: each reaches the others at `<NAME>_URL`
+(e.g. `BACK_URL=http://back:3000`). Each project also has its own README, Dockerfile and `compose.yaml`.
+
+The CI, the Docker files and the delivery are generated by [quoll](https://github.com/theo-mrn/Quoll)
+from the `quoll.toml` files: change them, then run `quoll ci update` (or `quoll docker update`, `quoll cd update`).
+Add a service with `quoll add service <name>=express` (it lands in `services/<name>/`).
+"""
+
+
+def _summary(root: Path, name: str, parts: List[Part], repo) -> None:
+    console.print(f"\n[bold green]✓ {name} is ready:[/bold green] {root}")
+    if repo:
+        console.print(f"  {repo.web_url}")
+    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 len(parts) > 1:
+        console.print(f"  cd {name} && docker compose up --build   # everything, with the databases")
+    else:
+        console.print("  docker compose up --build")

quoll/commands/remove.py

@@ -0,0 +1,79 @@
+"""`quoll remove service`: take a project out of a workspace, and out of its CI, compose.yaml and delivery."""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import questionary
+import typer
+
+from quoll import platforms
+from quoll.ci.detect import configured_platform
+from quoll.commands._common import DirOption, ask, resolve_dir
+from quoll.commands._workspace import refresh, remove_empty_parents, snapshot
+from quoll.config import quoll_toml
+from quoll.config.quoll_toml import ConfigError
+from quoll.console import console
+from quoll.workspace import WorkspaceConfig, find_root, load_workspace, member_name
+
+app = typer.Typer(help="Remove a project from a workspace.", no_args_is_help=True)
+
+
+@app.command()
+def service(
+    name: str = typer.Argument(..., help="The project's name or directory, e.g. billing or services/billing."),
+    project_dir: Path = DirOption,
+    keep_files: bool = typer.Option(
+        False, "--keep-files", help="Leave its directory in place: only take it out of the workspace."
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Don't ask before deleting its directory."),
+) -> None:
+    """Delete a project of the workspace, and remove it from the pipeline, compose.yaml and delivery."""
+    root = find_root(resolve_dir(project_dir))
+    try:
+        workspace = load_workspace(root)
+    except ConfigError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+    if workspace is None:
+        console.print("[red]Error:[/red] not a workspace: there is no project to remove.")
+        raise typer.Exit(1)
+    directory = next((m for m in workspace.members if name.strip("/") in (m, member_name(m))), None)
+    if directory is None:
+        console.print(f"[red]Error:[/red] no project named {name} (members: {', '.join(workspace.members)}).")
+        raise typer.Exit(1)
+    if len(workspace.members) == 1:
+        console.print(f"[red]Error:[/red] {directory} is the workspace's only project.")
+        raise typer.Exit(1)
+
+    delete = not keep_files and (root / directory).exists()
+    if delete and _uncommitted(root, directory):
+        console.print(f"[red]Error:[/red] {directory} has uncommitted changes: commit them first (git keeps the "
+                      "project in its history), or use --keep-files.")
+        raise typer.Exit(1)
+    if delete and not yes and not ask(questionary.confirm(f"Delete {directory}/ and everything in it?", default=False)):
+        raise typer.Exit(1)
+
+    platform = configured_platform(root) or platforms.detect(root, platforms.remote(root))
+    before = snapshot(root, platform)
+    members = [m for m in workspace.members if m != directory]
+    quoll_toml.save_section(root, "workspace", WorkspaceConfig(members=members))
+    if delete:
+        shutil.rmtree(root / directory)
+        remove_empty_parents(root, root / directory)
+    console.print(f"[green]✓[/green] {directory} " + ("deleted" if delete else "taken out of the workspace"))
+    refresh(root, platform, before, f"remove {member_name(directory)} from it yourself")
+
+    variable = f"{member_name(directory).upper().replace('-', '_')}_URL"
+    console.print(f"\n[bold green]✓ {member_name(directory)}[/bold green] removed. The others no longer get "
+                  f"[bold]{variable}[/bold]: check that their code doesn't use it.")
+
+
+def _uncommitted(root: Path, directory: str) -> bool:
+    """True when git would lose changes to `directory` (modified or untracked files)."""
+    done = subprocess.run(
+        ["git", "status", "--porcelain", "--", directory], cwd=root, capture_output=True, text=True
+    )
+    return done.returncode == 0 and bool(done.stdout.strip())
+

quoll/config/quoll_toml.py

@@ -0,0 +1,196 @@
+"""quoll.toml: a shared [project] section plus one section per feature ([ci], [docker], [cd]).
+
+Each feature model declares the [project] fields it uses (`shared_fields`; all of them for `ProjectConfig`
+subclasses), so in memory it carries them too; on disk they live once, in [project], so the CI, the image and
+the delivery can't disagree about the stack or the platform.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, ClassVar, Dict, List, Optional, Tuple, Type, TypeVar, Union
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib  # type: ignore[no-redef]
+import tomli_w
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, ValidationError, field_validator, model_validator
+
+from quoll import languages, platforms
+from quoll.services import DATABASE, SERVICES, environment
+
+CONFIG_FILE = "quoll.toml"
+PROJECT_SECTION = "project"
+
+
+class ConfigError(Exception):
+    pass
+
+
+class Section(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    # Fields stored in [project] and shared with the other sections.
+    shared_fields: ClassVar[Tuple[str, ...]] = ()
+    # Lists left out of quoll.toml while empty, so they can be written as [[section.field]] tables ("a.b" for a
+    # nested one).
+    omit_when_empty: ClassVar[Tuple[str, ...]] = ()
+
+
+class PlatformField(BaseModel):
+    # Where the repository is hosted and the pipelines run: github | gitlab.
+    platform: str = "github"
+
+    @field_validator("platform")
+    @classmethod
+    def _known_platform(cls, value: str) -> str:
+        if value not in platforms.NAMES:
+            raise ValueError(f"unknown platform '{value}' (expected one of: {', '.join(platforms.NAMES)})")
+        return value
+
+
+class ProjectConfig(Section, PlatformField):
+    # Where the project lives in the repository ("." alone; e.g. "backend" in a workspace). Not stored: it is
+    # where its quoll.toml is.
+    _directory: str = PrivateAttr(default=".")
+
+    # Name of a registered language plugin (see quoll/languages).
+    stack: str
+    # Name of one of the stack's frameworks, or empty.
+    framework: str = ""
+    package_manager: str
+    # Pin the package manager itself (pnpm, bun). Empty = read package.json "packageManager".
+    package_manager_version: str = ""
+    # Backing services: postgres | mysql | redis | mongodb. Run next to the CI tests and in compose.yaml.
+    services: List[str] = Field(default_factory=list)
+
+    @field_validator("stack")
+    @classmethod
+    def _known_stack(cls, value: str) -> str:
+        if value not in languages.names():
+            raise ValueError(f"unknown stack '{value}' (expected one of: {', '.join(languages.names())})")
+        return value
+
+    @field_validator("services")
+    @classmethod
+    def _known_services(cls, value: List[str]) -> List[str]:
+        unknown = [s for s in value if s not in SERVICES]
+        if unknown:
+            raise ValueError(f"unknown service '{unknown[0]}' (expected one of: {', '.join(SERVICES)})")
+        return value
+
+    @model_validator(mode="after")
+    def _check_project(self) -> "ProjectConfig":
+        lang = self.language
+        if self.framework and self.get_framework() is None:
+            known = [f.name for f in languages.frameworks(lang.name)]
+            raise ValueError(
+                f"unknown framework '{self.framework}' for {lang.name} (expected one of: {', '.join(known)})"
+            )
+        if self.package_manager not in lang.package_managers:
+            raise ValueError(
+                f"package_manager '{self.package_manager}' is not valid for {lang.name} "
+                f"(expected one of: {', '.join(lang.package_managers)})"
+            )
+        return self
+
+    @property
+    def language(self) -> languages.Language:
+        return languages.get(self.stack)
+
+    def get_framework(self) -> Optional[languages.Framework]:
+        return languages.get_framework(self.stack, self.framework) if self.framework else None
+
+    def service_environment(self, host: Union[str, Callable[[str], str]], database: str = DATABASE) -> Dict[str, str]:
+        """Variables pointing the app at its services on `host` (or `host(service)`), using `database`."""
+        framework = self.get_framework()
+        hooks = [self.language.service_env] + ([framework.service_env] if framework else [])
+        return environment(self.services, host, *hooks, database=database)
+
+    @property
+    def directory(self) -> str:
+        return self._directory
+
+    def in_directory(self, directory: str) -> "ProjectConfig":
+        """This config for a project living in `directory` of the repository."""
+        self._directory = directory.strip("/") or "."
+        return self
+
+    def path(self, name: str) -> str:
+        """`name`, relative to the project, as a path from the repository root."""
+        return name if self._directory == "." else f"{self._directory}/{name}"
+
+    @property
+    def target(self) -> str:
+        return f"{self.stack}/{self.framework}" if self.framework else self.stack
+
+
+PROJECT_FIELDS = tuple(ProjectConfig.model_fields)
+ProjectConfig.shared_fields = PROJECT_FIELDS
+
+M = TypeVar("M", bound=Section)
+
+
+def read(project_dir: Path) -> dict:
+    path = project_dir / CONFIG_FILE
+    if not path.exists():
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError(f"{CONFIG_FILE} is not valid TOML: {e}") from e
+
+
+def load_section(project_dir: Path, section: str, model: Type[M]) -> M:
+    data = read(project_dir)
+    if section not in data:
+        if not (project_dir / CONFIG_FILE).exists():
+            raise ConfigError(f"{CONFIG_FILE} not found in {project_dir}. Run `quoll {section} init` first.")
+        raise ConfigError(f"{CONFIG_FILE} has no [{section}] section. Run `quoll {section} init` first.")
+    merged = dict(data[section])
+    project = data.get(PROJECT_SECTION, {})
+    # Older files kept the project fields inside [ci]; [project] wins when both exist.
+    merged.update({k: v for k, v in project.items() if k in model.shared_fields})
+    try:
+        return model.model_validate(merged)
+    except ValidationError as e:
+        details = "\n".join(f"  {_location(model, section, err['loc'])}{err['msg']}" for err in e.errors())
+        raise ConfigError(f"Invalid {CONFIG_FILE}:\n{details}") from e
+
+
+def save_section(project_dir: Path, section: str, config: Section) -> Path:
+    """Write `section` and its shared fields in [project], preserving the rest of quoll.toml."""
+    data = read(project_dir)
+    values = config.model_dump()
+    for name in config.omit_when_empty:
+        *parents, key = name.split(".")
+        table = values
+        for parent in parents:
+            table = table.get(parent) or {}
+        if not table.get(key):
+            table.pop(key, None)
+    shared = {k: values.pop(k) for k in config.shared_fields}
+    if shared:
+        data[PROJECT_SECTION] = {**data.get(PROJECT_SECTION, {}), **shared}
+    data[section] = values
+    # [project] first, then the features in a stable order.
+    project = {PROJECT_SECTION: data.pop(PROJECT_SECTION)} if PROJECT_SECTION in data else {}
+    ordered = {**project, **dict(sorted(data.items()))}
+    path = project_dir / CONFIG_FILE
+    path.write_text(tomli_w.dumps(ordered))
+    return path
+
+
+def remove_section(project_dir: Path, section: str) -> None:
+    """Drop `section` from quoll.toml ([project] stays: other sections may still use it)."""
+    data = read(project_dir)
+    data.pop(section, None)
+    (project_dir / CONFIG_FILE).write_text(tomli_w.dumps(data))
+
+
+def _location(model: Type[Section], section: str, loc: tuple) -> str:
+    if not loc:
+        return ""
+    prefix = PROJECT_SECTION if loc[0] in model.shared_fields else section
+    return f"{prefix}.{'.'.join(str(p) for p in loc)}: "

quoll/config/settings.py

@@ -0,0 +1,22 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="QUOLL_",
+        env_file=".env",
+        extra="ignore",
+        frozen=False,
+    )
+
+    github_token: str = ""
+    github_org: str = ""
+    gitlab_token: str = ""
+    # gitlab.com or a self-managed instance.
+    gitlab_url: str = "https://gitlab.com"
+    # Group (or group/subgroup) where `quoll new --remote` creates GitLab projects; empty = the user's namespace.
+    gitlab_group: str = ""
+    default_branch: str = "main"
+
+
+settings = Settings()

quoll/config/store.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib  # type: ignore[no-redef]
+from pathlib import Path
+
+import tomli_w
+
+_CONFIG_PATH = Path.home() / ".config" / "quoll" / "config.toml"
+# Where tokens were stored before the tool was renamed; read when the new file doesn't exist yet.
+_LEGACY_CONFIG_PATH = Path.home() / ".config" / "forge" / "config.toml"
+
+
+def load_stored_token(platform: str = "github") -> str:
+    path = _CONFIG_PATH if _CONFIG_PATH.exists() else _LEGACY_CONFIG_PATH
+    if not path.exists():
+        return ""
+    try:
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+        return data.get(platform, {}).get("token", "")
+    except Exception:
+        return ""
+
+
+def save_token(token: str, platform: str = "github") -> None:
+    _CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    existing: dict = {}
+    if _CONFIG_PATH.exists():
+        try:
+            with open(_CONFIG_PATH, "rb") as f:
+                existing = tomllib.load(f)
+        except Exception:
+            pass
+    existing.setdefault(platform, {})["token"] = token
+    with open(_CONFIG_PATH, "wb") as f:
+        tomli_w.dump(existing, f)