AkurAI-Build

public

Latest change 1bf82460f606664ade8dcc0e56f49243851d3cec - Repair Bun helper in live worker by Ólafur Búi Ólafsson

# AkurAI Build operating contract

## Deployment workflow

1. Read `skills/akurai-build/SKILL.md` and the repository's `.akurai.yml`.
2. Run the focused local source checks.
3. Commit only the intended paths in the trusted Titan checkout and record the full commit SHA.
4. Publish the committed revision with `mcp__akurai_build_akurai_repo_sync`.
5. Confirm the hosted branch's returned `sha` equals the local commit with `mcp__akurai_build_akurai_repo_branches`.
6. Queue the exact SHA with `mcp__akurai_build_akurai_run_queue`.
7. Inspect or wait through `akurai_run_show`/`akurai_run_wait`; promote a persisted `waiting` production environment only with `akurai_run_promote`.
8. Require persisted `succeeded` state, then verify public health and the changed behavior.

## Prohibited direct mutations

Do not directly run SSH mutations, package managers, `systemctl`, Docker mutations, Nginx/certbot changes, database tools, artifact copies, raw Git push, `akurai-ec2 release`, or `deploy.sh publish|release|deploy`. Do not hand-edit anything below:

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

Repository source changes happen only in `~/Projects/AkurAI-Build`. A narrowly staged local commit is the only permitted Git mutation; hosted publication, CI, artifacts, approval, and deployment use the `akurai-build` MCP tools.

## Deployment

A deployable repository owns the full release contract in `.akurai.yml`:

1. `verify` runs formatting, linting, tests, and project-specific gates.
2. `package` produces an immutable artifact and recorded SHA-256.
3. An approval-gated production job consumes that artifact without rebuilding it.
4. Post-deploy acceptance verifies health and changed behavior; failure rolls back.

Agent-side flow is always:

```text
local commit → repo_sync → verify hosted head → run_queue(exact SHA) → wait/promote → persisted success → acceptance
```

Commands such as `akurai-ec2` service or edge operations may appear inside a committed pipeline job. They are not agent-side queue, publication, approval, or deployment substitutes.

AkurAI Build is self-hosted as separate service and worker containers. The protected `deploy-production` job consumes the package job's prebuilt binary and atomically replaces only `akurai-build-service`; the worker remains alive to persist the deployment result. `deploy/service-deploy.sh` verifies both health endpoints, repairs the live worker's Bun-compatible `bunx` alias, installs the packaged stdio MCP binary and shared CI helpers atomically into the worker-mounted host tool path, and rolls the service back if any step fails. Worker-image replacement remains an explicit `deploy/compose-release.sh` host-maintenance operation outside the worker so the pipeline cannot self-sever; the Dockerfile preserves the same alias in every replacement image.

Every published version must match the newest `CHANGELOG.md` entry. Version components are bounded to `1..10`: patch `10` rolls to the next minor, minor `10` rolls to the next major, and `10.10.10` is terminal.

## MCP tool set

Use the configured `mcp__akurai_build_akurai_*` tools. Never invoke the installed binary's stdio protocol, direct Build HTTP, or `deploy.sh cli|mcp`. The mounted tool schema is authoritative. Current tools: `akurai_doctor`, `akurai_repo_list`, `akurai_repo_add`, `akurai_repo_host`, `akurai_repo_sync`, `akurai_repo_rename`, `akurai_repo_remove`, `akurai_repo_visibility`, `akurai_repo_branches`, `akurai_repo_tree`, `akurai_repo_blob`, `akurai_init`, `akurai_release`, `akurai_run_queue`, `akurai_runs`, `akurai_run_show`, `akurai_run_wait`, `akurai_run_logs`, `akurai_run_retry`, `akurai_run_promote`, `akurai_artifact_get`, `akurai_workers`.

Each tool returns its JSON payload as the sole `content` text entry, or `isError: true` with a message. `akurai_repo_branches` returns each branch name, exact head SHA, and default marker. `akurai_repo_tree` lists a directory at a branch or immutable commit; `akurai_repo_blob` reads a bounded UTF-8 file at a ref and path. Require persisted `succeeded` status before reporting success; `waiting` requires an explicit `akurai_run_promote`, and `queued`/`running` are incomplete. `akurai_repo_list` supports text/visibility filters; `akurai_runs` supports `repo`/`status`/`trigger` as a string, comma-separated values, or an array, plus exact `git_ref`, free-text `search`, bounded `limit`/`offset`. `AKURAI_WORKERS` configures 1–16 Titan workers (the service default is 1). Never read or expose protected token/key/secret values.

`akurai_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. `akurai_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.

`akurai_repo_remove` and `akurai_run_promote` are consequential — confirm intent before calling them; `akurai_repo_remove` cascades runs, jobs, logs, and artifacts.

## 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.