@devopsplaybook.io/common-utils 1.10.1-beta.23.b1906d7 → 1.11.0-beta.24.d8f9aef

package/.github/workflows/reusable-pr-verify.yml

@@ -1,181 +0,0 @@
-name: "Reusable: PR Verify"
-
-on:
-  workflow_call:
-    inputs:
-      docker_platforms:
-        description: "Docker platforms to build for"
-        required: false
-        type: string
-        default: "linux/arm64/v8,linux/amd64"
-      node_app_directories:
-        description: "JSON array of Node.js app directories to build, lint, and test"
-        required: false
-        type: string
-        default: ""
-      node_version:
-        description: "Node.js version to use"
-        required: false
-        type: string
-        default: "22"
-    secrets:
-      DOCKER_HUB_USERNAME:
-        required: true
-      DOCKER_HUB_ACCESS_TOKEN:
-        required: true
-      QUALITY_DASHBOARD_TOKEN:
-        required: false
-      QUALITY_DASHBOARD_URL:
-        required: false
-
-jobs:
-  version-check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-
-      - name: Fetch main branch
-        run: git fetch origin main --depth=1
-
-      - name: Verify version is higher than main
-        run: |
-          PR_VERSION=$(jq -r '.version' package.json)
-          MAIN_VERSION=$(git show origin/main:package.json | jq -r '.version')
-
-          echo "PR version:   ${PR_VERSION}"
-          echo "Main version: ${MAIN_VERSION}"
-
-          if [ "$PR_VERSION" = "$MAIN_VERSION" ]; then
-            echo "::error::PR version (${PR_VERSION}) must be higher than main branch version (${MAIN_VERSION}). Please bump the version in package.json."
-            exit 1
-          fi
-
-          HIGHER=$(printf '%s\n%s' "$PR_VERSION" "$MAIN_VERSION" | sort -V | tail -n1)
-          if [ "$HIGHER" != "$PR_VERSION" ]; then
-            echo "::error::PR version (${PR_VERSION}) is lower than main branch version (${MAIN_VERSION}). Please bump the version in package.json."
-            exit 1
-          fi
-
-          echo "Version check passed: ${PR_VERSION} > ${MAIN_VERSION}"
-
-  node-build:
-    needs: version-check
-    if: inputs.node_app_directories != ''
-    strategy:
-      matrix:
-        app: ${{ fromJSON(inputs.node_app_directories) }}
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: ${{ matrix.app }}
-    steps:
-      - uses: actions/checkout@v7
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v7
-        with:
-          node-version: ${{ inputs.node_version }}
-          cache: "npm"
-          cache-dependency-path: ${{ matrix.app }}/package-lock.json
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Lint
-        run: npm run lint
-
-      - name: Test
-        run: npm run test
-
-      - name: Zip coverage and upload to Quality Dashboard
-        if: always()
-        env:
-          QUALITY_DASHBOARD_URL: ${{ secrets.QUALITY_DASHBOARD_URL }}
-          QUALITY_DASHBOARD_TOKEN: ${{ secrets.QUALITY_DASHBOARD_TOKEN }}
-        run: |
-          APP_NAME="${{ matrix.app }}"
-          PACKAGE_NAME=$(node -p "require('./package.json').name")
-          REPORT_KEY="$(echo "$APP_NAME" | sed 's/[^a-zA-Z0-9._:\-\/]/_/g')_coverage"
-
-          if [ -d coverage ]; then
-            if [ -z "$QUALITY_DASHBOARD_URL" ] || [ -z "$QUALITY_DASHBOARD_TOKEN" ]; then
-              echo "Quality Dashboard URL or token not set, skipping upload"
-              exit 0
-            fi
-            # Zip coverage contents at root level so the jest processor
-            # finds coverage-final.json / clover.xml directly
-            (cd coverage && zip -r "${{ runner.temp }}/coverage.zip" .)
-
-            META=$(jq -n \
-              --arg key "$REPORT_KEY" \
-              --arg pkg "$PACKAGE_NAME" \
-              '{
-                key: $key,
-                displayName: "Coverage: \($pkg)",
-                processor: "jest"
-              }')
-
-            echo "Uploading coverage: $REPORT_KEY"
-            HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
-              -X POST "$QUALITY_DASHBOARD_URL/api/reports/" \
-              -H "x-upload-token: $QUALITY_DASHBOARD_TOKEN" \
-              -F "meta=$META" \
-              -F "file=@${{ runner.temp }}/coverage.zip" \
-              --max-time 30)
-
-            if [ "$HTTP_CODE" = "201" ]; then
-              echo "\u2713 Coverage uploaded ($HTTP_CODE)"
-            else
-              echo "\u26a0 Upload returned HTTP $HTTP_CODE"
-            fi
-          else
-            echo "No coverage/ directory found, skipping upload"
-          fi
-
-  docker-build:
-    needs: version-check
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
-
-      - name: Login to Docker Hub
-        uses: docker/login-action@v4
-        with:
-          username: ${{ secrets.DOCKER_HUB_USERNAME }}
-          password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
-
-      - name: Build and Push Docker Image
-        env:
-          DOCKER_HUB_USERNAME: ${{ secrets.DOCKER_HUB_USERNAME }}
-          DOCKER_PLATFORMS: ${{ inputs.docker_platforms }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-        run: |
-          set -e
-          SERVICE_NAME=$(jq -r '.name' package.json)
-          IMAGE="${DOCKER_HUB_USERNAME}/${SERVICE_NAME}"
-
-          # `beta-pr-<number>` is the immutable per-PR reference: it identifies
-          # exactly the artifact validated by this pull request, and the merge
-          # build promotes it as-is to the semantic version tags.
-          PR_TAG="${PR_NUMBER}"
-          if [ -z "${PR_TAG}" ]; then
-            PR_TAG="manual-${GITHUB_SHA::7}"
-          fi
-
-          echo "Building ${IMAGE}:beta-pr-${PR_TAG} and ${IMAGE}:beta"
-          docker buildx build \
-            --platform "${DOCKER_PLATFORMS}" \
-            --push \
-            -f Dockerfile \
-            -t "${IMAGE}:beta-pr-${PR_TAG}" \
-            -t "${IMAGE}:beta" \
-            .

package/AGENTS.md

@@ -1,105 +0,0 @@
-# AGENTS.md
-
-This file provides context for AI coding agents working on this repository.
-
-## Repository Overview
-
-`@devopsplaybook.io/common-utils` is a shared npm library that centralizes utility modules used across devopsplaybook.io server projects. It serves two purposes:
-
-1. **Node.js library** (`src/`): Database access (SQLite via `better-sqlite3`, PostgreSQL via `pg.Pool`), configuration loading, OpenTelemetry context management, and small helpers.
-2. **Reusable GitHub Actions workflows** (`.github/workflows/reusable-*.yml`): Standardized CI/CD pipelines adopted by all projects in the organization.
-
-## Architecture
-
-```
-index.ts                    # Barrel re-exports for all modules
-src/
-  OTelContext.ts            # createOTelContext() factory (tracer/meter/logger singletons)
-  ConfigBase.ts             # Abstract base class for 3-layer config (env > config.json > defaults)
-  SqlDbUtils.ts             # SQLite operations (better-sqlite3, synchronous)
-  PostgresDbUtils.ts        # PostgreSQL operations (pg.Pool, async/Promise)
-  DbUtils.ts                # Unified facade dispatching to Sql or Postgres
-  DbUtilsNoTelemetry.ts     # Same DB ops without OTel span overhead
-  users/                    # Auth & user management module set
-    User.ts                 # User model, roles and application-defined scopes
-    UserSession.ts          # Decoded JWT session
-    UserApiToken.ts         # User API token model (SHA-256 hash only)
-    Auth.ts                 # JWT auth (key init, guards, session decode) + API token resolution
-    UserPassword.ts         # bcrypt password hashing/verification
-    UsersData.ts            # Users table CRUD (SQLite/Postgres)
-    UsersApiTokensData.ts   # users_api_tokens table CRUD (SQLite/Postgres)
-    UsersRoutes.ts          # Standard fastify user management routes (incl. self-service API tokens)
-  SystemCommand.ts          # Promise wrapper around child_process.exec
-  Timeout.ts                # Promise wrapper around setTimeout
-  LLM.ts                    # OpenAI-compatible chat completions client (LLMClient)
-  *.spec.ts                 # Co-located test files
-.github/workflows/
-  main-build.yml            # Caller: push to main -> reusable-npm-merge
-  pr-check.yml              # Caller: PR to main -> reusable-npm-pr
-  reusable-npm-merge.yml    # Lint + test + build + publish release to npm
-  reusable-npm-pr.yml       # Lint + test + build + publish beta tag + comment PR
-  reusable-npm-upgrade.yml  # npm-check-updates + auto PR (manual, workflow_call)
-  reusable-pr-verify.yml    # Matrix Node.js + multi-platform Docker build -> beta-pr-<PR> and beta
-  reusable-merge-build.yml  # Promotes the PR image to the version tags on merge (no build/lint/test)
-```
-
-## Weekly Dependency Updates
-
-The scheduled `npm-upgrade.yml` caller was retired: it created dependency upgrade pull requests every week that no one merged. `reusable-npm-upgrade.yml` is kept for manual, on-demand upgrades (`workflow_call`; adopting repositories can trigger it through their own `workflow_dispatch` caller).
-
-The weekly update of the shared npm libraries is agent-driven instead: a Kubernetes CronJob (`planner-shared-libraries-update` in the `DidierHoarau/didier-home` GitOps repository) creates a Planner task in the `Projects/xMaintenance` project every Friday, and the planner-llm-agent executes the `update-shared-libraries` skill from `DidierHoarau/planner-llm-agent-config`. The skill updates `otel-utils` first, then `otel-utils-fastify` and `common-utils` once the freshly published `otel-utils` version is visible on npm, then the consumer repositories discovered with GitHub code search. It applies minor/patch updates only (majors are reported, never applied), skips repositories already current against the npm registry, and delivers one squash-merged pull request per repository after green checks. Do not reintroduce a scheduled upgrade workflow in this repository: it would compete with the agent-driven update.
-
-## Key Conventions
-
-- **TypeScript**: Target ES2019, CommonJS output, strict mode enabled, declarations generated.
-- **Linting**: Uses `oxlint` with its default **recommended** preset. Minimize disable comments (`eslint-disable`-style comments are honored by oxlint); use them only when the rule cannot be satisfied (e.g. `no-explicit-any` is not enabled by the recommended preset, so `any` needs no directive).
-- **Tests**: Jest with `@swc/jest` transform (`jsc.target` matches tsconfig ES2019) and `v8` coverage provider. Spec files live next to source (`*.spec.ts`). Run with `npm run test`. The `tsconfig.spec.json` includes jest types; `npm run build` also type-checks specs (`tsc -p tsconfig.spec.json --noEmit`).
-- **No default exports**: All modules use named exports only.
-- **OTel dependency injection**: Every DB module exposes a `*SetOTel(tracer, logger)` function that must be called before `*Init()`. OTel instances are stored as module-level singletons.
-- **Auth modules**: `AuthSetOTel(tracer)` and `UsersDataSetOTel(tracer)` must be called before `AuthInit`. Application scopes are registered through `AuthInit(context, config, allScopes)`; `UsersRoutes` relies on `req.tracerSpanApi` set by the `otel-utils-fastify` hooks.
-- **ModuleLogger pattern**: `StandardLogger` only exposes `createModuleLogger(name)`. DB modules call `logger.createModuleLogger("ModuleName")` internally. Never call `.info()` or `.error()` directly on a `StandardLogger`.
-- **SQLite-first SQL**: Write SQL with `?` placeholders. The `DbUtils` facade and `DbUtilsNoTelemetry` module auto-convert to `$1, $2, ...` for Postgres via `convertToPostgresPlaceholders()`.
-- **Migration convention**: SQL files named `init-NNNN.sql`. `init-0000.sql` must create the `metadata` table. Subsequent files are applied in lexicographic order; applied versions are tracked in `metadata` for idempotency.
-- **Immutable Docker builds**: images are built once on the pull request (`reusable-pr-verify.yml` pushes `beta-pr-<PR number>` and `beta`) and promoted unchanged on merge (`reusable-merge-build.yml` writes `<version>`, `<major>`, `<minor>` and `latest`). The merge workflow runs no build, lint or test: it resolves the merged PR, carbon-copies the manifest with `docker buildx imagetools create --prefer-index=false`, then reads back each published digest and fails on a mismatch. It falls back to a full build only when no `beta-pr-<PR number>` image can be promoted. Image name and version come from the root `package.json`, and PR branches must be up to date with the default branch before merging.
-- **Reusable workflow permissions ceiling**: `reusable-merge-build.yml` may request only `contents: read`. A called workflow cannot exceed its caller's permissions, and callers use the default read-only token whose ceiling is `contents: read, pull-requests: none`. Adding `pull-requests: read` does not fail here — it fails in every consuming repo at startup with `Invalid workflow file ... requesting 'pull-requests: read', but is only allowed 'pull-requests: none'`. `GET /repos/{owner}/{repo}/commits/{sha}/pulls` works with `contents: read`, so no extra scope is needed.
-
-## Build and Verification
-
-```bash
-npm install
-npm run build    # tsc -> dist/
-npm run lint     # oxlint src (must pass with 0 errors)
-npm run test     # jest --coverage (all tests must pass)
-```
-
-All three commands must pass before committing. The CI pipeline (`reusable-npm-merge.yml`) runs the same checks.
-
-## Dependencies
-
-| Package                         | Role                                                                                       |
-| ------------------------------- | ------------------------------------------------------------------------------------------ |
-| `@devopsplaybook.io/otel-utils` | `StandardTracer`, `StandardLogger`, `StandardMeter`, `ModuleLogger`, `ConfigOTelInterface` |
-| `better-sqlite3`                | Synchronous SQLite driver (NOT the callback-based `sqlite3`)                               |
-| `pg`                            | PostgreSQL client with connection pooling                                                  |
-| `uuid`                          | v14+ (ESM -- requires `jest.mock("uuid")` in tests)                                        |
-| `fs-extra`                      | Async/sync file operations, `readJson`/`ensureDir`                                         |
-| `bcrypt`                        | Password hashing (users module)                                                            |
-| `jsonwebtoken`                  | JWT signing/verification (auth module)                                                     |
-| `fastify`                       | HTTP framework types used by `UsersRoutes`                                                 |
-
-## Known Gotchas
-
-- **uuid ESM**: `uuid` v14+ ships ESM. In any test that transitively imports `uuid`, add `jest.mock("uuid", () => ({ v4: () => "mock-uuid-1234" }))` to avoid `SyntaxError: Unexpected token 'export'`.
-- **better-sqlite3 is synchronous**: `SqlDbUtils` functions return values directly (not Promises). `PostgresDbUtils` functions return Promises. The `DbUtils` facade returns `number | Promise<number>` depending on the active backend.
-- **Disable-comment placement**: `eslint-disable-next-line` applies to the **immediately following line only** (oxlint honors these comments too). When disabling a rule inside a function call argument, place the comment directly before the offending expression, not before the function call.
-- **pg callback typing**: Always explicitly type pg callback parameters: `(error: Error | null, result: { rowCount: number | null })`. TypeScript cannot infer these from the overloaded `pool.query` signature.
-
-## Adopting in Other Projects
-
-See the [README](./README.md) for full adoption instructions. The typical pattern:
-
-1. Add `@devopsplaybook.io/common-utils` as a dependency.
-2. Replace the project's `OTelContext.ts` with `createOTelContext()`.
-3. Replace the project's `Config` class to `extend ConfigBase`.
-4. Replace DB utility files with re-exports from `common-utils`.
-5. Update `App.ts` to call `*SetOTel()` and `*Init()` from `common-utils`.

package/index.ts

@@ -1,18 +0,0 @@
-export * from "./src/OTelContext";
-export * from "./src/ConfigBase";
-export * from "./src/DbUtils";
-export * from "./src/DbUtilsNoTelemetry";
-export * from "./src/SqlDbUtils";
-export * from "./src/PostgresDbUtils";
-export * from "./src/Notifications";
-export * from "./src/LLM";
-export * from "./src/SystemCommand";
-export * from "./src/Timeout";
-export * from "./src/users/User";
-export * from "./src/users/UserSession";
-export * from "./src/users/UserApiToken";
-export * from "./src/users/Auth";
-export * from "./src/users/UserPassword";
-export * from "./src/users/UsersData";
-export * from "./src/users/UsersApiTokensData";
-export * from "./src/users/UsersRoutes";

package/jest.config.js

@@ -1,17 +0,0 @@
-module.exports = {
-  moduleFileExtensions: ["ts", "js"],
-  transform: {
-    "^.+\\.(ts|tsx)$": [
-      "@swc/jest",
-      {
-        jsc: {
-          target: "es2019",
-        },
-      },
-    ],
-  },
-  coverageProvider: "v8",
-  testMatch: ["/**/src/**/*.spec.(ts|js)"],
-  testPathIgnorePatterns: ["/node_modules/", "/dist/"],
-  testEnvironment: "node",
-};

package/prettierrc.json

@@ -1,5 +0,0 @@
-{
-  "tabWidth": 2,
-  "semi": true,
-  "singleQuote": false
-}

package/src/ConfigBase.spec.ts

@@ -1,108 +0,0 @@
-import * as fse from "fs-extra";
-import * as path from "path";
-import * as os from "os";
-
-jest.mock("uuid", () => ({
-  v4: () => "mock-uuid-1234",
-}));
-
-import { ConfigBase } from "./ConfigBase";
-
-/** Concrete subclass for testing. */
-class TestConfig extends ConfigBase {
-  public MY_SETTING = "default_value";
-  public SECRET_KEY = "secret_default";
-
-  constructor(configFile?: string) {
-    super("test-service", configFile);
-    this.addConfigField({ field: "MY_SETTING" });
-    this.addConfigField({ field: "SECRET_KEY", sensitive: true });
-  }
-}
-
-describe("ConfigBase", () => {
-  let tmpDir: string;
-  let configPath: string;
-
-  beforeEach(() => {
-    tmpDir = fse.mkdtempSync(path.join(os.tmpdir(), "config-test-"));
-    configPath = path.join(tmpDir, "config.json");
-  });
-
-  afterEach(() => {
-    fse.removeSync(tmpDir);
-    // Clean up env vars that tests may have set
-    delete process.env.MY_SETTING;
-    delete process.env.SECRET_KEY;
-    delete process.env.LOG_LEVEL;
-    delete process.env.DATA_DIR;
-  });
-
-  it("should initialise with default values", () => {
-    const config = new TestConfig(configPath);
-    expect(config.SERVICE_ID).toBe("test-service");
-    expect(config.MY_SETTING).toBe("default_value");
-    expect(config.SECRET_KEY).toBe("secret_default");
-    expect(config.LOG_LEVEL).toBe("info");
-    expect(config.DATABASE_TYPE).toBe("sqlite");
-  });
-
-  it("should load values from config.json", async () => {
-    fse.writeJsonSync(configPath, {
-      MY_SETTING: "from_file",
-      LOG_LEVEL: "debug",
-    });
-    const config = new TestConfig(configPath);
-    await config.reload();
-    expect(config.MY_SETTING).toBe("from_file");
-    expect(config.LOG_LEVEL).toBe("debug");
-  });
-
-  it("should prefer environment variables over config.json", async () => {
-    fse.writeJsonSync(configPath, {
-      MY_SETTING: "from_file",
-    });
-    process.env.MY_SETTING = "from_env";
-    const config = new TestConfig(configPath);
-    await config.reload();
-    expect(config.MY_SETTING).toBe("from_env");
-  });
-
-  it("should mask sensitive fields in log output", async () => {
-    const logs: string[] = [];
-    const config = new TestConfig(configPath);
-    await config.reload((msg) => logs.push(msg));
-    const secretLog = logs.find((l) => l.includes("SECRET_KEY"));
-    expect(secretLog).toContain("********************");
-    expect(secretLog).not.toContain("secret_default");
-  });
-
-  it("should not mask non-sensitive fields in log output", async () => {
-    const logs: string[] = [];
-    const config = new TestConfig(configPath);
-    await config.reload((msg) => logs.push(msg));
-    const settingLog = logs.find((l) => l.includes("MY_SETTING"));
-    expect(settingLog).toContain("default_value");
-  });
-
-  it("should survive missing config.json gracefully", async () => {
-    const config = new TestConfig("/nonexistent/path/config.json");
-    await config.reload();
-    // Should keep defaults
-    expect(config.MY_SETTING).toBe("default_value");
-  });
-
-  it("should register additional fields via addConfigField", async () => {
-    fse.writeJsonSync(configPath, { MY_SETTING: "updated" });
-    const config = new TestConfig(configPath);
-    await config.reload();
-    expect(config.MY_SETTING).toBe("updated");
-  });
-
-  it("should handle DATABASE_TYPE field", async () => {
-    fse.writeJsonSync(configPath, { DATABASE_TYPE: "postgres" });
-    const config = new TestConfig(configPath);
-    await config.reload();
-    expect(config.DATABASE_TYPE).toBe("postgres");
-  });
-});