wyvrnpm 2.8.1 → 2.10.0

package/README.md

@@ -4,7 +4,7 @@ A simple, private C++ package manager that works with any static file hosting pr
 
 There is no central registry. You control where packages are hosted.
 
-> **README version: 2.8.1** — Highlights since 2.4.0: non-ABI build-time `conf` block (CMake cache variables via recipe / team profile / `wyvrn.local.json` / CLI `--conf`), per-package `source` pin for multi-source defense, profile inheritance via `extends`, pattern-based `settingsOverrides` (`boost*: {...}`), `wyvrnpm cache list` / `cache prune` for selective source-build-cache cleanup, `install --dry-run` (JSON plan without side effects), `install --build=always` to force source-rebuild, `--token-env` for CI credentials, and a raft of security hardening (Zip Slip, MSVC arch allow-list). Full list in `claude/EVALUATION.md`.
+> **README version: 2.8.3** — Highlights since 2.4.0: non-ABI build-time `conf` block (CMake cache variables via recipe / team profile / `wyvrn.local.json` / CLI `--conf`), per-package `source` pin for multi-source defense, profile inheritance via `extends`, pattern-based `settingsOverrides` (`boost*: {...}`), `wyvrnpm cache list` / `cache prune` for selective source-build-cache cleanup, `install --dry-run` (JSON plan without side effects), `install --build=always` to force source-rebuild, `--token-env` for CI credentials, CloudFront/WAF-compatible HTTP provider (sends `User-Agent`, surfaces non-404 errors), publish preserves dependency ranges verbatim with lock snapshot moved to informational `publishedLock`, and a raft of security hardening (Zip Slip, MSVC arch allow-list). Full list in `claude/EVALUATION.md`.
 
 ---
 
@@ -143,6 +143,62 @@ wyvrnpm init --root ./my-project
 
 ---
 
