@revenexx/integrations-node-devkit 0.7.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/cli.js CHANGED
@@ -11,7 +11,7 @@ import {
11
11
  loadSeedsFromDir,
12
12
  loadState,
13
13
  saveState
14
- } from "./chunk-4QB5F7RT.js";
14
+ } from "./chunk-YUUW37NC.js";
15
15
  import "./chunk-PME34X7E.js";
16
16
 
17
17
  // src/cli.ts
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>;
package/dist/index.cjs CHANGED
@@ -47,6 +47,7 @@ __export(index_exports, {
47
47
  findNode: () => findNode,
48
48
  importFresh: () => importFresh,
49
49
  interpolateEnv: () => interpolateEnv,
50
+ listNodesNewestFirst: () => listNodesNewestFirst,
50
51
  loadEnvFile: () => loadEnvFile,
51
52
  loadPackageFromEntry: () => loadPackageFromEntry,
52
53
  loadSeedsFromDir: () => loadSeedsFromDir,
@@ -615,20 +616,66 @@ var noopLogger = {
615
616
  error() {
616
617
  }
617
618
  };
619
+ function parseSemver(version) {
620
+ const [withoutBuild] = version.split("+");
621
+ const dash = withoutBuild.indexOf("-");
622
+ const core = (dash === -1 ? withoutBuild : withoutBuild.slice(0, dash)).split(".").map((n) => Number.parseInt(n, 10) || 0);
623
+ const pre = dash === -1 ? [] : withoutBuild.slice(dash + 1).split(".");
624
+ return { core, pre };
625
+ }
626
+ function comparePrerelease(a, b) {
627
+ if (a.length === 0 || b.length === 0) {
628
+ return (a.length === 0 ? 1 : 0) - (b.length === 0 ? 1 : 0);
629
+ }
630
+ for (let i = 0; i < Math.max(a.length, b.length); i++) {
631
+ const ia = a[i];
632
+ const ib = b[i];
633
+ if (ia === void 0 || ib === void 0) {
634
+ return ia === void 0 ? -1 : 1;
635
+ }
636
+ const na = /^\d+$/.test(ia) ? Number(ia) : null;
637
+ const nb = /^\d+$/.test(ib) ? Number(ib) : null;
638
+ if (na !== null && nb !== null) {
639
+ if (na !== nb) {
640
+ return na - nb;
641
+ }
642
+ continue;
643
+ }
644
+ if (na !== null || nb !== null) {
645
+ return na !== null ? -1 : 1;
646
+ }
647
+ if (ia !== ib) {
648
+ return ia < ib ? -1 : 1;
649
+ }
650
+ }
651
+ return 0;
652
+ }
618
653
  function compareSemver(a, b) {
619
- const pa = a.split(".").map((n) => Number.parseInt(n, 10) || 0);
620
- const pb = b.split(".").map((n) => Number.parseInt(n, 10) || 0);
654
+ const pa = parseSemver(a);
655
+ const pb = parseSemver(b);
621
656
  for (let i = 0; i < 3; i++) {
622
- const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
657
+ const diff = (pa.core[i] ?? 0) - (pb.core[i] ?? 0);
623
658
  if (diff !== 0) {
624
659
  return diff;
625
660
  }
626
661
  }
627
- return 0;
662
+ return comparePrerelease(pa.pre, pb.pre);
628
663
  }
629
664
  function nodeVersions(loaded, slug) {
630
665
  return loaded.nodes.filter((n) => n.description.slug === slug).map((n) => n.description.version).sort((a, b) => compareSemver(b, a));
631
666
  }
667
+ function listNodesNewestFirst(nodes) {
668
+ const bySlug = /* @__PURE__ */ new Map();
669
+ for (const node of nodes) {
670
+ const group = bySlug.get(node.slug);
671
+ if (group) {
672
+ group.push(node);
673
+ } else {
674
+ bySlug.set(node.slug, [node]);
675
+ }
676
+ }
677
+ return [...bySlug.values()].flatMap((group) => [...group].sort((a, b) => compareSemver(b.version, a.version)));
678
+ }
632
679
  function findNode(loaded, slug, version) {
633
680
  const matches = loaded.nodes.filter((n) => n.description.slug === slug);
634
681
  if (matches.length === 0) {
@@ -1212,13 +1259,24 @@ function createRequestListener(deps) {
1212
1259
  function createDevServer(deps) {
1213
1260
  return import_node_http.default.createServer(createRequestListener(deps));
1214
1261
  }
1262
+ function requestOrigin(req) {
1263
+ const host = req.headers.host;
1264
+ if (!host) {
1265
+ return "http://localhost";
1266
+ }
1267
+ try {
1268
+ return new URL(`http://${host}`).origin;
1269
+ } catch {
1270
+ return "http://localhost";
1271
+ }
1272
+ }
1215
1273
  async function handle(req, res, deps) {
1216
1274
  const method = (req.method ?? "GET").toUpperCase();
1217
1275
  if (method === "OPTIONS") {
1218
1276
  sendJson(res, 204, {});
1219
1277
  return;
1220
1278
  }
1221
- const url = new URL(req.url ?? "/", "http://localhost");
1279
+ const url = new URL(req.url ?? "/", requestOrigin(req));
1222
1280
  let pathname = url.pathname;
1223
1281
  if (pathname.startsWith("/api/v1")) {
1224
1282
  pathname = pathname.slice("/api/v1".length);
@@ -1279,7 +1337,7 @@ function handleSchemas(res, deps, seg) {
1279
1337
  }
1280
1338
  async function handleNodes(req, res, method, loaded, store, seg) {
1281
1339
  if (seg.length === 1 && method === "GET") {
1282
- return void sendJson(res, 200, { data: loaded.manifest.nodes.map((n) => nodeToApi(n, nodeApiContext(loaded))) });
1340
+ return void sendJson(res, 200, { data: listNodesNewestFirst(loaded.manifest.nodes).map((n) => nodeToApi(n, nodeApiContext(loaded))) });
1283
1341
  }
1284
1342
  const slug = seg[1];
1285
1343
  if (!slug) {
@@ -1344,7 +1402,8 @@ function nodeApiContext(loaded) {
1344
1402
  return { packageInfo: loaded.packageInfo, loadedAt: loaded.loadedAt };
1345
1403
  }
1346
1404
  function findManifestNode(loaded, slug, version) {
1347
- const node = loaded.manifest.nodes.find((n) => n.slug === slug && (version === "latest" || n.version === version));
1405
+ const matches = loaded.manifest.nodes.filter((n) => n.slug === slug);
1406
+ const node = version === "latest" ? listNodesNewestFirst(matches)[0] : matches.find((n) => n.version === version);
1348
1407
  if (!node) {
1349
1408
  throw new DevApiError(404, `Node '${slug}@${version}' not found.`);
1350
1409
  }
@@ -1422,7 +1481,7 @@ async function handleCredentials(req, res, method, loaded, store, seg, url) {
1422
1481
  });
1423
1482
  }
1424
1483
  if (seg[2] === "oauth" && seg[3] === "authorize-url" && method === "POST") {
1425
- const redirectUri = "http://localhost/api/v1/credentials/oauth/callback";
1484
+ const redirectUri = `${url.origin}/api/v1/credentials/oauth/callback`;
1426
1485
  const result = await buildOAuthAuthorizeUrl(loaded, store, id, { redirectUri, state: id });
1427
1486
  return void sendJson(res, 200, { authorize_url: result.authorizeUrl });
1428
1487
  }
@@ -1629,6 +1688,7 @@ var DEVKIT_VERSION = JSON.parse((0, import_node_fs4.readFileSync)(manifestUrl, "
1629
1688
  findNode,
1630
1689
  importFresh,
1631
1690
  interpolateEnv,
1691
+ listNodesNewestFirst,
1632
1692
  loadEnvFile,
1633
1693
  loadPackageFromEntry,
1634
1694
  loadSeedsFromDir,