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.

Server (deploy the whole stack, one command)

nextcraft deploy --service

That clones (or updates) the repo, installs deps, builds the web UI, restarts the service, verifies the site is served, and installs a systemd unit so the stack survives reboots. Idempotent — same command for first install and upgrades. Toolchain discovery included: node/pnpm behind nvm/PNPM_HOME/corepack are found even when non-interactive shells can't see them.

Development (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, web export, live mount probe
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: node >= 18, pnpm >= 8 (discovered via PATH/nvm/PNPM_HOME/corepack), 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 (discovered toolchain), (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 state — free, or busy + serving the web UI (live mount probe: / must return HTML, not the API's JSON 404), web export present (apps/web/out), workspace node_modules.	0 ok, 1 failures
deploy	One-command deploy/upgrade: clone-or-update repo (--dir, --ref), pnpm install, ai-service venv, NEXT_PUBLIC_AI_SERVICE_URL=self pnpm build, restart, verify. Fails loudly if the site isn't served.	0 ok, 1 step failed
deploy --service	Same, plus generates + installs a systemd unit (real paths, Restart=always, enabled) so the stack survives reboots; systemd becomes the supervisor.	0 ok, 1 step failed
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 (and refuses when the systemd service is active). Auto-serves the built web UI same-origin when apps/web/out exists.	0 started, 1 already running
stop	Stops the systemd service when it supervises the stack; otherwise stops the daemon started by dev -d (SIGTERM, SIGKILL after 5s) and 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), the one-command deploy builds the web app as a static export and lets the ai-service serve it same-origin on :8420 — UI and API on one port, no CORS, no mixed content:

nextcraft deploy --service   # install/upgrade + web export + restart + verify + systemd unit

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.5 — Real Server Voice, KYC/Identity, Sandbox Environments, Seq-Lease (shipped as v0.4.5)

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