Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

nodejs-service-foundations

/nodejs-service-foundations

Ustawia lub utwardza fundamenty usługi Node.js: walidację env, logowanie, typowane błędy, type stripping i obsługę zamykania.

Licencja
Apache-2.0
Ostatnia zmiana repozytorium
28.09.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 28.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Ustawia lub utwardza fundamenty usługi Node.js: walidację env, logowanie, typowane błędy, type stripping i obsługę zamykania.

Oryginalny opis (EN)

Use when asked to set up or harden Node.js service foundations: env validation, logging, typed errors, type stripping, and shutdown wiring. Not for dedicated shutdown: use nodejs-graceful-shutdown.

Jak działa

  1. Contract
  2. Inputs
  3. Procedure
  4. Failure and recovery
  5. Output
Sekcje z nagłówków SKILL.md, w oryginale · 47 linii, 916 słów
Podgląd SKILL.md
---
name: nodejs-service-foundations
description: 'Use when asked to set up or harden Node.js service foundations: env validation, logging, typed errors, type stripping, and shutdown wiring. Not for dedicated shutdown: use nodejs-graceful-shutdown.'
---

# Node.js service foundations

## Contract

| Field | Bound contract |
|---|---|
| Trigger | Setting up or hardening Node.js service foundations: env or secrets configuration, structured logging with redaction, typed error taxonomy, module system, native TypeScript type stripping. |
| Authority | Reversible local: writes only named local artifacts (env schema, logger, error classes, tsconfig, package scripts) and may install the dependencies they need; rollback is version control. No remote mutation. |
| Side effect | Writes service scaffolding files and installs declared dependencies. |
| Done | The service validates startup env (invalid config fails fast), emits structured logs with secret redaction, throws typed coded errors with working instanceof checks and HTTP status mapping, and runs under type stripping or tsc with no errors. |

## Inputs

- Project root (required): the directory containing or to receive `package.json`.
- Environment variables (required): list of env variable names and types, and whether each is required or optional with a default.
- Secret field names (required): list of env keys whose values must be redacted in log output.
- Error catalogue (required): list of `{ code, message, httpStatus }` tuples for the service's domain errors.
- Logger dependency (required): the structured logger the service uses or will use (e.g., pino). Stated as an input, not discovered mid-procedure.

## Procedure

1. **Validate environment at startup.** Create an env schema module (e.g., `src/env.ts`) that reads `process.env` at import time. For each declared variable: parse the value against its type (string, number, boolean, URL); if required and missing or malformed, throw a descriptive error and exit with code 1 before any server binding. Export the frozen validated config object. Do not allow the service to start with invalid or missing configuration. Done when: the env schema module validates all declared variables and fails fast on invalid config.

2. **Configure structured logging with redaction.** Create a logger module (e.g., `src/logger.ts`) using the stated logger dependency. Configure the log level from env, ISO-8601 timestamps, and a request-id correlation field. Implement a redaction serializer that replaces values of every secret field name with `[REDACTED]` at every log level. Export a singleton logger instance. Done when: the logger module emits structured JSON with secret redaction at every log level.

3. **Define a typed-error catalogue with instanceof and HTTP mapping.** Create an error module (e.g., `src/errors.ts`) exporting a base `ServiceError` class with fields `code: string`, `message: string`, `httpStatus: number`, and `cause?: Error`. For each entry in the error catalogue, export a named subclass or factory. Ensure `instanceof ServiceError` works for error-handling middleware to map codes to HTTP responses. Done when: the error module exports `ServiceError` base and all catalogue entries, `instanceof ServiceError` returns true for every subclass instance, and every catalogue code maps to its declared HTTP status.

4. **Wire AbortController signal, drain, and exit.** In the service entry point, create an `AbortController`. Listen for `SIGTERM` and `SIGINT`: call `controller.abort()`, pass the signal to in-flight operations, drain active requests, then exit with code 0 on clean drain or non-zero on timeout. This wires the shutdown spine without implementing the full shutdown handler (that is the job of `nodejs-graceful-shutdown` when a dedicated implementation is needed). Done when: the entry point creates an AbortController, wires both signals to `controller.abort()`, and exits after drain.

