wyvrnpm 2.10.2 → 2.12.2

package/src/build/recipe.js

@@ -1,188 +1,188 @@
-'use strict';
-
-const { substituteTemplateAll } = require('../options');
-const { readRecipeConf }        = require('../conf');
-
-/**
- * The `build` section of a source-repo `wyvrn.json` tells wyvrnpm how to
- * build the package from source when `--build=missing` fires. Only
- * `system: "cmake"` is supported in phase 3.
- *
- * Example — single generator (strict; CMake errors if Ninja isn't installed):
- *   "build": {
- *     "system":       "cmake",
- *     "generator":    "Ninja",
- *     "configure":    ["-DZLIB_BUILD_EXAMPLES=OFF"],
- *     "buildArgs":    ["--parallel"],
- *     "installDir":   "install",
- *     "sourceSubdir": "."
- *   }
- *
- * Example — generator fallback chain (tried in order, first available wins;
- *           falls through to CMake's default if none are present):
- *   "build": {
- *     "generator": ["Ninja", "Visual Studio 17 2022", "Visual Studio 16 2019"]
- *   }
- */
-
-const DEFAULT_RECIPE = Object.freeze({
-  system:        'cmake',
-  // Null / empty array → let CMake pick its default
-  // (Visual Studio on Windows with VS installed, Unix Makefiles on Linux/macOS).
-  generators:    Object.freeze([]),
-  // All four CMake configurations are built and installed by default so
-  // downstream consumers can link against whichever they need. Restrict via
-  // the recipe (e.g. `"configs": ["Release"]`) to cut source-build time.
-  configs:       Object.freeze(['Debug', 'Release', 'RelWithDebInfo', 'MinSizeRel']),
-  configure:     Object.freeze([]),
-  buildArgs:     Object.freeze([]),
-  installDir:    'install',                 // relative to binary dir; becomes CMAKE_INSTALL_PREFIX
-  sourceSubdir:  '.',                       // where CMakeLists.txt lives relative to the clone root
-  requiredTools: Object.freeze([]),
-});
-
-const VALID_CMAKE_CONFIGS = new Set(['Debug', 'Release', 'RelWithDebInfo', 'MinSizeRel']);
-
-const SUPPORTED_SYSTEMS = new Set(['cmake']);
-
-/**
- * Normalise the `build` section of a manifest into a concrete, complete
- * recipe. Missing fields fall back to `DEFAULT_RECIPE`.
- *
- * `generator` accepts either a string (strict — single generator) or an
- * array of strings (fallback chain — tried in order; first available wins).
- * Both forms produce a `generators: string[]` field in the normalised recipe.
- *
- * When `effectiveOptions` is supplied, `${options.<name>}` tokens inside
- * `configure` and `buildArgs` are expanded using those values — bool → ON/OFF,
- * strings verbatim. An unknown option in a template is a hard error (fail
- * fast so the bad arg never reaches cmake). See src/options.js
- * `substituteTemplate`. When `effectiveOptions` is null (recipe declares
- * no options), any `${options.*}` token in the recipe also fails fast —
- * recipes don't get to reference undeclared options.
- *
- * When `manifestForConfCollisionCheck` is supplied, PLAN-CONF.md §4.7's
- * collision detection runs: any `-DKEY=...` in `build.configure` whose
- * KEY is ALSO declared in recipe-level `conf.cmake.cache` is a hard
- * error. Recipes pick ONE route, avoiding silent duplication.
- *
- * @param {object|null|undefined} rawBuild
- * @param {Record<string, any>|null} [effectiveOptions]
- * @param {object|null} [manifestForConfCollisionCheck]
- * @returns {{ system: string, generators: string[], configure: string[],
- *            buildArgs: string[], installDir: string, sourceSubdir: string,
- *            requiredTools: string[] }}
- * @throws {Error} when `system` is set but not supported, when a
- *                 `${options.<name>}` template references an undeclared option,
- *                 or when `build.configure` collides with `conf.cmake.cache`.
- */
-function normalizeRecipe(rawBuild, effectiveOptions = null, manifestForConfCollisionCheck = null) {
-  const b = rawBuild ?? {};
-  const system = b.system ?? DEFAULT_RECIPE.system;
-  if (!SUPPORTED_SYSTEMS.has(system)) {
-    throw new Error(
-      `build.system "${system}" is not supported. ` +
-      `Supported: ${[...SUPPORTED_SYSTEMS].join(', ')}.`,
-    );
-  }
-
-  // Accept generator as string | string[] | null for user convenience;
-  // canonicalise to an array.
-  let generators;
-  if (typeof b.generator === 'string') {
-    generators = b.generator.trim() ? [b.generator] : [];
-  } else if (Array.isArray(b.generator)) {
-    generators = b.generator.filter((g) => typeof g === 'string' && g.trim());
-  } else {
-    generators = [];
-  }
-
-  // Drop empty-string entries so a stray `""` in the user's JSON doesn't
-  // become an empty-string argument to CMake / the build tool.
-  const cleanArray = (arr) =>
-    Array.isArray(arr)
-      ? arr.filter((s) => typeof s === 'string' && s.trim().length > 0)
-      : [];
-
-  // Accept `configs` as string | string[]. Default to all four canonical
-  // CMake configurations. Unknown entries are silently dropped so a typo
-  // doesn't blow up the build loop.
-  let configs;
-  if (typeof b.configs === 'string') {
-    configs = [b.configs];
-  } else if (Array.isArray(b.configs)) {
-    configs = b.configs.filter((c) => typeof c === 'string' && c.trim());
-  } else {
-    configs = DEFAULT_RECIPE.configs.slice();
-  }
-  configs = configs.filter((c) => VALID_CMAKE_CONFIGS.has(c));
-  if (configs.length === 0) configs = DEFAULT_RECIPE.configs.slice();
-
-  // Expand ${options.<name>} tokens in args the recipe passes to cmake.
-  // Only `configure` and `buildArgs` are user-authored arg lists; the
-  // other fields are literals.
-  const configure = substituteTemplateAll(
-    cleanArray(b.configure),
-    effectiveOptions,
-    'build.configure',
-  );
-  const buildArgs = substituteTemplateAll(
-    cleanArray(b.buildArgs),
-    effectiveOptions,
-    'build.buildArgs',
-  );
-
-  // PLAN-CONF.md §4.7: recipe-side collision between `build.configure`
-  // `-DKEY=...` args and declared `conf.cmake.cache.KEY` is a hard
-  // error. Forces the author to pick one route; avoids silent
-  // duplication where one route wins opaquely.
-  if (manifestForConfCollisionCheck) {
-    const recipeConfFlat = readRecipeConf(manifestForConfCollisionCheck);
-    const confCacheKeys = new Set(
-      Object.keys(recipeConfFlat)
-        .filter((k) => k.startsWith('cmake.cache.'))
-        .map((k) => k.slice('cmake.cache.'.length)),
-    );
-    if (confCacheKeys.size > 0) {
-      for (const arg of configure) {
-        const m = arg.match(/^-D([^=]+)=/);
-        if (m && confCacheKeys.has(m[1])) {
-          throw new Error(
-            `recipe collision: "${m[1]}" is set in both ` +
-            `build.configure (as ${JSON.stringify(arg)}) and ` +
-            `conf.cmake.cache. Pick one route — see claude/PLAN-CONF.md §4.7.`,
-          );
-        }
-      }
-    }
-  }
-
-  return {
-    system,
-    generators,
-    configs,
-    configure,
-    buildArgs,
-    installDir:    b.installDir    ?? DEFAULT_RECIPE.installDir,
-    sourceSubdir:  b.sourceSubdir  ?? DEFAULT_RECIPE.sourceSubdir,
-    requiredTools: cleanArray(b.requiredTools),
-  };
-}
-
-/**
- * Returns true if a manifest has enough info for source-build — i.e. the
- * `build` section is present (even empty — defaults cover the rest).
- * @param {object} manifest
- * @returns {boolean}
- */
-function hasBuildRecipe(manifest) {
-  return !!manifest && typeof manifest.build === 'object' && manifest.build !== null;
-}
-
-module.exports = {
-  normalizeRecipe,
-  hasBuildRecipe,
-  DEFAULT_RECIPE,
-  SUPPORTED_SYSTEMS,
-  VALID_CMAKE_CONFIGS,
-};
+'use strict';
+
+const { substituteTemplateAll } = require('../options');
+const { readRecipeConf }        = require('../conf');
+
+/**
+ * The `build` section of a source-repo `wyvrn.json` tells wyvrnpm how to
+ * build the package from source when `--build=missing` fires. Only
+ * `system: "cmake"` is supported in phase 3.
+ *
+ * Example — single generator (strict; CMake errors if Ninja isn't installed):
+ *   "build": {
+ *     "system":       "cmake",
+ *     "generator":    "Ninja",
+ *     "configure":    ["-DZLIB_BUILD_EXAMPLES=OFF"],
+ *     "buildArgs":    ["--parallel"],
+ *     "installDir":   "install",
+ *     "sourceSubdir": "."
+ *   }
+ *
+ * Example — generator fallback chain (tried in order, first available wins;
+ *           falls through to CMake's default if none are present):
+ *   "build": {
+ *     "generator": ["Ninja", "Visual Studio 17 2022", "Visual Studio 16 2019"]
+ *   }
+ */
+
+const DEFAULT_RECIPE = Object.freeze({
+  system:        'cmake',
+  // Null / empty array → let CMake pick its default
+  // (Visual Studio on Windows with VS installed, Unix Makefiles on Linux/macOS).
+  generators:    Object.freeze([]),
+  // All four CMake configurations are built and installed by default so
+  // downstream consumers can link against whichever they need. Restrict via
+  // the recipe (e.g. `"configs": ["Release"]`) to cut source-build time.
+  configs:       Object.freeze(['Debug', 'Release', 'RelWithDebInfo', 'MinSizeRel']),
+  configure:     Object.freeze([]),
+  buildArgs:     Object.freeze([]),
+  installDir:    'install',                 // relative to binary dir; becomes CMAKE_INSTALL_PREFIX
+  sourceSubdir:  '.',                       // where CMakeLists.txt lives relative to the clone root
+  requiredTools: Object.freeze([]),
+});
+
+const VALID_CMAKE_CONFIGS = new Set(['Debug', 'Release', 'RelWithDebInfo', 'MinSizeRel']);
+
+const SUPPORTED_SYSTEMS = new Set(['cmake']);
+
+/**
+ * Normalise the `build` section of a manifest into a concrete, complete
+ * recipe. Missing fields fall back to `DEFAULT_RECIPE`.
+ *
+ * `generator` accepts either a string (strict — single generator) or an
+ * array of strings (fallback chain — tried in order; first available wins).
+ * Both forms produce a `generators: string[]` field in the normalised recipe.
+ *
+ * When `effectiveOptions` is supplied, `${options.<name>}` tokens inside
+ * `configure` and `buildArgs` are expanded using those values — bool → ON/OFF,
+ * strings verbatim. An unknown option in a template is a hard error (fail
+ * fast so the bad arg never reaches cmake). See src/options.js
+ * `substituteTemplate`. When `effectiveOptions` is null (recipe declares
+ * no options), any `${options.*}` token in the recipe also fails fast —
+ * recipes don't get to reference undeclared options.
+ *
+ * When `manifestForConfCollisionCheck` is supplied, PLAN-CONF.md §4.7's
+ * collision detection runs: any `-DKEY=...` in `build.configure` whose
+ * KEY is ALSO declared in recipe-level `conf.cmake.cache` is a hard
+ * error. Recipes pick ONE route, avoiding silent duplication.
+ *
+ * @param {object|null|undefined} rawBuild
+ * @param {Record<string, any>|null} [effectiveOptions]
+ * @param {object|null} [manifestForConfCollisionCheck]
+ * @returns {{ system: string, generators: string[], configure: string[],
+ *            buildArgs: string[], installDir: string, sourceSubdir: string,
+ *            requiredTools: string[] }}
+ * @throws {Error} when `system` is set but not supported, when a
+ *                 `${options.<name>}` template references an undeclared option,
+ *                 or when `build.configure` collides with `conf.cmake.cache`.
+ */
+function normalizeRecipe(rawBuild, effectiveOptions = null, manifestForConfCollisionCheck = null) {
+  const b = rawBuild ?? {};
+  const system = b.system ?? DEFAULT_RECIPE.system;
+  if (!SUPPORTED_SYSTEMS.has(system)) {
+    throw new Error(
+      `build.system "${system}" is not supported. ` +
+      `Supported: ${[...SUPPORTED_SYSTEMS].join(', ')}.`,
+    );
+  }
+
+  // Accept generator as string | string[] | null for user convenience;
+  // canonicalise to an array.
+  let generators;
+  if (typeof b.generator === 'string') {
+    generators = b.generator.trim() ? [b.generator] : [];
+  } else if (Array.isArray(b.generator)) {
+    generators = b.generator.filter((g) => typeof g === 'string' && g.trim());
+  } else {
+    generators = [];
+  }
+
+  // Drop empty-string entries so a stray `""` in the user's JSON doesn't
+  // become an empty-string argument to CMake / the build tool.
+  const cleanArray = (arr) =>
+    Array.isArray(arr)
+      ? arr.filter((s) => typeof s === 'string' && s.trim().length > 0)
+      : [];
+
+  // Accept `configs` as string | string[]. Default to all four canonical
+  // CMake configurations. Unknown entries are silently dropped so a typo
+  // doesn't blow up the build loop.
+  let configs;
+  if (typeof b.configs === 'string') {
+    configs = [b.configs];
+  } else if (Array.isArray(b.configs)) {
+    configs = b.configs.filter((c) => typeof c === 'string' && c.trim());
+  } else {
+    configs = DEFAULT_RECIPE.configs.slice();
+  }
+  configs = configs.filter((c) => VALID_CMAKE_CONFIGS.has(c));
+  if (configs.length === 0) configs = DEFAULT_RECIPE.configs.slice();
+
+  // Expand ${options.<name>} tokens in args the recipe passes to cmake.
+  // Only `configure` and `buildArgs` are user-authored arg lists; the
+  // other fields are literals.
+  const configure = substituteTemplateAll(
+    cleanArray(b.configure),
+    effectiveOptions,
+    'build.configure',
+  );
+  const buildArgs = substituteTemplateAll(
+    cleanArray(b.buildArgs),
+    effectiveOptions,
+    'build.buildArgs',
+  );
+
+  // PLAN-CONF.md §4.7: recipe-side collision between `build.configure`
+  // `-DKEY=...` args and declared `conf.cmake.cache.KEY` is a hard
+  // error. Forces the author to pick one route; avoids silent
+  // duplication where one route wins opaquely.
+  if (manifestForConfCollisionCheck) {
+    const recipeConfFlat = readRecipeConf(manifestForConfCollisionCheck);
+    const confCacheKeys = new Set(
+      Object.keys(recipeConfFlat)
+        .filter((k) => k.startsWith('cmake.cache.'))
+        .map((k) => k.slice('cmake.cache.'.length)),
+    );
+    if (confCacheKeys.size > 0) {
+      for (const arg of configure) {
+        const m = arg.match(/^-D([^=]+)=/);
+        if (m && confCacheKeys.has(m[1])) {
+          throw new Error(
+            `recipe collision: "${m[1]}" is set in both ` +
+            `build.configure (as ${JSON.stringify(arg)}) and ` +
+            `conf.cmake.cache. Pick one route — see claude/PLAN-CONF.md §4.7.`,
+          );
+        }
+      }
+    }
+  }
+
+  return {
+    system,
+    generators,
+    configs,
+    configure,
+    buildArgs,
+    installDir:    b.installDir    ?? DEFAULT_RECIPE.installDir,
+    sourceSubdir:  b.sourceSubdir  ?? DEFAULT_RECIPE.sourceSubdir,
+    requiredTools: cleanArray(b.requiredTools),
+  };
+}
+
+/**
+ * Returns true if a manifest has enough info for source-build — i.e. the
+ * `build` section is present (even empty — defaults cover the rest).
+ * @param {object} manifest
+ * @returns {boolean}
+ */
+function hasBuildRecipe(manifest) {
+  return !!manifest && typeof manifest.build === 'object' && manifest.build !== null;
+}
+
+module.exports = {
+  normalizeRecipe,
+  hasBuildRecipe,
+  DEFAULT_RECIPE,
+  SUPPORTED_SYSTEMS,
+  VALID_CMAKE_CONFIGS,
+};