+### `wyvrnpm bootstrap`
+
+Scaffolds a first-draft `wyvrn.json` for an open-source C++ library so it can be packaged into your wyvrnpm registry with a single review pass instead of hand-writing a manifest from scratch. Clones the upstream git repo, detects `name` / `version` / `kind` from the checkout, applies known-library CMake flag hints (skip tests, skip examples, flip install gates), and prints a TODO report for everything a machine can't decide for you.
+
+Designed for batch-converting a list of forked upstreams (fmt, spdlog, zlib, Catch2, etc.) into your private registry.
+
+```bash
+# Typical single-repo conversion
+wyvrnpm bootstrap https://github.com/fmtlib/fmt.git --dest ./pkgs/fmt
+cd ./pkgs/fmt                           # review wyvrn.json, settle TODOs
+wyvrnpm install
+wyvrnpm build --install --all-configs
+wyvrnpm publish --source team-s3
+
+# Override the derived name / version / kind
+wyvrnpm bootstrap https://github.com/nlohmann/json.git \
+    --dest ./pkgs/nlohmann-json \
+    --name nlohmann-json \
+    --kind HeaderOnlyLib
+
+# Work on a directory you already cloned
+wyvrnpm bootstrap --no-clone --dest ./pkgs/fmt --force
+
+# Preview without writing — TODO report only
+wyvrnpm bootstrap https://github.com/google/re2.git --dest /tmp/re2 --dry-run
+
+# Batch driver — one shell loop, no wyvrnpm subcommand needed
+while read url; do
+  wyvrnpm bootstrap "$url" --dest "./pkgs/$(basename "$url" .git)" --force
+done < urls.txt
+# then review, build, and publish each in a loop of your own
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `<url>` positional | *(required)* | Upstream git URL. Accepts HTTPS or SSH form. |
+| `--dest <dir>` | `basename(url)` | Destination directory for the clone. |
+| `--ref <ref>` | *(remote HEAD)* | Clone at a specific branch / tag / SHA. |
+| `--name` | *(from URL)* | Override the derived package name. |
+| `--pkg-version` | *(nearest git tag)* | Override the version. Named oddly so yargs doesn't confuse it with the built-in `--version`. |
+| `--kind` | *(auto-detect)* | Force `ConsoleApp` / `StaticLib` / `DynamicLib` / `HeaderOnlyLib` / etc. |
+| `--description` | *(TODO placeholder)* | One-line description written into `wyvrn.json`. |
+| `--no-clone` | `false` | Skip the clone step; operate on an already-populated `--dest`. |
+| `--shallow` | `false` | `--depth 1` clone. Faster, but git tag detection degrades — pair with `--pkg-version` when using this. |
+| `--dry-run` | `false` | Print the proposed manifest + TODOs; don't write `wyvrn.json`. |
+| `--force` | `false` | Overwrite an existing destination and/or `wyvrn.json`. |
+| `--format` | `text` | Output format: `text` (human) or `json` (CI — one object on stdout). |
+
+The cookbook of per-library hints lives in [src/bootstrap/cookbook.js](src/bootstrap/cookbook.js). Current coverage is ~30 popular libraries (fmt, spdlog, nlohmann/json, yaml-cpp, zlib, Catch2, lz4, brotli, hiredis, redis-plus-plus, GLM, SQLiteCpp, re2, …). Adding a new entry is a two-line change — submit a PR.
+
+The patterns bootstrap detects (header-only with INTERFACE target, standard CMake static lib, CMake with wyvrnpm dep, ABI-option'd lib, non-CMake upstream) are catalogued in the bundled Agent Skill at [claude/skills/wyvrnpm/references/oss-conversion-patterns.md](claude/skills/wyvrnpm/references/oss-conversion-patterns.md) — Claude reads it when you ask "how do I convert X to a wyvrnpm package?".
+
+---
+
 ### `wyvrnpm add`
 
 Adds one or more dependencies to `wyvrn.json` without downloading them. Useful when you know the package name but not the latest version.
@@ -285,6 +341,13 @@ wyvrnpm build
 # Build Debug, verbose compiler output
 wyvrnpm build --config Debug --verbose
 
+# Build multiple configs in one go — configure runs once, build loops per config
+wyvrnpm build --config Debug,Release --install
+
+# Build every config the recipe declares (recipe's build.configs, or all four
+# canonical configs if no recipe is present). Pairs naturally with --install.
+wyvrnpm build --all-configs --install
+
 # Use a specific profile's preset
 wyvrnpm build --profile release
 
@@ -318,7 +381,8 @@ wyvrnpm build -- -j 8
 |---|---|---|
 | `--preset` / `-P` | `wyvrn-<profile>` | CMake configure preset name. |
 | `--profile` / `-p` | *(config / "default")* | Build profile — determines the default preset name. |
-| `--config` / `-c` | `Release` | Build configuration (`Debug` \| `Release` \| `RelWithDebInfo` \| `MinSizeRel`). |
+| `--config` / `-c` | `Release` | Build configuration (`Debug` \| `Release` \| `RelWithDebInfo` \| `MinSizeRel`). Comma-separated to build multiple in one invocation (e.g. `Debug,Release`) — configure runs once, build (+ `--install`) loops per config. |
+| `--all-configs` | `false` | Build every config from the recipe's `build.configs` (or all four canonical configs when no recipe is present). Takes precedence over `--config`. |
 | `--target` / `-t` | *(all)* | Specific CMake target to build. |
 | `--verbose` / `-v` | `false` | Pass `--verbose` to `cmake --build`. |
 | `--clean` | `false` | Remove the build directory before configuring. |
@@ -546,8 +610,6 @@ You only need this if you want Claude Code to pick up the skill. The CLI itself
 | `--force` | `false` | Overwrite an existing skill install. Without it, the command refuses to clobber. |
 | `--dry-run` | `false` | Print the destination paths and intended actions without writing. |
 
-**CLAUDE.md §9 note for contributors:** the tested path for deploying a locally-edited skill is `node scripts/repack-skill.js && node bin/wyvrn.js install-skill --claude --force` — never `rm -rf` + `cp -r`.
-
 ---
 
 ### `wyvrnpm link`
@@ -1736,6 +1798,15 @@ wyvrnpm build --install --install-prefix C:\out\stage
 
 # Install a specific config
 wyvrnpm build --install --config Debug
+
+# Install multiple configs in one invocation — configure runs once,
+# build + install loops per config. Before 2.9.0 this required two
+# separate `wyvrnpm build --install ...` invocations.
+wyvrnpm build --install --config Debug,Release
+
+# Install every config declared in the recipe's build.configs
+# (or all four canonical configs when no recipe is present).
+wyvrnpm build --install --all-configs
 ```
 
 ### What it does, in order

