@gjsify/cli 0.3.21 → 0.4.0

package/lib/commands/run.js

@@ -1,26 +1,139 @@
-import { resolve } from 'node:path';
+// `gjsify run <target> [args..]` — dual-mode runner.
+//
+//   gjsify run <file>     → existing behavior: run a GJS bundle file
+//                          via `gjs -m`, with LD_LIBRARY_PATH +
+//                          GI_TYPELIB_PATH set for native packages.
+//   gjsify run <script>   → yarn-run-style: look up `<script>` in the
+//                          current workspace's package.json `scripts`
+//                          and execute it with `node_modules/.bin` on
+//                          PATH (workspace + monorepo root).
+//
+// Phase D.5 added the script-runner side. The two modes coexist via a
+// `looksLikeFile()` heuristic: anything with a path separator, JS-ish
+// extension, or that resolves to an existing path on disk is treated
+// as a bundle file. Everything else is a script name. Users who want
+// to disambiguate can pass `./<file>` explicitly.
+import { existsSync } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
 import { runGjsBundle } from '../utils/run-gjs.js';
+import { readPackageJson } from '../utils/pkg-json-edit.js';
+import { discoverWorkspaces } from '@gjsify/workspace';
 export const runCommand = {
-    command: 'run <file> [args..]',
-    description: 'Run a GJS bundle, automatically setting LD_LIBRARY_PATH and GI_TYPELIB_PATH for any installed native gjsify packages (e.g. @gjsify/webgl).',
-    builder: (yargs) => {
-        return yargs
-            .positional('file', {
-            description: 'The GJS bundle to run (e.g. dist/gjs.js)',
-            type: 'string',
-            normalize: true,
-            demandOption: true,
-        })
-            .positional('args', {
-            description: 'Extra arguments passed through to gjs',
-            type: 'string',
-            array: true,
-            default: [],
-        });
-    },
+    command: 'run <target> [args..]',
+    description: 'Run a script from package.json (yarn-run-style) or a GJS bundle file. If <target> resolves to a file on disk (or has a path-like prefix), it is launched via gjs with LD_LIBRARY_PATH + GI_TYPELIB_PATH set for native packages. Otherwise it is looked up in the current package.json `scripts`.',
+    builder: (yargs) => yargs
+        .positional('target', {
+        description: 'Either a script name (looked up in package.json `scripts`) or a path to a GJS bundle (e.g. dist/gjs.js).',
+        type: 'string',
+        demandOption: true,
+    })
+        .positional('args', {
+        description: 'Extra arguments passed through to the script / gjs.',
+        type: 'string',
+        array: true,
+        default: [],
+    }),
     handler: async (args) => {
-        const file = resolve(args.file);
+        const target = args.target;
         const extraArgs = args.args ?? [];
-        await runGjsBundle(file, extraArgs);
+        if (looksLikeFile(target)) {
+            const file = resolve(target);
+            await runGjsBundle(file, extraArgs);
+            return;
+        }
+        await runScript(target, extraArgs);
     },
 };
