@raclettejs/core 0.0.1

package/scripts/find-i18n-keys.cjs

@@ -0,0 +1,183 @@
+const fs = require("fs")
+const path = require("path")
+
+class I18nKeyFinder {
+  constructor(workspaceRoot, i18nKeysFile) {
+    this.workspaceRoot = workspaceRoot
+    this.i18nKeysFile = i18nKeysFile
+    this.usedKeys = new Set()
+    this.possiblyUsedKeys = new Set()
+    this.allKeys = new Set()
+
+    // Patterns to search for definite usage
+    this.definitePatterns = [
+      /\bt\(['"]([^'"]+)['"]\)/g, // t('key') or t("key")
+      /\bt\(['"]([^'"]+)['"],/g, // t('key', ...) or t("key", ...)
+      /\$t\(['"]([^'"]+)['"]\)/g, // $t('key') or $t("key")
+      /\$t\(['"]([^'"]+)['"],/g, // $t('key', ...) or $t("key", ...)
+    ]
+
+    // Patterns to search for possible usage (i18n object keys)
+    this.possiblePatterns = [
+      /i18n:\s*['"]([^'"]+)['"]/g, // i18n: "key" or i18n: 'key'
+    ]
+  }
+
+  // Load all i18n keys from your translation file
+  loadI18nKeys() {
+    try {
+      const content = fs.readFileSync(this.i18nKeysFile, "utf8")
+      const data = JSON.parse(content)
+
+      // Recursively extract all keys from nested object
+      const extractKeys = (obj, prefix = "") => {
+        Object.keys(obj).forEach((key) => {
+          const fullKey = prefix ? `${prefix}.${key}` : key
+
+          if (typeof obj[key] === "object" && obj[key] !== null) {
+            extractKeys(obj[key], fullKey)
+          } else {
+            this.allKeys.add(fullKey)
+          }
+        })
+      }
+
+      extractKeys(data)
+      console.log(`Loaded ${this.allKeys.size} i18n keys`)
+    } catch (error) {
+      console.error("Error loading i18n keys:", error)
+    }
+  }
+
+  // Search for translation key usage in a file
+  searchInFile(filePath) {
+    try {
+      const content = fs.readFileSync(filePath, "utf8")
+
+      // Search for definite usage patterns
+      this.definitePatterns.forEach((pattern) => {
+        let match
+
+        while ((match = pattern.exec(content)) !== null) {
+          this.usedKeys.add(match[1])
+        }
+      })
+
+      // Search for possible usage patterns
+      this.possiblePatterns.forEach((pattern) => {
+        let match
+
+        while ((match = pattern.exec(content)) !== null) {
+          this.possiblyUsedKeys.add(match[1])
+        }
+      })
+    } catch (error) {
+      // Skip files that can't be read
+    }
+  }
+
+  // Recursively search through directories
+  searchDirectory(dir) {
+    const items = fs.readdirSync(dir)
+
+    items.forEach((item) => {
+      const fullPath = path.join(dir, item)
+      const stat = fs.statSync(fullPath)
+
+      if (stat.isDirectory()) {
+        // Skip common directories that won't contain translation calls
+        if (
+          !["node_modules", ".git", "dist", "build", ".next"].includes(item)
+        ) {
+          this.searchDirectory(fullPath)
+        }
+      } else if (stat.isFile()) {
+        // Only search in relevant file types
+        const ext = path.extname(item).toLowerCase()
+
+        if ([".js", ".ts", ".jsx", ".tsx", ".vue", ".svelte"].includes(ext)) {
+          this.searchInFile(fullPath)
+        }
+      }
+    })
+  }
+
+  // Main function to find unused keys
+  findUnusedKeys() {
+    console.log("Loading i18n keys...")
+    this.loadI18nKeys()
+
+    console.log("Searching for key usage in workspace...")
+    this.searchDirectory(this.workspaceRoot)
+
+    console.log(`Found ${this.usedKeys.size} definitely used keys`)
+    console.log(`Found ${this.possiblyUsedKeys.size} possibly used keys`)
+
+    // Combine all used keys (definite + possible)
+    const allUsedKeys = new Set([...this.usedKeys, ...this.possiblyUsedKeys])
+
+    // Find unused keys
+    const unusedKeys = Array.from(this.allKeys).filter(
+      (key) => !allUsedKeys.has(key),
+    )
+
+    // Generate report
+    console.log("\n=== REPORT ===")
+    console.log(`Total i18n keys: ${this.allKeys.size}`)
+    console.log(`Definitely used keys: ${this.usedKeys.size}`)
+    console.log(`Possibly used keys: ${this.possiblyUsedKeys.size}`)
+    console.log(`Total used keys: ${allUsedKeys.size}`)
+    console.log(`Unused keys: ${unusedKeys.length}`)
+
+    // Show definitely used keys
+    if (this.usedKeys.size > 0) {
+      console.log("\nDefinitely used keys (t() and $t() functions):")
+      Array.from(this.usedKeys)
+        .sort()
+        .forEach((key) => console.log(`  ✓ ${key}`))
+    }
+
+    // Show possibly used keys
+    if (this.possiblyUsedKeys.size > 0) {
+      console.log('\nPossibly used keys (i18n: "key" patterns):')
+      Array.from(this.possiblyUsedKeys)
+        .sort()
+        .forEach((key) => console.log(`  ? ${key}`))
+    }
+
+    // Show unused keys
+    if (unusedKeys.length > 0) {
+      console.log("\nUnused keys:")
+      unusedKeys.sort().forEach((key) => console.log(`  - ${key}`))
+
+      // Save to file
+      fs.writeFileSync("unused-i18n-keys.txt", unusedKeys.join("\n"))
+      console.log("\nUnused keys saved to: unused-i18n-keys.txt")
+    }
+
+    // Save detailed report
+    const report = {
+      summary: {
+        total: this.allKeys.size,
+        definitelyUsed: this.usedKeys.size,
+        possiblyUsed: this.possiblyUsedKeys.size,
+        totalUsed: allUsedKeys.size,
+        unused: unusedKeys.length,
+      },
+      definitelyUsed: Array.from(this.usedKeys).sort(),
+      possiblyUsed: Array.from(this.possiblyUsedKeys).sort(),
+      unused: unusedKeys.sort(),
+    }
+
+    fs.writeFileSync("i18n-usage-report.json", JSON.stringify(report, null, 2))
+    console.log("Detailed report saved to: i18n-usage-report.json")
+  }
+}
+
+// Usage
+const workspaceRoot = process.argv[2] || "./"
+const i18nKeysFile = process.argv[3] || "./src/i18n/en.json"
+
+const finder = new I18nKeyFinder(workspaceRoot, i18nKeysFile)
+
+finder.findUnusedKeys()

package/scripts/sync-exports.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// This script generates index.js from index.d.ts by converting TypeScript exports
+// It adds .ts extensions to import paths since we're directly using TypeScript files with tsx
+
+import fs from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const rootDir = path.join(__dirname, "..")
+
+// Read the TypeScript declaration file
+const dtsPath = path.join(rootDir, "index.d.ts")
+const dtsContent = fs.readFileSync(dtsPath, "utf8")
+
+// Convert TypeScript declarations to JavaScript exports (adding .ts to imports)
+const jsContent = dtsContent
+  // Add TS file extension to relative imports
+  .replace(/from\s+['"](\.\/.+?)['"];/g, (match, importPath) => {
+    return `from "${importPath}.ts";`
+  })
+  // Handle comment lines
+  .replace(/\/\/.*$/gm, (match) => match)
+
+// Write the generated index.js file
+const jsPath = path.join(rootDir, "index.js")
+
+fs.writeFileSync(jsPath, jsContent)
+
+console.log("Successfully generated index.js from index.d.ts")

package/services/.dockerignore

@@ -0,0 +1,6 @@
+**/node_modules
+**/.nyc_output
+**/.dockerignore
+**/.git
+**/.gitignore
+**/docker-compose*

package/services/backend/.dockerignore

@@ -0,0 +1,12 @@
+node_modules
+.nyc_output
+.dockerignore
+.git
+.gitignore
+docker-compose\*
+README.md
+package.json
+yarn.lock
+.prettierrc
+eslint.config.js
+dist

package/services/backend/.env

@@ -0,0 +1,5 @@
+NODE_ENV=development
+RACLETTE_SERVER_TOKEN_SECRET=test
+SERVER_TOKEN_SECRET=asdas
+MONGO_HOST=mongodb://mongodb:2701/racletteAdmin
+REDIS_URL=redis://redis:6379

package/services/backend/.gitignore

@@ -0,0 +1,17 @@
+.nyc_output
+node_modules
+coverage
+data/core/tenant
+data/journal
+!data/.gitkeep
+dist
+yarn.error.log
+
+# just in case when moving around keys
+**/keys
+**/ssh-keys
+keys
+/ssh
+/.ssh
+id_rsa
+id_rsa.pub

package/services/backend/.vscode/launch.json

@@ -0,0 +1,18 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug: server build",
+      "skipFiles": ["<node_internals>/**"],
+      "program": "${workspaceFolder}/node_modules/tsc-alias/dist/bin/index.js",
+      "args": ["-p", "tsconfig.build.json", "--debug"],
+      "cwd": "${workspaceFolder}",
+      "console": "integratedTerminal"
+    }
+  ]
+}

