soliplex-template 0.12.1__tar.gz → 0.14.dev0__tar.gz

{soliplex_template-0.12.1/src/soliplex_template.egg-info → soliplex_template-0.14.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soliplex-template
-Version: 0.12.1
+Version: 0.14.dev0
 Summary: Docker Compose template for a Soliplex stack, plus the soliplex-template Agent Skill and its build tooling.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -19,6 +19,8 @@ There are two ways to use it: run this repository directly as a reference stack
 to try Soliplex now, or generate your own tailored stack from it (for a real
 deployment). Both are below.
 
+📖 **Full documentation:** <https://soliplex.github.io/soliplex-template/>
+
 ## Try it
 
 You need Docker (with the Compose plugin), [`uv`](https://docs.astral.sh/uv/),

{soliplex_template-0.12.1 → soliplex_template-0.14.dev0}/README.md

@@ -10,6 +10,8 @@ There are two ways to use it: run this repository directly as a reference stack
 to try Soliplex now, or generate your own tailored stack from it (for a real
 deployment). Both are below.
 
+📖 **Full documentation:** <https://soliplex.github.io/soliplex-template/>
+
 ## Try it
 
 You need Docker (with the Compose plugin), [`uv`](https://docs.astral.sh/uv/),

{soliplex_template-0.12.1 → soliplex_template-0.14.dev0}/pyproject.toml

@@ -4,12 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "soliplex-template"
-version = "0.12.1"
+version = "0.14dev0"
 description = "Docker Compose template for a Soliplex stack, plus the soliplex-template Agent Skill and its build tooling."
 readme = "README.md"
 requires-python = ">=3.12"
-# The 'soliplex_template' package (src/) is stdlib-only; the bundled skill's
-# add_room.py imports 'soliplex_template.rooms' from it.
 dependencies = []
 
 # Tooling for the soliplex-template skill. The scripts also carry PEP 723
@@ -34,32 +32,32 @@ dev = [
     "pytest",
     "pytest-cov",
     "ruff",
-    # Direct runtime dep of generate_soliplex_project.py (read_properties);
-    # pinned to match that script's PEP 723 header.
-    "skills-ref==0.1.1",
-    "soliplex-skills >= 0.4",
+    "skills-ref==0.1.1",  # 'generate_soliplex_project.py'
+    "soliplex-skills >= 0.5",
+    "soliplex-plumber >= 0.4", # skill's 'add_room.py'/'soliplex_config.py'
     "zensical",
 ]
 
-# The repo is configuration + Dockerfiles + skill source, but it also ships the
-# importable 'soliplex_template' package (src/), so it builds as a wheel. PEP 420
-# namespace package (no __init__.py); clients import the module directly, e.g.
-# 'from soliplex_template.rooms import ...'.
+# The repo is configuration + Dockerfiles + skill source, but it also ships
+# the importable 'soliplex_template' package (src/), so it builds as a wheel.
 [tool.setuptools.packages.find]
 where = ["src"]
 namespaces = true
 
-# Hermetic unit tests for the repo's Python scripts. The suite holds 100% branch
-# coverage; --cov=scripts measures the repo-level build tooling, --cov=skill/scripts
-# the bundled generator/version helpers, and --cov=tests/unit keeps the test
-# files themselves dead-code-free.
+# Required 100% unit test statement/branch coverage:
+#
+# --cov=scripts measures the repo-level build tooling;
+# --cov=skill/scripts the bundled generator/version helpers;
+# --cov=tests/unit keeps the test files themselves dead-code-free.
+#
+# Functional tests live under tests/functional/ and are opt-in: they generate
+# a real project and shell out to git/openssl/docker).  Run them explicitly
+# with: # 'uv run --group dev pytest tests/functional --no-cov'
+#
+# (--no-cov because the generator runs in a child process, so it isn't
+# measured and would otherwise trip --cov-fail-under).
 [tool.pytest.ini_options]
 python_files = "test_*.py"
-# Functional tests live under tests/functional/ and are opt-in (they generate a
-# real project and shell out to git/openssl/docker). Run them explicitly with
-#   uv run --group dev pytest tests/functional --no-cov
-# (--no-cov because the generator runs in a child process, so it isn't measured
-# and would otherwise trip --cov-fail-under). They are not collected by default.
 testpaths = ["tests/unit"]
 addopts = "--cov=scripts --cov=skills/soliplex-template/scripts --cov=src/soliplex_template --cov=tests/unit --cov-branch --cov-fail-under=100"
 markers = [
@@ -69,9 +67,9 @@ markers = [
 [tool.coverage.report]
 show_missing = true
 
-# Lint/format config mirrors soliplex/soliplex (same rule selection, line length,
-# single-line imports, and pytest-style tweaks). ruff-format is enforced by the
-# pre-commit hook; `ruff check` uses these rules on demand.
+# Mirror soliplex/soliplex linting (same rule selection, line length,
+# single-line imports, and pytest-style tweaks). ruff-format is enforced by
+# the pre-commit hook; `ruff check` uses these rules on demand.
 [tool.ruff]
 line-length = 79
 exclude = [

{soliplex_template-0.12.1 → soliplex_template-0.14.dev0}/src/soliplex_template/gitea.py

@@ -63,58 +63,78 @@ READY_DELAY = 2
 class GiteaError(Exception):
     """A user-facing error (printed without a traceback)."""
 
-    @classmethod
-    def not_ready(cls, url):
-        return cls(
+
+class GiteaNotReady(GiteaError):
+    def __init__(self, url):
+        self.url = url
+        super().__init__(
             f"Gitea did not become ready at {url} "
             "(is the stack up? 'docker compose up -d gitea')"
         )
 
-    @classmethod
-    def reserved_user(cls, name):
-        return cls(
+
+class ReservedUser(GiteaError):
+    def __init__(self, name):
+        self.name = name
+        super().__init__(
             f"web-UI admin user may not be {name!r}: it is the rotating "
             "service account"
         )
 
-    @classmethod
-    def password_mismatch(cls):
-        return cls("passwords did not match")
 
-    @classmethod
-    def token_request_failed(cls, code, body):
-        return cls(f"token request failed: HTTP {code}: {body}")
+class PasswordMismatch(GiteaError):
+    def __init__(self):
+        super().__init__("passwords did not match")
+
+
+class TokenRequestFailed(GiteaError):
+    def __init__(self, code, body):
+        self.code = code
+        self.body = body
+        super().__init__(f"token request failed: HTTP {code}: {body}")
+
 
-    @classmethod
-    def no_token(cls, body):
-        return cls(f"could not parse token from response: {body}")
+class NoToken(GiteaError):
+    def __init__(self, body):
+        self.body = body
+        super().__init__(f"could not parse token from response: {body}")
 
-    @classmethod
-    def repo_failed(cls, code):
-        return cls(f"repo creation failed (HTTP {code})")
 
-    @classmethod
-    def not_a_git_repo(cls, path):
-        return cls(
+class RepoCreationFailed(GiteaError):
+    def __init__(self, code):
+        self.code = code
+        super().__init__(f"repo creation failed (HTTP {code})")
+
+
+class NotAGitRepo(GiteaError):
+    def __init__(self, path):
+        self.path = path
+        super().__init__(
             f"{path} is not a git repository "
             "(was the stack scaffolded with --no-git?)"
         )
 
-    @classmethod
-    def no_ssh_keys(cls):
-        return cls(
+
+class No_SSH_hKeys(GiteaError):
+    def __init__(self):
+        super().__init__(
             "no SSH public key found to register with Gitea: load one into "
             "your agent (ssh-add), pass --ssh-key PATH, or create one "
             "(ssh-keygen)"
         )
 
-    @classmethod
-    def key_upload_failed(cls, code, body):
-        return cls(f"SSH key upload failed: HTTP {code}: {body}")
 
-    @classmethod
-    def push_failed(cls, stderr):
-        return cls(f"git push to Gitea failed: {stderr}")
+class KeyUploadFailed(GiteaError):
+    def __init__(self, code, body):
+        self.code = code
+        self.body = body
+        super().__init__(f"SSH key upload failed: HTTP {code}: {body}")
+
+
+class PushFailed(GiteaError):
+    def __init__(self, stderr):
+        self.stderr = stderr
+        super().__init__(f"git push to Gitea failed: {stderr}")
 
 
 def generate_admin_password(length: int = 32) -> str:
@@ -169,10 +189,10 @@ def parse_token(body: str) -> str:
     try:
         data = json.loads(body)
     except json.JSONDecodeError as exc:
-        raise GiteaError.no_token(body) from exc
+        raise NoToken(body) from exc
     token = data.get("sha1")
     if not token:
-        raise GiteaError.no_token(body)
+        raise NoToken(body)
     return token
 
 
@@ -231,7 +251,7 @@ def mint_token(password: str, *, token_name: str) -> str:
             body = resp.read().decode()
     except urllib.error.HTTPError as exc:
         body = exc.read().decode()
-        raise GiteaError.token_request_failed(exc.code, body) from exc
+        raise TokenRequestFailed(exc.code, body) from exc
     return parse_token(body)
 
 
@@ -253,7 +273,7 @@ def create_repo(
     except urllib.error.HTTPError as exc:
         code = exc.code
     if code not in (201, 409):
-        raise GiteaError.repo_failed(code)
+        raise RepoCreationFailed(code)
     return code
 
 
@@ -314,7 +334,7 @@ def upload_ssh_key(public_key: str, *, password: str, title: str) -> None:
         if exc.code == 422:
             return
         body = exc.read().decode()
-        raise GiteaError.key_upload_failed(exc.code, body) from exc
+        raise KeyUploadFailed(exc.code, body) from exc
 
 
 def _git(*args, project_dir, env=None):
@@ -375,7 +395,7 @@ def push_initial(project_dir, branch: str) -> None:
         "push", "-u", "origin", branch, project_dir=project_dir, env=env
     )
     if result.returncode != 0:
-        raise GiteaError.push_failed(result.stderr.strip())
+        raise PushFailed(result.stderr.strip())
 
 
 def push_stack_to_gitea(
@@ -392,10 +412,10 @@ def push_stack_to_gitea(
     """
     project = pathlib.Path(project_dir)
     if not (project / ".git").is_dir():
-        raise GiteaError.not_a_git_repo(project)
+        raise NotAGitRepo(project)
     keys = discover_ssh_keys(ssh_key=ssh_key)
     if not keys:
-        raise GiteaError.no_ssh_keys()
+        raise No_SSH_hKeys()
     print(f"Registering {len(keys)} SSH key(s) with '{ADMIN_USER}' ...")
     for key in keys:
         upload_ssh_key(key, password=password, title=_key_title(key))
@@ -482,12 +502,12 @@ def provision_gitea(
     accounts) are the result.
     """
     if webui_user == ADMIN_USER:
-        raise GiteaError.reserved_user(webui_user)
+        raise ReservedUser(webui_user)
     project = pathlib.Path(project_dir).resolve()
     print("=== Gitea provisioning ===")
     print(f"Waiting for Gitea at {GITEA_HTTP} ...")
     if not wait_for_gitea():
-        raise GiteaError.not_ready(GITEA_HTTP)
+        raise GiteaNotReady(GITEA_HTTP)
 
     password = generate_admin_password()
     print(f"Ensuring service account '{ADMIN_USER}' ...")

{soliplex_template-0.12.1 → soliplex_template-0.14.dev0}/src/soliplex_template/secrets.py

@@ -49,9 +49,11 @@ GEN_SUFFIX = ".gen"
 class SecretsError(Exception):
     """A user-facing error (printed without a traceback)."""
 
-    @classmethod
-    def compose_not_found(cls, path):
-        return cls(
+
+class ComposeNotFound(SecretsError):
+    def __init__(self, path):
+        self.path = path
+        super().__init__(
             f"cannot find compose file at: {path} "
             "(run with --project-dir pointing at the stack directory)"
         )
@@ -161,7 +163,7 @@ def generate_secrets(project_dir) -> None:
     project = pathlib.Path(project_dir).resolve()
     compose = project / COMPOSE_FILE
     if not compose.is_file():
-        raise SecretsError.compose_not_found(compose)
+        raise ComposeNotFound(compose)
 
     secrets_dir = project / SECRETS_DIR
     secrets_dir.mkdir(parents=True, exist_ok=True)

{soliplex_template-0.12.1 → soliplex_template-0.14.dev0/src/soliplex_template.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soliplex-template
-Version: 0.12.1
+Version: 0.14.dev0
 Summary: Docker Compose template for a Soliplex stack, plus the soliplex-template Agent Skill and its build tooling.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -19,6 +19,8 @@ There are two ways to use it: run this repository directly as a reference stack
 to try Soliplex now, or generate your own tailored stack from it (for a real
 deployment). Both are below.
 
+📖 **Full documentation:** <https://soliplex.github.io/soliplex-template/>
+
 ## Try it
 
 You need Docker (with the Compose plugin), [`uv`](https://docs.astral.sh/uv/),

{soliplex_template-0.12.1 → soliplex_template-0.14.dev0}/src/soliplex_template.egg-info/SOURCES.txt

@@ -2,7 +2,6 @@ LICENSE
 README.md
 pyproject.toml
 src/soliplex_template/gitea.py
-src/soliplex_template/rooms.py
 src/soliplex_template/secrets.py
 src/soliplex_template.egg-info/PKG-INFO
 src/soliplex_template.egg-info/SOURCES.txt

soliplex_template-0.12.1/src/soliplex_template/rooms.py

@@ -1,218 +0,0 @@
-"""Generic, template-agnostic logic for adding a room to a Soliplex stack.
-
-This is the reusable core behind the ``soliplex-template`` skill's bundled
-``add_room.py`` -- a PEP 723 shim that owns the ``.mako`` templates and the
-CLI and delegates the stack-level work here. It ships in the published
-``soliplex-template`` distribution so the skill (and any other consumer) can
-``from soliplex_template.rooms import ...``.
-
-It works on a *rendered* room config (text the caller produced however it likes
--- a template, an existing room's config, or built by hand) plus the stack's
-``installation.yaml``, which it edits line-based (comment-preserving):
-
-- ``resolve_project`` / ``resolve_package_name`` -- locate + introspect it.
-- ``validate_room_id`` -- the room-id / path-segment rule.
-- ``add_room_path`` -- ensure ``room_paths`` loads the room (``added`` /
-  ``COVERED`` by a ``./rooms`` parent entry / ``unchanged`` when already
-  listed), preserving comments and layout.
-- ``install_room`` -- write the room dir + config (+ optional prompt file) and
-  apply the ``room_paths`` edit; honors dry-run and force.
-
-Pure filesystem work -- no Docker, no running backend, stdlib only.
-"""
-
-from __future__ import annotations
-
-import dataclasses
-import pathlib
-import re
-
-# A room id usable as a path segment and a YAML id: no '/', no '..', no
-# leading dot (mirrors rag_db.py's DB_NAME_RE).
-ROOM_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
-
-# Placeholder when the stack's own package can't be inferred (no 'src/<pkg>/');
-# the '<pkg>.tools.greeting' demo tool in the skill templates references it.
-DEFAULT_PACKAGE_NAME = "your_package"
-# Written into the room dir when a prompt file is supplied; the config then
-# points its system_prompt at this file (the 'search' demo room uses the form).
-PROMPT_FILE_NAME = "prompt.txt"
-
-# Stack markers: the files that mark a directory as a generated stack.
-COMPOSE_FILE = "docker-compose.yml"
-ENVIRONMENT_DIR = pathlib.PurePosixPath("backend", "environment")
-INSTALLATION_FILE = ENVIRONMENT_DIR / "installation.yaml"
-ROOMS_DIR = ENVIRONMENT_DIR / "rooms"
-
-# room_paths splice: the anchor line and the entry-already-present probe.
-_ROOM_PATHS_RE = re.compile(r"^room_paths:\s*$")
-
-ADDED = "added"
-UNCHANGED = "unchanged"
-# room_paths may point at the rooms parent directory to auto-discover every
-# room beneath it; when it does, a new room needs no room_paths entry.
-ROOMS_PARENT_ENTRY = "./rooms"
-COVERED = f'covered by "{ROOMS_PARENT_ENTRY}"'
-
-
-class AddRoomError(Exception):
-    """A user-facing error (printed without a traceback).
-
-    Message construction lives in these classmethod factories so call sites
-    read ``raise AddRoomError.<reason>(...)`` with no inline message string.
-    """
-
-    @classmethod
-    def compose_not_found(cls, path):
-        return cls(
-            f"no {COMPOSE_FILE} at {path} "
-            "(run with --project-dir pointing at the stack directory)"
-        )
-
-    @classmethod
-    def not_a_stack(cls, path):
-        return cls(
-            f"{path} is not a generated Soliplex stack: missing "
-            f"'{INSTALLATION_FILE}'"
-        )
-
-    @classmethod
-    def bad_room_id(cls, room_id):
-        return cls(
-            f"room id {room_id!r} must match {ROOM_ID_RE.pattern} "
-            "(letters, digits, '.', '_', '-'; no leading dot)"
-        )
-
-    @classmethod
-    def unknown_template(cls, name, available):
-        avail = ", ".join(sorted(available)) or "(none found)"
-        return cls(f"unknown template {name!r}; available: {avail}")
-
-    @classmethod
-    def prompt_file_missing(cls, path):
-        return cls(f"prompt file {path} does not exist")
-
-    @classmethod
-    def room_exists(cls, path):
-        return cls(f"{path} already exists (use force to overwrite it)")
-
-    @classmethod
-    def no_room_paths(cls, path):
-        return cls(
-            f"no 'room_paths:' block in {path} to extend "
-            "(unexpected installation.yaml shape)"
-        )
-
-
-def validate_room_id(room_id: str) -> None:
-    if not ROOM_ID_RE.match(room_id):
-        raise AddRoomError.bad_room_id(room_id)
-
-
-def resolve_project(project_dir: str) -> pathlib.Path:
-    """Return the resolved stack root, or raise if it is not a stack."""
-    project = pathlib.Path(project_dir).resolve()
-    if not (project / COMPOSE_FILE).is_file():
-        raise AddRoomError.compose_not_found(project / COMPOSE_FILE)
-    if not (project / INSTALLATION_FILE).is_file():
-        raise AddRoomError.not_a_stack(project)
-    return project
-
-
-def resolve_package_name(project: pathlib.Path, override: str | None) -> str:
-    """The stack's own package (for ``<pkg>.tools.greeting``), or placeholder.
-
-    Prefer an explicit ``override``; otherwise infer the single package under
-    ``src/`` (the generator scaffolds ``src/<package_name>/tools.py``); failing
-    that, return ``DEFAULT_PACKAGE_NAME`` for the operator to edit.
-    """
-    if override is not None:
-        return override
-    src = project / "src"
-    if src.is_dir():
-        packages = [
-            child.name
-            for child in sorted(src.iterdir())
-            if child.is_dir() and (child / "tools.py").is_file()
-        ]
-        if len(packages) == 1:
-            return packages[0]
-    return DEFAULT_PACKAGE_NAME
-
-
-def add_room_path(text: str, room_id: str) -> tuple[str, str]:
-    """Ensure ``room_paths`` loads ``rooms/<room_id>``; return (text, action).
-
-    Action is ``"unchanged"`` when the explicit entry is already listed,
-    ``COVERED`` when a ``./rooms`` entry already auto-discovers every room
-    beneath it (so no entry is needed), or ``"added"`` when the
-    ``- "./rooms/<id>"`` entry is spliced in. The edit is line-based, so
-    comments and unrelated layout are preserved. Raises ``AddRoomError`` when
-    the file has no top-level ``room_paths:`` block.
-    """
-    entry = f"{ROOMS_PARENT_ENTRY}/{room_id}"
-    probe = re.compile(r'-\s*["\']?' + re.escape(entry) + r'["\']?\s*$')
-    parent_probe = re.compile(
-        r'-\s*["\']?' + re.escape(ROOMS_PARENT_ENTRY) + r'/?["\']?\s*$'
-    )
-    lines = text.splitlines(keepends=True)
-    if any(probe.search(line) for line in lines):
-        return text, UNCHANGED
-    if any(parent_probe.search(line) for line in lines):
-        return text, COVERED
-    idx = next(
-        (i for i, line in enumerate(lines) if _ROOM_PATHS_RE.match(line)),
-        None,
-    )
-    if idx is None:
-        raise AddRoomError.no_room_paths(INSTALLATION_FILE)
-    lines.insert(idx + 1, f'  - "{entry}"\n')
-    return "".join(lines), ADDED
-
-
-@dataclasses.dataclass(frozen=True)
-class RoomInstall:
-    """The outcome of ``install_room``: where the config went + the room_paths
-    action (``added`` / ``COVERED`` / ``unchanged``)."""
-
-    config_path: pathlib.Path
-    path_action: str
-
-
-def install_room(
-    project: pathlib.Path,
-    room_id: str,
-    *,
-    config_text: str,
-    prompt_text: str | None = None,
-    force: bool = False,
-    dry_run: bool = False,
-) -> RoomInstall:
-    """Install a rendered room into ``project``; return a ``RoomInstall``.
-
-    Writes ``rooms/<room_id>/room_config.yaml`` (and ``prompt.txt`` when
-    ``prompt_text`` is given), and ensures ``room_paths`` loads it. With
-    ``dry_run`` it computes the outcome but writes nothing. Raises
-    ``AddRoomError`` when the room directory already exists and ``force`` is
-    false. ``config_text`` is template-agnostic -- any caller-produced room
-    config.
-    """
-    room_dir = project / ROOMS_DIR / room_id
-    config_path = room_dir / "room_config.yaml"
-    if room_dir.exists() and not force:
-        raise AddRoomError.room_exists(room_dir)
-
-    installation = project / INSTALLATION_FILE
-    new_installation, path_action = add_room_path(
-        installation.read_text(), room_id
-    )
-
-    if not dry_run:
-        room_dir.mkdir(parents=True, exist_ok=True)
-        config_path.write_text(config_text)
-        if prompt_text is not None:
-            (room_dir / PROMPT_FILE_NAME).write_text(prompt_text)
-        if path_action == ADDED:
-            installation.write_text(new_installation)
-
-    return RoomInstall(config_path=config_path, path_action=path_action)