CIAgent
135ea21a61
Fixes the v0.3.4 fresh-box failures: silent CLI under bare-word PATH invocation (SEA argv detection), bootstrap dying on venv creation without an actionable hint (poisoned-partial-venv recovery + apt hint + doctor venv-capability probe + preflight), installer falsely 'verifying' a silent binary, and localhost-only server binding (network mode: 0.0.0.0 + wildcard CORS + hostname-derived API URL — remote browsing zero-config). 38 CLI tests, 3 web tests, 409 ai-service tests green; build/typecheck/lint clean. ---ci--- phase: hotfix milestone: v0.4 status: complete type: hotfix requirements: covered: [REQ-4-001, REQ-4-002, REQ-4-003, REQ-4-004, REQ-4-005] partial: [] ---/ci---
72 lines
4.0 KiB
Markdown
72 lines
4.0 KiB
Markdown
# Nextcraft
|
|
|
|
AI-native outcome school + marketplace — graduates prove what they can build, not what they can write.
|
|
|
|
## Quickstart
|
|
|
|
One-liner install (linux x64):
|
|
|
|
```sh
|
|
curl -fsSL https://git.coreci.dev/coreci/nextcraft/raw/main/scripts/install.sh | sh
|
|
```
|
|
|
|
That downloads the latest release's `nextcraft` CLI binary, verifies its sha256 checksum, and installs it to `~/.local/bin` (PATH hint printed if needed). Every release ships fresh binaries — re-run the one-liner to upgrade.
|
|
|
|
Then, from a clone of this repo:
|
|
|
|
```sh
|
|
nextcraft doctor # check prerequisites: node >= 18, pnpm >= 8, python3 >= 3.11, git, unshare
|
|
nextcraft bootstrap # pnpm install + ai-service venv + .env from template (idempotent)
|
|
nextcraft verify # health check: venv imports, uvicorn, ports, env
|
|
nextcraft dev # run the ai-service dev server on :8420 (web dev server: pnpm dev)
|
|
```
|
|
|
|
The E2E test (`apps/cli/tests/fresh-clone-e2e.test.ts`) proves this exact sequence on a fresh clone.
|
|
|
|
### No binary / non-linux?
|
|
|
|
The installer degrades to printed source instructions. Manual equivalent:
|
|
|
|
```sh
|
|
git clone https://git.coreci.dev/coreci/nextcraft.git && cd nextcraft
|
|
pnpm install
|
|
bash apps/ai-service/scripts/bootstrap.sh
|
|
cp apps/ai-service/.env.example apps/ai-service/.env
|
|
pnpm ai:dev
|
|
```
|
|
|
|
## CLI reference (`nextcraft`)
|
|
|
|
| Command | What it does | Exit codes |
|
|
|---------|--------------|------------|
|
|
| `doctor` | Checks prerequisites on PATH: node >= 18, pnpm >= 8, python3 >= 3.11, git, unshare (sandbox fabric). Every ✗ prints a fix hint. | 0 all pass, 1 any fail |
|
|
| `bootstrap` | Sets up the monorepo from a fresh clone: (1) locates the repo root, (2) `pnpm install`, (3) ai-service venv via `apps/ai-service/scripts/bootstrap.sh`, (4) copies `.env.example` → `.env` if absent, (5) warns on missing optional keys. Idempotent — safe to re-run. | 0 ok, 1 step failed |
|
|
| `verify` | Health check: ai-service venv + `import ai_service`, uvicorn importable, `.env` present (warn-only), `AI_PORT` (default 8420) free, workspace `node_modules` present. | 0 ok, 1 failures |
|
|
| `dev` | Thin passthrough to `apps/ai-service/scripts/dev.sh` (exports secrets from `.ciagent/.env.secrets` if present, runs uvicorn on :8420). Ctrl+C stops it. The web dev server is separate: `pnpm dev`. | child's exit code |
|
|
| `--help` / `-h` | Usage for the CLI or any command. | 0 |
|
|
| `--version` | Prints the version this binary was built as (matches the release tag). | 0 |
|
|
|
|
Exit-code contract: `0` success, `1` check/step failure (hint printed), `2` usage error.
|
|
|
|
### Remote server
|
|
|
|
`nextcraft dev` binds the API on **0.0.0.0:8420** (and `pnpm dev` serves the web app on all interfaces), so the stack works from other machines out of the box:
|
|
|
|
- Browse `http://<your-host>:3000` — the web app targets `http://<your-host>:8420` automatically (derived from the browser's hostname).
|
|
- CORS admits any origin (`AI_CORS_ORIGINS=*` in `apps/ai-service/.env`). This is safe **only** because credentials are never enabled; to restrict, set an explicit list: `AI_CORS_ORIGINS=http://<your-host>:3000`.
|
|
- To revert to loopback-only: `AI_HOST=127.0.0.1` in `apps/ai-service/.env`.
|
|
- Security note: this is an unauthenticated dev API reachable from any network the box exposes. Mitigations that still apply: per-learner sandbox caps + global rate caps + learner allowlist (G-5), telemetry flood control (traces marked `INCOMPLETE_FLOODED` are refused by the grader). Expose only on trusted networks until identity/KYC lands (v0.5).
|
|
|
|
## Docs
|
|
|
|
- [apps/cli/README.md](apps/cli/README.md) — CLI internals: build, binary pipeline, troubleshooting
|
|
- [.ciagent/PROJECT.md](.ciagent/PROJECT.md) — product spec and milestone history
|
|
- [.ciagent/ARCHITECTURE.md](.ciagent/ARCHITECTURE.md) — system architecture
|
|
|
|
## Status
|
|
|
|
**Milestone v0.4** — Distribution & Bootstrap CLI (one-liner install, `nextcraft` binary releases on every ship)
|
|
|
|
Prior: v0.3 Credential Engines (shipped v0.2.8) · v0.2 AI Tutor Architecture (v0.2.0) · v0.1 UI/UX Prototype (v0.1.0)
|
|
|
|
Initialized via CIAgent v0.7.0 |