@gjsify/cli 0.3.21 → 0.4.3

package/lib/utils/install-backend-native.js

@@ -5,17 +5,23 @@
 // node_modules/ via @gjsify/tar. Output layout matches `npm install` so the
 // existing `runGjsBundle()` prebuild detection works without branching.
 //
-// Out of scope (deferred to Phase 4): lockfile, peerDependencies validation,
+// Phase D.7b — version-conflict resolution via nested `node_modules`.
+// The resolver tracks per-package placement: a dep is hoisted to the
+// root when no conflict exists, nested under the requesting package
+// when its required version is incompatible with what's already at
+// the root. Mirrors npm v3+ behavior.
+//
+// Out of scope (still deferred): peerDependencies validation,
 // lifecycle scripts, git/file specs.
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import { Range, SemVer, maxSatisfying, } from "@gjsify/semver";
+import { Range, SemVer, maxSatisfying, satisfies, } from "@gjsify/semver";
 import { DEFAULT_REGISTRY, fetchPackument, fetchTarball, parseNpmrc, } from "@gjsify/npm-registry";
 import { extractTarball } from "@gjsify/tar";
 const DEFAULT_CONCURRENCY = Number(process.env.GJSIFY_INSTALL_CONCURRENCY ?? "8") || 8;
 const LOCKFILE_NAME = "gjsify-lock.json";