+function looksLikeFile(target) {
+    if (target.startsWith('./') || target.startsWith('../') || target.startsWith('/'))
+        return true;
+    if (target.includes('/') || target.includes('\\'))
+        return true;
+    if (/\.(c?js|mjs|cjs|gjs)$/.test(target))
+        return true;
+    return existsSync(target);
+}
+/**
+ * Run a script declared in the current workspace's `package.json#scripts`.
+ * Mirrors `yarn run <script>` semantics:
+ *   - PATH prepended with `<workspace>/node_modules/.bin` AND the
+ *     monorepo-root `node_modules/.bin` (covers locally-installed bins
+ *     and hoisted bins)
+ *   - extra args appended after the script's literal command, shell-escaped
+ *   - executed through `shell: true` so `&&` / `|` / env-var refs work
+ *     exactly as in package.json scripts (matches npm/yarn)
+ */
+async function runScript(script, extraArgs) {
+    const cwd = process.cwd();
+    const pkgPath = join(cwd, 'package.json');
+    const pkg = readPackageJson(pkgPath);
+    if (!pkg) {
+        console.error(`gjsify run: no package.json in ${cwd}`);
+        process.exit(1);
+    }
+    const scripts = pkg.scripts ?? {};
+    const literal = scripts[script];
+    if (typeof literal !== 'string') {
+        const available = Object.keys(scripts).join(', ') || '<none>';
+        console.error(`gjsify run: no script "${script}" in ${pkgPath} (available: ${available})`);
+        process.exit(1);
+    }
+    const monorepoRoot = findWorkspaceRoot(cwd);
+    const binDirs = [join(cwd, 'node_modules', '.bin')];
+    if (monorepoRoot && monorepoRoot !== cwd) {
+        binDirs.push(join(monorepoRoot, 'node_modules', '.bin'));
+    }
+    const env = {
+        ...process.env,
+        PATH: [...binDirs, process.env.PATH ?? ''].filter(Boolean).join(delimiter),
+        npm_lifecycle_event: script,
+        npm_package_name: pkg.name ?? '',
+        npm_package_version: pkg.version ?? '',
+    };
+    const fullCmd = extraArgs.length > 0
+        ? `${literal} ${extraArgs.map(shellEscape).join(' ')}`
+        : literal;
+    await new Promise((resolveOk, reject) => {
+        const child = spawn(fullCmd, { cwd, env, stdio: 'inherit', shell: true });
+        child.on('close', (code) => {
+            if (code === 0)
+                resolveOk();
+            else
+                reject(new Error(`script "${script}" exited with code ${code}`));
+        });
+        child.on('error', reject);
+    }).catch((err) => {
+        console.error(err.message);
+        process.exit(1);
+    });
+}
+function findWorkspaceRoot(start) {
+    let dir = start;
+    for (let i = 0; i < 12; i++) {
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath)) {
+            const pkg = readPackageJson(pkgPath);
+            if (pkg?.workspaces !== undefined) {
+                try {
+                    // Sanity-check that cwd is reachable as a workspace —
+                    // otherwise we'd pick an unrelated grand-parent monorepo.
+                    const ws = discoverWorkspaces(dir);
+                    if (dir === start || ws.some((w) => w.location === start))
+                        return dir;
+                }
+                catch { /* not a usable workspace root */ }
+            }
+        }
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function shellEscape(arg) {
+    if (/^[a-zA-Z0-9_\-./=:@,]+$/.test(arg))
+        return arg;
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}

package/lib/commands/workspace.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from '../types/index.js';
+interface WorkspaceCmdOptions {
+    name: string;
+    script: string;
+    args?: string[];
+}
+export declare const workspaceCommand: Command<any, WorkspaceCmdOptions>;
+export {};

package/lib/commands/workspace.js

@@ -0,0 +1,69 @@
+// `gjsify workspace <name> <script> [args..]` — yarn-workspace shortcut.
+//
+// Equivalent to `yarn workspace <name> run <script>`: locates the named
+// workspace in the current monorepo, then runs the script there. Used
+// extensively in gjsify's own root `package.json` (17 call sites).
+import { spawn } from 'node:child_process';
+import { discoverWorkspaces } from '@gjsify/workspace';
+export const workspaceCommand = {
+    command: 'workspace <name> <script> [args..]',
+    description: 'Run a workspace script (`yarn workspace <name> run <script>` equivalent).',
+    builder: (yargs) => yargs
+        .positional('name', {
+        description: 'Workspace name (matches package.json `name` field).',
+        type: 'string',
+        demandOption: true,
+    })
+        .positional('script', {
+        description: 'Script name to run inside that workspace.',
+        type: 'string',
+        demandOption: true,
+    })
+        .positional('args', {
+        description: 'Extra arguments forwarded to the script.',
+        type: 'string',
+        array: true,
+    }),
+    handler: async (args) => {
+        const workspaces = discoverWorkspaces(process.cwd());
+        const target = workspaces.find((w) => w.name === args.name);
+        if (!target) {
+            console.error(`gjsify workspace: no workspace named "${args.name}" — discovered ${workspaces.length} workspace(s)`);
+            process.exit(1);
+        }
+        const scripts = target.manifest.scripts ?? {};
+        if (typeof scripts[args.script] !== 'string') {
+            console.error(`gjsify workspace: workspace "${args.name}" has no script "${args.script}"`);
+            process.exit(1);
+        }
+        const runner = detectPackageManager();
+        const argv = runner === 'gjsify'
+            ? ['run', args.script, ...(args.args ?? [])]
+            : ['run', args.script, ...(args.args && args.args.length > 0 ? ['--', ...args.args] : [])];
+        await new Promise((resolve, reject) => {
+            const child = spawn(runner, argv, {
+                cwd: target.location,
+                stdio: 'inherit',
+                env: process.env,
+            });
+            child.on('close', (code) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`${runner} ${argv.join(' ')} exited with code ${code}`));
+            });
+            child.on('error', reject);
+        }).catch((err) => {
+            console.error(err.message);
+            process.exit(1);
+        });
+    },
+};
+function detectPackageManager() {
+    const ua = process.env.npm_config_user_agent ?? '';
+    if (ua.startsWith('yarn/'))
+        return 'yarn';
+    if (ua.startsWith('gjsify/'))
+        return 'gjsify';
+    return 'npm';
+}

