@yosr-ai/template-spring 0.0.0-stage → 0.2.6

package/files/src/main/java/com/yosr/app/core/AppSettings.java

@@ -0,0 +1,32 @@
+package com.yosr.app.core;
+
+import java.util.Arrays;
+import java.util.List;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+@Component
+public class AppSettings {
+  private final String appName;
+  private final List<String> corsOrigins;
+
+  // @seed:anchor settings-fields
+  public AppSettings(
+      @Value("${app.name}") String appName, @Value("${app.cors-origins}") String corsOriginsRaw) {
+    this.appName = appName;
+    this.corsOrigins =
+        Arrays.stream(corsOriginsRaw.split(","))
+            .map(String::trim)
+            .filter(part -> !part.isEmpty())
+            .toList();
+    // @seed:anchor settings-values
+  }
+
+  public String appName() {
+    return appName;
+  }
+
+  public List<String> corsOrigins() {
+    return corsOrigins;
+  }
+}

package/files/src/main/java/com/yosr/app/core/HealthController.java

@@ -0,0 +1,14 @@
+package com.yosr.app.core;
+
+import java.util.Map;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+public class HealthController {
+
+  @GetMapping("/health")
+  public Map<String, String> health() {
+    return Map.of("status", "ok");
+  }
+}

package/files/src/main/java/com/yosr/app/core/RestExceptionHandler.java

@@ -0,0 +1,22 @@
+package com.yosr.app.core;
+
+import com.yosr.app.shared.NotFoundException;
+import java.util.Map;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+@RestControllerAdvice
+public class RestExceptionHandler {
+
+  @ExceptionHandler(NotFoundException.class)
+  public ResponseEntity<Map<String, String>> notFound(NotFoundException ex) {
+    return ResponseEntity.status(HttpStatus.NOT_FOUND).body(Map.of("detail", ex.getMessage()));
+  }
+
+  @ExceptionHandler(IllegalArgumentException.class)
+  public ResponseEntity<Map<String, String>> badRequest(IllegalArgumentException ex) {
+    return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(Map.of("detail", ex.getMessage()));
+  }
+}

package/files/src/main/java/com/yosr/app/core/WebConfig.java

@@ -0,0 +1,27 @@
+package com.yosr.app.core;
+
+import java.util.List;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.CorsRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+@Configuration
+public class WebConfig implements WebMvcConfigurer {
+
+  private final AppSettings settings;
+
+  public WebConfig(AppSettings settings) {
+    this.settings = settings;
+  }
+
+  @Override
+  public void addCorsMappings(CorsRegistry registry) {
+    // @seed:anchor filter-registration
+    List<String> origins = settings.corsOrigins();
+    registry
+        .addMapping("/**")
+        .allowedOrigins(origins.toArray(String[]::new))
+        .allowedMethods("GET", "POST", "PATCH", "PUT", "DELETE", "OPTIONS")
+        .allowedHeaders("*");
+  }
+}

package/files/src/main/java/com/yosr/app/features/notes/MemoryNoteStore.java

