@limetry/preflight 0.0.0-stage → 1.2.57

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/README.md +128 -2
  2. package/dist/checks.d.ts +46 -0
  3. package/dist/checks.d.ts.map +1 -0
  4. package/dist/checks.js +61 -0
  5. package/dist/checks.js.map +1 -0
  6. package/dist/dotenv-files.d.ts +23 -0
  7. package/dist/dotenv-files.d.ts.map +1 -0
  8. package/dist/dotenv-files.js +57 -0
  9. package/dist/dotenv-files.js.map +1 -0
  10. package/dist/env-runtime.d.ts +43 -0
  11. package/dist/env-runtime.d.ts.map +1 -0
  12. package/dist/env-runtime.js +60 -0
  13. package/dist/env-runtime.js.map +1 -0
  14. package/dist/format.d.ts +40 -0
  15. package/dist/format.d.ts.map +1 -0
  16. package/dist/format.js +94 -0
  17. package/dist/format.js.map +1 -0
  18. package/dist/index.d.ts +34 -0
  19. package/dist/index.d.ts.map +1 -0
  20. package/dist/index.js +34 -0
  21. package/dist/index.js.map +1 -0
  22. package/dist/listen-urls.d.ts +37 -0
  23. package/dist/listen-urls.d.ts.map +1 -0
  24. package/dist/listen-urls.js +91 -0
  25. package/dist/listen-urls.js.map +1 -0
  26. package/dist/logger.d.ts +14 -0
  27. package/dist/logger.d.ts.map +1 -0
  28. package/dist/logger.js +64 -0
  29. package/dist/logger.js.map +1 -0
  30. package/dist/mask.d.ts +26 -0
  31. package/dist/mask.d.ts.map +1 -0
  32. package/dist/mask.js +55 -0
  33. package/dist/mask.js.map +1 -0
  34. package/dist/ports.d.ts +58 -0
  35. package/dist/ports.d.ts.map +1 -0
  36. package/dist/ports.js +134 -0
  37. package/dist/ports.js.map +1 -0
  38. package/dist/probes/http.d.ts +61 -0
  39. package/dist/probes/http.d.ts.map +1 -0
  40. package/dist/probes/http.js +106 -0
  41. package/dist/probes/http.js.map +1 -0
  42. package/dist/probes/postgres.d.ts +27 -0
  43. package/dist/probes/postgres.d.ts.map +1 -0
  44. package/dist/probes/postgres.js +64 -0
  45. package/dist/probes/postgres.js.map +1 -0
  46. package/dist/probes/posthog.d.ts +37 -0
  47. package/dist/probes/posthog.d.ts.map +1 -0
  48. package/dist/probes/posthog.js +79 -0
  49. package/dist/probes/posthog.js.map +1 -0
  50. package/dist/probes/redis.d.ts +25 -0
  51. package/dist/probes/redis.d.ts.map +1 -0
  52. package/dist/probes/redis.js +65 -0
  53. package/dist/probes/redis.js.map +1 -0
  54. package/dist/probes/sentry.d.ts +56 -0
  55. package/dist/probes/sentry.d.ts.map +1 -0
  56. package/dist/probes/sentry.js +130 -0
  57. package/dist/probes/sentry.js.map +1 -0
  58. package/dist/probes/telemetry.d.ts +30 -0
  59. package/dist/probes/telemetry.d.ts.map +1 -0
  60. package/dist/probes/telemetry.js +77 -0
  61. package/dist/probes/telemetry.js.map +1 -0
  62. package/dist/run.d.ts +70 -0
  63. package/dist/run.d.ts.map +1 -0
  64. package/dist/run.js +82 -0
  65. package/dist/run.js.map +1 -0
  66. package/dist/types.d.ts +90 -0
  67. package/dist/types.d.ts.map +1 -0
  68. package/dist/types.js +16 -0
  69. package/dist/types.js.map +1 -0
  70. package/package.json +74 -4
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Collects optional Sentry/PostHog env checks and probes from an injected env bag.
3
+ */
4
+ import type { ConnectivityProbe, PreflightCheck } from "../types.js";
5
+ /**
6
+ * Env checks, context lines, and probes for optional observability backends.
7
+ */
8
+ export type TelemetryBundle = {
9
+ /**
10
+ * Non-pass/fail context lines (e.g. annotated PostHog host).
11
+ */
12
+ configuration: string[];
13
+ /**
14
+ * Optional secret/env checks for configured backends.
15
+ */
16
+ envChecks: PreflightCheck[];
17
+ /**
18
+ * Optional connectivity probes; never critical for startup.
19
+ */
20
+ probes: ConnectivityProbe[];
21
+ };
22
+ /**
23
+ * Adds Sentry/PostHog env display and optional connectivity when those keys are set
24
+ * on `source`. Observability never blocks startup.
25
+ *
26
+ * @param source - Injected env bag; do not rely on ambient `process.env` inside callers.
27
+ * @returns Bundle of env checks, context lines, and probes to merge into `runPreflight`.
28
+ */
29
+ export declare function collectConfiguredTelemetry(source?: NodeJS.ProcessEnv): TelemetryBundle;
30
+ //# sourceMappingURL=telemetry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/probes/telemetry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AA8BpE;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;OAEG;IACH,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB;;OAEG;IACH,SAAS,EAAE,cAAc,EAAE,CAAA;IAC3B;;OAEG;IACH,MAAM,EAAE,iBAAiB,EAAE,CAAA;CAC5B,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,GAAE,MAAM,CAAC,UAAwB,GACtC,eAAe,CAwCjB"}
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Collects optional Sentry/PostHog env checks and probes from an injected env bag.
3
+ */
4
+ import { envCheck } from "../checks.js";
5
+ import { annotated } from "../dotenv-files.js";
6
+ import { createPosthogProbe } from "./posthog.js";
7
+ import { createSentryProbe, parseSentryDsn } from "./sentry.js";
8
+ /**
9
+ * First non-empty value among `keys` on the injected env bag.
10
+ *
11
+ * @param source - Injected env bag.
12
+ * @param keys - Candidate env key names in priority order.
13
+ * @returns Trimmed first non-empty value, or `undefined`.
14
+ */
15
+ function firstEnv(source, keys) {
16
+ for (const key of keys) {
17
+ const raw = source[key];
18
+ if (raw && raw.trim().length > 0) {
19
+ return raw.trim();
20
+ }
21
+ }
22
+ return undefined;
23
+ }
24
+ const SENTRY_KEYS = ["SENTRY_DSN", "NEXT_PUBLIC_SENTRY_DSN"];
25
+ const POSTHOG_KEY_KEYS = [
26
+ "POSTHOG_KEY",
27
+ "POSTHOG_API_KEY",
28
+ "NEXT_PUBLIC_POSTHOG_KEY",
29
+ "NEXT_PUBLIC_POSTHOG_PROJECT_API_KEY",
30
+ ];
31
+ const POSTHOG_HOST_KEYS = ["POSTHOG_HOST", "NEXT_PUBLIC_POSTHOG_HOST", "POSTHOG_API_HOST"];
32
+ /**
33
+ * Adds Sentry/PostHog env display and optional connectivity when those keys are set
34
+ * on `source`. Observability never blocks startup.
35
+ *
36
+ * @param source - Injected env bag; do not rely on ambient `process.env` inside callers.
37
+ * @returns Bundle of env checks, context lines, and probes to merge into `runPreflight`.
38
+ */
39
+ export function collectConfiguredTelemetry(source = process.env) {
40
+ const envChecks = [];
41
+ const configuration = [];
42
+ const probes = [];
43
+ const sentryDsn = firstEnv(source, SENTRY_KEYS);
44
+ if (sentryDsn) {
45
+ const parsed = parseSentryDsn(sentryDsn);
46
+ envChecks.push(envCheck({
47
+ name: "SENTRY_DSN",
48
+ value: sentryDsn,
49
+ secret: true,
50
+ ok: Boolean(parsed),
51
+ required: false,
52
+ critical: false,
53
+ }));
54
+ const sentryProbe = createSentryProbe({ dsn: sentryDsn, required: false });
55
+ if (sentryProbe) {
56
+ probes.push(sentryProbe);
57
+ }
58
+ }
59
+ const posthogKey = firstEnv(source, POSTHOG_KEY_KEYS);
60
+ if (posthogKey) {
61
+ envChecks.push(envCheck({
62
+ name: "POSTHOG_KEY",
63
+ value: posthogKey,
64
+ secret: true,
65
+ ok: true,
66
+ required: false,
67
+ critical: false,
68
+ }));
69
+ const host = firstEnv(source, POSTHOG_HOST_KEYS);
70
+ if (host) {
71
+ configuration.push(`POSTHOG_HOST: ${annotated("POSTHOG_HOST", host, source)}`);
72
+ }
73
+ probes.push(createPosthogProbe({ apiKey: posthogKey, host, required: false }));
74
+ }
75
+ return { envChecks, configuration, probes };
76
+ }
77
+ //# sourceMappingURL=telemetry.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/probes/telemetry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE/D;;;;;;GAMG;AACH,SAAS,QAAQ,CAAC,MAAyB,EAAE,IAAc;IACzD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;QACvB,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjC,OAAO,GAAG,CAAC,IAAI,EAAE,CAAA;QACnB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,MAAM,WAAW,GAAG,CAAC,YAAY,EAAE,wBAAwB,CAAC,CAAA;AAC5D,MAAM,gBAAgB,GAAG;IACvB,aAAa;IACb,iBAAiB;IACjB,yBAAyB;IACzB,qCAAqC;CACtC,CAAA;AACD,MAAM,iBAAiB,GAAG,CAAC,cAAc,EAAE,0BAA0B,EAAE,kBAAkB,CAAC,CAAA;AAoB1F;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,SAA4B,OAAO,CAAC,GAAG;IAEvC,MAAM,SAAS,GAAqB,EAAE,CAAA;IACtC,MAAM,aAAa,GAAa,EAAE,CAAA;IAClC,MAAM,MAAM,GAAwB,EAAE,CAAA;IAEtC,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;IAC/C,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,CAAA;QACxC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC;YACtB,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,SAAS;YAChB,MAAM,EAAE,IAAI;YACZ,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,KAAK;YACf,QAAQ,EAAE,KAAK;SAChB,CAAC,CAAC,CAAA;QACH,MAAM,WAAW,GAAG,iBAAiB,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAA;QAC1E,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;QAC1B,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IACrD,IAAI,UAAU,EAAE,CAAC;QACf,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC;YACtB,IAAI,EAAE,aAAa;YACnB,KAAK,EAAE,UAAU;YACjB,MAAM,EAAE,IAAI;YACZ,EAAE,EAAE,IAAI;YACR,QAAQ,EAAE,KAAK;YACf,QAAQ,EAAE,KAAK;SAChB,CAAC,CAAC,CAAA;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;QAChD,IAAI,IAAI,EAAE,CAAC;YACT,aAAa,CAAC,IAAI,CAAC,iBAAiB,SAAS,CAAC,cAAc,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAA;QAChF,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAA;IAChF,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,CAAA;AAC7C,CAAC"}
package/dist/run.d.ts ADDED
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Orchestrates env checks, connectivity probes, banner logging, and fail-hard policy.
3
+ */
4
+ import type { Logger } from "pino";
5
+ import { connectivityIcon } from "./checks.js";
6
+ import { type ConnectivityProbe, type PreflightCheck } from "./types.js";
7
+ /**
8
+ * Options for {@link runPreflight}.
9
+ *
10
+ * Pass product-validated checks via `envChecks` (built from a typed env object
11
+ * at the adapter). Use `env` / `source` only as the injected ProcessEnv bag for
12
+ * dotenv listing, fail-hard policy, and logger — not as a substitute for Zod.
13
+ */
14
+ export type RunPreflightOptions = {
15
+ /**
16
+ * Optional app version string rendered in the banner when provided.
17
+ */
18
+ appVersion?: string;
19
+ /**
20
+ * Extra context lines (NODE_ENV, ports, derived DB host) shown under Context.
21
+ * Prefer putting pass/fail settings in `envChecks`.
22
+ */
23
+ configuration?: string[];
24
+ /**
25
+ * Injected env bag merged over `process.env` for runtime flags and dotenv listing.
26
+ * Prefer passing the same bag your adapter already used for Zod parse.
27
+ */
28
+ env?: NodeJS.ProcessEnv;
29
+ /**
30
+ * Product-built env/secret checks included in the banner and fail-hard evaluation.
31
+ */
32
+ envChecks?: PreflightCheck[];
33
+ /**
34
+ * Override fail-hard policy. Defaults to {@link shouldFailHard} for the env bag.
35
+ */
36
+ failHard?: boolean;
37
+ /**
38
+ * Listen URL expanded into banner “ready” lines via {@link expandListenUrls}.
39
+ */
40
+ listenUrl?: string;
41
+ /**
42
+ * Optional Pino logger; defaults to {@link createPreflightLogger} for `product`.
43
+ */
44
+ logger?: Logger;
45
+ /**
46
+ * Connectivity probes run when probing is enabled for the env bag.
47
+ */
48
+ probes?: ConnectivityProbe[];
49
+ /**
50
+ * Product display name used in the banner title and logger name.
51
+ */
52
+ product: string;
53
+ /**
54
+ * When true, skips all probes. Defaults to the inverse of {@link shouldProbeConnectivity}.
55
+ */
56
+ skipConnectivity?: boolean;
57
+ };
58
+ /**
59
+ * Runs env checks + optional connectivity probes, prints the banner, and throws
60
+ * when blocking required checks fail under `failHard`.
61
+ *
62
+ * Side effects: writes structured preflight logs (banner + `preflight.complete`).
63
+ *
64
+ * @param options - Product name, checks, probes, and runtime policy overrides.
65
+ * @returns All env and connectivity {@link PreflightCheck} rows evaluated.
66
+ * @throws Error When one or more blocking required checks fail and `failHard` is true.
67
+ */
68
+ export declare function runPreflight(options: RunPreflightOptions): Promise<PreflightCheck[]>;
69
+ export { connectivityIcon };
70
+ //# sourceMappingURL=run.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAM9C,OAAO,EAAsB,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAA;AAE5F;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB;;OAEG;IACH,SAAS,CAAC,EAAE,cAAc,EAAE,CAAA;IAC5B;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAmE1F;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAA"}
package/dist/run.js ADDED
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Orchestrates env checks, connectivity probes, banner logging, and fail-hard policy.
3
+ */
4
+ import { connectivityIcon } from "./checks.js";
5
+ import { listEffectiveDotenvFiles } from "./dotenv-files.js";
6
+ import { shouldFailHard, shouldProbeConnectivity } from "./env-runtime.js";
7
+ import { formatPreflightReport } from "./format.js";
8
+ import { expandListenUrls } from "./listen-urls.js";
9
+ import { createPreflightLogger } from "./logger.js";
10
+ import { checkBlocksStartup } from "./types.js";
11
+ /**
12
+ * Runs env checks + optional connectivity probes, prints the banner, and throws
13
+ * when blocking required checks fail under `failHard`.
14
+ *
15
+ * Side effects: writes structured preflight logs (banner + `preflight.complete`).
16
+ *
17
+ * @param options - Product name, checks, probes, and runtime policy overrides.
18
+ * @returns All env and connectivity {@link PreflightCheck} rows evaluated.
19
+ * @throws Error When one or more blocking required checks fail and `failHard` is true.
20
+ */
21
+ export async function runPreflight(options) {
22
+ const source = { ...process.env, ...(options.env ?? {}) };
23
+ const logger = options.logger ?? createPreflightLogger(options.product, source);
24
+ const envChecks = [...(options.envChecks ?? [])];
25
+ const skipConnectivity = options.skipConnectivity ?? !shouldProbeConnectivity(source);
26
+ const connectivity = [];
27
+ if (!skipConnectivity) {
28
+ for (const probe of options.probes ?? []) {
29
+ const result = await probe.run();
30
+ connectivity.push({
31
+ name: probe.name,
32
+ ok: result.ok,
33
+ required: probe.required,
34
+ critical: probe.critical,
35
+ detail: result.detail,
36
+ kind: "connectivity",
37
+ });
38
+ }
39
+ }
40
+ const checks = [...envChecks, ...connectivity];
41
+ const failedBlocking = checks.filter((check) => checkBlocksStartup(check));
42
+ const failedRequired = checks.filter((check) => check.required && !check.ok);
43
+ const failedOptional = checks.filter((check) => !check.required && !check.ok);
44
+ const passed = failedBlocking.length === 0;
45
+ const warnings = failedOptional.length > 0 || failedRequired.some((check) => check.critical === false);
46
+ const listenUrls = options.listenUrl ? expandListenUrls(options.listenUrl) : [];
47
+ const report = formatPreflightReport({
48
+ product: options.product,
49
+ appVersion: options.appVersion,
50
+ envFiles: listEffectiveDotenvFiles(source),
51
+ envChecks,
52
+ contextLines: options.configuration,
53
+ connectivityChecks: connectivity,
54
+ passed,
55
+ warnings,
56
+ listenUrls,
57
+ });
58
+ logger.info({
59
+ preflightBanner: true,
60
+ passed,
61
+ warnings,
62
+ listenUrls,
63
+ appVersion: options.appVersion,
64
+ }, report);
65
+ logger.info({
66
+ event: "preflight.complete",
67
+ passed,
68
+ warnings,
69
+ listenUrls,
70
+ appVersion: options.appVersion,
71
+ failedBlocking: failedBlocking.map((check) => check.name),
72
+ failedRequired: failedRequired.map((check) => check.name),
73
+ failedOptional: failedOptional.map((check) => check.name),
74
+ }, "preflight.complete");
75
+ const failHard = options.failHard ?? shouldFailHard(source);
76
+ if (!passed && failHard) {
77
+ throw new Error(`Preflight failed: ${failedBlocking.map((check) => `${check.name} (${check.detail})`).join("; ")}`);
78
+ }
79
+ return checks;
80
+ }
81
+ export { connectivityIcon };
82
+ //# sourceMappingURL=run.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,90 @@
1
+ /**
2
+ * Shared preflight check and probe contracts used by `runPreflight` and adapters.
3
+ */
4
+ /**
5
+ * Discriminator for banner rows: environment variable, secret, or live probe.
6
+ */
7
+ export type PreflightCheckKind = "env" | "secret" | "connectivity";
8
+ /**
9
+ * One row in the preflight banner (env, secret, or connectivity).
10
+ *
11
+ * Severity:
12
+ * - optional (`required: false`): warn only
13
+ * - required: must be healthy for full features; does not abort unless critical
14
+ * - critical: abort startup when `failHard` (defaults to true when `required` is true)
15
+ */
16
+ export type PreflightCheck = {
17
+ /**
18
+ * When `required` is true, defaults to `true` (hard-fail). Set `false` for
19
+ * degraded-but-bootable dependencies (billing, secondary upstreams, etc.).
20
+ */
21
+ critical?: boolean;
22
+ /**
23
+ * Human-readable status text shown after the check name in the banner.
24
+ */
25
+ detail: string;
26
+ /**
27
+ * Row kind for formatting; connectivity probes set this to `"connectivity"`.
28
+ */
29
+ kind?: PreflightCheckKind;
30
+ /**
31
+ * Stable identifier for logging and failure summaries.
32
+ */
33
+ name: string;
34
+ /**
35
+ * Whether the check or probe succeeded.
36
+ */
37
+ ok: boolean;
38
+ /**
39
+ * When false, failures are warnings only and never block startup.
40
+ */
41
+ required: boolean;
42
+ };
43
+ /**
44
+ * Async connectivity check invoked by {@link runPreflight} when probing is enabled.
45
+ */
46
+ export type ConnectivityProbe = {
47
+ /**
48
+ * When `required` is true, defaults to hard-fail. Set `false` to allow boot
49
+ * with a degraded dependency.
50
+ */
51
+ critical?: boolean;
52
+ /**
53
+ * Stable probe name used in the resulting {@link PreflightCheck}.
54
+ */
55
+ name: string;
56
+ /**
57
+ * Whether a failed probe can block startup under `failHard`.
58
+ */
59
+ required: boolean;
60
+ /**
61
+ * Executes the probe and returns a pass/fail detail string.
62
+ *
63
+ * @returns Probe outcome used to build a connectivity {@link PreflightCheck}.
64
+ */
65
+ run: () => Promise<{
66
+ detail: string;
67
+ ok: boolean;
68
+ }>;
69
+ };
70
+ /**
71
+ * Result of a single probe attempt.
72
+ */
73
+ export type ProbeResult = {
74
+ /**
75
+ * Human-readable outcome including elapsed time and error context when failed.
76
+ */
77
+ detail: string;
78
+ /**
79
+ * Whether the probe succeeded.
80
+ */
81
+ ok: boolean;
82
+ };
83
+ /**
84
+ * Whether a failed check should abort the process under `failHard`.
85
+ *
86
+ * @param check - Subset of a {@link PreflightCheck} used for severity decisions.
87
+ * @returns `true` when the check is required, not ok, and not explicitly non-critical.
88
+ */
89
+ export declare function checkBlocksStartup(check: Pick<PreflightCheck, "critical" | "ok" | "required">): boolean;
90
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,QAAQ,GAAG,cAAc,CAAA;AAElE;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAA;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,EAAE,EAAE,OAAO,CAAA;IACX;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;OAIG;IACH,GAAG,EAAE,MAAM,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CACpD,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,EAAE,EAAE,OAAO,CAAA;CACZ,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,IAAI,GAAG,UAAU,CAAC,GAAG,OAAO,CAKvG"}
package/dist/types.js ADDED
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Shared preflight check and probe contracts used by `runPreflight` and adapters.
3
+ */
4
+ /**
5
+ * Whether a failed check should abort the process under `failHard`.
6
+ *
7
+ * @param check - Subset of a {@link PreflightCheck} used for severity decisions.
8
+ * @returns `true` when the check is required, not ok, and not explicitly non-critical.
9
+ */
10
+ export function checkBlocksStartup(check) {
11
+ if (check.ok || !check.required) {
12
+ return false;
13
+ }
14
+ return check.critical !== false;
15
+ }
16
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkFH;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAA2D;IAC5F,IAAI,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QAChC,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAA;AACjC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,76 @@
1
1
  {
2
2
  "name": "@limetry/preflight",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.2.57",
4
+ "description": "Startup preflight checks with secret masking, connectivity probes, and formatted listen URLs",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "import": "./dist/index.js",
13
+ "default": "./dist/index.js"
14
+ }
15
+ },
16
+ "files": [
17
+ "dist",
18
+ "README.md"
19
+ ],
20
+ "sideEffects": false,
21
+ "publishConfig": {
22
+ "access": "public",
23
+ "registry": "https://registry.npmjs.org"
24
+ },
25
+ "repository": {
26
+ "type": "git",
27
+ "url": "git+https://github.com/limetry/limetry.git",
28
+ "directory": "packages/preflight"
29
+ },
30
+ "keywords": [
31
+ "preflight",
32
+ "startup",
33
+ "health-check",
34
+ "pino",
35
+ "postgres",
36
+ "redis",
37
+ "sentry",
38
+ "posthog",
39
+ "dotenv"
40
+ ],
41
+ "scripts": {
42
+ "build": "rm -rf dist && tsc -p tsconfig.json",
43
+ "prepack": "node ../../scripts/rewrite-workspace-protocol.mjs prepare",
44
+ "postpack": "node ../../scripts/rewrite-workspace-protocol.mjs restore-after-pack",
45
+ "postpublish": "node ../../scripts/rewrite-workspace-protocol.mjs restore",
46
+ "test": "vitest run --coverage",
47
+ "typecheck": "yarn run -T tsgo -p tsconfig.json --noEmit"
48
+ },
49
+ "dependencies": {
50
+ "pino": "^10.3.1"
51
+ },
52
+ "peerDependencies": {
53
+ "ioredis": "^5.0.0",
54
+ "pg": "^8.0.0"
55
+ },
56
+ "peerDependenciesMeta": {
57
+ "ioredis": {
58
+ "optional": true
59
+ },
60
+ "pg": {
61
+ "optional": true
62
+ }
63
+ },
64
+ "devDependencies": {
65
+ "@types/node": "^26.1.2",
66
+ "@types/pg": "^8.20.0",
67
+ "@vitest/coverage-v8": "4.1.11",
68
+ "ioredis": "^5.11.1",
69
+ "pg": "^8.22.0",
70
+ "typescript": "^5.8.2",
71
+ "vitest": "4.1.11"
72
+ },
73
+ "engines": {
74
+ "node": ">=20"
75
+ }
76
+ }