Thanks for taking the time to contribute. This doc covers how to get the project running, where things live, and what we expect from pull requests.
# Prerequisites: Node >= 22, pnpm >= 10
git clone https://github.com/light-cloud-com/ice.git
cd ice
pnpm install
pnpm schemas:build # Generate provider schemas (~10-15 min first time)
pnpm dev:all # Web on localhost:5173, gateway on 15173
# or
pnpm dev:desktop # Electron appSee README.md for the full tree. The short version:
packages/core- graph engine, schemas, deploy translatorpackages/blocks- cloud resource block definitions (AWS/GCP/Azure/K8s)packages/ui- React components (canvas, panels, palette, AI chat)packages/web- Vite web app shellpackages/providers/{gcp,aws,azure}- per-cloud deployer implementationsservices/{canvas,deploy,ai,iam,credentials,engine}- backend express routersapps/gateway- composes all servicesapps/desktop- Electron wrapper with embedded gateway
Before opening a PR, run these locally:
pnpm typecheck # TypeScript across all packages
pnpm lint:check # ESLint (errors block; warnings allowed)
pnpm format:check # Prettier
pnpm test:unit # Vitest unit tests
pnpm --filter @ice/web buildCI runs the same commands on every push and PR. We don't ship red builds.
Integration tests that need a live SQLite DB live in **/*.int.test.ts and run separately:
pnpm dev:setup # Create the dev DB once
pnpm test:int # Run integration testsE2E tests use Playwright against a running app:
pnpm test:e2e # Headless
pnpm test:dashboard # Interactive GCP test dashboard at :15200Open an issue using the bug template. Include:
- What you did (ideally a minimal repro)
- What you expected
- What happened (logs, screenshots, stack traces)
- Your OS, Node version, and whether it's the web app or desktop
- The ICE version (
pnpm --filter ice exec node -p "require('./package.json').version")
Security issues: do not open a public issue. See SECURITY.md.
Open an issue using the feature template before writing code. Describe the use case - not the implementation. We'd rather discuss approach once than review a large PR that doesn't fit.
- One logical change per PR. Split refactors from behaviour changes.
- Commit messages: use imperative mood ("Add X", not "Added X"). Conventional Commits (
feat:,fix:,refactor:,docs:) are welcome but not required. - Rebase on
mainbefore opening a PR. We merge with squash by default. - Keep the diff focused. If you notice unrelated cleanup, open a separate PR.
- Add tests for new behaviour. Bug fixes should include a regression test.
- Don't regress CI. If your change touches something CI doesn't cover, add coverage in the same PR.
- Features without a clear user problem ("might be useful someday").
- Rewrites of working code without a behavioural reason.
- Dependencies added for a single one-liner.
- Anything that weakens the Electron security model (nodeIntegration, contextIsolation, sandbox).
ICE is released under the MIT License — free and open source, for any use including commercial. By contributing, you agree that your contribution will be licensed under the same terms. No separate CLA is required.
See CODE_OF_CONDUCT.md. Short version: be kind, call out behaviour not people.