diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d2540e8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,74 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. I'm a technical architect, java, spring boot and JavaFX +expert. + +This project is a desktop application for images / pictures management. Like collections of images. performance is key (volume and speed analysis) + +## Technical overview + +* Use java 26 (and javafx), spring-boot, picocli, h2, jackson +* use only maven as build tool. +* For packaging, use spring boot generated jar, and jdeploy to create OS package (jdk/jre included) +* Use lombok when applicable (Constructor and getter / setter) + +## Packaging & distribution (jDeploy) + +## Agent guidelines + +* Plans generated with Claude must be saved into directory: ".claude/plans". +* "Do not use the AskUserQuestion tool. If you need more information or need me to make a choice, output your questions as plain text in your final response + instead." + +Native installers with a bundled JRE are produced by jDeploy, driven from two files: `package.json` at the repository root (the descriptor) and +`.github/workflows/jdeploy.yml` (the release pipeline). + +* **Entry point.** jDeploy has no main-class setting — it runs the jar. So the entry point is declared once, as + `spring-boot-maven-plugin`'s `${main.class}`, which lands in the repackaged jar's manifest as `Start-Class`. `jdeploy.jar` in + `package.json` points at `target/pholio.jar`; `` is version-free precisely so that path never needs updating. +* **Runtime.** `jdeploy.javaVersion: "26"` with `jdeploy.javafx: true` provisions an Azul Zulu FX **JRE** per platform. `windows-arm64` is deliberately absent + from `downloadPage.platforms`: Azul publishes no FX build for it at 26, so listing it would produce an installer that cannot start. +* **Syncing the descriptor.** `mvn -Pjdeploy package` runs `jdeploy-maven-plugin:sync-package-json`, which copies version, name, description, title, jar path, + Java version and the JavaFX flag from the POM into + `package.json`. It works by shelling out to `npm pkg set`, which is why it sits behind a profile — a plain + `mvn package` must not require Node. Every other key in `package.json` is hand-maintained. +* **Releasing.** Push a `v` tag (the leading `v` is stripped to form the app version); the workflow builds the bundles and attaches them to that + release. Pushing a `*-snapshot` branch publishes a rolling prerelease instead. Branch and tag names must be at most 16 characters of `[A-Za-z0-9._-]` — the + jDeploy action silently skips anything else. +* **Auto-update.** Handled entirely by the native launcher: it reads a `package-info.json` that the action writes to a `jdeploy` tag in this repository, and + picks up a newer release on next start. This requires the repository to stay public; a private one needs a separate public release repository passed to the + action as + `target_repository`. +* **Do not add `documentTypes`, `urlSchemes` or `singleton` without changing the launcher first.** jDeploy passes opened files and URIs to `main`, and + `LaunchOptions` reads any unrecognised argument as a subcommand and switches to `HEADLESS`. File associations would therefore make a double-clicked photo + start Pholio with no window. + +## Preferences vc H2 DB (library) + +* preferences stored as yaml must contain only user preferences for the global application (not related to a library) +* All library information like: folders, metadata, latest importations, media hash, etc must be stores into H2 DB + +## Spring data jpa jdbc + +* use jpa Repository, enitiy +* use mapstruct for mapping entities to domain abd vis versa. + +## Testing + +* for unit test use AssertJ with SoftAssertion + +## Git & Commit Guidelines + +- Use the Conventional Commits v1.0.0 specification for all commit messages. +- Always structure messages as: `([optional scope]): ` +- Use lowercase for the type and scope. +- Write the description in the imperative mood (e.g., "add feature", not "added feature"). +- Allowed types: + - `feat`: A new feature + - `fix`: A bug fix + - `docs`: Documentation changes + - `style`: Code style changes (formatting, missing semi-colons, etc.) + - `refactor`: Code changes that neither fix a bug nor add a feature + - `test`: Adding missing tests or correcting existing tests + - `chore`: Changes to the build process or auxiliary tools +- Example: `feat(auth): add JWT token validation` diff --git a/CLAUDE.md b/CLAUDE.md index d2540e8..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,74 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. I'm a technical architect, java, spring boot and JavaFX -expert. - -This project is a desktop application for images / pictures management. Like collections of images. performance is key (volume and speed analysis) - -## Technical overview - -* Use java 26 (and javafx), spring-boot, picocli, h2, jackson -* use only maven as build tool. -* For packaging, use spring boot generated jar, and jdeploy to create OS package (jdk/jre included) -* Use lombok when applicable (Constructor and getter / setter) - -## Packaging & distribution (jDeploy) - -## Agent guidelines - -* Plans generated with Claude must be saved into directory: ".claude/plans". -* "Do not use the AskUserQuestion tool. If you need more information or need me to make a choice, output your questions as plain text in your final response - instead." - -Native installers with a bundled JRE are produced by jDeploy, driven from two files: `package.json` at the repository root (the descriptor) and -`.github/workflows/jdeploy.yml` (the release pipeline). - -* **Entry point.** jDeploy has no main-class setting — it runs the jar. So the entry point is declared once, as - `spring-boot-maven-plugin`'s `${main.class}`, which lands in the repackaged jar's manifest as `Start-Class`. `jdeploy.jar` in - `package.json` points at `target/pholio.jar`; `` is version-free precisely so that path never needs updating. -* **Runtime.** `jdeploy.javaVersion: "26"` with `jdeploy.javafx: true` provisions an Azul Zulu FX **JRE** per platform. `windows-arm64` is deliberately absent - from `downloadPage.platforms`: Azul publishes no FX build for it at 26, so listing it would produce an installer that cannot start. -* **Syncing the descriptor.** `mvn -Pjdeploy package` runs `jdeploy-maven-plugin:sync-package-json`, which copies version, name, description, title, jar path, - Java version and the JavaFX flag from the POM into - `package.json`. It works by shelling out to `npm pkg set`, which is why it sits behind a profile — a plain - `mvn package` must not require Node. Every other key in `package.json` is hand-maintained. -* **Releasing.** Push a `v` tag (the leading `v` is stripped to form the app version); the workflow builds the bundles and attaches them to that - release. Pushing a `*-snapshot` branch publishes a rolling prerelease instead. Branch and tag names must be at most 16 characters of `[A-Za-z0-9._-]` — the - jDeploy action silently skips anything else. -* **Auto-update.** Handled entirely by the native launcher: it reads a `package-info.json` that the action writes to a `jdeploy` tag in this repository, and - picks up a newer release on next start. This requires the repository to stay public; a private one needs a separate public release repository passed to the - action as - `target_repository`. -* **Do not add `documentTypes`, `urlSchemes` or `singleton` without changing the launcher first.** jDeploy passes opened files and URIs to `main`, and - `LaunchOptions` reads any unrecognised argument as a subcommand and switches to `HEADLESS`. File associations would therefore make a double-clicked photo - start Pholio with no window. - -## Preferences vc H2 DB (library) - -* preferences stored as yaml must contain only user preferences for the global application (not related to a library) -* All library information like: folders, metadata, latest importations, media hash, etc must be stores into H2 DB - -## Spring data jpa jdbc - -* use jpa Repository, enitiy -* use mapstruct for mapping entities to domain abd vis versa. - -## Testing - -* for unit test use AssertJ with SoftAssertion - -## Git & Commit Guidelines - -- Use the Conventional Commits v1.0.0 specification for all commit messages. -- Always structure messages as: `([optional scope]): ` -- Use lowercase for the type and scope. -- Write the description in the imperative mood (e.g., "add feature", not "added feature"). -- Allowed types: - - `feat`: A new feature - - `fix`: A bug fix - - `docs`: Documentation changes - - `style`: Code style changes (formatting, missing semi-colons, etc.) - - `refactor`: Code changes that neither fix a bug nor add a feature - - `test`: Adding missing tests or correcting existing tests - - `chore`: Changes to the build process or auxiliary tools -- Example: `feat(auth): add JWT token validation` +@AGENTS.md