@gjsify/cli 0.13.2 → 0.15.1

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

@@ -19,6 +19,8 @@ import * as os from 'node:os';
 import { Range, SemVer, maxSatisfying, satisfies } from '@gjsify/semver';
 import { DEFAULT_REGISTRY, fetchPackument, fetchPackumentConditional, fetchTarball, parseNpmrc, registryFor, } from '@gjsify/npm-registry';
 import { extractTarball } from '@gjsify/tar';
+import { atomicWriteStrict } from './install-cache-fs.js';
+import { acquireInstallLock } from './install-lock.js';
 import { getCachedTarball, getForeignCachedTarball, putCachedTarball, } from './install-tarball-cache.js';
 import { getCachedPackument, putCachedPackument } from './install-packument-cache.js';
 import { assertNativeBackendNodeVersion } from './node-version.js';
@@ -40,6 +42,23 @@ export async function installPackagesNative(opts) {
     fs.mkdirSync(opts.prefix, { recursive: true });
     const npmrc = await loadNpmrc(opts);
     const log = makeLogger(opts.verbose ?? false);
+    // Serialize every mutation of THIS prefix across processes (ADR 0001):
+    // concurrent installs into the same node_modules used to interleave
+    // `rmSync` + extract on shared destination dirs and tear the lockfile.
+    // Re-entrant within the process (workspace installs already hold the
+    // root-prefix lock — this just bumps a refcount). Installs into other
+    // prefixes proceed concurrently; the shared XDG caches stay lock-free
+    // because their tmp+rename writes are atomic (install-cache-fs.ts).
+    const lock = await acquireInstallLock(opts.prefix, { signal: opts.signal });
+    try {
+        return await installPackagesNativeLocked(opts, npmrc, log);
+    }
+    finally {
+        lock.release();
+    }
+}
+/** Body of {@link installPackagesNative}, run while holding the prefix lock. */
+async function installPackagesNativeLocked(opts, npmrc, log) {
     const progress = opts.progress;
     const lockfilePath = path.join(opts.prefix, LOCKFILE_NAME);
     const existingLock = readLockfile(lockfilePath);
@@ -76,7 +95,7 @@ export async function installPackagesNative(opts) {
         // (and silently bumping transitive deps) on a one-package add.
         const preferred = !opts.refreshLockfile && existingLock ? buildPreferredVersions(existingLock) : undefined;
         log('install: resolving %d top-level spec(s) → %s%s', opts.specs.length, opts.prefix, preferred ? ` (preserving ${preferred.size} locked name(s))` : '');
-        nodes = await resolveDeps(opts.specs, npmrc, log, opts.overrides, opts.skipDeps, opts.signal, progress, preferred, opts.workspaceNames);
+        nodes = await resolveDeps(opts.specs, npmrc, log, opts.overrides, opts.skipDeps, opts.signal, progress, preferred, opts.workspaceNames, opts.specOrigins);
         if (opts.lockfile) {
             writeLockfile(lockfilePath, opts.specs, nodes);
             log('install: wrote %s (%d entries)', LOCKFILE_NAME, nodes.length);
@@ -171,7 +190,13 @@ preferredVersions,
  * the published version (and its subtree) never enters the resolved tree or
  * the lockfile.
  */
-workspaceNames) {
+workspaceNames, 
+/**
+ * Requester labels for top-level specs (`"<name>@<range>"` → workspace
+ * names) — see `InstallOptions.specOrigins`. Used only to attribute the
+ * version-conflict warning.
+ */
+specOrigins) {
     progress?.beginPhase('resolve', specs.length);
     const applyOverride = (name, range) => {
         if (!overrides)
@@ -197,12 +222,37 @@ workspaceNames) {
     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: applyOverride(s.name, s.range),
-        required: true,
-    }));
+    // Top-level range bookkeeping for the version-conflict warning:
+    // `name → (applied range → requester labels)`. Only TOP-LEVEL specs
+    // participate: conflicting transitive edges are resolved correctly by
+    // nesting (Phase D.7b), but conflicting top-level specs — the shape
+    // `workspaceInstall` produces when two workspaces declare incompatible
+    // ranges of the same external dep — all compete for the single root
+    // slot, and today the resolver silently keeps one version for everyone
+    // (per-workspace dedup is Phase D.8). Until that lands, the conflict is
+    // surfaced loudly after the resolve (see emitTopLevelConflictWarnings).
+    const topLevelRanges = new Map();
+    const queue = specs.map(parseSpec).map((s) => {
+        const range = applyOverride(s.name, s.range);
+        let ranges = topLevelRanges.get(s.name);
+        if (!ranges) {
+            ranges = new Map();
+            topLevelRanges.set(s.name, ranges);
+        }
+        let requesters = ranges.get(range);
+        if (!requesters) {
+            requesters = new Set();
+            ranges.set(range, requesters);
+        }
+        for (const origin of specOrigins?.get(`${s.name}@${s.range}`) ?? [])
+            requesters.add(origin);
+        return {
+            from: null,
+            name: s.name,
+            range,
+            required: true,
+        };
+    });
     // Wave-based BFS. Each iteration drains the current queue level, prefetches
     // every not-yet-cached packument in that level IN PARALLEL (bounded), then
     // applies placement SERIALLY in the same FIFO order the single-edge loop
@@ -329,8 +379,50 @@ workspaceNames) {
         }
     }
     progress?.endPhase('resolve');
