@gjsify/cli 0.14.0 → 0.16.0

package/lib/actions/build.js

@@ -8,6 +8,7 @@ import { dirname, extname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { normalizeBundlerOptions, mergeBundlerOptions } from '../utils/normalize-bundler-options.js';
+import { inputSourceDirs, isOutdirInsideSource, libraryOutputLeakError } from '../utils/library-output.js';
 const DEFAULT_GJS_SHEBANG = '#!/usr/bin/env -S gjs -m';
 /**
  * `true` when `path` points at a location that's unsafe to use as a build
@@ -83,6 +84,19 @@ export class BuildAction {
         const { verbose, library, typescript, exclude, aliases } = this.configData;
         const lib = library ?? {};
         const userBundler = normalizeBundlerOptions(this.configData);
+        // Refuse to emit the compiled tree into the input source directory.
+        // The outdir is derived below from `dirname(module ?? main)`; when a
+        // package points `main`/`module` at a source entry (`src/index.ts`)
+        // that derivation is `src/`, so preserve-modules would write `.js`
+        // duplicates + a `_virtual/` dir + a nested `src/<pkg>/src` tree next
+        // to the sources. An explicit `--outdir` is the escape hatch and is
+        // trusted; only the DERIVED default is guarded.
+        const cwd = process.cwd();
+        const sourceDirs = inputSourceDirs(userBundler.input, cwd);
+        const assertDerivedOutdirSafe = (outdir) => {
+            if (outdir && isOutdirInsideSource(outdir, sourceDirs, cwd))
+                throw libraryOutputLeakError(outdir);
+        };
         const moduleOutdir = lib.module ? dirname(lib.module) : undefined;
         const mainOutdir = lib.main ? dirname(lib.main) : undefined;
         const moduleOutExt = lib.module ? extname(lib.module) : '.js';
@@ -92,6 +106,10 @@ export class BuildAction {
         const pnpPlugins = pnp ? [pnp] : [];
         const results = [];
         if (multipleBuilds) {
+            // Both outdirs are derived from module/main — always guard them
+            // (`--outdir` is not consulted on the multi-output path).
+            assertDerivedOutdirSafe(moduleOutdir);
+            assertDerivedOutdirSafe(mainOutdir);
             const moduleFormat = moduleOutdir.includes('/cjs') || moduleOutExt === '.cjs' ? 'cjs' : 'esm';
             results.push(await runOneLibraryBuild({
                 pluginOpts: {
@@ -122,9 +140,14 @@ export class BuildAction {
             }));
         }
         else {
+            const explicitOutdir = userBundler.output?.dir;
             const outfilePath = userBundler.output?.file ?? lib.module ?? lib.main;
             const outExt = outfilePath ? extname(outfilePath) : '.js';
-            const outdir = userBundler.output?.dir ?? (outfilePath ? dirname(outfilePath) : undefined);
+            const outdir = explicitOutdir ?? (outfilePath ? dirname(outfilePath) : undefined);
+            // Only the DERIVED default is a footgun; a user-supplied --outdir
+            // is trusted (the documented escape hatch).
+            if (explicitOutdir === undefined)
+                assertDerivedOutdirSafe(outdir);
             const format = userBundler.output?.format ??
                 (outdir?.includes('/cjs') || outExt === '.cjs' ? 'cjs' : 'esm');
             results.push(await runOneLibraryBuild({

package/lib/cli-app.js

@@ -19,7 +19,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yargs from 'yargs';
-import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, 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, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
+import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, 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, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
@@ -103,6 +103,7 @@ export async function runCli(argv) {
         .command(login.command, login.description, login.builder, login.handler)
         .command(logout.command, logout.description, logout.builder, logout.handler)
         .command(trust.command, trust.description, trust.builder, trust.handler)
+        .command(onboard.command, onboard.description, onboard.builder, onboard.handler)
         .command(selfUpdate.command, selfUpdate.description, selfUpdate.builder, selfUpdate.handler)
         .command(generateInstaller.command, generateInstaller.description, generateInstaller.builder, generateInstaller.handler)
         .command(uninstall.command, uninstall.description, uninstall.builder, uninstall.handler)

package/lib/commands/foreach.d.ts

@@ -13,6 +13,7 @@ interface ForeachOptions {
     verbose?: boolean;
     jobs?: number;
     exec?: boolean;
+    cached?: boolean;
 }
 export declare const foreachCommand: Command<unknown, ForeachOptions>;
 export {};

package/lib/commands/foreach.js

@@ -14,6 +14,7 @@ import { cpus } from 'node:os';
 import { buildDependencyGraph, discoverWorkspaces, filterWorkspaces, topologicalSort, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { prefixLines } from '../utils/prefixed-output.js';
+import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 // Every child spawned by spawnPrefixed registers here so fail-fast can
 // terminate the whole in-flight set instead of waiting on it. On CI a
@@ -238,6 +239,10 @@ export const foreachCommand = {
         description: 'Treat <script> [args..] as an arbitrary command (yarn `workspaces foreach exec`-equivalent) instead of a package.json script lookup. Workspace filtering by script presence is skipped. Use `-- <cmd> <args...>` to pass flags to the command without yargs intercepting them.',
         type: 'boolean',
         default: false,
+    })
+        .option('cached', {
+        description: 'Content-hash build cache (ADR 0006): skip a workspace whose inputs (src/**, package.json, tsconfig*.json, transitive workspace deps, toolchain versions) are unchanged and restore its stored outputs instead; on miss run the script and store the output dirs it modified. Script mode only. Default from GJSIFY_BUILD_CACHE=1.',
+        type: 'boolean',
     })
         .option('shard', {
         description: 'Run only a deterministic slice "<index>/<total>" (1-based) of the matched workspaces, e.g. --shard 2/4. For fanning a long run across parallel CI jobs. Partitions by sorted name (round-robin) so the shards are disjoint and their union is the full set; order-independent, so safe for tests but NOT for ordered builds.',
@@ -352,20 +357,43 @@ export const foreachCommand = {
         // `cmd` is guaranteed string at this point — both branches above
         // exit on undefined, but TS doesn't narrow through them.
         const finalCmd = cmd;
+        // Content-hash build cache (ADR 0006 phase 1). Explicit --cached /
+        // --no-cached wins; GJSIFY_BUILD_CACHE=1 is the env default so a
+        // whole root-script chain (`gjsify run build`) can opt in without
+        // editing every nested invocation. Keys are computed against ALL
+        // discovered workspaces (a dep outside the --include filter still
+        // participates in its dependents' keys).
+        const cached = args.cached ?? buildCacheEnabledByEnv();
+        if (args.cached === true && exec) {
+            // Only the EXPLICIT flag errors — the GJSIFY_BUILD_CACHE env
+            // default covers whole script chains (CI sets it once for the
+            // build job) where an --exec invocation is simply not cacheable.
+            console.error('gjsify foreach: --cached only applies to script mode, not --exec.');
+            process.exit(1);
+        }
+        const cache = cached && !exec
+            ? new BuildCacheRunner({
+                root: cwd,
+                workspaces: allWorkspaces,
+                script: finalCmd,
+                args: cmdArgs,
+                targets: selected.map((w) => w.name),
+            })
+            : undefined;
         try {
             if (args.parallel && !args.topological && !args['topological-dev']) {
                 const jobs = args.jobs && args.jobs > 0 ? args.jobs : cpus().length;
-                await runParallel(selected, finalCmd, cmdArgs, jobs, verbose, exec);
+                await runParallel(selected, finalCmd, cmdArgs, jobs, verbose, exec, cache);
             }
             else if (args.parallel) {
                 // Topological + parallel: each workspace starts as soon as its
                 // deps (in the selected set) have finished. Yarn calls this
                 // "topological order with concurrency"; we cap at --jobs.
                 const jobs = args.jobs && args.jobs > 0 ? args.jobs : cpus().length;
-                await runTopologicalParallel(selected, finalCmd, cmdArgs, jobs, verbose, args['topological-dev'] === true, exec);
+                await runTopologicalParallel(selected, finalCmd, cmdArgs, jobs, verbose, args['topological-dev'] === true, exec, cache);
             }
             else {
-                await runSequential(selected, finalCmd, cmdArgs, verbose, exec);
+                await runSequential(selected, finalCmd, cmdArgs, verbose, exec, cache);
             }
         }
         catch (err) {
@@ -382,25 +410,25 @@ export const foreachCommand = {
         process.exit(0);
     },
 };
-async function runSequential(workspaces, script, args, verbose, exec) {
+async function runSequential(workspaces, script, args, verbose, exec, cache) {
     for (const ws of workspaces) {
-        await runOne(ws, script, args, /* prefixOutput */ false, verbose, exec);
+        await runOne(ws, script, args, /* prefixOutput */ false, verbose, exec, cache);
     }
 }
