@gjsify/cli 0.35.0 → 0.37.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/check-system-deps.d.ts

@@ -130,6 +130,22 @@ export declare function runAllChecks(cwd: string): DepCheck[];
  * Used by `gjsify showcase` for examples that have no native deps.
  */
 export declare function runMinimalChecks(): DepCheck[];
+/**
+ * Is a blueprint-compiler reachable, by the SAME rule the build uses?
+ *
+ * Delegates to `@gjsify/vite-plugin-blueprint/resolve` rather than probing PATH
+ * here, because the two answers must not be able to disagree: on win32 the
+ * compiler is normally an MSYS2 script that is deliberately NOT on PATH, so a
+ * PATH-only check would report "missing" on a host where every `.blp` builds
+ * fine — a check failing for the wrong reason, which is the failure mode this
+ * file's own history is made of.
+ *
+ * `--version` is not run. MSYS2 ships blueprint-compiler as a shebang script
+ * with no `.exe`, so `checkBinary` cannot execute it on Windows; presence of the
+ * resolved pair is the honest answer, and the `source` is worth reporting
+ * because "found via msys2" explains an install PATH does not show.
+ */
+export declare function checkBlueprintCompiler(requiredBy?: string[]): DepCheck;
 /** Check gwebgl npm package (project first, CLI fallback). Optional — only needed by @gjsify/webgl users. */
 export declare function checkGwebgl(cwd: string): DepCheck;
 /**

package/lib/utils/check-system-deps.js

@@ -15,6 +15,9 @@ import { dirname, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
+// The zero-dependency subpath, deliberately: importing the plugin root would
+// pull vite/execa/minify-xml into a system CHECK.
+import { resolveBlueprintCompiler } from '@gjsify/vite-plugin-blueprint/resolve';
 /** Run a binary and return its stdout trimmed, or null if it fails. */
 function tryExecFile(binary, args) {
     try {
@@ -392,6 +395,32 @@ export function runMinimalChecks() {
         results.push(checkMsvcRuntime());
     return results;
 }
+/**
+ * Is a blueprint-compiler reachable, by the SAME rule the build uses?
+ *
+ * Delegates to `@gjsify/vite-plugin-blueprint/resolve` rather than probing PATH
+ * here, because the two answers must not be able to disagree: on win32 the
+ * compiler is normally an MSYS2 script that is deliberately NOT on PATH, so a
+ * PATH-only check would report "missing" on a host where every `.blp` builds
+ * fine — a check failing for the wrong reason, which is the failure mode this
+ * file's own history is made of.
+ *
+ * `--version` is not run. MSYS2 ships blueprint-compiler as a shebang script
+ * with no `.exe`, so `checkBinary` cannot execute it on Windows; presence of the
+ * resolved pair is the honest answer, and the `source` is worth reporting
+ * because "found via msys2" explains an install PATH does not show.
+ */
+export function checkBlueprintCompiler(requiredBy) {
+    const resolved = resolveBlueprintCompiler();
+    return {
+        id: 'blueprint-compiler',
+        name: 'blueprint-compiler (.blp templates)',
+        found: resolved !== null,
+        version: resolved ? `found via ${resolved.source}` : undefined,
+        severity: 'optional',
+        requiredBy,
+    };
+}
 /** Check gwebgl npm package (project first, CLI fallback). Optional — only needed by @gjsify/webgl users. */
 export function checkGwebgl(cwd) {
     return checkNpmPackage('gwebgl', 'gwebgl (@gjsify/webgl)', '@gjsify/webgl', cwd, 'optional', ['@gjsify/webgl']);
@@ -454,7 +483,13 @@ function runNativeBuildToolchainChecks() {
     // Narrower on purpose: only the three bridges that link an upstream Rust
     // crate by Cargo path-dependency need a Rust toolchain.
     const rustBridges = ['@gjsify/lightningcss-native', '@gjsify/oxfmt-native', '@gjsify/rolldown-native'];
+    // Every showcase/app whose window comes from a `.blp` template. NOT a Vala
+    // bridge and nothing to do with meson — it is a BUILD-time toolchain in the
+    // same sense, and it belongs here so `gjsify system-check` names it before a
+    // build does.
+    const blueprintConsumers = ['@gjsify/vite-plugin-blueprint'];
     return [
+        checkBlueprintCompiler(blueprintConsumers),
         checkBinary('ninja', 'Ninja', 'ninja', ['--version'], 'optional', undefined, valaBridges),
         checkBinary('vala', 'Vala', 'valac', ['--version'], 'optional', (out) => out.replace(/^Vala\s+/i, ''), valaBridges),
         checkBinary('cargo', 'Cargo (Rust)', 'cargo', ['--version'], 'optional', (out) => out.replace(/^cargo\s+/i, '').split(' ')[0] ?? out, rustBridges),
@@ -697,11 +732,24 @@ export function buildInstallCommand(pm, missing) {
     const pkgMap = PM_PACKAGES[pm];
     const pkgs = [];
     const npmDeps = [];
+    const standalone = [];
     for (const dep of missing) {
         if (dep.id === 'gwebgl') {
             npmDeps.push('@gjsify/webgl');
             continue;
         }
+        // blueprint-compiler on Windows is the one dep whose install command is
+        // not this host's package manager. winget has no package for it, and it
+        // cannot get one that works: the tool needs PyGObject, which publishes
+        // no Windows wheel, so MSYS2 — which ships Python, PyGObject and the
+        // typelibs already fitted together — is the only source. Its command is
+        // not `winget install`-shaped, so it cannot live in PM_PACKAGES without
+        // producing a line that looks right and fails.
+        if (dep.id === 'blueprint-compiler' && process.platform === 'win32') {
+            standalone.push('pacman -S mingw-w64-ucrt-x86_64-blueprint-compiler mingw-w64-ucrt-x86_64-gtk4 ' +
+                'mingw-w64-ucrt-x86_64-libadwaita   # inside MSYS2; found automatically afterwards');
+            continue;
+        }
         if (dep.id === 'nodejs')
             continue; // can't be missing if we're running
         const pkg = pkgMap[dep.id];
@@ -715,6 +763,7 @@ export function buildInstallCommand(pm, missing) {
     if (npmDeps.length > 0) {
         lines.push(`npm install ${npmDeps.join(' ')}`);
     }
+    lines.push(...standalone);
     return lines.length > 0 ? lines.join('\n  ') : null;
 }
 /**

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[];

package/lib/utils/dep-aggregation.js

@@ -1,16 +1,8 @@
-// Workspace-aware dependency aggregation for `gjsify upgrade`.
-//
-// Given a flat list of per-workspace dependency declarations, group them by
-// package name and surface inconsistencies (the same package declared at
-// different version ranges across workspaces). Used by:
-//
-//   - `gjsify upgrade` interactive table — shows fan-out (count of workspaces
-//     declaring the dep) and flags inconsistent declarations with `⚠`.
-//   - `gjsify upgrade --align` — offline mode that detects inconsistencies
-//     and proposes a single range (the highest semver-satisfying one) without
-//     hitting the registry.
-//   - `gjsify upgrade --check` — CI gate that exits non-zero when any
-//     inconsistency exists.
+// Workspace-aware dependency aggregation for `gjsify upgrade`: group per-workspace
+// declarations by package name and surface inconsistencies — the same package
+// declared at different ranges across workspaces. Drives the interactive table's
+// fan-out column, `--align` (propose one range offline, no registry hit) and
+// `--check` (CI gate, non-zero on any inconsistency).
 import { compare, parse } from '@gjsify/semver';
 /** Local `gt` shim: `@gjsify/semver` exports `compare` returning -1|0|1. */
 function semverGt(a, b) {
@@ -22,9 +14,8 @@ function semverGt(a, b) {
     }
 }
 /**
- * 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 function groupByDependency(decls) {
     const map = new Map();
@@ -48,8 +39,7 @@ export function groupByDependency(decls) {
             }
         }
     }
-    // Second pass: dominantRange = the range with the most occurrences;
-    // ties resolve by highest semver, then by lexicographic order.
+    // dominantRange = most occurrences; ties break on highest semver, then lexically.
     for (const g of map.values()) {
         const counts = new Map();
         for (const occ of g.occurrences) {
@@ -77,10 +67,7 @@ export function groupByDependency(decls) {
 export function isInconsistent(group) {
     return group.declaredRanges.size > 1;
 }
-/**
- * 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 function findInconsistencies(groups) {
     return groups.filter(isInconsistent);
 }