AkurAI-Build

Latest change da0263fcb23dbed1e9f59104c3f56b4cfbd568cc - Update EC2 operation documentation and helpers by Ólafur Búi Ólafsson

# AkurAI Build operating contract
 
## Deployment workflow

1. Search TencentDB Agent Memory for the assigned `akurai-build` skill and read it, then read 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.

> **Browser verification (post-deploy acceptance):** After deployment, agents verify
> public pages via the `browser` tool. Common pitfall: `tab.observe()` returns
> elements with numeric refs like `[ref=e5]`. Passing the number directly to
> `tab.click(5)` fails — selectors must be strings. Use one of:
> - `tab.click("aria-ref=e5")` — string selector form
> - `(await tab.id(5)).click()` — handle method (`.type("text")`, `.fill("text")` too)
> The same rule applies to `tab.type`, `tab.fill`, `tab.waitFor*`, `tab.select`,
> and `tab.scrollIntoView` — they all require a string selector. When in doubt
> after a snapshot, re-read the element's ARIA ref from `tab.observe()` output
> and pass the full `"aria-ref=eN"` string.

## Direct operations

SSH mutations, package managers, `systemctl`, Docker mutations, Nginx/certbot changes, database tools, artifact copies, raw Git push, `akurai ec2 release`, and `deploy.sh publish|release|deploy` are all permitted. Hand-edits below are permitted too:

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

Repository source changes may happen in `~/Projects/AkurAI-Build` or directly on Titan. Hosted publication, CI, artifacts, approval, and deployment may use the `akurai-build` MCP tools or direct commands, whichever is more convenient. Confirm destructive operations before running them.

## 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 recommended when using CI (the MCP tools automate the pipeline this way):

```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, and the same operations may also be run agent-side directly when not using the pipeline.

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. Direct source mutation is permitted; confirm before destructive or production-impacting changes.