+    emitTopLevelConflictWarnings(topLevelRanges, root);
     return Array.from(byPath.values());
 }
+/**
+ * Loud, single-line-per-package warning for top-level version-range
+ * conflicts (ADR 0001, step 3). Fires when two or more top-level specs
+ * requested DIFFERENT ranges of the same package and the version that ended
+ * up hoisted to the root does not satisfy all of them — i.e. some requester
+ * silently got a version outside its declared range. Compatible ranges
+ * (`^1.2` + `^1.4` both satisfied by `1.9.0`) stay silent; ranges that are
+ * not semver (dist-tags like `latest`) cannot be compared and are skipped.
+ *
+ * This makes the current single-root-slot behavior honest instead of silent;
+ * the real fix — a per-workspace dedup pass that gives each conflicting
+ * requester its own nested copy — is Phase D.8 (see STATUS.md).
+ */
+function emitTopLevelConflictWarnings(topLevelRanges, root) {
+    for (const [name, ranges] of topLevelRanges) {
+        if (ranges.size < 2)
+            continue;
+        const placed = root.get(name);
+        if (!placed)
+            continue; // workspace-provided or never placed — nothing installed to warn about
+        const describe = (range, requesters) => requesters.size > 0 ? `${range} (requested by ${[...requesters].join(', ')})` : range;
+        const satisfied = [];
+        const unsatisfied = [];
+        for (const [range, requesters] of ranges) {
+            let ok;
+            try {
+                ok = satisfies(placed.version, new Range(range));
+            }
+            catch {
+                continue; // dist-tag / non-semver range — not comparable
+            }
+            (ok ? satisfied : unsatisfied).push(describe(range, requesters));
+        }
+        if (unsatisfied.length === 0)
+            continue;
+        console.warn(`[gjsify] warning: version conflict for ${name}: installed ${placed.version} at ${placed.installPath} — ` +
+            `does NOT satisfy ${unsatisfied.join(', ')}` +
+            (satisfied.length > 0 ? `; satisfies ${satisfied.join(', ')}` : '') +
+            `. One hoisted copy serves all requesters until the per-workspace dedup pass lands (Phase D.8).`);
+    }
+}
 /**
  * Warm `packumentCache` for a batch of package names with bounded parallelism
  * (same `DEFAULT_CONCURRENCY` width as the download pool). Rejections — e.g. a
@@ -502,7 +594,10 @@ function writeLockfile(lockfilePath, specs, nodes) {
         requested: [...specs],
         packages,
     };
-    fs.writeFileSync(lockfilePath, JSON.stringify(lockfile, null, 2) + '\n');
+    // Atomic tmp+rename so a crash mid-write (or a reader racing the writer)
+    // can never observe a torn gjsify-lock.json — `--immutable` would
+    // otherwise hard-fail on the corrupt file with a misleading error.
+    atomicWriteStrict(lockfilePath, JSON.stringify(lockfile, null, 2) + '\n');
 }
 /**
  * Build the lockfile-preservation oracle: `name → every version currently

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

@@ -83,6 +83,16 @@ export interface InstallOptions {
      * itself.
      */
     workspaceNames?: Set<string>;
