Nextcraft

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

Quickstart

nextcraft installs on any Debian-based Linux server through three channels (full recipes in deploy/README.md or nextcraft guide):

# 1. docker — the whole stack pre-loaded (API + UI + CLI in one image):
docker run -d --name nextcraft -p 8420:8420 \
  -v nextcraft-state:/home/nextcraft/.nextcraft \
  git.coreci.dev/coreci/nextcraft:<release-tag>

# 2. deb — apt-shaped (amd64 + arm64):
dpkg -i nextcraft_<ver>_<arch>.deb && nextcraft deploy --service

# 3. binary — the one-liner (linux x64 + arm64):
curl -fsSL https://git.coreci.dev/coreci/nextcraft/raw/main/scripts/install.sh | sh
nextcraft deploy --service

The binary download verifies sha256 + version stamps before install (mismatch = hard stop). Every release ships fresh binaries, debs, and a registry image — all machine-made by the release workflow.

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.

Pre-commit hooks (optional, recommended)

The repo ships a .pre-commit-config.yaml that mirrors the CI lanes locally: ruff over the ai-service python, eslint over the five TS workspaces (one root flat config), tsc --noEmit per workspace, plus whitespace/merge-conflict/large-file hygiene. Hooks are local-only and fail loud.

pip install pre-commit   # or: pipx install pre-commit
pre-commit install

From then on every git commit runs the hooks on the staged changes. First run may fetch the hygiene hook repo (github.com, reachable from this LAN).

No toolbox? The honest skip path: if you don't have the ruff/eslint/tsc toolchain set up (e.g. no ai-service venv yet — run nextcraft bootstrap first), hooks will fail loud with a pointer. The simplest honest escape for a contributor without the toolbox is:

git commit --no-verify

or skip specific hooks for one commit:

SKIP=ruff,eslint,tsc-web,tsc-cli,tsc-ui,tsc-types,tsc-mock-data git commit

Loud note: CI still gates. Skipping locally changes nothing about the push lanes — .gitea/workflows/ci.yaml runs lint + typecheck + tests on every push to every branch. A --no-verify commit that breaks lint gets caught at push time, just later and more publicly.

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.8 — Ship Anywhere (in progress): installable on any Debian-based server via every mainstream channel — docker image (Gitea registry, honest sandbox degrade), .deb packages (amd64+arm64, advisory postinst), arch-aware one-liner binary — with release consistency enforced by pre-commit hooks + Gitea Actions pipelines (runner fleet on CT 113, machine-made releases), the CLI carrying the full suite (nextcraft guide, channel-aware doctor), and the admin runbook (deploy/README.md).

Prior: v0.7 Test Harness Review (shipped as v0.6.6) · Milestone v0.6 — Marketplace Engine (shipped as v0.5.6): real job-postings backend behind the marketplace surfaces (6th SQLite store family + seeded ingestion adapter + admin authoring surface), AI tagging with facet-driven filters, embedding-backed semantic search with computed match scores, employer enrichment with per-field provenance, resume-to-profile auto-fill with an explicit confirm gate, and SEO programmatic pages (metadata, JSON-LD, dynamic sitemap/robots).

Prior: v0.5 Real Server Voice, KYC/Identity, Sandbox Environments, Seq-Lease (shipped as v0.4.5) · v0.3 Credential Engines (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