Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

feat: interactive setup for try it, develop, and env generation (#314)

Croffcdc8e15052f6
diff --git a/.env.test.example b/.env.test.example
index 98d37968..3b2e0d87 100644
--- a/.env.test.example
+++ b/.env.test.example
@@ -1,6 +1,7 @@
# ─────────────────────────────────────────────────────────────
# Environment for the API test suite (bun test). Separate from .env so tests
-# never touch the dev database. Copy to .env.test: cp .env.test.example .env.test
+# never touch the dev database. `bun run setup` writes this file, creates the
+# test database, and migrates it; copy it by hand only to set it up yourself.
#
# The tests are integration tests: they run the real Elysia app against a real
# Postgres and create real better-auth sessions. Point DATABASE_URL at a
@@ -8,11 +9,11 @@
# tests, so it must never point at the dev or prod database.
# ─────────────────────────────────────────────────────────────
-# Dedicated test database on the local dev Postgres (docker-compose.dev.yml).
-# The name must contain "test" — the reset helper refuses to run otherwise.
-# Match the host/port/credentials of your dev DB; only the database name differs.
-# Use the same POSTGRES_PORT as your dev DB (5433 if 5432 is taken — see root .env).
-DATABASE_URL=postgres://vela:vela@localhost:5433/vela_test
+# Dedicated test database next to the dev one on the same Postgres
+# (docker-compose.dev.yml). The name must contain "test" — the reset helper
+# refuses to run otherwise. Host, port and credentials match the dev database
+# in the root .env; only the database name differs.
+DATABASE_URL=postgres://itsaplan:itsaplan@localhost:5432/itsaplan_test
# better-auth. Any fixed value works for a throwaway test DB.
BETTER_AUTH_SECRET=test-secret-not-for-production-use-only
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1d490267..16632b73 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -45,6 +45,9 @@ jobs:
- name: Typecheck
run: bun run typecheck
+ - name: Script tests
+ run: bun test scripts/
+
build:
name: Build apps
runs-on: ubuntu-latest
diff --git a/AGENTS.md b/AGENTS.md
index 48cd84c2..6f23e459 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -99,19 +99,53 @@ directly** — it talks to the API over HTTP (better-auth client + fetch).
| `bun run db:generate` | generate SQL migrations from Drizzle schema |
| `bun run db:migrate` | apply migrations |
| `bun run db:migrate:test` | apply migrations to the test DB (`.env.test`) |
+| `bun run setup` | interactive setup: try it, develop, or generate env |
| `bun run auth:generate` | regenerate better-auth tables → `packages/db/src/schema/auth.ts` |
## First run
```bash
bun install
-cp .env.example .env && cp apps/web/.env.example apps/web/.env
-# set BETTER_AUTH_SECRET in .env: openssl rand -base64 32
-docker compose -f docker-compose.dev.yml up -d # dev Postgres + MinIO
-bun run db:migrate # apply migrations
-bun run dev # api :3000 + web :3001
+bun run setup # pick "Develop" — see the table below
+bun run dev # api :3000 + web :3001
```
+`bun run setup` (`scripts/setup.ts`, `@clack/prompts`) asks what to set up and does the rest:
+
+| Answer | What it does |
+| ------- | ---------------------------------------------------------------------------------------- |
+| Try it | generates the secrets, `docker compose up -d`, opens the localhost URL in the browser |
+| Develop | `.env`, `apps/web/.env`, `.env.test`, dev compose, the `*_test` database, both migrations |
+| Generate env | builds `.env` and `apps/web/.env` from the examples, walks every value, then writes both or prints them instead; starts nothing |
+
+Self-hosting behind a domain is a manual `.env` and `docker compose up -d`, documented in
+`docs/self-hosting.md` — the script only covers the local cases.
+
+Running it again on a live instance does not damage it, and the rules that make that true
+are the part to preserve when changing the script:
+
+- Try it and Develop restart what is already up rather than setting up beside it, and each
+ offers to stop the other: they read the same `.env`, so they publish the same api and web
+ ports. Develop also offers to stop the PR stack, whose MinIO ports are fixed in its own
+ compose file. A refusal ends the run and changes nothing.
+- A busy port is offered for change, never forced. The check connects rather than binds, to
+ `127.0.0.1` and `::1`: on macOS a bind on one loopback address succeeds beside a listener
+ on the other, so a native Postgres and a container published on the wildcard both read as
+ free.
+- Postgres reads `POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_DB` once, when it
+ initialises its volume, and the secrets are what the instance stored its data under. So a
+ value is only generated while that volume does not exist, and one that already holds a
+ real value is kept in every case. Generate env, which always produces a fresh set, asks a
+ second time before it overwrites an existing `.env`.
+- Both check that the running database accepts the credentials `.env` holds before starting
+ the api, which would otherwise fail its healthcheck on the mismatch; a refusal is named,
+ and `down -v` offered behind a confirmation that says the data goes with it. Develop also
+ checks from the host that something answers on the Postgres port `.env` names — a
+ container keeps the port it started with, so one that was not recreated publishes the old
+ one and the migrations reach nothing.
+- The setup migrates through `packages/db/src/migrate.ts`, not `bun run db:migrate`:
+ drizzle-kit exits 1 without printing what the database refused.
+
## Environment
- Root `.env` (copy from `.env.example`) feeds api, drizzle, and docker-compose.
@@ -121,8 +155,8 @@ bun run dev # api :3000 + web :3001
its process at **startup**, never through `NEXT_PUBLIC_*`, which `next build` would inline
into the bundle and pin the image to one instance.
- Local dev DB: `docker compose -f docker-compose.dev.yml up -d` (the deploy composes do
- NOT publish the DB port). **Host 5432 is often taken** → use `POSTGRES_PORT=5433` and set
- `DATABASE_URL=...localhost:5433...` in `.env`.
+ NOT publish the DB port). Host 5432 is often taken; `bun run setup` finds a free port and
+ writes both `POSTGRES_PORT` and `DATABASE_URL`.
- A new environment variable belongs in `.env.example` and, if a service needs it, in the
compose files.
@@ -158,7 +192,7 @@ completed), runs the suite, and exits with its code. It does not use
`--abort-on-container-exit`, which tears the stack down the moment the one-shot
`minio-test-init` exits, before api-test starts.
-The test database is created by the `postgres-test` service (`POSTGRES_DB=vela_test`,
+The test database is created by the `postgres-test` service (`POSTGRES_DB=itsaplan_test`,
tmpfs — nothing persists). The `test` job in `.github/workflows/ci.yml` runs these
same commands.
diff --git a/README.md b/README.md
index 6ffcdab4..3b9a50c4 100644
--- a/README.md
+++ b/README.md
@@ -29,17 +29,12 @@ If It's a Plan looks useful to you, star the repo ⭐ — it helps other people
It's a Plan is a full issue tracker on its own: projects, boards, cycles, custom fields,
and dashboards. Use it that way and never turn on a single agent.
-Add agents when you need them. An agent gets a role, permissions, and an assignee slot, and
-it takes issues on the same board as your people. You run all of it on your own server, on
-your own database.
-
-- **Own your stack.** Your server, your database, your API keys. No per-seat fees, no lock-in.
-- **Agents as teammates.** Give one a model, a prompt, skills, and tools, then assign it an issue.
-- **Any model.** Internal agents take a key from any of 150+ providers, or a local endpoint.
-- **Your coding CLI.** External agents run on your machine: Claude Code, Codex, Antigravity,
- Copilot CLI, opencode.
-- **One board for both.** A run starts on an @mention, an assignment, or a schedule.
-- **Automate anything.** Everything the UI does is a REST API call, an MCP tool, or a webhook.
+**The difference: AI agents work here like any teammate.** An agent gets a role,
+permissions, and an assignee slot, and takes issues on the same board as your people.
+
+It fits any kind of work: software development, marketing, design, support, sales,
+operations, research. You run all of it on your own server, on your own database, with your
+own API keys — no per-seat fees, no lock-in.
It's a Plan is under active development. Expect breaking changes before the first stable
release.
@@ -48,9 +43,15 @@ release.
1. **Star the repo** if you think more people should see it. That is the whole cost, and it
is what makes the project findable.
-2. **Contribute.** Issues, bug reports, and pull requests are all welcome — start with
+2. **Share it** — post it on social media or send it to a colleague who runs a team or
+ writes code. One link reaches people search never will.
+3. **Contribute.** Issues, bug reports, and pull requests are all welcome — start with
[CONTRIBUTING.md](CONTRIBUTING.md).
-3. **Donate.** Any amount helps the project grow and keeps the work going.
+4. **Donate.** Any amount helps the project grow and keeps the work going. A donation can
+ also move a feature up the roadmap — ask on [Telegram](https://telegram.me/croffasia).
+
+ <details>
+ <summary>Wallet addresses</summary>
| Network | Address |
| ------- | ------- |
@@ -58,12 +59,18 @@ release.
| USDT (TON) | `UQBTE0qA7ZPKOkjbrCyqVopXFKNbbcDd-RcKeR9wkoyAjNb4` |
| USDT (TRC-20) | `TMSdmfoEVkC4sA1ejmhimcZC4eSremmkjV` |
-A commercial licence is available if AGPL-3.0 does not fit your company, and a feature can
-be moved up the roadmap. Ask on [Telegram](https://telegram.me/croffasia).
+ </details>
## Features
-**Tracking**
+| Area | What you get |
+| --------- | ------------------------------------------------------------------------------------- |
+| Product management | Kanban, table, timeline, and calendar views · cycles · custom fields · dashboards · docs · notes boards |
+| AI agents | Agents as project members · internal on any model, or external on your coding CLI · runs start on an @mention, an assignment, or a schedule |
+| Platform | REST API with OpenAPI · MCP server · webhooks · pull requests from 5 forges · passkeys and Google sign-in · 6 languages |
+
+<details>
+<summary><b>Product management</b> — the full list</summary>
- Configure issues per project: custom fields, labels, states, and issue types
- Kanban, table, timeline, and calendar views. Save each one as a tab with its own filters,
@@ -73,12 +80,17 @@ be moved up the roadmap. Ask on [Telegram](https://telegram.me/croffasia).
- Comment threads with replies, and @username mentions of people and agents
- Configurable dashboards for project analytics: throughput, breakdown, pulse
- Quick actions that run on an issue, and auto-assignment when an issue moves into a state
+- Docs: shared Markdown pages in a tree, with revision history, private and locked pages,
+ favorites, embedded files, and links to the issues they describe
- Freeform notes boards: sticky notes on a canvas, with colors, checklists, and connections
- Share a view or an issue by public link, read-only and without sign-in
- Initiatives that group and track related work inside a project
- Auto-archive, a notification inbox, role-based access control, and more
-**AI agents**
+</details>
+
+<details>
+<summary><b>AI agents</b> — the full list</summary>
- Agents as project members, with their own permissions and assigned issues
- Internal agents run on the instance. Configure the model, system prompt, tools, and
@@ -94,7 +106,10 @@ be moved up the roadmap. Ask on [Telegram](https://telegram.me/croffasia).
- Chat with an external agent too. The runner answers from your machine, streams the reply
and its tool calls, and resumes the same coding agent session on each message
-**Platform**
+</details>
+
+<details>
+<summary><b>Platform</b> — the full list</summary>
- REST API with an OpenAPI reference and API keys
- MCP server, so an external assistant can read and change issues through the same API
@@ -106,6 +121,8 @@ be moved up the roadmap. Ask on [Telegram](https://telegram.me/croffasia).
- Interface in English, Ukrainian, Russian, Simplified Chinese, Arabic, and French
- Instance administration: storage limits, mail transport, and instance-wide settings
+</details>
+
## Getting started
### Deploy on Railway — recommended
@@ -116,20 +133,22 @@ The whole stack in one click, with no server to maintain. You give Railway two h
and it generates every secret. You need a domain of your own: [the guide](docs/railway.md)
explains why, and what to do after the deploy.
-### Run it on your own server
+### Try it on your machine
-Requirements: Docker and a domain behind a TLS-terminating reverse proxy.
+Requirements: Docker and [Bun](https://bun.sh).
```bash
git clone https://github.com/croffasia/itsaplan.git
cd itsaplan
-cp .env.example .env # set API_URL, APP_URL, and the secrets
-docker compose up -d
+bun install
+bun run setup # answer "Try it"
```
-This starts Postgres, MinIO, and the four services (api, worker, bot, web) from the images
-published on each release. Add `--build` to build them from the checkout instead. The first
-account you register becomes the instance admin.
+It picks free ports, generates the secrets, starts the whole stack in Docker, and opens
+<http://localhost:3001>. Everything runs on localhost, so no domain and no reverse proxy are
+needed. Run it again later to restart the instance; the data stays.
+
+### Everything else
- [Deploy on Railway](docs/railway.md) — one-click hosted deploy from the template
- [Self-hosting](docs/self-hosting.md) — the full production setup, secrets, and updates
@@ -172,3 +191,6 @@ Copyright © 2026 Andrii Poluosmak.
[AGPL-3.0](LICENSE), except `packages/runner`, which is
[Apache-2.0](packages/runner/LICENSE).
+
+A commercial licence is available if AGPL-3.0 does not fit your company. Ask on
+[Telegram](https://telegram.me/croffasia).
diff --git a/apps/api/AGENTS.md b/apps/api/AGENTS.md
index 2e11f13d..ab1ccbd0 100644
--- a/apps/api/AGENTS.md
+++ b/apps/api/AGENTS.md
@@ -159,7 +159,8 @@ nosniff`, forced download outside a strict media allowlist, locked-down CSP.
and real better-auth sessions — nothing is mocked. Import `app` via the helpers (from
`src/app.ts`), never `src/index.ts` (it binds the port).
-**Setup.** Point tests at a dedicated `*_test` database, never dev/prod:
+**Setup.** `bun run setup` at the repo root creates the `*_test` database next to the dev
+one, writes `.env.test`, and migrates it. To do it by hand instead:
```bash
cp .env.test.example .env.test # repo root; DATABASE_URL must name a *_test database
diff --git a/bun.lock b/bun.lock
index 249a5a75..687c3feb 100644
--- a/bun.lock
+++ b/bun.lock
@@ -5,7 +5,9 @@
"": {
"name": "dev-plane",
"devDependencies": {
+ "@clack/prompts": "^1.7.0",
"@repo/eslint-config": "workspace:*",
+ "@types/bun": "^1.4.1",
"eslint": "^9.39.0",
"lefthook": "^2.1.10",
"prettier": "3.9.6",
@@ -393,6 +395,10 @@
"@bramus/specificity": ["@bramus/[email protected]", "", { "dependencies": { "css-tree": "^3.0.0" }, "bin": { "specificity": "bin/cli.js" } }, "sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw=="],
+ "@clack/core": ["@clack/[email protected]", "", { "dependencies": { "fast-wrap-ansi": "^0.2.0", "sisteransi": "^1.0.5" } }, "sha512-/kr3UWNtdJfxZtPgDqUOmG2pvwlmcLGheex5yiZKdwbzZJxhV+HMNR9QNmyY5cGwTNV6LrR7Jtp+KjhUAP1qBQ=="],
+
+ "@clack/prompts": ["@clack/[email protected]", "", { "dependencies": { "@clack/core": "1.4.3", "fast-string-width": "^3.0.2", "fast-wrap-ansi": "^0.2.0", "sisteransi": "^1.0.5" } }, "sha512-y7/yvZ2TPAnR9+jnc00klvNNLkJiXFFrQA/hlLCcxA9a2A4zQIOimyFQ9XfwYKiGD1fb5GY8vbKIIgO8d5Tb2A=="],
+
"@codemirror/autocomplete": ["@codemirror/[email protected]", "", { "dependencies": { "@codemirror/language": "^6.0.0", "@codemirror/state": "^6.0.0", "@codemirror/view": "^6.17.0", "@lezer/common": "^1.0.0" } }, "sha512-tlosUqb+3BbxCxZdu4tKeRghPFC+QM7q4X5YhKV2eCmPG+1r2F3f4AaSz5sCrFqUtX4Jh20VFTKecl16MgiV9g=="],
"@codemirror/commands": ["@codemirror/[email protected]", "", { "dependencies": { "@codemirror/language": "^6.0.0", "@codemirror/state": "^6.7.0", "@codemirror/view": "^6.27.0", "@lezer/common": "^1.1.0" } }, "sha512-Ryk9y9T0FFVF0cUGhAknveAyUOl/A1qReTFi+qPKtOh2Z9F4AUBz3XOrYD4ZEgZirdugVzHvd/2/Wcwy5OliTg=="],
@@ -1175,7 +1181,7 @@
"@turbo/windows-arm64": ["@turbo/[email protected]", "", { "os": "win32", "cpu": "arm64" }, "sha512-W2Ub165Qv0iMFljbYKxxbZN+2dVSngnzEjQNEFXtnz5oJVx9XSypmNmUvMtuYMeZ3kdVC1zI7yd/rtuX+SDnbg=="],
- "@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+ "@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.4.1" } }, "sha512-0AVGiTXGajf1rgKom3N+c5L7CBxuoyyv1i44M0nX4UDK0G/fnRAMiri93nHuVPIb429KKtAgj7HatVmmOjeQLA=="],
"@types/d3-array": ["@types/[email protected]", "", {}, "sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw=="],
@@ -1443,7 +1449,7 @@
"buffers": ["[email protected]", "", {}, "sha512-9q/rDEGSb/Qsvv2qvzIzdluL5k7AaJOTrw23z9reQthrbF7is4CtlT0DXyO1oei2DCp4uojjzQ7igaSHp1kAEQ=="],
- "bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+ "bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-loKuVrAFZKfEv+JvWkHRS9GW5IqLuLRjVXN9p+vZvBN86O5hf/pBZQ5hSoyipsrMmWObZBDvWnlmKvjKTM0PdA=="],
"bytes": ["[email protected]", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
@@ -1725,8 +1731,14 @@
"fast-levenshtein": ["[email protected]", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],
+ "fast-string-truncated-width": ["[email protected]", "", {}, "sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g=="],
+
+ "fast-string-width": ["[email protected]", "", { "dependencies": { "fast-string-truncated-width": "^3.0.2" } }, "sha512-gX8LrtNEI5hq8DVUfRQMbr5lpaS4nMIWV+7XEbXk2b8kiQIizgnlr12B4dA3ZEx3308ze0O4Q1R+cHts8kyUJg=="],
+
"fast-uri": ["[email protected]", "", {}, "sha512-i70LwGWUduXqzicKXWshooq+sWL1K3WUU5rKZNG/0i3a1OSoX3HqhH5WbWwTmqWfor4urUakGPiRQcleRZTwOg=="],
+ "fast-wrap-ansi": ["[email protected]", "", { "dependencies": { "fast-string-width": "^3.0.2" } }, "sha512-7F2Fl+TjRSenLqlU3UjSH0iyqopqoZIu7eZVpEirP2g1GtWa2G/ecEmBdgz31+Mxr+ELclgg6sokpSFIQiZ02Q=="],
+
"fastq": ["[email protected]", "", { "dependencies": { "reusify": "^1.0.4" } }, "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw=="],
"fdir": ["[email protected]", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
@@ -2611,6 +2623,8 @@
"signal-exit": ["[email protected]", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="],
+ "sisteransi": ["[email protected]", "", {}, "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg=="],
+
"sonner": ["[email protected]", "", { "peerDependencies": { "@types/react": "^18.0.0 || ^19.0.0", "react": "^18.0.0 || ^19.0.0 || ^19.0.0-rc", "react-dom": "^18.0.0 || ^19.0.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-UM/ByIoFra8yzV75n1o0Puu0bw5U/9UNnDacrJNspekBewIfsQ3D6ez1nvlWpt7aTsO6rujQtifBpycwIivqlg=="],
"source-map": ["[email protected]", "", {}, "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g=="],
@@ -2937,6 +2951,8 @@
"@formatjs/ecma402-abstract/@formatjs/intl-localematcher": ["@formatjs/[email protected]", "", { "dependencies": { "tslib": "^2.8.0" } }, "sha512-XOMO2Hupl0wdd172Y06h6kLpBz6Dv+J4okPLl4LPtzbr8f66WbIoy4ev98EBuZ6ZK4h5ydTN6XneT4QVpD7cdA=="],
+ "@itsaplan/runner/@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
"@mastra/core/ajv": ["[email protected]", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA=="],
"@mastra/core/ignore": ["[email protected]", "", {}, "sha512-BAg6QkE8W+TuQLrrw0Ugr7HegXduRuuj8/ti2kSOc+jz1dmx8/WNcjr6XGnq5YpDWxFwwaavqD0+jIUOKelTsw=="],
@@ -2945,18 +2961,6 @@
"@reduxjs/toolkit/reselect": ["[email protected]", "", {}, "sha512-K/BG6eIky/SBpzfHZv/dd+9JBFiS4SWV7FIujVyJRux6e45+73RaUHXLmIR1f7WOMaQ0U1km6qwklRQxpJJY0w=="],
- "@repo/agent-tools/@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.4.1" } }, "sha512-0AVGiTXGajf1rgKom3N+c5L7CBxuoyyv1i44M0nX4UDK0G/fnRAMiri93nHuVPIb429KKtAgj7HatVmmOjeQLA=="],
-
- "@repo/auth/@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.4.1" } }, "sha512-0AVGiTXGajf1rgKom3N+c5L7CBxuoyyv1i44M0nX4UDK0G/fnRAMiri93nHuVPIb429KKtAgj7HatVmmOjeQLA=="],
-
- "@repo/crypto/@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.4.1" } }, "sha512-0AVGiTXGajf1rgKom3N+c5L7CBxuoyyv1i44M0nX4UDK0G/fnRAMiri93nHuVPIb429KKtAgj7HatVmmOjeQLA=="],
-
- "@repo/db/@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.4.1" } }, "sha512-0AVGiTXGajf1rgKom3N+c5L7CBxuoyyv1i44M0nX4UDK0G/fnRAMiri93nHuVPIb429KKtAgj7HatVmmOjeQLA=="],
-
- "@repo/mailer/@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.4.1" } }, "sha512-0AVGiTXGajf1rgKom3N+c5L7CBxuoyyv1i44M0nX4UDK0G/fnRAMiri93nHuVPIb429KKtAgj7HatVmmOjeQLA=="],
-
- "@repo/net/@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.4.1" } }, "sha512-0AVGiTXGajf1rgKom3N+c5L7CBxuoyyv1i44M0nX4UDK0G/fnRAMiri93nHuVPIb429KKtAgj7HatVmmOjeQLA=="],
-
"@scalar/agent-chat/@scalar/helpers": ["@scalar/[email protected]", "", {}, "sha512-IAfnpIZnXY6ni+zyFMwWHBa5b/7yr4mCSvoTGR84oS9q4Quy2wjgafnr7CyfL65ney3iilBZHigZYLYqdqCu3Q=="],
"@scalar/api-client/@scalar/helpers": ["@scalar/[email protected]", "", {}, "sha512-IAfnpIZnXY6ni+zyFMwWHBa5b/7yr4mCSvoTGR84oS9q4Quy2wjgafnr7CyfL65ney3iilBZHigZYLYqdqCu3Q=="],
@@ -3045,15 +3049,13 @@
"ajv-formats/ajv": ["[email protected]", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA=="],
- "api/@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.4.1" } }, "sha512-0AVGiTXGajf1rgKom3N+c5L7CBxuoyyv1i44M0nX4UDK0G/fnRAMiri93nHuVPIb429KKtAgj7HatVmmOjeQLA=="],
-
"archiver-utils/readable-stream": ["[email protected]", "", { "dependencies": { "core-util-is": "~1.0.0", "inherits": "~2.0.3", "isarray": "~1.0.0", "process-nextick-args": "~2.0.0", "safe-buffer": "~5.1.1", "string_decoder": "~1.1.1", "util-deprecate": "~1.0.1" } }, "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA=="],
"better-call/@better-auth/utils": ["@better-auth/[email protected]", "", { "dependencies": { "@noble/hashes": "^2.0.1" } }, "sha512-BL8W4EfIZFwlu0r54m3v1ztjDhu6dDe/amLTm0xybmbZaNgYUqhD3SjpAsnq0q8YD6/ki4iwIgxJNLP/N3TxiA=="],
"body-parser/content-type": ["[email protected]", "", {}, "sha512-j/O/d7GcZCyNl7/hwZAb606rzqkyvaDctLmckbxLzHvFBzTJHuGEdodATcP3yIRoDrLHkIATJuvzbFlp/ki2cQ=="],
- "bun-types/@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q=="],
+ "bot/@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
"chat/@workflow/serde": ["@workflow/[email protected]", "", {}, "sha512-8kkeoQKLDaKXefjV5dbhBj2aErfKp1Mc4pb6tj8144cF+Em5SPbyMbyLCHp+BVrFfFVCBluCtMx+jjvaFVZGww=="],
@@ -3155,8 +3157,6 @@
"which-builtin-type/isarray": ["[email protected]", "", {}, "sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw=="],
- "worker/@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.4.1" } }, "sha512-0AVGiTXGajf1rgKom3N+c5L7CBxuoyyv1i44M0nX4UDK0G/fnRAMiri93nHuVPIb429KKtAgj7HatVmmOjeQLA=="],
-
"zip-stream/archiver-utils": ["[email protected]", "", { "dependencies": { "glob": "^7.2.3", "graceful-fs": "^4.2.0", "lazystream": "^1.0.0", "lodash.defaults": "^4.2.0", "lodash.difference": "^4.5.0", "lodash.flatten": "^4.4.0", "lodash.isplainobject": "^4.0.6", "lodash.union": "^4.6.0", "normalize-path": "^3.0.0", "readable-stream": "^3.6.0" } }, "sha512-KVgf4XQVrTjhyWmx6cte4RxonPLR9onExufI1jhvw/MQ4BB6IsZD5gT8Lq+u/+pRkWna/6JoHpiQioaqFP5Rzw=="],
"@ai-sdk/vue/@ai-sdk/provider-utils/@ai-sdk/provider": ["@ai-sdk/[email protected]", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-HrEmNt/BH/hkQ7zpi2o6N3k1ZR1QTb7z85WYhYygiTxOQuaml4CMtHCWRbric5WPU+RNsYI7r1EpyVQMKO1pYw=="],
@@ -3205,22 +3205,12 @@
"@esbuild-kit/core-utils/esbuild/@esbuild/win32-x64": ["@esbuild/[email protected]", "", { "os": "win32", "cpu": "x64" }, "sha512-kTdfRcSiDfQca/y9QIkng02avJ+NCaQvrMejlsB3RRv5sE9rRoeBPISaZpKxHELzRxZyLvNts1P27W3wV+8geQ=="],
+ "@itsaplan/runner/@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
"@mastra/core/ajv/json-schema-traverse": ["[email protected]", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
"@modelcontextprotocol/sdk/ajv/json-schema-traverse": ["[email protected]", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
- "@repo/agent-tools/@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-loKuVrAFZKfEv+JvWkHRS9GW5IqLuLRjVXN9p+vZvBN86O5hf/pBZQ5hSoyipsrMmWObZBDvWnlmKvjKTM0PdA=="],
-
- "@repo/auth/@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-loKuVrAFZKfEv+JvWkHRS9GW5IqLuLRjVXN9p+vZvBN86O5hf/pBZQ5hSoyipsrMmWObZBDvWnlmKvjKTM0PdA=="],
-
- "@repo/crypto/@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-loKuVrAFZKfEv+JvWkHRS9GW5IqLuLRjVXN9p+vZvBN86O5hf/pBZQ5hSoyipsrMmWObZBDvWnlmKvjKTM0PdA=="],
-
- "@repo/db/@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-loKuVrAFZKfEv+JvWkHRS9GW5IqLuLRjVXN9p+vZvBN86O5hf/pBZQ5hSoyipsrMmWObZBDvWnlmKvjKTM0PdA=="],
-
- "@repo/mailer/@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-loKuVrAFZKfEv+JvWkHRS9GW5IqLuLRjVXN9p+vZvBN86O5hf/pBZQ5hSoyipsrMmWObZBDvWnlmKvjKTM0PdA=="],
-
- "@repo/net/@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-loKuVrAFZKfEv+JvWkHRS9GW5IqLuLRjVXN9p+vZvBN86O5hf/pBZQ5hSoyipsrMmWObZBDvWnlmKvjKTM0PdA=="],
-
"@scalar/icons/@types/node/undici-types": ["[email protected]", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
"@types/nodemailer/@types/node/undici-types": ["[email protected]", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
@@ -3233,11 +3223,9 @@
"ajv-formats/ajv/json-schema-traverse": ["[email protected]", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
- "api/@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-loKuVrAFZKfEv+JvWkHRS9GW5IqLuLRjVXN9p+vZvBN86O5hf/pBZQ5hSoyipsrMmWObZBDvWnlmKvjKTM0PdA=="],
-
"archiver-utils/readable-stream/string_decoder": ["[email protected]", "", { "dependencies": { "safe-buffer": "~5.1.0" } }, "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg=="],
- "bun-types/@types/node/undici-types": ["[email protected]", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
+ "bot/@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
"cmdk/@radix-ui/react-dialog/@radix-ui/primitive": ["@radix-ui/[email protected]", "", {}, "sha512-d86WIWFYNtGA0H/d8exstrTRTp7eWJYlYJbtNofxr/3ljupZYn6EFDG/Qgu/0Kc8v7yMUxySagqJsL1+PdYjWg=="],
@@ -3367,10 +3355,12 @@
"unzipper/readable-stream/string_decoder": ["[email protected]", "", { "dependencies": { "safe-buffer": "~5.1.0" } }, "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg=="],
- "worker/@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-loKuVrAFZKfEv+JvWkHRS9GW5IqLuLRjVXN9p+vZvBN86O5hf/pBZQ5hSoyipsrMmWObZBDvWnlmKvjKTM0PdA=="],
+ "@itsaplan/runner/@types/bun/bun-types/@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q=="],
"@typescript-eslint/typescript-estree/minimatch/brace-expansion/balanced-match": ["[email protected]", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
+ "bot/@types/bun/bun-types/@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q=="],
+
"cmdk/@radix-ui/react-dialog/@radix-ui/react-dismissable-layer/@radix-ui/react-use-callback-ref": ["@radix-ui/[email protected]", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-xCso9j1/u8sEgP1RNHjFrXJLApL8LiqOkI1R4ywuN00rxWdYg4oQXuwKLS3i0j5NWLromUD27/4nlxj2UFVvIw=="],
"cmdk/@radix-ui/react-dialog/@radix-ui/react-dismissable-layer/@radix-ui/react-use-effect-event": ["@radix-ui/[email protected]", "", { "dependencies": { "@radix-ui/react-use-layout-effect": "1.1.2" }, "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-6c8ZqvPTWILEKnyVkP53EGRCcpnJiKTC21sS/6R1GF5xKyHJJWQEPfkqlcgUkdRQivd6tb23abUwe4ngWmY0JA=="],
@@ -3399,6 +3389,10 @@
"pretty-format/ansi-styles/color-convert/color-name": ["[email protected]", "", {}, "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw=="],
+ "@itsaplan/runner/@types/bun/bun-types/@types/node/undici-types": ["[email protected]", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
+
+ "bot/@types/bun/bun-types/@types/node/undici-types": ["[email protected]", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
+
"cmdk/@radix-ui/react-dialog/@radix-ui/react-dismissable-layer/@radix-ui/react-use-effect-event/@radix-ui/react-use-layout-effect": ["@radix-ui/[email protected]", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-jrBWOxZITuGcnjRCM2t2U5ZPkCLxD+Ym6DjfssS5haTj2iiak/DOb64JeN6OdLfLgptb6/e2kKR+ZuTrGoZTPA=="],
"eslint-plugin-i18n-json/chalk/ansi-styles/color-convert/color-name": ["[email protected]", "", {}, "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw=="],
diff --git a/docker-compose.test.yml b/docker-compose.test.yml
index 798e60e1..f0f9d941 100644
--- a/docker-compose.test.yml
+++ b/docker-compose.test.yml
@@ -9,23 +9,27 @@
# docker compose -f docker-compose.test.yml run --rm api-test
#
# The test database is created automatically by the postgres-test service
-# (POSTGRES_DB=vela_test); its data is tmpfs, so nothing persists between runs.
+# (POSTGRES_DB=itsaplan_test); its data is tmpfs, so nothing persists between runs.
# Use as a Coolify pre-deployment step now, or drop the same command into a
# GitHub Actions job later.
# ─────────────────────────────────────────────────────────────
+# Its own project: without a name compose derives one from the directory and the test
+# containers join the self-hosting stack, which `docker compose down` then takes with it.
+name: itsaplan-test
+
services:
postgres-test:
image: postgres:17-alpine
environment:
- POSTGRES_USER: vela
- POSTGRES_PASSWORD: vela
+ POSTGRES_USER: itsaplan
+ POSTGRES_PASSWORD: itsaplan
# Name contains "test" — the resetDb() guard requires it.
- POSTGRES_DB: vela_test
+ POSTGRES_DB: itsaplan_test
# Ephemeral: the data directory lives in memory, wiped when the run ends.
tmpfs:
- /var/lib/postgresql/data
healthcheck:
- test: ['CMD-SHELL', 'pg_isready -U vela -d vela_test']
+ test: ['CMD-SHELL', 'pg_isready -U itsaplan -d itsaplan_test']
interval: 3s
timeout: 3s
retries: 20
@@ -68,7 +72,7 @@ services:
condition: service_completed_successfully
environment:
NODE_ENV: test
- DATABASE_URL: postgres://vela:vela@postgres-test:5432/vela_test
+ DATABASE_URL: postgres://itsaplan:itsaplan@postgres-test:5432/itsaplan_test
# Any fixed secret works for a throwaway test DB.
BETTER_AUTH_SECRET: test-secret-not-for-production-use-only
# Fixed 32-byte base64 key for the provider-credential encryption tests.
@@ -98,4 +102,4 @@ services:
condition: service_healthy
environment:
NODE_ENV: test
- DATABASE_URL: postgres://vela:vela@postgres-test:5432/vela_test
+ DATABASE_URL: postgres://itsaplan:itsaplan@postgres-test:5432/itsaplan_test
diff --git a/docs/development.md b/docs/development.md
index be856865..64411107 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -8,27 +8,30 @@ Requirements: [Bun](https://bun.sh) 1.3+, Docker, Git.
git clone https://github.com/croffasia/itsaplan.git
cd itsaplan
bun install
+bun run setup # "Develop", or "Generate env" for just the .env files
+bun run dev # api + web together, via Turborepo
+```
-cp .env.example .env
-cp apps/web/.env.example apps/web/.env
-
-# BETTER_AUTH_SECRET, APP_ENCRYPTION_KEY, WORKER_INTERNAL_TOKEN in .env:
-openssl rand -base64 32
+**Develop** writes the env files, generates the secrets, starts Postgres and MinIO, creates
+the test database, and migrates both. Run it again any time: it restarts the stack and
+re-applies the migrations, keeping the data. It offers another port when one is taken, and
+offers to stop the **Try it** stack, which publishes the same ones.
-docker compose -f docker-compose.dev.yml up -d # Postgres + MinIO only
-bun run db:migrate
-bun run dev # api + web together, via Turborepo
-```
+`bun run dev` runs the workspace in watch mode: web on <http://localhost:3001>, api on
+<http://localhost:3000>, MinIO console on <http://localhost:9001>. Only Postgres and MinIO
+run in Docker; the apps run on the host.
-The apps run on: web <http://localhost:3001>, api <http://localhost:3000>, MinIO console
-<http://localhost:9001>. `bun run dev` runs the whole workspace in watch mode from the repo
-root; the dev compose brings up only the backing services and the apps run on the host.
+## Environment
-If host port 5432 is taken, set another one and update `DATABASE_URL` in `.env`:
+| File | Read by |
+| --------------- | --------------------------------------------- |
+| `.env` | api, worker, bot, drizzle |
+| `apps/web/.env` | web — Next reads env only from its own folder |
+| `.env.test` | the api test suite |
-```bash
-POSTGRES_PORT=5433 docker compose -f docker-compose.dev.yml up -d
-```
+`.env.example` documents every variable and its default. The three secrets have none and are
+generated while the database volume does not exist — past that the instance is using them,
+and a new value would lock it out of its own data.
## Commands
@@ -47,33 +50,23 @@ pnpm: the lockfile is `bun.lock`.
## Tests
-Tests run against a real test Postgres, not mocks. Prepare a dedicated `*_test` database
-once, then run the suite from the repo root:
+Integration tests against a real Postgres, not mocks. The setup prepared a separate `*_test`
+database with `.env.test` pointing at it; the name must contain "test", since the reset
+helper TRUNCATEs every table between tests and refuses otherwise.
```bash
-cp .env.test.example .env.test # DATABASE_URL must name a *_test database
-bun run db:migrate:test # migrate the test database
-bun run test # run all suites via Turborepo
+bun run test
```
-The dev compose (`docker-compose.dev.yml`) provides Postgres and MinIO for these tests; the
-attachments suite needs the MinIO bucket it creates.
-
-Alternatively, run the same gate CI uses — the suite against a throwaway Postgres in a
-container built from the production image:
+The same gate CI runs — the suite against a throwaway Postgres, in a container built from
+the production image:
```bash
docker compose -f docker-compose.test.yml build
docker compose -f docker-compose.test.yml run --rm api-test
```
-`run` starts the dependencies, runs the suite, and exits with its code.
-
-`apps/api` has the integration suite; `apps/api/AGENTS.md` covers how to write one.
-
-## Internals
-
-Descriptions of the mechanisms that span several apps live in [`docs/dev/`](dev/):
+The integration suite is in `apps/api`. `apps/api/AGENTS.md` explains how to write a test.
-- [The revision engine](dev/revision-engine.md) — how an open screen stays current.
-- [Languages](dev/i18n.md) — how the interface language is resolved, and how to add one.
+The mechanisms that span several apps — the revision engine, the interface languages — are
+described in [`docs/dev/`](dev/).
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index ea7daf5b..f9be8174 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -6,17 +6,30 @@ Requirements: Docker and a domain behind a TLS-terminating reverse proxy.
git clone https://github.com/croffasia/itsaplan.git
cd itsaplan
cp .env.example .env
-# Set the public origins: API_URL, APP_URL
-# Generate each secret with `openssl rand -base64 32`:
-# POSTGRES_PASSWORD, BETTER_AUTH_SECRET, APP_ENCRYPTION_KEY,
-# WORKER_INTERNAL_TOKEN, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY
-
+# fill in the eight values below
docker compose up -d
```
-One command brings up the whole stack: Postgres, MinIO, api, worker, bot, and web. The four
-services run from the images published on each release; `VERSION` in `.env` pins one instead
-of the newest. The API applies migrations on startup, and the first account registered
+The stack refuses to start while one of these is missing:
+
+| Variable | Value |
+| ----------------------- | ------------------------------------------ |
+| `API_URL` | public origin of the api |
+| `APP_URL` | public origin of the web app |
+| `POSTGRES_PASSWORD` | `openssl rand -base64 32` |
+| `BETTER_AUTH_SECRET` | `openssl rand -base64 32` |
+| `APP_ENCRYPTION_KEY` | `openssl rand -base64 32` |
+| `WORKER_INTERNAL_TOKEN` | `openssl rand -base64 32` |
+| `S3_ACCESS_KEY_ID` | the MinIO root user, any name over 3 chars |
+| `S3_SECRET_ACCESS_KEY` | `openssl rand -base64 32` |
+
+On a machine with [Bun](https://bun.sh), the setup script generates them instead. Run
+`bun install && bun run setup`, answer **Generate env**, and answer no when it offers to
+write the files: it prints `.env` and `apps/web/.env` for you to copy onto the server.
+
+That starts the whole stack: Postgres, MinIO, api, worker, bot, and web. The four services
+run from the images published on each release. `VERSION` in `.env` pins one release instead
+of the newest. The api applies migrations when it starts, and the first account you register
becomes the instance admin.
`.env.example` documents every variable, including the optional ones: legal document URLs,
@@ -24,25 +37,25 @@ passkey and cookie settings, telemetry opt-out, and worker tuning.
## Single sign-on
-Any provider that publishes an OpenID Connect discovery document works: Keycloak,
-Authentik, KanIDM, GitLab, Forgejo, Okta, Entra. The credentials are stored in the
-database, not in env, so nothing here needs a restart.
+Any provider with an OpenID Connect discovery document works: Keycloak, Authentik, KanIDM,
+GitLab, Forgejo, Okta, Entra. The credentials go into the database, not into `.env`, so
+nothing here needs a restart.
1. In god mode, open **Integrations → Auth provider** and copy the redirect URI it shows
(`<API_URL>/api/auth/oauth2/callback/oidc`).
2. Create a confidential client at your provider with that redirect URI.
3. Paste the discovery URL (`.../.well-known/openid-configuration`), the client ID and the
- client secret back into the page, name the sign-in button, and turn the provider on.
+ client secret back into the page. Name the sign-in button and turn the provider on.
-A first sign-in creates the account, subject to the registration mode under
-**Authentication**: `open` creates it, `invite only` needs a pending project invite, and
-`closed` refuses it — use SCIM below to provision people on a closed instance.
+The first sign-in creates the account, and the registration mode under **Authentication**
+decides whether it may: `open` creates it, `invite only` needs a pending project invite,
+`closed` refuses it. On a closed instance, provision people with SCIM.
-Once a provider works, **Authentication → Email and password** can be turned off. That
-hides and refuses the sign-in and sign-up forms, password reset and sign-in links; the
-provider becomes the only way in. Passkeys keep working, since one can only be added to an
-account that already exists. The switch stays disabled until a provider is configured, so
-an instance cannot be left with no way in.
+Once a provider works, you can turn off **Authentication → Email and password**. The sign-in
+and sign-up forms, password reset and sign-in links are then hidden and refused, and the
+provider is the only way in. Passkeys keep working, because a passkey can only be added to an
+account that already exists. The switch stays disabled until a provider is configured, so an
+instance cannot be left with no way in.
## Provisioning with SCIM
@@ -55,23 +68,28 @@ project access through its groups.
(`<API_URL>/scim/v2`), authenticating with `Authorization: Bearer <token>`.
3. Push users, and groups if you use them.
-Deactivating someone at the provider (`active: false`) ends their sessions and refuses
-their API keys; reactivating restores them with their projects intact. The instance owner's
-own account is outside SCIM's reach — a provisioning run can neither change nor deactivate
-it, and a repeated create for an address it already provisioned answers "already exists"
-rather than overwriting the link back to the provider.
+Deactivating someone at the provider (`active: false`) ends their sessions and refuses their
+API keys. Reactivating restores both, with their projects intact.
+
+The instance owner's account is outside SCIM's reach: a provisioning run cannot change or
+deactivate it. A repeated create for an address SCIM already provisioned answers "already
+exists" instead of overwriting the link back to the provider.
+
+A pushed group grants nothing until you map it. On the same page, open the group and add the
+projects its members join, and the role they join on. Remove a project from that list, and
+the memberships the group gave it go away.
+
+A sync never touches a membership someone got through an invite. A membership the sync
+created cannot be edited from the project's members page — it changes at the identity
+provider.
+
+A group also appears here without an explicit push in two cases:
-A pushed group grants nothing until you say what it is for: on the same page, open a group
-and add the projects its members should join, and the role they join on. Removing a project
-from that list takes away the memberships the group gave it. A membership someone got
-through an invite is never touched by a sync, and one the sync created cannot be edited from
-the project's members page — it changes at the identity provider.
+- a SCIM user whose payload embeds a `groups` attribute, instead of a separate group push,
+- anyone who signs in through OIDC while their provider puts a `groups` claim on the token.
+ Set that up as a claim mapping on the OIDC client.
-A group also appears here without any explicit push, in two cases: a SCIM user whose
-payload embeds a `groups` attribute instead of being assigned through a separate group
-push, and anyone who signs in through OIDC while their identity provider puts a `groups`
-claim on the token — set that up as a claim mapping on the OIDC client if the provider
-supports one. Either way, map the group the same way once it shows up.
+Map such a group the same way once it appears.
## Updating
@@ -81,8 +99,8 @@ docker compose pull
docker compose up -d
```
-`git pull` is for the compose file itself; the services come from the registry. Changing
-`API_URL` or `APP_URL` afterwards only needs `docker compose up -d`.
+`git pull` updates the compose file. The services come from the registry. Changing `API_URL`
+or `APP_URL` afterwards only needs `docker compose up -d`.
## Building from source instead
@@ -90,9 +108,8 @@ docker compose up -d
docker compose up -d --build
```
-Builds every service from this checkout and runs those images. Nothing else changes, and
+That builds every service from this checkout and runs those images. Nothing else changes, and
the same command picks up local edits.
-For a Coolify instance, see [coolify.md](coolify.md). For Kubernetes, see
-[helm.md](helm.md). For a hosted deploy without a server of your own, see
-[railway.md](railway.md).
+For a Coolify instance, see [coolify.md](coolify.md). For Kubernetes, see [helm.md](helm.md).
+For a hosted deploy without a server of your own, see [railway.md](railway.md).
diff --git a/package.json b/package.json
index cd883f2e..8614761a 100644
--- a/package.json
+++ b/package.json
@@ -3,7 +3,9 @@
"version": "0.16.0",
"license": "AGPL-3.0-only",
"devDependencies": {
+ "@clack/prompts": "^1.7.0",
"@repo/eslint-config": "workspace:*",
+ "@types/bun": "^1.4.1",
"eslint": "^9.39.0",
"lefthook": "^2.1.10",
"prettier": "3.9.6",
@@ -14,14 +16,15 @@
"packageManager": "[email protected]",
"private": true,
"scripts": {
+ "setup": "bun scripts/setup.ts",
"dev": "turbo run dev",
"build": "turbo run build",
"start": "turbo run start",
"lint": "turbo run lint",
"format": "prettier . --write",
"format:check": "prettier . --check",
- "typecheck": "turbo run typecheck",
- "test": "turbo run test",
+ "typecheck": "turbo run typecheck && tsc --noEmit",
+ "test": "bun test scripts/ && turbo run test",
"test:coverage": "cd apps/api && bun run test:coverage",
"db:generate": "bun --filter='@repo/db' run db:generate",
"db:migrate": "bun --filter='@repo/db' run db:migrate",
diff --git a/scripts/env-file.test.ts b/scripts/env-file.test.ts
new file mode 100644
index 00000000..8a169fbf
--- /dev/null
+++ b/scripts/env-file.test.ts
@@ -0,0 +1,74 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, test } from 'bun:test';
+import { EnvFile, getEnv, setEnv } from './env-file.ts';
+
+const example = `# a comment
+POSTGRES_USER=itsaplan
+BETTER_AUTH_SECRET=change-me # openssl rand -base64 32
+# WEB_PORT=3001
+`;
+
+describe('getEnv', () => {
+ test('reads a value and drops the trailing comment', () => {
+ expect(getEnv(example, 'POSTGRES_USER')).toBe('itsaplan');
+ expect(getEnv(example, 'BETTER_AUTH_SECRET')).toBe('change-me');
+ });
+
+ test('treats a commented-out key and an unknown key as unset', () => {
+ expect(getEnv(example, 'WEB_PORT')).toBe('');
+ expect(getEnv(example, 'NOPE')).toBe('');
+ });
+});
+
+describe('setEnv', () => {
+ test('replaces in place and leaves the other lines alone', () => {
+ const written = setEnv(example, 'POSTGRES_USER', 'other');
+ expect(getEnv(written, 'POSTGRES_USER')).toBe('other');
+ expect(getEnv(written, 'BETTER_AUTH_SECRET')).toBe('change-me');
+ });
+
+ test('appends a key that is only present commented out', () => {
+ expect(getEnv(setEnv(example, 'WEB_PORT', '3002'), 'WEB_PORT')).toBe('3002');
+ });
+
+ test('writes a generated secret literally, $ and all', () => {
+ const secret = 'a$&b$1c/+=';
+ expect(getEnv(setEnv(example, 'APP_ENCRYPTION_KEY', secret), 'APP_ENCRYPTION_KEY')).toBe(
+ secret,
+ );
+ });
+});
+
+describe('EnvFile', () => {
+ const tempPath = () => join(mkdtempSync(join(tmpdir(), 'env-file-')), '.env');
+
+ const write = (body: string) => {
+ const path = tempPath();
+ writeFileSync(path, body);
+ return new EnvFile(path);
+ };
+
+ test('generates over an example value and keeps a real one', () => {
+ const env = write(
+ 'BETTER_AUTH_SECRET=change-me\nAPP_ENCRYPTION_KEY=\nWORKER_INTERNAL_TOKEN=kept\n',
+ );
+ ['BETTER_AUTH_SECRET', 'APP_ENCRYPTION_KEY', 'WORKER_INTERNAL_TOKEN'].forEach((key) =>
+ env.generate(key),
+ );
+
+ expect(env.get('BETTER_AUTH_SECRET')).not.toBe('change-me');
+ expect(env.get('APP_ENCRYPTION_KEY')).toHaveLength(44);
+ expect(env.get('WORKER_INTERNAL_TOKEN')).toBe('kept');
+ });
+
+ test('fresh reads the example, ignoring the file next to it', () => {
+ const path = tempPath();
+ writeFileSync(path, 'POSTGRES_USER=vela\n');
+ writeFileSync(`${path}.example`, 'POSTGRES_USER=itsaplan\n');
+
+ expect(new EnvFile(path).get('POSTGRES_USER')).toBe('vela');
+ expect(new EnvFile(path, true).get('POSTGRES_USER')).toBe('itsaplan');
+ });
+});
diff --git a/scripts/env-file.ts b/scripts/env-file.ts
new file mode 100644
index 00000000..8d03deb6
--- /dev/null
+++ b/scripts/env-file.ts
@@ -0,0 +1,55 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+
+export const getEnv = (text: string, key: string): string => {
+ const match = text.match(new RegExp(`^${key}=(.*)$`, 'm'));
+ return match ? match[1].replace(/\s+#.*$/, '').trim() : '';
+};
+
+export const setEnv = (text: string, key: string, value: string): string => {
+ const line = new RegExp(`^${key}=.*$`, 'm');
+ // The replacement is a function so $& and $1 in a generated secret stay literal.
+ return line.test(text)
+ ? text.replace(line, () => `${key}=${value}`)
+ : `${text.replace(/\n*$/, '')}\n${key}=${value}\n`;
+};
+
+/** One .env file, written back on save(). Reads its .example when the file is missing, or
+ * when `fresh` asks for a file built from scratch rather than from what is already there. */
+export class EnvFile {
+ private text: string;
+
+ constructor(
+ private readonly path: string,
+ fresh = false,
+ ) {
+ this.text = readFileSync(fresh || !existsSync(path) ? `${path}.example` : path, 'utf8');
+ }
+
+ get(key: string) {
+ return getEnv(this.text, key);
+ }
+
+ set(key: string, value: string) {
+ this.text = setEnv(this.text, key, value);
+ }
+
+ /** True while the key still holds an example value rather than one somebody chose. */
+ isPlaceholder(key: string) {
+ const current = this.get(key);
+ return current === '' || current.startsWith('change-me');
+ }
+
+ /** Replaces a secret that still holds an example value; a real one is kept. */
+ generate(key: string) {
+ if (this.isPlaceholder(key)) this.set(key, randomBytes(32).toString('base64'));
+ }
+
+ save() {
+ writeFileSync(this.path, this.text);
+ }
+
+ toString() {
+ return this.text;
+ }
+}
diff --git a/scripts/setup.ts b/scripts/setup.ts
new file mode 100644
index 00000000..f6e83bc6
--- /dev/null
+++ b/scripts/setup.ts
@@ -0,0 +1,406 @@
+#!/usr/bin/env bun
+import { existsSync } from 'node:fs';
+import { connect } from 'node:net';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as p from '@clack/prompts';
+import { EnvFile } from './env-file.ts';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const file = (name: string) => join(root, name);
+
+const answer = <T>(value: T | symbol): T => {
+ if (p.isCancel(value)) {
+ p.cancel('Setup cancelled.');
+ process.exit(0);
+ }
+ return value as T;
+};
+
+// Output is captured rather than inherited: docker and drizzle write while a spinner
+// is running, and only a failure is worth showing.
+const exec = async (...cmd: string[]) => {
+ const proc = Bun.spawn(cmd, { cwd: root, stdout: 'pipe', stderr: 'pipe' });
+ const [code, stdout, stderr] = await Promise.all([
+ proc.exited,
+ new Response(proc.stdout).text(),
+ new Response(proc.stderr).text(),
+ ]);
+ return { ok: code === 0, code, stdout, stderr };
+};
+
+const run = async (...cmd: string[]) => {
+ const { ok, code, stdout, stderr } = await exec(...cmd);
+ if (!ok) {
+ p.cancel(`\`${cmd.join(' ')}\` failed:\n${`${stderr}\n${stdout}`.trim()}`);
+ process.exit(code);
+ }
+};
+
+const accepts = (host: string, port: number) =>
+ new Promise<boolean>((resolve) => {
+ const socket = connect({ host, port });
+ const done = (reachable: boolean) => {
+ socket.destroy();
+ resolve(reachable);
+ };
+ socket.setTimeout(500);
+ socket.once('connect', () => done(true));
+ socket.once('timeout', () => done(false));
+ socket.once('error', () => done(false));
+ });
+
+/**
+ * Asked by connecting, not by binding: macOS lets a bind on one loopback address succeed
+ * beside a listener on the other, so a native Postgres on 127.0.0.1 and a container
+ * published on the wildcard both read as free. Both addresses are tried — Docker publishes
+ * on one, a host service often listens on both.
+ */
+const portFree = async (port: number) =>
+ !(await accepts('127.0.0.1', port)) && !(await accepts('::1', port));
+
+/**
+ * The port is only offered for change, never forced: a port held by a container of this
+ * project is in use and correct at the same time, and only the person running this knows.
+ */
+const askPort = async (what: string, wanted: number) => {
+ if (await portFree(wanted)) return wanted;
+
+ let free = wanted + 1;
+ while (!(await portFree(free))) free += 1;
+
+ return Number(
+ answer(
+ await p.text({
+ message: `Port ${wanted} is in use. Pick another for ${what}:`,
+ initialValue: String(free),
+ validate: (value = '') => (/^\d+$/.test(value) ? undefined : 'Enter a port number.'),
+ }),
+ ),
+ );
+};
+
+/** True while a service of this compose project — any of them, or the named one — is running. */
+const isUp = async (compose: string[], ...service: string[]) =>
+ (await exec(...compose, 'ps', '-q', '--status', 'running', ...service)).stdout.trim() !== '';
+
+/** The two stacks read the same .env, so they publish the same api and web ports. */
+const stopOther = async (other: string[], what: string, hint = '') => {
+ if (!(await isUp(other))) return;
+
+ if (!answer(await p.confirm({ message: `The ${what} stack holds these ports. Stop it?` }))) {
+ p.cancel(`Nothing changed.${hint}`);
+ process.exit(0);
+ }
+ await run(...other, 'down');
+};
+
+const requireDocker = async () => {
+ if ((await exec('docker', 'info')).ok) return;
+ p.cancel('Docker is not running. Start it and run this again.');
+ process.exit(1);
+};
+
+const openBrowser = (url: string) => exec(process.platform === 'darwin' ? 'open' : 'xdg-open', url);
+
+const secrets = ['BETTER_AUTH_SECRET', 'APP_ENCRYPTION_KEY', 'WORKER_INTERNAL_TOKEN'];
+
+/** Every value the setup chooses, with the default to prefill when the file carries none. */
+const generated: Record<string, string> = {
+ POSTGRES_USER: 'itsaplan',
+ POSTGRES_PASSWORD: 'itsaplan',
+ POSTGRES_DB: 'itsaplan',
+ ...Object.fromEntries(secrets.map((key) => [key, ''])),
+};
+
+const volumeExists = async (volume: string) =>
+ (await exec('docker', 'volume', 'inspect', volume)).ok;
+
+/**
+ * Secrets are chosen once, into a fresh install: past the first start BETTER_AUTH_SECRET
+ * signs live sessions and APP_ENCRYPTION_KEY decrypts the stored provider keys, so a new
+ * value would make what the instance saved unreadable.
+ */
+const writeSecrets = async (env: EnvFile, volume: string) => {
+ if (!(await volumeExists(volume))) {
+ secrets.forEach((key) => env.generate(key));
+ return;
+ }
+
+ const kept = secrets.filter((key) => env.isPlaceholder(key));
+ if (kept.length > 0)
+ p.log.warn(`${kept.join(', ')} keep their example value: the database exists.`);
+};
+
+/** Whether the running database accepts the credentials .env holds now, over TCP as the api does. */
+const databaseAccepts = async (compose: string[], env: EnvFile) =>
+ (
+ await exec(
+ ...compose,
+ 'exec',
+ '-T',
+ '-e',
+ `PGPASSWORD=${env.get('POSTGRES_PASSWORD')}`,
+ 'postgres',
+ 'psql',
+ '-h',
+ '127.0.0.1',
+ '-U',
+ env.get('POSTGRES_USER'),
+ '-d',
+ env.get('POSTGRES_DB'),
+ '-c',
+ 'select 1',
+ )
+ ).ok;
+
+/**
+ * A container keeps the port it started with, so one that was not recreated still publishes
+ * the old one and nothing answers on the port .env names. Asked of the host, which is where
+ * the migrations connect from, and only a recreate moves it.
+ */
+const matchPort = async (compose: string[], wanted: number) => {
+ if (await accepts('127.0.0.1', wanted)) return;
+
+ await run(...compose, 'up', '-d', '--force-recreate', '--wait', 'postgres');
+ if (await accepts('127.0.0.1', wanted)) return;
+
+ p.cancel(`Nothing answers on port ${wanted}, the one .env names for Postgres.`);
+ process.exit(1);
+};
+
+/**
+ * Postgres creates the role and the database when it initialises its volume and never reads
+ * those variables again, so credentials changed afterwards reach nothing and every
+ * connection fails. Starting over is the only way to apply them, and it deletes the data,
+ * so it is offered rather than done.
+ */
+const matchCredentials = async (compose: string[], env: EnvFile) => {
+ if (await databaseAccepts(compose, env)) return;
+
+ p.log.warn(
+ `The database does not accept ${env.get('POSTGRES_USER')}. It was created with other credentials.`,
+ );
+
+ const confirmed = answer(
+ await p.confirm({
+ message: 'Recreate it? Every row and every uploaded file is deleted.',
+ initialValue: false,
+ }),
+ );
+ if (!confirmed) {
+ p.cancel('Nothing changed. Restore the old credentials in .env.');
+ process.exit(0);
+ }
+
+ await run(...compose, 'down', '-v');
+ await run(...compose, 'up', '-d');
+ await run(...compose, 'up', '-d', '--wait', '--no-recreate', 'postgres');
+};
+
+/** Every chosen value, one prompt each, prefilled, so any of them can be replaced. */
+const walk = async (env: EnvFile, fields: Record<string, string>) => {
+ for (const [key, fallback] of Object.entries(fields)) {
+ const value = answer(
+ await p.text({
+ message: key,
+ initialValue: env.get(key) || fallback,
+ validate: (input = '') => (input.trim() === '' ? 'Enter a value.' : undefined),
+ }),
+ );
+ env.set(key, value.trim());
+ }
+};
+
+p.intro("It's a Plan setup");
+
+const mode = answer(
+ await p.select({
+ message: 'What do you want to set up?',
+ options: [
+ { value: 'try', label: 'Try it', hint: 'the whole stack in Docker, on localhost' },
+ {
+ value: 'dev',
+ label: 'Develop',
+ hint: 'Postgres and MinIO in Docker, the apps on your machine',
+ },
+ { value: 'env', label: 'Generate env', hint: 'the secrets and every value, step by step' },
+ ],
+ }),
+);
+
+if (mode !== 'env') await requireDocker();
+// Generate env builds both files from the examples: it is a fresh set of values, not an
+// edit of the ones already here.
+const env = new EnvFile(file('.env'), mode === 'env');
+
+if (mode === 'env') {
+ secrets.forEach((key) => env.generate(key));
+ await walk(env, generated);
+
+ const web = new EnvFile(file('apps/web/.env'), true);
+ web.set('API_URL', env.get('API_URL'));
+
+ let write = answer(
+ await p.confirm({ message: 'Write .env and apps/web/.env? No prints them instead.' }),
+ );
+
+ // A running instance reads its own data with the secrets in the file being replaced.
+ if (write && existsSync(file('.env')))
+ write = answer(
+ await p.confirm({
+ message:
+ 'Overwrite the .env you have? Copy its secrets first — an instance built on them cannot read its data without them.',
+ initialValue: false,
+ }),
+ );
+
+ if (write) {
+ env.save();
+ web.save();
+ p.outro('.env and apps/web/.env are written.');
+ } else {
+ p.outro('Nothing was written.');
+ // Printed unindented and unboxed so it can be copied straight into another file.
+ console.log(`# .env\n${env}\n# apps/web/.env\n${web}`);
+ }
+}
+
+if (mode === 'try') {
+ const compose = ['docker', 'compose'];
+ await stopOther(['docker', 'compose', '-f', 'docker-compose.dev.yml'], 'Develop');
+
+ const running = await isUp(compose);
+
+ if (running) {
+ const restart = answer(
+ await p.confirm({
+ message: 'An instance is running. Restart it? The data is kept.',
+ }),
+ );
+ if (!restart) {
+ p.outro('Nothing changed.');
+ process.exit(0);
+ }
+ } else {
+ const apiPort = await askPort('the api', Number(env.get('API_PORT') || 3000));
+ const webPort = await askPort('the web app', Number(env.get('WEB_PORT') || 3001));
+ env.set('API_PORT', String(apiPort));
+ env.set('WEB_PORT', String(webPort));
+ env.set('API_URL', `http://localhost:${apiPort}`);
+ env.set('APP_URL', `http://localhost:${webPort}`);
+ await writeSecrets(env, 'itsaplan_postgres-data');
+ env.save();
+ }
+
+ const database = p.spinner();
+ database.start(running ? 'Restarting Postgres' : 'Starting Postgres');
+ if (running) await run(...compose, 'down');
+ await run(...compose, 'up', '-d', '--wait', 'postgres');
+ database.stop('Postgres is up');
+
+ // Before the api, which would otherwise fail its healthcheck on the same mismatch.
+ await matchCredentials(compose, env);
+
+ const spinner = p.spinner();
+ spinner.start('Starting the rest of the stack');
+ await run(...compose, 'up', '-d');
+ // --wait names api and web only: minio-init is a one-shot and its exit counts as a
+ // failure. api is worth waiting for on its own — it migrates before it listens, and
+ // web renders /login without it.
+ await run(...compose, 'up', '-d', '--wait', '--no-recreate', 'api', 'web');
+ spinner.stop('Stack is up');
+
+ const url = env.get('APP_URL');
+ await openBrowser(url);
+ p.outro(`${url} is open in your browser. The first account you register is the admin.`);
+}
+
+if (mode === 'dev') {
+ const compose = ['docker', 'compose', '-f', 'docker-compose.dev.yml'];
+
+ // Stopped before the ports are chosen, so a port this stack holds reads as free.
+ // Only the containers go; the volumes stay and the migrations below top the data up.
+ if (await isUp(compose)) {
+ const stopping = p.spinner();
+ stopping.start('Stopping the dev stack');
+ await run(...compose, 'down');
+ stopping.stop('Dev stack stopped');
+ }
+
+ await stopOther(['docker', 'compose'], 'Try it');
+ // The PR stack fixes the MinIO ports in its own compose file, so no port question can
+ // resolve an overlap with the dev one.
+ await stopOther(
+ ['docker', 'compose', '-f', 'docker-compose.dev.pr.yml'],
+ 'pull request',
+ ' `dev-scripts/dev-stack.sh dev` switches the two over.',
+ );
+
+ const dbPort = await askPort('Postgres', Number(env.get('POSTGRES_PORT') || 5432));
+ const apiPort = await askPort('the api', Number(env.get('API_PORT') || 3000));
+
+ env.set('POSTGRES_PORT', String(dbPort));
+ env.set('API_PORT', String(apiPort));
+ env.set('API_URL', `http://localhost:${apiPort}`);
+ await writeSecrets(env, 'itsaplan-dev_postgres-dev-data');
+
+ const user = env.get('POSTGRES_USER');
+ const database = env.get('POSTGRES_DB');
+ // The password reaches DATABASE_URL as a URL component; a typed one may need escaping.
+ const password = encodeURIComponent(env.get('POSTGRES_PASSWORD'));
+
+ env.set('DATABASE_URL', `postgres://${user}:${password}@localhost:${dbPort}/${database}`);
+ env.save();
+
+ const web = new EnvFile(file('apps/web/.env'));
+ web.set('API_URL', `http://localhost:${apiPort}`);
+ web.save();
+
+ const spinner = p.spinner();
+ spinner.start('Starting Postgres and MinIO');
+ await run(...compose, 'up', '-d');
+ // --wait names postgres only: minio-init is a one-shot and its exit counts as a failure.
+ await run(...compose, 'up', '-d', '--wait', '--no-recreate', 'postgres');
+ spinner.stop('Postgres and MinIO are up');
+
+ await matchPort(compose, dbPort);
+ await matchCredentials(compose, env);
+
+ // The integration suite TRUNCATEs every table, so it gets a database of its own
+ // next to the dev one. Already created on a re-run, which psql reports as an error.
+ const testDatabase = `${database}_test`;
+ await exec(
+ ...compose,
+ 'exec',
+ '-T',
+ 'postgres',
+ 'psql',
+ '-U',
+ user,
+ '-d',
+ database,
+ '-c',
+ `CREATE DATABASE ${testDatabase}`,
+ );
+
+ const test = new EnvFile(file('.env.test'));
+ test.set('DATABASE_URL', `postgres://${user}:${password}@localhost:${dbPort}/${testDatabase}`);
+ test.set('API_URL', `http://localhost:${apiPort}`);
+ test.set('APP_URL', env.get('APP_URL'));
+ for (const key of ['S3_ENDPOINT', 'S3_BUCKET', 'S3_ACCESS_KEY_ID', 'S3_SECRET_ACCESS_KEY'])
+ test.set(key, env.get(key));
+ test.save();
+
+ const migrations = p.spinner();
+ migrations.start('Applying migrations');
+ // The programmatic runner, not `bun run db:migrate`: drizzle-kit exits 1 without printing
+ // what the database refused, and a failure here is exactly what needs reading.
+ await run('bun', '--env-file=.env', 'packages/db/src/migrate.ts');
+ await run('bun', '--env-file=.env.test', 'packages/db/src/migrate.ts');
+ migrations.stop(`Migrated ${database} and ${testDatabase}`);
+
+ p.outro(
+ `Run \`bun run dev\` — web on http://localhost:3001, api on http://localhost:${apiPort}.`,
+ );
+}
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 00000000..1b52ea7c
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "$schema": "https://json.schemastore.org/tsconfig",
+ "extends": "./tsconfig.base.json",
+ "compilerOptions": {
+ "types": ["bun"],
+ "allowImportingTsExtensions": true
+ },
+ "include": ["scripts/**/*.ts"]
+}