release

AGENTS.md

@@ -1,8 +1,23 @@
 # AGENTS.md
 
-## Engineering principles for Codex in this repository
-
-When implementing changes in this codebase, prioritize consistency and consolidation over novelty.
+## Engineering principles in this repository
+
+- When implementing changes in this codebase, prioritize consistency and consolidation over novelty.
+
+### Code comments
+
+- **Default to no comments.** Code, names, and types are the documentation. Add a comment only when a future reader cannot recover the intent from the code itself.
+- **Never restate what the code does.** If the comment paraphrases the next line, delete it.
+- **Never explain a change you are making.** Comments are about the resulting code, not about the diff or the review that produced it.
+- **Never narrate trivial mechanics** ("seed the form", "fall back to default", "guard for unmount", "cleanup on success", "preserves siblings", etc.). If the function/variable name doesn't already say that, rename instead of commenting.
+- **No "why" boilerplate.** Don't write comments like "we do X so that Y" unless Y is genuinely surprising and not visible from reading the function. A two-word identifier (`safeFallback`, `corsHeaders`, …) usually beats a three-line comment.
+- **Allowed comments** (rare, deliberate):
+    - Workarounds for third-party bugs, with a link or version reference.
+    - Non-obvious invariants or ordering constraints that aren't enforced by the type system.
+    - Explanations *required* by another rule in this file (e.g. the `as` rule, the MUI polymorphic-strip cast rule).
+    - Spec citations when the code implements a non-trivial part of an external spec.
+- **JSDoc on exported APIs is fine** when it documents the *contract* (parameters, return shape, edge cases) — not when it restates the implementation.
+- **Delete stale comments aggressively.** A comment that lies is worse than no comment.
 
 ### Reuse before creating
 

apps/api/package.json

@@ -29,6 +29,7 @@
     "@nestjs/platform-express": "^11.0.1",
     "@nestjs/schedule": "^6.0.0",
     "@nestjs/typeorm": "^11.0.0",
+    "@oboku/archive-metadata": "^0.1.0",
     "@oboku/shared": "^0.8.0",
     "@oboku/synology": "^0.1.0",
     "@sentry/nestjs": "^10.25.0",

apps/api/src/books/books-metadata.service.ts

@@ -18,11 +18,11 @@ export class BooksMetadataService {
   ) {}
 
   public refreshMetadata = async (
-    body: { bookId: string },
+    body: { bookId: string; force?: boolean },
     providerCredentials: ProviderApiCredentials<DataSourceType>,
     userEmail: string,
   ) => {
-    const { bookId } = body
+    const { bookId, force } = body
 
     const userNameHex = emailToNameHex(userEmail)
 
@@ -63,6 +63,7 @@ export class BooksMetadataService {
           link,
           googleApiKey: this.appConfigService.GOOGLE_API_KEY,
           db,
+          force,
         },
         this.appConfigService,
         this.coversService,

apps/api/src/books/books.controller.ts

@@ -28,17 +28,17 @@ export class BooksController implements OnModuleInit {
 
   @Post("metadata/refresh")
   async metadataRefresh(
-    @Body() { bookId, providerCredentials }: RefreshBookMetadataRequest,
+    @Body() { bookId, providerCredentials, force }: RefreshBookMetadataRequest,
     @WithAuthUser() user: AuthUser,
   ) {
-    this.logger.log("metadataRefresh", bookId)
+    this.logger.log("metadataRefresh", bookId, { force })
 
     this.taskQueueService.enqueue(
       this.BOOKS_METADATA_REFRESH_QUEUE,
       () =>
         from(
           this.booksMetadataService.refreshMetadata(
-            { bookId },
+            { bookId, force },
             providerCredentials,
             user.email,
           ),

apps/api/src/config/AppConfigService.ts

@@ -104,10 +104,6 @@ export class AppConfigService {
    * ------------------------------------------------------------
    */
 
-  get COVERS_ALLOWED_EXT() {
-    return [".jpg", ".jpeg", ".png"]
-  }
-
   get COVERS_BUCKET_NAME() {
     return this.config.get("COVERS_BUCKET_NAME", { infer: true })
   }