release-scope 0.3.1__tar.gz → 0.4.0__tar.gz

{release_scope-0.3.1 → release_scope-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: release-scope
-Version: 0.3.1
+Version: 0.4.0
 Summary: Collect what sits between production and the default branch across GitLab services: tags, MRs, Jira keys, failed jobs
 Keywords: release,gitlab,jira,deployments,merge-requests,ci,cli,python
 Author: Artur Shiriev
@@ -65,7 +65,7 @@ issue's Web links whenever a commit or MR mentions it; a link counts only if it
 
 ```sh
 export RELEASE_SCOPE_GITLAB__ENDPOINT=https://gitlab.example.com
-export RELEASE_SCOPE_GITLAB__TOKEN=glpat-...          # read_api scope
+export RELEASE_SCOPE_GITLAB__TOKEN=glpat-...          # read_api scope; api for publish
 export RELEASE_SCOPE_ENVIRONMENTS='["prod", "preview"]'
 export RELEASE_SCOPE_PRODUCTION_ENVIRONMENT=prod
 
@@ -152,6 +152,39 @@ Chain the two commands with `;`, not `&&`: `collect` exits `1` when a service fa
 should show it. Alert on the exit code of `collect`, not on whether to render. `render` fails only when it cannot
 read the report or write the page.
 
+## Wiki
+
+`publish` replaces the content of an existing page in a project wiki with a rendered page:
+
+```sh
+uvx release-scope publish report.md --project team/docs --page releases/backend
+```
+
+`--page` is the page slug, as in its URL after `/-/wikis/`. The page must already exist; `publish` never creates
+one, so create it once in GitLab. It keeps the page title and format, and skips the write when the content is
+unchanged, so a scheduled run does not add a page version every time. Publishing needs a token with the `api` scope
+whose user has at least the Developer role in the wiki's project; a denied token exits `3`, a missing page or any
+other failed request exits `4`. GitLab rejects pages larger than its wiki page size limit, 5 MB by default; the error
+then names the size of the page.
+
+A scheduled GitLab CI job keeps the page current. It publishes even when a service failed, then fails the job:
+
+```yaml
+release-page:
+  image: python:3.13-slim
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+  script:
+    - pip install 'release-scope>=0.4,<0.5'
+    - release-scope collect --group team/backend --output report.json || status=$?
+    - release-scope render report.json --output report.md
+    - release-scope publish report.md --project team/docs --page releases/backend
+    - exit "${status:-0}"
+```
+
+Set `RELEASE_SCOPE_GITLAB__ENDPOINT` and a masked `RELEASE_SCOPE_GITLAB__TOKEN` as CI/CD variables of the project
+that runs the job, along with the other settings.
+
 ## Cache
 
 `--cache` names a JSON file that is read if present and rewritten atomically after the run. It holds only facts
@@ -167,7 +200,8 @@ requests and never changes the report.
 skill that runs `release-scope` through `uvx` and answers release questions from the report. Ask your coding agent
 what in the current repository has not reached production, what a group will ship with the next tag, or whether a
 Jira issue is released and which services it touches. For the current repository the skill takes `--project` from
-the git remote. It keeps the report and cache outside the repository and never writes to GitLab or Jira.
+the git remote. It keeps the report and cache outside the repository, and publishes to a wiki page only when you ask
+for it and name the page.
 
 Install it with [skills](https://github.com/vercel-labs/skills):
 
@@ -176,4 +210,4 @@ npx skills add modern-python/release-scope
 ```
 
 The agent reads the same environment variables as the CLI, so set them first as described under Configuration.
-The skill runs `release-scope>=0.3,<0.4`, the range whose flags and report schema it describes.
+The skill runs `release-scope>=0.4,<0.5`, the range whose flags and report schema it describes.

{release_scope-0.3.1 → release_scope-0.4.0}/README.md

@@ -32,7 +32,7 @@ issue's Web links whenever a commit or MR mentions it; a link counts only if it
 
 ```sh
 export RELEASE_SCOPE_GITLAB__ENDPOINT=https://gitlab.example.com
-export RELEASE_SCOPE_GITLAB__TOKEN=glpat-...          # read_api scope
+export RELEASE_SCOPE_GITLAB__TOKEN=glpat-...          # read_api scope; api for publish
 export RELEASE_SCOPE_ENVIRONMENTS='["prod", "preview"]'
 export RELEASE_SCOPE_PRODUCTION_ENVIRONMENT=prod
 
@@ -119,6 +119,39 @@ Chain the two commands with `;`, not `&&`: `collect` exits `1` when a service fa
 should show it. Alert on the exit code of `collect`, not on whether to render. `render` fails only when it cannot
 read the report or write the page.
 
+## Wiki
+
+`publish` replaces the content of an existing page in a project wiki with a rendered page:
+
+```sh
+uvx release-scope publish report.md --project team/docs --page releases/backend
+```
+
+`--page` is the page slug, as in its URL after `/-/wikis/`. The page must already exist; `publish` never creates
+one, so create it once in GitLab. It keeps the page title and format, and skips the write when the content is
+unchanged, so a scheduled run does not add a page version every time. Publishing needs a token with the `api` scope
+whose user has at least the Developer role in the wiki's project; a denied token exits `3`, a missing page or any
+other failed request exits `4`. GitLab rejects pages larger than its wiki page size limit, 5 MB by default; the error
+then names the size of the page.
+
+A scheduled GitLab CI job keeps the page current. It publishes even when a service failed, then fails the job:
+
+```yaml
+release-page:
+  image: python:3.13-slim
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+  script:
+    - pip install 'release-scope>=0.4,<0.5'
+    - release-scope collect --group team/backend --output report.json || status=$?
+    - release-scope render report.json --output report.md
+    - release-scope publish report.md --project team/docs --page releases/backend
+    - exit "${status:-0}"
+```
+
+Set `RELEASE_SCOPE_GITLAB__ENDPOINT` and a masked `RELEASE_SCOPE_GITLAB__TOKEN` as CI/CD variables of the project
+that runs the job, along with the other settings.
+
 ## Cache
 
 `--cache` names a JSON file that is read if present and rewritten atomically after the run. It holds only facts
@@ -134,7 +167,8 @@ requests and never changes the report.
 skill that runs `release-scope` through `uvx` and answers release questions from the report. Ask your coding agent
 what in the current repository has not reached production, what a group will ship with the next tag, or whether a
 Jira issue is released and which services it touches. For the current repository the skill takes `--project` from
-the git remote. It keeps the report and cache outside the repository and never writes to GitLab or Jira.
+the git remote. It keeps the report and cache outside the repository, and publishes to a wiki page only when you ask
+for it and name the page.
 
 Install it with [skills](https://github.com/vercel-labs/skills):
 
@@ -143,4 +177,4 @@ npx skills add modern-python/release-scope
 ```
 
 The agent reads the same environment variables as the CLI, so set them first as described under Configuration.
-The skill runs `release-scope>=0.3,<0.4`, the range whose flags and report schema it describes.
+The skill runs `release-scope>=0.4,<0.5`, the range whose flags and report schema it describes.

{release_scope-0.3.1 → release_scope-0.4.0}/pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
     "Typing :: Typed",
     "Topic :: Software Development :: Build Tools",
 ]
