wyvrnpm 2.11.0 → 2.12.2

package/src/auth.js

@@ -1,66 +1,66 @@
-'use strict';
-
-/**
- * Resolve an authentication token for HTTP-source reads/writes.
- *
- * Closes EVALUATION.md S8 — passing `--token <value>` on the command line
- * leaks the token into any shell history, process table, or CI job log
- * that captures argv. `--token-env <VAR>` and the config equivalent
- * `tokenEnv` let users keep the literal value in env only.
- *
- * Resolution order (first match wins):
- *   1. `token`     — literal string from CLI or config (explicit beats env).
- *   2. `tokenEnv`  — name of an env var; its value becomes the token.
- *
- * Returns `undefined` when nothing is configured (valid — not every source
- * needs auth). Throws when `tokenEnv` names a var that is unset or empty.
- *
- * @param {{ token?: string, tokenEnv?: string }} opts
- * @returns {string|undefined}
- */
-function resolveToken(opts = {}) {
-  const { token, tokenEnv } = opts;
-
-  if (typeof token === 'string' && token.length > 0) {
-    return token;
-  }
-
-  if (typeof tokenEnv === 'string' && tokenEnv.length > 0) {
-    const value = process.env[tokenEnv];
-    if (typeof value !== 'string' || value.length === 0) {
-      throw new Error(
-        `--token-env ${tokenEnv} (or config tokenEnv=${tokenEnv}) is set, ` +
-        `but the environment variable is unset or empty.`,
-      );
-    }
-    return value;
-  }
-
-  return undefined;
-}
-
-/**
- * Merge CLI auth args + a source-config entry into a final `{ token }`
- * object ready for passing to a provider. Centralises the "CLI wins,
- * then env-backed CLI, then config literal, then config env-backed"
- * precedence so call sites don't each re-implement it.
- *
- * @param {{ token?: string, tokenEnv?: string }} cli
- * @param {{ token?: string, tokenEnv?: string } | null | undefined} source
- * @returns {{ token: string|undefined }}
- */
-function resolveSourceAuth(cli, source) {
-  // Try CLI first; if it produced nothing, fall back to the source's
-  // own stored auth. Each call to resolveToken handles its own
-  // precedence (literal > env) and throws on invalid tokenEnv.
-  const fromCli    = resolveToken(cli);
-  if (fromCli !== undefined) return { token: fromCli };
-
-  const fromSource = source ? resolveToken(source) : undefined;
-  return { token: fromSource };
-}
-
-module.exports = {
-  resolveToken,
-  resolveSourceAuth,
-};
+'use strict';
+
+/**
+ * Resolve an authentication token for HTTP-source reads/writes.
+ *
+ * Closes EVALUATION.md S8 — passing `--token <value>` on the command line
+ * leaks the token into any shell history, process table, or CI job log
+ * that captures argv. `--token-env <VAR>` and the config equivalent
+ * `tokenEnv` let users keep the literal value in env only.
+ *
+ * Resolution order (first match wins):
+ *   1. `token`     — literal string from CLI or config (explicit beats env).
+ *   2. `tokenEnv`  — name of an env var; its value becomes the token.
+ *
+ * Returns `undefined` when nothing is configured (valid — not every source
+ * needs auth). Throws when `tokenEnv` names a var that is unset or empty.
+ *
+ * @param {{ token?: string, tokenEnv?: string }} opts
+ * @returns {string|undefined}
+ */
+function resolveToken(opts = {}) {
+  const { token, tokenEnv } = opts;
+
+  if (typeof token === 'string' && token.length > 0) {
+    return token;
+  }
+
+  if (typeof tokenEnv === 'string' && tokenEnv.length > 0) {
+    const value = process.env[tokenEnv];
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new Error(
+        `--token-env ${tokenEnv} (or config tokenEnv=${tokenEnv}) is set, ` +
+        `but the environment variable is unset or empty.`,
+      );
+    }
+    return value;
+  }
+
+  return undefined;
+}
+
+/**
+ * Merge CLI auth args + a source-config entry into a final `{ token }`
+ * object ready for passing to a provider. Centralises the "CLI wins,
+ * then env-backed CLI, then config literal, then config env-backed"
+ * precedence so call sites don't each re-implement it.
+ *
+ * @param {{ token?: string, tokenEnv?: string }} cli
+ * @param {{ token?: string, tokenEnv?: string } | null | undefined} source
+ * @returns {{ token: string|undefined }}
+ */
+function resolveSourceAuth(cli, source) {
+  // Try CLI first; if it produced nothing, fall back to the source's
+  // own stored auth. Each call to resolveToken handles its own
+  // precedence (literal > env) and throws on invalid tokenEnv.
+  const fromCli    = resolveToken(cli);
+  if (fromCli !== undefined) return { token: fromCli };
+
+  const fromSource = source ? resolveToken(source) : undefined;
+  return { token: fromSource };
+}
+
+module.exports = {
+  resolveToken,
+  resolveSourceAuth,
+};

