Skip to content

README.md

Latest commit

 

History

History
97 lines (75 loc) · 3.37 KB

README.md

File metadata and controls

97 lines (75 loc) · 3.37 KB
Raw

Cealshell Proxy

A small, self-hostable proxy that turns a Git host reference into an installable Roblox model — with no central registry. Packages aren't published or namespaced here; they live in whatever GitHub or Codeberg repo their author chose, and the proxy resolves owner:repo[@version] on demand. Point the Cealshell CLI at the official instance or run your own.

It is stateless apart from a tiny version cache: it resolves owner:repo[@version] against a source provider (GitHub or Codeberg), fetches the release's .rbxm asset (or one committed via cealshell.toml), parses it into the instance tree the plugin consumes, and returns it. No accounts, no uploads, no download tracking.

This is the open-source proxy slice of Cealshell. User accounts, OAuth, admin and moderation tooling live in the private backend and are intentionally not included here.

Endpoints

Route Description
GET /github/:ref Resolve :ref through GitHub
GET /codeberg/:ref Resolve :ref through Codeberg (Forgejo/Gitea)
GET /:ref Default — resolves owner:repo[@version] through GitHub
GET /health Liveness check

:ref is owner:repo[@version], e.g. janisfox:marble or janisfox:marble@1.2.0. Omitting the version resolves to the newest published one. (owner/repo is also accepted.)

The response envelope is:

{
  "ok": true,
  "data": {
    "package": { "provider": "github", "owner": "...", "repo": "...", "slug": "...", "version": "1.2.0" },
    "instances": [ /* parsed .rbxm instance tree */ ],
    "release_notes": "..."
  }
}

To use your instance from the CLI, set it as the remote:

cshl remote set https://proxy.example.com

…or use a one-off override on a single reference, e.g. proxy.example.com/janisfox:marble.

How a repo becomes installable

Either of:

  1. Release asset — attach a .rbxm to a GitHub/Codeberg release. The proxy serves the newest release that ships one.
  2. cealshell.toml — commit a manifest pointing at a .rbxm in the repo, no release needed. See docs/manifest.md. When present it takes precedence over releases.

Running it

Requires Node 18+ and PostgreSQL.

cp .env.example .env       # fill in DB_* (and optionally GITHUB_TOKEN)
npm install
npm run migrate            # create the cache tables
npm run dev                # or: npm run build && npm start

A GITHUB_TOKEN / CODEBERG_TOKEN is optional but recommended — without one you share the host's low unauthenticated API rate limit.

Adding a source provider

Source providers live in src/providers/source/. Implement the SourceProvider interface (types.ts) — fetchVersions and fetchManifest — and register it in index.ts. It auto-mounts at /<id>/:ref. GitHub and Codeberg are the built-in examples; the contract assumes a release-with-attached-asset model.

Project layout

src/
  index.ts                 Express app — health + proxy routes only
  routes/registry.ts       The proxy HTTP handlers
  services/
    registry.ts            Ref parsing, package upsert, version sync
    rbxm.ts                Fetch + parse a .rbxm into the instance tree
    manifest.ts            cealshell.toml reader
  providers/source/        GitHub + Codeberg source providers
  db/                      pg connection, schema, migrate runner