Merge branch 'main' of https://github.com/MliroLirrorsIngenuity/Felis

# Felis Contributor Guide

This document is the practical entry point for contributors. It focuses on how to

run, test, and reason about the project while keeping changes small and aligned

with the current codebase.

## Project Shape

Felis is a Kubernetes-native Minecraft server control plane. The repository has

four main areas:

- `cmd/felis/`: the single Go CLI binary. It dispatches subcommands such as

  `api`, `operator`, `migrate`, `reaper`, `restore`, `manifests`, and

  `breakGlass`.

- `internal/`: backend packages for API handlers, store migrations, Kubernetes

  rendering, operator reconciliation, build, backup, restore, and related domain

  logic.

- `panel/`: the React/Vite web control panel.

- `plugins/`: Minecraft-side plugins and mods for Velocity, Paper, Fabric,

  Forge, and NeoForge.

The codebase is intentionally split by responsibility. Prefer changing the

smallest owning module instead of adding broad abstractions or rebuilding nearby

code.

## Local Development

You can do most day-to-day development on macOS or Linux without a full cluster.

The full product needs Postgres and Kubernetes, but unit tests and frontend work

run locally.

Recommended local tools:

- Go matching `go.mod`

- Node.js and npm for `panel/`

- Optional: JDK/Gradle for plugin work

- Optional integration environment: a clean Linux VM or server with Docker,

  k3s, and Postgres

Check tool versions:

```bash

go version

node --version

npm --version

java -version

```

## Backend Commands

Run these from the repository root:

```bash

cd /path/to/Felis

```

Run all Go tests:

```bash

go test ./...

```

Run a focused package:

```bash

go test ./internal/api

go test ./cmd/felis

```

Build the CLI:

```bash

go build -o /tmp/felis-dev ./cmd/felis

/tmp/felis-dev help

```

Render Kubernetes manifests without contacting a cluster:

```bash

/tmp/felis-dev manifests \

  --felis-image registry.felis.svc:5000/felis:dev \

  --velocity-cidr 10.0.0.5/32

```

`felis api`, `felis operator`, `felis migrate up`, and `felis reaper` are real

runtime commands. They need external services such as Postgres and/or a

Kubernetes config, so they are not the first choice for quick local iteration.

## Frontend Commands

Run these from the frontend workspace:

```bash

cd /path/to/Felis/panel

```

Install dependencies:

```bash

npm ci

```

Run against a real backend at `http://localhost:8080`:

```bash

npm run dev

```

Run with the local mock API:

```bash

npm run dev:mock

```

The mock dev server prints its accounts, link code, and reset command when it

starts. Use it for frontend work when you do not have the Go API and cluster

running.

Common frontend checks:

```bash

npm run typecheck

npm test

npm run build

```

## Mock API

The frontend mock API lives under `panel/dev/` and is loaded only by

`npm run dev:mock`. It must not leak into production code or business

components.

Run mock commands from the frontend workspace:

```bash

cd /path/to/Felis/panel

npm run dev:mock

```

Current mock accounts:

| Username | Password | Scenario |

| --- | --- | --- |

| `owner` | `devpassword` | admin, linked |

| `user` | `devpassword` | normal user, not linked |

| `linked` | `devpassword` | normal user, linked |

| `setup` | `devpassword` | admin, first-login password change |

Mock Minecraft link code:

```text

LINK1234

```

Reset mock state:

```bash

curl -X POST http://127.0.0.1:5173/api/v1/__mock/reset

```

Mock rules:

- Keep mock-only logic in `panel/dev/`.

- Do not import mock code from `panel/src/`.

- Keep response shapes aligned with `panel/src/lib/types.ts` and the Go API

  handlers.

- Prefer realistic error codes over happy-path-only mocks.

- Do not present mock data as live production data.

## Full Integration Environment

Run integration/deploy commands from the repository root on the Linux host:

```bash

cd /path/to/Felis

```

The one-line bootstrap script is intended for a clean Linux host, not a typical

macOS development machine:

```bash

sudo -E bash deploy/bootstrap.sh

```

Useful overrides:

```bash

export FELIS_REPO_URL=<your fork url>

export FELIS_REF=<your branch>

export FELIS_IMAGE=felis:dev

export FELIS_ROOT_DOMAIN=<node-ip>.nip.io

```

The bootstrap flow installs/configures system services, builds the Felis image,

imports it into k3s, runs migrations, applies CRDs/manifests, and deploys the

control plane.

After bootstrap, use the break-glass console to create or recover the Owner

account:

```bash

sudo felis breakGlass

```

Use a VM or disposable Linux server for this. Treat it as an integration and

acceptance environment, while keeping normal coding and quick tests local.

## Plugin Development

Plugin docs live in `plugins/README.md`.

The plugin modules intentionally use separate Gradle builds:

```bash

# cwd: repository root

cd /path/to/Felis

gradle -p plugins/velocity build

gradle -p plugins/paper build

bash plugins/fabric/gradlew -p plugins/fabric build

bash plugins/forge/gradlew -p plugins/forge build

bash plugins/neoforge/gradlew -p plugins/neoforge build

```

Notes:

- Fabric/Forge/NeoForge use module wrappers.

- Velocity/Paper use system Gradle.

- Most modules target Java 17.

- Paper needs a Java 21 toolchain.

- First builds may be slow because Minecraft dependencies are downloaded and

  remapped.

## Frontend Status

The panel is currently an early control-panel implementation, not a complete

product.

Reasonably usable today:

- Local-password login

- First-login password change

- User/admin route gates

- Dashboard shell

- My servers list

- Wake, stop, claim actions

- Read-only console log stream

- Account linking flow

- Admin create-server form

- Read-only image whitelist

- Mock API for local frontend work

Still shallow or missing:

- Server detail depth

- Log search/filter/download

- RCON command UX, if/when the backend path is ready

- Admin edit/delete/transfer flows

- Image whitelist mutations

- Backups and restore UI

- Fleet-wide ops data

- Stronger component and browser-level tests

When adding frontend features, keep UI state honest. If the backend endpoint does

not exist yet, use an explicit placeholder instead of fake live data.

## i18n Notes

i18n is not yet established as a full system. User-facing strings are currently

mostly inline in TSX and helper functions.

Good first targets:

- Error messages mapped from stable API error codes

- Navigation labels

- Page titles and primary actions

- Phase/status labels

- Empty/loading/error states

Recommended initial approach:

```text

panel/src/i18n/

  index.ts

  en.ts

  zh-CN.ts

```

Use a small typed dictionary first. Add a larger library such as

`i18next/react-i18next` only when the project needs runtime language switching,

pluralization rules, external translation workflows, or more complex

localization behavior.

Do not translate code comments, internal logs, or mock-only terminal messages

unless there is a clear contributor need.

## Contribution Style

Follow the existing code. Keep changes narrow and easy to review.

Guidelines:

- Prefer minimal changes over rewrites.

- Do not add a new abstraction unless it removes real duplication or names a

  strong local concept.

- Keep frontend mock code out of business components.

- Keep backend tests close to the package that owns the behavior.

- Preserve public API and persistence shapes unless the change explicitly needs a

  contract update.

- Do not commit generated build output such as `panel/dist/`, `node_modules/`,

  Gradle build directories, or local binaries.

AI-assisted work is welcome, but the contributor is responsible for the result.

Do not submit a PR that is entirely AI-generated and not personally reviewed.

Low-quality AI dumps, broad rewrites that ignore the current design, unverified

changes, or code the author cannot explain will not be accepted.

Before handing off a change, run the smallest meaningful checks:

```bash

go test ./...

cd panel && npm run typecheck && npm test && npm run build

```

If you cannot run a relevant check, say so explicitly in the handoff.

<!doctype html>

<html lang="en" class="dark">