5. **Verify startup logs, one invalid-env case, and tsc.** Run the service with valid env and confirm: server binds, startup log emits as structured JSON with secrets redacted. Run with a missing required env var and confirm: process exits with code 1 and a descriptive error before any server binding. Run `tsc --noEmit` and confirm: zero type errors. Verify the typed-error catalogue: instantiate one subclass, confirm `instanceof ServiceError` returns true, and confirm its `httpStatus` matches the catalogue entry. Verify redaction: log a record containing a secret field name and confirm the output shows `[REDACTED]`. Done when: valid-env startup emits structured redacted JSON, invalid-env exits code 1 before binding, `tsc --noEmit` reports zero errors, the instanceof check passes, the HTTP mapping is correct, and the redaction test passes.

## Failure and recovery

| Failure class | Detection | Recovery |
|---|---|---|
| Missing dependency | The stated logger or a required package is not installed | Install it using the project's package manager. If installation fails, stop and report the missing dependency. |
| Invalid or missing env var | Env schema validation throws at import time | Process exits code 1 with descriptive message listing the missing or invalid vars. Do not start the server. |
| Unredacted log | Secret value appears unredacted in log output | Halt: the redaction serializer is misconfigured. Fix the field-name list before proceeding. |
| Unmapped error | A catalogue entry has no matching subclass or HTTP status | Add the missing subclass or factory. Every catalogue entry must have a working instanceof check and HTTP mapping. |
| Type error on tsc --noEmit | Compiler emits diagnostics | Fix the type errors. Do not suppress with `@ts-ignore` or `any`. |
| Partial write on rollback | Some files written, others not | Use the recorded rollback path: `git checkout -- <written files>` or delete the listed untracked files. |

## Output

Local named files: `src/env.ts` (validated env schema), `src/logger.ts` (structured JSON logger with redaction), `src/errors.ts` (typed `ServiceError` base and subclasses with instanceof and HTTP mapping), `tsconfig.json` (strict type-stripping config), `package.json` (ESM, engines, scripts). All reversible via the stated rollback path. The Done proof covers startup logs, invalid-env failure, tsc, instanceof, HTTP mapping, and redaction.
Pliki w paczce (2)
  • SKILL.md 6 KB
  • agents/openai.yaml 1 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · OutlineDriven/outline-driven-development90Apache-2.0
gosuda/dalcom-skills100Apache-2.0

Migawka bazy z 13.11.2026 · wersja paczki 9a4dd67926f3 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100nodejs-graceful-shutdown
    Wdraża lub naprawia łagodne zamykanie usługi Node.js: sygnały SIGTERM i SIGINT, dokańczanie połączeń i sygnał health-check.
  • 100nodejs-graceful-shutdown
    Wdraża lub naprawia zamykanie usługi Node.js: obsługa SIGTERM i SIGINT, opróżnianie połączeń i sygnalizowanie w health checku.
  • 91nodejs-development
    Buduje, debuguje i optymalizuje aplikacje Node.js: serwery Fastify, TypeScript, OAuth 2.1 i diagnozę wydajności.
  • 100nodejs-best-practices
    Pomaga podejmować decyzje dla usług Node.js: framework, warstwy, błędy, asynchroniczność, walidację i bezpieczeństwo.
  • 90node-backend-setup
    Zakłada backend Node.js z ESM, typowaną konfiguracją, łagodnym zamykaniem i ustrukturyzowanym logowaniem od początku, także przy utwardzaniu usługi rozrosłej bez fundamentów.
  • 100node
    Dostarcza dobre praktyki Node.js z TypeScript: usuwanie typów, wzorce async, obsługa błędów, strumienie, moduły, testy, wydajność, cache i logowanie, także dla Node 22+ bez kroku budowania.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.