-version = "0.3.1"
+version = "0.4.0"
 dependencies = [
     "typer>=0.13",
     "pydantic>=2; python_version < '3.12'",

{release_scope-0.3.1 → release_scope-0.4.0}/pyproject.toml.orig

@@ -17,7 +17,7 @@ classifiers = [
     "Typing :: Typed",
     "Topic :: Software Development :: Build Tools",
 ]
-version = "0.3.1"
+version = "0.4.0"
 dependencies = [
     "typer>=0.13",
     # The first release whose pydantic-core ships a wheel for each interpreter.

{release_scope-0.3.1 → release_scope-0.4.0}/release_scope/__main__.py

@@ -1,3 +1,4 @@
+import functools
 import importlib.metadata
 import json
 import pathlib
@@ -11,9 +12,9 @@ from release_scope._cache import Cache
 from release_scope._errors import ConfigError, ReleaseScopeError
 from release_scope._files import write_text_atomic
 from release_scope._jira_keys import JIRA_KEY_PATTERN
+from release_scope._publish import PublishUseCase
 from release_scope._render import render_markdown
 from release_scope._report import SCHEMA_VERSION, Report
-from release_scope._settings import Settings, load_settings
 from release_scope._use_case import CollectUseCase
 
 
@@ -47,16 +48,26 @@ def _main_callback(
     pass
 
 
-@modern_di_typer.inject
-def _resolve_use_case(
-    use_case: typing.Annotated[CollectUseCase, modern_di_typer.FromDI(CollectUseCase)],
-) -> CollectUseCase:
-    return use_case
+_P = typing.ParamSpec("_P")
+
+
+def _exit_on_error(func: typing.Callable[_P, None]) -> typing.Callable[_P, None]:
+    @functools.wraps(func)
+    def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> None:
+        try:
+            func(*args, **kwargs)
+        except ReleaseScopeError as err:
+            typer.echo(f"Error: {err}", err=True)
+            raise typer.Exit(code=err.exit_code) from err
+
+    return wrapper
 
 
 @MAIN_APP.command("collect", help="Collect pending changes per service into a JSON report.")
+@_exit_on_error
+@modern_di_typer.inject
 def _collect_command(  # noqa: PLR0913, PLR0917
-    ctx: typer.Context,
+    use_case: typing.Annotated[CollectUseCase, modern_di_typer.FromDI(CollectUseCase)],
     output: typing.Annotated[pathlib.Path, typer.Option("--output", "-o", help="Where to write the report JSON.")],
     group: typing.Annotated[
         list[str] | None, typer.Option("--group", "-g", help="GitLab group path; repeatable.")
@@ -76,24 +87,14 @@ def _collect_command(  # noqa: PLR0913, PLR0917
         typer.Option("--jira", "-j", help="Jira issue key; collect only the services it links to. Repeatable."),
     ] = None,
 ) -> None:
-    try:
-        _check_selection(groups=group or [], projects=project or [], keys=jira or [])
-        settings = load_settings({})
-        modern_di_typer.fetch_di_container(ctx).set_context(Settings, settings)
-        cache, cache_warning = Cache.load(cache_path) if cache_path else (Cache(), None)
-        if cache_warning:
-            typer.echo(f"Warning: {cache_warning}", err=True)
-        use_case = _resolve_use_case(ctx=ctx)
-        if jira:
-            report = use_case.for_issues(keys=list(dict.fromkeys(jira)), cache=cache)
-        else:
-            report = use_case(
-                groups=group or [], projects=project or [], include_subgroups=include_subgroups, cache=cache
-            )
-    except ReleaseScopeError as err:
-        typer.echo(f"Error: {err}", err=True)
-        raise typer.Exit(code=err.exit_code) from err
-
+    _check_selection(groups=group or [], projects=project or [], keys=jira or [])
+    cache, cache_warning = Cache.load(cache_path) if cache_path else (Cache(), None)
+    if cache_warning:
+        typer.echo(f"Warning: {cache_warning}", err=True)
+    if jira:
+        report = use_case.for_issues(keys=list(dict.fromkeys(jira)), cache=cache)
+    else:
+        report = use_case(groups=group or [], projects=project or [], include_subgroups=include_subgroups, cache=cache)
     write_text_atomic(output, report.model_dump_json(indent=2))
     if cache_path:
         cache.save(cache_path)
@@ -160,6 +161,24 @@ def _render_command(
     typer.echo(f"{len(report.services)} services -> {output}", err=True)
 
 
+@MAIN_APP.command("publish", help="Replace the content of an existing GitLab wiki page with a rendered page.")
+@_exit_on_error
+@modern_di_typer.inject
+def _publish_command(
+    use_case: typing.Annotated[PublishUseCase, modern_di_typer.FromDI(PublishUseCase)],
+    page_path: typing.Annotated[pathlib.Path, typer.Argument(help="Markdown page written by `render`.")],
+    project: typing.Annotated[str, typer.Option("--project", "-p", help="GitLab project path that holds the wiki.")],
+    page: typing.Annotated[str, typer.Option("--page", help="Slug of the wiki page, such as releases/backend.")],
+) -> None:
+    try:
+        content = page_path.read_text(encoding="utf-8")
+    except (OSError, ValueError) as exc:
+        typer.echo(f"Error: Cannot read page {page_path}: {type(exc).__name__}.", err=True)
+        raise typer.Exit(code=ConfigError.exit_code) from exc
+    published: typing.Final = use_case(project=project, slug=page, content=content)
+    typer.echo(f"{'Updated' if published.updated else 'Unchanged'} {published.url}", err=True)
+
+
 def main() -> None:
     with ioc.container:
         MAIN_APP()

{release_scope-0.3.1 → release_scope-0.4.0}/release_scope/_gitlab.py

@@ -104,6 +104,11 @@ class Bridge(Job):
     downstream_pipeline: DownstreamPipeline | None = None
 
 
+class WikiPage(pydantic.BaseModel):
+    slug: str
+    content: str
+
+
 class _Projects(pydantic.RootModel[list[Project]]):
     pass
 
@@ -137,7 +142,7 @@ class _Bridges(pydantic.RootModel[list[Bridge]]):
 
 
 Resource: typing.TypeAlias = typing.Literal[
-    "group", "project", "deployments", "pipelines", "repository", "merge_requests"
+    "group", "project", "deployments", "pipelines", "repository", "merge_requests", "wiki"
 ]
 
 
@@ -165,6 +170,12 @@ class GitLabApi:
         except httpware.ClientError as exc:
             raise _translate(exc, url=url, resource=resource) from exc
 
+    def _put(self, url: str, body: dict[str, typing.Any], *, resource: Resource) -> None:
+        try:
+            self.http.put(url, json=body)
+        except httpware.ClientError as exc:
+            raise _translate(exc, url=url, resource=resource) from exc
+
     def _pages(
         self,
         url: str,
@@ -288,3 +299,9 @@ class GitLabApi:
             resource="pipelines",
         )
         return bridges
+
+    def get_wiki_page(self, project: str, slug: str) -> WikiPage:
+        return self._get(f"{_API}/projects/{_quote(project)}/wikis/{_quote(slug)}", {}, WikiPage, resource="wiki")
+
+    def update_wiki_page(self, project: str, slug: str, *, content: str) -> None:
+        self._put(f"{_API}/projects/{_quote(project)}/wikis/{_quote(slug)}", {"content": content}, resource="wiki")

release_scope-0.4.0/release_scope/_publish.py

@@ -0,0 +1,51 @@
+import dataclasses
+import http
+import typing
+
+from release_scope._errors import AuthError, GitLabError, ReleaseScopeError
+from release_scope._gitlab import GitLabApi
+from release_scope._settings import Settings
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class Published:
+    url: str
+    updated: bool
+
+
+def _wiki_error(error: GitLabError, *, project: str, slug: str, size: int | None) -> ReleaseScopeError:
+    if error.status == http.HTTPStatus.FORBIDDEN:
+        return AuthError(
+            f"GitLab denied access to the wiki of project '{project}' (403). Check that the token has the 'api' "
+            "scope and that its user has at least the Developer role there."
+        )
+    if error.status == http.HTTPStatus.NOT_FOUND:
+        return GitLabError(
+            f"Wiki page '{slug}' does not exist in project '{project}', or the token cannot see it. "
+            "Create the page in GitLab first.",
+            resource="wiki",
+            status=error.status,
+        )
+    if size is None:
+        return error
+    return GitLabError(f"{error} The page is {size} bytes.", resource="wiki", status=error.status, reason=error.reason)
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class PublishUseCase:
+    api: GitLabApi
+    settings: Settings
+
+    def __call__(self, *, project: str, slug: str, content: str) -> Published:
+        url: typing.Final = f"{self.settings.gitlab.endpoint.rstrip('/')}/{project}/-/wikis/{slug}"
+        try:
+            page = self.api.get_wiki_page(project, slug)
+        except GitLabError as exc:
+            raise _wiki_error(exc, project=project, slug=slug, size=None) from exc
+        if page.content == content:
+            return Published(url=url, updated=False)
+        try:
+            self.api.update_wiki_page(project, slug, content=content)
+        except GitLabError as exc:
+            raise _wiki_error(exc, project=project, slug=slug, size=len(content.encode())) from exc
+        return Published(url=url, updated=True)

{release_scope-0.3.1 → release_scope-0.4.0}/release_scope/_settings.py

@@ -49,9 +49,9 @@ class Settings(pydantic_settings.BaseSettings):
         return self
 
 
-def load_settings(overrides: dict[str, typing.Any]) -> Settings:
+def load_settings() -> Settings:
     try:
-        settings: typing.Final = Settings(**overrides)
+        settings: typing.Final = Settings()
     except pydantic.ValidationError as exc:
         msg = f"Invalid configuration: {exc}"
         raise ConfigError(msg) from exc

{release_scope-0.3.1 → release_scope-0.4.0}/release_scope/ioc.py

@@ -6,7 +6,8 @@ from modern_di import Scope, providers
 
 from release_scope._gitlab import GitLabApi
 from release_scope._jira import JiraApi
-from release_scope._settings import Settings
+from release_scope._publish import PublishUseCase
+from release_scope._settings import Settings, load_settings
 from release_scope._use_case import CollectUseCase
 
 
@@ -47,7 +48,7 @@ def _close_client(client: httpware.Client | None) -> None:
 
 
 class SettingsGroup(modern_di.Group):
-    settings = providers.ContextProvider(scope=Scope.APP, context_type=Settings)
+    settings = providers.Factory(scope=Scope.APP, creator=load_settings, cache=True)
 
 
 class ClientsGroup(modern_di.Group):
@@ -73,6 +74,7 @@ class UseCasesGroup(modern_di.Group):
     collect_use_case = providers.Factory(
         scope=Scope.APP, creator=CollectUseCase, kwargs={"jira": ClientsGroup.jira_api}
     )
+    publish_use_case = providers.Factory(scope=Scope.APP, creator=PublishUseCase)
 
 
 ALL_GROUPS: typing.Final[list[type[modern_di.Group]]] = [SettingsGroup, ClientsGroup, UseCasesGroup]