@gjsify/cli 0.36.0 → 0.38.0

package/lib/utils/auth-npmrc.js

@@ -1,11 +1,6 @@
-// Write/remove npm auth tokens in the user's `.npmrc` — the write side of
-// `load-npmrc.ts` (which only reads). Used by `gjsify login` / `gjsify logout`.
-//
-// npm stores the token under a "nerf-dart" key: the registry URL with the
-// protocol stripped, e.g. `//registry.npmjs.org/:_authToken=<token>`. We upsert
-// exactly that line in the userconfig file (`$NPM_CONFIG_USERCONFIG` or
-// `~/.npmrc`), preserving every other line, and chmod it to 0600 (it holds a
-// credential).
+// The write side of `load-npmrc.ts`: `gjsify login`/`logout` upsert or drop one
+// `_authToken` line in the userconfig `.npmrc` (`$NPM_CONFIG_USERCONFIG` or
+// `~/.npmrc`), preserving every other line and chmod'ing the file to 0600.
 import { existsSync, readFileSync, writeFileSync, chmodSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
@@ -14,8 +9,9 @@ export function userconfigNpmrcPath() {
     return process.env.NPM_CONFIG_USERCONFIG || join(homedir(), '.npmrc');
 }
 /**
- * The npm "nerf-dart" key for a registry: the URL with the protocol removed,
- * keeping the host + path with a trailing slash — `//registry.npmjs.org/`.
+ * The npm "nerf-dart" key for a registry — the URL with the protocol removed,
+ * host + path, trailing slash: `//registry.npmjs.org/`. npm keys credentials by
+ * this, so the exact shape is what makes the token findable.
  */
 export function nerfDart(registry) {
     const u = new URL(registry);
@@ -42,10 +38,7 @@ function writeUserconfig(path, content) {
         /* non-POSIX filesystem */
     }
 }
-/**
- * Upsert `<nerf-dart>:_authToken=<token>` in the userconfig `.npmrc`, preserving
- * all other lines. Returns the file path written.
- */
+/** Upsert `<nerf-dart>:_authToken=<token>`; returns the file path written. */
 export function writeAuthToken(registry, token) {
     const path = userconfigNpmrcPath();
     const key = authTokenKey(registry);
@@ -54,15 +47,15 @@ export function writeAuthToken(registry, token) {
     const lines = existing.length ? existing.split('\n') : [];
     let replaced = false;
     const next = lines.map((l) => {
-        // Match the key at the start of the line (ignore `${...}` placeholder
-        // values too — we always overwrite with the concrete token).
+        // Matches on the KEY only, so a `${VAR}` placeholder value is overwritten
+        // with the concrete token like any other.
         if (l.replace(/\s+/g, '').startsWith(`${key}=`)) {
             replaced = true;
             return line;
         }
         return l;
     });
-    // Strip trailing blank lines so we don't accumulate them across rewrites.
+    // Or they accumulate across rewrites.
     while (next.length && next[next.length - 1].trim() === '')
         next.pop();
     if (!replaced)
@@ -70,10 +63,7 @@ export function writeAuthToken(registry, token) {
     writeUserconfig(path, next.join('\n') + '\n');
     return path;
 }
-/**
- * Remove the `<nerf-dart>:_authToken=` line for a registry from the userconfig
- * `.npmrc`. Returns `{ path, removed }` — `removed` is false if no line matched.
- */
+/** Drop the registry's `_authToken` line; `removed` is false when none matched. */
 export function removeAuthToken(registry) {
     const path = userconfigNpmrcPath();
     const key = authTokenKey(registry);

package/lib/utils/bin-shim.d.ts

@@ -130,31 +130,16 @@ export declare function buildLauncherShims(opts: {
  * script chain: the self-relative `@loader_path` rpath that
  * `check-prebuild-loader-path.mjs` enforces is what actually has to carry it.
  *
- * NOT EXTENDED WITH THE HOST'S GI LIBDIRS — a decision, not an oversight.
- * `buildNativeEnv()` now puts `systemGiLibraryDirs()` on the gjs CHILD's
- * `DYLD_FALLBACK_LIBRARY_PATH`, which repairs every command that goes through this
- * CLI. A launcher that `exec`s a GJS bundle DIRECTLY — `gjsify install -g` on a
- * package whose `gjsify.bin` is a GTK app — has no CLI in the loop and still
- * carries the gap.
- *
- * The MECHANISM would work, and that was measured on the macOS 15.7.8 VM rather
- * than assumed. It is a finer point than the caveat above: what SIP strips is an
- * INHERITED `DYLD_*` at the `/bin/sh` exec, so a value this preamble exports
- * ITSELF survives the following `exec gjs` (an unprotected Homebrew binary) and
- * `Gtk.init()` then succeeds. What is missing is a shape worth having:
- *
- *   - BAKING `systemGiLibraryDirs()` in at write time reintroduces precisely the
- *     snapshot this function exists to remove — a launcher is routinely written
- *     BEFORE `brew install gtk4`, and would bake nothing while saying nothing.
- *   - RE-DERIVING it in shell means a THIRD copy of a rule that already has two,
- *     pinned in agreement by `system-gi.spec.ts` — and shell can express only one
- *     of its three sources (the probed prefixes; `pkg-config` would be a spawn on
- *     every launch), so that copy would be knowingly partial, in the one language
- *     nothing here type-checks.
- *
- * So the gap is recorded in `status/open-todos.md` with the measurement attached
- * instead of being closed by a mechanism that drifts. Closing it properly means
- * teaching such a launcher to defer to the CLI, not to re-derive.
+ * IT DOES export dyld's own default fallback list on darwin — see
+ * {@link dyldFallbackPreamble}. That is a CONSTANT, so it carries none of the
+ * staleness that rules out the alternatives: BAKING `systemGiLibraryDirs()` in
+ * at write time reintroduces the snapshot this function exists to remove (a
+ * launcher is routinely written BEFORE `brew install gtk4`), and RE-DERIVING it
+ * in shell would be a knowingly partial THIRD copy of a two-copy rule, in the
+ * one language nothing here type-checks. The REMAINING gap — a host GI stack
+ * under a prefix dyld never defaulted to, `/opt/homebrew/lib` on Apple silicon —
+ * stays in `status/open-todos.md`, to be closed by teaching such a launcher to
+ * defer to the CLI rather than to re-derive.
  *
  * @param scanRoot Directory whose `node_modules` is globbed at launch time.
  * @param bakedDirs Prebuild dirs found at write time; entries outside `scanRoot`
@@ -166,6 +151,36 @@ export declare function buildNativeEnvPreamble(scanRoot: string, bakedDirs?: rea
     arch?: string;
     libc?: HostLibc | null;
 }): string;
+/**
+ * The darwin half of {@link buildNativeEnvPreamble}: put dyld's OWN default
+ * fallback list back, from inside the launcher.
+ *
+ * MEASURED on the macOS 15.7.9 x86_64 VM against the published 0.37.0: every
+ * `gjsify` command died in `dlopen(libsoup-3.0.0.dylib)` — before downloading
+ * anything, the CLI's own npm fetcher going through Soup — with a dyld search
+ * list that ended at `/usr/lib` and never held `/usr/local/lib`, where Homebrew
+ * puts every GTK library on Intel macOS. Exporting these four directories here
+ * makes the same command resolve, download and render (`OpenGL 4.1`).
+ *
+ * WHY HERE, and not the caller's job: SIP strips every `DYLD_*` variable when a
+ * PROTECTED binary is exec'd, and `/bin/sh` — this script — is protected. A
+ * value the USER exports is already gone by the time the preamble runs
+ * (measured: exporting the identical value around `gjsify showcase` changes
+ * nothing), while one the preamble exports ITSELF survives the following
+ * `exec gjs`, Homebrew's gjs being unprotected. This is the last hop that can.
+ *
+ * A CONSTANT is safe here only because it is dyld's DOCUMENTED DEFAULT: it
+ * cannot go stale the way baking `systemGiLibraryDirs()` in would (a launcher is
+ * routinely written before `brew install gtk4`), and it re-derives nothing —
+ * four literals from `dyld(1)`, shared with {@link dyldDefaultFallbackDirs}.
+ * An inherited value stays AHEAD of it; the export only ADDS BACK what dyld
+ * would have searched on its own.
+ *
+ * NOT the host's GI libdirs: `/opt/homebrew/lib` was never in dyld's default
+ * either, so an ARM Mac has that gap with or without gjsify —
+ * `status/open-todos.md`.
+ */
+export declare function dyldFallbackPreamble(platform: string): string;
 /** POSIX `sh` single-quoting for a launcher's target path. */
 export declare function shQuoteArg(s: string): string;
 /**

package/lib/utils/bin-shim.js

@@ -25,6 +25,7 @@
 // declaring `#!/usr/bin/env node` and one declaring `#!/usr/bin/env -S gjs -m`
 // both work without the caller knowing which it is.
 import { detectHostLibc, libraryPathVar, prebuildDirCandidates } from './detect-native-packages.js';
+import { dyldDefaultFallbackDirs } from './system-gi.js';
 // Matches `#!<prog> <args>` and `#!/usr/bin/env [-S] [K=V ...] <prog> <args>`.
 // Verbatim from cmd-shim's `shebangExpr`.
 const SHEBANG_RE = /^#!\s*(?:\/usr\/bin\/env\s+(?:-S\s+)?((?:[^ \t=]+=[^ \t=]+\s+)*))?([^ \t]+)(.*)$/;
@@ -340,31 +341,16 @@ function shQuote(s) {
  * script chain: the self-relative `@loader_path` rpath that
  * `check-prebuild-loader-path.mjs` enforces is what actually has to carry it.
  *
- * NOT EXTENDED WITH THE HOST'S GI LIBDIRS — a decision, not an oversight.
- * `buildNativeEnv()` now puts `systemGiLibraryDirs()` on the gjs CHILD's
- * `DYLD_FALLBACK_LIBRARY_PATH`, which repairs every command that goes through this
- * CLI. A launcher that `exec`s a GJS bundle DIRECTLY — `gjsify install -g` on a
- * package whose `gjsify.bin` is a GTK app — has no CLI in the loop and still
- * carries the gap.
- *
- * The MECHANISM would work, and that was measured on the macOS 15.7.8 VM rather
- * than assumed. It is a finer point than the caveat above: what SIP strips is an
- * INHERITED `DYLD_*` at the `/bin/sh` exec, so a value this preamble exports
- * ITSELF survives the following `exec gjs` (an unprotected Homebrew binary) and
- * `Gtk.init()` then succeeds. What is missing is a shape worth having:
- *
- *   - BAKING `systemGiLibraryDirs()` in at write time reintroduces precisely the
- *     snapshot this function exists to remove — a launcher is routinely written
- *     BEFORE `brew install gtk4`, and would bake nothing while saying nothing.
- *   - RE-DERIVING it in shell means a THIRD copy of a rule that already has two,
- *     pinned in agreement by `system-gi.spec.ts` — and shell can express only one
- *     of its three sources (the probed prefixes; `pkg-config` would be a spawn on
- *     every launch), so that copy would be knowingly partial, in the one language
- *     nothing here type-checks.
- *
- * So the gap is recorded in `status/open-todos.md` with the measurement attached
- * instead of being closed by a mechanism that drifts. Closing it properly means
- * teaching such a launcher to defer to the CLI, not to re-derive.
+ * IT DOES export dyld's own default fallback list on darwin — see
+ * {@link dyldFallbackPreamble}. That is a CONSTANT, so it carries none of the
+ * staleness that rules out the alternatives: BAKING `systemGiLibraryDirs()` in
+ * at write time reintroduces the snapshot this function exists to remove (a
+ * launcher is routinely written BEFORE `brew install gtk4`), and RE-DERIVING it
+ * in shell would be a knowingly partial THIRD copy of a two-copy rule, in the
+ * one language nothing here type-checks. The REMAINING gap — a host GI stack
+ * under a prefix dyld never defaulted to, `/opt/homebrew/lib` on Apple silicon —
+ * stays in `status/open-todos.md`, to be closed by teaching such a launcher to
+ * defer to the CLI rather than to re-derive.
  *
  * @param scanRoot Directory whose `node_modules` is globbed at launch time.
  * @param bakedDirs Prebuild dirs found at write time; entries outside `scanRoot`
@@ -433,7 +419,46 @@ export function buildNativeEnvPreamble(scanRoot, bakedDirs = [], target = {}) {
         `  ${libVar}="$gjsify_np\${${libVar}:+${separator}$${libVar}}"\n` +
         `  export GI_TYPELIB_PATH ${libVar}\n` +
         `fi\n` +
-        `unset gjsify_np gjsify_d gjsify_t\n`);
+        `unset gjsify_np gjsify_d gjsify_t\n` +
+        dyldFallbackPreamble(platform));
+}
+/**
+ * The darwin half of {@link buildNativeEnvPreamble}: put dyld's OWN default
+ * fallback list back, from inside the launcher.
+ *
+ * MEASURED on the macOS 15.7.9 x86_64 VM against the published 0.37.0: every
+ * `gjsify` command died in `dlopen(libsoup-3.0.0.dylib)` — before downloading
+ * anything, the CLI's own npm fetcher going through Soup — with a dyld search
+ * list that ended at `/usr/lib` and never held `/usr/local/lib`, where Homebrew
+ * puts every GTK library on Intel macOS. Exporting these four directories here
+ * makes the same command resolve, download and render (`OpenGL 4.1`).
+ *
+ * WHY HERE, and not the caller's job: SIP strips every `DYLD_*` variable when a
+ * PROTECTED binary is exec'd, and `/bin/sh` — this script — is protected. A
+ * value the USER exports is already gone by the time the preamble runs
+ * (measured: exporting the identical value around `gjsify showcase` changes
+ * nothing), while one the preamble exports ITSELF survives the following
+ * `exec gjs`, Homebrew's gjs being unprotected. This is the last hop that can.
+ *
+ * A CONSTANT is safe here only because it is dyld's DOCUMENTED DEFAULT: it
+ * cannot go stale the way baking `systemGiLibraryDirs()` in would (a launcher is
+ * routinely written before `brew install gtk4`), and it re-derives nothing —
+ * four literals from `dyld(1)`, shared with {@link dyldDefaultFallbackDirs}.
+ * An inherited value stays AHEAD of it; the export only ADDS BACK what dyld
+ * would have searched on its own.
+ *
+ * NOT the host's GI libdirs: `/opt/homebrew/lib` was never in dyld's default
+ * either, so an ARM Mac has that gap with or without gjsify —
+ * `status/open-todos.md`.
+ */
+export function dyldFallbackPreamble(platform) {
+    if (platform !== 'darwin')
+        return '';
+    // `HOME: '$HOME'` on purpose — the shim must expand it at LAUNCH, not bake
+    // the writing machine's home directory into every launcher.
+    const dirs = dyldDefaultFallbackDirs({ HOME: '$HOME' }).join(':');
+    return (`DYLD_FALLBACK_LIBRARY_PATH="\${DYLD_FALLBACK_LIBRARY_PATH:+$DYLD_FALLBACK_LIBRARY_PATH:}${dirs}"\n` +
+        `export DYLD_FALLBACK_LIBRARY_PATH\n`);
 }
 /** POSIX `sh` single-quoting for a launcher's target path. */
 export function shQuoteArg(s) {

package/lib/utils/clear-targets.d.ts

@@ -8,9 +8,9 @@ export interface ClearContext {
 /**
  * Does this path segment carry a shell wildcard?
  *
- * `*` and `?` only — what `rm -rf *.log` used. Deliberately NOT a glob engine:
- * a `clear` script names build output, and `**` or character classes there would
- * let a line delete more than its author can see at a glance.
+ * `*` and `?` only — what `rm -rf *.log` used. Deliberately NOT a glob engine: a `clear` script
+ * names build output, and `**` or character classes would let a line delete more than its
+ * author can see at a glance.
  */
 export declare function hasWildcard(segment: string): boolean;
 /** Compile one wildcard segment to an anchored regex, escaping every other metachar. */
@@ -18,13 +18,10 @@ export declare function segmentToRegExp(segment: string): RegExp;
 /**
  * Expand and validate every target, resolving wildcards against `readdir`.
  *
- * ALL targets are resolved before the caller deletes any of them — a typo in the
- * fourth path must not be discovered after the first three are gone.
- *
- * A wildcard is honoured in the LAST segment only, matched against a single
- * directory read: the shell semantics the rewritten scripts need, with none of
- * the recursive traversal. A pattern matching nothing yields no targets, which
- * is `rm -rf`'s behaviour under `--force` and why a package that was never built
- * clears cleanly.
+ * ALL targets are resolved before the caller deletes any — a typo in the fourth path must not
+ * be discovered after the first three are gone. A wildcard is honoured in the LAST segment
+ * only, matched against a single directory read: shell semantics without recursive traversal.
+ * A pattern matching nothing yields no targets, which is `rm -rf --force`'s behaviour and why a
+ * package that was never built clears cleanly.
  */
 export declare function resolveClearTargets(paths: readonly string[], ctx: ClearContext): string[];

package/lib/utils/clear-targets.js

@@ -1,20 +1,19 @@
 // Target resolution for `gjsify clear` — the safety-critical half, kept pure.
 //
-// A recursive delete driven by strings from 224 package.json files is a footgun,
-// so the "which paths does this actually delete" decision lives here, with the
-// directory read INJECTED. That makes every rule below unit-testable without a
-// real filesystem, which is the point: the tests that matter are the ones for
-// paths that must be REFUSED, and creating a fixture outside the cwd to prove
-// that is exactly what a test must not do.
+// A recursive delete driven by strings from every workspace's package.json is a footgun, so
+// the "which paths does this actually delete" decision lives here with the directory read
+// INJECTED. That makes every rule below unit-testable without a real filesystem, which is the
+// point: the tests that matter are the ones for paths that must be REFUSED, and creating a
+// fixture outside the cwd to prove that is exactly what a test must not do.
 //
 // See `commands/clear.ts` for why the command exists at all.
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 /**
  * Does this path segment carry a shell wildcard?
  *
- * `*` and `?` only — what `rm -rf *.log` used. Deliberately NOT a glob engine:
- * a `clear` script names build output, and `**` or character classes there would
- * let a line delete more than its author can see at a glance.
+ * `*` and `?` only — what `rm -rf *.log` used. Deliberately NOT a glob engine: a `clear` script
+ * names build output, and `**` or character classes would let a line delete more than its
+ * author can see at a glance.
  */
 export function hasWildcard(segment) {
     return segment.includes('*') || segment.includes('?');
@@ -30,9 +29,8 @@ export function segmentToRegExp(segment) {
 /**
  * Reject a target that is not strictly inside `cwd`.
  *
- * A hard error, never a skip: a typo that would otherwise delete a sibling
- * package — or `$HOME` — must not depend on anyone reading a warning in the
- * middle of a 224-package `foreach` run.
+ * A hard error, never a skip: a typo that would otherwise delete a sibling package — or
+ * `$HOME` — must not depend on anyone reading a warning mid-`foreach` across every workspace.
  */
 function assertInsideCwd(absolute, original, cwd) {
     const rel = relative(cwd, absolute);
@@ -47,14 +45,11 @@ function assertInsideCwd(absolute, original, cwd) {
 /**
  * Expand and validate every target, resolving wildcards against `readdir`.
  *
- * ALL targets are resolved before the caller deletes any of them — a typo in the
- * fourth path must not be discovered after the first three are gone.
- *
- * A wildcard is honoured in the LAST segment only, matched against a single
- * directory read: the shell semantics the rewritten scripts need, with none of
- * the recursive traversal. A pattern matching nothing yields no targets, which
- * is `rm -rf`'s behaviour under `--force` and why a package that was never built
- * clears cleanly.
+ * ALL targets are resolved before the caller deletes any — a typo in the fourth path must not
+ * be discovered after the first three are gone. A wildcard is honoured in the LAST segment
+ * only, matched against a single directory read: shell semantics without recursive traversal.
+ * A pattern matching nothing yields no targets, which is `rm -rf --force`'s behaviour and why a
+ * package that was never built clears cleanly.
  */
 export function resolveClearTargets(paths, ctx) {
     const out = [];
@@ -73,17 +68,16 @@ export function resolveClearTargets(paths, ctx) {
 function expandTarget(target, ctx) {
     const leaf = basename(target);
     const parent = dirname(target);
-    // Checked BEFORE the no-wildcard shortcut: `*/dist` has a wildcard-free
-    // basename, and treating it as a literal path would silently delete nothing
-    // instead of telling the author the shape is unsupported.
+    // Checked BEFORE the no-wildcard shortcut: `*/dist` has a wildcard-free basename, and
+    // treating it as a literal path would silently delete nothing instead of telling the
+    // author the shape is unsupported.
     if (hasWildcard(parent)) {
         throw new Error(`gjsify clear: a wildcard is only supported in the last path segment — got "${target}".`);
     }
     if (!hasWildcard(leaf))
         return [resolve(ctx.cwd, target)];
-    // The parent is validated too: `../*.log` must be refused, and it is only
-    // refused if the containing DIRECTORY is checked against cwd before the
-    // expansion — the matches themselves are all inside it.
+    // The parent is validated too: `../*.log` is only refused if the containing DIRECTORY is
+    // checked against cwd before expansion — the matches themselves are all inside it.
     const dir = resolve(ctx.cwd, parent);
     assertInsideCwdOrSelf(dir, target, ctx.cwd);
     const re = segmentToRegExp(leaf);
@@ -92,9 +86,8 @@ function expandTarget(target, ctx) {
         names = ctx.readdir(dir);
     }
     catch {
-        // The containing directory is absent or unreadable — nothing to clear,
-        // like `rm -rf` on a missing path. A permission problem on an EXISTING
-        // target still surfaces from the delete itself.
+        // Absent or unreadable containing directory — nothing to clear, like `rm -rf` on a
+        // missing path. A permission problem on an EXISTING target still surfaces from the delete.
         return [];
     }
     return names

package/lib/utils/copy-targets.d.ts

@@ -13,29 +13,23 @@ export interface CopyOperation {
 /**
  * Is the destination a DIRECTORY to copy into, rather than the target path?
  *
- * Decided from the ARGUMENTS ALONE — never from what is on disk. `cp` decides it
- * by stat'ing the destination, which is why `cp -r src/assets dist/res` copies
- * the directory to `dist/res` the first time and to `dist/res/assets` the
- * second: the same script means two different things depending on whether it has
- * run before. Four of the scripts this command replaces carry exactly that shape,
- * so they were already non-idempotent on Linux. A build step must not be.
+ * Decided from the ARGUMENTS ALONE — never from what is on disk. `cp` decides it by stat'ing the
+ * destination, which is why `cp -r src/assets dist/res` copies the directory to `dist/res` the
+ * first time and to `dist/res/assets` the second: the same script means two things depending on
+ * whether it has run before. Several scripts this command replaces carried that shape and were
+ * already non-idempotent on Linux. A build step must not be.
  *
- * The rule, in full:
- *   - a trailing `/` (or `\`) on the destination — the explicit spelling;
- *   - more than one source;
- *   - any source carrying a wildcard.
+ * Directory mode iff: a trailing `/` (or `\`) on the destination — the explicit spelling; more
+ * than one source; or any source carrying a wildcard.
  *
- * The last two are what keep the two platforms in agreement. A POSIX shell
- * expands `src/public/*` before gjsify is started (many sources); `cmd.exe` does
- * not expand anything and passes the pattern through (one source, a wildcard).
- * Both land in directory mode, so the same script means the same thing on both.
+ * The last two keep the platforms in agreement: a POSIX shell expands `src/public/*` before
+ * gjsify starts (many sources), while `cmd.exe` passes the pattern through (one source, a
+ * wildcard). Both land in directory mode, so the same script means the same thing on both.
  */
 export declare function isDirectoryDestination(sources: readonly string[], dest: string): boolean;
 /**
- * Resolve `gjsify copy <sources…> <destination>` into the exact list of copies.
- *
- * ALL operations are planned before the caller performs any of them, so a bad
- * argument in position four cannot be discovered after three files have already
- * been written.
+ * Resolve `gjsify copy <sources…> <destination>` into the exact list of copies. ALL operations are
+ * planned before the caller performs any, so a bad argument in position four cannot be discovered
+ * after three files have been written.
  */
 export declare function planCopy(args: readonly string[], ctx: CopyContext): CopyOperation[];

package/lib/utils/copy-targets.js

@@ -1,9 +1,9 @@
 // Target resolution for `gjsify copy` — the deciding half, kept pure.
 //
-// Same split as `clear-targets.ts`, for the same reason: the paths come from
-// package.json files rather than from a human at a prompt, so "which file lands
-// where" must be testable without a filesystem — including the cases that must
-// be REFUSED, which cannot be proven by writing outside the working directory.
+// Same split as `clear-targets.ts`, for the same reason: the paths come from package.json files
+// rather than from a human at a prompt, so "which file lands where" must be testable without a
+// filesystem — including the cases that must be REFUSED, which cannot be proven by writing
+// outside the working directory.
 //
 // See `commands/copy.ts` for why the command exists at all.
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
@@ -11,22 +11,18 @@ import { hasWildcard, segmentToRegExp } from './clear-targets.js';
 /**
  * Is the destination a DIRECTORY to copy into, rather than the target path?
  *
- * Decided from the ARGUMENTS ALONE — never from what is on disk. `cp` decides it
- * by stat'ing the destination, which is why `cp -r src/assets dist/res` copies
- * the directory to `dist/res` the first time and to `dist/res/assets` the
- * second: the same script means two different things depending on whether it has
- * run before. Four of the scripts this command replaces carry exactly that shape,
- * so they were already non-idempotent on Linux. A build step must not be.
+ * Decided from the ARGUMENTS ALONE — never from what is on disk. `cp` decides it by stat'ing the
+ * destination, which is why `cp -r src/assets dist/res` copies the directory to `dist/res` the
+ * first time and to `dist/res/assets` the second: the same script means two things depending on
+ * whether it has run before. Several scripts this command replaces carried that shape and were
+ * already non-idempotent on Linux. A build step must not be.
  *
- * The rule, in full:
- *   - a trailing `/` (or `\`) on the destination — the explicit spelling;
- *   - more than one source;
- *   - any source carrying a wildcard.
+ * Directory mode iff: a trailing `/` (or `\`) on the destination — the explicit spelling; more
+ * than one source; or any source carrying a wildcard.
  *
- * The last two are what keep the two platforms in agreement. A POSIX shell
- * expands `src/public/*` before gjsify is started (many sources); `cmd.exe` does
- * not expand anything and passes the pattern through (one source, a wildcard).
- * Both land in directory mode, so the same script means the same thing on both.
+ * The last two keep the platforms in agreement: a POSIX shell expands `src/public/*` before
+ * gjsify starts (many sources), while `cmd.exe` passes the pattern through (one source, a
+ * wildcard). Both land in directory mode, so the same script means the same thing on both.
  */
 export function isDirectoryDestination(sources, dest) {
     if (dest.endsWith('/') || dest.endsWith('\\'))
@@ -38,15 +34,13 @@ export function isDirectoryDestination(sources, dest) {
 /**
  * Reject a destination that is not inside `cwd`.
  *
- * A hard error, never a skip — the same posture as `clear`, for the mirrored
- * reason: `clear` must not DELETE outside the package, `copy` must not WRITE
- * outside it. `allowSelf` covers `gjsify copy ../shared/x.wasm ./`, where the
+ * A hard error, never a skip — mirroring `clear`: it must not DELETE outside the package, `copy`
+ * must not WRITE outside it. `allowSelf` covers `gjsify copy ../shared/x.wasm ./`, where the
  * package root legitimately IS the destination directory.
  *
- * SOURCES are deliberately NOT checked. Three of the scripts this replaces read
- * from a sibling package (`../../../packages/infra/lightningcss-wasm/…`), which
- * is the normal shape for staging a workspace artifact, and reading is not the
- * dangerous direction.
+ * SOURCES are deliberately NOT checked: reading from a sibling package
+ * (`../../../packages/infra/lightningcss-wasm/…`) is the normal shape for staging a workspace
+ * artifact, and reading is not the dangerous direction.
  */
 function assertWritableDestination(absolute, original, cwd, allowSelf) {
     const rel = relative(cwd, absolute);
@@ -62,15 +56,12 @@ function assertWritableDestination(absolute, original, cwd, allowSelf) {
     }
 }
 /**
- * Expand one source argument. A wildcard is honoured in the LAST segment only,
- * against a single directory read — the same restricted grammar `clear` uses,
- * and for the same reason: a build script names files, and `**` there would copy
- * more than its author can see at a glance.
+ * Expand one source argument. A wildcard is honoured in the LAST segment only, against a single
+ * directory read — the same restricted grammar `clear` uses, and for the same reason.
  *
- * A pattern matching nothing yields NO operations. A literal path that does not
- * exist yields one operation, which then fails loudly in the copy itself — the
- * asymmetry is deliberate and mirrors the shell: `cp missing.html dist/` is an
- * error, `cp *.html dist/` on an empty directory is not.
+ * A pattern matching nothing yields NO operations; a literal path that does not exist yields one,
+ * which then fails loudly in the copy itself. The asymmetry mirrors the shell: `cp missing.html
+ * dist/` is an error, `cp *.html dist/` on an empty directory is not.
  */
 function expandSource(source, ctx) {
     const leaf = basename(source);
@@ -95,11 +86,9 @@ function expandSource(source, ctx) {
         .map((name) => join(dir, name));
 }
 /**
- * Resolve `gjsify copy <sources…> <destination>` into the exact list of copies.
- *
- * ALL operations are planned before the caller performs any of them, so a bad
- * argument in position four cannot be discovered after three files have already
- * been written.
+ * Resolve `gjsify copy <sources…> <destination>` into the exact list of copies. ALL operations are
+ * planned before the caller performs any, so a bad argument in position four cannot be discovered
+ * after three files have been written.
  */
 export function planCopy(args, ctx) {
     if (args.length < 2) {
@@ -120,9 +109,8 @@ export function planCopy(args, ctx) {
         expanded.push(...expandSource(source, ctx));
     }
     if (!intoDirectory && expanded.length !== 1) {
-        // Only reachable when a single wildcard-free source expanded to something
-        // other than one path, which cannot happen — but leaving it unstated would
-        // make a future change to `expandSource` silently copy the wrong file.
+        // Unreachable today (a single wildcard-free source always expands to one path), but
+        // leaving it unstated would let a future `expandSource` change silently copy the wrong file.
         throw new Error(`gjsify copy: "${dest}" names a single destination, but ${expanded.length} sources resolved.`);
     }
     const ops = [];
@@ -133,9 +121,8 @@ export function planCopy(args, ctx) {
             throw new Error(`gjsify copy: "${from}" is its own destination.`);
         }
         if (seenDest.has(to)) {
-            // Two sources with the same basename copied into one directory: the
-            // second silently overwrites the first, and which one wins depends on
-            // argument order. Name it instead.
+            // Two sources with the same basename into one directory: the second would silently
+            // overwrite the first, and which wins depends on argument order.
             throw new Error(`gjsify copy: two sources would both be written to ${to}.`);
         }
         seenDest.add(to);

package/lib/utils/dep-aggregation.d.ts

@@ -4,40 +4,32 @@ export interface DepDeclaration {
     workspace: string;
     /** Absolute path to the workspace's `package.json`. */
     workspaceLocation: string;
-    /** Dependency name (e.g. `rolldown`). */
     name: string;
-    /** Which manifest field this declaration lives in. */
     field: 'dependencies' | 'devDependencies' | 'optionalDependencies' | 'peerDependencies';
     /** The original range string (e.g. `^1.0.4`). */
     currentRange: string;
-    /** The parsed version (max-satisfying numeric) inside the range, or `null`. */
+    /** Max-satisfying numeric version inside the range, or `null` if unparseable. */
     currentVersion: string | null;
     /** Range prefix preserved on write-back (`^`, `~`, `>=`, …; `""` for literal). */
     prefix: string;
 }
 /** Aggregated view of one external dep across all workspaces that declare it. */
 export interface DependencyGroup {
-    /** Dependency name. */
     name: string;
-    /** Every declaration of this dep across the workspace. */
     occurrences: DepDeclaration[];
-    /** Set of all unique declared ranges (size > 1 → inconsistency). */
+    /** Unique declared ranges — size > 1 IS the inconsistency. */
     declaredRanges: Set<string>;
-    /** Range string declared by the most workspaces (the de-facto consensus). */
+    /** Range declared by the most workspaces: the de-facto consensus. */
     dominantRange: string;
-    /** When ranges disagree, the highest declared semver version across them. */
+    /** Highest declared semver across the group. */
     highestVersion: string | null;
 }
 /**
- * Group a flat list of `DepDeclaration`s by dep name. Each group has the full
- * occurrence list plus pre-computed aggregates (consensus range, highest
- * declared version) so callers don't have to re-scan.
+ * Group a flat list of `DepDeclaration`s by dep name, pre-computing the aggregates
+ * so no caller has to re-scan the occurrences.
  */
 export declare function groupByDependency(decls: readonly DepDeclaration[]): DependencyGroup[];
 /** `true` when the group's workspaces declare the dep at >1 distinct range. */
 export declare function isInconsistent(group: DependencyGroup): boolean;
-/**
- * Filter to just the inconsistent groups (>1 distinct range across workspaces).
- * Convenience wrapper for `--align` and `--check` modes.
- */
+/** The inconsistent groups only — what `--align` and `--check` operate on. */
 export declare function findInconsistencies(groups: readonly DependencyGroup[]): DependencyGroup[];