ForgeCAD Development

This is the private development repository for ForgeCAD.

The public/community README lives in public-kit/README.md. That file is copied to the root README.md of forgecad-public-kit during the public sync, so keep user-facing overview, install, examples, benchmarks, and community positioning there.

Use this README for local development notes only.

Start Here

npm install
npm link
forgecad dev examples

Then open http://localhost:5173.

forgecad dev examples opens the local examples project with live reload, so you can edit and save files immediately.

To check the production studio build locally after npm run build:

forgecad studio examples

Daily Commands

npm run dev              # Vite editor against ./examples
npm run open:homepage    # Vite public homepage/docs preview
npm run dev:studio       # hosted-mode Vite editor, normally with a Daytona API
npm run build:cli        # fast CLI rebuild after CLI/runtime changes
npm run build            # full solver, docs, browser, CLI, skill build
npm test                 # smoke suite
npm run check:suite      # full repo invariant suite
npm run test:unit        # Vitest unit tests
npm run lint             # Biome check

npm run dev is wired for editor work and routes / into the local examples project. Use npm run open:homepage when you need to inspect the public homepage, docs, SEO metadata, or hosted-site routes locally.

npm run build:cli is the fast daily-driver build. Run npm run build when you need the production SPA in dist/, the package artifacts, or a publish-ready build.

Hosted Services

Local development is intentionally editor-first now. For auth, database, projects, sharing, or hosted-app work, use a Daytona sandbox:

bash infra/daytona/start-dev.sh

See docs/internal/daytona-dev.md for the snapshot, bootstrap, tunnel, and teardown workflow. npm run dev:server still exists for manual debugging when PostgreSQL is already running, but the repo no longer ships local Docker Compose development stacks.

New Team Members

For normal code work, start with npm install, npm run dev, and the command list above. Do not use the production deploy SSH account for teammate access; that account has sudo and Docker access.

Getting Production DB Access

Production DB access for teammates is read-only and tunnel-based:

• OS user: per-person restricted user like fcdb_<member>
• SSH access: local port forwarding only, no shell
• DB user: shared PostgreSQL role forgecad_readonly
• Local port: 15432 on the teammate's machine

What the teammate should do:

1. Generate an SSH key and send only the public key to the production operator:

   ssh-keygen -t ed25519 -a 100 -f ~/.ssh/forgecad_prod_db -C "<member>@forgecad-prod-db"

2. After the operator confirms access and shares the read-only DB credential through a password manager, open the tunnel with the exact SSH command the operator gives you. It will look like:

   ssh -i ~/.ssh/forgecad_prod_db -N -L 15432:<postgres-container-ip>:5432 fcdb_<member>@65.108.210.215

3. In another terminal, connect with psql:

   psql "postgresql://forgecad_readonly:<password>@127.0.0.1:15432/forgecad"

What the production operator should do:

1. Ensure the read-only DB role exists:

   npm run prod:db:ro:ensure

2. Create the restricted SSH user from the teammate's public key:

   npm run prod:db:tunnel-user -- <member> --public-key ~/Downloads/<member>.pub

   This creates fcdb_<member> and restricts it to forwarding only to the current Postgres container IP and port. Copy the printed SSH tunnel command for the teammate.

3. Share the forgecad_readonly username/password from .kamal/prod-readonly-db.env through a password manager. Do not send DB credentials or private keys through chat, email, or git.

If the teammate cannot generate their own key, the operator can generate one locally:

npm run prod:db:tunnel-user -- <member>

That writes .kamal/db-tunnel-keys/fcdb_<member>; share that private key only through a password manager. If the Postgres accessory is recreated and receives a new Docker-network IP, rerun npm run prod:db:tunnel-user -- <member> to refresh the SSH PermitOpen target. See docs/internal/deployment.md for the full production DB runbook.

Repo Map

• src/ - browser app, modeling runtime, store, and worker code
• cli/ - forgecad command entrypoint and CLI workflows
• server/ - hosted app API, auth, project storage, and routes
• solver/ - Rust/WASM constraint solver
• examples/ - maintained ForgeCAD model examples
• docs/core-skill/ - installable core skill API/CLI/guide docs (scanned by the skill builder)
• docs/site/ - public website docs source copied into generated docs/mirrored_public/
• docs/internal/ - release, deploy, ops, monetization, product, and contributor docs
• agent-skill-library/ - package source for CLI-shipped companion skills
• .agents/skills/ - repo-local operational and developer skills
• dist-skill/ - generated installable forgecad skill output

Solver Build Note

The solver compiles to WebAssembly via wasm-pack, which needs the Rust wasm32-unknown-unknown target. If the build fails because the target is missing:

rustup target add wasm32-unknown-unknown

If Rust came from Homebrew and cannot add that target, switch to rustup.

Generated Docs And Skills

Refresh generated API docs, CLI docs, the installable skill, and the docs site with:

npm run refresh

For just the core agent skill:

npm run build:skill:forgecad

The agent-skill-library/ directory is the source of truth for companion ForgeCAD workflows shipped by forgecad skill install. Public export is controlled by each skill's forgecad-public: true frontmatter. Repo-local operational and developer skills live under .agents/skills/.

Public Sync

The public repository is /Users/kostard/Projects/CAD/ForgeCAD-public.

public-kit/README.md and public-kit/LICENSE are the root README and license sources for that public repo. The public skill sync copies them to ForgeCAD-public/README.md and ForgeCAD-public/LICENSE, then mirrors the generated core skill and public companion skills:

npm run sync:public-skills -- --list
npm run sync:public-skills

When syncing examples or other public-safe folders manually, follow .agents/skills/sync-forgecad-public/SKILL.md and stage explicit paths only.

Validation

Suggested local validation depends on the change:

npm run test:unit
npm run test:examples
npm run test:compiler
npm run test:brep

For model or API changes, validate representative files directly:

node dist-cli/forgecad.js run examples/api/01-parametric-bracket.forge.js
node dist-cli/forgecad.js check params path/to/file.forge.js --samples 10

Publishing

npm login
npm version patch
npm publish

npm publish runs npm run build through prepublishOnly. Check package contents before publishing with:

npm pack --dry-run

The published package includes dist/, dist-cli/, dist-skill/, examples/, README.md, and LICENSE.

Durable Docs

• API: docs/internal/API/README.md
• CLI: docs/core-skill/CLI.md
• Vision: docs/internal/VISION.md
• Coding notes: .agents/skills/forgecad-dev/references/coding.md
• Skill maintenance: .agents/skills/forgecad-dev/references/skill-maintenance.md

License

ForgeCAD Software License. Personal non-commercial use is free. Human-operated commercial CAD work, including designing models for customers, requires Pro. Automated backend, hosted, embedded, AI training, evaluation, benchmarking, RL environment, or application usage requires Enterprise. Current plan details are at forgecad.io/pricing.