fuzzyworld-tools

Tooling for Pavel's self-hosted code and apps on DreamHost. It replaces GitLab (code, CI, Pages) and WordPress (the blog) with static files plus a few helper machines.

The one rule: DreamHost only serves files. There is no app server. Pages are generated when you push, and Apache just sends them. Work that needs a real machine (CI, screenshots) runs on a runner (a home TrueNAS box, or the laptop when it is idle), which pulls jobs from DreamHost over ssh. No runner is a normal state: jobs wait.

The roadmap and backlog are in PLAN.md.

What it provides

Philosophy

Things made with AI should be shared freely with the world. The code and apps here were made with AI, so they are MIT-licensed: use them, change them, share them.

My conversations with the AI are different. My words and my way of working are mine. I publish a conversation only when I choose to.

The same text is on /why-i-left-gitlab/.

Hosting tiers

Each feature needs a certain kind of host. A tier includes the ones above it, so you can pick what your hosting allows.

T2 is new attack surface (code that runs on a web request, as the same user as everything else on the account), so comments are accepted by email only. To use the form you would host server/comments/post.php on its own subdomain and set comments_form in the blog config.

Quick start

First create the repo on DreamHost (private unless --public):

fw new my-game --public --description "One line."

Then make it an app (details and every option: docs/apps.md):

// package.json of the app repo
"scripts": { "deploy": "fw deploy" },
"fuzzyworld": { "app": "my-game", "title": "My Game", "description": "One line." },
"devDependencies": { "fuzzyworld-tools": "git+https://code.fuzzyworld.net/fuzzyworld-tools.git#semver:^1.0.0" }

git push dh:git/my-game.git   # `dh` is the SSH alias in ~/.ssh/config
npm run deploy                # clone main, install, check, build, upload, print the URL

Use fw outside an app repo (for example on a second laptop):

npm install -g "git+https://code.fuzzyworld.net/fuzzyworld-tools.git#semver:^1.0.0"

Commands

bin/fw runs some commands on the laptop (deploy, repoint, usage, admin, blog) and forwards the rest to DreamHost (ssh dh ~/bin/fw ...).

Repos

Apps and deploys

CI

Bug reports and comments

Laptop-side tools

npm run scripts in this repo: dev (preview the pages locally), deploy and deploy-status (deploy this repo's own server by default; -- all or a target name adds the runner and VS Code web; docs/operations.md), list-repos (fw list) and prepare-usage-for-pr (fw usage --trailers).

Visibility

Each bare repo stores its own setting: git config fuzzyworld.visibility public|private. Anything other than exactly public is private, including a missing value, so a repo is never published by accident. A private repo has no pages, no clone URL and no index entry, and pushing to it publishes nothing.

Other settings in the repo config:

Repository layout

Where things live on DreamHost: docs/operations.md.

Security in one paragraph

The site never executes anything from a repo: pages are pre-generated HTML with all repo content escaped, only image files are copied raw, scripts are denied by .htaccess, and the code site sends Content-Security-Policy: script-src 'none'. The full list is in docs/code-site.md.

Documentation

Tests

python3 -m unittest discover tests     # the whole suite: pages, blog, comments, issues, runner, admin, deploys
node --test tests/deploy.test.mjs      # fw deploy's config, rsync filters and replay-template checks

Known gaps

• fw deploys is documented above but bin/fw on the laptop rejects it ("unknown command"). fw admin is not affected.
• The npm package does not ship server/ (files in package.json), but fw blog (including import-wp and check) needs it, and fw usage --trailers reads server/prices.json (without it the trailers lose the @over100k split). So these work fully only from a checkout of this repo.

Other problems found are tracked in the global queue, not here.