@revenexx/integrations-node-devkit 0.8.0 → 0.8.1

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.
package/dist/env.d.ts ADDED
@@ -0,0 +1,70 @@
1
+ /**
2
+ * `.env` loading for the CLI.
3
+ *
4
+ * Seeds reference secrets as `${VAR}` and {@link interpolateEnv} resolves those
5
+ * from `process.env`, so without this the documented workflow — commit the
6
+ * reference, keep the value in `.env` — only worked if the developer exported
7
+ * the variables by hand.
8
+ *
9
+ * Loading happens before option parsing, because the CLI reads `PORT` for its
10
+ * default port; a `.env` that sets `PORT` would otherwise be read too late.
11
+ *
12
+ * Exactly one file is ever loaded: `.env` by default, or the one named by
13
+ * `--env`, which *replaces* the default rather than layering on top of it.
14
+ * "Use this env file" is what the flag reads like, so leaving `.env` in play
15
+ * would be the surprise. `--no-env` loads none.
16
+ *
17
+ * `process.loadEnvFile` deliberately does not overwrite variables that are
18
+ * already set, so a shell-provided value always beats the file:
19
+ *
20
+ * REVENEXX_DEV_API_KEY=… npm run preview
21
+ *
22
+ * The flag is `--env`, *not* `--env-file`: Node reserves `--env-file` and
23
+ * `--env-file-if-exists` and acts on them wherever they appear, including after
24
+ * the script path. `node cli.js --env-file missing` therefore dies inside Node
25
+ * with exit code 9 before this module is ever reached, so the devkit cannot own
26
+ * that name. {@link nodeOwnedEnvFlag} spots the mistake and explains it.
27
+ *
28
+ * `--env` takes a path rather than Laravel's bare environment name, because it
29
+ * mirrors Node's flag and because a path can point outside the package. A value
30
+ * that looks like it was meant as a name still gets a pointed error — see
31
+ * {@link missingFileMessage}.
32
+ */
33
+ /** Minimum Node version shipping `process.loadEnvFile`. */
34
+ export declare const ENV_FILE_MIN_NODE = "20.12";
35
+ export interface EnvFileChoice {
36
+ /** Absolute path to load, or `null` when `--no-env` disabled loading. */
37
+ path: string | null;
38
+ /** True when the file was named with `--env` rather than defaulted to. */
39
+ explicit: boolean;
40
+ /** The `--env` value exactly as typed, kept for {@link missingFileMessage}. */
41
+ raw?: string;
42
+ }
43
+ /**
44
+ * Returns the Node-owned env flag present in `argv`, if any. Node has already
45
+ * acted on it by the time the CLI runs — this exists only so the CLI can say so
46
+ * instead of leaving the user wondering why `--env-file` behaved oddly.
47
+ */
48
+ export declare function nodeOwnedEnvFlag(argv: string[]): string | null;
49
+ /**
50
+ * Decides which env file to load. Pure — touches neither disk nor `process.env`.
51
+ *
52
+ * A repeated `--env` resolves to the last one, matching every other option in
53
+ * the CLI, whose parse loop simply overwrites. Every occurrence is still
54
+ * validated, so a malformed earlier one is reported rather than skipped.
55
+ */
56
+ export declare function resolveEnvFile(argv: string[], cwd?: string): EnvFileChoice;
57
+ export interface LoadEnvFileOptions {
58
+ cwd?: string;
59
+ warn?: (message: string) => void;
60
+ }
61
+ /**
62
+ * Loads the env file chosen by {@link resolveEnvFile} into `process.env` and
63
+ * returns its path, or `null` when nothing was loaded.
64
+ *
65
+ * A missing *default* `.env` is fine — most packages do not have one. A file
66
+ * asked for by name and missing is an error: ignoring it would hide a typo and
67
+ * resurface much later as a puzzling `Seed references ${X}` failure. There is no
68
+ * fallback to `.env` in that case, since naming a file replaces the default.
69
+ */
70
+ export declare function loadEnvFile(argv: string[], options?: LoadEnvFileOptions): string | null;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * An error that maps to an HTTP status + JSON body in the mock API, mirroring
3
+ * Laravel's `{message}` / `{message, errors}` envelopes.
4
+ */
5
+ export declare class DevApiError extends Error {
6
+ readonly status: number;
7
+ readonly errors?: Record<string, string[]> | undefined;
8
+ constructor(status: number, message: string, errors?: Record<string, string[]> | undefined);
9
+ }
10
+ /**
11
+ * An error whose message is the whole story for the user — a wrong flag, an
12
+ * occupied port, a refused second preview.
13
+ *
14
+ * The CLI's top-level handler prints these as a single line and exits 1, rather
15
+ * than the stack trace it prints for a genuine defect. That distinction is the
16
+ * point: a stack trace on `--port abc` teaches the reader nothing and buries the
17
+ * one line that matters.
18
+ */
19
+ export declare class CliError extends Error {
20
+ constructor(message: string);
21
+ }
package/dist/http.d.ts ADDED
@@ -0,0 +1,23 @@
1
+ import type http from 'node:http';
2
+ /**
3
+ * The `/api/v1` contract version this mock implements. Mirrors what the real
4
+ * service reports via its `SetApiVersion` middleware.
5
+ *
6
+ * Kept as a constant rather than read from the vendored spec so nothing 357 KB
7
+ * has to ship in the package; `tests/contract.test.ts` asserts it equals
8
+ * `info.version` of `contract/integrations-v1.json`, so the two cannot drift.
9
+ */
10
+ export declare const API_VERSION = "1.0.0";
11
+ export declare function sendJson(res: http.ServerResponse, status: number, body: unknown): void;
12
+ /**
13
+ * 204 with no body, which is what the service returns from every DELETE. The mock
14
+ * used to answer `200 {deleted:true}`; per ADR-0036 §3 a changed status code is a
15
+ * breaking difference, so that was training node authors on behaviour the real API
16
+ * does not have.
17
+ */
18
+ export declare function sendNoContent(res: http.ServerResponse): void;
19
+ /** Maps a thrown error to the Laravel-style `{message}` / `{message, errors}` body. */
20
+ export declare function sendError(res: http.ServerResponse, err: unknown): void;
21
+ export declare function readBody(req: http.IncomingMessage): Promise<string>;
22
+ /** Reads + parses a JSON body; throws {@link DevApiError} 400 on malformed input. */
23
+ export declare function readJson<T>(req: http.IncomingMessage): Promise<T>;