-const LOCKFILE_VERSION = 1;
+const LOCKFILE_VERSION = 2;
 export async function installPackagesNative(opts) {
     if (opts.specs.length === 0) {
         throw new Error("installPackagesNative: empty specs list");
@@ -26,14 +32,29 @@ export async function installPackagesNative(opts) {
     const lockfilePath = path.join(opts.prefix, LOCKFILE_NAME);
     const existingLock = readLockfile(lockfilePath);
     let nodes;
-    if (existingLock && (opts.frozen || lockfileMatchesRequest(existingLock, opts.specs))) {
+    if (opts.frozen) {
+        // --immutable / --frozen: lockfile is the authoritative source.
+        // Reject if the file is missing, version-mismatched, or its
+        // `requested` set has drifted from the live request — silently
+        // honoring a stale lockfile would mask real dep churn (the original
+        // bug --immutable exists to catch).
+        if (!existingLock) {
+            throw new Error(`install: --immutable requires ${LOCKFILE_NAME} at ${opts.prefix} — none found. ` +
+                `Run \`gjsify install\` (without --immutable) to generate one and commit it.`);
+        }
+        const drift = describeLockfileDrift(existingLock, opts.specs);
+        if (drift) {
+            throw new Error(`install: --immutable but ${lockfilePath} is stale.\n${drift}\n` +
+                `Re-run \`gjsify install\` (without --immutable) to refresh the lockfile.`);
+        }
+        log("install: --immutable, using lockfile (%d package(s))", Object.keys(existingLock.packages).length);
+        nodes = lockfileToNodes(existingLock);
+    }
+    else if (existingLock && lockfileMatchesRequest(existingLock, opts.specs)) {
         log("install: using lockfile (%d package(s))", Object.keys(existingLock.packages).length);
         nodes = lockfileToNodes(existingLock);
     }
     else {
-        if (opts.frozen) {
-            throw new Error(`install: --frozen requested but ${lockfilePath} is missing or stale (specs differ)`);
-        }
         log("install: resolving %d top-level spec(s) → %s", opts.specs.length, opts.prefix);
         nodes = await resolveDeps(opts.specs, npmrc, log);
         if (opts.lockfile) {
@@ -45,7 +66,54 @@ export async function installPackagesNative(opts) {
     await downloadAndExtractAll(nodes, opts.prefix, npmrc, log);
     await linkBins(nodes, opts.prefix, log);
     log("install: done");
+    // Surface the top-level requested packages so callers can update
+    // package.json with the resolved version (mirrors `npm install --save`
+    // behavior). Sub-deps are not included.
+    return topLevelResolutions(opts.specs, nodes);
+}
+function topLevelResolutions(specs, nodes) {
+    // Top-level installs live at `node_modules/<name>` (no nesting). Build
+    // a name → root-node lookup limited to the top-level set.
+    const byName = new Map();
+    for (const n of nodes) {
+        if (n.installPath === `node_modules/${n.name}`)
+            byName.set(n.name, n);
+    }
+    const out = [];
+    for (const spec of specs) {
+        const name = parseSpecName(spec);
+        const node = byName.get(name);
+        if (node)
+            out.push({ name: node.name, version: node.version });
+    }
+    return out;
+}
+function parseSpecName(spec) {
+    if (spec.startsWith("@")) {
+        const slash = spec.indexOf("/");
+        if (slash === -1)
+            return spec;
+        const at = spec.indexOf("@", slash + 1);
+        return at === -1 ? spec : spec.slice(0, at);
+    }
+    const at = spec.indexOf("@");
+    return at === -1 ? spec : spec.slice(0, at);
 }
+/**
+ * Tree-aware dependency resolution with npm v3+ hoisting semantics.
+ *
+ *   - A dep is HOISTED (placed at `node_modules/<dep>`) when no existing
+ *     placement conflicts with its required range — either it's not
+ *     placed yet, or it's already at the root with a satisfying version.
+ *   - A dep is NESTED (placed at `<requester>/node_modules/<dep>`) when
+ *     the root has an incompatible version. Subsequent dependents of the
+ *     same conflicting version reuse the nested placement.
+ *
+ * The walk is BFS over (requester, depName, depRange) edges. Top-level
+ * specs are seeded with a synthetic `null` requester so they hoist to
+ * the root. Each placement returns a `ResolvedNode` whose `installPath`
+ * captures where it lives in the tree.
+ */
 async function resolveDeps(specs, npmrc, log) {
     const packumentCache = new Map();
     const fetchPkg = (name) => {
@@ -56,45 +124,155 @@ async function resolveDeps(specs, npmrc, log) {
         packumentCache.set(name, fresh);
         return fresh;
     };
-    const resolved = new Map();
-    const queue = specs.map(parseSpec);
+    /** Every installed package keyed by `installPath`. */
+    const byPath = new Map();
+    /** Root placements indexed by name for the hoist-vs-nest decision. */
+    const root = new Map();
+    const queue = specs.map(parseSpec).map((s) => ({
+        from: null,
+        name: s.name,
+        range: s.range,
+        required: true,
+    }));
     while (queue.length > 0) {
-        const spec = queue.shift();
-        if (resolved.has(spec.name)) {
-            // Single-version-per-name policy (npm v6 semantics). Phase 4 v2
-            // (when peer-dep validation lands) revisits this for duplication.
+        const edge = queue.shift();
+        // Walk the ancestor chain to see whether a satisfying placement is
+        // already visible from the requester's `node_modules` lookup. npm's
+        // resolver does this — each level of nesting acts as a fallback.
+        const visible = findVisible(edge.from, edge.name, byPath);
+        if (visible && satisfiesRange(visible.version, edge.range)) {
+            // Compatible placement reachable; reuse, no new install.
             continue;
         }
-        const packument = await fetchPkg(spec.name);
-        const version = pickVersion(packument, spec.range);
-        if (!version) {
-            throw new Error(`No version of ${spec.name} satisfies ${spec.range}`);
-        }
-        const v = packument.versions[version];
-        if (!v) {
-            throw new Error(`Packument for ${spec.name} promised ${version} but no entry exists`);
+        // No compatible existing placement. Resolve a fresh version.
+        let version = null;
+        try {
+            const packument = await fetchPkg(edge.name);
+            version = pickVersion(packument, edge.range);
+            if (!version) {
+                if (!edge.required)
+                    continue;
+                throw new Error(`No version of ${edge.name} satisfies ${edge.range}`);
+            }
+            const v = packument.versions[version];
+            if (!v) {
+                throw new Error(`Packument for ${edge.name} promised ${version} but no entry exists`);
+            }
+            // Decision: hoist to root, or nest under the requester?
+            //   - Hoist iff the root has no conflicting placement (i.e. the
+            //     root slot for `name` is empty OR holds the same version).
+            //   - Otherwise nest. Top-level specs (from === null) always
+            //     hoist; the resolver guarantees they never conflict with
+            //     each other because the input set is checked once.
+            const installPath = decidePlacement(edge.from, edge.name, version, root);
+            const node = {
+                name: edge.name,
+                version,
+                tarballUrl: v.dist.tarball,
+                integrity: v.dist.integrity,
+                installPath,
+                dependencies: v.dependencies ?? {},
+                optionalDependencies: v.optionalDependencies ?? {},
+                bin: v.bin,
+            };
+            byPath.set(installPath, node);
+            if (installPath === `node_modules/${edge.name}`) {
+                root.set(edge.name, node);
+            }
+            log("resolve: %s@%s ← %s (at %s)", edge.name, version, edge.range, installPath);
+            for (const [depName, depRange] of Object.entries(node.dependencies)) {
+                queue.push({ from: installPath, name: depName, range: depRange, required: true });
+            }
+            for (const [depName, depRange] of Object.entries(node.optionalDependencies)) {
+                queue.push({ from: installPath, name: depName, range: depRange, required: false });
+            }
         }
-        const node = {
-            name: spec.name,
-            version,
-            tarballUrl: v.dist.tarball,
-            integrity: v.dist.integrity,
-            dependencies: v.dependencies ?? {},
-            optionalDependencies: v.optionalDependencies ?? {},
-            bin: v.bin,
-        };
-        resolved.set(spec.name, node);
-        log("resolve: %s@%s ← %s", spec.name, version, spec.range);
-        for (const [depName, depRange] of Object.entries(node.dependencies)) {
-            if (!resolved.has(depName))
-                queue.push({ name: depName, range: depRange });
+        catch (e) {
+            // Optional deps that fail to resolve are skipped — yarn/npm
+            // behavior. Required deps re-throw.
+            if (!edge.required) {
+                log("resolve: optional dep %s@%s skipped (%s)", edge.name, edge.range, e.message);
+                continue;
+            }
+            throw e;
         }
-        for (const [depName, depRange] of Object.entries(node.optionalDependencies)) {
-            if (!resolved.has(depName))
-                queue.push({ name: depName, range: depRange });
+    }
+    return Array.from(byPath.values());
+}
+/**
+ * Walk the ancestor `node_modules` chain from `requesterPath` upward,
+ * looking for a placement of `name` that the requester would resolve
+ * through Node's CommonJS lookup. Returns the first match — that's the
+ * one the requester actually sees at runtime.
+ */
+function findVisible(requesterPath, name, byPath) {
+    // From the requester's directory, Node walks up node_modules dirs
+    // looking for `<dir>/node_modules/<name>`. Translate that to lockfile
+    // paths: any prefix of the requester's `installPath` that ends in a
+    // package directory gives a candidate `<prefix>/node_modules/<name>`.
+    //
+    // The requester itself ALSO checks its OWN `node_modules` first
+    // (i.e. `<requesterPath>/node_modules/<name>` — nested deps shadow
+    // ancestor ones). Then it walks up.
+    const candidates = [];
+    if (requesterPath !== null) {
+        candidates.push(`${requesterPath}/node_modules/${name}`);
+        // Walk up: strip the last `/node_modules/<pkg>` segment and try again.
+        let p = requesterPath;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            // Find the deepest `/node_modules/<pkg>` in `p`, strip it.
+            const idx = p.lastIndexOf("/node_modules/");
+            if (idx < 0)
+                break;
+            p = p.slice(0, idx);
+            candidates.push(`${p}/node_modules/${name}`);
+            if (p === "")
+                break;
         }
     }
-    return Array.from(resolved.values());
+    // The root `node_modules/<name>` is the final candidate (covers the
+    // `requesterPath === null` case too).
+    candidates.push(`node_modules/${name}`);
+    for (const candidate of candidates) {
+        const hit = byPath.get(candidate);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/**
+ * Decide where to install `name@version` for a request from `requesterPath`.
+ *
+ *   - Root is empty for `name`: hoist (return `node_modules/<name>`).
+ *   - Root has the SAME version: reuse the root placement.
+ *   - Root has a DIFFERENT version: nest under the requester.
+ *
+ * Top-level requesters (requesterPath === null) always hoist.
+ */
+function decidePlacement(requesterPath, name, version, root) {
+    const rootSlot = root.get(name);
+    if (!rootSlot)
+        return `node_modules/${name}`;
+    if (rootSlot.version === version)
+        return `node_modules/${name}`;
+    if (requesterPath === null) {
+        // Top-level specs are deduplicated by the caller before reaching
+        // here; this branch is defensive (would only fire on a duplicate
+        // top-level spec with conflicting versions).
+        return `node_modules/${name}`;
+    }
+    return `${requesterPath}/node_modules/${name}`;
+}
+function satisfiesRange(version, range) {
+    // dist-tag (e.g. `latest`) cannot be matched here — caller passed a
+    // raw range. Dist-tags only meaningful at fresh-resolve time.
+    try {
+        return satisfies(version, new Range(range));
+    }
+    catch {
+        return false;
+    }
 }
 function readLockfile(lockfilePath) {
     if (!fs.existsSync(lockfilePath))
@@ -113,10 +291,10 @@ function readLockfile(lockfilePath) {
 }
 function writeLockfile(lockfilePath, specs, nodes) {
     const packages = {};
-    // Sort for deterministic output (diff-friendly).
-    const sorted = [...nodes].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    // Sort by install path for deterministic, diff-friendly output.
+    const sorted = [...nodes].sort((a, b) => a.installPath < b.installPath ? -1 : a.installPath > b.installPath ? 1 : 0);
     for (const node of sorted) {
-        packages[node.name] = {
+        packages[node.installPath] = {
             version: node.version,
             resolved: node.tarballUrl,
             integrity: node.integrity,
@@ -132,16 +310,26 @@ function writeLockfile(lockfilePath, specs, nodes) {
     fs.writeFileSync(lockfilePath, JSON.stringify(lockfile, null, 2) + "\n");
 }
 function lockfileToNodes(lockfile) {
-    return Object.entries(lockfile.packages).map(([name, entry]) => ({
-        name,
+    return Object.entries(lockfile.packages).map(([installPath, entry]) => ({
+        // Recover the package name from the path: the last segment is
+        // either `<name>` (unscoped) or `@scope/<name>` (scoped).
+        name: nameFromInstallPath(installPath),
         version: entry.version,
         tarballUrl: entry.resolved,
         integrity: entry.integrity,
+        installPath,
         dependencies: entry.dependencies ?? {},
         optionalDependencies: {},
         bin: entry.bin,
     }));
 }
+function nameFromInstallPath(installPath) {
+    // Last `node_modules/` boundary, then the rest is the package name
+    // (single segment unscoped, or `@scope/pkg` scoped).
+    const idx = installPath.lastIndexOf("/node_modules/");
+    const after = idx < 0 ? installPath.replace(/^node_modules\//, "") : installPath.slice(idx + "/node_modules/".length);
+    return after;
+}
 function lockfileMatchesRequest(lockfile, specs) {
     if (lockfile.requested.length !== specs.length)
         return false;
@@ -149,6 +337,32 @@ function lockfileMatchesRequest(lockfile, specs) {
     const b = [...specs].sort();
     return a.every((v, i) => v === b[i]);
 }
+/**
+ * Human-readable diff between `lockfile.requested` and the live request.
+ * Returns null when the two sets are identical (the lockfile is in sync).
+ * Used by `--immutable` to surface exactly which deps drifted, so CI
+ * failures don't force the user to diff lockfile JSON by hand.
+ */
+function describeLockfileDrift(lockfile, specs) {
+    const lockSet = new Set(lockfile.requested);
+    const liveSet = new Set(specs);
+    const added = [];
+    const removed = [];
+    for (const s of liveSet)
+        if (!lockSet.has(s))
+            added.push(s);
+    for (const s of lockSet)
+        if (!liveSet.has(s))
+            removed.push(s);
+    if (added.length === 0 && removed.length === 0)
+        return null;
+    const lines = [];
+    if (added.length > 0)
+        lines.push(`  + ${added.sort().join("\n  + ")}`);
+    if (removed.length > 0)
+        lines.push(`  - ${removed.sort().join("\n  - ")}`);
+    return lines.join("\n");
+}
 function parseSpec(raw) {
     if (raw.startsWith("@")) {
         const slash = raw.indexOf("/");
@@ -188,42 +402,77 @@ function pickVersion(packument, range) {
     return maxSatisfying(versions, parsedRange);
 }
 async function downloadAndExtractAll(nodes, prefix, npmrc, log) {
-    const queue = [...nodes];
+    // Sort by install-path depth ascending so parents extract before
+    // children. Extracting a parent on top of an existing child would
+    // wipe out the child.
+    const queue = [...nodes].sort((a, b) => depth(a.installPath) - depth(b.installPath) ||
+        (a.installPath < b.installPath ? -1 : 1));
     const workers = [];
     const concurrency = Math.max(1, Math.min(DEFAULT_CONCURRENCY, queue.length));
+    // Parents (depth 1) are extracted serially first to avoid concurrent
+    // `rm -rf` + extract races with their children. Once depth-1 is done,
+    // depths >=2 run with full concurrency.
+    let cursor = 0;
+    const depth1End = queue.findIndex((n) => depth(n.installPath) > 1);
+    const splitAt = depth1End < 0 ? queue.length : depth1End;
+    // Serial root pass.
+    while (cursor < splitAt) {
+        const node = queue[cursor++];
+        if (!node)
+            break;
+        await extractOne(node, prefix, npmrc, log);
+    }
+    // Concurrent nested pass.
     for (let i = 0; i < concurrency; i++) {
-        workers.push(worker());
+        workers.push((async () => {
+            while (true) {
+                const idx = cursor++;
+                if (idx >= queue.length)
+                    return;
+                const node = queue[idx];
+                if (!node)
+                    return;
+                await extractOne(node, prefix, npmrc, log);
+            }
+        })());
     }
     await Promise.all(workers);
-    async function worker() {
-        while (queue.length > 0) {
-            const node = queue.shift();
-            if (!node)
-                return;
-            const dest = path.join(prefix, "node_modules", node.name);
-            log("fetch: %s@%s ← %s", node.name, node.version, node.tarballUrl);
-            const bytes = await fetchTarball(node.tarballUrl, {
-                npmrc,
-                integrity: node.integrity,
-            });
-            fs.rmSync(dest, { recursive: true, force: true });
-            fs.mkdirSync(dest, { recursive: true });
-            await extractTarball(bytes, dest);
-        }
-    }
+}
+async function extractOne(node, prefix, npmrc, log) {
+    const dest = path.join(prefix, node.installPath);
+    log("fetch: %s@%s ← %s (→ %s)", node.name, node.version, node.tarballUrl, node.installPath);
+    const bytes = await fetchTarball(node.tarballUrl, {
+        npmrc,
+        integrity: node.integrity,
+    });
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.mkdirSync(dest, { recursive: true });
+    await extractTarball(bytes, dest);
+}
+function depth(installPath) {
+    // Count `node_modules/` segments to know nesting depth.
+    // `node_modules/foo` = 1, `node_modules/foo/node_modules/bar` = 2, etc.
+    return installPath.split("/node_modules/").length;
 }
 async function linkBins(nodes, prefix, log) {
+    // Only root-level packages publish bins into the top-level
+    // `node_modules/.bin/`. Nested-package bins are addressable by their
+    // direct dependents through the nested .bin (npm matches this) — we
+    // omit nested-bin linking for now since no consumer of the install
+    // backend depends on it (gjsify's own use cases all hit root bins).
     const binDir = path.join(prefix, "node_modules", ".bin");
     let created = 0;
     for (const node of nodes) {
         if (!node.bin)
             continue;
+        if (depth(node.installPath) !== 1)
+            continue;
         const map = normalizeBin(node.name, node.bin);
         if (map.size === 0)
             continue;
         fs.mkdirSync(binDir, { recursive: true });
         for (const [binName, binTarget] of map) {
-            const targetAbs = path.join(prefix, "node_modules", node.name, binTarget);
+            const targetAbs = path.join(prefix, node.installPath, binTarget);
             if (!fs.existsSync(targetAbs))
                 continue;
             try {
@@ -265,25 +514,35 @@ function normalizeBin(pkgName, bin) {
 }
 async function loadNpmrc(opts) {
     const home = os.homedir();
-    const homeRc = path.join(home, ".npmrc");
     let parsed = {
         registry: opts.registry ?? DEFAULT_REGISTRY,
         scopes: {},
         authTokens: {},
         basicAuth: {},
     };
-    if (fs.existsSync(homeRc)) {
+    // Layered .npmrc lookup (most-specific wins): home → project (cwd's
+    // prefix). npm itself merges through `XDG_CONFIG_HOME/npm/npmrc` and a
+    // workspace-root one too; the gjsify project-local case is what users
+    // hit most often (mock-registry tests, scoped-registry overrides), so
+    // we cover that explicitly.
+    for (const candidate of [path.join(home, ".npmrc"), path.join(opts.prefix, ".npmrc")]) {
+        if (!fs.existsSync(candidate))
+            continue;
         try {
-            parsed = parseNpmrc(fs.readFileSync(homeRc, "utf-8"));
+            const projectParsed = parseNpmrc(fs.readFileSync(candidate, "utf-8"));
+            parsed = { ...parsed, ...projectParsed, scopes: { ...parsed.scopes, ...projectParsed.scopes } };
         }
         catch (e) {
-            // Don't let a busted .npmrc prevent installs from anonymous registries.
-            console.warn(`gjsify install: ignoring malformed ${homeRc}: ${e.message}`);
+            console.warn(`gjsify install: ignoring malformed ${candidate}: ${e.message}`);
         }
     }
-    if (opts.registry) {
+    // env-var override (npm convention: `npm_config_registry`).
+    const envRegistry = process.env.npm_config_registry;
+    if (envRegistry)
+        parsed.registry = envRegistry;
+    // Explicit caller-provided registry trumps everything else.
+    if (opts.registry)
         parsed.registry = opts.registry;
-    }
     return parsed;
 }
 function makeLogger(verbose) {

package/lib/utils/install-backend.d.ts

@@ -16,4 +16,14 @@ export interface InstallOptions {
     /** Use `<prefix>/gjsify-lock.json` as the source of truth — fail if missing. */
     frozen?: boolean;
 }
-export declare function installPackages(opts: InstallOptions): Promise<void>;
+export interface InstallResult {
+    /** Top-level packages that were requested, with the version each
+     *  resolved to. Empty for the npm backend (parsing npm's stdout would
+     *  be unreliable; callers that need this should set
+     *  GJSIFY_INSTALL_BACKEND=native). */
+    installed: Array<{
+        name: string;
+        version: string;
+    }>;
+}
+export declare function installPackages(opts: InstallOptions): Promise<InstallResult>;

package/lib/utils/install-backend.js

@@ -18,10 +18,12 @@ import { join } from 'node:path';
 const DEFAULT_BACKEND = process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
 export async function installPackages(opts) {
     if (DEFAULT_BACKEND === 'npm') {
-        return installViaNpm(opts);
+        await installViaNpm(opts);
+        return { installed: [] };
     }
     const { installPackagesNative } = await import('./install-backend-native.js');
-    return installPackagesNative(opts);
+    const installed = await installPackagesNative(opts);
+    return { installed };
 }
 async function installViaNpm({ prefix, specs, verbose, registry }) {
     if (specs.length === 0) {

package/lib/utils/pkg-json-edit.d.ts

@@ -0,0 +1,47 @@
+export type DependencyKind = 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
+export interface PackageJson {
+    name?: string;
+    version?: string;
+    type?: string;
+    workspaces?: string[] | {
+        packages?: string[];
+        nohoist?: string[];
+    };
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    [key: string]: unknown;
+}
+export declare function readPackageJson(pkgPath: string): PackageJson | null;
+export declare function writePackageJson(pkgPath: string, pkg: PackageJson): void;
+/**
+ * Parse a user spec into `{ name, range }`:
+ *   `react`         → { name: 'react', range: undefined }
+ *   `react@^18`     → { name: 'react', range: '^18' }
+ *   `@types/node`   → { name: '@types/node', range: undefined }
+ *   `@types/node@1` → { name: '@types/node', range: '1' }
+ */
+export declare function parseSpec(spec: string): {
+    name: string;
+    range?: string;
+};
+/**
+ * Collect existing dependencies + devDependencies + optionalDependencies
+ * from a project package.json into installable specs of the form
+ * `name@range`. Used by `gjsify install` (no args) to seed the resolver
+ * with the project's existing dependency manifest — equivalent to
+ * `npm install` reading `package.json`.
+ */
+export declare function projectSpecsFromPackageJson(pkg: PackageJson): string[];
+/**
+ * Add or update a dependency entry in `pkg`. If the spec didn't include
+ * a range, callers fill in the installed version after resolution and
+ * call this again with `installedVersion` set.
+ */
+export declare function addDependencyEntry(pkg: PackageJson, name: string, range: string, kind: DependencyKind): void;
+/**
+ * Default version range when the user didn't pin one: `^x.y.z` from the
+ * installed version. Mirrors npm's `save-prefix` default (`^`).
+ */
+export declare function defaultRangeFromVersion(version: string): string;