package/bin/wyvrn.js

@@ -14,6 +14,7 @@ const build        = require('../src/commands/build');
 const show         = require('../src/commands/show');
 const installSkill = require('../src/commands/install-skill');
 const cache        = require('../src/commands/cache');
+const bootstrap    = require('../src/commands/bootstrap');
 const { link, unlink } = require('../src/commands/link');
 
 yargs
@@ -37,6 +38,83 @@ yargs
     (argv) => init(argv),
   )
 
+  // ── bootstrap ─────────────────────────────────────────────────────────────
+  .command(
+    'bootstrap <url> [dest]',
+    'Scaffold a first-draft wyvrn.json for an OSS C++ library. Shallow-clones ' +
+    '(or reuses with --no-clone), detects name/version/kind, applies known-library ' +
+    'cookbook hints, and prints TODOs for gotchas worth a human look before publish. ' +
+    'Designed for batch-converting upstream repos to wyvrnpm packages.',
+    (y) => {
+      y
+        .positional('url', {
+          type: 'string',
+          describe: 'Upstream git URL (e.g. https://github.com/fmtlib/fmt.git)',
+        })
+        .positional('dest', {
+          type: 'string',
+          describe: 'Destination directory (default: basename(url))',
+        })
+        .option('dest', {
+          type: 'string',
+          description: 'Destination directory (alias for the positional).',
+        })
+        .option('ref', {
+          type: 'string',
+          description: 'Clone at this branch/tag/SHA (default: the remote HEAD).',
+        })
+        .option('name', {
+          type: 'string',
+          description: 'Override the derived package name.',
+        })
+        .option('pkg-version', {
+          type: 'string',
+          description: 'Override the wyvrnpm package version (otherwise: nearest git tag padded to 4 parts). Not named --version to avoid colliding with yargs\'s built-in --version flag.',
+        })
+        .option('shallow', {
+          type: 'boolean',
+          default: false,
+          description: 'Use a shallow (`--depth 1`) clone. Faster, but git tag detection degrades to a TODO — pass --pkg-version when combining with this.',
+        })
+        .option('kind', {
+          type: 'string',
+          choices: ['ConsoleApp', 'StaticLib', 'DynamicLib', 'HeaderOnlyLib', 'WebApp', 'Utility', 'Service', 'TestProject'],
+          description: 'Override the detected kind.',
+        })
+        .option('description', {
+          type: 'string',
+          description: 'One-line description written into the manifest.',
+        })
+        .option('no-clone', {
+          type: 'boolean',
+          default: false,
+          description: 'Skip cloning — operate on an existing directory at --dest.',
+        })
+        .option('dry-run', {
+          type: 'boolean',
+          default: false,
+          description: 'Print the proposed manifest + TODO report, do not write wyvrn.json.',
+        })
+        .option('force', {
+          type: 'boolean',
+          default: false,
+          description: 'Overwrite an existing destination or existing wyvrn.json.',
+        })
+        .option('format', {
+          type: 'string',
+          choices: ['text', 'json'],
+          default: 'text',
+          description: 'Output format for CI pipelines. `json` emits the manifest + TODOs as one JSON object on stdout.',
+        });
+    },
+    (argv) => bootstrap({
+      ...argv,
+      version: argv['pkg-version'],
+      noClone: argv['no-clone'],
+      dryRun:  argv['dry-run'],
+    }),
+  )
+
   // ── add ───────────────────────────────────────────────────────────────────
   .command(
     'add <packages...>',
@@ -191,9 +269,21 @@ yargs
         .option('config', {
           alias: 'c',
           type: 'string',
-          choices: ['Debug', 'Release', 'RelWithDebInfo', 'MinSizeRel'],
           default: 'Release',
-          description: 'Build configuration',
+          description:
+            'Build configuration. Accepts a single value (Release) or a ' +
+            'comma-separated list (Debug,Release) to build multiple configs ' +
+            'in one invocation — configure runs once, build (+ --install) ' +
+            'loops per config. Valid: Debug | Release | RelWithDebInfo | MinSizeRel.',
+        })
+        .option('all-configs', {
+          type: 'boolean',
+          default: false,
+          description:
+            'Build every config declared in the recipe\'s build.configs ' +
+            '(falls back to all four canonical configs when no recipe is ' +
+            'present). Equivalent to spelling out --config Debug,Release,... ' +
+            'by hand. Pairs naturally with --install.',
         })
         .option('target', {
           alias: 't',
@@ -262,6 +352,7 @@ yargs
       ...argv,
       autoInstall:   argv['auto-install'],
       installPrefix: argv['install-prefix'],
+      allConfigs:    argv['all-configs'],
     }),
   )
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wyvrnpm",
-  "version": "2.8.1",
+  "version": "2.10.0",
   "description": "A simple, static-hosting-compatible C++ package manager",
   "keywords": [
     "c++",

package/src/bootstrap/cookbook.js

@@ -0,0 +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 };