@@ -0,0 +1,71 @@
+package com.yosr.app.features.notes;
+
+import java.time.OffsetDateTime;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Optional;
+import java.util.concurrent.atomic.AtomicInteger;
+
+public final class MemoryNoteStore implements NoteStore {
+
+  private final Object gate = new Object();
+  private final List<Note> notes = new ArrayList<>();
+  private final AtomicInteger nextId = new AtomicInteger(1);
+
+  @Override
+  public List<Note> list() {
+    synchronized (gate) {
+      return notes.stream()
+          .sorted(Comparator.comparingInt(Note::id).reversed())
+          .map(
+              note ->
+                  new Note(
+                      note.id(), note.title(), note.body(), note.createdAt(), note.updatedAt()))
+          .toList();
+    }
+  }
+
+  @Override
+  public Optional<Note> get(int id) {
+    synchronized (gate) {
+      return notes.stream()
+          .filter(note -> note.id() == id)
+          .findFirst()
+          .map(
+              note ->
+                  new Note(
+                      note.id(), note.title(), note.body(), note.createdAt(), note.updatedAt()));
+    }
+  }
+
+  @Override
+  public Note add(String title, String body) {
+    synchronized (gate) {
+      var now = OffsetDateTime.now();
+      var note = new Note(nextId.getAndIncrement(), title, body, now, null);
+      notes.add(note);
+      return new Note(note.id(), note.title(), note.body(), note.createdAt(), note.updatedAt());
+    }
+  }
+
+  @Override
+  public Optional<Note> update(int id, String title, String body) {
+    synchronized (gate) {
+      for (Note note : notes) {
+        if (note.id() == id) {
+          if (title != null) {
+            note.setTitle(title);
+          }
+          if (body != null) {
+            note.setBody(body);
+          }
+          note.setUpdatedAt(OffsetDateTime.now());
+          return Optional.of(
+              new Note(note.id(), note.title(), note.body(), note.createdAt(), note.updatedAt()));
+        }
+      }
+      return Optional.empty();
+    }
+  }
+}

package/files/src/main/java/com/yosr/app/features/notes/Note.java

@@ -0,0 +1,53 @@
+package com.yosr.app.features.notes;
+
+import java.time.OffsetDateTime;
+
+public final class Note {
+
+  private final int id;
+  private String title;
+  private String body;
+  private final OffsetDateTime createdAt;
+  private OffsetDateTime updatedAt;
+
+  public Note(
+      int id, String title, String body, OffsetDateTime createdAt, OffsetDateTime updatedAt) {
+    this.id = id;
+    this.title = title;
+    this.body = body;
+    this.createdAt = createdAt;
+    this.updatedAt = updatedAt;
+  }
+
+  public int id() {
+    return id;
+  }
+
+  public String title() {
+    return title;
+  }
+
+  public void setTitle(String title) {
+    this.title = title;
+  }
+
+  public String body() {
+    return body;
+  }
+
+  public void setBody(String body) {
+    this.body = body;
+  }
+
+  public OffsetDateTime createdAt() {
+    return createdAt;
+  }
+
+  public OffsetDateTime updatedAt() {
+    return updatedAt;
+  }
+
+  public void setUpdatedAt(OffsetDateTime updatedAt) {
+    this.updatedAt = updatedAt;
+  }
+}

package/files/src/main/java/com/yosr/app/features/notes/NoteDtos.java

@@ -0,0 +1,21 @@
+package com.yosr.app.features.notes;
+
+import java.time.OffsetDateTime;
+
+public final class NoteDtos {
+
+  private NoteDtos() {}
+
+  public record NoteCreate(String title, String body) {}
+
+  public record NoteUpdate(String title, String body) {}
+
+  public record NoteResponse(
+      int id, String title, String body, OffsetDateTime createdAt, OffsetDateTime updatedAt) {
+
+    public static NoteResponse from(Note note) {
+      return new NoteResponse(
+          note.id(), note.title(), note.body(), note.createdAt(), note.updatedAt());
+    }
+  }
+}

package/files/src/main/java/com/yosr/app/features/notes/NoteStore.java

@@ -0,0 +1,15 @@
+package com.yosr.app.features.notes;
+
+import java.util.List;
+import java.util.Optional;
+
+public interface NoteStore {
+
+  List<Note> list();
+
+  Optional<Note> get(int id);
+
+  Note add(String title, String body);
+
+  Optional<Note> update(int id, String title, String body);
+}

package/files/src/main/java/com/yosr/app/features/notes/NotesController.java

