Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
chore: add arcanes AI policy (#1622)
Kyle Mendellf53e2028c02b
diff --git a/.github/CLAUDE.md b/.github/CLAUDE.mddeleted file mode 100644index 3c64f9b88..000000000--- a/.github/CLAUDE.md+++ /dev/null@@ -1,127 +0,0 @@-# CLAUDE.md--This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.--## Project Overview--Arcane is a modern Docker management UI with a Go backend and SvelteKit frontend. It manages containers, images, volumes, networks, stacks, and tracks image updates.--## Commands--### Development--```bash-./scripts/development/dev.sh start # Start Docker-based dev environment (recommended)-./scripts/development/dev.sh stop|restart|rebuild|clean-```--### Backend (Go)--```bash-cd backend-go build ./... # Build all modules-go test ./... # Run tests-golangci-lint run # Lint-```--### Frontend (SvelteKit)--```bash-pnpm -w -C frontend dev # Dev server (port 3000)-pnpm -w -C frontend build # Production build-pnpm -w -C frontend check # Type check-pnpm -w format # Format all code-```--### E2E Tests (Playwright)--```bash-pnpm test # Run tests-```--## Architecture--**Three Go modules** unified via `go.work`:--- `backend/` - API server, services, models-- `cli/` - Command-line tool (uses Cobra)-- `types/` - Shared type definitions--**Frontend**: SvelteKit in `frontend/` with pnpm--### Backend Structure--```-backend/internal/-├── bootstrap/ # App initialization & DI wiring (start here)-├── api/ # HTTP handlers (*_handler.go)-├── services/ # Business logic (*_service.go)-├── models/ # GORM database models-├── dto/ # Request/response DTOs-├── huma/ # Huma v2 API handlers (newer pattern)-└── job/ # Background job scheduling (gocron v2)-```--### Frontend Structure--```-frontend/src/-├── routes/(app)/ # Main app pages (dashboard, containers, images, etc.)-├── routes/(auth)/ # Auth pages-├── lib/components/ # Reusable Svelte components (shadcn-svelte)-├── lib/services/api/ # API service classes (Axios)-├── lib/stores/ # Svelte stores-└── lib/types/ # TypeScript types-```--## Key Patterns--### Backend--- **Thin handlers**: HTTP handlers call services; business logic lives in `*_service.go`-- **Bootstrap DI**: All wiring happens in `internal/bootstrap/` - check here for how services are instantiated-- **DTOs for boundaries**: Use `internal/dto/` for API request/response types-- **Structured logging**: Use `slog` with context-- **Error wrapping**: `fmt.Errorf("context: %w", err)`--### Frontend (Svelte 5 Only)--```svelte-<!-- Props -->-let { prop1, prop2 } = $props();--<!-- State -->-let count = $state(0);--<!-- Derived -->-let doubled = $derived(count * 2);--<!-- Effects -->-$effect(() => { /* side effects */ });-```--**Do NOT update state values in an effect**--**Do NOT use Svelte 4 syntax** (`export let`, `on:click`, `$:`, etc.)--### Database--- GORM with SQLite or PostgreSQL-- Models include `BaseModel` (UUID, timestamps)-- Use proper preloading for relationships--## Anti-Patterns--- Don't put business logic in handlers-- Don't use Svelte 4 syntax anywhere-- Don't hardcode registry-specific logic (support generic OCI patterns)-- Don't bypass TypeScript with `any`-- Don't add unnecessary comments--## Container Registry Integration--When working with registries:--- Use generic authentication (bearer tokens, basic auth)-- Support multiple providers (Docker Hub, GHCR, custom OCI)-- Use case-insensitive header checkingdiff --git a/.github/copilot-instructions.md b/AGENTS.mdsimilarity index 61%rename from .github/copilot-instructions.mdrename to AGENTS.mdindex a341453eb..5e2480765 100644--- a/.github/copilot-instructions.md+++ b/AGENTS.md@@ -1,5 +1,7 @@# Arcane AI Agent Instructions+> **All AI agents must conform to [AI_POLICY.md](./AI_POLICY.md)**+Arcane is a modern Docker management UI with a **Go backend** (Huma v2 API), **SvelteKit frontend** (Svelte 5), and an optional headless agent. Three Go modules unified via `go.work`: `backend/`, `cli/`, `types/`.## Development Environment@@ -116,11 +118,99 @@ Backend tests use in-memory SQLite and testify. See [auth_service_test.go](backe## Anti-Patterns to Avoid-- Business logic in handlers — move to services-- Svelte 4 syntax anywhere-- Hardcoded registry logic — use generic OCI patterns-- TypeScript `any` without justification-- Unnecessary comments explaining obvious code+### Anti-Pattern 1: Business Logic in Handlers+**Bad**: Handler contains business logic+```go+func (h *ContainerHandler) RestartContainer(ctx context.Context, input *RestartInput) (*RestartOutput, error) {+ container, err := h.dockerClient.ContainerInspect(ctx, input.ID)+ if container.State.Running {+ h.dockerClient.ContainerStop(ctx, input.ID, nil)+ }+ return h.dockerClient.ContainerStart(ctx, input.ID, nil)+}+```++**Good**: Handler calls service+```go+func (h *ContainerHandler) RestartContainer(ctx context.Context, input *RestartInput) (*RestartOutput, error) {+ err := h.containerService.Restart(ctx, input.EnvironmentID, input.ID)+ if err != nil {+ return nil, fmt.Errorf("failed to restart container: %w", err)+ }+ return &RestartOutput{Success: true}, nil+}+```++### Anti-Pattern 2: Svelte 4 Syntax+**Bad**: Using deprecated Svelte 4 patterns+```svelte+<script>+ export let name;+ $: greeting = `Hello ${name}`;+</script>+<button on:click={handleClick}>Click</button>+```++**Good**: Using Svelte 5 runes+```svelte+<script lang="ts">+ let { name }: { name: string } = $props();+ let greeting = $derived(`Hello ${name}`);+</script>+<button onclick={handleClick}>Click</button>+```++### Anti-Pattern 3: Missing Multi-Environment Support+**Bad**: Hardcoded API path without environment+```typescript+async getContainers() {+ return this.api.get('/containers');+}+```++**Good**: Include environment ID in path+```typescript+async getContainers() {+ const envId = await environmentStore.getCurrentEnvironmentId();+ return this.api.get(`/environments/${envId}/containers`);+}+```++### Anti-Pattern 4: Missing BaseModel+**Bad**: Model without standard fields+```go+type Stack struct {+ ID string `json:"id"`+ Name string `json:"name"`+}+```++**Good**: Model with BaseModel+```go+type Stack struct {+ models.BaseModel+ Name string `json:"name" gorm:"column:name"`+}++func (Stack) TableName() string { return "stacks" }+```++### Anti-Pattern 5: Using TypeScript `any`+**Bad**: Untyped data+```typescript+function processContainer(data: any) {+ return data.name;+}+```++**Good**: Properly typed+```typescript+import type { Container } from '$lib/types';++function processContainer(data: Container): string {+ return data.name;+}+```## Container Registry Integration@@ -248,3 +338,88 @@ ARCANE_AGENT_TOKEN=<api-key>- Check `cfg.AgentMode` to skip manager-only logic (e.g., environment health checks)- Agent auto-pairs with manager on startup if token is configured- Edge connections are stateless — each request is independent++## AI-Assisted Contributions++If you're an AI coding agent (like Claude Code, GitHub Copilot, Cursor, or similar) assisting a human developer:++### Required Reading++1. **Must read**: [AI_POLICY.md](AI_POLICY.md) — Disclosure requirements and quality standards+2. **Must follow**: All coding patterns in this document+3. **Must ensure**: Human has tested the changes locally++### Common AI Pitfalls to Avoid++When working with Arcane:++❌ **Don't use Svelte 4 syntax**: This project uses Svelte 5 exclusively. No `export let`, no `on:click`, no `$:` reactive statements.++❌ **Don't put business logic in handlers**: Handlers should be thin wrappers that call services. Check `backend/internal/services/` for patterns.++❌ **Don't ignore multi-environment patterns**: All API endpoints must include environment ID. Check `environmentStore` usage in frontend services.++❌ **Don't skip BaseModel**: All database models must embed `models.BaseModel` for UUID and timestamps.++❌ **Don't ignore existing patterns**: Before writing new code, search for similar functionality:+```bash+# Find existing patterns+git grep "func.*Service" backend/internal/services/+git grep "extends BaseAPIService" frontend/src/lib/services/+```++### Good AI-Assisted Contribution Pattern++1. **Start with the issue**: Read the full GitHub issue and understand the user's actual problem+2. **Find existing patterns**: Search for similar code in the same package/directory+3. **Follow the pattern**: Match structure, error handling, naming conventions+4. **Test comprehensively**: Run dev environment, verify frontend and backend work+5. **Explain in human terms**: Write PR descriptions that explain WHY, not just WHAT++### Testing Requirements++Before submitting any AI-assisted contribution, ensure:++```bash+# 1. Start development environment+./scripts/development/dev.sh start++# 2. Backend tests (if you changed Go code)+cd backend && go test ./...++# 3. Frontend type checking (if you changed frontend code)+pnpm -C frontend check:ci++# 4. E2E tests+pnpm test++# 5. Verify hot reload works+# - Frontend: http://localhost:3000+# - Backend: http://localhost:3552+```++If any of these fail, **do not submit the PR**. Fix the issues first.++### PR Description Template for AI-Assisted Contributions++```markdown+## Summary+[One paragraph explaining what this PR does and why]++## Related Issue+Fixes #[issue number]++## Changes+- [Specific change 1 with rationale]+- [Specific change 2 with rationale]++## Testing+- [ ] Dev environment starts successfully+- [ ] Backend tests pass: `cd backend && go test ./...`+- [ ] Frontend type checks pass: `pnpm -C frontend check:ci`+- [ ] Manually tested: [describe how]++## AI Tool Used+AI Tool: [e.g., Claude Code, GitHub Copilot, Cursor]+Assistance Level: [Significant/Moderate/Minor]+```diff --git a/AI_POLICY.md b/AI_POLICY.mdnew file mode 100644index 000000000..68a203972--- /dev/null+++ b/AI_POLICY.md@@ -0,0 +1,48 @@+# AI Usage Policy++Arcane has clear rules for AI-assisted contributions:++- **All AI usage in any form must be disclosed.** You must state the tool you used (e.g., Claude Code, Cursor, GitHub Copilot, ChatGPT) along with the extent that the work was AI-assisted.++- **Pull requests created by AI must have been fully verified with human testing.** AI must not create hypothetically correct code that hasn't been tested. You must run the development environment, verify both frontend and backend work correctly, and manually test your changes. You must not allow AI to write code for platforms or environments you don't have access to manually test on.++- **Code must follow Arcane's existing patterns.** Before writing code, read [AGENTS.md](AGENTS.md) for technical guidance. AI-generated code that ignores project conventions (Svelte 5 syntax, service patterns, error handling) will be rejected.++- **Issues and discussions can use AI assistance but must have a full human-in-the-loop.** This means that any content generated with AI must have been reviewed *and edited* by a human before submission. AI is very good at being overly verbose and including noise that distracts from the main point. Humans must do their research and trim this down.++- **No AI-generated media is allowed** (art, images, videos, audio, etc.). Text and code are the only acceptable AI-generated content, per the other rules in this policy.++- **Contributors who ignore this policy will face consequences.** Undisclosed AI usage or suspected AI usage without disclosure will result in PR closure. Repeated violations may result in being blocked from contributing. You've been warned.++These rules apply to all outside contributions. Maintainers are exempt from these rules and may use AI tools at their discretion; they've proven themselves trustworthy to apply good judgment.++## Testing Requirements++Before submitting any AI-assisted contribution, you must:++1. Start the development environment: `./scripts/development/dev.sh start`+2. Access the frontend at http://localhost:3000 and verify it works+3. Verify the backend at http://localhost:3552 responds correctly+4. Test your specific changes manually+5. Ensure no linting errors exist+6. Verify hot reload works for both frontend and backend++## There are Humans Here++Please remember that Arcane is maintained by humans.++Every discussion, issue, and pull request is read and reviewed by humans. It is a point of interaction between people and their work. Approaching this with low-effort, unverified submissions is disrespectful and puts the burden of validation on maintainers who volunteer their time.++In a perfect world, AI would produce high-quality, correct code every time. But that reality depends on the person using the AI. Today, we see too many contributions where AI-generated code hasn't been tested, doesn't follow project patterns, or solves problems that don't exist. Until this improves, we need clear rules to protect maintainer time.++## AI is Welcome Here++Arcane is developed with AI assistance, and maintainers use AI tools productively in their workflow. As a project, we welcome AI as a tool for those who use it responsibly!++**Our reason for this policy is not an anti-AI stance**, but rather a response to the increase in low-quality AI-generated pull requests that don't address real user needs or follow project standards. It's about the quality of contributions, not the tools used to create them.++This section exists to be transparent about the project's use of AI and to clarify that this policy targets contribution quality, not the use of AI tools themselves.++## Technical Guidance for AI Tools++If you're using AI tools to contribute to Arcane, ensure your AI is configured with our coding standards. See [AGENTS.md](AGENTS.md) for architecture patterns, anti-patterns to avoid, and project-specific conventions that will help AI tools generate code that matches our standards.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 940633926..4ce2e6008 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -2,6 +2,8 @@Thanks for helping make Arcane better! We've built a modern, streamlined development experience that gets you up and running in minutes.+> **Using AI tools?** Please read our [AI Usage Policy](AI_POLICY.md) before contributing.+## 🌟 Ways to Contribute- 🐛 **Report bugs** using our issue templates