package/src/bootstrap/detect.js

@@ -0,0 +1,150 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+/**
+ * Inspect a cloned repo directory and infer the wyvrnpm `kind`, plus
+ * anything else a bootstrap flow can read off the filesystem cheaply.
+ *
+ * We explicitly do NOT fully parse CMakeLists.txt — a regex scan is good
+ * enough for the 80% case, and the bootstrap command's job is to produce
+ * a *first draft* that the human reviews before publish. When the signal
+ * is ambiguous we return `unknown` and let the TODO report surface it.
+ *
+ * @typedef {Object} DetectResult
+ * @property {'HeaderOnlyLib' | 'StaticLib' | 'DynamicLib' | 'unknown'} kind
+ * @property {boolean} hasCMakeLists       — root CMakeLists.txt present?
+ * @property {boolean} hasConfigureAc      — autotools (libsodium, bzip2)?
+ * @property {boolean} hasMeson            — meson.build present?
+ * @property {string[]} notes              — human-readable signals for the TODO report.
+ */
+
+/**
+ * @param {string} repoDir
+ * @returns {DetectResult}
+ */
+function detectFromRepo(repoDir) {
+  const notes = [];
+  const result = {
+    kind:             'unknown',
+    hasCMakeLists:    false,
+    hasConfigureAc:   false,
+    hasMeson:         false,
+    notes,
+  };
+
+  if (!fs.existsSync(repoDir) || !fs.statSync(repoDir).isDirectory()) {
+    notes.push(`directory does not exist: ${repoDir}`);
+    return result;
+  }
+
+  const cmakePath = path.join(repoDir, 'CMakeLists.txt');
+  result.hasCMakeLists  = fs.existsSync(cmakePath);
+  result.hasConfigureAc = fs.existsSync(path.join(repoDir, 'configure.ac'))
+                      || fs.existsSync(path.join(repoDir, 'configure'));
+  result.hasMeson       = fs.existsSync(path.join(repoDir, 'meson.build'));
+
+  if (!result.hasCMakeLists) {
+    if (result.hasConfigureAc) {
+      notes.push(
+        'no CMakeLists.txt — upstream uses autotools. wyvrnpm source-build ' +
+        'supports cmake only; ship a wrapper CMakeLists.txt in your fork or ' +
+        'prebuild and publish as a binary-only artefact.',
+      );
+    } else if (result.hasMeson) {
+      notes.push(
+        'no CMakeLists.txt — upstream uses meson. Same workaround as ' +
+        'autotools: ship a wrapper CMakeLists.txt in your fork.',
+      );
+    } else {
+      notes.push(
+        'no CMakeLists.txt and no recognised build system — likely a header-' +
+        'drop upstream (e.g. imgui, nuklear, stb). Add a small CMakeLists.txt ' +
+        'in the fork that declares an INTERFACE target + install() rules.',
+      );
+    }
+    return result;
+  }
+
+  const kindFromCmake = detectKindFromCMakeLists(cmakePath);
+  result.kind = kindFromCmake.kind;
+  if (kindFromCmake.note) notes.push(kindFromCmake.note);
+  return result;
+}
+
+/**
+ * Scan a CMakeLists.txt for the most specific `add_library(<name> <type>)`
+ * signal we can find. In order of preference we look for:
+ *   INTERFACE  → HeaderOnlyLib
+ *   SHARED     → DynamicLib
+ *   STATIC     → StaticLib
+ *   MODULE     → StaticLib  (rare; treat as static for now)
+ *
+ * If we find `add_library(<name>)` with no explicit type, CMake's default
+ * depends on `BUILD_SHARED_LIBS`. wyvrnpm's convention is to default to
+ * `StaticLib` — the consumer can flip via an `options.shared` toggle later.
+ *
+ * `add_executable(...)` with no `add_library(...)` → the repo ships only a
+ * tool, not a library. We return `unknown` so the TODO report surfaces it.
+ *
+ * @param {string} cmakePath
+ * @returns {{ kind: DetectResult['kind'], note?: string }}
+ */
+function detectKindFromCMakeLists(cmakePath) {
+  let text;
+  try { text = fs.readFileSync(cmakePath, 'utf8'); }
+  catch { return { kind: 'unknown', note: `could not read ${cmakePath}` }; }
+
+  // Strip line comments so an old "# add_library(foo SHARED ...)" doesn't
+  // poison detection. Block comments in CMake (#[[ ... ]]) are rare; not
+  // worth handling here.
+  const stripped = text.replace(/#[^\n]*/g, '');
+
+  const has = (re) => re.test(stripped);
+
+  // add_library(<name> [STATIC|SHARED|MODULE|OBJECT|INTERFACE|IMPORTED] ...)
+  if (has(/add_library\s*\(\s*[A-Za-z0-9_.+-]+\s+INTERFACE\b/i)) {
+    return { kind: 'HeaderOnlyLib' };
+  }
+  if (has(/add_library\s*\(\s*[A-Za-z0-9_.+-]+\s+SHARED\b/i)) {
+    return {
+      kind: 'DynamicLib',
+      note: 'detected SHARED library — consider declaring an `options.shared` toggle if the upstream respects BUILD_SHARED_LIBS.',
+    };
+  }
+  if (has(/add_library\s*\(\s*[A-Za-z0-9_.+-]+\s+STATIC\b/i)) {
+    return { kind: 'StaticLib' };
+  }
+  if (has(/add_library\s*\(\s*[A-Za-z0-9_.+-]+\s+(MODULE|OBJECT)\b/i)) {
+    return {
+      kind: 'StaticLib',
+      note: 'detected MODULE/OBJECT library — treating as StaticLib. Review.',
+    };
+  }
+  // Implicit-default form: `add_library(<name> <sources>...)` — no type
+  // keyword after the name. Negative lookahead on the recognised types
+  // distinguishes this from the explicit-type cases above (which we've
+  // already checked and returned from).
+  if (has(/add_library\s*\(\s*[A-Za-z0-9_.+-]+\s+(?!(STATIC|SHARED|MODULE|OBJECT|INTERFACE|IMPORTED)\b)/i)) {
+    return {
+      kind: 'StaticLib',
+      note: 'add_library() with no explicit type — defaulting to StaticLib. ' +
+            'If the upstream respects BUILD_SHARED_LIBS, add an `options.shared` toggle.',
+    };
+  }
+  if (has(/add_executable\s*\(/i)) {
+    return {
+      kind: 'unknown',
+      note: 'repo declares add_executable() but no add_library() — looks like ' +
+            'a tool, not a library. Set kind: ConsoleApp in the manifest.',
+    };
+  }
+  return {
+    kind: 'unknown',
+    note: 'no add_library() / add_executable() found at the root CMakeLists.txt. ' +
+          'The library may be declared in a subdirectory — inspect and set kind manually.',
+  };
+}
+
+module.exports = { detectFromRepo, detectKindFromCMakeLists };