From 5a07ccbc1c9fe0a005f7e96ae85b8aecf7174979 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 28 Oct 2025 14:41:04 +0000 Subject: [PATCH 1/8] Initial plan From 6674cacb2fc531dd0e20ac0ca7ae93a4a083b03c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 28 Oct 2025 14:54:20 +0000 Subject: [PATCH 2/8] Add comprehensive copilot-instructions.md file Co-authored-by: stnguyen90 <1477010+stnguyen90@users.noreply.github.com> --- .github/copilot-instructions.md | 266 ++++++++++++++++++++++++++++++++ 1 file changed, 266 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..f0555fde52 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,266 @@ +# Appwrite Console - Copilot Instructions + +## Repository Overview + +**What it is**: Appwrite Console is the web-based Graphical User Interface for developers to interact with their Appwrite instance. It's a production-ready single-page application serving as the front-end dashboard for the Appwrite backend-as-a-service platform. + +**Tech Stack**: +- Framework: Svelte 5 + SvelteKit 2 +- Language: TypeScript (not strictly typed - `strict: false` in tsconfig) +- Build Tool: Vite 7 +- Package Manager: pnpm 10.15.1 +- Node Version: 20+ +- Testing: Vitest (unit) + Playwright (e2e) +- UI Components: Custom design system (@appwrite.io/pink-svelte, @appwrite.io/pink-icons-svelte) +- Styling: SCSS with svelte-preprocess + +**Size**: ~1500 files, heavily component-based architecture with extensive routing. + +## Critical Build & Test Commands + +### Prerequisites +**ALWAYS** install pnpm first before any other commands: +```bash +npm install -g corepack +corepack enable +corepack prepare pnpm@10.15.1 --activate +``` + +### Environment Setup +**REQUIRED** before dev or build: Create `.env` file from `.env.example`: +```bash +cp .env.example .env +``` + +Key environment variables (see `.env.example`): +- `PUBLIC_CONSOLE_MODE`: `self-hosted` or `cloud` +- `PUBLIC_APPWRITE_ENDPOINT`: Backend API endpoint (default: `http://localhost/v1`) +- `PUBLIC_APPWRITE_MULTI_REGION`: `true` or `false` +- `PUBLIC_CONSOLE_EMAIL_VERIFICATION`: `true` or `false` +- `PUBLIC_CONSOLE_MOCK_AI_SUGGESTIONS`: `true` or `false` + +### Installation +**ALWAYS** use `--frozen-lockfile` for reproducible builds: +```bash +pnpm install --frozen-lockfile +``` + +**Note**: Some dependencies may fail to download due to network issues (e.g., pkg.pr.new, pkg.vc domains). The build may still succeed if these are optional development dependencies. + +### Commands (in order of typical workflow) + +1. **Install dependencies**: `pnpm install --frozen-lockfile` (required first) +2. **Check TypeScript/Svelte**: `pnpm run check` (~30-60 seconds) +3. **Lint**: `pnpm run lint` (~10-20 seconds) +4. **Format**: `pnpm run format` (auto-fixes formatting issues) +5. **Unit Tests**: `pnpm run test` (runs Vitest with TZ=EST, ~10-30 seconds) +6. **Build**: `pnpm run build` (runs custom build.js script, ~60-120 seconds) +7. **Dev Server**: `pnpm dev` (starts Vite dev server on port 3000) +8. **Preview**: `pnpm run preview` (preview production build on port 4173) +9. **E2E Tests**: `pnpm run e2e` (requires build + preview, ~120+ seconds) + +### CI/CD Pipeline Validation + +**GitHub Actions run on every PR** (see `.github/workflows/tests.yml`): +1. `pnpm audit --audit-level high` (security check) +2. `pnpm install --frozen-lockfile` +3. `pnpm run check` (Svelte diagnostics) +4. `pnpm run lint` +5. `pnpm run test` (unit tests) +6. `pnpm run build` + +**To replicate CI locally**, run these commands in sequence: +```bash +pnpm audit --audit-level high +pnpm install --frozen-lockfile +pnpm run check +pnpm run lint +pnpm run test +pnpm run build +``` + +**E2E Tests** (separate workflow `.github/workflows/e2e.yml`): +```bash +pnpm install --frozen-lockfile +pnpm exec playwright install --with-deps chromium +pnpm run e2e +``` + +## Project Architecture + +### Directory Structure +``` +├── src/ +│ ├── lib/ # Reusable logic (import as '$lib') +│ │ ├── actions/ # Svelte actions +│ │ ├── charts/ # Chart components (ECharts) +│ │ ├── commandCenter/ # Command palette functionality +│ │ ├── components/ # Reusable UI components +│ │ │ ├── billing/ # Billing-related components +│ │ │ ├── domains/ # Domain management +│ │ │ ├── feedback/ # User feedback system +│ │ │ ├── filters/ # Data filtering +│ │ │ ├── permissions/ # Permission management +│ │ │ └── ... # Many other feature areas +│ │ ├── elements/ # Basic UI elements +│ │ ├── helpers/ # Utility functions +│ │ ├── images/ # Image assets +│ │ ├── layout/ # Global layout components (Nav, Container) +│ │ ├── mock/ # Mock components for testing +│ │ ├── sdk/ # Appwrite SDK wrappers +│ │ ├── stores/ # Svelte stores (state management) +│ │ ├── constants.ts # Global constants +│ │ ├── flags.ts # Feature flags +│ │ └── system.ts # System utilities +│ ├── routes/ # SvelteKit file-based routing +│ │ ├── (console)/ # Authenticated routes +│ │ │ ├── organization-[organization]/ # Org-scoped routes +│ │ │ ├── project-[region]-[project]/ # Project-scoped routes +│ │ │ │ ├── databases/ # Database service +│ │ │ │ ├── functions/ # Functions service +│ │ │ │ ├── messaging/ # Messaging service +│ │ │ │ ├── storage/ # Storage service +│ │ │ │ └── ... # Other services +│ │ │ ├── onboarding/ # User onboarding flows +│ │ │ └── wizard/ # Setup wizards +│ │ └── (public)/ # Unauthenticated routes +│ │ ├── (guest)/ # Login, register, etc. +│ │ └── auth/ # OAuth callbacks +│ ├── themes/ # Theme definitions (import as '$themes') +│ ├── app.html # HTML template +│ ├── hooks.client.ts # Client hooks +│ ├── hooks.server.ts # Server hooks +│ └── service-worker.ts # Service worker +├── static/ # Static assets (served as-is) +├── e2e/ # Playwright e2e tests +│ ├── helpers/ # Test helpers +│ ├── steps/ # Test steps +│ └── journeys/ # Test scenarios (*.spec.ts) +├── docker/ # Docker configuration +│ └── nginx.conf # Nginx config for production +├── .github/workflows/ # GitHub Actions +│ ├── tests.yml # Unit tests + build +│ ├── e2e.yml # E2E tests +│ ├── publish.yml # Docker image publishing +│ └── stale.yml # Stale issue management +├── build.js # Custom build script (wraps Vite) +├── vite.config.ts # Vite configuration +├── svelte.config.js # Svelte/SvelteKit configuration +├── tsconfig.json # TypeScript configuration +├── eslint.config.js # ESLint configuration (flat config) +├── .prettierrc # Prettier configuration +├── playwright.config.ts # Playwright configuration +└── Dockerfile # Multi-stage Docker build +``` + +### SvelteKit Routing Conventions +- `+page.svelte`: Page component +- `+page.ts`: Page data loader (runs before component) +- `+layout.svelte`: Layout wrapper for nested routes +- `+layout.ts`: Layout data loader +- `+error.svelte`: Error boundary +- `(console)/`: Route group (doesn't affect URL, used for organization) +- `[param]/`: Dynamic route parameter + +### Key Configuration Files + +**svelte.config.js**: +- Adapter: `@sveltejs/adapter-static` (SPA mode with fallback to index.html) +- Base path: `/console` (unless PREVIEW env var set) +- Aliases: `$routes` → `./src/routes`, `$themes` → `./src/themes` +- Preprocessors: SCSS + Melt UI + +**vite.config.ts**: +- Dev server port: 3000 +- Vitest configured with two projects: "client" (jsdom) and "server" (node) +- Client tests: `src/**/*.svelte.{test,spec}.{js,ts}` +- Server tests: `src/**/*.{test,spec}.{js,ts}` (excluding `.svelte.` files) +- SSR noExternal: analytics, dayjs, echarts, prismjs, zrender + +**tsconfig.json**: +- Extends `.svelte-kit/tsconfig.json` (auto-generated) +- **NOT strict**: `strict: false` +- Unused locals/parameters flagged: `noUnusedLocals: true`, `noUnusedParameters: true` + +**eslint.config.js**: +- Flat config format (ESLint 9+) +- Many rules temporarily disabled (see TODOs in file) +- Svelte plugin configured with parser for `.svelte` files + +**.prettierrc**: +- 4 spaces (not tabs) +- Single quotes +- No trailing commas +- 100 char line width +- Bracket same line + +### Testing + +**Unit Tests (Vitest)**: +- Setup: `vitest-setup-client.ts` mocks SvelteKit modules +- Location: `src/lib/helpers/*.test.ts`, `src/routes/**/store.test.ts` +- Run with: `TZ=EST vitest run` (timezone matters for date tests) +- Environment: jsdom for client tests, node for server tests + +**E2E Tests (Playwright)**: +- Location: `e2e/journeys/*.spec.ts` +- Requires: Build + preview server running on port 4173 +- Browser: Chromium only (install with `pnpm exec playwright install --with-deps chromium`) +- Retries: 3 (configured in playwright.config.ts) +- Timeout: 120 seconds per test + +## Common Pitfalls & Workarounds + +1. **Blank page after `pnpm dev`**: If browser console shows `TypeError: Failed to fetch dynamically imported module`, disable ad blockers and reload. This is a known SvelteKit issue. + +2. **Network errors during install**: Dependencies from `pkg.pr.new` and `pkg.vc` may fail due to network restrictions. These are often optional; continue if other dependencies install successfully. + +3. **Build fails with memory error**: The Dockerfile sets `NODE_OPTIONS=--max_old_space_size=8192`. If building locally fails with OOM, set this environment variable. + +4. **Tests fail with timezone issues**: Unit tests run with `TZ=EST`. Always use `pnpm run test` instead of `vitest` directly. + +5. **TypeScript errors not showing**: Run `pnpm run check` explicitly. The dev server doesn't always surface TS errors. + +6. **Linter vs formatter conflicts**: Run `pnpm run format` before `pnpm run lint`. Prettier formats, then ESLint checks logic. + +7. **E2E tests timeout**: Ensure preview server is fully started (wait 120s). Tests retry 3 times automatically. + +8. **Changes not reflected in build**: Clear `.svelte-kit` directory: `rm -rf .svelte-kit && pnpm run build` + +## Code Style & Conventions + +- **Imports**: Use `$lib` alias for `src/lib`, `$routes` for `src/routes`, `$themes` for `src/themes` +- **Components**: PascalCase filenames, organized by feature in `src/lib/components/[feature]/` +- **Stores**: Svelte stores in `src/lib/stores/`, use derived stores for computed values +- **Helpers**: Pure utility functions in `src/lib/helpers/` +- **Types**: Inline types or in `.d.ts` files, not in separate `.types.ts` files +- **Comments**: Minimal; use for TODOs (`// TODO:`) or complex logic only +- **No strict TypeScript**: Many `any` types tolerated, focus on functionality over perfect typing + +## Development Workflow + +1. **Start backend**: Run Appwrite locally (see [docs](https://appwrite.io/docs/advanced/self-hosting)) +2. **Configure environment**: Ensure `.env` points to backend endpoint +3. **Install**: `pnpm install --frozen-lockfile` +4. **Develop**: `pnpm dev` (hot reload enabled) +5. **Check types**: `pnpm run check` (frequently, especially before committing) +6. **Format**: `pnpm run format` (before committing) +7. **Test**: `pnpm run test` (unit tests) +8. **Build**: `pnpm run build` (validate production build) +9. **E2E** (optional): `pnpm run e2e` (if touching critical flows) + +## Security & Dependencies + +- **Audit on every PR**: `pnpm audit --audit-level high` runs in CI +- **Frozen lockfile**: Always use `--frozen-lockfile` to prevent supply chain attacks +- **Update dependencies carefully**: Discuss with team before adding/updating (see CONTRIBUTING.md) +- **Sentry**: Integrated for error tracking (requires `SENTRY_AUTH_TOKEN` for production builds) + +## Final Notes + +- **Trust these instructions**: Only search/explore if information is incomplete or incorrect +- **Read CONTRIBUTING.md**: Required reading for contribution guidelines and PR conventions +- **Check feature flags**: Some features gated by `PUBLIC_CONSOLE_FEATURE_FLAGS` env var +- **Backend dependency**: Console requires Appwrite backend running; mock mode available with `PUBLIC_CONSOLE_MOCK_AI_SUGGESTIONS=true` +- **Docker builds**: Use multi-stage build in Dockerfile; final image is nginx serving static files +- **Path configuration**: All routes prefixed with `/console` in production (see svelte.config.js) From a3d727404944ae93a83f35451959df87c27bcb6b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 28 Oct 2025 14:59:34 +0000 Subject: [PATCH 3/8] Optimize copilot-instructions.md to fit within 2 pages Co-authored-by: stnguyen90 <1477010+stnguyen90@users.noreply.github.com> --- .github/copilot-instructions.md | 303 +++++++------------------------- 1 file changed, 65 insertions(+), 238 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f0555fde52..8d4901e752 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,265 +2,92 @@ ## Repository Overview -**What it is**: Appwrite Console is the web-based Graphical User Interface for developers to interact with their Appwrite instance. It's a production-ready single-page application serving as the front-end dashboard for the Appwrite backend-as-a-service platform. - -**Tech Stack**: -- Framework: Svelte 5 + SvelteKit 2 -- Language: TypeScript (not strictly typed - `strict: false` in tsconfig) -- Build Tool: Vite 7 -- Package Manager: pnpm 10.15.1 -- Node Version: 20+ -- Testing: Vitest (unit) + Playwright (e2e) -- UI Components: Custom design system (@appwrite.io/pink-svelte, @appwrite.io/pink-icons-svelte) -- Styling: SCSS with svelte-preprocess - -**Size**: ~1500 files, heavily component-based architecture with extensive routing. +Appwrite Console is the web-based GUI for the Appwrite backend-as-a-service platform. Single-page application built with **Svelte 5 + SvelteKit 2**, **TypeScript** (not strict mode), **Vite 7**, tested with **Vitest + Playwright**. Package manager: **pnpm 10.15.1**, Node 20+. ~1500 files with extensive component-based architecture. ## Critical Build & Test Commands -### Prerequisites -**ALWAYS** install pnpm first before any other commands: -```bash -npm install -g corepack -corepack enable -corepack prepare pnpm@10.15.1 --activate -``` - -### Environment Setup -**REQUIRED** before dev or build: Create `.env` file from `.env.example`: -```bash -cp .env.example .env -``` - -Key environment variables (see `.env.example`): -- `PUBLIC_CONSOLE_MODE`: `self-hosted` or `cloud` -- `PUBLIC_APPWRITE_ENDPOINT`: Backend API endpoint (default: `http://localhost/v1`) -- `PUBLIC_APPWRITE_MULTI_REGION`: `true` or `false` -- `PUBLIC_CONSOLE_EMAIL_VERIFICATION`: `true` or `false` -- `PUBLIC_CONSOLE_MOCK_AI_SUGGESTIONS`: `true` or `false` - -### Installation -**ALWAYS** use `--frozen-lockfile` for reproducible builds: -```bash -pnpm install --frozen-lockfile -``` +### Setup (REQUIRED before any commands) -**Note**: Some dependencies may fail to download due to network issues (e.g., pkg.pr.new, pkg.vc domains). The build may still succeed if these are optional development dependencies. +1. **Install pnpm**: `npm install -g corepack && corepack enable && corepack prepare pnpm@10.15.1 --activate` +2. **Create .env**: `cp .env.example .env` (configure `PUBLIC_APPWRITE_ENDPOINT` and `PUBLIC_CONSOLE_MODE`) +3. **Install dependencies**: `pnpm install --frozen-lockfile` (some pkg.pr.new/pkg.vc deps may fail - usually safe to ignore) -### Commands (in order of typical workflow) +### Development Commands -1. **Install dependencies**: `pnpm install --frozen-lockfile` (required first) -2. **Check TypeScript/Svelte**: `pnpm run check` (~30-60 seconds) -3. **Lint**: `pnpm run lint` (~10-20 seconds) -4. **Format**: `pnpm run format` (auto-fixes formatting issues) -5. **Unit Tests**: `pnpm run test` (runs Vitest with TZ=EST, ~10-30 seconds) -6. **Build**: `pnpm run build` (runs custom build.js script, ~60-120 seconds) -7. **Dev Server**: `pnpm dev` (starts Vite dev server on port 3000) -8. **Preview**: `pnpm run preview` (preview production build on port 4173) -9. **E2E Tests**: `pnpm run e2e` (requires build + preview, ~120+ seconds) +**Standard workflow**: `check` → `lint` → `test` → `build` (before committing) -### CI/CD Pipeline Validation +- `pnpm run check` - TypeScript/Svelte validation (~30-60s) +- `pnpm run lint` - ESLint check (~10-20s) +- `pnpm run format` - Auto-fix Prettier formatting +- `pnpm run test` - Vitest unit tests with TZ=EST (~10-30s) +- `pnpm run build` - Production build via build.js (~60-120s) +- `pnpm dev` - Dev server on port 3000 +- `pnpm run preview` - Preview build on port 4173 +- `pnpm run e2e` - Playwright tests (needs `pnpm exec playwright install --with-deps chromium` first, ~120s+) -**GitHub Actions run on every PR** (see `.github/workflows/tests.yml`): -1. `pnpm audit --audit-level high` (security check) -2. `pnpm install --frozen-lockfile` -3. `pnpm run check` (Svelte diagnostics) -4. `pnpm run lint` -5. `pnpm run test` (unit tests) -6. `pnpm run build` +**CI Pipeline** (`.github/workflows/tests.yml`): audit → install → check → lint → test → build -**To replicate CI locally**, run these commands in sequence: -```bash -pnpm audit --audit-level high -pnpm install --frozen-lockfile -pnpm run check -pnpm run lint -pnpm run test -pnpm run build -``` +## Project Structure -**E2E Tests** (separate workflow `.github/workflows/e2e.yml`): -```bash -pnpm install --frozen-lockfile -pnpm exec playwright install --with-deps chromium -pnpm run e2e ``` - -## Project Architecture - -### Directory Structure +src/ +├── lib/ # Reusable logic ($lib alias) +│ ├── components/ # Feature components (billing, domains, permissions, etc.) +│ ├── elements/ # Basic UI elements +│ ├── helpers/ # Utility functions (array, date, string, etc.) +│ ├── stores/ # Svelte stores for state +│ ├── sdk/ # Appwrite SDK wrappers +│ └── constants.ts, flags.ts, system.ts +├── routes/ +│ ├── (console)/ # Auth-required routes +│ │ ├── organization-[organization]/ +│ │ └── project-[region]-[project]/ # databases, functions, messaging, storage +│ └── (public)/ # Public routes (login, register, auth callbacks) +├── themes/ # Theme definitions ($themes alias) +└── app.html, hooks.{client,server}.ts, service-worker.ts ``` -├── src/ -│ ├── lib/ # Reusable logic (import as '$lib') -│ │ ├── actions/ # Svelte actions -│ │ ├── charts/ # Chart components (ECharts) -│ │ ├── commandCenter/ # Command palette functionality -│ │ ├── components/ # Reusable UI components -│ │ │ ├── billing/ # Billing-related components -│ │ │ ├── domains/ # Domain management -│ │ │ ├── feedback/ # User feedback system -│ │ │ ├── filters/ # Data filtering -│ │ │ ├── permissions/ # Permission management -│ │ │ └── ... # Many other feature areas -│ │ ├── elements/ # Basic UI elements -│ │ ├── helpers/ # Utility functions -│ │ ├── images/ # Image assets -│ │ ├── layout/ # Global layout components (Nav, Container) -│ │ ├── mock/ # Mock components for testing -│ │ ├── sdk/ # Appwrite SDK wrappers -│ │ ├── stores/ # Svelte stores (state management) -│ │ ├── constants.ts # Global constants -│ │ ├── flags.ts # Feature flags -│ │ └── system.ts # System utilities -│ ├── routes/ # SvelteKit file-based routing -│ │ ├── (console)/ # Authenticated routes -│ │ │ ├── organization-[organization]/ # Org-scoped routes -│ │ │ ├── project-[region]-[project]/ # Project-scoped routes -│ │ │ │ ├── databases/ # Database service -│ │ │ │ ├── functions/ # Functions service -│ │ │ │ ├── messaging/ # Messaging service -│ │ │ │ ├── storage/ # Storage service -│ │ │ │ └── ... # Other services -│ │ │ ├── onboarding/ # User onboarding flows -│ │ │ └── wizard/ # Setup wizards -│ │ └── (public)/ # Unauthenticated routes -│ │ ├── (guest)/ # Login, register, etc. -│ │ └── auth/ # OAuth callbacks -│ ├── themes/ # Theme definitions (import as '$themes') -│ ├── app.html # HTML template -│ ├── hooks.client.ts # Client hooks -│ ├── hooks.server.ts # Server hooks -│ └── service-worker.ts # Service worker -├── static/ # Static assets (served as-is) -├── e2e/ # Playwright e2e tests -│ ├── helpers/ # Test helpers -│ ├── steps/ # Test steps -│ └── journeys/ # Test scenarios (*.spec.ts) -├── docker/ # Docker configuration -│ └── nginx.conf # Nginx config for production -├── .github/workflows/ # GitHub Actions -│ ├── tests.yml # Unit tests + build -│ ├── e2e.yml # E2E tests -│ ├── publish.yml # Docker image publishing -│ └── stale.yml # Stale issue management -├── build.js # Custom build script (wraps Vite) -├── vite.config.ts # Vite configuration -├── svelte.config.js # Svelte/SvelteKit configuration -├── tsconfig.json # TypeScript configuration -├── eslint.config.js # ESLint configuration (flat config) -├── .prettierrc # Prettier configuration -├── playwright.config.ts # Playwright configuration -└── Dockerfile # Multi-stage Docker build -``` - -### SvelteKit Routing Conventions -- `+page.svelte`: Page component -- `+page.ts`: Page data loader (runs before component) -- `+layout.svelte`: Layout wrapper for nested routes -- `+layout.ts`: Layout data loader -- `+error.svelte`: Error boundary -- `(console)/`: Route group (doesn't affect URL, used for organization) -- `[param]/`: Dynamic route parameter - -### Key Configuration Files - -**svelte.config.js**: -- Adapter: `@sveltejs/adapter-static` (SPA mode with fallback to index.html) -- Base path: `/console` (unless PREVIEW env var set) -- Aliases: `$routes` → `./src/routes`, `$themes` → `./src/themes` -- Preprocessors: SCSS + Melt UI - -**vite.config.ts**: -- Dev server port: 3000 -- Vitest configured with two projects: "client" (jsdom) and "server" (node) -- Client tests: `src/**/*.svelte.{test,spec}.{js,ts}` -- Server tests: `src/**/*.{test,spec}.{js,ts}` (excluding `.svelte.` files) -- SSR noExternal: analytics, dayjs, echarts, prismjs, zrender - -**tsconfig.json**: -- Extends `.svelte-kit/tsconfig.json` (auto-generated) -- **NOT strict**: `strict: false` -- Unused locals/parameters flagged: `noUnusedLocals: true`, `noUnusedParameters: true` - -**eslint.config.js**: -- Flat config format (ESLint 9+) -- Many rules temporarily disabled (see TODOs in file) -- Svelte plugin configured with parser for `.svelte` files - -**.prettierrc**: -- 4 spaces (not tabs) -- Single quotes -- No trailing commas -- 100 char line width -- Bracket same line - -### Testing - -**Unit Tests (Vitest)**: -- Setup: `vitest-setup-client.ts` mocks SvelteKit modules -- Location: `src/lib/helpers/*.test.ts`, `src/routes/**/store.test.ts` -- Run with: `TZ=EST vitest run` (timezone matters for date tests) -- Environment: jsdom for client tests, node for server tests - -**E2E Tests (Playwright)**: -- Location: `e2e/journeys/*.spec.ts` -- Requires: Build + preview server running on port 4173 -- Browser: Chromium only (install with `pnpm exec playwright install --with-deps chromium`) -- Retries: 3 (configured in playwright.config.ts) -- Timeout: 120 seconds per test - -## Common Pitfalls & Workarounds - -1. **Blank page after `pnpm dev`**: If browser console shows `TypeError: Failed to fetch dynamically imported module`, disable ad blockers and reload. This is a known SvelteKit issue. - -2. **Network errors during install**: Dependencies from `pkg.pr.new` and `pkg.vc` may fail due to network restrictions. These are often optional; continue if other dependencies install successfully. - -3. **Build fails with memory error**: The Dockerfile sets `NODE_OPTIONS=--max_old_space_size=8192`. If building locally fails with OOM, set this environment variable. - -4. **Tests fail with timezone issues**: Unit tests run with `TZ=EST`. Always use `pnpm run test` instead of `vitest` directly. -5. **TypeScript errors not showing**: Run `pnpm run check` explicitly. The dev server doesn't always surface TS errors. +**SvelteKit conventions**: `+page.svelte` (component), `+page.ts` (data loader), `+layout.svelte` (wrapper), `+error.svelte` (errors). Groups like `(console)` organize routes without affecting URLs. Dynamic params: `[param]`. -6. **Linter vs formatter conflicts**: Run `pnpm run format` before `pnpm run lint`. Prettier formats, then ESLint checks logic. +## Key Configuration -7. **E2E tests timeout**: Ensure preview server is fully started (wait 120s). Tests retry 3 times automatically. +**svelte.config.js**: Adapter = static SPA (fallback: index.html), base path `/console`, aliases: `$lib`, `$routes`, `$themes` +**vite.config.ts**: Dev port 3000, Vitest (client=jsdom, server=node), test files: `src/**/*.{test,spec}.{js,ts}` +**tsconfig.json**: Extends `.svelte-kit/tsconfig.json`, **NOT strict mode** (`strict: false`) +**eslint.config.js**: Flat config (ESLint 9+), many rules disabled (see TODOs) +**.prettierrc**: 4 spaces, single quotes, 100 char width, no trailing commas -8. **Changes not reflected in build**: Clear `.svelte-kit` directory: `rm -rf .svelte-kit && pnpm run build` +## Testing -## Code Style & Conventions +**Unit (Vitest)**: Tests in `src/lib/helpers/*.test.ts`, run with `TZ=EST` (timezone matters). Setup mocks SvelteKit (`$app/*`) in `vitest-setup-client.ts`. +**E2E (Playwright)**: Tests in `e2e/journeys/*.spec.ts`, needs build+preview on port 4173, retries 3x, timeout 120s, Chromium only. -- **Imports**: Use `$lib` alias for `src/lib`, `$routes` for `src/routes`, `$themes` for `src/themes` -- **Components**: PascalCase filenames, organized by feature in `src/lib/components/[feature]/` -- **Stores**: Svelte stores in `src/lib/stores/`, use derived stores for computed values -- **Helpers**: Pure utility functions in `src/lib/helpers/` -- **Types**: Inline types or in `.d.ts` files, not in separate `.types.ts` files -- **Comments**: Minimal; use for TODOs (`// TODO:`) or complex logic only -- **No strict TypeScript**: Many `any` types tolerated, focus on functionality over perfect typing +## Common Pitfalls -## Development Workflow +1. **Blank page in dev**: Disable ad blockers if seeing "Failed to fetch dynamically imported module" (known SvelteKit issue) +2. **Network errors on install**: pkg.pr.new/pkg.vc deps may fail - usually safe to continue +3. **OOM on build**: Set `NODE_OPTIONS=--max_old_space_size=8192` (like Dockerfile does) +4. **Test failures**: Always use `pnpm run test` (sets TZ=EST), not `vitest` directly +5. **TS errors not showing**: Run `pnpm run check` explicitly (dev server doesn't always surface them) +6. **Format vs lint conflicts**: Run `pnpm run format` before `pnpm run lint` +7. **E2E timeouts**: Wait 120s for preview server startup, tests auto-retry 3x +8. **Stale build**: Clear `.svelte-kit` if changes not reflected: `rm -rf .svelte-kit && pnpm run build` -1. **Start backend**: Run Appwrite locally (see [docs](https://appwrite.io/docs/advanced/self-hosting)) -2. **Configure environment**: Ensure `.env` points to backend endpoint -3. **Install**: `pnpm install --frozen-lockfile` -4. **Develop**: `pnpm dev` (hot reload enabled) -5. **Check types**: `pnpm run check` (frequently, especially before committing) -6. **Format**: `pnpm run format` (before committing) -7. **Test**: `pnpm run test` (unit tests) -8. **Build**: `pnpm run build` (validate production build) -9. **E2E** (optional): `pnpm run e2e` (if touching critical flows) +## Code Conventions -## Security & Dependencies +- Imports: Use `$lib`, `$routes`, `$themes` aliases +- Components: PascalCase, in `src/lib/components/[feature]/` +- Helpers: Pure functions in `src/lib/helpers/` +- Types: Inline or `.d.ts`, not `.types.ts` files +- Comments: Minimal, use for TODOs or complex logic +- TypeScript: Not strict mode, `any` tolerated -- **Audit on every PR**: `pnpm audit --audit-level high` runs in CI -- **Frozen lockfile**: Always use `--frozen-lockfile` to prevent supply chain attacks -- **Update dependencies carefully**: Discuss with team before adding/updating (see CONTRIBUTING.md) -- **Sentry**: Integrated for error tracking (requires `SENTRY_AUTH_TOKEN` for production builds) +## Workflow -## Final Notes +1. Run Appwrite backend locally (see [docs](https://appwrite.io/docs/advanced/self-hosting)) +2. Configure `.env` with backend endpoint +3. `pnpm install --frozen-lockfile` +4. `pnpm dev` (hot reload on port 3000) +5. Before commit: `pnpm run check && pnpm run format && pnpm run lint && pnpm run test && pnpm run build` -- **Trust these instructions**: Only search/explore if information is incomplete or incorrect -- **Read CONTRIBUTING.md**: Required reading for contribution guidelines and PR conventions -- **Check feature flags**: Some features gated by `PUBLIC_CONSOLE_FEATURE_FLAGS` env var -- **Backend dependency**: Console requires Appwrite backend running; mock mode available with `PUBLIC_CONSOLE_MOCK_AI_SUGGESTIONS=true` -- **Docker builds**: Use multi-stage build in Dockerfile; final image is nginx serving static files -- **Path configuration**: All routes prefixed with `/console` in production (see svelte.config.js) +**Trust these instructions** - only search if incomplete/incorrect. See CONTRIBUTING.md for PR conventions. Use `--frozen-lockfile` always. Docker builds: multi-stage, final image is nginx serving static files from `/console` path. From 300b435cfeb4c0a34da96978fcbd4d0ec01772cf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 28 Oct 2025 17:12:57 +0000 Subject: [PATCH 4/8] Add network access configuration steps for pkg.pr.new and pkg.vc Co-authored-by: stnguyen90 <1477010+stnguyen90@users.noreply.github.com> --- .github/copilot-instructions.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8d4901e752..1fffcca18f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -10,7 +10,12 @@ Appwrite Console is the web-based GUI for the Appwrite backend-as-a-service plat 1. **Install pnpm**: `npm install -g corepack && corepack enable && corepack prepare pnpm@10.15.1 --activate` 2. **Create .env**: `cp .env.example .env` (configure `PUBLIC_APPWRITE_ENDPOINT` and `PUBLIC_CONSOLE_MODE`) -3. **Install dependencies**: `pnpm install --frozen-lockfile` (some pkg.pr.new/pkg.vc deps may fail - usually safe to ignore) +3. **Configure network access** (if using GitHub Actions or restricted environments): + - Ensure firewall/proxy allows access to: `pkg.pr.new`, `pkg.vc`, `registry.npmjs.org` + - These domains are required for dependencies: `@appwrite.io/console`, `@appwrite.io/pink-icons-svelte`, `@appwrite.io/pink-svelte` + - In GitHub Actions: Use `pnpm/action-setup@v4` which handles registry configuration + - If network errors persist, check proxy settings: `npm config get proxy` and `npm config get https-proxy` +4. **Install dependencies**: `pnpm install --frozen-lockfile` (if pkg.pr.new/pkg.vc fail due to network restrictions, installation may still succeed with cached versions) ### Development Commands @@ -65,7 +70,12 @@ src/ ## Common Pitfalls 1. **Blank page in dev**: Disable ad blockers if seeing "Failed to fetch dynamically imported module" (known SvelteKit issue) -2. **Network errors on install**: pkg.pr.new/pkg.vc deps may fail - usually safe to continue +2. **Network errors on install**: + - pkg.pr.new/pkg.vc deps may fail due to firewall/proxy restrictions + - Check access: `curl -I https://pkg.pr.new` and `curl -I https://pkg.vc` + - Configure proxy if needed: `npm config set proxy http://proxy:port` and `npm config set https-proxy http://proxy:port` + - GitHub Actions: Ensure runner has internet access; use `pnpm/action-setup@v4` action + - Local dev: Often safe to continue with cached versions if network fails 3. **OOM on build**: Set `NODE_OPTIONS=--max_old_space_size=8192` (like Dockerfile does) 4. **Test failures**: Always use `pnpm run test` (sets TZ=EST), not `vitest` directly 5. **TS errors not showing**: Run `pnpm run check` explicitly (dev server doesn't always surface them) From 299573fa7c598f211dfaa22ebb9700bb69d67efd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 28 Oct 2025 18:43:54 +0000 Subject: [PATCH 5/8] Move firewall config to dedicated GitHub Actions Setup section Co-authored-by: stnguyen90 <1477010+stnguyen90@users.noreply.github.com> --- .github/copilot-instructions.md | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1fffcca18f..2d8e01edbe 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -10,12 +10,24 @@ Appwrite Console is the web-based GUI for the Appwrite backend-as-a-service plat 1. **Install pnpm**: `npm install -g corepack && corepack enable && corepack prepare pnpm@10.15.1 --activate` 2. **Create .env**: `cp .env.example .env` (configure `PUBLIC_APPWRITE_ENDPOINT` and `PUBLIC_CONSOLE_MODE`) -3. **Configure network access** (if using GitHub Actions or restricted environments): - - Ensure firewall/proxy allows access to: `pkg.pr.new`, `pkg.vc`, `registry.npmjs.org` - - These domains are required for dependencies: `@appwrite.io/console`, `@appwrite.io/pink-icons-svelte`, `@appwrite.io/pink-svelte` - - In GitHub Actions: Use `pnpm/action-setup@v4` which handles registry configuration - - If network errors persist, check proxy settings: `npm config get proxy` and `npm config get https-proxy` -4. **Install dependencies**: `pnpm install --frozen-lockfile` (if pkg.pr.new/pkg.vc fail due to network restrictions, installation may still succeed with cached versions) +3. **Install dependencies**: `pnpm install --frozen-lockfile` + +### GitHub Actions Setup + +When running in GitHub Actions, ensure network access to required package registries: + +**Required domains** (add to firewall allowlist): +- `pkg.pr.new` - Required for `@appwrite.io/console` dependency +- `pkg.vc` - Required for `@appwrite.io/pink-icons-svelte` and `@appwrite.io/pink-svelte` dependencies +- `registry.npmjs.org` - Standard npm registry + +**Action configuration**: +```yaml +- name: Install pnpm + uses: pnpm/action-setup@v4 +``` + +The `pnpm/action-setup@v4` action handles registry configuration automatically. If installation fails with ENOTFOUND errors for pkg.pr.new or pkg.vc, verify runner has internet access and these domains are not blocked by firewall/proxy. ### Development Commands @@ -74,8 +86,7 @@ src/ - pkg.pr.new/pkg.vc deps may fail due to firewall/proxy restrictions - Check access: `curl -I https://pkg.pr.new` and `curl -I https://pkg.vc` - Configure proxy if needed: `npm config set proxy http://proxy:port` and `npm config set https-proxy http://proxy:port` - - GitHub Actions: Ensure runner has internet access; use `pnpm/action-setup@v4` action - - Local dev: Often safe to continue with cached versions if network fails + - Local dev: Installation may still succeed with cached versions if network fails 3. **OOM on build**: Set `NODE_OPTIONS=--max_old_space_size=8192` (like Dockerfile does) 4. **Test failures**: Always use `pnpm run test` (sets TZ=EST), not `vitest` directly 5. **TS errors not showing**: Run `pnpm run check` explicitly (dev server doesn't always surface them) From 73e9b822363524652a59e6240a5bfe7b651eb499 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 28 Oct 2025 18:55:01 +0000 Subject: [PATCH 6/8] Revert GitHub Actions Setup section changes Co-authored-by: stnguyen90 <1477010+stnguyen90@users.noreply.github.com> --- .github/copilot-instructions.md | 27 ++++++++------------------- 1 file changed, 8 insertions(+), 19 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 2d8e01edbe..1fffcca18f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -10,24 +10,12 @@ Appwrite Console is the web-based GUI for the Appwrite backend-as-a-service plat 1. **Install pnpm**: `npm install -g corepack && corepack enable && corepack prepare pnpm@10.15.1 --activate` 2. **Create .env**: `cp .env.example .env` (configure `PUBLIC_APPWRITE_ENDPOINT` and `PUBLIC_CONSOLE_MODE`) -3. **Install dependencies**: `pnpm install --frozen-lockfile` - -### GitHub Actions Setup - -When running in GitHub Actions, ensure network access to required package registries: - -**Required domains** (add to firewall allowlist): -- `pkg.pr.new` - Required for `@appwrite.io/console` dependency -- `pkg.vc` - Required for `@appwrite.io/pink-icons-svelte` and `@appwrite.io/pink-svelte` dependencies -- `registry.npmjs.org` - Standard npm registry - -**Action configuration**: -```yaml -- name: Install pnpm - uses: pnpm/action-setup@v4 -``` - -The `pnpm/action-setup@v4` action handles registry configuration automatically. If installation fails with ENOTFOUND errors for pkg.pr.new or pkg.vc, verify runner has internet access and these domains are not blocked by firewall/proxy. +3. **Configure network access** (if using GitHub Actions or restricted environments): + - Ensure firewall/proxy allows access to: `pkg.pr.new`, `pkg.vc`, `registry.npmjs.org` + - These domains are required for dependencies: `@appwrite.io/console`, `@appwrite.io/pink-icons-svelte`, `@appwrite.io/pink-svelte` + - In GitHub Actions: Use `pnpm/action-setup@v4` which handles registry configuration + - If network errors persist, check proxy settings: `npm config get proxy` and `npm config get https-proxy` +4. **Install dependencies**: `pnpm install --frozen-lockfile` (if pkg.pr.new/pkg.vc fail due to network restrictions, installation may still succeed with cached versions) ### Development Commands @@ -86,7 +74,8 @@ src/ - pkg.pr.new/pkg.vc deps may fail due to firewall/proxy restrictions - Check access: `curl -I https://pkg.pr.new` and `curl -I https://pkg.vc` - Configure proxy if needed: `npm config set proxy http://proxy:port` and `npm config set https-proxy http://proxy:port` - - Local dev: Installation may still succeed with cached versions if network fails + - GitHub Actions: Ensure runner has internet access; use `pnpm/action-setup@v4` action + - Local dev: Often safe to continue with cached versions if network fails 3. **OOM on build**: Set `NODE_OPTIONS=--max_old_space_size=8192` (like Dockerfile does) 4. **Test failures**: Always use `pnpm run test` (sets TZ=EST), not `vitest` directly 5. **TS errors not showing**: Run `pnpm run check` explicitly (dev server doesn't always surface them) From 4ab3df1dee450a08b9589b64823ebcdb123159a4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Oct 2025 18:05:21 +0000 Subject: [PATCH 7/8] Add screenshot instruction to workflow section Co-authored-by: stnguyen90 <1477010+stnguyen90@users.noreply.github.com> --- .github/copilot-instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1fffcca18f..a66e705697 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -99,5 +99,6 @@ src/ 3. `pnpm install --frozen-lockfile` 4. `pnpm dev` (hot reload on port 3000) 5. Before commit: `pnpm run check && pnpm run format && pnpm run lint && pnpm run test && pnpm run build` +6. **Take screenshots**: For any UI changes, capture screenshots and include them in the PR description or comments before finalizing **Trust these instructions** - only search if incomplete/incorrect. See CONTRIBUTING.md for PR conventions. Use `--frozen-lockfile` always. Docker builds: multi-stage, final image is nginx serving static files from `/console` path. From 4b411b00424ab0970af19eece63371b1e81aa2e5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Oct 2025 21:15:51 +0000 Subject: [PATCH 8/8] Rename copilot-instructions.md to AGENTS.md and move to root Co-authored-by: stnguyen90 <1477010+stnguyen90@users.noreply.github.com> --- .github/copilot-instructions.md => AGENTS.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/copilot-instructions.md => AGENTS.md (100%) diff --git a/.github/copilot-instructions.md b/AGENTS.md similarity index 100% rename from .github/copilot-instructions.md rename to AGENTS.md