akurai-tasks

Latest change 364da517e9f2fad427d727601fa9609c03fe46f1 - feat: REST project repos and item repo; document repo binding by Ólafur Búi Ólafsson

# AkurAI-Tasks

AkurAI-Framework-based task and Kanban service for work spanning multiple projects and
repositories. One Rust process exposes the same command core through CLI, authenticated REST,
MCP over stdio/HTTP, and a no-build web application.

The local vertical slice is operational. Production deployment, legacy-board import, source
fencing, OIDC, backup automation, and migration remain gated by the later increments in
[PLAN.md](PLAN.md); this repository must not yet be treated as the production source of truth.

## What works

- multiple projects, each scoped to zero or more `owner/repository` identifiers;
- project task IDs (`PROJECT-1`, `PROJECT-2`, …) and nine-state Kanban boards;
- revision-checked adjacent transitions, blocking, dependencies, Ready frontier, claims,
  evidence, comments, durable handoffs, and append-only audit events;
- actor-scoped idempotency for every mutation;
- one embedded AkurAI-Framework BTree commit for projection, event, and idempotency result;
- CLI, authenticated REST, MCP 2025-11-25 tools/resources/prompts, and responsive web UI;
- bearer authentication and same-origin enforcement for REST and Streamable HTTP MCP.

## Build and check

Run on Titan from the repository root:

```sh
./scripts/check.sh
```

The gate runs the Rust workspace tests, builds the binary, creates a real temporary
multi-repository project and task through the CLI, reads its board, and exercises MCP over
stdio. The API tests cover authenticated reads/mutations and same-origin rejection.

## Run locally

Keep the token in the process environment or AkurAI PassVault-backed deployment environment;
never commit it:

```sh
export AKURAI_TASKS_TOKEN='replace-with-a-local-token'
export AKURAI_TASKS_ACTOR='local-operator'
cargo run -p akurai-tasks -- \
  --db data/tasks.db \
  serve --host 127.0.0.1 --port 8090 --frontend frontend
```

Open <http://127.0.0.1:8090>. Enter the same token in the in-app session dialog. The browser
keeps it in `sessionStorage`, so it is removed when the tab session ends.

For a separate public origin, set `AKURAI_TASKS_ALLOWED_ORIGIN` to the exact origin. Same-origin
browser requests work without that override.

## CLI

Global flags may appear before or after the command:

```sh
export AKURAI_TASKS_DB=data/tasks.db
export AKURAI_TASKS_ACTOR=olafur

cargo run -p akurai-tasks -- \
  --idempotency project-akurai \
  project create AKURAI "AkurAI services" olibuijr/AkurAI-Tasks,olibuijr/AkurAI-Framework

cargo run -p akurai-tasks -- \
  --idempotency task-command-core \
  item create AKURAI "Finish command core" \
  --repo olibuijr/AkurAI-Tasks --priority high

cargo run -p akurai-tasks -- project update AKURAI olibuijr/AkurAI-Tasks,olibuijr/AkurAI-Framework
cargo run -p akurai-tasks -- item set-repo AKURAI-1 olibuijr/AkurAI-Tasks
cargo run -p akurai-tasks -- board AKURAI
cargo run -p akurai-tasks -- frontier AKURAI
```

### Repository binding

A work item's `repo` must name a repository the project registers. When a project registers
exactly one repository the item repo is auto-filled; when it registers several an explicit
`--repo` is required, and an unregistered or missing repo is rejected. Use `project update KEY
REPOS` to register repositories on an existing project and `item set-repo ID REPO` to move an
existing item onto one. The MCP equivalents are `project_update` and `work_set_repo`.

Run `akurai-tasks help` for transition, claim, dependency, comment, evidence, block, and handoff
commands. Supply explicit idempotency keys for automation; the CLI generates one only for
interactive calls.

## REST

All `/api/*` routes except `/api/health` and `/api/ready` require:

```text
Authorization: Bearer <token>
X-AkurAI-Actor: <stable principal>
Idempotency-Key: <required on mutations>
```

Primary resources:

```text
GET  /api/projects
POST /api/projects
POST /api/projects/{key}/repos
GET  /api/projects/{project}/board
GET  /api/projects/{project}/frontier
POST /api/items
GET  /api/items/{id}
POST /api/items/{id}/repo
POST /api/items/{id}/transition
POST /api/items/{id}/claim
POST /api/items/{id}/dependency
POST /api/items/{id}/comment
POST /api/items/{id}/evidence
POST /api/items/{id}/handoff
POST /api/items/{id}/accept-handoff
POST /api/items/{id}/block
```

## MCP

Stdio mode never opens a second production database in the intended deployment topology; run it
against a local database only during development:

```sh
cargo run -p akurai-tasks -- --db data/tasks.db --actor agent-id mcp
```

The serving process exposes the same JSON-RPC dispatcher at authenticated `POST /mcp`. Tools
cover project/task creation and reads, boards, Ready frontier, transitions, claims, comments,
evidence, dependencies, and handoffs. It also exposes `tasks://projects` and the `next-task`
prompt.

## Architecture and boundaries

- Framework checkout: `/home/olafurbui/Projects/AkurAI-Framework` on Titan.
- Hindsight remains authoritative for conversational memory.
- AkurAI Notes notebook **AkurAI-Tasks** (ID 34) remains the architecture/operations record.
- AkurAI PassVault folder **AkurAI-Tasks** (ID 5) is the only approved credential store.
- ACP connects editors to agents; AkurAI-Tasks is the MCP tool server, not an ACP task store.

See [PLAN.md](PLAN.md) for production hardening, lossless import, backup/restore, source fencing,
deployment, and cutover acceptance gates.