<html lang="en">

  <head>

    <meta charset="UTF-8" />

    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <title>Felis · Control Panel</title>

    <script>

      try {

        const theme = localStorage.getItem("felis-theme") || "system";

        const dark = theme === "dark" || (theme === "system" && window.matchMedia("(prefers-color-scheme: dark)").matches);

        if (dark) {

          document.documentElement.classList.add("dark");

        } else {

          document.documentElement.classList.remove("dark");

        }

      } catch (_) {}

    </script>

  </head>

  <body>

    <div id="root"></div>

        "@radix-ui/react-slot": "^1.1.2",

        "class-variance-authority": "^0.7.1",

        "clsx": "^2.1.1",

        "i18next": "^26.3.3",

        "i18next-browser-languagedetector": "^8.2.1",

        "lucide-react": "^0.469.0",

        "react": "^18.3.1",

        "react-dom": "^18.3.1",

        "react-i18next": "^17.0.8",

        "react-router-dom": "^6.28.2",

        "tailwind-merge": "^2.6.0",

        "three": "^0.172.0"

        "@babel/core": "^7.0.0-0"

      }

    },

    "node_modules/@babel/runtime": {

      "version": "7.29.7",

      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.7.tgz",

      "integrity": "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==",

      "license": "MIT",

      "engines": {

        "node": ">=6.9.0"

      }

    },

    "node_modules/@babel/template": {

      "version": "7.29.7",

      "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.29.7.tgz",

        "node": ">= 0.4"

      }

    },

    "node_modules/html-parse-stringify": {

      "version": "3.0.1",

      "resolved": "https://registry.npmjs.org/html-parse-stringify/-/html-parse-stringify-3.0.1.tgz",

      "integrity": "sha512-KknJ50kTInJ7qIScF3jeaFRpMpE8/lfiTdzf/twXyPBLAGrLRTmkz3AdTnKeh40X8k9L2fdYwEp/42WGXIRGcg==",

      "license": "MIT",

      "dependencies": {

        "void-elements": "3.1.0"

      }

    },

    "node_modules/i18next": {

      "version": "26.3.3",

      "resolved": "https://registry.npmjs.org/i18next/-/i18next-26.3.3.tgz",

      "integrity": "sha512-aYVegyBdXSO93CMMihvr47jI7GHSOcIahMpJX+qzUXDzW4xDJf2uenIA+45vDU+YhiVdcfsql70AC9RVdMNrHg==",

      "funding": [

        {

          "type": "individual",

          "url": "https://www.locize.com/i18next"

        },

        {

          "type": "individual",

          "url": "https://www.i18next.com/how-to/faq#i18next-is-awesome.-how-can-i-support-the-project"

        },

        {

          "type": "individual",

          "url": "https://www.locize.com"

        }

      ],

      "license": "MIT",

      "peerDependencies": {

        "typescript": "^5 || ^6"

      },

      "peerDependenciesMeta": {

        "typescript": {

          "optional": true

        }

      }

    },

    "node_modules/i18next-browser-languagedetector": {

      "version": "8.2.1",

      "resolved": "https://registry.npmjs.org/i18next-browser-languagedetector/-/i18next-browser-languagedetector-8.2.1.tgz",

      "integrity": "sha512-bZg8+4bdmaOiApD7N7BPT9W8MLZG+nPTOFlLiJiT8uzKXFjhxw4v2ierCXOwB5sFDMtuA5G4kgYZ0AznZxQ/cw==",

      "license": "MIT",

      "dependencies": {

        "@babel/runtime": "^7.23.2"

      }

    },

    "node_modules/is-binary-path": {

      "version": "2.1.0",

      "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz",

        "react": "^18.3.1"

      }

    },

    "node_modules/react-i18next": {

      "version": "17.0.8",

      "resolved": "https://registry.npmjs.org/react-i18next/-/react-i18next-17.0.8.tgz",

      "integrity": "sha512-0ooKbGLU8JXhe1zwpQUWIeXSgLPOfwJmgheWRIUpcoA0CpyabpGhayjdG+/eA5esC1AQ8h2jWpXjJfzQzeDOCw==",

      "license": "MIT",

      "dependencies": {

        "@babel/runtime": "^7.29.2",

        "html-parse-stringify": "^3.0.1",

        "use-sync-external-store": "^1.6.0"

      },

      "peerDependencies": {

        "i18next": ">= 26.2.0",

        "react": ">= 16.8.0",

        "typescript": "^5 || ^6"

      },

      "peerDependenciesMeta": {

        "react-dom": {

          "optional": true

        },

        "react-native": {

          "optional": true

        },

        "typescript": {

          "optional": true

        }

      }

    },

    "node_modules/react-refresh": {

      "version": "0.17.0",

      "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.17.0.tgz",

      "version": "5.9.3",

      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",

      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",

      "dev": true,

      "devOptional": true,

      "license": "Apache-2.0",

      "bin": {

        "tsc": "bin/tsc",

        }

      }

    },

    "node_modules/use-sync-external-store": {

      "version": "1.6.0",

      "resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.6.0.tgz",

      "integrity": "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==",

      "license": "MIT",

      "peerDependencies": {

        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"

      }

    },

    "node_modules/util-deprecate": {

      "version": "1.0.2",

      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",

        "url": "https://github.com/sponsors/jonschlinkert"

      }

    },

    "node_modules/void-elements": {

      "version": "3.1.0",

      "resolved": "https://registry.npmjs.org/void-elements/-/void-elements-3.1.0.tgz",

      "integrity": "sha512-Dhxzh5HZuiHQhbvTW9AMetFfBHDMYpo23Uo9btPXgdYP+3T5S+p+jgNy7spra+veYhBP2dCSgxR/i2Y02h5/6w==",

      "license": "MIT",

      "engines": {

        "node": ">=0.10.0"

      }

    },

    "node_modules/why-is-node-running": {

      "version": "2.3.0",

      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",

  "description": "Felis control panel — external face of felis-api (spec §7)",

  "scripts": {

    "dev": "vite",

    "dev:mock": "vite --mode mock",

    "build": "tsc -b && vite build",

    "typecheck": "tsc --noEmit",

    "test": "vitest run",

    "@radix-ui/react-slot": "^1.1.2",

    "class-variance-authority": "^0.7.1",

    "clsx": "^2.1.1",

    "i18next": "^26.3.3",

    "i18next-browser-languagedetector": "^8.2.1",

    "lucide-react": "^0.469.0",

    "react": "^18.3.1",

    "react-dom": "^18.3.1",

    "react-i18next": "^17.0.8",

    "react-router-dom": "^6.28.2",

    "tailwind-merge": "^2.6.0",

    "three": "^0.172.0"