toki
424de604ee
- Add plane adapter client with test coverage - Add task external refs migration - Update workflow service with tests - Add HTTP handler tests - Update router and middleware tests - Update database models and queries - Update scheduler jobs - Update storage store - Update server main and docker-compose - Update roadmaps and documentation
125 lines
6.5 KiB
Markdown
125 lines
6.5 KiB
Markdown
# NomadCode
|
|
|
|
NomadCode is a monorepo for AI-assisted development workflows. It brings together a Go orchestration service, a React/Vite operator console, a Flutter client, shared contract space, and root-level agent-operation rules.
|
|
|
|
The repository is currently an early product scaffold. The core service owns task orchestration and persistence, the web and mobile apps provide initial operator surfaces, and `agent-ops/` keeps the rules and roadmap that AI agents need before changing the workspace.
|
|
|
|
## Current Status
|
|
|
|
- `services/core` has HTTP health/readiness endpoints, task APIs, PostgreSQL persistence, goose migrations, sqlc-generated query code, River jobs, model/A2A client paths, and Plane/Mattermost adapter stubs.
|
|
- `apps/web` is a React/Vite scaffold for Agent, Projects, and Settings views. Some state and integration status areas are still mocked or stubbed.
|
|
- `apps/mobile` is a Flutter app scaffold with Firebase Messaging, local notifications, and HTTP client dependencies.
|
|
- `packages/contracts` is a placeholder for future shared OpenAPI, protobuf, generated client, fixture, and compatibility assets.
|
|
- Active planning lives under `agent-ops/roadmap/`; this README links to that context instead of duplicating milestone state.
|
|
|
|
## Quick Start
|
|
|
|
Install only the runtimes needed for the part of the workspace you are using.
|
|
|
|
```bash
|
|
# Show service/app dev entrypoints.
|
|
bin/dev
|
|
|
|
# Run workspace checks for installed toolchains.
|
|
bin/test
|
|
bin/lint
|
|
bin/build
|
|
```
|
|
|
|
Run the core service locally. The scripts provide local defaults, but they still expect reachable PostgreSQL and Redis services; see `services/core/README.md` for the current `code-server` database setup notes.
|
|
|
|
```bash
|
|
cd services/core
|
|
./bin/migrate-up
|
|
./bin/run
|
|
```
|
|
|
|
Run the web console:
|
|
|
|
```bash
|
|
cd apps/web
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Run the Flutter app:
|
|
|
|
```sh
|
|
cd apps/mobile
|
|
flutter pub get
|
|
flutter run
|
|
```
|
|
|
|
## Major Commands
|
|
|
|
| Purpose | Command | Notes |
|
|
|------|------|------|
|
|
| Show local dev entrypoints | `bin/dev` | Prints core, web, and mobile commands. |
|
|
| Test workspace | `bin/test` | Runs `go test ./...`, web `npm run check` or tests if present, and `flutter test`; skips missing toolchains. |
|
|
| Lint workspace | `bin/lint` | Runs `go vet ./...`, web `npm run lint --if-present`, and `flutter analyze --no-fatal-infos`; skips missing toolchains. |
|
|
| Build workspace | `bin/build` | Runs core `go build ./...`, web `npm run build`, and `flutter build web`; skips missing toolchains. |
|
|
| Run core | `cd services/core && ./bin/run` | Uses local defaults from the core script unless environment variables override them. |
|
|
| Migrate core DB | `cd services/core && ./bin/migrate-up` | Uses goose against the configured PostgreSQL database. |
|
|
| Test core | `cd services/core && ./bin/test` | Thin wrapper around `go test ./...`. |
|
|
| Build core binary | `cd services/core && ./bin/build` | Outputs to `.build/nomadcode-core` unless `OUTPUT` is set. |
|
|
| Run web dev server | `cd apps/web && npm run dev` | Vite development server. |
|
|
| Check web types | `cd apps/web && npm run check` | TypeScript `--noEmit`. |
|
|
| Verify web | `cd apps/web && npm run verify` | Runs type check and production build. |
|
|
| Run mobile tests | `cd apps/mobile && flutter test` | Flutter test suite. |
|
|
|
|
## Structure
|
|
|
|
| Path | Role |
|
|
|------|------|
|
|
| `services/core/` | Go backend for orchestration, persistence, scheduling, HTTP APIs, and external service adapters. |
|
|
| `apps/web/` | React/Vite operator console and browser-based agent/project workspace UI. |
|
|
| `apps/mobile/` | Flutter mobile/desktop client and notification integration surface. |
|
|
| `packages/contracts/` | Future shared API/schema contracts and generated client boundary. |
|
|
| `docs/` | Architecture and operations notes. |
|
|
| `bin/` | Root test, lint, build, and dev helper commands. |
|
|
| `agent-ops/` | Agent rules, domain routing, roadmap, and repeatable task skills. |
|
|
|
|
## Work Context
|
|
|
|
AI agents should start with the root instructions and project rules before changing files:
|
|
|
|
- `AGENTS.md`
|
|
- `agent-ops/rules/project/rules.md`
|
|
- `agent-ops/rules/private/rules.md` when present
|
|
|
|
For workspace-level files such as this README, also check:
|
|
|
|
- `agent-ops/rules/project/domain/workspace-ops/rules.md`
|
|
- `agent-ops/skills/common/create-readme/SKILL.md`
|
|
- `agent-ops/roadmap/current.md`
|
|
|
|
Keep detailed roadmap state in `agent-ops/roadmap/` and detailed domain rules in `agent-ops/rules/project/domain/`. Do not read `agent-task/archive/**` unless the user explicitly asks for it.
|
|
|
|
## Development Flow
|
|
|
|
- Prefer the root `bin/test`, `bin/lint`, `bin/build`, and `bin/dev` entrypoints for whole-workspace work.
|
|
- Keep changes scoped to the owning domain rules. Cross-boundary changes should close the contract, service, and client behavior in the same branch when those boundaries move together.
|
|
- For core database changes, update `services/core/migrations/` and `services/core/queries/`, then regenerate sqlc output instead of hand-editing generated files under `services/core/internal/db/`.
|
|
- Keep `agent-ops/rules/common/**` and `agent-ops/skills/common/**` as framework-synced areas; put project-specific rules under `agent-ops/rules/project/**`.
|
|
|
|
## Environment Variables
|
|
|
|
| Runtime | Name | Required | Notes |
|
|
|------|------|------|------|
|
|
| Core | `DATABASE_URL` | No, with scripts | Core scripts provide local defaults; set it when running the binary directly or using a different PostgreSQL database. |
|
|
| Core | `REDIS_URL`, `REDIS_KEY_PREFIX` | No, with scripts | Core scripts provide local defaults for worker/queue state; set them when running outside those scripts. |
|
|
| Core | `AUTH_USERNAME`, `AUTH_PASSWORD` | No | `AUTH_PASSWORD` enables HTTP Basic Auth for `/readyz` and `/api/*`. |
|
|
| Core | `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` | No | Configure the OpenAI-compatible model endpoint used by worker execution. |
|
|
| Core | `A2A_EDGE_URL`, `A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC` | No | Configure the A2A-compatible agent call path. |
|
|
| Core | `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN` | No | Reserved for Mattermost adapter integration. |
|
|
| Core | `PLANE_BASE_URL`, `PLANE_TOKEN` | No | Configure Plane work item lookup, comment, and state update integration. |
|
|
| Web | `VITE_NOMADCODE_API_BASE_URL` | No | The web client falls back to `http://localhost:8080`; `apps/web/.env.example` documents the same local value. |
|
|
|
|
## Reference Documents
|
|
|
|
- `docs/monorepo.md`
|
|
- `services/core/README.md`
|
|
- `apps/web/README.md`
|
|
- `apps/mobile/README.md`
|
|
- `packages/contracts/README.md`
|
|
- `agent-ops/roadmap/current.md`
|