@@ -0,0 +1,47 @@
+package com.yosr.app.features.notes;
+
+import com.yosr.app.features.notes.NoteDtos.NoteCreate;
+import com.yosr.app.features.notes.NoteDtos.NoteResponse;
+import com.yosr.app.features.notes.NoteDtos.NoteUpdate;
+import java.net.URI;
+import java.util.List;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PatchMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/notes")
+public class NotesController {
+  private final NotesService notes;
+
+  public NotesController(NotesService notes) {
+    this.notes = notes;
+  }
+
+  // @seed:anchor notes-group
+  @GetMapping
+  public List<NoteResponse> list() {
+    return notes.list().stream().map(NoteResponse::from).toList();
+  }
+
+  @GetMapping("/{id}")
+  public NoteResponse get(@PathVariable int id) {
+    return NoteResponse.from(notes.get(id));
+  }
+
+  @PostMapping
+  public ResponseEntity<NoteResponse> create(@RequestBody NoteCreate body) {
+    Note note = notes.create(body);
+    return ResponseEntity.created(URI.create("/notes/" + note.id())).body(NoteResponse.from(note));
+  }
+
+  @PatchMapping("/{id}")
+  public NoteResponse update(@PathVariable int id, @RequestBody NoteUpdate body) {
+    return NoteResponse.from(notes.update(id, body));
+  }
+}

package/files/src/main/java/com/yosr/app/features/notes/NotesService.java

@@ -0,0 +1,43 @@
+package com.yosr.app.features.notes;
+
+import com.yosr.app.shared.NotFoundException;
+import java.util.List;
+
+public final class NotesService {
+
+  private final NoteStore store;
+
+  public NotesService(NoteStore store) {
+    this.store = store;
+  }
+
+  public List<Note> list() {
+    return store.list();
+  }
+
+  public Note get(int id) {
+    return store.get(id).orElseThrow(() -> new NotFoundException("Note " + id + " was not found."));
+  }
+
+  public Note create(NoteDtos.NoteCreate input) {
+    String title = requireTitle(input.title());
+    return store.add(title, input.body());
+  }
+
+  public Note update(int id, NoteDtos.NoteUpdate input) {
+    if (input.title() != null) {
+      requireTitle(input.title());
+    }
+    return store
+        .update(id, input.title(), input.body())
+        .orElseThrow(() -> new NotFoundException("Note " + id + " was not found."));
+  }
+
+  private static String requireTitle(String title) {
+    String trimmed = title == null ? "" : title.trim();
+    if (trimmed.isEmpty()) {
+      throw new IllegalArgumentException("Title must not be blank.");
+    }
+    return trimmed;
+  }
+}

package/files/src/main/java/com/yosr/app/shared/NotFoundException.java

@@ -0,0 +1,8 @@
+package com.yosr.app.shared;
+
+public class NotFoundException extends RuntimeException {
+
+  public NotFoundException(String message) {
+    super(message);
+  }
+}

package/files/src/main/resources/application.yml

