Skip to content
This repository was archived by the owner on Jul 13, 2026. It is now read-only.

developers.md

Latest commit

 

History

History
176 lines (132 loc) · 5.78 KB

developers.md

File metadata and controls

176 lines (132 loc) · 5.78 KB
Raw

Finite Sites Developer Guide

This document is for humans and agents working on the Finite Sites codebase. The root README.md is intentionally agent-first and focuses on installing and using fsite.

Read CONTEXT.md before changing code. It defines the product vocabulary used by code, docs, tests, and prompts. Follow docs/engineering-style.md; it is the style contract for this repo.

Product Shape

Finite Sites replaces self-hosting sites from inside agent machines with a Finite-owned serving substrate behind wildcard domains. Agents collaborate in git. A Project Repository is the editable source of truth, and Project Outputs select committed bytes to serve as immutable Versions.

Current v1 capabilities:

  • Static site Project Outputs served from committed deploy bytes.
  • Document Outputs served from authored Markdown under the document base domain, including clean routes, Markdown companion URLs, /llms.txt, and /llms-full.txt.
  • NIP-98-signed registry mutations through a local User Key.
  • Self-registration with fsite auth register.
  • Project Repositories over Git smart HTTP through git-http-backend.
  • Generated /llms.txt for project-backed editable outputs when the project did not publish that path itself.
  • Per-output visibility: private, shared, or public.
  • Email magic links for external viewer and collaborator bootstrap.
  • Operator controls for publish grants, output disable/delete, and selected public-read Project Repository visibility.

Stateful apps and PDF outputs use or will use the same Project Repository model. See docs/roadmap.md and the ADRs for the current design history.

Crate Layout

Crate Ownership
finitesites-proto Nostr events, NIP-98, manifests, names, limits, DTOs, finite.toml parsing
finitesites-blob Content-addressed blob storage
finitesites-store SQLite registry: grants, projects, outputs, versions, shares, tokens
finitesites-engine Product decisions: project init, git deploy, sharing, viewing, auth
finitesitesd HTTP server, wildcard site serving, Git smart HTTP, operator commands
fsite-cli Agent-facing CLI binary, fsite

Local Development

Common commands:

just dev
just test
just lint
just fmt

just dev runs finitesitesd against .dev-data.

Manual local quickstart:

# Terminal 1: run the server.
cargo run -p finitesitesd -- serve --data .dev-data

# Terminal 2: use the CLI against the local server.
export FINITE_SITES_API=http://127.0.0.1:8787
cargo run -p fsite-cli --bin fsite -- whoami
cargo run -p fsite-cli --bin fsite -- auth register --output json

Create a static-site Project from an example:

cargo run -p fsite-cli --bin fsite -- project init \
  --config examples/finitechat-native-mockup/finite.toml \
  --dry-run \
  --output json

cargo run -p fsite-cli --bin fsite -- project init \
  --config examples/finitechat-native-mockup/finite.toml \
  --output json

cargo run -p fsite-cli --bin fsite -- auth git finitechat-native --store --output json

tmp="$(mktemp -d)"
git clone http://git.sites.localhost:8787/finitechat-native.git "$tmp/finitechat-native"
rsync -a --delete examples/finitechat-native-mockup/ "$tmp/finitechat-native/"
cd "$tmp/finitechat-native"
git add finite.toml index.html
git commit -m "Seed finitechat native mockup"
git push origin main

Open the local site:

open http://finitechat-native-mockup.sites.localhost:8787/

*.sites.localhost resolves to loopback in modern browsers. For curl, pass a Host header against 127.0.0.1:8787.

curl -H "Host: finitechat-native-mockup.sites.localhost:8787" \
  http://127.0.0.1:8787/

Test Expectations

The repo's test bar is in docs/engineering-style.md.

  • Registry mutations need positive tests plus negative or replay tests.
  • Idempotent mutations need replay coverage.
  • Storage invariants need restart or migration coverage.
  • Git deploy behavior should be covered through the real HTTP e2e path.
  • cargo clippy --all-targets -- -D warnings must pass before handoff.

Use just test and just lint before committing. For release confidence, also run:

cargo build --locked --release --workspace

Production And Operations

Production runs finitesitesd as a systemd service behind Caddy and Cloudflare. The server owns the control-plane API, Git smart HTTP, and wildcard site serving. Publishing does not mutate host configuration; it is registry, blob, and git repository state.

Runbook and deploy files:

  • docs/deploy-finite-lat-2.md
  • deploy/finite-lat-2/
  • docs/technical-debt-ledger.md

Important production rule: use fsite for agent-facing publishing and editor handoff. Do not bypass it with raw Nostr events, direct registry writes, DNS edits, or proxy edits unless you are doing an explicit operator recovery from the runbook.

Release Shape

Tags named v* trigger .github/workflows/release.yml.

The GitHub release currently packages fsite binaries for:

  • fsite-linux-x86_64
  • fsite-macos-aarch64
  • fsite-macos-x86_64

The server binary finitesitesd is built locally or on the production host; it is not currently a GitHub release asset.

Before tagging:

just test
just lint
cargo build --locked --release --workspace

Documentation Map

  • CONTEXT.md: glossary; use these words in code and prompts.
  • AGENTS.md: prompting contract and repo commands.
  • docs/engineering-style.md: engineering rules and test shape.
  • docs/adr/: decisions and alternatives.
  • docs/roadmap.md: planned tiers and future outputs.
  • docs/bare-repos-and-skills-hosting.md: source-only Project Repository requirements and public-read policy for finitecomputer-managed skills.
  • docs/technical-debt-ledger.md: accepted shortcuts with delete conditions.
  • skills/finite-sites-publishing/SKILL.md: agent skill for publishing.