From 11327edbcd8ec8d92533f8844c4df80ecb9c2810 Mon Sep 17 00:00:00 2001 From: Adhish-Krishna Date: Sun, 26 Apr 2026 12:14:12 +0530 Subject: [PATCH 1/6] feat: add repository guidelines and update TypeScript configuration --- AGENTS.md | 35 +++++++++++++++++++++++++++++++++++ tsconfig.json | 3 ++- 2 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..913eb7f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,35 @@ +# Repository Guidelines + +## Project Structure & Module Organization +`src/` contains the TypeScript core service. HTTP routes live in `src/api/`, background execution in `src/workers/` and `src/processors/`, channel integrations in `src/plugins/`, and shared infrastructure in `src/config/`, `src/database/`, and `src/utils/`. + +Tests are split between `tests/unit` and `tests/integration`, with helpers in `tests/testutil` and setup in `tests/setup.ts`. The Next.js admin UI lives in `dashboard/`. Docs and assets are in `api-docs/`, `architecture/`, and `assets/`. + +## Build, Test, and Development Commands +Install dependencies with `npm install` and `npm install --prefix dashboard`. + +- `npm run dev` starts the core API with `tsx` and `nodemon`. +- `npm run worker:dev`, `npm run processor:dev`, `npm run delayed-processor:dev`, and `npm run recovery:dev` start background services. +- `npm run build` compiles `src/` to `dist/` and rewrites path aliases. +- `npm run start` runs the compiled API from `dist/api/server.js`. +- `npm run test`, `npm run test:unit`, `npm run test:integration`, and `npm run test:coverage` run tests. +- `npm run lint:core` checks the core codebase; `npm run lint:dashboard` checks the dashboard. +- `npm run dev --prefix dashboard` starts the dashboard on port `3002`. + +## Coding Style & Naming Conventions +Use TypeScript with strict typing and existing `@src/*` path aliases. Match current style: 2-space indentation, camelCase for variables and functions, PascalCase for types, classes, and React components, and filenames such as `notification.controller.test.ts`. + +Plan changes before writing code. Follow low-level design principles: single responsibility, clear interfaces, useful dependency inversion, and explicit error handling. Do not duplicate logic; extract shared behavior into focused utilities, services, or test helpers. + +## Testing Guidelines +Vitest is the test runner. Integration tests also use `supertest`, `mongodb-memory-server`, and Redis mocks. Name test files with `.test.ts`, for example `tests/unit/plugins/loader.test.ts`. + +Every new feature or code path must include matching tests in `tests/`. Add unit suites for isolated logic and integration suites for API, persistence, plugin, processor, or worker behavior. + +## Commit & Pull Request Guidelines +Use short Conventional Commit style messages such as `feat: add email retry policy`, `fix: handle missing template`, or `docs: update setup notes`. Keep commits focused. + +PRs should include a summary, linked issue when applicable, test evidence, and screenshots or GIFs for `dashboard/` UI changes. Husky `pre-push` runs both lint commands. + +## Security & Configuration Tips +Do not commit secrets. Use `.env.example` as the template for `.env`, and update it when adding configuration. For local full-stack work, prefer `docker-compose.dev.yaml`; for core-only work, start infrastructure with `docker compose -f docker-compose.infra.yaml up -d`. diff --git a/tsconfig.json b/tsconfig.json index a3a79bc..733db57 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -3,6 +3,7 @@ "target": "ES2020", "module": "NodeNext", "moduleResolution": "NodeNext", + "ignoreDeprecations": "6.0", "baseUrl": ".", "paths": { "@src/*": ["src/*"] @@ -14,7 +15,7 @@ "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, - "resolveJsonModule": true + "resolveJsonModule": true, }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"] From 4dcdee7b544fb30e94e01aec714c9f391dad972a Mon Sep 17 00:00:00 2001 From: Adhish-Krishna Date: Fri, 19 Jun 2026 20:57:38 +0530 Subject: [PATCH 2/6] docs: add repository guidelines for project structure, development commands, and testing practices --- AGENTS.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..913eb7f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,35 @@ +# Repository Guidelines + +## Project Structure & Module Organization +`src/` contains the TypeScript core service. HTTP routes live in `src/api/`, background execution in `src/workers/` and `src/processors/`, channel integrations in `src/plugins/`, and shared infrastructure in `src/config/`, `src/database/`, and `src/utils/`. + +Tests are split between `tests/unit` and `tests/integration`, with helpers in `tests/testutil` and setup in `tests/setup.ts`. The Next.js admin UI lives in `dashboard/`. Docs and assets are in `api-docs/`, `architecture/`, and `assets/`. + +## Build, Test, and Development Commands +Install dependencies with `npm install` and `npm install --prefix dashboard`. + +- `npm run dev` starts the core API with `tsx` and `nodemon`. +- `npm run worker:dev`, `npm run processor:dev`, `npm run delayed-processor:dev`, and `npm run recovery:dev` start background services. +- `npm run build` compiles `src/` to `dist/` and rewrites path aliases. +- `npm run start` runs the compiled API from `dist/api/server.js`. +- `npm run test`, `npm run test:unit`, `npm run test:integration`, and `npm run test:coverage` run tests. +- `npm run lint:core` checks the core codebase; `npm run lint:dashboard` checks the dashboard. +- `npm run dev --prefix dashboard` starts the dashboard on port `3002`. + +## Coding Style & Naming Conventions +Use TypeScript with strict typing and existing `@src/*` path aliases. Match current style: 2-space indentation, camelCase for variables and functions, PascalCase for types, classes, and React components, and filenames such as `notification.controller.test.ts`. + +Plan changes before writing code. Follow low-level design principles: single responsibility, clear interfaces, useful dependency inversion, and explicit error handling. Do not duplicate logic; extract shared behavior into focused utilities, services, or test helpers. + +## Testing Guidelines +Vitest is the test runner. Integration tests also use `supertest`, `mongodb-memory-server`, and Redis mocks. Name test files with `.test.ts`, for example `tests/unit/plugins/loader.test.ts`. + +Every new feature or code path must include matching tests in `tests/`. Add unit suites for isolated logic and integration suites for API, persistence, plugin, processor, or worker behavior. + +## Commit & Pull Request Guidelines +Use short Conventional Commit style messages such as `feat: add email retry policy`, `fix: handle missing template`, or `docs: update setup notes`. Keep commits focused. + +PRs should include a summary, linked issue when applicable, test evidence, and screenshots or GIFs for `dashboard/` UI changes. Husky `pre-push` runs both lint commands. + +## Security & Configuration Tips +Do not commit secrets. Use `.env.example` as the template for `.env`, and update it when adding configuration. For local full-stack work, prefer `docker-compose.dev.yaml`; for core-only work, start infrastructure with `docker compose -f docker-compose.infra.yaml up -d`. From 0bd731d39c80f187c988df9399e27961a4dd9937 Mon Sep 17 00:00:00 2001 From: Adhish-Krishna Date: Fri, 19 Jun 2026 20:59:20 +0530 Subject: [PATCH 3/6] chore: remove deprecated option from TypeScript configuration --- tsconfig.json | 1 - 1 file changed, 1 deletion(-) diff --git a/tsconfig.json b/tsconfig.json index 733db57..83afc3e 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -3,7 +3,6 @@ "target": "ES2020", "module": "NodeNext", "moduleResolution": "NodeNext", - "ignoreDeprecations": "6.0", "baseUrl": ".", "paths": { "@src/*": ["src/*"] From cadea55f31c6c24bc7eef0ea6e4d10bff8928b8a Mon Sep 17 00:00:00 2001 From: Adhish-Krishna Date: Sat, 20 Jun 2026 11:36:35 +0530 Subject: [PATCH 4/6] feat: update GitHub Actions workflow to include linting for core and dashboard --- .github/workflows/build-and-push.yml | 53 ++++++++++++++++++++++++++-- 1 file changed, 51 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build-and-push.yml b/.github/workflows/build-and-push.yml index b18092b..9e43645 100644 --- a/.github/workflows/build-and-push.yml +++ b/.github/workflows/build-and-push.yml @@ -3,8 +3,8 @@ name: Build and Push Docker Images on: push: branches: - - main - master + - development paths: - 'dashboard/**' - 'src/**' @@ -13,8 +13,8 @@ on: - 'v*.*.*' pull_request: branches: - - main - master + - development paths: - 'dashboard/**' - 'src/**' @@ -32,11 +32,59 @@ env: DASHBOARD_IMAGE_NAME: ${{ github.repository_owner }}/simplens-dashboard jobs: + # ============================================ + # Lint: simplens-core + # ============================================ + lint-core: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run core lint + run: npm run lint:core + + # ============================================ + # Lint: simplens-dashboard + # ============================================ + lint-dashboard: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Install dashboard dependencies + run: npm ci --prefix dashboard + + - name: Run dashboard lint + run: npm run lint:dashboard + # ============================================ # Test: simplens-core # ============================================ test-core: runs-on: ubuntu-latest + needs: + - lint-core + - lint-dashboard steps: - name: Checkout repository uses: actions/checkout@v4 @@ -108,6 +156,7 @@ jobs: # ============================================ build-dashboard: runs-on: ubuntu-latest + needs: test-core permissions: contents: read packages: write From e778e56e96c28912fea22dc51a32dbab6638b4be Mon Sep 17 00:00:00 2001 From: Adhish-Krishna Date: Sat, 20 Jun 2026 11:36:44 +0530 Subject: [PATCH 5/6] docs: update contribution workflow to branch from development instead of master --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7db1d72..3bce98e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -138,7 +138,7 @@ Notes: ## Contribution Workflow 1. Look into the open issues on [simplens-core issues](https://github.com/SimpleNotificationSystem/simplens-core/issues) and choose an issue you like to solve. -2. Create a new branch (`-`) from the `master` branch. +2. Create a new branch (`-`) from the `development` branch. 3. Solve or complete the feature/bug mentioned in the issue. 4. Add or update tests for behavior changes. 5. Run lint + tests locally. From 6366baac270f3da8d96a66c428c8f44016738186 Mon Sep 17 00:00:00 2001 From: Adhish-Krishna Date: Sat, 20 Jun 2026 11:50:49 +0530 Subject: [PATCH 6/6] feat: update Node.js version requirements and add verification step in workflows --- .github/workflows/build-and-push.yml | 15 ++++++++++++--- .nvmrc | 1 + dashboard/package.json | 3 +++ package.json | 3 +++ packages/config-gen/package.json | 3 +++ packages/create-simplens-plugin/package.json | 6 +++--- packages/mcp-server/package.json | 3 +++ packages/onboard/package.json | 3 +++ packages/sdk/package.json | 3 +++ 9 files changed, 34 insertions(+), 6 deletions(-) create mode 100644 .nvmrc diff --git a/.github/workflows/build-and-push.yml b/.github/workflows/build-and-push.yml index 9e43645..b0511eb 100644 --- a/.github/workflows/build-and-push.yml +++ b/.github/workflows/build-and-push.yml @@ -44,9 +44,12 @@ jobs: - name: Set up Node.js uses: actions/setup-node@v4 with: - node-version: '22' + node-version: '22.x' cache: 'npm' + - name: Verify Node.js version + run: node --version + - name: Install dependencies run: npm ci @@ -65,9 +68,12 @@ jobs: - name: Set up Node.js uses: actions/setup-node@v4 with: - node-version: '22' + node-version: '22.x' cache: 'npm' + - name: Verify Node.js version + run: node --version + - name: Install dependencies run: npm ci @@ -92,9 +98,12 @@ jobs: - name: Set up Node.js uses: actions/setup-node@v4 with: - node-version: '22' + node-version: '22.x' cache: 'npm' + - name: Verify Node.js version + run: node --version + - name: Install dependencies run: npm ci diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..8fdd954 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +22 \ No newline at end of file diff --git a/dashboard/package.json b/dashboard/package.json index 707e7dc..9531ac3 100644 --- a/dashboard/package.json +++ b/dashboard/package.json @@ -2,6 +2,9 @@ "name": "dashboard", "version": "1.2.1", "private": true, + "engines": { + "node": ">=22.0.0" + }, "scripts": { "dev": "next dev -p 3002", "build": "NODE_ENV=production next build", diff --git a/package.json b/package.json index cb7d41a..9ef4e99 100644 --- a/package.json +++ b/package.json @@ -5,6 +5,9 @@ "description": "Open-source plugin-based notification orchestration engine for developers who value control ", "main": "dist/api/server.js", "type": "module", + "engines": { + "node": ">=22.0.0" + }, "scripts": { "test": "vitest run", "test:watch": "vitest", diff --git a/packages/config-gen/package.json b/packages/config-gen/package.json index e56ecdc..e8b735c 100644 --- a/packages/config-gen/package.json +++ b/packages/config-gen/package.json @@ -3,6 +3,9 @@ "version": "1.0.2", "description": "CLI tool to generate simplens.config.yaml from plugin manifests", "type": "module", + "engines": { + "node": ">=22.0.0" + }, "bin": { "simplens-config": "./dist/index.js" }, diff --git a/packages/create-simplens-plugin/package.json b/packages/create-simplens-plugin/package.json index 478dd45..f276ff2 100644 --- a/packages/create-simplens-plugin/package.json +++ b/packages/create-simplens-plugin/package.json @@ -28,6 +28,9 @@ ], "author": "", "license": "MIT", + "engines": { + "node": ">=22.0.0" + }, "dependencies": { "@clack/prompts": "^1.0.0", "chalk": "^5.3.0", @@ -44,9 +47,6 @@ "typescript": "^5.0.0", "vitest": "^2.0.0" }, - "engines": { - "node": ">=18.0.0" - }, "files": [ "dist", "README.md" diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json index 099b8eb..a82299f 100644 --- a/packages/mcp-server/package.json +++ b/packages/mcp-server/package.json @@ -4,6 +4,9 @@ "description": "Remote MCP server for SimpleNS notification orchestration engine", "type": "module", "main": "dist/index.js", + "engines": { + "node": ">=22.0.0" + }, "bin": { "simplens-mcp": "dist/index.js" }, diff --git a/packages/onboard/package.json b/packages/onboard/package.json index 5c69b61..dd5db2a 100644 --- a/packages/onboard/package.json +++ b/packages/onboard/package.json @@ -3,6 +3,9 @@ "version": "1.0.11", "type": "module", "main": "dist/index.js", + "engines": { + "node": ">=22.0.0" + }, "bin": { "simplens-onboard": "./dist/index.js" }, diff --git a/packages/sdk/package.json b/packages/sdk/package.json index bbfd9b9..71409fb 100644 --- a/packages/sdk/package.json +++ b/packages/sdk/package.json @@ -5,6 +5,9 @@ "main": "dist/index.js", "types": "dist/index.d.ts", "type": "module", + "engines": { + "node": ">=22.0.0" + }, "exports": { ".": { "types": "./dist/index.d.ts",