From e34e027318a7ada148b8ec619139393422611ed6 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 8 Jul 2026 08:15:49 +0000 Subject: [PATCH 1/6] Add AGENTS.md and JavaFX project scaffold - AGENTS.md with project overview, commands, and clean/structured conventions - Maven build (pom.xml) targeting Java 21 with JavaFX 21 and JUnit 5 - JPMS module descriptor and base package com.example.vibeapp - Runnable JavaFX app: App entry point, FXML main view, CSS styling - Greeter domain class kept UI-free, covered by unit tests - Expand .gitignore for Maven target/ and common IDE files Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_019dPnZoRJALVs9vRd9i1MPH --- .gitignore | 11 +++ AGENTS.md | 97 +++++++++++++++++++ pom.xml | 66 +++++++++++++ src/main/java/com/example/vibeapp/App.java | 32 ++++++ .../java/com/example/vibeapp/Greeter.java | 30 ++++++ .../com/example/vibeapp/MainController.java | 23 +++++ src/main/java/module-info.java | 8 ++ .../com/example/vibeapp/main-view.fxml | 18 ++++ .../resources/com/example/vibeapp/styles.css | 22 +++++ .../java/com/example/vibeapp/GreeterTest.java | 27 ++++++ 10 files changed, 334 insertions(+) create mode 100644 AGENTS.md create mode 100644 pom.xml create mode 100644 src/main/java/com/example/vibeapp/App.java create mode 100644 src/main/java/com/example/vibeapp/Greeter.java create mode 100644 src/main/java/com/example/vibeapp/MainController.java create mode 100644 src/main/java/module-info.java create mode 100644 src/main/resources/com/example/vibeapp/main-view.fxml create mode 100644 src/main/resources/com/example/vibeapp/styles.css create mode 100644 src/test/java/com/example/vibeapp/GreeterTest.java diff --git a/.gitignore b/.gitignore index 524f096..bac31be 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,14 @@ +# Maven build output +target/ + +# IDE files +.idea/ +*.iml +.vscode/ +.settings/ +.classpath +.project + # Compiled class file *.class diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0e6a3b9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,97 @@ +# AGENTS.md + +Guidance for AI coding agents (Claude Code and compatible tools) working in this +repository. Read this before making changes. + +## Project overview + +**Vibe Coding App** is a desktop **frontend application built with JavaFX**. +It is an early-stage project — the goal is to grow it cleanly and keep the +structure understandable as it evolves. + +- **Language:** Java 21 (LTS) +- **UI toolkit:** JavaFX 21 (FXML + controllers + CSS) +- **Build tool:** Maven +- **Testing:** JUnit 5 (Jupiter) +- **Module system:** JPMS is used (`src/main/java/module-info.java`) + +## Repository layout + +``` +pom.xml Maven build definition +src/main/java/module-info.java JPMS module descriptor +src/main/java/com/example/vibeapp/ + App.java Application entry point (extends Application) + MainController.java Controller for the main view (view wiring only) + Greeter.java Example of pure, testable domain logic +src/main/resources/com/example/vibeapp/ + main-view.fxml Main window layout + styles.css Stylesheet for the UI +src/test/java/com/example/vibeapp/ + GreeterTest.java Unit tests for domain logic +``` + +The base package is `com.example.vibeapp`. Rename it deliberately (and update +`module-info.java`, the FXML `fx:controller`, and `mainClass` in `pom.xml`) if +the project gets a real name — do not leave a half-renamed package. + +## Commands + +Run all commands from the repository root. + +| Task | Command | +| ------------------- | ------------------- | +| Build | `mvn compile` | +| Run the tests | `mvn test` | +| Full verify (build + test) | `mvn verify` | +| Run the app | `mvn javafx:run` | +| Clean build outputs | `mvn clean` | + +> Note: `mvn javafx:run` needs a graphical display. In a headless environment +> (like CI or a remote container) it will fail to open a window — that is +> expected. Use `mvn test` / `mvn verify` to validate changes there. + +## Conventions (priority: clean & structured) + +- **Separate logic from UI.** Keep business/domain logic in plain Java classes + (see `Greeter`) with **no JavaFX imports**, so it can be unit-tested without + starting the toolkit. Controllers should only wire that logic to the view. +- **Every non-trivial class or logic change gets a test.** Put tests under + `src/test/java`, mirroring the main package. Name them `Test`. +- **FXML for layout, CSS for styling.** Avoid hard-coding colors, fonts, or + sizes in Java; put them in `styles.css`. Build screens in `.fxml` files with a + matching controller rather than constructing large scene graphs in code. +- **Keep `module-info.java` correct.** New packages that JavaFX must reflect + over (controllers, FXML-bound classes) need an `opens` entry. New third-party + modules need a `requires` entry. +- **Code style:** 4-space indentation, one top-level class per file, standard + Java naming (`PascalCase` types, `camelCase` members, `UPPER_SNAKE_CASE` + constants). Add a short Javadoc to public classes and non-obvious methods. +- **Small, focused commits** with clear messages describing the *why*. + +## Definition of done + +Before considering a change complete: + +1. `mvn verify` passes (compiles cleanly, all tests green). +2. New or changed logic is covered by a test. +3. `module-info.java`, FXML `fx:controller` references, and `pom.xml` + `mainClass` are consistent with the code. +4. No unused imports, dead code, or commented-out blocks left behind. + +## Good first tasks / how to extend + +- **Add a screen:** create `foo-view.fxml` + `FooController` in the resource and + Java package, load it from `App` or via navigation. +- **Add logic:** create a plain class + its `*Test`, then call it from a + controller. +- **Add a dependency:** add it to `pom.xml`, then add a `requires` line in + `module-info.java`. + +## Things to avoid + +- Do not put business logic or magic values directly inside controllers or + `App`. +- Do not commit build output (`target/`) or IDE files — they are gitignored. +- Do not add a dependency without also updating `module-info.java`. +- Do not bypass FXML by building complex UIs entirely in Java code. diff --git a/pom.xml b/pom.xml new file mode 100644 index 0000000..f6709c9 --- /dev/null +++ b/pom.xml @@ -0,0 +1,66 @@ + + + 4.0.0 + + com.example + vibeapp + 0.1.0-SNAPSHOT + jar + + Vibe Coding App + A JavaFX frontend application. + + + UTF-8 + 21 + 21.0.5 + 5.11.3 + com.example.vibeapp.App + + + + + org.openjfx + javafx-controls + ${javafx.version} + + + org.openjfx + javafx-fxml + ${javafx.version} + + + + org.junit.jupiter + junit-jupiter + ${junit.version} + test + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.13.0 + + + org.apache.maven.plugins + maven-surefire-plugin + 3.5.2 + + + + org.openjfx + javafx-maven-plugin + 0.0.8 + + ${mainClass} + + + + + diff --git a/src/main/java/com/example/vibeapp/App.java b/src/main/java/com/example/vibeapp/App.java new file mode 100644 index 0000000..cc05f23 --- /dev/null +++ b/src/main/java/com/example/vibeapp/App.java @@ -0,0 +1,32 @@ +package com.example.vibeapp; + +import java.io.IOException; +import java.util.Objects; + +import javafx.application.Application; +import javafx.fxml.FXMLLoader; +import javafx.scene.Scene; +import javafx.stage.Stage; + +/** + * Application entry point. Bootstraps the JavaFX runtime, loads the main view + * and shows the primary window. + */ +public class App extends Application { + + @Override + public void start(Stage stage) throws IOException { + FXMLLoader loader = new FXMLLoader(getClass().getResource("main-view.fxml")); + Scene scene = new Scene(loader.load(), 480, 320); + scene.getStylesheets().add( + Objects.requireNonNull(getClass().getResource("styles.css")).toExternalForm()); + + stage.setTitle("Vibe Coding App"); + stage.setScene(scene); + stage.show(); + } + + public static void main(String[] args) { + launch(args); + } +} diff --git a/src/main/java/com/example/vibeapp/Greeter.java b/src/main/java/com/example/vibeapp/Greeter.java new file mode 100644 index 0000000..4ee9ad1 --- /dev/null +++ b/src/main/java/com/example/vibeapp/Greeter.java @@ -0,0 +1,30 @@ +package com.example.vibeapp; + +/** + * Pure domain logic for producing greeting messages. + * + *