@@ -0,0 +1,7 @@
+server:
+  port: 8080
+
+app:
+  name: ${APP_NAME:__seed_projectName__}
+  cors-origins: ${CORS_ORIGINS:http://localhost:5173}
+# @seed:anchor application-config

package/files/src/test/java/com/yosr/app/NotesApiTest.java

@@ -0,0 +1,102 @@
+package com.yosr.app;
+
+import static org.hamcrest.Matchers.hasSize;
+import static org.hamcrest.Matchers.is;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.patch;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.MvcResult;
+import org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+import org.springframework.web.context.WebApplicationContext;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+
+// @seed:anchor test-class-annotations
+@SpringBootTest
+class NotesApiTest {
+
+  @Autowired private WebApplicationContext context;
+
+  @Autowired private ObjectMapper objectMapper;
+
+  private MockMvc mockMvc;
+
+  // @seed:anchor test-client-headers
+  @BeforeEach
+  void resetHeaders() {
+    mockMvc = MockMvcBuilders.webAppContextSetup(context).build();
+    // @seed:anchor test-setup
+  }
+
+  private MockHttpServletRequestBuilder forNotes(MockHttpServletRequestBuilder builder) {
+    // @seed:anchor notes-request-wrap
+    return builder;
+  }
+
+  @Test
+  void healthIsOk() throws Exception {
+    mockMvc
+        .perform(get("/health"))
+        .andExpect(status().isOk())
+        .andExpect(jsonPath("$.status", is("ok")));
+  }
+
+  @Test
+  void createListGetAndUpdateANote() throws Exception {
+    MvcResult created =
+        mockMvc
+            .perform(
+                forNotes(post("/notes"))
+                    .contentType(MediaType.APPLICATION_JSON)
+                    .content("{\"title\":\"Hello\",\"body\":\"World\"}"))
+            .andExpect(status().isCreated())
+            .andReturn();
+
+    JsonNode note = objectMapper.readTree(created.getResponse().getContentAsByteArray());
+    int id = note.get("id").asInt();
+
+    mockMvc
+        .perform(forNotes(get("/notes")))
+        .andExpect(status().isOk())
+        .andExpect(jsonPath("$", hasSize(1)));
+
+    mockMvc
+        .perform(forNotes(get("/notes/" + id)))
+        .andExpect(status().isOk())
+        .andExpect(jsonPath("$.title", is("Hello")));
+
+    mockMvc
+        .perform(
+            forNotes(patch("/notes/" + id))
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("{\"title\":\"Hi\"}"))
+        .andExpect(status().isOk())
+        .andExpect(jsonPath("$.title", is("Hi")))
+        .andExpect(jsonPath("$.body", is("World")));
+  }
+
+  @Test
+  void missingNoteIs404() throws Exception {
+    mockMvc.perform(forNotes(get("/notes/999"))).andExpect(status().isNotFound());
+  }
+
+  @Test
+  void blankTitleIsRejected() throws Exception {
+    mockMvc
+        .perform(
+            forNotes(post("/notes"))
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("{\"title\":\"  \",\"body\":\"x\"}"))
+        .andExpect(status().isBadRequest());
+  }
+}

package/files/src/test/java/com/yosr/app/NotesServiceTest.java

@@ -0,0 +1,42 @@
+package com.yosr.app;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import com.yosr.app.features.notes.MemoryNoteStore;
+import com.yosr.app.features.notes.NoteDtos.NoteCreate;
+import com.yosr.app.features.notes.NoteDtos.NoteUpdate;
+import com.yosr.app.features.notes.NotesService;
+import com.yosr.app.shared.NotFoundException;
+import org.junit.jupiter.api.Test;
+
+class NotesServiceTest {
+
+  private static NotesService service() {
+    return new NotesService(new MemoryNoteStore());
+  }
+
+  @Test
+  void createThenGetReturnsTheNote() {
+    NotesService notes = service();
+    var created = notes.create(new NoteCreate("Hello", "Body"));
+    var found = notes.get(created.id());
+    assertEquals("Hello", found.title());
+    assertEquals("Body", found.body());
+  }
+
+  @Test
+  void getMissingNoteThrows() {
+    NotesService notes = service();
+    assertThrows(NotFoundException.class, () -> notes.get(99));
+  }
+
+  @Test
+  void updateChangesOnlyGivenFields() {
+    NotesService notes = service();
+    var created = notes.create(new NoteCreate("Hello", "Body"));
+    var updated = notes.update(created.id(), new NoteUpdate("Hi", null));
+    assertEquals("Hi", updated.title());
+    assertEquals("Body", updated.body());
+  }
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@yosr-ai/template-spring",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.6",
+  "description": "Yosr Seed Spring Boot template.",
+  "license": "MIT",
+  "homepage": "https://seed.yosr.ai",
+  "bugs": {
+    "email": "wzohny@gmail.com"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    "./seed.template.json": "./seed.template.json"
+  },
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "seed.template.json",
+    "files",
+    "features",
+    "style",
+    "rules"
+  ],
+  "engines": {
+    "node": ">=24"
+  }
+}