package/services/backend/Dockerfile

@@ -0,0 +1,41 @@
+# matches node:lts-alpine at time of writing, but we don't want to risk updates we have not checked, so we manually define this version
+FROM node:24.4-alpine
+# context is from host machine app/ to make sure we can include the shared dir
+
+WORKDIR /app
+
+# add bash since alpine doesn't come with a shell
+RUN apk update && apk add bash curl
+
+COPY backend/package.json backend/yarn.lock backend/.npmrc backend/.yarnrc ./
+
+ARG NODE_ENV
+
+RUN if [ "$NODE_ENV" = "internal" ]; \
+      then yarn install; \
+      else yarn install --production=true; \
+      fi;
+
+# make sure our raclette packages are being resolved by adding a symlink to handle nodes module resolution
+RUN mkdir -p /app/node_modules/@raclettejs/core
+RUN ln -sf /app/src /app/node_modules/@raclettejs/core/backend
+
+# copy everything else that is not ignored (see .dockerignore)
+COPY backend ./
+
+# set default values
+ENV PORT 3000
+
+# Note: when running production mode locally, make sure there is no node_modules folder under frontend in your filesystem
+# otherwise this will not work because it overwrites the installed deps
+RUN if [ "$NODE_ENV" != "internal" ]; then \
+      yarn run build; \
+      fi
+
+
+# set port
+EXPOSE $PORT
+EXPOSE 9229
+
+# default command
+CMD ["yarn", "run", "dev"]