Deliberately free of JavaFX types so it can be unit-tested without + * starting the UI toolkit. This is the pattern to follow: keep business logic + * in plain classes and let controllers only wire it to the view. + */ +public class Greeter { + + private int count; + + /** + * Records a greeting and returns the message to display. + * + * @return the greeting message, including how many times it has been called + */ + public String greet() { + count++; + return "Hello, Vibe Coding! (" + count + ")"; + } + + /** + * @return how many greetings have been produced so far + */ + public int count() { + return count; + } +} diff --git a/src/main/java/com/example/vibeapp/MainController.java b/src/main/java/com/example/vibeapp/MainController.java new file mode 100644 index 0000000..f4b547c --- /dev/null +++ b/src/main/java/com/example/vibeapp/MainController.java @@ -0,0 +1,23 @@ +package com.example.vibeapp; + +import javafx.fxml.FXML; +import javafx.scene.control.Label; + +/** + * Controller for {@code main-view.fxml}. + * + *

Keeps only view wiring here; the actual logic lives in {@link Greeter} so + * it can be tested independently of the JavaFX toolkit. + */ +public class MainController { + + @FXML + private Label messageLabel; + + private final Greeter greeter = new Greeter(); + + @FXML + private void onHelloButtonClick() { + messageLabel.setText(greeter.greet()); + } +} diff --git a/src/main/java/module-info.java b/src/main/java/module-info.java new file mode 100644 index 0000000..b32f2c7 --- /dev/null +++ b/src/main/java/module-info.java @@ -0,0 +1,8 @@ +module com.example.vibeapp { + requires javafx.controls; + requires javafx.fxml; + + // Allow JavaFX to reflectively access controllers and load FXML resources. + opens com.example.vibeapp to javafx.fxml; + exports com.example.vibeapp; +} diff --git a/src/main/resources/com/example/vibeapp/main-view.fxml b/src/main/resources/com/example/vibeapp/main-view.fxml new file mode 100644 index 0000000..4752b52 --- /dev/null +++ b/src/main/resources/com/example/vibeapp/main-view.fxml @@ -0,0 +1,18 @@ + + + + + + + + + + + + +