Metadata-Version: 2.4
Name: scripticus-server
Version: 0.8.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.5.0,<0.6.0
Requires-Dist: scripticus-common>=0.2.0,<0.3.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 listing, and the atomic publish path for
a Scripticus registry. Installing this package provides the
`scripticus-svr` command.

## Running the server

The recommended way to run a Scripticus registry is the Docker Compose
bundle: a reverse proxy fronting the index service and the Gitea instance
that provides storage, authentication, and namespace ownership. 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`), and the repository's
`docker-compose.yml` wires the whole bundle together — no checkout needed.
The proxy is the single URL clients use (`http://localhost:8000`): it routes
blob downloads to Gitea and everything else to the index, so a client needs
no Gitea address of its own (D45). The bundle publishes exactly one port:
account management is served through the same front at
`http://localhost:8000/accounts` (D62), so there is no second port to open.

The `get-scripticus-svr` script does the whole standup (D61) — it checks the
host, fetches the compose bundle, starts it, and creates your Gitea admin
account with a correctly-scoped publish token:

```console
$ curl -fsSL https://raw.githubusercontent.com/kevinchannon/scripticus/main/get-scripticus-svr | sh
```

It asks three things — where to put the stack, the administrator's account
name, and the organisation to publish under — then prints a username,
password, and token. **Save all three then** — Gitea shows a token once, and
the script will not mint a second one for an account that already exists.

The administrator and the publishing namespace are deliberately separate. A
namespace is a Gitea user *or organisation*, so the person running the registry
does not have to be the identity packages belong to: answer `acme-co` to the
namespace question and packages read `acme-co/backup-rotate`, while the admin
account stays a person. Skipping it publishes under the admin's own username,
which is fine for a personal registry and a trap for a shared one — every
reference already published keeps that name.

Options go after `-s --`, since a pipe leaves nowhere else to put them:

```console
$ curl -fsSL .../get-scripticus-svr | sh -s -- --dir /srv/registry --port 9000
```

`--dir`, `--user`, `--org`, `--email`, and `--port` cover the non-interactive case;
`--help` lists them. Pass `--public-url` if the registry will not be reached at
`http://localhost:<port>` — the account pages build their links from it, so
getting it wrong leaves a working registry with broken links.

If you would rather read it before running it — a fair instinct for anything
piped into a shell — download it first and run it separately; the script
behaves identically either way:

```console
$ curl -fsSLO https://raw.githubusercontent.com/kevinchannon/scripticus/main/get-scripticus-svr
$ less get-scripticus-svr
$ sh get-scripticus-svr
```

It refuses rather than repairs: an existing directory, compose stack, or Gitea
user stops the run rather than modifying what is already there. It needs
Docker, the Compose v2 plugin at v2.23.1 or newer (the bundle carries its proxy
config inline), and either `curl` or `wget`.

### Running the index service directly

Of course, you can also just run the index service on its own — without
the proxy-and-Gitea bundle — which is handy for development or slotting it
into infrastructure you already operate. `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`.

Run this way, the index service still needs a Gitea instance to publish
against (`SCRIPTICUS_GITEA_URL`, default `http://localhost:3000`) and an
index database — a local SQLite file (`scripticus-index.db`) by default,
or set `SCRIPTICUS_INDEX_DB` to any SQLAlchemy URL to point elsewhere;
tables are created automatically on first use. The Compose bundle provides
both for you.

### 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.

### Publishing

`POST /packages` publishes a package version: a multipart upload of one
or more archives — a version's whole format-group set, as produced by
`scripticus pack`, one repeated `archives` part each — with your Gitea
token in the `Authorization` header. This is what `scripticus publish`
does for you; the raw request looks like:

```console
$ curl -X POST http://localhost:8000/packages \
    -H "Authorization: token <your-gitea-token>" \
    -F archives=@my_tool-1.0.0-linux.macos-bash.tar.gz \
    -F archives=@my_tool-1.0.0-windows-bash.zip
```

The server trusts nothing about the upload: it re-validates every
archive's manifest and package tree, checks the batch is one content
tree in different archive formats, 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 blobs in Gitea's generic package registry, and only then
commits the index record. The batch is atomic: if any archive fails
validation or any write fails, nothing is published.
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`).

### Yanking

`PATCH /packages/{namespace}/{name}/{version}` with a JSON body of
`{"yanked": true}` hides a published version from search and `latest`/range
resolution while leaving it fetchable by anything that pins it exactly — no
hard delete. `{"yanked": false}` reverses it. Auth is the same live,
namespace-scoped Gitea check as publishing, so only a namespace owner can
yank. This is what `scripticus yank` (and `yank --undo`) does for you:

```console
$ curl -X PATCH http://localhost:8000/packages/infra/backup-rotate/1.2.0 \
    -H "Authorization: token <your-gitea-token>" \
    -H "Content-Type: application/json" \
    -d '{"yanked": true}'
```

Unlike publish, this touches no Gitea blob — it flips one flag on the index
record. An unknown version is a 404; yank is idempotent and carries no time
window, so a version can be un-yanked at any time.

## Licence

MIT
