@pulse-si/next 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Désiré Bally
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# @pulse-si/next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ton app Next.js surveillée par [Pulse](https://pulse-app.si), sur ton iPhone et ton Mac : signal de vie, base de données, Redis, files, routes de cron et journaux du serveur, depuis `instrumentation.ts`.
+
+```
+  ton serveur Next.js                                    ton iPhone, ton Mac
+ ┌────────────────────────────┐       HTTPS       ┌──────────┐       ┌──────────────┐
+ │ instrumentation.ts         │ ────────────────▶ │  Pulse   │ ────▶ │  app Pulse   │
+ │  └ startPulse({ watch })   │  état, crons,     │  (API)   │ push  │  alertes,    │
+ │     ├ Prisma    SELECT 1   │  journaux         │          │ ◀──── │  journaux,   │
+ │     ├ Redis     PING       │  (chiffrés si tu  │          │  SSE  │  en direct   │
+ │     └ crons     trackCron  │   le veux)        └──────────┘       └──────────────┘
+ └────────────────────────────┘
+```
+
+## En deux minutes
+
+À la racine du projet, avec la clé que l'app Pulse t'affiche :
+
+```bash
+npx @pulse-si/init pk_live_…
+```
+
+La commande installe `@pulse-si/next`, écrit la clé dans `.env.local` (lisible par toi seul, couvert par le `.gitignore`), crée `instrumentation.ts` au bon endroit (`src/` si ton projet l'utilise), puis te demande ce que tu veux envoyer. Relance ton serveur.
+
+### Ou à la main
+
+```ts
+// instrumentation.ts (ou src/instrumentation.ts)
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { startPulse } = await import('@pulse-si/next');
+    const { prisma } = await import('./lib/prisma');
+    startPulse({ watch: [prisma] });
+  }
+}
+```
+
+`watch` reçoit tes clients : Prisma, TypeORM, Mongoose, ioredis, node-redis, files BullMQ. Pulse les reconnaît à leur forme et les vérifie en lecture seule (`SELECT 1`, `PING`), 5 secondes au plus. Next.js 14 demande en plus `experimental.instrumentationHook: true` dans `next.config`.
+
+## Les routes de cron
+
+Une route appelée par Vercel Cron, un planificateur externe ou un `curl` sur le serveur remonte ses échecs :
+
+```ts
+import { trackCron } from '@pulse-si/next';
+
+export async function GET() {
+  await trackCron('relance-abonnements', () => relancer());
+  return Response.json({ ok: true });
+}
+```
+
+L'erreur est nettoyée, notée dans Pulse, puis relancée : ta route répond comme avant.
+
+## Où ça marche
+
+`@pulse-si/next` vit dans le processus Node de ton serveur. Il est fait pour `next start` sur un VPS, dans Docker ou chez un hébergeur qui garde le processus en vie. Sur une plateforme sans serveur (Vercel, Netlify), une instance peut dormir entre deux requêtes : surveille plutôt l'app par son URL dans Pulse, et garde `trackCron` pour tes routes de cron. Le runtime Edge est ignoré sans erreur.
+
+## Choisir ce qui part
+
+Le signal de vie part toujours. Le reste se règle par variables ou dans `startPulse` :
+
+```bash
+PULSE_SEND=checks,crons          # pas de journaux ni de versions
+PULSE_EXCLUDE=File emails        # ignorer une instance (* permis)
+PULSE_LOG_LEVEL=WARN             # journaux : avertissements et erreurs seulement
+```
+
+```ts
+startPulse({ watch: [prisma, redis], send: ['checks', 'logs'], logLevel: 'WARN' });
+```
+
+## Journaux et mode direct (Pro et Team)
+
+Pulse recopie ce que ton serveur écrit (`console`, pino, messages de Next.js) sans rien changer à ton terminal. Les niveaux sont reconnus (`⚠` et `⨯` de Next.js compris), les couleurs retirées, les secrets masqués avant de partir. Quand tu ouvres l'app dans Pulse, l'état part toutes les 5 secondes et les journaux chaque seconde. Gardés 3 jours en Pro, 7 jours en Team.
+
+## Mode sécurisé : Pulse ne peut rien lire
+
+Ton iPhone ou ton Mac fabrique une paire de clés ; la clé publique va dans `.env.local`, la clé privée reste dans ton trousseau.
+
+```bash
+PULSE_PUBLIC_KEY=pulse_pub_…
+PULSE_CLEAR=status        # par défaut : « ok » ou « N soucis », pour garder les alertes
+```
+
+Rapports et journaux partent chiffrés (HPKE, X25519 et AES-256-GCM) et Pulse ne garde qu'un paquet qu'il ne sait pas ouvrir. Avec `PULSE_CLEAR=none`, Pulse ne sait plus que si ton app est en vie.
+
+## Sécurité, en clair
+
+- Le package ne lève jamais d'erreur et ne bloque jamais une requête : tout se passe à côté, sur des minuteurs qui ne retiennent pas le processus.
+- Rien n'est écrit chez toi, rien de métier ne part : état, temps de réponse, messages d'erreur nettoyés.
+- La clé ne voyage qu'en HTTPS, dans un en-tête. Elle n'ouvre pas ton compte et se remplace depuis l'app.
+- En développement, Next.js recharge `instrumentation.ts` à chaque modification : un seul rapporteur tourne par processus.
+
+## Variables
+
+| Variable | Défaut | Rôle |
+|---|---|---|
+| `PULSE_KEY` | (obligatoire) | clé de l'app, `pk_live_…` ou `pk_test_…` |
+| `PULSE_SEND` | `checks,crons,logs,versions` | ce qui part en plus du signal de vie |
+| `PULSE_INCLUDE`, `PULSE_EXCLUDE` | (tout), (rien) | instances et tâches suivies, `*` permis |
+| `PULSE_LOG_LEVEL` | `DEBUG` | niveau minimal des journaux |
+| `PULSE_LOGS` | `true` | `false` coupe les journaux |
+| `PULSE_PUBLIC_KEY` | (aucune) | active le mode sécurisé |
+| `PULSE_CLEAR` | `status` | en mode sécurisé, ce qui reste lisible par Pulse |
+| `PULSE_ENDPOINT` | `https://api.pulse-app.si` | ton Pulse Relay en mode VPS perso (Team), par exemple `https://relais.kalao.ci` |
+| `PULSE_RELAY_FINGERPRINT` | (aucune) | empreinte du certificat d'un relais sans domaine : rien ne part si elle ne correspond pas |
+| `PULSE_APP_VERSION` | version du `package.json` | version affichée dans Pulse |
+| `PULSE_DISABLED` | `false` | `true` coupe tout |
+
+## Licence
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { httpProbe, type Probe } from '@pulse-si/core';
+export { pulse, startPulse, stopPulse, trackCron, type PulseNextOptions } from './start';

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackCron = exports.stopPulse = exports.startPulse = exports.pulse = exports.httpProbe = void 0;
+var core_1 = require("@pulse-si/core");
+Object.defineProperty(exports, "httpProbe", { enumerable: true, get: function () { return core_1.httpProbe; } });
+var start_1 = require("./start");
+Object.defineProperty(exports, "pulse", { enumerable: true, get: function () { return start_1.pulse; } });
+Object.defineProperty(exports, "startPulse", { enumerable: true, get: function () { return start_1.startPulse; } });
+Object.defineProperty(exports, "stopPulse", { enumerable: true, get: function () { return start_1.stopPulse; } });
+Object.defineProperty(exports, "trackCron", { enumerable: true, get: function () { return start_1.trackCron; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uCAAuD;AAA9C,iGAAA,SAAS,OAAA;AAClB,iCAAyF;AAAhF,8FAAA,KAAK,OAAA;AAAE,mGAAA,UAAU,OAAA;AAAE,kGAAA,SAAS,OAAA;AAAE,kGAAA,SAAS,OAAA"}

package/dist/start.d.ts

@@ -0,0 +1,9 @@
+import { PulseReporter, type Probe, type PulseOptions } from '@pulse-si/core';
+export type PulseNextOptions = PulseOptions & {
+    watch?: unknown[];
+    probes?: Probe[];
+};
+export declare function startPulse(options?: PulseNextOptions): PulseReporter | null;
+export declare function pulse(): PulseReporter | null;
+export declare function trackCron<T>(name: string, task: () => Promise<T>): Promise<T>;
+export declare function stopPulse(): void;

package/dist/start.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startPulse = startPulse;
+exports.pulse = pulse;
+exports.trackCron = trackCron;
+exports.stopPulse = stopPulse;
+const node_path_1 = require("node:path");
+const core_1 = require("@pulse-si/core");
+const GLOBAL_KEY = Symbol.for('pulse-next.reporter');
+function startPulse(options = {}) {
+    if (process.env.NEXT_RUNTIME && process.env.NEXT_RUNTIME !== 'nodejs')
+        return null;
+    const store = globalThis;
+    const existing = store[GLOBAL_KEY];
+    if (existing)
+        return existing;
+    const reporter = new core_1.PulseReporter({
+        packageName: 'pulse-next',
+        packageVersion: (0, core_1.ownVersion)((0, node_path_1.join)(__dirname, '..')),
+        framework: 'nextjs',
+        frameworkVersion: (0, core_1.installedVersion)('next'),
+    }, options);
+    if (!reporter.enabled)
+        return null;
+    for (const probe of [...(options.probes ?? []), ...(0, core_1.detectProbes)(options.watch ?? [])]) {
+        reporter.addProbe(probe);
+    }
+    reporter.start();
+    store[GLOBAL_KEY] = reporter;
+    return reporter;
+}
+function pulse() {
+    return globalThis[GLOBAL_KEY] ?? null;
+}
+async function trackCron(name, task) {
+    try {
+        const result = await task();
+        pulse()?.recordCronRun(name, true);
+        return result;
+    }
+    catch (error) {
+        pulse()?.recordCronRun(name, false, error);
+        throw error;
+    }
+}
+function stopPulse() {
+    const store = globalThis;
+    store[GLOBAL_KEY]?.stop();
+    delete store[GLOBAL_KEY];
+}
+//# sourceMappingURL=start.js.map

package/dist/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../src/start.ts"],"names":[],"mappings":";;AAoBA,gCAqBC;AAED,sBAEC;AAGD,8BASC;AAED,8BAIC;AA/DD,yCAAiC;AACjC,yCAOwB;AAOxB,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;AAKrD,SAAgB,UAAU,CAAC,UAA4B,EAAE;IACvD,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACnF,MAAM,KAAK,GAAG,UAAyB,CAAC;IACxC,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;IACnC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,QAAQ,GAAG,IAAI,oBAAa,CAChC;QACE,WAAW,EAAE,YAAY;QACzB,cAAc,EAAE,IAAA,iBAAU,EAAC,IAAA,gBAAI,EAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACjD,SAAS,EAAE,QAAQ;QACnB,gBAAgB,EAAE,IAAA,uBAAgB,EAAC,MAAM,CAAC;KAC3C,EACD,OAAO,CACR,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,GAAG,IAAA,mBAAY,EAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QACtF,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,QAAQ,CAAC,KAAK,EAAE,CAAC;IACjB,KAAK,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC;IAC7B,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAgB,KAAK;IACnB,OAAQ,UAA0B,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC;AACzD,CAAC;AAGM,KAAK,UAAU,SAAS,CAAI,IAAY,EAAE,IAAsB;IACrE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;QAC5B,KAAK,EAAE,EAAE,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACnC,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,KAAK,EAAE,EAAE,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC3C,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAgB,SAAS;IACvB,MAAM,KAAK,GAAG,UAAyB,CAAC;IACxC,KAAK,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,CAAC;IAC1B,OAAO,KAAK,CAAC,UAAU,CAAC,CAAC;AAC3B,CAAC"}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@pulse-si/next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Surveillance Pulse pour Next.js : signal de vie et dépendances depuis instrumentation.ts.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "homepage": "https://pulse-app.si",
+  "jest": {
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.ts$": "ts-jest"
+    },
+    "testEnvironment": "node"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.20.5",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.13.0",
+    "jest": "^30.5.2",
+    "ts-jest": "^29.4.15",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.71.2"
+  },
+  "dependencies": {
+    "@pulse-si/core": "^0.0.1"
+  },
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "jest"
+  }
 }