Initial commit for project Spoon!

README.md

@@ -0,0 +1,86 @@
+# Spoon
+
+A reusable Bun/Turborepo template with Next.js 16, Expo, self-hosted Convex,
+shared UI/config packages, Vitest, and Docker deployment.
+
+## Local setup
+
+Requirements: Bun 1.3.10, Docker or Podman, Node 22, and the Infisical CLI.
+
+```sh
+bun install --frozen-lockfile
+infisical login
+infisical init
+bun db:up
+bun dev:next
+```
+
+The committed `.infisical.json` links this repository to its own Infisical
+project. Local commands read `dev` by default and never fall back to `.env`
+files. Select staging with `INFISICAL_ENV=staging bun dev:next`.
+
+Local services:
+
+- Next.js: `http://localhost:3000`
+- Convex API: `http://localhost:3210`
+- Convex dashboard: `http://localhost:6791`
+- Convex Postgres: `localhost:5432`
+
+Next and Expo run on the host. Spoon runs local Convex with Postgres storage by
+default. Local Compose creates the database named by `LOCAL_INSTANCE_NAME`
+because the Convex backend opens that database inside the Postgres cluster.
+Convex receives a database-cluster URL without a path.
+
+```sh
+bun db:down        # stop; preserve local data
+bun db:down:wipe   # remove local data volumes and generated admin key
+```
+
+Normal `bun db:up` never contacts staging. It starts local Postgres, Convex, and
+the dashboard, generates a machine-local Convex admin key in
+`.local/dev.generated.env` when needed, deploys functions/schema, and configures
+local Convex Auth keys.
+
+Physical devices cannot resolve their own `localhost`; override the public
+Convex URL with the development host's LAN address when testing Expo on-device.
+
+## Environment model
+
+- Local `dev` and `staging`: Infisical.
+- Generated local state: `.local/<environment>.generated.env`.
+- CI/CD: Gitea `DOTENV_PROD`, materialized only as a temporary runner file.
+- Docker compilation: explicit Compose build args; `.env*` stays outside the
+  image context.
+
+Run `sh scripts/with-env dev -- <command>` for an environment-aware command or
+`sh scripts/export-env dev` to materialize a temporary merged dotenv stream.
+Do not commit or maintain root `.env` files.
+
+## Development and quality
+
+```sh
+bun dev:next
+bun dev:expo
+bun lint:ws
+bun format
+bun lint
+bun typecheck
+bun test:unit
+bun test:integration
+bun test:component
+SKIP_E2E=1 bun run ci:check
+```
+
+`bun test:e2e` starts the isolated local stack and currently performs generic
+stack smoke checks. It stops the stack afterward only when the stack was not
+already running. It skips in CI and when `SKIP_E2E=1` is set.
+
+Shared dependency versions belong in root catalogs. Edit the root catalog, run
+`bun install`, then `bun lint:ws`; do not run `bun update` inside a workspace.
+
+## Deployment
+
+Production Compose retains the self-hosted Convex backend/dashboard and expects
+`POSTGRES_URL` to be a database-cluster URL without a database path. Gitea runs
+the quality gate first, builds the Next image from a temporary Gitea-secret env
+file, then pushes SHA and `latest` tags. CI never installs or invokes Infisical.