package/services/backend/README.md

@@ -0,0 +1,172 @@
+# Pacifico API
+
+For initial setup, see the end of the file.
+
+## Docker-Compose
+
+The API runs under the service name `api`. For development we will also give a ccontainer name to make writing the READMEs easiert. It is called `portal-api`. On production this name will be auto-generated to prevent docker name collision. This also means you cannot start two instances of our services locally.
+
+### Installing packages
+
+When installing new packages, please exec into the docker container beforehand. Do not run `yarn add` on your machine.
+
+`docker exec -it portal-api bash`
+And install again:
+`yarn add ...`
+
+### EsLint
+
+For Eslint to work you need to install the packages locally. It is fine to run `yarn install`on your machine (outside of the container). Just never so `yarn add...` there.
+
+For now manually, run the linter and formatter before commiting or at the end of your work on a branch:
+`yarn run fixAndFormat`
+
+Manually check any lint errors and fix them before commiting. It is recommended to not commit any errors (only warning).
+
+You can run the linter standalone with: `yarn run lint:fix`
+And format after: `yarn run format`.
+
+The linter itself is not formatting, so it is required to format after the linter fixed code.
+
+### Debugging
+
+If you use VS code and want to attach your debugger to node within the api docker container, add the following to your launch.json:
+
+```json
+{
+  "configurations": [
+    {
+      "name": "Docker: Attach to Node",
+      "type": "node",
+      "request": "attach",
+      "port": 9229,
+      "address": "localhost",
+      "restart": true,
+      "localRoot": "${workspaceFolder}/services/backend",
+      "remoteRoot": "/app"
+    }
+  ]
+}
+```
+
+Make sure to start the backend with the `dev:inspect` command and to map the port 9229:9229 in the docker-compose(.override).
+
+For the auto-restart to fully work, we need to add a start delay. Create a `tasks.json`file besides your `launch.json` with the following content:
+
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "delay",
+      "type": "shell",
+      "command": "${workspaceFolder}/delay-api-debugger.sh",
+      "problemMatcher": []
+    }
+  ]
+}
+```
+
+If you have permission errors, make sure the delay shell script is executable under `app/api`
+
+```
+chmod +x delay-api-debugger.sh
+```
+
+### Shared Folder
+
+The shared folder is mounted during container build. To make your IDE work with the given path INSIDE of api, while shared is still located outside of api, you need to symlink it.
+
+```
+cd app/api
+ln -s ../shared ./shared
+```
+
+## Initial Setup
+
+### Fill the database / Adding fixturees
+
+Assuming you have already built and started all containers in the root of the
+mono repo, run the following commands to fill the mongodb with the initial dev example data.
+
+As a prerequisite, you need to install 'jq' on your dev machine (e.g. with `brew` on mac)
+
+```bash
+# generate a token with the login-dev command (path expects you to be on root level)
+token=$(./app/api/bin/login-dev)
+
+# import the fixtures by calling the api endpoint POST /core/system/fixtures
+# e.g. with curl
+curl -X POST \
+  -H "$token" \
+  -H 'Accept-Version: 1.0' \
+  -H 'Content-Type: application/json' \
+  -d '{"useDeprecatedVersionAndDeleteDatabase": true}' \
+  http://localhost:8082/core/system/fixtures
+```
+
+The token generation will only work if there are NO users in the database. If you want to call the fixture endpoint anyway, you need to use an auth token of one of the exisiting user. Or delete all users from the database, e.g. with the ui tool `mongoCompass`.
+
+Also note, that you are required to run database migrations as the deprecated fixture flow is not up to date. See below.
+
+### Run migrations
+
+TODO: On API container startup migrations will run. So usually there is no need to interact with them unless you are developing.
+NOTE: Currently all migrations have to be executed by hand!
+
+Exec into to api container: `docker exec -it portal-api bash` and run all yarn scripts related to migrations there. You can run migrations from your machine as well, but due to package differences, it is recommended to do this sensible job from within the docker environment!
+
+To create a new file use this command: `yarn run migrate:create name-your-file`
+
+This applies all migrations that had not run yet: `yarn run migrate:up`. Run this also when you have set up your database with fixture data, as the old fixture flow is a bit deprecated. It will be replaced in the future.
+
+This reverts changed until a given script name (or all if none is given): `yarn run migrate:down`
+
+Migration status: `yarn run migrate:status`
+
+## Troubleshooting
+
+### On Login: 429 - Too many Retries
+
+Due to security reasons the login api logs and blocks too many failed login attempts. Just for consistency this also happens for local development.
+
+But you can easily use the admin endpoints to remove these entries, if you need to. Normally calling this should be suitable (locally)
+
+`DELETE http://localhost:8081/core/admin/cache/blocks/172.20.0.1`
+
+Or you can delete all entries:
+
+`DELETE http://localhost:8081/core/admin/cache/blocks`
+
+You can always see the tracked attempts with this (to retrieve your key (ip address) for the first command):
+
+`http://localhost:8081/core/admin/cache/blocks`
+
+### Error when building the image or running any commands
+
+```
+error /app/node_modules/bcrypt: Command failed.
+Exit code: 1
+Command: node-pre-gyp install --fallback-to-build
+Arguments:
+Directory: /app/node_modules/bcrypt
+Output:
+/app/node_modules/wide-align/align.js:2
+var stringWidth = require('string-width')
+                  ^
+Error [ERR_REQUIRE_ESM]: require() of ES Module /app/node_modules/string-width/index.js from /app/node_modules/wide-align/align.js not supported.
+Instead change the require of index.js in /app/node_modules/wide-align/align.js to a dynamic import() which is available in all CommonJS modules.
+    at Object.<anonymous> (/app/node_modules/wide-align/align.js:2:19) {
+  code: 'ERR_REQUIRE_ESM'
+```
+
+This error usually happens when you install a new package for the api from your host machine. To fix it you need to exec into the api container:
+`docker exec -it portal-api bash`
+
+Remove the yarn.lock file:
+`rm -f yarn.lock`
+
+And install again:
+`yarn install`
+
+This will align your versions and also update your yarn.lock file. Commit it!