package/rules/architecture.md

@@ -0,0 +1,5 @@
+# Architecture
+
+Spring Boot REST on Java 25. `AppApplication` boots component scanning under `com.yosr.app`. A request hits `features/<feature>/` controllers, which call a service; the service talks to a `NoteStore` implementation (memory or JPA). Settings come from `application.yml` and environment variables via `AppSettings`.
+
+Unit tests exercise services with a memory store. HTTP tests use MockMvc in-process. Gate never runs schema migrations; Postgres reachability is via the gate service / `--database-url`.

package/rules/auth-api-key.md

@@ -0,0 +1,3 @@
+# Auth (API key)
+
+Callers send `X-API-Key` matching the `API_KEY` environment variable (`app.api-key`). `/health` stays open. Set `API_KEY` in `.env` for local runs.

package/rules/commands.md

@@ -0,0 +1,7 @@
+# Commands
+
+- `mvn -B -q dependency:resolve dependency-lock:check` — locked Maven resolve from `dependencies-lock.json`
+- `mvn -B -q spring-boot:run` — run the API
+- `mvn -B -q spotless:check` — Google Java Format (Spotless)
+- `mvn -B -q compile` — compile (`-Werror` on the compiler)
+- `mvn -B -q test` — JUnit 5 + MockMvc

package/rules/data-jpa.md

@@ -0,0 +1,3 @@
+# Data (JPA / Postgres)
+
+__seed_storageLabel__ through Spring Data JPA. `AppSettings` and `application.yml` read `DATABASE_URL`. Gate only checks reachability (throwaway container or `--database-url`); it does not run Flyway or Liquibase. Tests use `ddl-auto=create-drop` against throwaway Postgres or embedded H2.

package/rules/data-none.md

@@ -0,0 +1,3 @@
+# Data (memory)
+
+Notes live in an in-process `MemoryNoteStore`. Restarting the JVM clears data. No database URL is required.

package/rules/errors-result.md

@@ -0,0 +1,3 @@
+# Errors (Result)
+
+Services return `Result.Ok` / `Result.Err` instead of throwing for expected failures. Controllers map `Err` to HTTP status codes.

package/rules/errors-throw.md

@@ -0,0 +1,3 @@
+# Errors (throw)
+
+Expected failures raise typed exceptions (for example `NotFoundException`). `RestExceptionHandler` maps them to HTTP status codes.

package/rules/layout-feature.md

@@ -0,0 +1,5 @@
+# Layout (feature)
+
+- `__seed_domainDir__/notes/` holds that feature's models, store, service, and controller. Follow `notes/`.
+- `__seed_serverDir__/` holds app settings, config, filters, and health.
+- `__seed_sharedDir__/` holds cross-cutting types (errors, Result).

package/rules/layout-flat.md

@@ -0,0 +1,3 @@
+# Layout (flat)
+
+- Feature types live under the project root package (`__seed_domainDir__/`). Keep `core` and `shared` for infrastructure and shared types.

package/rules/layout-layer.md

@@ -0,0 +1,3 @@
+# Layout (layer)
+
+- Domain services live under `__seed_domainDir__/`. Shared types under `__seed_sharedDir__/`. Core/infrastructure under `__seed_serverDir__/`.

package/rules/project-overview.md

@@ -0,0 +1,5 @@
+# __seed_projectName__
+
+Spring Boot REST API on Java 25. Data: __seed_storageLabel__. Auth: __seed_authLabel__. Deploy: __seed_deploy__.
+
+Install with `mvn -B -q dependency:resolve dependency-lock:check` (committed `dependencies-lock.json`). Format with `mvn spotless:check`. Compile with `mvn compile` (warnings fail). Test with `mvn test` (JUnit 5 + MockMvc, no live server). Maven coordinates stay `com.yosr:app`.