package/src/commands/add.js

@@ -1,141 +1,141 @@
-'use strict';
-
-const path = require('path');
-
-const { readManifest, writeManifest } = require('../manifest');
-const { resolveLatestVersion }        = require('../resolve');
-const { readConfig }                  = require('../config');
-const { wyvrnFetch }                  = require('../http-fetch');
-const log                             = require('../logger');
-
-/**
- * Parse a `<name>[@<version>]` positional into its parts.
- *
- * `@` inside the version (e.g. tags like `latest`) is allowed — only the
- * first `@` is treated as the separator.
- *
- * @param {string} spec
- * @returns {{ name: string, version: string | null }}
- */
-function parseSpec(spec) {
-  const at = spec.indexOf('@');
-  if (at === -1)  return { name: spec, version: null };
-  if (at === 0)   throw new Error(`invalid package spec "${spec}" — missing name before "@"`);
-  const name    = spec.slice(0, at);
-  const version = spec.slice(at + 1);
-  if (!version) throw new Error(`invalid package spec "${spec}" — missing version after "@"`);
-  return { name, version };
-}
-
-/**
- * Add one or more dependencies to wyvrn.json.
- *
- *   wyvrnpm add <name>              → resolves latest, writes "^<latest>"
- *   wyvrnpm add <name>@<version>    → writes "<version>" verbatim (exact or range)
- *
- * Existing entries are replaced. If the prior entry was an object
- * (`{ version, settings, options }`), its settings/options are preserved —
- * only `version` is updated.
- *
- * Does not run install. The user must `wyvrnpm install` afterwards.
- *
- * @param {object} argv
- */
-async function add(argv) {
-  const manifestPath = path.resolve(argv.manifest);
-  const specs = (argv.packages ?? []).map(parseSpec);
-
-  if (specs.length === 0) {
-    log.error('no packages given. Usage: wyvrnpm add <name>[@<version>] [...]');
-    process.exit(1);
-  }
-
-  // Install sources — only needed when at least one spec omits @version and
-  // we have to hit `latest.json`.
-  let packageSources;
-  if (argv.source && argv.source.length > 0) {
-    packageSources = argv.source;
-  } else {
-    const config   = readConfig();
-    packageSources = config.installSources.map((s) => s.url);
-  }
-
-  const needsResolve = specs.some((s) => s.version === null);
-  if (needsResolve && packageSources.length === 0) {
-    log.error(
-      'no install sources configured — cannot look up latest versions.\n' +
-      '  Pass --source <url>, pin versions explicitly (`name@1.2.3.4`), or run:\n' +
-      '    wyvrnpm configure add-source --kind install --name ... --url ...',
-    );
-    process.exit(1);
-  }
-
-  const manifest = readManifest(manifestPath);
-
-  // Preserve whichever dependencies key the manifest already uses. If neither
-  // exists, create lowercase `dependencies` (the v2 convention).
-  const depsKey =
-    Object.prototype.hasOwnProperty.call(manifest, 'dependencies') ? 'dependencies' :
-    Object.prototype.hasOwnProperty.call(manifest, 'Dependencies') ? 'Dependencies' :
-    'dependencies';
-
-  let deps = manifest[depsKey];
-  // Legacy array form → object. Editing by name is the whole point of `add`,
-  // and round-tripping as an array would silently drop per-dep settings.
-  if (Array.isArray(deps)) {
-    const obj = {};
-    for (const d of deps) {
-      const n = d.Name ?? d.name;
-      const v = d.Version ?? d.version;
-      if (n && v) obj[n] = v;
-    }
-    deps = obj;
-  } else if (!deps || typeof deps !== 'object') {
-    deps = {};
-  }
-
-  for (const spec of specs) {
-    let versionToWrite;
-    if (spec.version) {
-      versionToWrite = spec.version;
-      log.info(`${spec.name}: writing "${versionToWrite}" (as given)`);
-    } else {
-      const latest = await resolveLatestVersion(spec.name, packageSources, argv.platform, wyvrnFetch);
-      versionToWrite = `^${latest}`;
-      log.info(`${spec.name}: latest is ${latest} → writing "${versionToWrite}"`);
-    }
-
-    const prior = deps[spec.name];
-    if (prior !== undefined) {
-      const priorVer =
-        typeof prior === 'string' ? prior :
-        (prior && typeof prior === 'object') ? (prior.version ?? prior.Version ?? '(unknown)') :
-        '(unknown)';
-      log.info(`  replacing existing entry: "${priorVer}"`);
-    }
-
-    // If the prior entry was an object with settings/options, keep those —
-    // only bump the version field. Otherwise write the short-form string.
-    if (prior && typeof prior === 'object' && !Array.isArray(prior)) {
-      const updated = { ...prior };
-      if ('Version' in updated && !('version' in updated)) {
-        updated.Version = versionToWrite;
-      } else {
-        updated.version = versionToWrite;
-      }
-      deps[spec.name] = updated;
-    } else {
-      deps[spec.name] = versionToWrite;
-    }
-  }
-
-  manifest[depsKey] = deps;
-  writeManifest(manifestPath, manifest);
-
-  const n = specs.length;
-  log.success(`Updated ${manifestPath} — ${n} package${n !== 1 ? 's' : ''}.`);
-  log.info('Run `wyvrnpm install` to download.');
-}
-
-module.exports = add;
-module.exports.parseSpec = parseSpec;
+'use strict';
+
+const path = require('path');
+
+const { readManifest, writeManifest } = require('../manifest');
+const { resolveLatestVersion }        = require('../resolve');
+const { readConfig }                  = require('../config');
+const { wyvrnFetch }                  = require('../http-fetch');
+const log                             = require('../logger');
+
+/**
+ * Parse a `<name>[@<version>]` positional into its parts.
+ *
+ * `@` inside the version (e.g. tags like `latest`) is allowed — only the
+ * first `@` is treated as the separator.
+ *
+ * @param {string} spec
+ * @returns {{ name: string, version: string | null }}
+ */
+function parseSpec(spec) {
+  const at = spec.indexOf('@');
+  if (at === -1)  return { name: spec, version: null };
+  if (at === 0)   throw new Error(`invalid package spec "${spec}" — missing name before "@"`);
+  const name    = spec.slice(0, at);
+  const version = spec.slice(at + 1);
+  if (!version) throw new Error(`invalid package spec "${spec}" — missing version after "@"`);
+  return { name, version };
+}
+
+/**
+ * Add one or more dependencies to wyvrn.json.
+ *
+ *   wyvrnpm add <name>              → resolves latest, writes "^<latest>"
+ *   wyvrnpm add <name>@<version>    → writes "<version>" verbatim (exact or range)
+ *
+ * Existing entries are replaced. If the prior entry was an object
+ * (`{ version, settings, options }`), its settings/options are preserved —
+ * only `version` is updated.
+ *
+ * Does not run install. The user must `wyvrnpm install` afterwards.
+ *
+ * @param {object} argv
+ */
+async function add(argv) {
+  const manifestPath = path.resolve(argv.manifest);
+  const specs = (argv.packages ?? []).map(parseSpec);
+
+  if (specs.length === 0) {
+    log.error('no packages given. Usage: wyvrnpm add <name>[@<version>] [...]');
+    process.exit(1);
+  }
+
+  // Install sources — only needed when at least one spec omits @version and
+  // we have to hit `latest.json`.
+  let packageSources;
+  if (argv.source && argv.source.length > 0) {
+    packageSources = argv.source;
+  } else {
+    const config   = readConfig();
+    packageSources = config.installSources.map((s) => s.url);
+  }
+
+  const needsResolve = specs.some((s) => s.version === null);
+  if (needsResolve && packageSources.length === 0) {
+    log.error(
+      'no install sources configured — cannot look up latest versions.\n' +
+      '  Pass --source <url>, pin versions explicitly (`name@1.2.3.4`), or run:\n' +
+      '    wyvrnpm configure add-source --kind install --name ... --url ...',
+    );
+    process.exit(1);
+  }
+
+  const manifest = readManifest(manifestPath);
+
+  // Preserve whichever dependencies key the manifest already uses. If neither
+  // exists, create lowercase `dependencies` (the v2 convention).
+  const depsKey =
+    Object.prototype.hasOwnProperty.call(manifest, 'dependencies') ? 'dependencies' :
+    Object.prototype.hasOwnProperty.call(manifest, 'Dependencies') ? 'Dependencies' :
+    'dependencies';
+
+  let deps = manifest[depsKey];
+  // Legacy array form → object. Editing by name is the whole point of `add`,
+  // and round-tripping as an array would silently drop per-dep settings.
+  if (Array.isArray(deps)) {
+    const obj = {};
+    for (const d of deps) {
+      const n = d.Name ?? d.name;
+      const v = d.Version ?? d.version;
+      if (n && v) obj[n] = v;
+    }
+    deps = obj;
+  } else if (!deps || typeof deps !== 'object') {
+    deps = {};
+  }
+
+  for (const spec of specs) {
+    let versionToWrite;
+    if (spec.version) {
+      versionToWrite = spec.version;
+      log.info(`${spec.name}: writing "${versionToWrite}" (as given)`);
+    } else {
+      const latest = await resolveLatestVersion(spec.name, packageSources, argv.platform, wyvrnFetch);
+      versionToWrite = `^${latest}`;
+      log.info(`${spec.name}: latest is ${latest} → writing "${versionToWrite}"`);
+    }
+
+    const prior = deps[spec.name];
+    if (prior !== undefined) {
+      const priorVer =
+        typeof prior === 'string' ? prior :
+        (prior && typeof prior === 'object') ? (prior.version ?? prior.Version ?? '(unknown)') :
+        '(unknown)';
+      log.info(`  replacing existing entry: "${priorVer}"`);
+    }
+
+    // If the prior entry was an object with settings/options, keep those —
+    // only bump the version field. Otherwise write the short-form string.
+    if (prior && typeof prior === 'object' && !Array.isArray(prior)) {
+      const updated = { ...prior };
+      if ('Version' in updated && !('version' in updated)) {
+        updated.Version = versionToWrite;
+      } else {
+        updated.version = versionToWrite;
+      }
+      deps[spec.name] = updated;
+    } else {
+      deps[spec.name] = versionToWrite;
+    }
+  }
+
+  manifest[depsKey] = deps;
+  writeManifest(manifestPath, manifest);
+
+  const n = specs.length;
+  log.success(`Updated ${manifestPath} — ${n} package${n !== 1 ? 's' : ''}.`);
+  log.info('Run `wyvrnpm install` to download.');
+}
+
+module.exports = add;
+module.exports.parseSpec = parseSpec;