package/src/binary-dir.js

@@ -0,0 +1,95 @@
+'use strict';
+
+// Project-local CMake binary-dir root. Sibling concept to `conf` —
+// non-ABI, dev-local, never published. Two channels feed it:
+//
+//   1. CLI flag `--build-dir <path>` (install + build)
+//   2. wyvrn.local.json `binaryDirRoot` (persistent per-developer)
+//
+// CLI > local > default `"build"`. The resolved value plugs into the
+// preset's binaryDir as `${sourceDir}/<binaryDirRoot>/wyvrn-<profile>`.
+//
+// Why this exists: repos with a `BUILD` Bazel/Buck file at the root
+// collide with the default `build/` subdir on case-insensitive
+// filesystems (Windows NTFS, macOS HFS+ default). gRPC is the
+// canonical case.
+
+const path = require('path');
+
+const DEFAULT_BINARY_DIR_ROOT = 'build';
+
+/**
+ * Validate + normalise a candidate binaryDirRoot value. Returns the
+ * normalised string (forward slashes, no trailing separator) or
+ * throws with a `<source>:` prefix so the caller knows which channel
+ * the bad value came from.
+ *
+ * @param {unknown} value
+ * @param {string}  source  e.g. "--build-dir" or "wyvrn.local.json"
+ * @returns {string}
+ */
+function validateBinaryDirRoot(value, source) {
+  if (typeof value !== 'string') {
+    throw new Error(`${source}: binaryDirRoot must be a string, got ${typeof value}`);
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`${source}: binaryDirRoot must not be empty`);
+  }
+  // Reject absolute paths — the preset macro is `${sourceDir}/<root>`,
+  // so an absolute value would produce nonsense (`${sourceDir}//abs`
+  // or `${sourceDir}/C:/...`). If a user genuinely wants an absolute
+  // build dir they can hand-edit CMakeUserPresets.json; that's a
+  // different escape hatch.
+  if (path.isAbsolute(trimmed) || /^[a-zA-Z]:[\\/]/.test(trimmed)) {
+    throw new Error(
+      `${source}: binaryDirRoot must be relative to the project root, ` +
+      `got ${JSON.stringify(trimmed)}`,
+    );
+  }
+
+  // Normalise to forward slashes (CMake preset macros expect them) and
+  // strip any trailing separators so the join is deterministic.
+  const normalised = trimmed.replace(/\\/g, '/').replace(/\/+$/, '');
+  if (normalised.length === 0) {
+    throw new Error(`${source}: binaryDirRoot must not be empty`);
+  }
+
+  // `..` segments would let a value escape the project root — reject
+  // rather than silently allow it. Single `.` segments are harmless and
+  // CMake handles them fine.
+  if (normalised.split('/').some((seg) => seg === '..')) {
+    throw new Error(`${source}: binaryDirRoot must not contain ".." segments`);
+  }
+
+  return normalised;
+}
+
+/**
+ * Resolve the effective binaryDirRoot from the two configured channels.
+ * Pure function — deliberately takes pre-read values rather than doing
+ * filesystem I/O so unit tests don't need temp dirs.
+ *
+ * @param {object} args
+ * @param {string|null|undefined} [args.cliBuildDir]
+ *   Value of `--build-dir` from argv. `undefined`/`null` = not passed.
+ * @param {string|null|undefined} [args.localOverlayBinaryDirRoot]
+ *   Value of `binaryDirRoot` read out of wyvrn.local.json (already
+ *   parsed; this module does NOT re-read the file).
+ * @returns {string}
+ */
+function resolveBinaryDirRoot({ cliBuildDir, localOverlayBinaryDirRoot } = {}) {
+  if (cliBuildDir !== undefined && cliBuildDir !== null) {
+    return validateBinaryDirRoot(cliBuildDir, '--build-dir');
+  }
+  if (localOverlayBinaryDirRoot !== undefined && localOverlayBinaryDirRoot !== null) {
+    return validateBinaryDirRoot(localOverlayBinaryDirRoot, 'wyvrn.local.json');
+  }
+  return DEFAULT_BINARY_DIR_ROOT;
+}
+
+module.exports = {
+  DEFAULT_BINARY_DIR_ROOT,
+  resolveBinaryDirRoot,
+  validateBinaryDirRoot,
+};

