fix(quickstart): make README cp-paste flow bugless end-to-end (#1871 )

Reproducing the README's quickstart on a clean clone surfaced seven
independent bugs between `git clone` and seeing the Canvas in a browser.
Each fix is minimal and local-dev-only — the SaaS/EC2 provisioner path
(issue #1822) is untouched.

Bugs fixed:

1. `infra/scripts/setup.sh` applied migrations via raw psql, bypassing
   the platform's `schema_migrations` tracker. The platform then re-ran
   every migration on first boot and crashed on non-idempotent ALTER
   TABLE statements (e.g. `036_org_api_tokens_org_id.up.sql`). Dropped
   the migration block — `workspace-server/internal/db/postgres.go:53`
   already tracks and skips applied files.

2. `.env.example` shipped `DATABASE_URL=postgres://USER:PASS@postgres:...`
   with literal `USER:PASS` placeholders and the Docker-internal hostname
   `postgres`. A `cp .env.example .env` followed by `go run ./cmd/server`
   on the host failed with `dial tcp: lookup postgres: no such host`.
   Replaced with working `dev:dev@localhost:5432` defaults that match
   `docker-compose.infra.yml`.

3. `docker-compose.infra.yml` and `docker-compose.yml` set
   `CLICKHOUSE_URL: clickhouse://...:9000/...`. Langfuse v2 rejects
   anything other than `http://` or `https://`, so the container
   crash-looped and returned HTTP 500. Switched to
   `http://...:8123` (HTTP interface) and added `CLICKHOUSE_MIGRATION_URL`
   for the migration-time native-protocol connection. Also removed
   `LANGFUSE_AUTO_CLICKHOUSE_MIGRATION_DISABLED` so migrations actually
   run.

4. `canvas/package.json` dev script crashed with `EADDRINUSE :::8080`
   when `.env` was sourced before `npm run dev` — Next.js reads `PORT`
   from env and the platform owns 8080. Pinned `dev` to
   `-p 3000` so sourced env can't hijack it. `start` left as-is because
   production `node server.js` (Dockerfile CMD) must respect `PORT`
   from the orchestrator.

5. README/CONTRIBUTING told users to clone `Molecule-AI/molecule-monorepo`
   — that repo 404s; the actual name is `molecule-core`. The Railway
   and Render deploy buttons had the same broken URL. Replaced in both
   English and Chinese READMEs and in CONTRIBUTING. Internal identifiers
   (Go module path, Docker network `molecule-monorepo-net`, Python helper
   `molecule-monorepo-status`) deliberately left alone — renaming those
   is an invasive refactor orthogonal to this fix.

6. README quickstart was missing `cp .env.example .env`. Users who went
   straight from `git clone` to `./infra/scripts/setup.sh` got a script
   that warned about an unset `ADMIN_TOKEN` (harmless) but then couldn't
   run the platform without figuring out the env setup on their own.
   Added the step in both READMEs and CONTRIBUTING. Deliberately NOT
   generating `ADMIN_TOKEN`/`SECRETS_ENCRYPTION_KEY` here — the e2e-api
   suite (`tests/e2e/test_api.sh`) assumes AdminAuth fallback mode
   (no server-side `ADMIN_TOKEN`), which is how CI runs it.

7. CI shellcheck only covered `tests/e2e/*.sh` — `infra/scripts/setup.sh`
   is in the critical path of every new-user onboarding but was never
   linted. Extended the `shellcheck` job and the `changes` filter to
   cover `infra/scripts/`. `scripts/` deliberately excluded until its
   pre-existing SC3040/SC3043 warnings are cleaned up separately.

Verification (fresh nuke-and-rebuild following the updated README):

- `docker compose -f docker-compose.infra.yml down -v` + `rm .env`
- `cp .env.example .env` → defaults work as-is
- `bash infra/scripts/setup.sh` — clean, no migration errors, all 6
  infra containers healthy
- `cd workspace-server && go run ./cmd/server` — "Applied 41 migrations
  (0 already applied)", platform on :8080/health 200
- `cd canvas && npm install && npm run dev` — Canvas on :3000/ 200
  even with `.env` sourced (PORT=8080 in env)
- `bash tests/e2e/test_api.sh` — **61 passed, 0 failed**
- `cd canvas && npx vitest run` — **900 tests passed**
- `cd canvas && npm run build` — production build clean
- `shellcheck --severity=warning infra/scripts/*.sh` — clean
- Langfuse `/api/public/health` 200 (was 500)

Scope notes:

- SaaS/EC2 parity (issue #1822): all files touched here are local-dev
  surface. Canvas container uses `node server.js` with `ENV PORT=3000`
  in `canvas/Dockerfile` — the `-p 3000` pin in `package.json` dev
  script only affects `npm run dev`, not the production CMD.
- Test coverage (issue #1821): project policy is tiered coverage floors,
  not a blanket 100% target. Files touched here are shell scripts,
  YAML, Markdown, and one package.json script — not classes covered
  by the coverage matrix.
- No overlap with open PRs — searched `setup.sh`, `quickstart`,
  `langfuse`, `clickhouse`, `migration`, `README`; nothing conflicts.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: molecule-ai[bot] <276602405+molecule-ai[bot]@users.noreply.github.com>

2026-04-23 19:53:43 +00:00

4.1 KiB

Raw Blame History

Contributing to Molecule AI

Thanks for your interest in contributing to Molecule AI! This guide covers the development workflow, conventions, and how to get your changes merged.

Getting Started

Prerequisites

Go 1.25+ — platform backend
Node.js 20+ — canvas frontend
Python 3.11+ — workspace runtime
Docker — infrastructure services (Postgres, Redis)
Git — with hooks path set to .githooks

Setup

# Clone the repo
git clone https://github.com/Molecule-AI/molecule-core.git
cd molecule-core

# Install git hooks
git config core.hooksPath .githooks

# Copy and edit .env (generate ADMIN_TOKEN + SECRETS_ENCRYPTION_KEY)
cp .env.example .env

# Start infrastructure (Postgres, Redis, Langfuse, Temporal)
./infra/scripts/setup.sh

# Build and run the platform — applies pending migrations on first boot
cd workspace-server
go run ./cmd/server

# In a separate terminal, run the canvas
cd canvas
npm install
npm run dev

Environment Variables

Copy .env.example to .env and fill in your values:

cp .env.example .env

See CLAUDE.md for a full list of environment variables and their purposes.

Development Workflow

Branch Naming

Use prefixed branches:

feat/ — new features
fix/ — bug fixes
chore/ — maintenance, deps, CI
docs/ — documentation only

Never push directly to main. All changes go through pull requests.

Commits

Write concise commit messages that focus on the "why":

fix(canvas): prevent infinite re-render on WebSocket reconnect

The useEffect dependency array included the entire nodes object,
causing a render loop when any node position changed.

Pull Requests

Keep PRs focused — one concern per PR
Include a test plan in the PR description
PRs are merged with merge commits (not squash or rebase)

Running Tests

# Go (platform)
cd workspace-server && go test -race ./...

# Canvas (Next.js)
cd canvas && npm test

# Workspace runtime (Python)
cd workspace && python -m pytest -v

# E2E API tests (requires running platform)
bash tests/e2e/test_api.sh

Pre-commit Hooks

The .githooks/pre-commit hook enforces:

'use client' directive on React hook files
Dark theme only (no white/light CSS classes)
No SQL injection patterns (fmt.Sprintf with SQL)
No leaked secrets (sk-ant-, ghp_, AKIA)

Fix violations before committing — the hook will reject the commit.

CI Pipeline

CI runs on GitHub Actions with a self-hosted runner. External contributors: PRs from forks will not trigger CI automatically. A maintainer will review and run CI manually.

Job	What it checks
platform-build	Go build + vet + `go test -race`
canvas-build	npm build + vitest
python-lint	pytest with coverage
e2e-api	Full API test suite (62 tests)
shellcheck	Shell script linting

Code Style

Go (Platform)

Standard gofmt formatting
go vet must pass
No fmt.Sprintf in SQL queries (use parameterized queries)
Prefer function injection over import cycles

TypeScript (Canvas)

Strict mode enabled
No any types (use unknown or proper types)
Use ConfirmDialog component, never native confirm/alert/prompt
Dark theme only — no white/light CSS classes

Python (Workspace Runtime)

Type hints on public functions
pytest for all tests

Architecture Overview

See CLAUDE.md for detailed architecture documentation, including:

Component diagram (Platform, Canvas, Workspace Runtime)
Key architectural patterns
Database schema and migrations
API route reference

Reporting Issues

Use GitHub Issues with a clear title and reproduction steps. Include:

What you expected
What actually happened
Platform/OS version
Relevant logs or screenshots

Security

If you discover a security vulnerability, please report it privately via GitHub Security Advisories rather than opening a public issue.

License

By contributing, you agree that your contributions will be licensed under the same Business Source License 1.1 that covers this project.

4.1 KiB Raw Blame History