coreci-nextcraft-po
ca08f93eeb
Wave 6-1 multi-persona review (lead-developer): D-100 one-transaction discipline VERIFIED (transition_application = the sole post-creation status writer, R-78 — marketplace store carries no status write; one Session, one commit covering both tables + the application row); R-80 re-hire coherence VERIFIED (rehire = fresh PlacementRow + placement.rehired, never a fabricated application transition; partial-unique guard, the IntegrityError surfaces); G-319 pin split VERIFIED (own-postings list counts-only, test_postings_read.py negative PII assertion unchanged); D-110 wire pins VERIFIED (placement.ts mirrors placements/base.py field-for-field + status-union, pinned in pins.test.ts); D-092 census VERIFIED (the overview mock block replaced by real placements; talent mocks retained + honestly labeled; no fake-converted surface). Zero P0s. Security-auditor pass: no credentials/identity PII on any log or asset path (learner_id an opaque handle everywhere, R-79); gate orders pinned per principal class (employer session->claim->entitlement; admin token; learner allowlist->verified-18+->data); the ledger no-delete path intact (R-70); tamper/fork/concurrency arms green; export determinism + the G-321 methodology honesty re-verified; no secret echoed by any exception path. Clean. P1 findings, dispositioned with recorded follow-ups (never loop back to EXECUTE): (1) PLAN Must-Haves names tests/placements/test_e2e_audit.py but the D-111 E2E proof lives as tests/placements/test_export.py:: test_e2e_audit_proof — doc-path drift, substance verified green; (2) the D-112 addition census omits employers/store.py L64-70 (the two-line _AUDIT_EVENT_KINDS "application" vocabulary addition, P2 REQ-11-002 audit lane — in-scope, the census text incomplete). Wave 6-2 audit (D-112 reconstruction): 27 branch commits vs the .census — 18 added + 23 changed files, all placement-surface-scoped (+ the .ciagent process set, README/deploy doc rows); feat commits scoped to the placement surface; the two same-cycle CI red triages + the disclosed probe.txt pair on main accounted. PASS. ---ci--- phase: 6 milestone: v0.11 status: ship_pending ---/ci---
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 targetshttp://<your-host>:8420automatically (derived from the browser's hostname). - CORS admits any origin (
AI_CORS_ORIGINS=*inapps/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.1inapps/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_FLOODEDare 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