scripticus-server 0.1.1__tar.gz → 0.3.0__tar.gz

scripticus_server-0.3.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: scripticus-server
+Version: 0.3.0
+Summary: A package manager and registry for scripts — index service
+License-Expression: MIT
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: scripticus-schema>=0.1.2,<0.2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Scripticus server
+
+The index service for [Scripticus](https://github.com/kevinchannon/scripticus),
+a package manager and registry for scripts. The server provides
+manifest-aware search, version and dependency resolution, and the publish
+path for a Scripticus registry. Installing this package provides the
+`scripticus-svr` command.
+
+## Running the server
+
+`scripticus-svr` starts the service, printing its version and address on
+start-up:
+
+```console
+$ scripticus-svr --host 0.0.0.0 --port 8000
+scripticus-svr 0.1.0 — serving on http://0.0.0.0:8000 (interactive API docs at http://0.0.0.0:8000/docs)
+```
+
+Both options are optional; the default is `127.0.0.1:8000`. The API is
+self-describing: interactive docs are served at `/docs` and the OpenAPI
+spec at `/openapi.json`.
+
+### Health check
+
+`GET /health` returns `200` with `{"status": "ok"}` while the service is
+up. It is deliberately unauthenticated — it's a liveness probe for load
+balancers and container orchestrators.
+
+### Version
+
+`GET /version` returns the running server's version, e.g.
+`{"version": "0.1.1"}`.
+
+### Package index (read API)
+
+- `GET /packages/{namespace}/{name}` — a package's version listing, newest
+  first by semver precedence. Yanked versions are included and marked
+  (`"yanked": true`) so pinned lookups can still see them; unknown packages
+  return `404`.
+- `GET /search?q=<substring>&platform=<os>&language=<lang>` — packages whose
+  name contains `q` (all parameters optional), with each result's latest
+  non-yanked version. Yanked versions are invisible to search; `platform`
+  and `language` filter on the artifacts a version actually provides.
+
+The index database defaults to a local SQLite file
+(`scripticus-index.db`); set `SCRIPTICUS_INDEX_DB` to any SQLAlchemy URL
+to point elsewhere. Tables are created automatically on first use.
+
+### Publishing
+
+`POST /packages` publishes a package: a multipart upload of one archive
+(as produced by `scripticus pack`) with your Gitea token in the
+`Authorization` header:
+
+```console
+$ curl -X POST http://localhost:8000/packages \
+    -H "Authorization: token <your-gitea-token>" \
+    -F archive=@my_tool-1.0.0-linux.macos-bash.tar.gz
+```
+
+The server trusts nothing about the upload: it re-validates the manifest
+and package tree, computes the content hash, checks with Gitea (live)
+that your token may publish to the manifest's namespace — your own
+username, or an organisation you belong to — stores the blob in Gitea's
+generic package registry, and only then commits the index record.
+Versions are immutable; the one addition an existing version accepts is
+an artifact in a new archive format carrying the identical content hash.
+Declared package dependencies must be fully namespaced and already
+present in the index, and a publish that would create a dependency cycle
+is rejected. The `library` namespace is reserved. The Gitea instance is
+configured with `SCRIPTICUS_GITEA_URL` (default `http://localhost:3000`).
+
+### Docker
+
+Server releases publish a Docker image to
+[`kevinchannon/scripticus-server`](https://hub.docker.com/r/kevinchannon/scripticus-server)
+(tagged with the release version and `latest`). The repository's
+`docker-compose.yml` is the full registry bundle — the index service plus
+the Gitea instance that provides storage, authentication, and namespace
+ownership — and needs no checkout:
+
+```console
+$ curl -LO https://raw.githubusercontent.com/kevinchannon/scripticus/main/docker-compose.yml
+$ docker compose up -d
+$ curl http://localhost:8000/health
+{"status":"ok"}
+```
+
+First-run Gitea setup: accounts and organisations are managed in Gitea
+(http://localhost:3000), and a Scripticus namespace *is* a Gitea user or
+organisation, claimed first-come-first-served, with publish rights
+following Gitea's own membership and ACLs. So, once the bundle is up:
+
+1. Register your user in the Gitea web UI (the first registered user is
+   the instance admin), and create an organisation for any shared
+   namespace you want.
+2. Generate a token under *Settings → Applications → Manage Access
+   Tokens* with package write and user read scopes.
+3. Publish with that token (see above).
+
+## Licence
+
+MIT

scripticus_server-0.3.0/README.md

@@ -0,0 +1,103 @@
+# Scripticus server
+
+The index service for [Scripticus](https://github.com/kevinchannon/scripticus),
+a package manager and registry for scripts. The server provides
+manifest-aware search, version and dependency resolution, and the publish
+path for a Scripticus registry. Installing this package provides the
+`scripticus-svr` command.
+
+## Running the server
+
+`scripticus-svr` starts the service, printing its version and address on
+start-up:
+
+```console
+$ scripticus-svr --host 0.0.0.0 --port 8000
+scripticus-svr 0.1.0 — serving on http://0.0.0.0:8000 (interactive API docs at http://0.0.0.0:8000/docs)
+```
+
+Both options are optional; the default is `127.0.0.1:8000`. The API is
+self-describing: interactive docs are served at `/docs` and the OpenAPI
+spec at `/openapi.json`.
+
+### Health check
+
+`GET /health` returns `200` with `{"status": "ok"}` while the service is
+up. It is deliberately unauthenticated — it's a liveness probe for load
+balancers and container orchestrators.
+
+### Version
+
+`GET /version` returns the running server's version, e.g.
+`{"version": "0.1.1"}`.
+
+### Package index (read API)
+
+- `GET /packages/{namespace}/{name}` — a package's version listing, newest
+  first by semver precedence. Yanked versions are included and marked
+  (`"yanked": true`) so pinned lookups can still see them; unknown packages
+  return `404`.
+- `GET /search?q=<substring>&platform=<os>&language=<lang>` — packages whose
+  name contains `q` (all parameters optional), with each result's latest
+  non-yanked version. Yanked versions are invisible to search; `platform`
+  and `language` filter on the artifacts a version actually provides.
+
+The index database defaults to a local SQLite file
+(`scripticus-index.db`); set `SCRIPTICUS_INDEX_DB` to any SQLAlchemy URL
+to point elsewhere. Tables are created automatically on first use.
+
+### Publishing
+
+`POST /packages` publishes a package: a multipart upload of one archive
+(as produced by `scripticus pack`) with your Gitea token in the
+`Authorization` header:
+
+```console
+$ curl -X POST http://localhost:8000/packages \
+    -H "Authorization: token <your-gitea-token>" \
+    -F archive=@my_tool-1.0.0-linux.macos-bash.tar.gz
+```
+
+The server trusts nothing about the upload: it re-validates the manifest
+and package tree, computes the content hash, checks with Gitea (live)
+that your token may publish to the manifest's namespace — your own
+username, or an organisation you belong to — stores the blob in Gitea's
+generic package registry, and only then commits the index record.
+Versions are immutable; the one addition an existing version accepts is
+an artifact in a new archive format carrying the identical content hash.
+Declared package dependencies must be fully namespaced and already
+present in the index, and a publish that would create a dependency cycle
+is rejected. The `library` namespace is reserved. The Gitea instance is
+configured with `SCRIPTICUS_GITEA_URL` (default `http://localhost:3000`).
+
+### Docker
+
+Server releases publish a Docker image to
+[`kevinchannon/scripticus-server`](https://hub.docker.com/r/kevinchannon/scripticus-server)
+(tagged with the release version and `latest`). The repository's
+`docker-compose.yml` is the full registry bundle — the index service plus
+the Gitea instance that provides storage, authentication, and namespace
+ownership — and needs no checkout:
+
+```console
+$ curl -LO https://raw.githubusercontent.com/kevinchannon/scripticus/main/docker-compose.yml
+$ docker compose up -d
+$ curl http://localhost:8000/health
+{"status":"ok"}
+```
+
+First-run Gitea setup: accounts and organisations are managed in Gitea
+(http://localhost:3000), and a Scripticus namespace *is* a Gitea user or
+organisation, claimed first-come-first-served, with publish rights
+following Gitea's own membership and ACLs. So, once the bundle is up:
+
+1. Register your user in the Gitea web UI (the first registered user is
+   the instance admin), and create an organisation for any shared
+   namespace you want.
+2. Generate a token under *Settings → Applications → Manage Access
+   Tokens* with package write and user read scopes.
+3. Publish with that token (see above).
+
+## Licence
+
+MIT

{scripticus_server-0.1.1 → scripticus_server-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scripticus-server"
-version = "0.1.1"
+version = "0.3.0"
 description = "A package manager and registry for scripts — index service"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -8,8 +8,15 @@ license = "MIT"
 dependencies = [
     "fastapi>=0.115",
     "uvicorn>=0.30",
+    "sqlalchemy>=2.0",
+    "httpx>=0.27",
+    "python-multipart>=0.0.9",
+    "scripticus-schema>=0.1.2,<0.2.0",
 ]
 
+[tool.uv.sources]
+scripticus-schema = { workspace = true }
+
 [project.scripts]
 scripticus-svr = "scripticus_server.main:main"
 

scripticus_server-0.3.0/src/scripticus_server/app.py

@@ -0,0 +1,122 @@
+from typing import Literal
+
+from fastapi import Depends, FastAPI, HTTPException
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from scripticus_schema.index_api import (
+    PackageSummary,
+    PackageVersions,
+    SearchResults,
+    VersionSummary,
+)
+from scripticus_schema.semver import semver_key
+from scripticus_server import __version__, db
+from scripticus_server.db import get_session
+from scripticus_server.publish import router as publish_router
+
+app = FastAPI(
+    title="Scripticus index service",
+    description=(
+        "Manifest-aware search, version and dependency resolution, and the "
+        "publish path for a Scripticus registry."
+    ),
+    version=__version__,
+)
+app.include_router(publish_router)
+
+
+# Local to the server on purpose: a liveness shape is not part of the
+# package contract, so it doesn't meet the schema/ admission rule (D29).
+class HealthStatus(BaseModel):
+    status: Literal["ok"] = "ok"
+
+
+# Unauthenticated by design: a liveness probe carries nothing worth gating,
+# and the index service stays out of the ACL business anyway (D24). Leave it
+# open even once other endpoints grow auth.
+@app.get("/health")
+def health() -> HealthStatus:
+    return HealthStatus()
+
+
+class VersionInfo(BaseModel):
+    version: str
+
+
+@app.get("/version")
+def version() -> VersionInfo:
+    return VersionInfo(version=__version__)
+
+
+@app.get("/packages/{namespace}/{name}")
+def package_versions(
+    namespace: str, name: str, session: Session = Depends(get_session)
+) -> PackageVersions:
+    package = session.scalar(
+        select(db.Package)
+        .join(db.Namespace)
+        .where(db.Namespace.name == namespace, db.Package.name == name)
+    )
+    if package is None:
+        raise HTTPException(404, f"no package '{namespace}/{name}' in the index")
+    ordered = sorted(
+        package.versions, key=lambda pv: semver_key(pv.version), reverse=True
+    )
+    return PackageVersions(
+        namespace=namespace,
+        name=name,
+        description=next((pv.description for pv in ordered if not pv.yanked), ""),
+        versions=[
+            VersionSummary(version=pv.version, yanked=pv.yanked) for pv in ordered
+        ],
+    )
+
+
+def _has_matching_artifact(
+    package_version: db.PackageVersion, platform: str | None, language: str | None
+) -> bool:
+    if platform is None and language is None:
+        return True
+    for artifact in package_version.artifacts:
+        if platform is not None and platform not in artifact.platform_list():
+            continue
+        if language is not None and artifact.language != language:
+            continue
+        return True
+    return False
+
+
+@app.get("/search")
+def search(
+    q: str = "",
+    platform: str | None = None,
+    language: str | None = None,
+    session: Session = Depends(get_session),
+) -> SearchResults:
+    packages = session.scalars(
+        select(db.Package)
+        .join(db.Namespace)
+        .where(db.Package.name.contains(q))
+        .order_by(db.Namespace.name, db.Package.name)
+    ).all()
+    results = []
+    for package in packages:
+        candidates = [
+            pv
+            for pv in package.versions
+            if not pv.yanked and _has_matching_artifact(pv, platform, language)
+        ]
+        if not candidates:
+            continue
+        latest = max(candidates, key=lambda pv: semver_key(pv.version))
+        results.append(
+            PackageSummary(
+                namespace=package.namespace.name,
+                name=package.name,
+                description=latest.description,
+                latest_version=latest.version,
+            )
+        )
+    return SearchResults(results=results)

scripticus_server-0.3.0/src/scripticus_server/db.py

@@ -0,0 +1,175 @@
+"""The index data model (ARCHITECTURE.md), SQLite via SQLAlchemy (D23).
+
+No SQLite-isms: everything here must work unchanged on Postgres, so the
+database stays a configuration change (``SCRIPTICUS_INDEX_DB``). Tables are
+created with ``create_all`` at startup — no migration tool until the schema
+has released consumers (D31).
+
+The extracted columns are a publish-time projection of the verbatim
+manifest blob, never independently editable (D21).
+"""
+
+import os
+from collections.abc import Iterator
+
+from sqlalchemy import ForeignKey, Text, UniqueConstraint, create_engine
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import (
+    DeclarativeBase,
+    Mapped,
+    Session,
+    mapped_column,
+    relationship,
+    sessionmaker,
+)
+
+DEFAULT_DB_URL = "sqlite:///scripticus-index.db"
+
+
+def database_url() -> str:
+    return os.environ.get("SCRIPTICUS_INDEX_DB", DEFAULT_DB_URL)
+
+
+def make_engine(url: str | None = None) -> Engine:
+    return create_engine(url or database_url())
+
+
+def init_db(engine: Engine) -> None:
+    Base.metadata.create_all(engine)
+
+
+_session_factory: sessionmaker | None = None
+
+
+def get_session() -> Iterator[Session]:
+    # FastAPI dependency. Lazy so that importing the app never touches the
+    # database; tables are created on first use (D31: create_all until the
+    # schema stabilises).
+    global _session_factory
+    if _session_factory is None:
+        engine = make_engine()
+        init_db(engine)
+        _session_factory = sessionmaker(bind=engine)
+    with _session_factory() as session:
+        yield session
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Namespace(Base):
+    """A cached reference to a Gitea user/org — an FK anchor only. Gitea
+    remains authoritative for ownership and ACLs; nothing permission-shaped
+    is ever stored here (D24).
+    """
+
+    __tablename__ = "namespace"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(unique=True)
+
+    packages: Mapped[list["Package"]] = relationship(back_populates="namespace")
+
+
+class Package(Base):
+    __tablename__ = "package"
+    __table_args__ = (UniqueConstraint("namespace_id", "name"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    namespace_id: Mapped[int] = mapped_column(ForeignKey("namespace.id"))
+    name: Mapped[str]
+
+    namespace: Mapped[Namespace] = relationship(back_populates="packages")
+    versions: Mapped[list["PackageVersion"]] = relationship(back_populates="package")
+
+
+class PackageVersion(Base):
+    """Immutable once written; yank is a whole-version flag (npm model)."""
+
+    __tablename__ = "package_version"
+    __table_args__ = (UniqueConstraint("package_id", "version"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    package_id: Mapped[int] = mapped_column(ForeignKey("package.id"))
+    version: Mapped[str]
+    description: Mapped[str] = mapped_column(default="")
+    yanked: Mapped[bool] = mapped_column(default=False)
+    published_at: Mapped[str] = mapped_column(default="")  # ISO 8601 UTC
+    publisher: Mapped[str] = mapped_column(default="")
+
+    package: Mapped[Package] = relationship(back_populates="versions")
+    artifacts: Mapped[list["Artifact"]] = relationship(back_populates="package_version")
+    dependencies: Mapped[list["Dependency"]] = relationship()
+    tool_deps: Mapped[list["ToolDep"]] = relationship()
+    commands: Mapped[list["Command"]] = relationship()
+    manifest_blob: Mapped["ManifestBlob | None"] = relationship(
+        back_populates="package_version"
+    )
+
+
+class Artifact(Base):
+    """One per platform/language variant of a version."""
+
+    __tablename__ = "artifact"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    package_version_id: Mapped[int] = mapped_column(ForeignKey("package_version.id"))
+    # Comma-joined OS names from the manifest's platforms.os — a queryable
+    # projection; the manifest blob remains the authoritative list.
+    platforms: Mapped[str]
+    language: Mapped[str]
+    archive_format: Mapped[str] = mapped_column(default="")
+    content_hash: Mapped[str] = mapped_column(default="")
+    size: Mapped[int] = mapped_column(default=0)
+    gitea_pointer: Mapped[str] = mapped_column(default="")
+
+    package_version: Mapped[PackageVersion] = relationship(back_populates="artifacts")
+
+    def platform_list(self) -> list[str]:
+        return self.platforms.split(",") if self.platforms else []
+
+
+class Dependency(Base):
+    __tablename__ = "dependency"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    package_version_id: Mapped[int] = mapped_column(ForeignKey("package_version.id"))
+    target: Mapped[str]  # fully namespaced: "owner/name"
+    spec: Mapped[str]  # semver range constraint
+
+
+class ToolDep(Base):
+    __tablename__ = "tool_dep"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    package_version_id: Mapped[int] = mapped_column(ForeignKey("package_version.id"))
+    name: Mapped[str]
+    required: Mapped[bool] = mapped_column(default=True)
+
+
+class Command(Base):
+    __tablename__ = "command"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    package_version_id: Mapped[int] = mapped_column(ForeignKey("package_version.id"))
+    name: Mapped[str]
+    script_path: Mapped[str]
+
+
+class ManifestBlob(Base):
+    """The verbatim manifest as published — the authoritative record every
+    extracted column above is re-derivable from (D21).
+    """
+
+    __tablename__ = "manifest_blob"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    package_version_id: Mapped[int] = mapped_column(
+        ForeignKey("package_version.id"), unique=True
+    )
+    toml: Mapped[str] = mapped_column(Text)
+
+    package_version: Mapped[PackageVersion] = relationship(
+        back_populates="manifest_blob"
+    )

scripticus_server-0.3.0/src/scripticus_server/gitea.py

@@ -0,0 +1,115 @@
+"""The server's boundary to Gitea (D2): permission checks and blob storage.
+
+Auth is pass-through (D32): every publish carries the caller's own Gitea
+token, and this client acts with exactly that token's rights — the index
+service holds no credentials and caches nothing ACL-shaped (D24). The
+narrow surface here exists so tests can fake Gitea; nothing outside this
+module speaks HTTP to it.
+"""
+
+import os
+
+import httpx
+from fastapi import Header, HTTPException
+
+DEFAULT_GITEA_URL = "http://localhost:3000"
+
+
+def gitea_url() -> str:
+    return os.environ.get("SCRIPTICUS_GITEA_URL", DEFAULT_GITEA_URL)
+
+
+class GiteaAuthError(Exception):
+    """The token is missing, invalid, or expired."""
+
+
+class GiteaError(Exception):
+    """Gitea is unreachable or answered something unexpected."""
+
+
+class GiteaClient:
+    def __init__(self, base_url: str, token: str):
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"Authorization": f"token {token}"},
+            timeout=30,
+        )
+
+    def _get(self, path: str) -> httpx.Response:
+        try:
+            return self._client.get(path)
+        except httpx.HTTPError as exc:
+            raise GiteaError(f"cannot reach Gitea: {exc}") from exc
+
+    def authenticated_user(self) -> str:
+        """The login of the token's owner; raises GiteaAuthError on a bad token."""
+        response = self._get("/api/v1/user")
+        if response.status_code in (401, 403):
+            raise GiteaAuthError("Gitea rejected the token")
+        if response.status_code != 200:
+            raise GiteaError(f"unexpected {response.status_code} from Gitea /user")
+        return response.json()["login"]
+
+    def can_publish(self, namespace: str, user: str) -> bool:
+        """Live ACL check (D24): the namespace is the user themselves, or an
+        organisation the user is a member of. Unknown namespaces are simply
+        not publishable — Gitea owns namespace existence.
+        """
+        if namespace == user:
+            return True
+        response = self._get(f"/api/v1/orgs/{namespace}/members/{user}")
+        if response.status_code == 204:
+            return True
+        if response.status_code < 500:
+            # Non-membership, nonexistent org, and permission refusals all
+            # come back as assorted 3xx/4xx depending on Gitea version; every
+            # one of them means "cannot publish here".
+            return False
+        raise GiteaError(f"unexpected {response.status_code} from Gitea org check")
+
+    def _blob_path(self, namespace: str, name: str, version: str, filename: str) -> str:
+        return f"/api/packages/{namespace}/generic/{name}/{version}/{filename}"
+
+    def upload_blob(
+        self, namespace: str, name: str, version: str, filename: str, data: bytes
+    ) -> str:
+        """Write the archive to Gitea's generic package registry; returns the
+        download path (relative to the Gitea base URL) as the artifact pointer.
+        """
+        path = self._blob_path(namespace, name, version, filename)
+        try:
+            response = self._client.put(path, content=data)
+        except httpx.HTTPError as exc:
+            raise GiteaError(f"cannot reach Gitea: {exc}") from exc
+        if response.status_code == 201:
+            return path
+        if response.status_code in (401, 403):
+            raise GiteaAuthError("Gitea refused the blob write")
+        raise GiteaError(
+            f"Gitea blob write failed with {response.status_code}: {response.text}"
+        )
+
+    def delete_blob(
+        self, namespace: str, name: str, version: str, filename: str
+    ) -> None:
+        """Best-effort cleanup of an uploaded blob after a failed publish;
+        never raises — the publish error it accompanies matters more.
+        """
+        try:
+            self._client.delete(self._blob_path(namespace, name, version, filename))
+        except httpx.HTTPError:
+            pass
+
+
+def get_gitea_client(authorization: str | None = Header(None)) -> GiteaClient:
+    """FastAPI dependency: a GiteaClient acting as the request's caller.
+
+    Accepts ``Authorization: token <t>`` (Gitea's own convention) or
+    ``Bearer <t>``.
+    """
+    if authorization is None:
+        raise HTTPException(401, "publishing requires a Gitea token")
+    scheme, _, token = authorization.partition(" ")
+    if scheme.lower() not in ("token", "bearer") or not token:
+        raise HTTPException(401, "malformed Authorization header")
+    return GiteaClient(gitea_url(), token)

scripticus_server-0.3.0/src/scripticus_server/publish.py

@@ -0,0 +1,316 @@
+"""The write path: atomic server-mediated publish (D8, D32).
+
+Order of operations is the atomicity guarantee: every validation and
+permission check happens first, the blob goes to Gitea next, and the index
+record is committed only after Gitea confirms the write. Failure at any
+step rejects the whole publish; a commit failure after the blob write
+triggers a best-effort blob delete so nothing dangles.
+
+Nothing the client claims is trusted (D8): identity, variant tags,
+dependencies, and the content hash are all derived from the uploaded
+archive server-side.
+"""
+
+import re
+import tarfile
+import tempfile
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException, UploadFile
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from scripticus_schema.manifest import (
+    FORMAT_GROUPS,
+    NAMESPACE_RE,
+    PACKAGE_NAME_RE,
+    Manifest,
+    ManifestError,
+    commands_of,
+    load_manifest,
+)
+from scripticus_schema.publish_api import PublishedArtifact, PublishResult
+from scripticus_schema.treehash import tree_hash
+from scripticus_server import db
+from scripticus_server.db import get_session
+from scripticus_server.gitea import (
+    GiteaAuthError,
+    GiteaClient,
+    GiteaError,
+    get_gitea_client,
+)
+
+router = APIRouter()
+
+RESERVED_NAMESPACES = ("library",)
+
+_SAFE_FILENAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+def _archive_format(filename: str) -> str:
+    if filename.endswith((".tar.gz", ".tgz")):
+        return "tar.gz"
+    if filename.endswith(".zip"):
+        return "zip"
+    raise HTTPException(400, f"'{filename}' is not a supported archive (.tar.gz or .zip)")
+
+
+def _extract_archive(archive: Path, destination: Path) -> Path:
+    """Extract and return the single root directory of the package tree.
+
+    The tar "data" filter (PEP 706) rejects path traversal, links pointing
+    outside the tree, and device files; zipfile's extract sanitises
+    absolute paths and parent references itself.
+    """
+    try:
+        if archive.name.endswith(".zip"):
+            with zipfile.ZipFile(archive) as zf:
+                zf.extractall(destination)
+        else:
+            with tarfile.open(archive) as tar:
+                tar.extractall(destination, filter="data")
+    except (tarfile.TarError, zipfile.BadZipFile, OSError) as exc:
+        raise HTTPException(400, f"cannot extract archive: {exc}") from exc
+
+    roots = list(destination.iterdir())
+    if len(roots) != 1 or not roots[0].is_dir():
+        raise HTTPException(400, "archive does not contain a single package directory")
+    return roots[0]
+
+
+def _artifact_platforms(manifest: Manifest, archive_format: str) -> list[str]:
+    group = dict(FORMAT_GROUPS)[archive_format]
+    platforms = [os_name for os_name in group if os_name in manifest.platforms.os]
+    if not platforms:
+        raise HTTPException(
+            422,
+            f"a .{archive_format} archive carries {'/'.join(group)} targets, but the"
+            f" manifest declares platforms {manifest.platforms.os}",
+        )
+    return platforms
+
+
+def _check_dependency_targets(session: Session, manifest: Manifest) -> None:
+    """Publish-time dependency rules (D33): targets must be fully namespaced
+    and already present in the index.
+    """
+    missing = []
+    for target in sorted(manifest.dependencies.packages):
+        namespace, _, name = target.partition("/")
+        if not (NAMESPACE_RE.match(namespace) and name and PACKAGE_NAME_RE.match(name)):
+            raise HTTPException(
+                422,
+                f"dependency '{target}' is not a fully namespaced package"
+                " reference (namespace/name)",
+            )
+        known = session.scalar(
+            select(db.Package)
+            .join(db.Namespace)
+            .where(db.Namespace.name == namespace, db.Package.name == name)
+        )
+        if known is None or not known.versions:
+            missing.append(target)
+    if missing:
+        raise HTTPException(
+            422,
+            "dependencies not present in the index: " + ", ".join(missing),
+        )
+
+
+def _check_no_cycle(session: Session, manifest: Manifest) -> None:
+    """Reject a publish that would make the publishing package reachable from
+    its own dependencies (D33). Edges are package-level: the union of every
+    version's declared dependencies.
+    """
+    rows = session.execute(
+        select(db.Namespace.name, db.Package.name, db.Dependency.target)
+        .join(db.Package, db.Package.namespace_id == db.Namespace.id)
+        .join(db.PackageVersion, db.PackageVersion.package_id == db.Package.id)
+        .join(db.Dependency, db.Dependency.package_version_id == db.PackageVersion.id)
+    ).all()
+    edges: dict[str, set[str]] = {}
+    for namespace, name, target in rows:
+        edges.setdefault(f"{namespace}/{name}", set()).add(target)
+
+    publishing = f"{manifest.package.namespace}/{manifest.package.name}"
+    edges.setdefault(publishing, set()).update(manifest.dependencies.packages)
+
+    seen = set()
+    stack = list(edges[publishing])
+    while stack:
+        node = stack.pop()
+        if node == publishing:
+            raise HTTPException(
+                422,
+                f"publishing would create a dependency cycle back to '{publishing}'",
+            )
+        if node in seen:
+            continue
+        seen.add(node)
+        stack.extend(edges.get(node, ()))
+
+
+def _storage_filename(upload_name: str, manifest: Manifest, archive_format: str) -> str:
+    """The blob's filename in Gitea. The client's wheel-style name is kept
+    when sane (filenames are human-legible redundancy only — the manifest is
+    the source of truth), otherwise a minimal name is generated.
+    """
+    candidate = Path(upload_name).name
+    if _SAFE_FILENAME_RE.match(candidate) and candidate.endswith(f".{archive_format}"):
+        return candidate
+    package = manifest.package
+    return (
+        f"{package.name.replace('-', '_')}-{package.version.replace('-', '_')}"
+        f".{archive_format}"
+    )
+
+
+@router.post("/packages", status_code=201)
+def publish(
+    archive: UploadFile,
+    session: Session = Depends(get_session),
+    gitea: GiteaClient = Depends(get_gitea_client),
+) -> PublishResult:
+    data = archive.file.read()
+    archive_format = _archive_format(Path(archive.filename or "").name)
+
+    with tempfile.TemporaryDirectory(prefix="scripticus-publish-") as staging_dir:
+        staging = Path(staging_dir)
+        upload_path = staging / f"upload.{archive_format}"
+        upload_path.write_bytes(data)
+        package_root = _extract_archive(upload_path, staging / "tree")
+
+        try:
+            manifest = load_manifest(package_root)
+        except ManifestError as exc:
+            raise HTTPException(422, str(exc)) from exc
+        meta = manifest.package
+
+        if meta.namespace in RESERVED_NAMESPACES:
+            raise HTTPException(
+                403, f"the '{meta.namespace}' namespace is reserved"
+            )
+        platforms = _artifact_platforms(manifest, archive_format)
+
+        try:
+            user = gitea.authenticated_user()
+            allowed = gitea.can_publish(meta.namespace, user)
+        except GiteaAuthError as exc:
+            raise HTTPException(401, str(exc)) from exc
+        except GiteaError as exc:
+            raise HTTPException(502, str(exc)) from exc
+        if not allowed:
+            raise HTTPException(
+                403, f"'{user}' cannot publish to namespace '{meta.namespace}'"
+            )
+
+        content_hash = tree_hash(package_root)
+        manifest_text = (package_root / "meta.toml").read_text()
+
+    namespace = session.scalar(
+        select(db.Namespace).where(db.Namespace.name == meta.namespace)
+    )
+    package = session.scalar(
+        select(db.Package)
+        .join(db.Namespace)
+        .where(db.Namespace.name == meta.namespace, db.Package.name == meta.name)
+    )
+    existing = None
+    if package is not None:
+        existing = next(
+            (pv for pv in package.versions if pv.version == meta.version), None
+        )
+    if existing is not None:
+        # The variant rule (D32): more artifacts may join a version only if
+        # they carry the identical tree, in a format not yet published.
+        recorded_hashes = {a.content_hash for a in existing.artifacts}
+        if recorded_hashes and content_hash not in recorded_hashes:
+            raise HTTPException(
+                409,
+                f"{meta.namespace}/{meta.name} {meta.version} already exists"
+                " with different content; versions are immutable",
+            )
+        if any(a.archive_format == archive_format for a in existing.artifacts):
+            raise HTTPException(
+                409,
+                f"{meta.namespace}/{meta.name} {meta.version} already has a"
+                f" .{archive_format} artifact; duplicate versions are rejected",
+            )
+    else:
+        _check_dependency_targets(session, manifest)
+        _check_no_cycle(session, manifest)
+
+    filename = _storage_filename(archive.filename or "", manifest, archive_format)
+    try:
+        pointer = gitea.upload_blob(meta.namespace, meta.name, meta.version, filename, data)
+    except GiteaAuthError as exc:
+        raise HTTPException(401, str(exc)) from exc
+    except GiteaError as exc:
+        raise HTTPException(502, str(exc)) from exc
+
+    # Gitea has confirmed the write; only now may the index record go in.
+    try:
+        if existing is None:
+            if namespace is None:
+                namespace = db.Namespace(name=meta.namespace)
+            if package is None:
+                package = db.Package(namespace=namespace, name=meta.name)
+            version = db.PackageVersion(
+                package=package,
+                version=meta.version,
+                description=meta.description,
+                published_at=datetime.now(timezone.utc).isoformat(),
+                publisher=user,
+            )
+            for target, spec in sorted(manifest.dependencies.packages.items()):
+                version.dependencies.append(db.Dependency(target=target, spec=spec))
+            for tool in manifest.dependencies.tools.requires:
+                version.tool_deps.append(db.ToolDep(name=tool, required=True))
+            for tool in manifest.dependencies.tools.optional:
+                version.tool_deps.append(db.ToolDep(name=tool, required=False))
+            for command, script in sorted(commands_of(manifest).items()):
+                version.commands.append(db.Command(name=command, script_path=script))
+            db.ManifestBlob(package_version=version, toml=manifest_text)
+        else:
+            version = existing
+        db.Artifact(
+            package_version=version,
+            platforms=",".join(platforms),
+            language=meta.language,
+            archive_format=archive_format,
+            content_hash=content_hash,
+            size=len(data),
+            gitea_pointer=pointer,
+        )
+        session.add(version)
+        session.commit()
+    except IntegrityError as exc:
+        session.rollback()
+        gitea.delete_blob(meta.namespace, meta.name, meta.version, filename)
+        raise HTTPException(
+            409,
+            f"{meta.namespace}/{meta.name} {meta.version} was published"
+            " concurrently; duplicate versions are rejected",
+        ) from exc
+    except Exception:
+        session.rollback()
+        gitea.delete_blob(meta.namespace, meta.name, meta.version, filename)
+        raise
+
+    return PublishResult(
+        namespace=meta.namespace,
+        name=meta.name,
+        version=meta.version,
+        content_hash=content_hash,
+        publisher=user,
+        artifact=PublishedArtifact(
+            filename=filename,
+            archive_format=archive_format,
+            platforms=platforms,
+            language=meta.language,
+            size=len(data),
+        ),
+    )

scripticus_server-0.1.1/PKG-INFO

@@ -1,66 +0,0 @@
-Metadata-Version: 2.4
-Name: scripticus-server
-Version: 0.1.1
-Summary: A package manager and registry for scripts — index service
-License-Expression: MIT
-Requires-Dist: fastapi>=0.115
-Requires-Dist: uvicorn>=0.30
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
-# Scripticus server
-
-The index service for [Scripticus](https://github.com/kevinchannon/scripticus),
-a package manager and registry for scripts. The server provides
-manifest-aware search, version and dependency resolution, and the publish
-path for a Scripticus registry. Installing this package provides the
-`scripticus-svr` command.
-
-## Running the server
-
-`scripticus-svr` starts the service, printing its version and address on
-start-up:
-
-```console
-$ scripticus-svr --host 0.0.0.0 --port 8000
-scripticus-svr 0.1.0 — serving on http://0.0.0.0:8000 (interactive API docs at http://0.0.0.0:8000/docs)
-```
-
-Both options are optional; the default is `127.0.0.1:8000`. The API is
-self-describing: interactive docs are served at `/docs` and the OpenAPI
-spec at `/openapi.json`.
-
-### Health check
-
-`GET /health` returns `200` with `{"status": "ok"}` while the service is
-up. It is deliberately unauthenticated — it's a liveness probe for load
-balancers and container orchestrators.
-
-### Docker
-
-Server releases publish a Docker image to
-[`kevinchannon/scripticus-server`](https://hub.docker.com/r/kevinchannon/scripticus-server)
-(tagged with the release version and `latest`). The repository ships a
-`docker-compose.yml` running it as a single container — no checkout
-needed:
-
-```console
-$ curl -LO https://raw.githubusercontent.com/kevinchannon/scripticus/main/docker-compose.yml
-$ docker compose up -d
-$ curl http://localhost:8000/health
-{"status":"ok"}
-```
-
-The intended v1 deployment pairs the index service with a Gitea instance
-that provides storage, authentication, and namespace ownership; Gitea
-integration doesn't exist yet, so the compose file is currently
-server-only and does not stand up a working registry.
-
-Once Gitea is part of the bundle: accounts and organisations are managed
-in Gitea; a Scripticus namespace is a Gitea user or organisation, claimed
-first-come-first-served, and publish rights follow Gitea's own membership
-and ACLs. The `library` namespace is reserved.
-
-## Licence
-
-MIT

scripticus_server-0.1.1/README.md

@@ -1,56 +0,0 @@
-# Scripticus server
-
-The index service for [Scripticus](https://github.com/kevinchannon/scripticus),
-a package manager and registry for scripts. The server provides
-manifest-aware search, version and dependency resolution, and the publish
-path for a Scripticus registry. Installing this package provides the
-`scripticus-svr` command.
-
-## Running the server
-
-`scripticus-svr` starts the service, printing its version and address on
-start-up:
-
-```console
-$ scripticus-svr --host 0.0.0.0 --port 8000
-scripticus-svr 0.1.0 — serving on http://0.0.0.0:8000 (interactive API docs at http://0.0.0.0:8000/docs)
-```
-
-Both options are optional; the default is `127.0.0.1:8000`. The API is
-self-describing: interactive docs are served at `/docs` and the OpenAPI
-spec at `/openapi.json`.
-
-### Health check
-
-`GET /health` returns `200` with `{"status": "ok"}` while the service is
-up. It is deliberately unauthenticated — it's a liveness probe for load
-balancers and container orchestrators.
-
-### Docker
-
-Server releases publish a Docker image to
-[`kevinchannon/scripticus-server`](https://hub.docker.com/r/kevinchannon/scripticus-server)
-(tagged with the release version and `latest`). The repository ships a
-`docker-compose.yml` running it as a single container — no checkout
-needed:
-
-```console
-$ curl -LO https://raw.githubusercontent.com/kevinchannon/scripticus/main/docker-compose.yml
-$ docker compose up -d
-$ curl http://localhost:8000/health
-{"status":"ok"}
-```
-
-The intended v1 deployment pairs the index service with a Gitea instance
-that provides storage, authentication, and namespace ownership; Gitea
-integration doesn't exist yet, so the compose file is currently
-server-only and does not stand up a working registry.
-
-Once Gitea is part of the bundle: accounts and organisations are managed
-in Gitea; a Scripticus namespace is a Gitea user or organisation, claimed
-first-come-first-served, and publish rights follow Gitea's own membership
-and ACLs. The `library` namespace is reserved.
-
-## Licence
-
-MIT

scripticus_server-0.1.1/src/scripticus_server/app.py

@@ -1,29 +0,0 @@
-from typing import Literal
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-from scripticus_server import __version__
-
-app = FastAPI(
-    title="Scripticus index service",
-    description=(
-        "Manifest-aware search, version and dependency resolution, and the "
-        "publish path for a Scripticus registry."
-    ),
-    version=__version__,
-)
-
-
-# Local to the server on purpose: a liveness shape is not part of the
-# package contract, so it doesn't meet the schema/ admission rule (D29).
-class HealthStatus(BaseModel):
-    status: Literal["ok"] = "ok"
-
-
-# Unauthenticated by design: a liveness probe carries nothing worth gating,
-# and the index service stays out of the ACL business anyway (D24). Leave it
-# open even once other endpoints grow auth.
-@app.get("/health")
-def health() -> HealthStatus:
-    return HealthStatus()