Files

T

CIAgent 135ea21a61 merge: hotfix/fresh-box-experience → main (v0.3.5 fresh-box experience)

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

2026-09-13 00:05:37 +00:00

4.0 KiB

Raw Permalink Blame History

Nextcraft

AI-native outcome school + marketplace — graduates prove what they can build, not what they can write.

Quickstart

One-liner install (linux x64):

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:

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:

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 — CLI internals: build, binary pipeline, troubleshooting
.ciagent/PROJECT.md — product spec and milestone history
.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

4.0 KiB Raw Permalink Blame History