package/lib/config.js

@@ -247,7 +247,18 @@ export class Config {
         if (output.minify === undefined)
             output.minify = true;
         if (output.minify === true) {
-            output.minify = { mangle: { keepNames: { function: true, class: true } } };
+            // `keepNames: true` on output is the top-level BundlerOptions
+            // path: rolldown wires it into both `mangle.keepNames.all_true()`
+            // (function+class) AND `compress.keepNames.all_true()` for us.
+            // The previous `minify: { mangle: { keepNames: {...} } }` shape
+            // worked under npm rolldown's JS API but rolldown's serde
+            // `deserialize_minify` (deserialize_minify_options.rs:311) only
+            // accepts SimpleMinifyOptions (bool/string), so the object form
+            // was rejected by the native facade's JSON-deserializer with
+            // "data did not match any variant of untagged enum
+            // SimpleMinifyOptions". `output.keepNames` reaches the binding
+            // through the documented top-level path in both engines.
+            output.keepNames = true;
         }
         if (cliArgs.logLevel) {
             // Map esbuild log levels to Rolldown's narrower set:

package/lib/index.js

@@ -1,9 +1,14 @@
 #!/usr/bin/env node
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, } from './commands/index.js';
+import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
-void yargs(hideBin(process.argv))
+// `parseAsync()` instead of `.argv` so the top-level await keeps the
+// process alive until command handlers complete. Under Node this is
+// cosmetic — the event loop holds the process up — but under GJS the
+// script ends as soon as the top-level synchronous flow finishes, and
+// fire-and-forget handlers silently exit before any async work runs.
+await yargs(hideBin(process.argv))
     .scriptName(APP_NAME)
     .strict()
     .command(create.command, create.description, create.builder, create.handler)
@@ -18,5 +23,8 @@ void yargs(hideBin(process.argv))
     .command(gettext.command, gettext.description, gettext.builder, gettext.handler)
     .command(gsettings.command, gsettings.description, gsettings.builder, gsettings.handler)
     .command(flatpak.command, flatpak.description, flatpak.builder, flatpak.handler)
+    .command(foreach.command, foreach.description, foreach.builder, foreach.handler)
+    .command(workspace.command, workspace.description, workspace.builder, workspace.handler)
     .demandCommand(1)
-    .help().argv;
+    .help()
+    .parseAsync();

package/lib/types/config-data.d.ts

@@ -202,7 +202,16 @@ export interface ConfigDataFlatpak {
     runtime?: 'gnome' | 'freedesktop';
     /** Runtime/SDK version, e.g. `'50'` for GNOME or `'24.08'` for Freedesktop. */
     runtimeVersion?: string;
-    /** Extra SDK extensions, e.g. `['org.freedesktop.Sdk.Extension.node24']` for build-time `yarn install`. */
+    /**
+     * Extra SDK extensions to include in the manifest, e.g.
+     * `['org.freedesktop.Sdk.Extension.llvm17']` for projects with native
+     * code that needs a specific toolchain. Leave empty (the default) for
+     * pure gjsify projects — the GNOME runtime already ships GJS + GLib
+     * + libsoup, and `gjsify build` produces a self-contained bundle that
+     * needs no build-time Node anymore. (Before Phase D-3 we added
+     * `org.freedesktop.Sdk.Extension.node24` here by default for the
+     * yarn-install + esbuild build step — that's no longer required.)
+     */
     sdkExtensions?: string[];
     /** Path components prepended to PATH inside the build sandbox. */
     appendPath?: string[];

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

@@ -1,2 +1,6 @@
 import type { InstallOptions } from "./install-backend.ts";
-export declare function installPackagesNative(opts: InstallOptions): Promise<void>;
+export interface InstalledTopLevel {
+    name: string;
+    version: string;
+}
+export declare function installPackagesNative(opts: InstallOptions): Promise<InstalledTopLevel[]>;

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

@@ -26,14 +26,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,6 +60,32 @@ 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) {
+    const byName = new Map(nodes.map((n) => [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);
 }
 async function resolveDeps(specs, npmrc, log) {
     const packumentCache = new Map();
@@ -149,6 +190,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("/");
@@ -265,25 +332,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;

package/lib/utils/pkg-json-edit.js

@@ -0,0 +1,108 @@
+// Helpers for editing `package.json` during `gjsify install <pkg>`.
+//
+// Mirrors npm's `--save-{prod,dev,peer,optional}` semantics:
+//   - default → dependencies (production)
+//   - --save-dev → devDependencies
+//   - --save-peer → peerDependencies
+//   - --save-optional → optionalDependencies
+//
+// Version specifier resolution mirrors npm's default (`^x.y.z` from the
+// installed version), unless the user passed an explicit range in the spec
+// (`react@^18` → keep `^18`).
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+export function readPackageJson(pkgPath) {
+    if (!existsSync(pkgPath))
+        return null;
+    const raw = readFileSync(pkgPath, 'utf-8');
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`gjsify install: ${pkgPath} is not valid JSON: ${e.message}`);
+    }
+}
+export function writePackageJson(pkgPath, pkg) {
+    const sorted = sortKnownDepFields(pkg);
+    writeFileSync(pkgPath, JSON.stringify(sorted, null, 2) + '\n', 'utf-8');
+}
+/**
+ * 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 function parseSpec(spec) {
+    if (spec.startsWith('@')) {
+        const slash = spec.indexOf('/');
+        if (slash === -1)
+            return { name: spec };
+        const at = spec.indexOf('@', slash + 1);
+        if (at === -1)
+            return { name: spec };
+        return { name: spec.slice(0, at), range: spec.slice(at + 1) };
+    }
+    const at = spec.indexOf('@');
+    if (at === -1)
+        return { name: spec };
+    return { name: spec.slice(0, at), range: spec.slice(at + 1) };
+}
+/**
+ * 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 function projectSpecsFromPackageJson(pkg) {
+    const out = [];
+    for (const kind of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+        const block = pkg[kind];
+        if (!block)
+            continue;
+        for (const [name, range] of Object.entries(block)) {
+            // Skip workspace: / link: / file: / portal: specifiers — those
+            // are workspace-local references handled by Phase D.3, not by
+            // the project-local install path.
+            if (typeof range !== 'string')
+                continue;
+            if (/^(workspace|link|file|portal|git\+|https?):/.test(range))
+                continue;
+            out.push(`${name}@${range}`);
+        }
+    }
+    return out;
+}
+/**
+ * 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 function addDependencyEntry(pkg, name, range, kind) {
+    if (pkg[kind] === undefined) {
+        pkg[kind] = {};
+    }
+    pkg[kind][name] = range;
+}
+/**
+ * Default version range when the user didn't pin one: `^x.y.z` from the
+ * installed version. Mirrors npm's `save-prefix` default (`^`).
+ */
+export function defaultRangeFromVersion(version) {
+    return `^${version}`;
+}
+function sortKnownDepFields(pkg) {
+    const out = { ...pkg };
+    for (const kind of [
+        'dependencies',
+        'devDependencies',
+        'peerDependencies',
+        'optionalDependencies',
+    ]) {
+        const block = out[kind];
+        if (!block)
+            continue;
+        out[kind] = Object.fromEntries(Object.entries(block).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    }
+    return out;
+}