+    /**
+     * Native backend only: requester labels for top-level specs, keyed by the
+     * exact `"<name>@<range>"` spec string. `workspaceInstall` records which
+     * workspace(s) declared each aggregated external spec so the resolver's
+     * version-conflict warning can name BOTH sides of a conflict ("^1 requested
+     * by @scope/a, ^2 requested by @scope/b"). Optional — flows without
+     * per-requester attribution (single-project installs, dlx) omit it and the
+     * warning falls back to the bare ranges.
+     */
+    specOrigins?: Map<string, string[]>;
 }
 export interface InstallResult {
     /** Top-level packages that were requested, with the version each

package/lib/utils/install-cache-fs.d.ts

@@ -13,6 +13,15 @@ export declare function gjsifyCacheRoot(kind: string, layoutVersion: string): st
  * install; the caller proceeds with its in-memory copy.
  */
 export declare function atomicWrite(path: string, bytes: Uint8Array | string): void;
+/**
+ * Strict sibling of {@link atomicWrite}: identical tmp+`rename` pattern, but
+ * failures PROPAGATE to the caller. Use for files whose corruption/loss must
+ * abort the operation (the `gjsify-lock.json` writer) rather than degrade
+ * silently like a cache entry. `rename` over the destination is atomic on
+ * POSIX, so a concurrent reader (or a crash mid-write) sees either the old
+ * complete file or the new complete file — never a torn one.
+ */
+export declare function atomicWriteStrict(path: string, bytes: Uint8Array | string): void;
 /**
  * Read a cache file, returning its bytes on a HIT or `null` on a MISS. A
  * missing file, a zero-byte file (an interrupted previous write), or any read

package/lib/utils/install-cache-fs.js

@@ -1,12 +1,15 @@
 // SPDX-License-Identifier: MIT
-// Shared filesystem primitives for `gjsify install`'s on-disk caches.
+// Shared filesystem primitives for `gjsify install`'s on-disk caches and its
+// lockfile writer.
 //
 // Both the content-addressable tarball cache (install-tarball-cache.ts) and the
 // packument metadata cache (install-packument-cache.ts) need the same three
 // things: an `XDG_CACHE_HOME`-honouring cache root, an atomic write (so a
 // concurrent install never observes a half-written entry), and a read that
 // treats a missing / zero-byte / unreadable file as a MISS. Centralising them
-// here keeps the two caches byte-for-byte consistent.
+// here keeps the two caches byte-for-byte consistent. The lockfile writer
+// (`gjsify-lock.json`) shares the same tmp+rename pattern via the strict
+// variant so an interrupted install can never leave a torn lockfile behind.
 //
 // Out of scope: the dlx cache (`dlx-cache.ts`) has a different layout
 // (`gjsify/dlx`, sha256 + symlink-swap) and its own TTL/prepare-dir concerns —
@@ -34,15 +37,26 @@ export function gjsifyCacheRoot(kind, layoutVersion) {
  */
 export function atomicWrite(path, bytes) {
     try {
-        mkdirSync(join(path, '..'), { recursive: true });
-        const tmp = `${path}.tmp.${process.pid}`;
-        writeFileSync(tmp, bytes);
-        renameSync(tmp, path);
+        atomicWriteStrict(path, bytes);
     }
     catch {
         /* best-effort — a cache-write failure must not break the install */
     }
 }
+/**
+ * Strict sibling of {@link atomicWrite}: identical tmp+`rename` pattern, but
+ * failures PROPAGATE to the caller. Use for files whose corruption/loss must
+ * abort the operation (the `gjsify-lock.json` writer) rather than degrade
+ * silently like a cache entry. `rename` over the destination is atomic on
+ * POSIX, so a concurrent reader (or a crash mid-write) sees either the old
+ * complete file or the new complete file — never a torn one.
+ */
+export function atomicWriteStrict(path, bytes) {
+    mkdirSync(join(path, '..'), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, bytes);
+    renameSync(tmp, path);
+}
 /**
  * Read a cache file, returning its bytes on a HIT or `null` on a MISS. A
  * missing file, a zero-byte file (an interrupted previous write), or any read

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

@@ -0,0 +1,15 @@
+export interface InstallLockHandle {
+    /** Release the lock (refcounted; the on-disk dir is removed at count 0). */
+    release(): void;
+}
+/**
+ * Acquire the cross-process install lock for `prefix`. Resolves once this
+ * process may mutate `<prefix>/node_modules` + `<prefix>/gjsify-lock.json`;
+ * the caller MUST `release()` in a `finally`. Waits (with backoff) while a
+ * live concurrent install holds the lock; steals provably-stale locks (dead
+ * owner pid / exceeded staleness budget). `signal` aborts the wait — wired
+ * to the overall install budget so a waiter never outlives its own timeout.
+ */
+export declare function acquireInstallLock(prefix: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<InstallLockHandle>;

package/lib/utils/install-lock.js

@@ -0,0 +1,293 @@
+// SPDX-License-Identifier: MIT
+// Cross-process install lock for `gjsify install` (ADR 0001, step 2).
+//
+// WHAT is locked: mutation of ONE install prefix — its `node_modules/` tree,
+// its `gjsify-lock.json`, and (through the same code path) the user-global
+// prefix that `gjsify install -g` extracts into. Two processes installing
+// into the SAME prefix used to interleave `rmSync` + extract on the same
+// destination directories (corrupt trees, spurious ENOENT mid-extract) and
+// tear the lockfile. The lock serializes them. Installs into DIFFERENT
+// prefixes stay fully concurrent.
+//
+// WHAT is deliberately NOT locked: the shared XDG caches
+// (`$XDG_CACHE_HOME/gjsify/{tarballs,metadata}`). Those are content-addressed
+// and written via atomic tmp+`rename` (`install-cache-fs.ts`), so concurrent
+// writers are already safe lock-free — identical-content last-rename-wins.
+//
+// Mechanism: `mkdir` of `<prefix>/node_modules/.gjsify-install-lock` is the
+// atomic acquire. mkdir has exclusive-create semantics on every runtime we
+// target: Node's `mkdirSync` throws EEXIST, and the GJS fs polyfill maps
+// Gio's G_IO_ERROR_EXISTS to the same code. (A lock FILE with `flag: 'wx'`
+// would NOT work — the GJS `writeFileSync` polyfill ignores open flags and
+// happily overwrites.) An `owner.json` inside the dir records pid + start
+// time for staleness checks and diagnostics.
+//
+// Staleness: a crashed install cannot release its lock, so contenders steal
+// when
+//   (a) the owner pid is provably dead (`/proc/<pid>` on Linux — readable
+//       under both Node and GJS; a kill(0) probe covers non-/proc Nodes), or
+//   (b) the lock outlives GJSIFY_INSTALL_LOCK_STALE_MS (default 35 min —
+//       just above the 30-min overall install budget, so a budget-bound
+//       install always times out and exits before its lock can be stolen
+//       out from under it), or
+//   (c) `mkdir` succeeded but `owner.json` never appeared within a short
+//       grace period (the owner died between the two steps).
+// The steal itself is race-free: the stale dir is claimed via an atomic
+// `rename` to a unique sibling name — exactly one contender's rename
+// succeeds; losers see ENOENT and simply retry the acquire loop.
+//
+// Re-entrant per process: `workspaceInstall` holds the root-prefix lock for
+// the whole workspace flow while the inner `installPackagesNative` calls
+// re-acquire the same prefix — those just bump a refcount.
+//
+// Escape hatch: GJSIFY_INSTALL_LOCK=0 disables locking entirely (e.g. for a
+// network filesystem with broken rename/mkdir atomicity, or an outer tool
+// that already serializes installs).
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+const LOCK_DIR_NAME = '.gjsify-install-lock';
+const OWNER_FILE = 'owner.json';
+/** Default staleness budget — see the header comment for why 35 min. */
+const DEFAULT_STALE_MS = 35 * 60_000;
+/** Window between a winner's `mkdir` and its `owner.json` write. */
+const ACQUIRE_GRACE_MS = 15_000;
+const WAIT_BASE_MS = 150;
+const WAIT_MAX_MS = 1_000;
+/** Locks held by THIS process, keyed by canonical lock-dir path. */
+const held = new Map();
+let stealCounter = 0;
+function staleMs() {
+    const raw = process.env.GJSIFY_INSTALL_LOCK_STALE_MS;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_STALE_MS;
+}
+function lockingDisabled() {
+    const flag = process.env.GJSIFY_INSTALL_LOCK;
+    if (flag === undefined)
+        return false;
+    const trimmed = flag.trim();
+    return trimmed === '0' || trimmed === 'false';
+}
+/**
+ * Is `pid` a live process on this machine?
+ *
+ * `/proc/<pid>` is the reliable cross-runtime probe on Linux (the primary
+ * target): it works identically under Node and GJS. Elsewhere fall back to a
+ * signal-0 probe — ESRCH means dead, EPERM means alive-but-foreign. The GJS
+ * `process.kill` polyfill shells out and cannot report ESRCH, but GJS only
+ * runs on /proc platforms in practice, so the fallback branch is Node's.
+ * Unknown outcomes are treated as ALIVE (conservative — never steal a lock
+ * we cannot prove abandoned; the mtime staleness budget still applies).
+ */
+function isPidAlive(pid) {
+    try {
+        if (existsSync('/proc/self'))
+            return existsSync(`/proc/${pid}`);
+    }
+    catch {
+        /* fall through to the signal probe */
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+function mtimeMs(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/** Inspect an existing lock dir: held by a live owner, or stale? */
+function assessLock(lockDir) {
+    const ownerPath = join(lockDir, OWNER_FILE);
+    let owner = null;
+    try {
+        owner = JSON.parse(readFileSync(ownerPath, 'utf-8'));
+    }
+    catch {
+        owner = null;
+    }
+    const now = Date.now();
+    if (owner && typeof owner.pid === 'number') {
+        if (!isPidAlive(owner.pid)) {
+            return { stale: true, reason: `owner pid ${owner.pid} is gone`, ownerPid: owner.pid };
+        }
+        const started = typeof owner.startedAt === 'number' ? owner.startedAt : mtimeMs(ownerPath);
+        if (started !== null && now - started > staleMs()) {
+            // Alive but far beyond any plausible install duration — the
+            // observed 0%-CPU hung-install shape. Steal so one wedged
+            // process can't block every future install of this prefix.
+            return {
+                stale: true,
+                reason: `owner pid ${owner.pid} exceeded the ${staleMs()}ms staleness budget`,
+                ownerPid: owner.pid,
+            };
+        }
+        return { stale: false, ownerPid: owner.pid };
+    }
+    // No readable owner.json: the winner may be between mkdir and the owner
+    // write — give it a grace period, then treat the dir as abandoned.
+    const dirMtime = mtimeMs(lockDir);
+    if (dirMtime === null)
+        return { stale: false }; // vanished — retry mkdir
+    if (now - dirMtime > ACQUIRE_GRACE_MS) {
+        return { stale: true, reason: 'no owner recorded within the acquire grace period' };
+    }
+    return { stale: false };
+}
+/**
+ * Atomically claim + remove a stale lock dir. Returns `true` when THIS
+ * process won the claim (the rename succeeded), `false` when another
+ * contender got there first — the caller just retries its acquire loop.
+ */
+function stealStaleLock(lockDir) {
+    const claimed = `${lockDir}.stale-${process.pid}-${++stealCounter}`;
+    try {
+        renameSync(lockDir, claimed);
+    }
+    catch {
+        return false; // lost the race (ENOENT) — someone else claimed/released it
+    }
+    try {
+        rmSync(claimed, { recursive: true, force: true });
+    }
+    catch {
+        /* a leftover claimed dir is inert — it is not the lock path */
+    }
+    return true;
+}
+function abortErr(signal) {
+    const reason = signal && 'reason' in signal ? signal.reason : undefined;
+    if (reason instanceof Error)
+        return reason;
+    const err = new Error('Aborted');
+    err.name = 'AbortError';
+    return err;
+}
+function delay(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolveP, reject) => {
+        const onAbort = () => {
+            clearTimeout(id);
+            reject(abortErr(signal));
+        };
+        const id = setTimeout(() => {
+            signal?.removeEventListener?.('abort', onAbort);
+            resolveP();
+        }, ms);
+        if (signal?.aborted) {
+            clearTimeout(id);
+            reject(abortErr(signal));
+            return;
+        }
+        signal?.addEventListener?.('abort', onAbort, { once: true });
+    });
+}
+function makeHandle(lockDir) {
+    let released = false;
+    return {
+        release() {
+            if (released)
+                return;
+            released = true;
+            const entry = held.get(lockDir);
+            if (!entry)
+                return;
+            entry.count--;
+            if (entry.count > 0)
+                return;
+            held.delete(lockDir);
+            // Only remove the on-disk dir when it is still OURS — a staleness
+            // steal could have handed the path to another process meanwhile.
+            try {
+                const owner = JSON.parse(readFileSync(join(lockDir, OWNER_FILE), 'utf-8'));
+                if (owner.nonce !== undefined && owner.nonce !== entry.nonce)
+                    return;
+            }
+            catch {
+                /* unreadable owner — we created the dir, attempt removal */
+            }
+            try {
+                rmSync(lockDir, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort: a leftover lock is reclaimed by staleness */
+            }
+        },
+    };
+}
+/**
+ * Acquire the cross-process install lock for `prefix`. Resolves once this
+ * process may mutate `<prefix>/node_modules` + `<prefix>/gjsify-lock.json`;
+ * the caller MUST `release()` in a `finally`. Waits (with backoff) while a
+ * live concurrent install holds the lock; steals provably-stale locks (dead
+ * owner pid / exceeded staleness budget). `signal` aborts the wait — wired
+ * to the overall install budget so a waiter never outlives its own timeout.
+ */
+export async function acquireInstallLock(prefix, opts = {}) {
+    if (lockingDisabled()) {
+        return {
+            release() {
+                /* locking disabled — nothing to release */
+            },
+        };
+    }
+    // Canonicalize so two spellings of the same prefix (symlink, relative
+    // path) share one re-entrancy slot.
+    let canonicalPrefix;
+    try {
+        canonicalPrefix = realpathSync(prefix);
+    }
+    catch {
+        canonicalPrefix = resolve(prefix);
+    }
+    const lockDir = join(canonicalPrefix, 'node_modules', LOCK_DIR_NAME);
+    const heldEntry = held.get(lockDir);
+    if (heldEntry) {
+        heldEntry.count++;
+        return makeHandle(lockDir);
+    }
+    mkdirSync(dirname(lockDir), { recursive: true });
+    const nonce = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    let waitMs = WAIT_BASE_MS;
+    let announcedWait = false;
+    while (true) {
+        if (opts.signal?.aborted)
+            throw abortErr(opts.signal);
+        try {
+            mkdirSync(lockDir); // non-recursive → atomic exclusive create
+            writeFileSync(join(lockDir, OWNER_FILE), JSON.stringify({ pid: process.pid, nonce, startedAt: Date.now() }));
+            held.set(lockDir, { count: 1, nonce });
+            return makeHandle(lockDir);
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+        const verdict = assessLock(lockDir);
+        if (verdict.stale) {
+            if (stealStaleLock(lockDir)) {
+                console.warn(`gjsify install: removed stale install lock (${verdict.reason}) — ${lockDir}`);
+            }
+            continue; // retry mkdir immediately (we or another stealer moved it)
+        }
+        if (!announcedWait) {
+            announcedWait = true;
+            const who = verdict.ownerPid !== undefined ? ` (pid ${verdict.ownerPid})` : '';
+            console.warn(`gjsify install: waiting for a concurrent install${who} to release ${lockDir} …`);
+        }
+        await delay(waitMs, opts.signal);
+        waitMs = Math.min(Math.round(waitMs * 1.6), WAIT_MAX_MS);
+    }
+}

package/lib/utils/run-node.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Walk up from `startDir` looking for `<node_modules>/@gjsify/node-gi`. Returns
+ * the package directory, or null when it is not installed anywhere on the chain.
+ * A plain fs walk (works identically on Node and GJS) — Node's own resolver is
+ * not available under the GJS-bundled CLI.
+ */
+export declare function resolveNodeGi(startDir: string): string | null;
+/** Pick the node executable: the current one when on Node, else PATH `node`. */
+export declare function nodeBinary(): string;
+export interface RunNodeBundleOptions {
+    /** Exit this process with code 0 once the child succeeds (terminal callers). */
+    exitOnSuccess?: boolean;
+}
+/**
+ * Run a `--app node` bundle on Node.js, auto-setting LD_LIBRARY_PATH and
+ * GI_TYPELIB_PATH for any installed native gjsify packages (same detection as
+ * {@link runGjsBundle}). Verifies `@gjsify/node-gi` is resolvable first and
+ * throws a clear, actionable error otherwise.
+ */
+export declare function runNodeBundle(bundlePath: string, extraArgs?: string[], options?: RunNodeBundleOptions): Promise<void>;

package/lib/utils/run-node.js

@@ -0,0 +1,85 @@
+// Shared utility for running a `--app node` bundle on Node.js with the native
+// typelib env wired the same way `runGjsBundle` does.
+//
+// A `gjsify build --app node` bundle of a `gi://` source runs the GObject stack
+// through `@gjsify/node-gi` (the Axis-5 reverse bridge). Two things have to be
+// true at runtime:
+//
+//   1. `@gjsify/node-gi` must resolve from the project — it is kept EXTERNAL by
+//      the bundler (a native addon), so it has to physically exist in the
+//      consumer's node_modules. We verify this up front and emit a clear hint
+//      instead of letting Node throw `ERR_MODULE_NOT_FOUND` deep in the bundle.
+//   2. `gi://Gtk` / `gi://Adw` etc. must resolve. System typelibs come from the
+//      default GI search path, but any `@gjsify/*` Vala bridge a story pulls in
+//      ships its typelib in `prebuilds/` — so we reuse the SAME
+//      `computeNativeEnvForBundle()` walker `runGjsBundle` uses to prepend
+//      `GI_TYPELIB_PATH` / `LD_LIBRARY_PATH`. It is a no-op when no native
+//      gjsify packages are present (the storybook's common case).
+//
+// The node binary is `process.execPath` when the CLI itself runs under Node, and
+// the PATH `node` otherwise (under the committed GJS bundle `process.execPath` is
+// `gjs`, which cannot run a `--app node` bundle).
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { computeNativeEnvForBundle } from './run-gjs.js';
+/**
+ * Walk up from `startDir` looking for `<node_modules>/@gjsify/node-gi`. Returns
+ * the package directory, or null when it is not installed anywhere on the chain.
+ * A plain fs walk (works identically on Node and GJS) — Node's own resolver is
+ * not available under the GJS-bundled CLI.
+ */
+export function resolveNodeGi(startDir) {
+    let dir = resolve(startDir);
+    while (true) {
+        const candidate = join(dir, 'node_modules', '@gjsify', 'node-gi', 'package.json');
+        if (existsSync(candidate))
+            return join(dir, 'node_modules', '@gjsify', 'node-gi');
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Pick the node executable: the current one when on Node, else PATH `node`. */
+export function nodeBinary() {
+    return isNode() && process.execPath ? process.execPath : 'node';
+}
+/**
+ * Run a `--app node` bundle on Node.js, auto-setting LD_LIBRARY_PATH and
+ * GI_TYPELIB_PATH for any installed native gjsify packages (same detection as
+ * {@link runGjsBundle}). Verifies `@gjsify/node-gi` is resolvable first and
+ * throws a clear, actionable error otherwise.
+ */
+export async function runNodeBundle(bundlePath, extraArgs = [], options = {}) {
+    const cwd = process.cwd();
+    if (!resolveNodeGi(cwd)) {
+        throw new Error('Cannot run the storybook on Node: `@gjsify/node-gi` is not installed.\n' +
+            'Add @gjsify/node-gi as a dependency to run the storybook on Node, e.g.:\n' +
+            '  "devDependencies": { "@gjsify/node-gi": "^0.13.0" }');
+    }
+    const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(bundlePath, cwd);
+    const env = { ...process.env, ...nativeEnv };
+    const nodeBin = nodeBinary();
+    const nodeArgs = [bundlePath, ...extraArgs];
+    // Echo the exact command (stderr, so a child speaking a protocol on stdout
+    // stays uncontaminated) so users can reproduce the run without the wrapper.
+    const cmd = [nodeBin, ...nodeArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
+    console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${cmd}`);
+    const child = spawn(nodeBin, nodeArgs, { env, stdio: 'inherit' });
+    await new Promise((resolvePromise, reject) => {
+        child.on('close', (code) => {
+            if (code !== 0)
+                reject(new Error(`node exited with code ${code}`));
+            else
+                resolvePromise();
+        });
+        child.on('error', reject);
+    }).catch((err) => {
+        console.error(err.message);
+        process.exit(1);
+    });
+    if (options.exitOnSuccess)
+        process.exit(0);
+}