-async function runParallel(workspaces, script, args, concurrency, verbose, exec) {
+async function runParallel(workspaces, script, args, concurrency, verbose, exec, cache) {
     let cursor = 0;
     const workers = [];
     for (let w = 0; w < concurrency; w++) {
         workers.push((async () => {
             while (cursor < workspaces.length) {
                 const i = cursor++;
-                await runOne(workspaces[i], script, args, /* prefixOutput */ true, verbose, exec);
+                await runOne(workspaces[i], script, args, /* prefixOutput */ true, verbose, exec, cache);
             }
         })());
     }
     await Promise.all(workers);
 }
-async function runTopologicalParallel(workspaces, script, args, concurrency, verbose, includeDev, exec) {
+async function runTopologicalParallel(workspaces, script, args, concurrency, verbose, includeDev, exec, cache) {
     const selectedNames = new Set(workspaces.map((w) => w.name));
     const remaining = new Map();
     for (const ws of workspaces) {
@@ -439,9 +467,7 @@ async function runTopologicalParallel(workspaces, script, args, concurrency, ver
     return new Promise((resolve, reject) => {
         let error = null;
         let lastActivity = Date.now();
-        const describeInflight = () => [...inflightStarts.entries()]
-            .map(([n, t]) => `${n} (${Math.round((Date.now() - t) / 1000)}s)`)
-            .join(', ');
+        const describeInflight = () => [...inflightStarts.entries()].map(([n, t]) => `${n} (${Math.round((Date.now() - t) / 1000)}s)`).join(', ');
         const failFast = (e) => {
             // First error wins. KILL the in-flight siblings instead of
             // waiting for them (yarn waits — but a sibling's nested build
@@ -488,7 +514,7 @@ async function runTopologicalParallel(workspaces, script, args, concurrency, ver
                 if (liveProgress) {
                     console.error(`[gjsify foreach] start ${next} (${done.size}/${total} done, ${inflight} in flight)`);
                 }
-                runOne(byName.get(next), script, args, /* prefixOutput */ true, verbose, exec)
+                runOne(byName.get(next), script, args, /* prefixOutput */ true, verbose, exec, cache)
                     .then(() => {
                     done.add(next);
                 })
@@ -528,7 +554,7 @@ async function runTopologicalParallel(workspaces, script, args, concurrency, ver
         pump();
     });
 }
-async function runOne(ws, script, args, prefixOutput, verbose, exec) {
+async function runOne(ws, script, args, prefixOutput, verbose, exec, cache) {
     if (exec) {
         // Arbitrary-command mode: spawn `<script> <args...>` directly
         // (yarn `workspaces foreach exec`-equivalent). Used by callers
@@ -540,6 +566,13 @@ async function runOne(ws, script, args, prefixOutput, verbose, exec) {
         await spawnPrefixed(script, args, ws.location, prefixOutput ? `[${ws.name}] ` : null);
         return;
     }
+    // Content-hash build cache: on a key hit the stored outputs are
+    // restored and the script is skipped entirely; on a miss the output
+    // dirs are snapshotted so only the dirs the script MODIFIED are stored
+    // after it succeeds (never a committed, no-build lib/).
+    if (cache && cache.tryRestore(ws))
+        return;
+    const before = cache?.snapshotOutputs(ws);
     // Use the same package manager that invoked us — yarn under yarn,
     // npm under npm, gjsify under gjsify. Default to `npm` for portability
     // when nothing is detectable; the script-runner (D.5) will replace
@@ -550,6 +583,8 @@ async function runOne(ws, script, args, prefixOutput, verbose, exec) {
         console.error(`[${ws.name}] $ ${runner} ${argv.join(' ')}`);
     }
     await spawnPrefixed(runner, argv, ws.location, prefixOutput ? `[${ws.name}] ` : null);
+    if (cache && before)
+        cache.storeAfterSuccess(ws, before);
 }
 function detectPackageManager() {
     // Under GJS there is no Node — neither `npm` nor `yarn` can run scripts, so

package/lib/commands/index.d.ts

@@ -20,6 +20,7 @@ export * from './whoami.js';
 export * from './login.js';
 export * from './logout.js';
 export * from './trust.js';
+export * from './onboard.js';
 export * from './self-update.js';
 export * from './generate-installer.js';
 export * from './uninstall.js';

package/lib/commands/index.js

@@ -20,6 +20,7 @@ export * from './whoami.js';
 export * from './login.js';
 export * from './logout.js';
 export * from './trust.js';
+export * from './onboard.js';
 export * from './self-update.js';
 export * from './generate-installer.js';
 export * from './uninstall.js';

package/lib/commands/install.js

@@ -15,9 +15,18 @@
 // Workspace install (`gjsify install` in a monorepo root with a
 // `"workspaces"` field) hoists every workspace's externals into the root
 // `node_modules/` and symlinks `workspace:*` / `workspace:^` / `workspace:~`
-// refs to their target source. Open follow-ups (see STATUS.md "Open TODOs"):
-// per-workspace dedup of conflicting transitive version ranges (first-match
-// wins today).
+// refs to their target source. Conflicting version ranges of the same
+// external dep from different workspaces still share ONE hoisted root copy
+// (a real per-workspace dedup pass is Phase D.8, see STATUS.md), but since
+// ADR 0001 step 3 the resolver surfaces every such conflict loudly —
+// `[gjsify] warning: version conflict for <pkg> …` names both ranges, the
+// workspaces that requested them, and the version that actually won.
+//
+// Concurrency (ADR 0001 step 2): every mutation of an install prefix —
+// project node_modules/, gjsify-lock.json, the user-global prefix — runs
+// under a per-prefix cross-process lock (utils/install-lock.ts). Installs
+// into different prefixes stay parallel; the shared XDG tarball/packument
+// caches need no lock because their writes are atomic tmp+rename.
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
@@ -25,6 +34,8 @@ import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
 import { detectNativePackages } from '../utils/detect-native-packages.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
+import { atomicWriteStrict } from '../utils/install-cache-fs.js';
+import { acquireInstallLock } from '../utils/install-lock.js';
 import { binDirOnPath, defaultGlobalLayout, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
 // Default 30min wall-clock budget for the full install. Big workspaces
@@ -268,40 +279,50 @@ async function projectInstallNative(args, signal) {
     const progress = makeProgressReporter({
         enabled: !args.verbose && !args.quiet && args.progress !== false,
     });
-    const result = await installPackages({
-        prefix: cwd,
-        specs,
-        verbose: args.verbose,
-        // --immutable consumes the lockfile verbatim and must NOT rewrite
-        // it (the whole point is byte-stability under CI).
-        lockfile: !args.immutable,
-        frozen: args.immutable,
-        refreshLockfile: args['refresh-lockfile'],
-        signal,
-        progress,
-    });
-    // Update package.json only when the user passed explicit packages
-    // (the `gjsify install <pkg>...` add-a-dep flow). The no-args refresh
-    // flow doesn't mutate manifest entries.
-    if (args.packages && args.packages.length > 0 && pkg) {
-        const kind = depKindFromArgs(args);
-        for (const spec of args.packages) {
-            const { name, range } = parseSpec(spec);
-            const installed = result.installed.find((r) => r.name === name);
-            const finalRange = range ?? (installed ? defaultRangeFromVersion(installed.version) : 'latest');
-            addDependencyEntry(pkg, name, finalRange, kind);
-        }
-        writePackageJson(pkgPath, pkg);
-        // Re-sync the lockfile's `requested` field with what
-        // `projectSpecsFromPackageJson()` will return on the next
-        // invocation. Without this, a `gjsify install foo` (bare name,
-        // lockfile records `"foo"`) followed by `gjsify install
-        // --immutable` (reads package.json → spec `"foo@^1.2.3"`) would
-        // surface a spurious drift error.
-        if (!args.immutable) {
-            syncLockfileRequested(cwd, projectSpecsFromPackageJson(pkg));
+    // Hold the per-prefix lock across the install AND the manifest/lockfile
+    // sync that follows, so a concurrent `gjsify install <pkg>` in the same
+    // project can't interleave its package.json / gjsify-lock.json writes
+    // with ours. `installPackages` re-acquires the same lock re-entrantly.
+    const lock = await acquireInstallLock(cwd, { signal });
+    try {
+        const result = await installPackages({
+            prefix: cwd,
+            specs,
+            verbose: args.verbose,
+            // --immutable consumes the lockfile verbatim and must NOT rewrite
+            // it (the whole point is byte-stability under CI).
+            lockfile: !args.immutable,
+            frozen: args.immutable,
+            refreshLockfile: args['refresh-lockfile'],
+            signal,
+            progress,
+        });
+        // Update package.json only when the user passed explicit packages
+        // (the `gjsify install <pkg>...` add-a-dep flow). The no-args refresh
+        // flow doesn't mutate manifest entries.
+        if (args.packages && args.packages.length > 0 && pkg) {
+            const kind = depKindFromArgs(args);
+            for (const spec of args.packages) {
+                const { name, range } = parseSpec(spec);
+                const installed = result.installed.find((r) => r.name === name);
+                const finalRange = range ?? (installed ? defaultRangeFromVersion(installed.version) : 'latest');
+                addDependencyEntry(pkg, name, finalRange, kind);
+            }
+            writePackageJson(pkgPath, pkg);
+            // Re-sync the lockfile's `requested` field with what
+            // `projectSpecsFromPackageJson()` will return on the next
+            // invocation. Without this, a `gjsify install foo` (bare name,
+            // lockfile records `"foo"`) followed by `gjsify install
+            // --immutable` (reads package.json → spec `"foo@^1.2.3"`) would
+            // surface a spurious drift error.
+            if (!args.immutable) {
+                syncLockfileRequested(cwd, projectSpecsFromPackageJson(pkg));
+            }
         }
     }
+    finally {
+        lock.release();
+    }
 }
 function syncLockfileRequested(cwd, specs) {
     const lockPath = join(cwd, 'gjsify-lock.json');
@@ -315,7 +336,9 @@ function syncLockfileRequested(cwd, specs) {
             return; // Already in sync; preserve byte-stability.
         }
         lock.requested = specs;
-        writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
+        // Atomic tmp+rename — same rationale as the backend's lockfile
+        // writer: a torn gjsify-lock.json breaks the next `--immutable`.
+        atomicWriteStrict(lockPath, JSON.stringify(lock, null, 2) + '\n');
     }
     catch {
         // Best-effort sync; if the lockfile is malformed, the next
@@ -328,23 +351,45 @@ function syncLockfileRequested(cwd, specs) {
  *   2. Aggregate the union of their external (non-`workspace:`) deps.
  *   3. Run the native install backend ONCE at the root prefix so all
  *      externals land in a single `node_modules/` (poor-man's hoisting —
- *      we don't deduplicate version-range conflicts yet, the BFS resolver
- *      picks first-match).
+ *      workspaces with conflicting ranges of the same dep share one hoisted
+ *      copy; the resolver emits a loud `[gjsify] warning: version conflict`
+ *      naming both sides and the version that won).
  *   4. For every `workspace:` reference, symlink the target workspace's
  *      directory into the requesting workspace's `node_modules/<dep>`
  *      so `import '@gjsify/utils'` resolves to the local source.
  *
  * Hoisting strategy is intentionally minimal — per-workspace dedup +
- * nested `node_modules/` for version conflicts are tracked as a follow-up
- * in STATUS.md "Open TODOs".
+ * nested `node_modules/` for cross-workspace version conflicts are the
+ * Phase D.8 follow-up tracked in STATUS.md.
  */
 async function workspaceInstall(cwd, args, signal) {
+    // Hold the root-prefix lock for the WHOLE workspace flow: bin shims,
+    // workspace symlinks and the external install all mutate the root
+    // node_modules/, and a second concurrent workspace install interleaving
+    // its rm+symlink/extract steps with ours corrupts both. The inner
+    // `installPackages` calls re-acquire the same lock re-entrantly (root
+    // prefix) or take the child-workspace lock (scoped overrides) — always
+    // in root→child order, so there is no lock-ordering cycle.
+    const lock = await acquireInstallLock(cwd, { signal });
+    try {
+        await workspaceInstallLocked(cwd, args, signal);
+    }
+    finally {
+        lock.release();
+    }
+}
+/** Body of {@link workspaceInstall}, run while holding the root-prefix lock. */
+async function workspaceInstallLocked(cwd, args, signal) {
     const workspaces = discoverWorkspaces(cwd, { includeRoot: true });
     if (workspaces.length === 0) {
         throw new Error(`gjsify install: ${cwd} has a "workspaces" field but no workspaces were discovered`);
     }
     const byName = new Map(workspaces.map((w) => [w.name, w]));
     const externalSpecs = new Set();
+    // Which workspace(s) declared each external spec — `"<name>@<range>"` →
+    // workspace names. Feeds the resolver's version-conflict warning so it
+    // can attribute both sides of a cross-workspace range conflict.
+    const specOrigins = new Map();
     const symlinks = [];
     for (const ws of workspaces) {
         const m = ws.manifest;
@@ -391,7 +436,14 @@ async function workspaceInstall(cwd, args, signal) {
                 }
                 if (/^(link|file|portal|git\+|https?):/.test(spec))
                     continue;
-                externalSpecs.add(`${depName}@${spec}`);
+                const specKey = `${depName}@${spec}`;
+                externalSpecs.add(specKey);
+                let origins = specOrigins.get(specKey);
+                if (!origins) {
+                    origins = new Set();
+                    specOrigins.set(specKey, origins);
+                }
+                origins.add(ws.name);
             }
         }
     }
@@ -624,6 +676,7 @@ async function workspaceInstall(cwd, args, signal) {
             // symlinks (e.g. a `types-dev/<lib>` workspace that also exists on
             // npm and is pinned transitively in the lockfile).
             workspaceNames: new Set(byName.keys()),
+            specOrigins: new Map([...specOrigins].map(([k, v]) => [k, [...v]])),
         });
     }
     else if (args.verbose) {
@@ -926,28 +979,42 @@ async function installGlobalAndLink(specs, opts) {
     mkdirSync(layout.prefix, { recursive: true });
     console.log(`gjsify install --global  → ${layout.prefix}`);
     console.log(`                  bins → ${layout.binDir}`);
-    const result = await installPackages({
-        prefix: layout.prefix,
-        specs,
-        verbose: opts.verbose,
-    });
-    const packageNames = specs.map(specToPackageName);
-    // A global GJS install of `@gjsify/cli` must also lay down the GJS-native
-    // bundler engine (`@gjsify/rolldown-native`) + the sibling format/CSS
-    // bridges. They are declared OPTIONAL peers of `@gjsify/cli` (so plain
-    // `npm install @gjsify/cli` on Node doesn't force a linux prebuild), and
-    // the native backend doesn't resolve peerDependencies at all — so without
-    // this they'd never be installed, and `gjsify build` would hard-fail under
-    // GJS ("no usable bundler engine"). Installed best-effort at the cli's
-    // resolved version so they move in lockstep with the bundle; a platform
-    // with no published prebuild degrades to a warning. Must run BEFORE
-    // linkGlobalBins so the launcher's detectNativePackages() bakes the
-    // engine's prebuild dirs into the wrapper's GI_TYPELIB_PATH/LD_LIBRARY_PATH.
-    if (packageNames.includes('@gjsify/cli')) {
-        const cliVersion = result.installed.find((r) => r.name === '@gjsify/cli')?.version ?? 'latest';
-        await installGjsEnginePackages(layout.prefix, cliVersion, { verbose: opts.verbose });
+    // The global prefix is SHARED user-wide state — two concurrent
+    // `gjsify install -g` runs (e.g. parallel agent sessions bootstrapping
+    // tooling) used to interleave rm+extract on the same package dirs and
+    // race the launcher writes in ~/.local/bin. Hold the prefix lock across
+    // the install, the engine-package top-up AND the bin linking (ADR 0001).
+    const lock = await acquireInstallLock(layout.prefix, {});
+    try {
+        const result = await installPackages({
+            prefix: layout.prefix,
+            specs,
+            verbose: opts.verbose,
+        });
+        const packageNames = specs.map(specToPackageName);
+        // A global GJS install of `@gjsify/cli` must also lay down the GJS-native
+        // bundler engine (`@gjsify/rolldown-native`) + the sibling format/CSS
+        // bridges. They are declared OPTIONAL peers of `@gjsify/cli` (so plain
+        // `npm install @gjsify/cli` on Node doesn't force a linux prebuild), and
+        // the native backend doesn't resolve peerDependencies at all — so without
+        // this they'd never be installed, and `gjsify build` would hard-fail under
+        // GJS ("no usable bundler engine"). Installed best-effort at the cli's
+        // resolved version so they move in lockstep with the bundle; a platform
+        // with no published prebuild degrades to a warning. Must run BEFORE
+        // linkGlobalBins so the launcher's detectNativePackages() bakes the
+        // engine's prebuild dirs into the wrapper's GI_TYPELIB_PATH/LD_LIBRARY_PATH.
+        if (packageNames.includes('@gjsify/cli')) {
+            const cliVersion = result.installed.find((r) => r.name === '@gjsify/cli')?.version ?? 'latest';
+            await installGjsEnginePackages(layout.prefix, cliVersion, { verbose: opts.verbose });
+        }
+        const created = linkGlobalBins(packageNames, layout);
+        reportLinkedBins(created, layout.binDir);
+    }
+    finally {
+        lock.release();
     }
-    const created = linkGlobalBins(packageNames, layout);
+}
+function reportLinkedBins(created, binDir) {
     if (created.length === 0) {
         console.warn('\nNo bins declared (neither `gjsify.bin` nor `bin` in package.json) — nothing was symlinked.');
     }
@@ -957,9 +1024,9 @@ async function installGlobalAndLink(specs, opts) {
             console.log(`  • ${e.link}  →  ${e.target}`);
         }
     }
-    if (created.length > 0 && !binDirOnPath(layout.binDir)) {
-        console.warn(`\nNote: ${layout.binDir} is not on your PATH.\n` +
-            `Add it to your shell rc file:\n  export PATH="${layout.binDir}:$PATH"`);
+    if (created.length > 0 && !binDirOnPath(binDir)) {
+        console.warn(`\nNote: ${binDir} is not on your PATH.\n` +
+            `Add it to your shell rc file:\n  export PATH="${binDir}:$PATH"`);
     }
 }
 async function runPostInstallChecks() {

package/lib/commands/login.d.ts

@@ -6,5 +6,34 @@ interface LoginOptions {
     otp?: string;
     json?: boolean;
 }
+/** Options for the reusable {@link runLogin} flow. */
+export interface RunLoginOptions {
+    registry?: string;
+    scope?: string;
+    username?: string;
+    otp?: string;
+    /** Directory whose `.npmrc` seeds scope/registry resolution. Default: cwd. */
+    cwd?: string;
+}
+/** Successful login result. */
+export interface LoginResult {
+    username: string;
+    /** Registry URL (with trailing slash). */
+    registry: string;
+    /** Path of the `.npmrc` the token was written to. */
+    npmrcPath: string;
+}
+/** Thrown by {@link runLogin} on any recoverable login failure (bad creds, no token, …). */
+export declare class LoginError extends Error {
+    constructor(message: string);
+}
 export declare const loginCommand: Command<unknown, LoginOptions>;
+/**
+ * The `gjsify login` core, extracted so `gjsify onboard` can authenticate the
+ * user when the whoami gate fails. Prompts for username + password (unless
+ * provided), PUTs the CouchDB user doc, writes the token to the userconfig
+ * `.npmrc`, and verifies it with `whoami`. Throws {@link LoginError} on any
+ * recoverable failure (the command handler / onboard present it).
+ */
+export declare function runLogin(opts: RunLoginOptions): Promise<LoginResult>;
 export {};