package/src/bootstrap/cookbook.js

@@ -1,196 +1,196 @@
-'use strict';
-
-/**
- * Known-library cookbook for `wyvrnpm bootstrap`.
- *
- * Each entry captures the non-obvious tweaks a wyvrnpm recipe needs for a
- * popular upstream — the CMake cache variables that disable tests /
- * examples / docs so the install tree doesn't balloon, install gates the
- * upstream hides behind a flag (the `ZLIB_INSTALL=ON` class of gotcha,
- * see SKILL.md references/manifest-authoring.md §build), and any
- * transitive wyvrnpm deps the upstream already depends on.
- *
- * Keyed by a case-insensitive match on the repo tail. Matching is
- * restricted to exact tails so `wyvrnpm bootstrap` never surprises a
- * user whose fork name collides coincidentally — unmatched tails get
- * the safe-default recipe.
- *
- * Keep this file short and dumb. Rich per-library behaviour belongs in
- * the author's actual `wyvrn.json` — the cookbook is just the "everyone
- * hits these flags on day one" cheat sheet.
- *
- * @typedef {Object} CookbookEntry
- * @property {'HeaderOnlyLib'|'StaticLib'|'DynamicLib'} [kind]
- *   Override `detect.js` when upstream's CMakeLists lies (e.g. fmt has
- *   both a STATIC lib and an INTERFACE `fmt-header-only`).
- * @property {string[]} [configure]
- *   `-DKEY=VAL` args threaded into build.configure. Preserves order so a
- *   `-DBUILD_SHARED_LIBS=OFF` comes before a `-DXYZ_OPTION=...` override.
- * @property {Record<string,string>} [dependencies]
- *   Known wyvrnpm deps — merged into manifest.dependencies. Versions
- *   use `"latest"` so the user picks up whatever the team's registry
- *   publishes; they can pin in review.
- * @property {string[]} [notes]
- *   Human-readable reminders appended to the TODO report.
- */
-
-/** @type {Record<string, CookbookEntry>} */
-const KNOWN_LIBRARIES = Object.freeze({
-  // ── Formatting / logging ─────────────────────────────────────────────
-  fmt: {
-    kind: 'StaticLib',
-    configure: ['-DFMT_TEST=OFF', '-DFMT_DOC=OFF'],
-    notes: [
-      'fmt also ships a `fmt-header-only` INTERFACE target. If you want ' +
-      'the header-only variant, declare kind=HeaderOnlyLib and add -DFMT_INSTALL=ON.',
-    ],
-  },
-  spdlog: {
-    kind: 'StaticLib',
-    configure: [
-      '-DSPDLOG_BUILD_TESTS=OFF',
-      '-DSPDLOG_BUILD_EXAMPLE=OFF',
-      '-DSPDLOG_INSTALL=ON',
-      '-DSPDLOG_FMT_EXTERNAL=ON',
-    ],
-    dependencies: { fmt: 'latest' },
-    notes: [
-      'SPDLOG_FMT_EXTERNAL=ON makes spdlog link against the wyvrnpm fmt package ' +
-      'instead of its bundled fork. Drop if you want the bundled copy.',
-    ],
-  },
-
-  // ── JSON / config / serialization ────────────────────────────────────
-  json:      { kind: 'HeaderOnlyLib', configure: ['-DJSON_BuildTests=OFF'] },
-  rapidjson: { kind: 'HeaderOnlyLib', configure: ['-DRAPIDJSON_BUILD_TESTS=OFF', '-DRAPIDJSON_BUILD_EXAMPLES=OFF', '-DRAPIDJSON_BUILD_DOC=OFF'] },
-  jsoncpp:   { kind: 'StaticLib',     configure: ['-DJSONCPP_WITH_TESTS=OFF', '-DJSONCPP_WITH_POST_BUILD_UNITTEST=OFF'] },
-  'yaml-cpp':{ kind: 'StaticLib',     configure: ['-DYAML_CPP_BUILD_TESTS=OFF', '-DYAML_CPP_BUILD_TOOLS=OFF', '-DYAML_CPP_INSTALL=ON'] },
-  pugixml:   { kind: 'StaticLib',     configure: ['-DPUGIXML_BUILD_TESTS=OFF'] },
-  tinyxml2:  { kind: 'StaticLib',     configure: ['-Dtinyxml2_BUILD_TESTING=OFF'] },
-  cereal:    { kind: 'HeaderOnlyLib', configure: ['-DJUST_INSTALL_CEREAL=ON'] },
-  'msgpack-c': { kind: 'StaticLib',   configure: ['-DMSGPACK_BUILD_TESTS=OFF', '-DMSGPACK_BUILD_EXAMPLES=OFF'] },
-
-  // ── CLI / utilities ──────────────────────────────────────────────────
-  cli11:       { kind: 'HeaderOnlyLib', configure: ['-DCLI11_BUILD_TESTS=OFF', '-DCLI11_BUILD_EXAMPLES=OFF'] },
-  cxxopts:     { kind: 'HeaderOnlyLib', configure: ['-DCXXOPTS_BUILD_TESTS=OFF', '-DCXXOPTS_BUILD_EXAMPLES=OFF'] },
-  magic_enum:  { kind: 'HeaderOnlyLib', configure: ['-DMAGIC_ENUM_OPT_BUILD_EXAMPLES=OFF', '-DMAGIC_ENUM_OPT_BUILD_TESTS=OFF'] },
-  date:        { kind: 'StaticLib',     configure: ['-DBUILD_TZ_LIB=ON', '-DUSE_SYSTEM_TZ_DB=OFF'] },
-  utfcpp:      { kind: 'HeaderOnlyLib', configure: ['-DUTF8_TESTS=OFF', '-DUTF8_SAMPLES=OFF'] },
-
-  // ── Testing / benchmarking ──────────────────────────────────────────
-  catch2:    { kind: 'StaticLib',     configure: ['-DCATCH_INSTALL_DOCS=OFF', '-DCATCH_BUILD_TESTING=OFF'] },
-  doctest:   { kind: 'HeaderOnlyLib', configure: ['-DDOCTEST_WITH_TESTS=OFF', '-DDOCTEST_WITH_MAIN_IN_STATIC_LIB=OFF'] },
-  benchmark: {
-    kind: 'StaticLib',
-    configure: ['-DBENCHMARK_ENABLE_TESTING=OFF', '-DBENCHMARK_ENABLE_GTEST_TESTS=OFF'],
-    notes: ['google/benchmark — only one of several projects named "benchmark"; confirm the repo URL.'],
-  },
-
-  // ── Compression ──────────────────────────────────────────────────────
-  zlib: {
-    kind: 'StaticLib',
-    configure: ['-DZLIB_BUILD_EXAMPLES=OFF'],
-    notes: [
-      'zlib is the textbook example for an `options.shared` toggle — see ' +
-      'references/worked-example-zlib.md. Consider declaring it before you publish.',
-    ],
-  },
-  lz4:     { kind: 'StaticLib', configure: ['-DLZ4_BUILD_LEGACY_LZ4C=OFF', '-DLZ4_BUILD_CLI=OFF', '-DBUILD_SHARED_LIBS=OFF'] },
-  snappy:  { kind: 'StaticLib', configure: ['-DSNAPPY_BUILD_TESTS=OFF', '-DSNAPPY_BUILD_BENCHMARKS=OFF'] },
-  brotli:  { kind: 'StaticLib', configure: ['-DBROTLI_DISABLE_TESTS=ON'] },
-  bzip2: {
-    notes: [
-      'bzip2 uses autotools (no CMakeLists.txt). Either ship a wrapper CMakeLists.txt ' +
-      'in your fork or prebuild + publish as a binary-only artefact.',
-    ],
-  },
-
-  // ── Networking / HTTP ────────────────────────────────────────────────
-  'cpp-httplib':   { kind: 'HeaderOnlyLib', configure: ['-DHTTPLIB_TEST=OFF'] },
-  cpr: {
-    kind: 'StaticLib',
-    configure: ['-DCPR_BUILD_TESTS=OFF', '-DCPR_USE_SYSTEM_CURL=ON'],
-    notes: ['cpr needs libcurl — add a wyvrnpm `libcurl` dep if your registry publishes one, or rely on system curl.'],
-  },
-  websocketpp: {
-    kind: 'HeaderOnlyLib',
-    notes: ['websocketpp requires boost::asio or standalone Asio — add the appropriate dep.'],
-  },
-  cppzmq: {
-    kind: 'HeaderOnlyLib',
-    notes: ['cppzmq needs libzmq — add a wyvrnpm dep for libzmq before publish.'],
-  },
-  hiredis:            { kind: 'StaticLib', configure: ['-DDISABLE_TESTS=ON', '-DENABLE_EXAMPLES=OFF'] },
-  'redis-plus-plus':  {
-    kind: 'StaticLib',
-    configure: ['-DREDIS_PLUS_PLUS_BUILD_TEST=OFF', '-DREDIS_PLUS_PLUS_USE_TLS=OFF'],
-    dependencies: { hiredis: 'latest' },
-  },
-
-  // ── Concurrency ──────────────────────────────────────────────────────
-  concurrentqueue:    { kind: 'HeaderOnlyLib' },
-  readerwriterqueue:  { kind: 'HeaderOnlyLib' },
-
-  // ── Graphics / image ─────────────────────────────────────────────────
-  stb: {
-    kind: 'HeaderOnlyLib',
-    notes: [
-      'stb is a header drop — no CMakeLists.txt upstream. Ship a small wrapper ' +
-      'CMakeLists.txt in your fork that declares an INTERFACE target with ' +
-      'target_include_directories(... INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}) and install() rules.',
-    ],
-  },
-  glm: { kind: 'HeaderOnlyLib', configure: ['-DGLM_TEST_ENABLE=OFF', '-DGLM_BUILD_LIBRARY=OFF'] },
-  imgui: {
-    notes: [
-      'imgui ships no CMakeLists.txt. Ship a wrapper CMakeLists.txt in your fork ' +
-      'that picks the backends you need (OpenGL3/Win32/DX11/etc) and declares a ' +
-      'StaticLib with them.',
-    ],
-  },
-  nuklear: {
-    kind: 'HeaderOnlyLib',
-    notes: [
-      'Nuklear is a single-header drop. Same pattern as stb: ship an INTERFACE ' +
-      'wrapper CMakeLists.txt in your fork.',
-    ],
-  },
-
-  // ── Database ─────────────────────────────────────────────────────────
-  sqlitecpp: { kind: 'StaticLib', configure: ['-DSQLITECPP_RUN_CPPLINT=OFF', '-DSQLITECPP_RUN_CPPCHECK=OFF', '-DSQLITECPP_BUILD_TESTS=OFF', '-DSQLITECPP_BUILD_EXAMPLES=OFF'] },
-
-  // ── Crypto ───────────────────────────────────────────────────────────
-  libsodium: {
-    notes: [
-      'libsodium uses autotools (configure.ac, Makefile.am). wyvrnpm source-build ' +
-      'supports cmake only — ship a wrapper CMakeLists.txt in your fork, or ' +
-      'prebuild + publish as a binary-only artefact.',
-    ],
-  },
-
-  // ── Text / regex ─────────────────────────────────────────────────────
-  re2: { kind: 'StaticLib', configure: ['-DRE2_BUILD_TESTING=OFF'] },
-});
-
-/**
- * Look up cookbook hints for a given package tail (e.g. "fmt", "zlib").
- * Case-insensitive; returns a defensive copy so callers can merge freely.
- *
- * @param {string} key
- * @returns {CookbookEntry | null}
- */
-function lookupCookbook(key) {
-  if (typeof key !== 'string') return null;
-  const normal = key.trim().toLowerCase();
-  if (!normal) return null;
-  const entry = KNOWN_LIBRARIES[normal];
-  if (!entry) return null;
-  return {
-    ...entry,
-    configure:    entry.configure    ? [...entry.configure]         : undefined,
-    dependencies: entry.dependencies ? { ...entry.dependencies }    : undefined,
-    notes:        entry.notes        ? [...entry.notes]             : undefined,
-  };
-}
-
-module.exports = { KNOWN_LIBRARIES, lookupCookbook };
+'use strict';
+
+/**
+ * Known-library cookbook for `wyvrnpm bootstrap`.
+ *
+ * Each entry captures the non-obvious tweaks a wyvrnpm recipe needs for a
+ * popular upstream — the CMake cache variables that disable tests /
+ * examples / docs so the install tree doesn't balloon, install gates the
+ * upstream hides behind a flag (the `ZLIB_INSTALL=ON` class of gotcha,
+ * see SKILL.md references/manifest-authoring.md §build), and any
+ * transitive wyvrnpm deps the upstream already depends on.
+ *
+ * Keyed by a case-insensitive match on the repo tail. Matching is
+ * restricted to exact tails so `wyvrnpm bootstrap` never surprises a
+ * user whose fork name collides coincidentally — unmatched tails get
+ * the safe-default recipe.
+ *
+ * Keep this file short and dumb. Rich per-library behaviour belongs in
+ * the author's actual `wyvrn.json` — the cookbook is just the "everyone
+ * hits these flags on day one" cheat sheet.
+ *
+ * @typedef {Object} CookbookEntry
+ * @property {'HeaderOnlyLib'|'StaticLib'|'DynamicLib'} [kind]
+ *   Override `detect.js` when upstream's CMakeLists lies (e.g. fmt has
+ *   both a STATIC lib and an INTERFACE `fmt-header-only`).
+ * @property {string[]} [configure]
+ *   `-DKEY=VAL` args threaded into build.configure. Preserves order so a
+ *   `-DBUILD_SHARED_LIBS=OFF` comes before a `-DXYZ_OPTION=...` override.
+ * @property {Record<string,string>} [dependencies]
+ *   Known wyvrnpm deps — merged into manifest.dependencies. Versions
+ *   use `"latest"` so the user picks up whatever the team's registry
+ *   publishes; they can pin in review.
+ * @property {string[]} [notes]
+ *   Human-readable reminders appended to the TODO report.
+ */
+
+/** @type {Record<string, CookbookEntry>} */
+const KNOWN_LIBRARIES = Object.freeze({
+  // ── Formatting / logging ─────────────────────────────────────────────
+  fmt: {
+    kind: 'StaticLib',
+    configure: ['-DFMT_TEST=OFF', '-DFMT_DOC=OFF'],
+    notes: [
+      'fmt also ships a `fmt-header-only` INTERFACE target. If you want ' +
+      'the header-only variant, declare kind=HeaderOnlyLib and add -DFMT_INSTALL=ON.',
+    ],
+  },
+  spdlog: {
+    kind: 'StaticLib',
+    configure: [
+      '-DSPDLOG_BUILD_TESTS=OFF',
+      '-DSPDLOG_BUILD_EXAMPLE=OFF',
+      '-DSPDLOG_INSTALL=ON',
+      '-DSPDLOG_FMT_EXTERNAL=ON',
+    ],
+    dependencies: { fmt: 'latest' },
+    notes: [
+      'SPDLOG_FMT_EXTERNAL=ON makes spdlog link against the wyvrnpm fmt package ' +
+      'instead of its bundled fork. Drop if you want the bundled copy.',
+    ],
+  },
+
+  // ── JSON / config / serialization ────────────────────────────────────
+  json:      { kind: 'HeaderOnlyLib', configure: ['-DJSON_BuildTests=OFF'] },
+  rapidjson: { kind: 'HeaderOnlyLib', configure: ['-DRAPIDJSON_BUILD_TESTS=OFF', '-DRAPIDJSON_BUILD_EXAMPLES=OFF', '-DRAPIDJSON_BUILD_DOC=OFF'] },
+  jsoncpp:   { kind: 'StaticLib',     configure: ['-DJSONCPP_WITH_TESTS=OFF', '-DJSONCPP_WITH_POST_BUILD_UNITTEST=OFF'] },
+  'yaml-cpp':{ kind: 'StaticLib',     configure: ['-DYAML_CPP_BUILD_TESTS=OFF', '-DYAML_CPP_BUILD_TOOLS=OFF', '-DYAML_CPP_INSTALL=ON'] },
+  pugixml:   { kind: 'StaticLib',     configure: ['-DPUGIXML_BUILD_TESTS=OFF'] },
+  tinyxml2:  { kind: 'StaticLib',     configure: ['-Dtinyxml2_BUILD_TESTING=OFF'] },
+  cereal:    { kind: 'HeaderOnlyLib', configure: ['-DJUST_INSTALL_CEREAL=ON'] },
+  'msgpack-c': { kind: 'StaticLib',   configure: ['-DMSGPACK_BUILD_TESTS=OFF', '-DMSGPACK_BUILD_EXAMPLES=OFF'] },
+
+  // ── CLI / utilities ──────────────────────────────────────────────────
+  cli11:       { kind: 'HeaderOnlyLib', configure: ['-DCLI11_BUILD_TESTS=OFF', '-DCLI11_BUILD_EXAMPLES=OFF'] },
+  cxxopts:     { kind: 'HeaderOnlyLib', configure: ['-DCXXOPTS_BUILD_TESTS=OFF', '-DCXXOPTS_BUILD_EXAMPLES=OFF'] },
+  magic_enum:  { kind: 'HeaderOnlyLib', configure: ['-DMAGIC_ENUM_OPT_BUILD_EXAMPLES=OFF', '-DMAGIC_ENUM_OPT_BUILD_TESTS=OFF'] },
+  date:        { kind: 'StaticLib',     configure: ['-DBUILD_TZ_LIB=ON', '-DUSE_SYSTEM_TZ_DB=OFF'] },
+  utfcpp:      { kind: 'HeaderOnlyLib', configure: ['-DUTF8_TESTS=OFF', '-DUTF8_SAMPLES=OFF'] },
+
+  // ── Testing / benchmarking ──────────────────────────────────────────
+  catch2:    { kind: 'StaticLib',     configure: ['-DCATCH_INSTALL_DOCS=OFF', '-DCATCH_BUILD_TESTING=OFF'] },
+  doctest:   { kind: 'HeaderOnlyLib', configure: ['-DDOCTEST_WITH_TESTS=OFF', '-DDOCTEST_WITH_MAIN_IN_STATIC_LIB=OFF'] },
+  benchmark: {
+    kind: 'StaticLib',
+    configure: ['-DBENCHMARK_ENABLE_TESTING=OFF', '-DBENCHMARK_ENABLE_GTEST_TESTS=OFF'],
+    notes: ['google/benchmark — only one of several projects named "benchmark"; confirm the repo URL.'],
+  },
+
+  // ── Compression ──────────────────────────────────────────────────────
+  zlib: {
+    kind: 'StaticLib',
+    configure: ['-DZLIB_BUILD_EXAMPLES=OFF'],
+    notes: [
+      'zlib is the textbook example for an `options.shared` toggle — see ' +
+      'references/worked-example-zlib.md. Consider declaring it before you publish.',
+    ],
+  },
+  lz4:     { kind: 'StaticLib', configure: ['-DLZ4_BUILD_LEGACY_LZ4C=OFF', '-DLZ4_BUILD_CLI=OFF', '-DBUILD_SHARED_LIBS=OFF'] },
+  snappy:  { kind: 'StaticLib', configure: ['-DSNAPPY_BUILD_TESTS=OFF', '-DSNAPPY_BUILD_BENCHMARKS=OFF'] },
+  brotli:  { kind: 'StaticLib', configure: ['-DBROTLI_DISABLE_TESTS=ON'] },
+  bzip2: {
+    notes: [
+      'bzip2 uses autotools (no CMakeLists.txt). Either ship a wrapper CMakeLists.txt ' +
+      'in your fork or prebuild + publish as a binary-only artefact.',
+    ],
+  },
+
+  // ── Networking / HTTP ────────────────────────────────────────────────
+  'cpp-httplib':   { kind: 'HeaderOnlyLib', configure: ['-DHTTPLIB_TEST=OFF'] },
+  cpr: {
+    kind: 'StaticLib',
+    configure: ['-DCPR_BUILD_TESTS=OFF', '-DCPR_USE_SYSTEM_CURL=ON'],
+    notes: ['cpr needs libcurl — add a wyvrnpm `libcurl` dep if your registry publishes one, or rely on system curl.'],
+  },
+  websocketpp: {
+    kind: 'HeaderOnlyLib',
+    notes: ['websocketpp requires boost::asio or standalone Asio — add the appropriate dep.'],
+  },
+  cppzmq: {
+    kind: 'HeaderOnlyLib',
+    notes: ['cppzmq needs libzmq — add a wyvrnpm dep for libzmq before publish.'],
+  },
+  hiredis:            { kind: 'StaticLib', configure: ['-DDISABLE_TESTS=ON', '-DENABLE_EXAMPLES=OFF'] },
+  'redis-plus-plus':  {
+    kind: 'StaticLib',
+    configure: ['-DREDIS_PLUS_PLUS_BUILD_TEST=OFF', '-DREDIS_PLUS_PLUS_USE_TLS=OFF'],
+    dependencies: { hiredis: 'latest' },
+  },
+
+  // ── Concurrency ──────────────────────────────────────────────────────
+  concurrentqueue:    { kind: 'HeaderOnlyLib' },
+  readerwriterqueue:  { kind: 'HeaderOnlyLib' },
+
+  // ── Graphics / image ─────────────────────────────────────────────────
+  stb: {
+    kind: 'HeaderOnlyLib',
+    notes: [
+      'stb is a header drop — no CMakeLists.txt upstream. Ship a small wrapper ' +
+      'CMakeLists.txt in your fork that declares an INTERFACE target with ' +
+      'target_include_directories(... INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}) and install() rules.',
+    ],
+  },
+  glm: { kind: 'HeaderOnlyLib', configure: ['-DGLM_TEST_ENABLE=OFF', '-DGLM_BUILD_LIBRARY=OFF'] },
+  imgui: {
+    notes: [
+      'imgui ships no CMakeLists.txt. Ship a wrapper CMakeLists.txt in your fork ' +
+      'that picks the backends you need (OpenGL3/Win32/DX11/etc) and declares a ' +
+      'StaticLib with them.',
+    ],
+  },
+  nuklear: {
+    kind: 'HeaderOnlyLib',
+    notes: [
+      'Nuklear is a single-header drop. Same pattern as stb: ship an INTERFACE ' +
+      'wrapper CMakeLists.txt in your fork.',
+    ],
+  },
+
+  // ── Database ─────────────────────────────────────────────────────────
+  sqlitecpp: { kind: 'StaticLib', configure: ['-DSQLITECPP_RUN_CPPLINT=OFF', '-DSQLITECPP_RUN_CPPCHECK=OFF', '-DSQLITECPP_BUILD_TESTS=OFF', '-DSQLITECPP_BUILD_EXAMPLES=OFF'] },
+
+  // ── Crypto ───────────────────────────────────────────────────────────
+  libsodium: {
+    notes: [
+      'libsodium uses autotools (configure.ac, Makefile.am). wyvrnpm source-build ' +
+      'supports cmake only — ship a wrapper CMakeLists.txt in your fork, or ' +
+      'prebuild + publish as a binary-only artefact.',
+    ],
+  },
+
+  // ── Text / regex ─────────────────────────────────────────────────────
+  re2: { kind: 'StaticLib', configure: ['-DRE2_BUILD_TESTING=OFF'] },
+});
+
+/**
+ * Look up cookbook hints for a given package tail (e.g. "fmt", "zlib").
+ * Case-insensitive; returns a defensive copy so callers can merge freely.
+ *
+ * @param {string} key
+ * @returns {CookbookEntry | null}
+ */
+function lookupCookbook(key) {
+  if (typeof key !== 'string') return null;
+  const normal = key.trim().toLowerCase();
+  if (!normal) return null;
+  const entry = KNOWN_LIBRARIES[normal];
+  if (!entry) return null;
+  return {
+    ...entry,
+    configure:    entry.configure    ? [...entry.configure]         : undefined,
+    dependencies: entry.dependencies ? { ...entry.dependencies }    : undefined,
+    notes:        entry.notes        ? [...entry.notes]             : undefined,
+  };
+}
+
+module.exports = { KNOWN_LIBRARIES, lookupCookbook };