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
dev -d / dev --detach	Same, but as an unattended daemon: detached, output appended to ~/.nextcraft/run/<clone>/dev.log, pidfile beside it. Refuses to double-start. Auto-serves the built web UI same-origin when apps/web/out exists.	0 started, 1 already running
stop	Stops the daemon started by dev -d (SIGTERM, SIGKILL after 5s), cleans the pidfile.	0 stopped/clean, 1 kill failed
log	Tails the daemon log: last 50 lines by default, -n N for more, -f/--follow to stream.	0 ok, 1 no log yet
--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 / single-port deployment

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

Production behind one port (v0.3.6): when only one port is reachable (e.g. behind HAProxy), build the web app as a static export and let the ai-service serve it same-origin on :8420 — UI and API on one port, no CORS, no mixed content:

curl -fsSL https://git.coreci.dev/coreci/nextcraft/raw/main/scripts/install.sh | sh   # fresh binary
git pull --ff-only && pnpm install
NEXT_PUBLIC_AI_SERVICE_URL=self pnpm build   # emits apps/web/out
nextcraft dev -d                             # daemon; auto-serves the UI from :8420
nextcraft log -f                             # tail the daemon log

Durable state (SQLite DB, sandbox workdirs, daemon pid/log) lives in ~/.nextcraft/ — never inside the repo. Full recipe incl. HAProxy timeouts and a systemd unit: deploy/README.md.

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