scripticus-server 0.1.0__tar.gz → 0.2.0__tar.gz

{scripticus_server-0.1.0 → scripticus_server-0.2.0}/PKG-INFO

@@ -1,10 +1,12 @@
 Metadata-Version: 2.4
 Name: scripticus-server
-Version: 0.1.0
+Version: 0.2.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: scripticus-schema>=0.1.1,<0.2.0
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 
@@ -36,12 +38,38 @@ spec at `/openapi.json`.
 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. Note
+that publishing doesn't exist yet, so a fresh index is empty until it
+lands.
+
 ### Docker
 
-The repository ships a `docker-compose.yml` running the index service as a
-single container:
+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"}

{scripticus_server-0.1.0 → scripticus_server-0.2.0}/README.md

@@ -26,12 +26,38 @@ spec at `/openapi.json`.
 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. Note
+that publishing doesn't exist yet, so a fresh index is empty until it
+lands.
+
 ### Docker
 
-The repository ships a `docker-compose.yml` running the index service as a
-single container:
+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"}

{scripticus_server-0.1.0 → scripticus_server-0.2.0}/pyproject.toml

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

scripticus_server-0.2.0/src/scripticus_server/app.py

@@ -0,0 +1,134 @@
+from collections.abc import Iterator
+from typing import Literal
+
+from fastapi import Depends, FastAPI, HTTPException
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.orm import Session, sessionmaker
+
+from scripticus_schema.index_api import (
+    PackageSummary,
+    PackageVersions,
+    SearchResults,
+    VersionSummary,
+)
+from scripticus_schema.semver import semver_key
+from scripticus_server import __version__, db
+
+app = FastAPI(
+    title="Scripticus index service",
+    description=(
+        "Manifest-aware search, version and dependency resolution, and the "
+        "publish path for a Scripticus registry."
+    ),
+    version=__version__,
+)
+
+_session_factory: sessionmaker | None = None
+
+
+def get_session() -> Iterator[Session]:
+    # 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 = db.make_engine()
+        db.init_db(engine)
+        _session_factory = sessionmaker(bind=engine)
+    with _session_factory() as session:
+        yield session
+
+
+# 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.2.0/src/scripticus_server/db.py

@@ -0,0 +1,151 @@
+"""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 sqlalchemy import ForeignKey, Text, UniqueConstraint, create_engine
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+
+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)
+
+
+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.1.0/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()