AkurAI-Build

Latest change 30e6b8c347048d64c2c048dfd05a8ded219d37f6 - Host authenticated Git repositories over Smart HTTP with repo host/sync CLI by Ólafur Búi Ólafsson

# AkurAI Build operating contract

This is the first document to consult for every task.

## Command ladder

1. Read `skills/akurai-build/SKILL.md`.
2. Check `./deploy.sh help` for source, host, service, GitHub, EC2, Nginx, TLS, version, release, rollback, health, and logs operations.
3. Check `./deploy.sh cli --help` for repositories, runs, jobs, artifacts, promotions, recovery, and diagnostics.
4. Use the existing maintained command.
5. If no command exists, run only the smallest bounded **read-only probe** needed to understand the gap.
6. Once the probe succeeds, implement that operation in `deploy.sh` or `akurai`, add a focused check, and update this document plus the skill before performing the mutation.

## Prohibited direct mutations

Do not directly run SSH mutations, package managers, `systemctl`, Docker mutations, Nginx/certbot changes, database tools, artifact copies, Git commit/push, or edits to installed/runtime files. Do not hand-edit anything below:

- `~/.local/lib/akurai-build`
- `~/.local/share/akurai-build`
- `~/.config/akurai-build`
- `/etc/systemd/system/akurai-build.service`
- EC2 `/etc/nginx` or `/etc/letsencrypt`

Repository source changes happen only in `~/Projects/AkurAI-Build`; run `./deploy.sh sync` before Titan checks, then `./deploy.sh check`, and publish with `./deploy.sh publish` or `./deploy.sh release`; both maintain the repository-local GitHub author identity.

## Maintained operations

```sh
./deploy.sh sync
./deploy.sh edge-probe
./deploy.sh mesh-recover
./deploy.sh http-smoke
./deploy.sh probe
./deploy.sh bootstrap
./deploy.sh lock
./deploy.sh version show
./deploy.sh version patch|minor|major "summary"
./deploy.sh format
./deploy.sh clean-build
./deploy.sh recover-checks
./deploy.sh check
./deploy.sh binfmt
./deploy.sh docker-smoke
./deploy.sh build
./deploy.sh build-info
./deploy.sh deploy-local
./deploy.sh deploy
./deploy.sh vhost
./deploy.sh status-local
./deploy.sh status
./deploy.sh logs 100
./deploy.sh rollback
./deploy.sh publish "summary"
./deploy.sh release patch|minor|major "summary"
./deploy.sh cli ...
```

Source-changing/checking commands automatically run `sync` when forwarded from another host. Cargo incremental compilation is disabled because version-only rebuilds reproduced corrupt `rust-lld` objects in the Syncthing-backed tree. `check` bounds formatting, Clippy, and tests to 30/180/90 seconds with process-group termination so a deadlock is killed instead of hanging.
`mesh-recover` restarts the managed VPN tunnels on Titan and EC2 after a host reboot, then waits until EC2 can reach AkurAI Build's private health endpoint; it fails closed if the upstream does not return.

`http-smoke` verifies page rendering, strict CSP/frame/nosniff headers, health, and unauthenticated API rejection. `binfmt` installs only ARM64 emulation from pinned `tonistiigi/binfmt:qemu-v10.2.3-68`, verifies kernel registration, and runs an ARM Alpine smoke command. `docker-smoke` runs the real restricted Docker executor and verifies artifact creation on Titan. `deploy-local` verifies the Titan service independently with a bounded 15-second readiness wait. `deploy` owns the entire route to `https://akurai-builds.olibuijr.com`: Titan build/install/migration/system service with the Docker supplementary group, Pi skill, EC2 DNS/HTTP/S reachability, AkurAI-VPN upstream, Nginx, certificate presence/30-day expiry check, issuance or renewal, and local/public health verification.

Version components are bounded to `1..10`: `major.minor.patch`, starting at `1.1.1`. Patch `10` rolls to the next minor; minor `10` rolls to the next major; `10.10.10` is terminal. Every published version must match the newest `CHANGELOG.md` entry; `publish` compares against Git `HEAD` so non-version `Cargo.toml` edits cannot bypass a bump.

## CI operations

```sh
./deploy.sh cli doctor
./deploy.sh cli repo list --search NAME --visibility private
./deploy.sh cli repo add NAME URL --branch main
./deploy.sh cli repo host NAME /home/olafurbui/Projects/NAME --branch main
./deploy.sh cli repo sync NAME /home/olafurbui/Projects/NAME
./deploy.sh cli run NAME --git-ref main
./deploy.sh cli runs --repo NAME,OTHER --status failed,interrupted --trigger manual,webhook --search compiler --limit 20 --offset 0
./deploy.sh cli show RUN
./deploy.sh cli wait RUN --timeout 3600
./deploy.sh cli logs RUN --failed
./deploy.sh cli retry RUN
./deploy.sh cli promote RUN ENVIRONMENT
./deploy.sh cli artifact get ARTIFACT OUTPUT
./deploy.sh cli workers
```

Parse the JSON envelope and require persisted `succeeded` status before reporting success. `repo list` supports text/visibility filters. `runs` supports comma-separated `--repo`, `--status`, and `--trigger` filters plus exact `--git-ref`, free-text `--search`, bounded `--limit`, and `--offset`; `/api/state` exposes the same run query parameters. `AKURAI_WORKERS` configures 1–16 Titan workers (the service default is 2). Never read or expose protected token/key/secret values.

`repo host` is the maintained migration path from an external Git remote to AkurAI Build's authenticated Smart HTTP host. It creates a bare mirror below the protected data root and updates the CI registration only after the mirror is complete. `repo sync` is the maintained source-publication path from a trusted Titan checkout. Public Git clients use `https://akurai-build.olibuijr.com/git/NAME.git` with the protected API bearer token supplied through a credential helper; never put the token in a URL or argument.

For read-only MCP access, configure the client to run `./deploy.sh cli mcp`. The stdio server exposes `akurai_repositories`, `akurai_runs`, `akurai_run`, and `akurai_workers`; multi-value run filters accept strings, comma-separated values, or arrays.

## Learning loop

Run history, immutable commits, logs, artifact digests, deployment records, health results, tests, changelog entries, and rollback evidence are the system's knowledge. Improve commands and documentation from that evidence. Never implement autonomous unreviewed source mutation.