Skip to content

Modern Docker Management, Designed for Everyone

chore(vscode): add recommended extensions

Kyle Mendell539e00ba00b6
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 2782c1caa..ca832b516 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,11 +1,68 @@
+# Arcane — Copilot / AI agent quick instructions
+
+Purpose: Get an AI coding agent productive quickly. Make small, well-scoped edits, follow repository wiring, and run the provided dev script for integrated testing, dont make useless comments that dont help the codebase.
+
+Quick architecture summary
+
+- Backend: Go (cmd/main.go) + Gin. App wiring and DI live in `internal/bootstrap/`. DB via GORM; models under `internal/models/`. Handlers in `internal/api/*_handler.go`, services in `internal/services/*_service.go`.
+- Frontend: SvelteKit (frontend/src) using Svelte 5 syntax (runes). Routes: `frontend/src/routes/`. Shared components: `frontend/src/lib/components/`.
+- Integration: Docker + local containers. Entry scripts: `scripts/docker/entrypoint.sh` and `docker/entrypoint.sh`.
+
+Essential workflows (commands)
+
+- Start dev env (recommended): `./scripts/development/dev.sh start` (VS Code task "Start").
+- Stop / Restart / Rebuild: same script with `stop|restart|rebuild|clean`.
+- Frontend local build: use `frontend/package.json` scripts (or run inside the dev containers).
+- Tests: Playwright E2E specs in `tests/spec/*.ts`; helpers in `tests/` and `setup/`.
+
+Project-specific conventions (follow exactly)
+
+- Keep HTTP handlers thin — push business logic into `internal/services/*_service.go`.
+- File naming: `*_handler.go`, `*_service.go`, DTOs in `internal/dto/`.
+- Use DTOs for API boundaries; frontend also has DTOs under `frontend/src/lib/dto/`.
+- Database models include `BaseModel` fields and may implement `TableName()` for custom names.
+- Svelte 5: use `$state()/$effect()/$derived()` and `let { prop } = $props()` patterns. Frontend files use Svelte 5 runes consistently.
+
+Where to look when adding features or debugging
+
+- Startup & wiring: `internal/bootstrap/` -> `cmd/main.go`.
+- API endpoints and handlers: `internal/api/`.
+- Services and business logic: `internal/services/`.
+- Frontend pages & components: `frontend/src/routes/` and `frontend/src/lib/components/`.
+- Docker/dev scripts: `scripts/development/dev.sh`, `docker-compose*.yml`, and `scripts/docker/entrypoint.sh`.
+
+Tests & CI notes
+
+- Playwright E2E lives in `tests/` and is configured via `tests/package.json` and `playwright.config.ts`.
+- Backend unit tests should mock Docker client calls where possible.
+
+Safe-edit checklist for AI agents
+
+1. Make minimal changes and run `go build ./...` if you change backend code.
+2. Run frontend build (`pnpm -w -C frontend build`) or use the dev script for integrated runs.
+3. Do not commit secrets or change environment wiring; use `dev.sh` for env setup.
+
+Examples (copyable patterns)
+
+- New handler: add `internal/api/foo_handler.go` that binds request DTO, calls `services.NewFooService(db, docker).Create(...)`, and returns JSON.
+- New service: `internal/services/foo_service.go` that accepts DB and Docker clients from bootstrap and implements business logic; return wrapped errors with `fmt.Errorf("context: %w", err)`.
+
+If unclear
+
+- Ask to inspect a specific file (path) and whether you want me to run build/tests. I'll run them and return results.
+
+— End of concise instructions —
+
# Arcane Docker Management UI - Copilot Instructions
## Project Overview
+
Arcane is a modern, full-stack Docker management UI built with SvelteKit frontend and Go backend. It provides comprehensive Docker environment management including containers, images, volumes, networks, stacks, and image update tracking.
## Architecture & Tech Stack
### Backend (Go)
+
- **Framework**: Gin web framework with Go 1.24.3+
- **Database**: GORM with PostgreSQL/SQLite support
- **Structure**: Clean architecture with bootstrap pattern
@@ -14,6 +71,7 @@ Arcane is a modern, full-stack Docker management UI built with SvelteKit fronten
- **Docker**: Official Docker SDK integration
### Frontend (SvelteKit + TypeScript)
+
- **Framework**: SvelteKit with Svelte 5 syntax
- **UI**: shadcn-svelte components + Tailwind CSS
- **Icons**: Lucide Svelte
@@ -26,13 +84,14 @@ Arcane is a modern, full-stack Docker management UI built with SvelteKit fronten
### Backend (Go)
#### File Organization
+
```
backend/
├── cmd/main.go # Application entry point
├── internal/
│ ├── bootstrap/ # App initialization (DI container pattern)
│ ├── api/ # HTTP handlers (*_handler.go)
-│ ├── services/ # Business logic (*_service.go)
+│ ├── services/ # Business logic (*_service.go)
│ ├── models/ # Database models
│ ├── dto/ # Data transfer objects
│ ├── database/ # DB connection & migrations
@@ -43,18 +102,21 @@ backend/
```
#### Naming Conventions
+
- **Handlers**: `*_handler.go` with methods like `List`, `Create`, `Update`, `Delete`
- **Services**: `*_service.go` with business logic implementation
- **Models**: Singular names (e.g., `Container`, `Image`, `Stack`)
- **Package names**: Lowercase, single word when possible
#### Database Models
+
- Use GORM annotations for relationships and constraints
- Include `BaseModel` for common fields (ID, CreatedAt, UpdatedAt)
- Implement `TableName()` method for custom table names
- Use proper foreign key relationships with preloading
#### API Patterns
+
- RESTful endpoints with proper HTTP status codes
- Use DTOs for request/response transformation
- Implement pagination with `SortedPaginationRequest`
@@ -62,6 +124,7 @@ backend/
- Use Gin binding for request validation
#### Error Handling
+
- Return meaningful HTTP status codes
- Use structured logging with `slog`
- Wrap errors with context using `fmt.Errorf`
@@ -70,12 +133,13 @@ backend/
### Frontend (SvelteKit + TypeScript)
#### File Organization
+
```
frontend/src/
├── routes/ # SvelteKit file-based routing
├── lib/
│ ├── components/ # Reusable Svelte components
-│ ├── services/api/ # API service classes
+│ ├── services/api/ # API service classes
│ ├── stores/ # Svelte stores
│ ├── types/ # TypeScript type definitions
│ ├── dto/ # Frontend DTOs
@@ -84,6 +148,7 @@ frontend/src/
```
#### Svelte 5 Conventions
+
- **Props**: Use `let { prop1, prop2 } = $props()` destructuring
- **State**: Use `$state()` for reactive variables
- **Effects**: Use `$effect()` for side effects
@@ -91,6 +156,7 @@ frontend/src/
- **Event handlers**: Use `on*` props or inline handlers
#### Component Patterns
+
- **Reusable components**: Place in `/lib/components/`
- **Page components**: Use `+page.svelte` in routes
- **Layout components**: Use `+layout.svelte` for shared layouts
@@ -98,18 +164,21 @@ frontend/src/
- **Error boundaries**: Handle errors gracefully with user feedback
#### TypeScript Usage
+
- Define interfaces for all data structures
- Use strict type checking
- Export types from dedicated `*.type.ts` files
- Use generic types for reusable components
#### API Integration
+
- Create service classes in `/lib/services/api/`
- Use Axios with proper error handling
- Implement request/response DTOs
- Use async/await patterns consistently
#### Styling
+
- Use Tailwind CSS classes
- Follow shadcn-svelte component patterns
- Implement dark/light mode support
@@ -118,6 +187,7 @@ frontend/src/
## Development Guidelines
### General Rules
+
- **No unnecessary comments**: Code should be self-documenting
- **Clean imports**: Group and sort imports logically
- **Error handling**: Always handle errors appropriately
@@ -125,6 +195,7 @@ frontend/src/
- **Performance**: Implement pagination, lazy loading, and efficient updates
### Backend Specific
+
- Use dependency injection through bootstrap pattern
- Implement proper service layer separation
- Use GORM relationships efficiently with preloading
@@ -132,6 +203,7 @@ frontend/src/
- Implement proper logging with structured data
### Frontend Specific
+
- **Always use Svelte 5 syntax** (runes, new event handling)
- Implement proper loading and error states
- Use reactive patterns efficiently
@@ -139,12 +211,14 @@ frontend/src/
- Implement proper form validation
### Database
+
- Use migrations for schema changes
- Implement proper indexing for performance
- Use foreign key constraints
- Handle soft deletes where appropriate
### Security
+
- Validate all user inputs
- Use proper authentication middleware
- Implement CORS correctly
@@ -152,6 +226,7 @@ frontend/src/
- Follow Docker security best practices
### Testing
+
- Write Playwright E2E tests for critical user flows
- Test API endpoints thoroughly
- Mock external Docker API calls in tests
@@ -160,25 +235,30 @@ frontend/src/
## Anti-Patterns to Avoid
### Backend
+
- Don't put business logic in handlers
- Don't use global variables for state
- Don't ignore database transaction boundaries
- Don't hardcode registry-specific logic (use generic patterns)
-### Frontend
+### Frontend
+
- Don't use Svelte 4 syntax (no export let, on:click, etc.)
- Don't ignore loading/error states
- Don't create overly complex component hierarchies
- Don't bypass type checking with `any`
### General
+
- Don't add unnecessary comments or console.log statements
- Don't ignore error handling
- Don't create tight coupling between layers
- Don't commit sensitive configuration data
## Container Registry Integration
+
When working with container registries:
+
- Use generic authentication patterns, not registry-specific hardcoding
- Handle different authentication methods (bearer tokens, basic auth)
- Implement proper error handling for network timeouts
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
index c6422a79a..aca5fcec0 100644
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -1,5 +1,3 @@
{
- "recommendations": [
- "actboy168.tasks"
- ]
-}
\ No newline at end of file
+ "recommendations": ["actboy168.tasks", "svelte.svelte-vscode", "golang.go"]
+}