wyvrnpm 2.9.0 → 2.10.0

package/README.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.

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...>',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wyvrnpm",
-  "version": "2.9.0",
+  "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 };

package/src/bootstrap/index.js

@@ -0,0 +1,220 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const { tagToVersion, nameFromUrl } = require('./version');
+const { detectFromRepo }            = require('./detect');
+const { lookupCookbook }            = require('./cookbook');
+const log                           = require('../logger');
+
+/**
+ * Clone `gitUrl` into `destDir` so bootstrap can read the tree.
+ * Defaults to a full clone — bootstrap's target audience is "I forked
+ * these repos to maintain them", so they want the history. `--shallow`
+ * opts into `--depth 1` (faster, but `git describe --tags` will miss
+ * tags that aren't reachable from the single fetched commit, so the
+ * version detection degrades to HEAD SHA placeholder + TODO).
+ *
+ * Uses the user's ambient git auth (SSH keys, credential helper). We do
+ * NOT manage credentials here.
+ *
+ * @param {{ gitUrl: string, destDir: string, ref?: string | null, shallow?: boolean }} opts
+ */
+function cloneRepo({ gitUrl, destDir, ref = null, shallow = false }) {
+  const args = ['clone'];
+  if (shallow) args.push('--depth', '1');
+  if (ref)     args.push('--branch', ref);
+  args.push('--', gitUrl, destDir);
+  log.info(`  git ${args.join(' ')}`);
+  execFileSync('git', args, { stdio: 'inherit' });
+}
+
+/**
+ * Read HEAD SHA + nearest tag out of an existing clone. Pure
+ * read-side — never writes. Returns nulls on failure so the caller
+ * can surface a TODO rather than abort.
+ *
+ * @param {string} repoDir
+ * @returns {{ sha: string | null, tag: string | null }}
+ */
+function readGitState(repoDir) {
+  const safe = (args) => {
+    try {
+      return execFileSync('git', args, { cwd: repoDir, stdio: ['ignore', 'pipe', 'ignore'] })
+        .toString('utf8').trim() || null;
+    } catch { return null; }
+  };
+  return {
+    sha: safe(['rev-parse', 'HEAD']),
+    // `--abbrev=0` gives the nearest tag without the "-<N>-g<sha>" suffix.
+    tag: safe(['describe', '--tags', '--abbrev=0']),
+  };
+}
+
+/**
+ * Compose a first-draft `wyvrn.json` from detection + cookbook data.
+ * Pure: no filesystem writes, no network. `compose` is the unit-testable
+ * seam between orchestration (`bootstrap`) and persistence.
+ *
+ * Precedence for each field (highest wins):
+ *   CLI override → cookbook hint → filesystem detection → safe default.
+ *
+ * @param {{
+ *   url:        string,
+ *   repoDir:    string,
+ *   overrides?: { name?: string, version?: string, kind?: string, description?: string },
+ *   detect?:    ReturnType<typeof detectFromRepo>,
+ *   gitState?:  { sha: string | null, tag: string | null },
+ * }} args
+ * @returns {{ manifest: object, todos: string[] }}
+ */
+function compose({ url, repoDir, overrides = {}, detect = null, gitState = null }) {
+  const todos = [];
+  const detection = detect ?? detectFromRepo(repoDir);
+  const { sha, tag } = gitState ?? { sha: null, tag: null };
+
+  const repoTail = nameFromUrl(url);
+  const cookbook = lookupCookbook(repoTail) ?? {};
+
+  const name = overrides.name || repoTail;
+  if (!name) todos.push('name could not be derived from the URL — set "name" manually.');
+
+  let version = overrides.version || null;
+  if (!version && tag) {
+    version = tagToVersion(tag);
+    if (!version) {
+      todos.push(`nearest tag "${tag}" doesn't match a clean numeric version — set "version" manually (used HEAD SHA as a placeholder).`);
+    }
+  }
+  if (!version) {
+    version = '0.0.0.0';
+    todos.push('no usable git tag found — "version" defaulted to 0.0.0.0. Pin to a real release before publish.');
+  }
+
+  const kind = overrides.kind || cookbook.kind || detection.kind;
+  if (kind === 'unknown') {
+    todos.push('kind could not be detected — set "kind" to ConsoleApp | StaticLib | DynamicLib | HeaderOnlyLib | WebApp | Utility | Service | TestProject.');
+  }
+  for (const note of detection.notes) todos.push(`detect: ${note}`);
+  for (const note of (cookbook.notes ?? [])) todos.push(`cookbook: ${note}`);
+
+  // Safe default recipe for any CMake project. Header-only still goes
+  // through cmake --install so the INTERFACE target + install() rules
+  // land in the published zip.
+  const build = {
+    system:    'cmake',
+    configs:   ['Debug', 'Release', 'RelWithDebInfo', 'MinSizeRel'],
+    configure: cookbook.configure ? [...cookbook.configure] : [],
+    installDir: 'install',
+  };
+
+  const manifest = {
+    name,
+    version,
+    schemaVersion: 2,
+    kind:          kind === 'unknown' ? 'StaticLib' : kind,
+    description:   overrides.description || `TODO: one-line description of ${name}`,
+    dependencies:  cookbook.dependencies ? { ...cookbook.dependencies } : {},
+    build,
+  };
+
+  if (cookbook.dependencies) {
+    todos.push(
+      `dependencies seeded from cookbook: ${Object.keys(cookbook.dependencies).join(', ')}. ` +
+      `Verify versions and pin ranges before publish.`,
+    );
+  }
+
+  // `gitRepo` / `gitSha` are normally captured by `wyvrnpm publish` at
+  // publish time — we leave them out of the manifest (not an author
+  // field) but surface them in the TODO report so the user can
+  // double-check the clone landed at the ref they expected.
+  if (sha) todos.push(`git HEAD at bootstrap: ${sha}`);
+  if (tag) todos.push(`nearest git tag: ${tag}`);
+
+  return { manifest, todos };
+}
+
+/**
+ * Full bootstrap flow: optionally clone, read git state, compose manifest,
+ * write it to disk. Returns the result so callers (CLI, tests) can decide
+ * what to print.
+ *
+ * @param {{
+ *   url:      string,
+ *   dest:     string,
+ *   ref?:     string | null,
+ *   name?:    string,
+ *   version?: string,
+ *   kind?:    string,
+ *   description?: string,
+ *   noClone?: boolean,
+ *   dryRun?:  boolean,
+ *   force?:   boolean,
+ * }} opts
+ * @returns {{ manifest: object, todos: string[], manifestPath: string, wrote: boolean }}
+ */
+function bootstrap(opts) {
+  const {
+    url, dest, ref = null,
+    name, version, kind, description,
+    noClone = false, dryRun = false, force = false, shallow = false,
+  } = opts;
+
+  if (!url && !noClone) throw new Error('bootstrap: --url (or a positional git URL) is required unless --no-clone');
+  if (!dest) throw new Error('bootstrap: --dest (or positional) is required');
+
+  const repoDir = path.resolve(dest);
+
+  if (!noClone) {
+    if (fs.existsSync(repoDir) && !force) {
+      throw new Error(
+        `bootstrap: destination already exists: ${repoDir}\n` +
+        '  Pass --force to reuse it, or --no-clone to operate on it in place.',
+      );
+    }
+    if (fs.existsSync(repoDir) && force) {
+      fs.rmSync(repoDir, { recursive: true, force: true });
+    }
+    cloneRepo({ gitUrl: url, destDir: repoDir, ref, shallow });
+  } else if (!fs.existsSync(repoDir)) {
+    throw new Error(`bootstrap: --no-clone but directory does not exist: ${repoDir}`);
+  }
+
+  const detect   = detectFromRepo(repoDir);
+  const gitState = readGitState(repoDir);
+
+  const { manifest, todos } = compose({
+    url:       url || gitRemoteUrl(repoDir) || '',
+    repoDir,
+    overrides: { name, version, kind, description },
+    detect,
+    gitState,
+  });
+
+  const manifestPath = path.join(repoDir, 'wyvrn.json');
+  let wrote = false;
+  if (!dryRun) {
+    if (fs.existsSync(manifestPath) && !force) {
+      throw new Error(
+        `bootstrap: ${manifestPath} already exists. Pass --force to overwrite, or --dry-run to preview only.`,
+      );
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    wrote = true;
+  }
+
+  return { manifest, todos, manifestPath, wrote };
+}
+
+function gitRemoteUrl(repoDir) {
+  try {
+    return execFileSync('git', ['remote', 'get-url', 'origin'], {
+      cwd: repoDir, stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString('utf8').trim() || null;
+  } catch { return null; }
+}
+
+module.exports = { bootstrap, compose, readGitState, cloneRepo };

package/src/bootstrap/version.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * Parse an upstream git tag into wyvrnpm's 4-part version scheme.
+ *
+ * Most C++ OSS projects publish 3-part semver tags (`v1.2.3`, `11.0.2`,
+ * `1.3.12`). wyvrnpm uses a 4-part `major.minor.patch.build` scheme
+ * throughout (see CLAUDE.md §4.2). We pad the upstream tag with `.0` for
+ * the build component so published manifests look like `1.3.12.0`.
+ *
+ * Accepted tag shapes:
+ *   v1.2.3      → "1.2.3.0"
+ *   1.2.3       → "1.2.3.0"
+ *   v1.2.3.4    → "1.2.3.4"
+ *   v11.0       → "11.0.0.0"  (2-part — padded)
+ *   v11         → "11.0.0.0"  (1-part — padded)
+ *   release-1.2 → "1.2.0.0"   (strips a leading "release-" / "ver-")
+ *
+ * Rejected (returns null):
+ *   empty / non-string
+ *   tags with suffixes ("1.2.3-rc1", "1.2.3+git", "1.2.3a") — callers
+ *     fall back to the HEAD SHA and flag a TODO
+ *   tags with 5+ numeric components
+ *
+ * @param {string | null} tag
+ * @returns {string | null} 4-part version, or null when the tag can't be
+ *                          cleanly promoted.
+ */
+function tagToVersion(tag) {
+  if (typeof tag !== 'string') return null;
+  let t = tag.trim();
+  if (!t) return null;
+
+  // Strip the most common prefixes authors use on git tags. Longest
+  // alternatives first so `version-2.0` matches the whole word, not
+  // just the leading `v`. We keep the allowlist tight — we'd rather
+  // fall through than silently misparse `release-candidate-1.2.3`.
+  t = t.replace(/^(version|release|ver|v)[-_.]?/i, '');
+
+  // Must be bare numeric segments separated by dots, nothing else.
+  if (!/^\d+(\.\d+){0,3}$/.test(t)) return null;
+
+  const parts = t.split('.').map((n) => parseInt(n, 10));
+  if (parts.some((n) => !Number.isFinite(n) || n < 0)) return null;
+
+  while (parts.length < 4) parts.push(0);
+  return parts.join('.');
+}
+
+/**
+ * Derive a wyvrnpm package name from a git URL.
+ *
+ *   https://github.com/fmtlib/fmt.git          → "fmt"
+ *   git@github.com:fmtlib/fmt.git              → "fmt"
+ *   https://gitlab.com/bzip2/bzip2.git         → "bzip2"
+ *   https://github.com/Tencent/rapidjson.git   → "rapidjson"
+ *   https://github.com/nlohmann/json.git       → "json"  (caller may want "nlohmann-json")
+ *
+ * Pure: does not hit the network.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+function nameFromUrl(url) {
+  if (typeof url !== 'string' || !url.trim()) return '';
+  const trimmed = url.trim().replace(/\/$/, '');
+  // Split on the last slash or colon (SSH form).
+  const tail = trimmed.split(/[/:]/).pop() || '';
+  return tail.replace(/\.git$/i, '');
+}
+
+module.exports = { tagToVersion, nameFromUrl };

package/src/commands/bootstrap.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const path = require('path');
+
+const { bootstrap } = require('../bootstrap');
+const { nameFromUrl } = require('../bootstrap/version');
+const log           = require('../logger');
+
+/**
+ * `wyvrnpm bootstrap <git-url>` — scaffold a first-draft `wyvrn.json`
+ * inside a cloned OSS repo so it can be built + published as a wyvrnpm
+ * package. See CLAUDE.md §5.9 and
+ * claude/skills/wyvrnpm/references/oss-conversion-patterns.md.
+ *
+ * Typical use — batch-convert a list of OSS libraries into wyvrnpm:
+ *
+ *   while read url; do
+ *     wyvrnpm bootstrap "$url" --dest "./pkgs/$(basename "$url" .git)"
+ *   done < urls.txt
+ *
+ * The output is always a *first draft* — bootstrap prints a TODO report
+ * flagging gotchas that need human review (install gates, test-skip
+ * flags upstream-specific, missing CMakeLists.txt on header-drop repos
+ * like stb/imgui). Always review before `wyvrnpm publish`.
+ *
+ * @param {object} argv
+ */
+async function bootstrapCmd(argv) {
+  const url = argv.url ?? argv._?.[1] ?? null;
+  if (!url && !argv.noClone) {
+    log.error('bootstrap: missing git URL.\n  Usage: wyvrnpm bootstrap <git-url> [--dest <dir>]');
+    process.exit(1);
+  }
+
+  const dest = argv.dest || path.resolve(nameFromUrl(url ?? '') || 'package');
+
+  let result;
+  try {
+    result = bootstrap({
+      url,
+      dest,
+      ref:         argv.ref,
+      name:        argv.name,
+      version:     argv.version,
+      kind:        argv.kind,
+      description: argv.description,
+      noClone:     Boolean(argv.noClone),
+      dryRun:      Boolean(argv.dryRun),
+      force:       Boolean(argv.force),
+    });
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
+  const { manifest, todos, manifestPath, wrote } = result;
+
+  if (argv.format === 'json') {
+    process.stdout.write(JSON.stringify({
+      command: 'bootstrap',
+      wyvrnpmVersion: require('../../package.json').version,
+      dest,
+      manifestPath,
+      wrote,
+      manifest,
+      todos,
+    }, null, 2) + '\n');
+    return;
+  }
+
+  console.log();
+  console.log(`─── ${manifest.name}@${manifest.version} (${manifest.kind}) ───`);
+  console.log(JSON.stringify(manifest, null, 2));
+  console.log();
+
+  if (wrote) log.success(`Wrote ${manifestPath}`);
+  else       log.info(`Dry run — no manifest written.`);
+
+  if (todos.length > 0) {
+    console.log();
+    console.log('TODOs — review before `wyvrnpm publish`:');
+    for (const t of todos) console.log(`  • ${t}`);
+  }
+
+  if (wrote) {
+    console.log();
+    console.log('Next steps:');
+    console.log(`  cd ${path.relative(process.cwd(), path.resolve(dest)) || '.'}`);
+    console.log('  wyvrnpm install');
+    console.log('  wyvrnpm build --install --all-configs');
+    console.log('  # review the install tree, then:');
+    console.log('  wyvrnpm publish --source <your-s3-publish-source>');
+  }
+}
+
+module.exports = bootstrapCmd;