package/services/backend/delay-api-debugger.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+sleep 1

package/services/backend/dist/src/app.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Primary entry file to the app
+ */
+import type { FastifyInstance } from "fastify";
+/**
+ * Main application factory function
+ */
+declare const _default: () => Promise<FastifyInstance>;
+export default _default;

package/services/backend/dist/src/app.js

@@ -0,0 +1,164 @@
+import fastifyCors from "@fastify/cors"
+import fastifySchedule from "@fastify/schedule"
+import fastifySensible from "@fastify/sensible"
+import Fastify from "fastify"
+import healthcheck from "fastify-custom-healthcheck"
+import { dirname } from "path"
+import pino from "pino"
+import { Transform } from "stream"
+import { fileURLToPath } from "url"
+// Application components
+import registerCore from "./domains/index.js"
+import { registerPlugins } from "./core/pluginSystem/pluginLoader.js"
+import initializeSocketSystem from "./core/sockets/socketManager.js"
+import jwt from "./modules/authentication/index.js"
+import eventbus from "./core/eventBus/index.js"
+import headersPlugin from "./core/http/headers.js"
+import httpClient from "./core/http/httpService.js"
+import requestParamsPlugin from "./core/http/request-params.plugin.js"
+import mongodb from "./modules/database/providers/mongodb/mongoConnection.js"
+import redisPlugin from "./modules/cache/providers/redis/redisConnection.js"
+import socket from "./core/sockets/index.js"
+import taskManager from "./core/backgroundTasks/taskManager.js"
+import configService from "./core/config/configService.js"
+import {
+  generateAllFrontendConfigs,
+  setFastifyInstanceForGeneration,
+} from "./core/pluginSystem/configGenerator/index.js"
+import generateRegisteredSchemas from "./core/validation/schemaGenerator.js"
+// Environment type guard
+const NODE_ENV = process.env.NODE_ENV
+/* Set global variables */
+global.__filename = fileURLToPath(import.meta.url)
+global.__dirname = dirname(__filename)
+/**
+ * Logger filter stream to exclude plugin logs when configured
+ */
+class PluginFilterStream extends Transform {
+  constructor() {
+    super({ objectMode: true })
+  }
+  _transform(chunk, _, callback) {
+    try {
+      const log = JSON.parse(chunk.toString())
+      if (!process.env.DISABLE_PLUGIN_LOGS || !log.plugin) {
+        this.push(JSON.stringify(log) + "\n")
+      }
+    } catch {
+      // Pass through if parsing fails
+      this.push(chunk)
+    }
+    callback()
+  }
+}
+/**
+ * Configure and create the logger
+ */
+const createLogger = () => {
+  const isDevelopment = NODE_ENV === "development"
+  const usePrettyLogs = process.env.PRETTY_LOGS === "true"
+  const logLevel = process.env.LOG_LEVEL ?? "debug"
+  const disablePluginLogs = process.env.DISABLE_PLUGIN_LOGS === "true"
+  const logger = {
+    development: {
+      transport: {
+        target: "pino-pretty",
+        options: {
+          translateTime: "HH:MM:ss Z",
+          ignore: "pid,hostname",
+        },
+      },
+    },
+    production: true,
+    test: false,
+  }
+  logger.info("Logger initialized successfully")
+  return logger
+}
+/**
+ * Main application factory function
+ */
+export default async () => {
+  const environment = process.env.NODE_ENV
+  const envToLogger = createLogger()
+  const fastify = Fastify({
+    loggerInstance: envToLogger[environment] ?? true,
+    disableRequestLogging: true,
+    trustProxy: true,
+  })
+  // Validate required environment variables
+  if (!process.env.SERVER_TOKEN_SECRET) {
+    fastify.log.fatal("Missing config SERVER_TOKEN_SECRET")
+    throw new Error("Canceling...")
+  }
+  await configService.init()
+  // setup route tracker for plugin code generation
+  setFastifyInstanceForGeneration(fastify)
+  // Register core plugins
+  fastify.register(eventbus)
+  await fastify.register(mongodb, { uri: process.env.MONGO_HOST ?? "" })
+  fastify.register(headersPlugin)
+  fastify.register(jwt, { secret: process.env.SERVER_TOKEN_SECRET })
+  fastify.register(redisPlugin, {
+    url: process.env.REDIS_URL,
+    options: {
+      maxRetriesPerRequest: 3,
+      enableReadyCheck: true,
+    },
+  })
+  fastify.register(socket)
+  fastify.register(requestParamsPlugin)
+  fastify.register(taskManager)
+  // Register utility plugins
+  fastify.register(fastifySensible)
+  fastify.register(fastifySchedule)
+  await fastify.register(httpClient, {})
+  // Configure CORS
+  fastify.register(fastifyCors, {
+    origin: "*",
+    methods: "GET,PUT,HEAD,POST,PATCH,DELETE",
+    strictPreflight: false,
+    allowedHeaders: [
+      "Accept",
+      "Accept-Version",
+      "Access-Control-Allow-Headers",
+      "Access-Control-Request-Method",
+      "Authorization",
+      "Content-Range",
+      "Content-Type",
+      "Origin",
+      "current-project",
+      "app-session-id",
+      "app-request-code",
+      "app-broadcast-channels",
+    ],
+  })
+  // Add health check
+  fastify.register(healthcheck, {
+    info: {
+      env: NODE_ENV,
+    },
+    schema: { tags: ["core/system"] },
+  })
+  // Register application components
+  await fastify.register(registerCore, { prefix: "/core" })
+  // Register plugins
+  try {
+    await registerPlugins(fastify)
+    fastify.log.info("Plugins registered successfully")
+  } catch (error) {
+    fastify.log.error("Plugin registration failed:" + error.message)
+  }
+  // Log registered routes in debug mode
+  fastify.log.debug(fastify.printRoutes())
+  // Generate schemas and types
+  await generateRegisteredSchemas(fastify)
+  await generateAllFrontendConfigs()
+  // Initialize socket system
+  if (process.env.RACLETTE_BUILD_MODE !== "generate") {
+    initializeSocketSystem(fastify)
+    await fastify.ready()
+    fastify.eventbus.emit("appReady")
+  }
+  return fastify
+}

package/services/backend/dist/src/core/backgroundTasks/taskManager.d.ts

@@ -0,0 +1,12 @@
+import type { IntervalTaskOptions, TaskOptions } from "../backgroundTasks/taskManagerTypes.js";
+import type { FastifyInstance } from "fastify";
+declare const setupTaskManager: (fastify: FastifyInstance) => {
+    createIntervalTask: (name: string, handler: () => Promise<void>, options: IntervalTaskOptions) => void;
+    cancelTask: (name: string) => void;
+    markAppReady: () => void;
+    stopAllTasks: () => void;
+    getTaskCount: () => number;
+};
+declare const _default: (fastify: FastifyInstance) => Promise<void>;
+export default _default;
+export { setupTaskManager, type TaskOptions, type IntervalTaskOptions };