# 0xTsoa

> 0xTsoa (pronounced ZeroTsoa) is an open-source registry of Linux desktop configurations.

Created by Ny Harena RAVELOMANANTSOA ([GitHub](https://github.com/nyharena25) · [LinkedIn](https://www.linkedin.com/in/rnyharena-dev/)).

0xTsoa (spoken alias: **ZeroTsoa**) is a static registry built with Astro 7 (`output: 'static'`), Tailwind CSS v4, Zod 4, and Pagefind, deployed on Vercel at https://www.0xtsoa.dev. Every configuration is a standalone JSON file in Git (`configs/<author>/<slug>.json`), validated against a strict Zod/JSON Schema in CI and compiled into static HTML and JSON at build time.

## Pages

- [Home](https://www.0xtsoa.dev/): top-voted spotlight carousel, quick compositor/style links, and registry overview
- [Catalogue](https://www.0xtsoa.dev/catalogue/): full configuration index filterable by desktop part, compositor/WM, distribution and theme style (`?category=`, `?wm=`, `?style=`, `?distro=`, `?q=`), 10 per page (`?p=`), sorted by `?sort=new|old|votes|popular`
- [Contribute](https://www.0xtsoa.dev/contribute/): submission instructions for GitHub Issue Form and direct Pull Requests
- [About](https://www.0xtsoa.dev/about/): what 0xTsoa is, name origin, and creator profile (Ny Harena RAVELOMANANTSOA)
- Configuration detail pages: `https://www.0xtsoa.dev/configs/<author>/<slug>/` (specifications table, assurance badges, step-by-step install commands and downloadable `.sh` script, optional SHA-256 script digest, screenshot gallery, rendered upstream README snapshot, and keybindings)

## Machine-Readable Data

- [index.json](https://www.0xtsoa.dev/index.json): full registry exported as a JSON array of `CatalogueItem` objects
- [Sitemap](https://www.0xtsoa.dev/sitemap-index.xml): XML sitemap index covering all public pages and `/configs/<author>/<slug>/` routes

### `index.json` Entry Field Reference

Each item in `https://www.0xtsoa.dev/index.json` contains:

- `id` (`string`): `<author>/<slug>` identifier matching `/configs/<author>/<slug>/`
- `name` (`string`): setup title (`3–80` chars)
- `author` (`{ name: string, github: string }`): maintainer display name and GitHub handle
- `summary` (`string`): one-sentence technical summary (`10–200` chars)
- `distros` (`string[]`): target distributions (`arch`, `endeavouros`, `manjaro`, `fedora`, `nixos`, `debian`, `ubuntu`, `mint`, `void`, `opensuse`, `gentoo`, `alpine`, `any`)
- `wm` (`string`): window manager or compositor (`hyprland`, `sway`, `river`, `niri`, `wayfire`, `labwc`, `i3`, `bspwm`, `awesome`, `qtile`, `xmonad`, `dwm`, `herbstluftwm`, `openbox`, `gnome`, `kde`, `xfce`, `cinnamon`, `cosmic`, `any`, `other`)
- `displayServer` (`"wayland" | "x11" | "both"`): display server protocol
- `tags` (`string[]`): lowercase kebab-case tags (up to 10)
- `specs` (`object`): optional component details (`bar`, `terminal`, `launcher`, `notifications`, `theme`, `shell`, `editor`)
- `thumbUrl` (`string`): primary screenshot URL (from `screenshots[0].url`)
- `thumbAlt` (`string`): accessible description for the primary screenshot
- `version` (`string`, optional): configuration version string
- `updatedAt` (`string`): last modification date (`YYYY-MM-DD`)
- `votes` (`number`): community sign-off count snapshotted at build time

## Submission & Community Vote Flow

1. **Issue Form or Direct PR**: Contributors submit via the GitHub Issue Form (`new-config.yml`) or open a Pull Request adding `configs/<author>/<slug>.json`.
2. **Automated Bot PR (`issue-to-pr.yml`)**: When an issue with label `new-config` is opened (or labeled `regenerate` by a maintainer), `scripts/issue-to-config.ts` parses the markdown fields, downloads any referenced install script (up to 1 MiB) to compute its SHA-256 hash if omitted, validates the payload with `configSchema`, and either opens a Pull Request or comments the validation errors on the issue.
3. **CI Validation (`validate.yml`)**: Every push and PR runs `npx tsx scripts/validate-configs.ts --scripts`, `npm test`, and `npm run build` to enforce schema rules, `{{ref}}` checkout in `git clone` steps, duplicate/case-collision detection, allowed image hosts, and `install.script` SHA-256 digests. Pull requests touching `configs/**` also run `npx tsx scripts/validate-configs.ts --network --only <changed-files>` to check remote screenshot, README, and script reachability.
4. **Community Vote Issue (`ensure-vote-issues` & `fetch-votes`)**: On push to `main` or nightly (`deploy.yml`), CI ensures a dedicated GitHub issue titled `[0xTsoa] <author>/<slug>` with label `vote` exists and triggers a Vercel deployment. Community members vote by reacting with `+1` (one vote per user) on that issue; `prebuild` (`scripts/fetch-votes.ts`) snapshots those `+1` reaction counts into `src/generated/votes.json`.

## Assurance & Reproducibility Model

- **Three Levels of Assurance (`AssuranceBadges.astro`)**:
  - **Schema validated**: always shown; entry passes Zod schema, screenshot-host, and `{{ref}}` clone-step validation.
  - **Source pinned**: shown when `source.ref` is a 40-character hexadecimal Git commit SHA (`^[0-9a-f]{40}$`), because Git tags can be moved upstream whereas a 40-char commit SHA cannot be moved and all `git clone` steps check out `{{ref}}`.
  - **Script hash-checked**: shown only when `install.script` is provided; CI verifies the script's 64-character lowercase hex `sha256` digest (1 MiB limit).
  - **Install reviewed by @x**: shown only when `review.installReviewed` is true.
- **Image Host Allowlist**: External screenshot URLs are restricted to `raw.githubusercontent.com`, `user-images.githubusercontent.com`, `private-user-images.githubusercontent.com`, `github.com`, `i.imgur.com`, `i.redd.it`, `codeberg.org`, and `gitlab.com` (plus local `/` paths).
- **Sanitized README Rendering**: Upstream READMEs are fetched from `source.ref` at build time, parsed with `marked`, and stripped of unsafe tags/attributes via `sanitize-html`.

## Source & Governance

- [GitHub Repository](https://github.com/nyharena25/0xTsoa)
- [Config JSON Schema](https://github.com/nyharena25/0xTsoa/blob/main/schema/config.schema.json)
- [Zod Schema Definition](https://github.com/nyharena25/0xTsoa/blob/main/src/lib/schema.ts)
- [Contribution Guidelines](https://github.com/nyharena25/0xTsoa/blob/main/CONTRIBUTING.md)
- Licenses: platform code is MIT; registry entries (`configs/`) are CC BY 4.0; linked dotfiles retain their respective upstream licenses.