@gjsify/cli 0.48.0 → 0.50.0

package/lib/actions/barrels-generate.d.ts

@@ -21,9 +21,31 @@ export interface BarrelsArgs {
 }
 export declare const DEFAULT_BARRELS_HEADER = "// Auto-generated by `gjsify barrels` \u2014 do not edit by hand.";
 export declare const DEFAULT_BARRELS_EXCLUDES: readonly string[];
+/**
+ * The entries of `paths` that cannot be scanned as a directory, resolved against `baseDir`
+ * — each already phrased for printing.
+ *
+ * A SEPARATE pass rather than a behaviour change inside {@link generateBarrels}, because
+ * the two callers want opposite things. A programmatic caller may legitimately hand the
+ * generator a directory that is not there yet and still want the others written, which is
+ * why it skips; a COMMAND-LINE caller named these directories, so one that cannot be read
+ * is a typo or a rename and nothing else. So the command asserts first — the shape
+ * `assertEveryIncludeMatches` already has for `gjsify foreach --include`.
+ *
+ * THE INCIDENT: `gjsify barrels --check` counted a directory it could not read as 0 drift
+ * and exited 0, so the guard reported a clean barrel for a directory nothing had looked
+ * at, and the only trace was a line printed under `--verbose`. "Skipped" and "in sync"
+ * have to be told apart by the exit code — a guard that goes green for work it never did
+ * is worse than no guard, because a later step is measuring its output.
+ */
+export declare function unscannableBarrelPaths(baseDir: string, paths: readonly string[]): Promise<string[]>;
 /**
  * Regenerate `index.ts` in every directory in `args.paths`.
  *
+ * A path that cannot be read is SKIPPED here, deliberately — see
+ * {@link unscannableBarrelPaths} for who refuses it instead, and why that is the command
+ * and not this.
+ *
  * Returns the number of files that drifted from the canonical output —
  * always 0 when `check` is false (drift is rewritten in-place); non-zero
  * under `check: true` signals CI failure.

package/lib/actions/barrels-generate.js

@@ -12,14 +12,49 @@
 //
 // Original: Copyright (c) Beabee Community Repo contributors. AGPL-3.0.
 // Reimplemented for gjsify under the project's MIT license.
-import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { basename, extname, join, resolve } from 'node:path';
 export const DEFAULT_BARRELS_HEADER = '// Auto-generated by `gjsify barrels` — do not edit by hand.';
 export const DEFAULT_BARRELS_EXCLUDES = ['\\.test\\.', '\\.spec\\.', '\\.test-data\\.'];
 const SOURCE_FILE_RE = /\.(ts|tsx|mts|cts)$/;
+/**
+ * The entries of `paths` that cannot be scanned as a directory, resolved against `baseDir`
+ * — each already phrased for printing.
+ *
+ * A SEPARATE pass rather than a behaviour change inside {@link generateBarrels}, because
+ * the two callers want opposite things. A programmatic caller may legitimately hand the
+ * generator a directory that is not there yet and still want the others written, which is
+ * why it skips; a COMMAND-LINE caller named these directories, so one that cannot be read
+ * is a typo or a rename and nothing else. So the command asserts first — the shape
+ * `assertEveryIncludeMatches` already has for `gjsify foreach --include`.
+ *
+ * THE INCIDENT: `gjsify barrels --check` counted a directory it could not read as 0 drift
+ * and exited 0, so the guard reported a clean barrel for a directory nothing had looked
+ * at, and the only trace was a line printed under `--verbose`. "Skipped" and "in sync"
+ * have to be told apart by the exit code — a guard that goes green for work it never did
+ * is worse than no guard, because a later step is measuring its output.
+ */
+export async function unscannableBarrelPaths(baseDir, paths) {
+    const problems = [];
+    for (const p of paths) {
+        const dir = resolve(baseDir, p);
+        try {
+            if (!(await stat(dir)).isDirectory())
+                problems.push(`${dir} is not a directory`);
+        }
+        catch (err) {
+            problems.push(`${dir}: ${err.message}`);
+        }
+    }
+    return problems;
+}
 /**
  * Regenerate `index.ts` in every directory in `args.paths`.
  *
+ * A path that cannot be read is SKIPPED here, deliberately — see
+ * {@link unscannableBarrelPaths} for who refuses it instead, and why that is the command
+ * and not this.
+ *
  * Returns the number of files that drifted from the canonical output —
  * always 0 when `check` is false (drift is rewritten in-place); non-zero
  * under `check: true` signals CI failure.

package/lib/actions/build.js

@@ -15,6 +15,7 @@ import { collectEntryPaths, describeJsxConfig, findJsxEntryPoint, jsxConfigMissi
 import { giSystemProbes } from '../utils/gi-runtime-paths.js';
 import { escapeRawNulForGjs } from '../utils/gjs-source-escape.js';
 import { assertNodeBundleGlobalsShimmed } from '../utils/node-bundle-guard.js';
+import { DEP_CHANGE_LOCKFILES } from '../utils/package-inputs.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
@@ -59,16 +60,18 @@ function isTruthyEnv(v) {
     return v === '1' || v === 'true' || v === 'yes';
 }
 /**
- * Lockfiles whose change implies a plugin's *transitive* deps may have moved.
+ * Newest mtime (ms) among known lockfiles in `cwd`, or 0 when none exist.
+ *
  * A dep bump (`npm/yarn/pnpm/gjsify install`) rewrites one of these but leaves
  * the plugin's own entry-file mtime untouched — so the plugin GJS-bundle cache
- * must invalidate on these too, not only on the entry.
+ * must invalidate on them too, not only on the entry. The LIST is
+ * {@link DEP_CHANGE_LOCKFILES}, shared with the package-input definition: two
+ * answers to "has the dependency tree moved" is how they come to disagree
+ * about a fifth package manager.
  */
-const PLUGIN_CACHE_DEP_SIGNALS = ['gjsify-lock.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'];
-/** Newest mtime (ms) among known lockfiles in `cwd`, or 0 when none exist. */
 async function newestLockfileMtime(cwd) {
     let newest = 0;
-    for (const name of PLUGIN_CACHE_DEP_SIGNALS) {
+    for (const name of DEP_CHANGE_LOCKFILES) {
         try {
             const s = await stat(join(cwd, name));
             if (s.mtimeMs > newest)
@@ -630,7 +633,7 @@ export class BuildAction {
             throw new Error('gjsify build: an .html entry needs an explicit --outfile ' +
                 '(e.g. --outfile dist-app/app.js); the emitted index.html is written beside it.');
         }
-        const { consoleShim, globals, dialect } = this.configData;
+        const { consoleShim, globals, dialect, giRenderer } = this.configData;
         const userExternal = Array.isArray(userBundler.external) ? userBundler.external : undefined;
         const userBanner = typeof userBundler.output?.banner === 'string' ? userBundler.output.banner : undefined;
         const pluginOpts = {
@@ -641,6 +644,7 @@ export class BuildAction {
             reflection: typescript?.reflection,
             consoleShim,
             ...(dialect !== undefined ? { dialect } : {}),
+            ...(giRenderer === true ? { giRenderer: true } : {}),
             ...(aliases ? { aliases } : {}),
             ...(opts.preserveDefaultExport ? { preserveDefaultExport: true } : {}),
             ...(opts.toolchainAnchor !== undefined ? { toolchainAnchor: opts.toolchainAnchor } : {}),

package/lib/commands/barrels.js

@@ -13,7 +13,10 @@
 //     file as a module.
 //   - Output is sorted by file name (locale-compare) — deterministic diffs.
 //   - `--check` exits non-zero on drift without writing (pre-commit / CI use).
-import { DEFAULT_BARRELS_EXCLUDES, DEFAULT_BARRELS_HEADER, generateBarrels, } from '../actions/barrels-generate.js';
+//   - A named path that is not a readable directory is REFUSED before anything
+//     is generated: skipping it would let `--check` report 0 drift, and exit 0,
+//     for a barrel nothing ever looked at.
+import { DEFAULT_BARRELS_EXCLUDES, DEFAULT_BARRELS_HEADER, generateBarrels, unscannableBarrelPaths, } from '../actions/barrels-generate.js';
 export const barrelsCommand = {
     command: 'barrels [paths..]',
     description: 'Regenerate `index.ts` barrel files for the given directories. Drop-in replacement for `barrelsby`.',
@@ -81,13 +84,27 @@ export const barrelsCommand = {
             process.exitCode = 1;
             return;
         }
+        const baseDir = args.baseDir ?? process.cwd();
+        // A named path this cannot scan is a typo or a rename, and it is refused BEFORE
+        // anything is generated. The generator skips such a path and reports no drift for
+        // it, which under `--check` is a guard going green for a directory nothing looked
+        // at — the one failure mode a guard must not have.
+        const unscannable = await unscannableBarrelPaths(baseDir, paths);
+        if (unscannable.length > 0) {
+            for (const problem of unscannable)
+                console.error(`[gjsify barrels] cannot scan ${problem}`);
+            console.error(`[gjsify barrels] ${unscannable.length} of ${paths.length} path(s) could not be scanned — ` +
+                'refusing to report on the rest as if that were the whole set.');
+            process.exitCode = 1;
+            return;
+        }
         const excludePatterns = args.exclude?.length
             ? args.exclude
             : [...DEFAULT_BARRELS_EXCLUDES];
         const drift = await generateBarrels({
             paths,
             extension: args.ext ?? 'none',
-            baseDir: args.baseDir ?? process.cwd(),
+            baseDir,
             exclude: excludePatterns.map((src) => new RegExp(src)),
             header: args.header ?? DEFAULT_BARRELS_HEADER,
             noSemicolon: args.semicolon === false || args.semicolon === undefined,

package/lib/commands/build.js

@@ -112,6 +112,10 @@ export const buildCommand = {
             description: "The dialect the SOURCE is written in. 'react-native' aliases 'react-native' onto '@gjsify/react-native' and fails the build on an import whose ADR 0032 support-table status is not supported/partial. GJS and Node app builds. This is NOT gjsify.runtimes['react-native'], which declares the runtime a package RUNS on — the two answer opposite questions.",
             type: 'string',
             choices: [...SOURCE_DIALECTS],
+        })
+            .option('gi-renderer', {
+            description: "Resolve `gi://Ns?version=X` to the target's widget renderer instead of an empty module (ADR 0034 stage 9): --app browser answers gi://Adw and gi://Gtk out of @gjsify/adwaita-web, --app nativescript out of @gjsify/adwaita-nativescript. A namespace with no renderer, and a ?version= the renderer's vocabulary was not generated against, both FAIL the build by name. Off by default — a gi:// import on those targets is usually a GJS-only code path pulled in transitively.",
+            type: 'boolean',
         })
             .option('console-shim', {
             description: 'Inject a console shim into GJS builds for clean output without the GLib prefix and with working ANSI colors. Use --no-console-shim to disable. Only applies to GJS app builds.',

package/lib/commands/foreach.js

@@ -583,25 +583,17 @@ async function runParallel(workspaces, script, args, concurrency, verbose, exec,
     await Promise.all(workers);
 }
 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) {
-        const wsDeps = new Set();
-        const m = ws.manifest;
-        for (const block of [m.dependencies, includeDev ? m.devDependencies : undefined, m.optionalDependencies]) {
-            if (!block)
-                continue;
-            for (const [name, spec] of Object.entries(block)) {
-                if (typeof spec !== 'string')
-                    continue;
-                if (!spec.startsWith('workspace:'))
-                    continue;
-                if (selectedNames.has(name))
-                    wsDeps.add(name);
-            }
-        }
-        remaining.set(ws.name, wsDeps);
-    }
+    // The SHARED graph, walked once — never a private copy of the walk. `buildDependencyGraph`
+    // over the SELECTED set yields exactly these edges: it indexes by name from the list it is
+    // handed, so a dependency outside the selection resolves to no member and is not an edge.
+    //
+    // The copy this replaces followed `workspace:` only. Once #1587 widened the shared rule to
+    // include a plain range the local member satisfies, the two topological legs would have
+    // DISAGREED — `-t` ordering correctly off the shared graph while `-t -p` saw no edges at
+    // all and started every workspace at once, in a monorepo that declares its local deps by
+    // plain semver range. Wrong order, exit 0, and a build measured by a later step: the same
+    // shape #1587 is about, one flag over.
+    const remaining = new Map([...buildDependencyGraph(workspaces, { includeDev }).edges].map(([name, deps]) => [name, new Set(deps)]));
     const byName = new Map(workspaces.map((w) => [w.name, w]));
     const total = workspaces.length;
     const done = new Set();

package/lib/commands/install.js

@@ -23,7 +23,7 @@ import { spawnSync } from 'node:child_process';
 import { forceExit } from '../utils/force-exit.js';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
-import { detectNativePackages } from '../utils/detect-native-packages.js';
+import { detectHostLibc, detectNativePackages, muslPrebuildFallbacks } from '../utils/detect-native-packages.js';
 import { buildLauncherShims, buildNativeEnvPreamble } from '../utils/bin-shim.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
 import { atomicWriteStrict } from '../utils/install-cache-fs.js';
@@ -1339,6 +1339,26 @@ async function runPostInstallChecks(args) {
             console.log(`  • ${pkg.name}`);
         }
         console.log('\nUse `gjsify run <bundle>` to launch with LD_LIBRARY_PATH/GI_TYPELIB_PATH set.');
+        // The install is the ONLY moment this is knowable: the libc axis is decided
+        // here, the failure it predicts happens in another process, days later, and
+        // names something else entirely (see `muslPrebuildFallbacks`). The list is
+        // the point — it is what lets a later `Error relocating` line be matched to
+        // a package.
+        const fellBack = muslPrebuildFallbacks(detectHostLibc(process.platform), native);
+        if (fellBack.length > 0) {
+            console.warn(`\nWarning: musl host — ${fellBack.length} of ${native.length} package(s) ship no \`-musl\`` +
+                ' prebuild, so the\n  default (glibc) build was used:');
+            for (const name of fellBack)
+                console.warn(`    ${name}`);
+            console.warn('  Most of these run anyway: a bridge that links only GLib records no libc at all.\n' +
+                '  One that links glibc loads too — musl aliases `libc.so.6` to itself — and then\n' +
+                '  fails at dlopen on its first glibc-only symbol:\n' +
+                '    Error relocating <prebuild>.so: <symbol>: symbol not found\n' +
+                '  A bridge lost that way is silently absent from the next build rather than\n' +
+                '  reported, so the first symptom can be an unrelated-looking bundler error\n' +
+                '  (`Could not load <file>` from rolldown, for the CSS bridge). Nothing to\n' +
+                '  install: no `-musl` package is published for any target yet.');
+        }
     }
     maybeInstallGitHooks();
 }

package/lib/commands/test.d.ts

@@ -9,4 +9,20 @@ interface TestOptions {
     verbose?: boolean;
 }
 export declare const testCommand: Command<unknown, TestOptions>;
+/**
+ * True when `outfile` is at least as new as every build input of the package
+ * at `cwd`.
+ *
+ * The set is {@link packageBuildInputs}, the same one the build cache hashes.
+ * It used to be `dirname(entry)` — `tests/` for any package whose suite lives
+ * there, so `src/**` was never walked: a change to the code UNDER TEST left
+ * the bundle "fresh" and `gjsify test` reran the previous build and reported
+ * on it. That went both ways inside one dependency bump — a green run
+ * measuring a version that was no longer installed, then a red one after the
+ * source had already been repaired (#1651).
+ *
+ * `outdir` is subtracted as this command's own output; `entry` is added
+ * because `--entry ../shared/test.mts` may point outside the package.
+ */
+export declare function isFresh(outfile: string, entry: string, cwd: string, outdir: string): boolean;
 export {};

package/lib/commands/test.js

@@ -5,8 +5,9 @@
 // just needs `src/test.mts` aggregating its `@gjsify/unit` suites; this
 // command builds it for GJS + Node and runs each output, aggregating
 // exit codes.
-import { existsSync, statSync, readdirSync } from 'node:fs';
-import { join, dirname, resolve, relative } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import { join, resolve, relative, sep } from 'node:path';
+import { newestDepSignalMtimeMs, newestInputMtimeMs, packageBuildInputs } from '../utils/package-inputs.js';
 import { isRuntimeAvailable, RUNTIMES } from '../utils/runtimes.js';
 import { nodeBinary } from '../utils/run-node.js';
 import { describeExit, spawnToCompletion } from '../utils/spawn.js';
@@ -99,7 +100,7 @@ export const testCommand = {
             const outfile = join(outdir, `test.${runtime}.mjs`);
             // Build stage (skip if --no-build OR (not --rebuild AND outfile fresher than src)).
             if (args.build !== false) {
-                const needsBuild = args.rebuild || !isFresh(outfile, entry);
+                const needsBuild = args.rebuild || !isFresh(outfile, entry, cwd, outdir);
                 if (needsBuild) {
                     const buildStart = Date.now();
                     if (args.verbose) {
@@ -204,16 +205,35 @@ async function runTestBundle(outfile, runtime) {
     if (result.code !== 0)
         throw new Error(`node exited with ${describeExit(result)}`);
 }
-/** True when `outfile` exists and is newer than every `.ts`/`.mts` file under the entry's directory tree. */
-function isFresh(outfile, entry) {
+/**
+ * True when `outfile` is at least as new as every build input of the package
+ * at `cwd`.
+ *
+ * The set is {@link packageBuildInputs}, the same one the build cache hashes.
+ * It used to be `dirname(entry)` — `tests/` for any package whose suite lives
+ * there, so `src/**` was never walked: a change to the code UNDER TEST left
+ * the bundle "fresh" and `gjsify test` reran the previous build and reported
+ * on it. That went both ways inside one dependency bump — a green run
+ * measuring a version that was no longer installed, then a red one after the
+ * source had already been repaired (#1651).
+ *
+ * `outdir` is subtracted as this command's own output; `entry` is added
+ * because `--entry ../shared/test.mts` may point outside the package.
+ */
+export function isFresh(outfile, entry, cwd, outdir) {
     if (!existsSync(outfile))
         return false;
-    const outMtime = statSync(outfile).mtimeMs;
-    const srcRoot = dirname(entry);
-    // Conservative: walk the src tree once. If the package has no `src/`,
-    // fall back to entry-only check.
     try {
-        const newest = newestMtimeUnder(existsSync(srcRoot) ? srcRoot : entry);
+        const outMtime = statSync(outfile).mtimeMs;
+        const extraOutputs = [];
+        const outdirRel = relative(cwd, outdir).split(sep).join('/');
+        if (outdirRel !== '' && !outdirRel.startsWith('../'))
+            extraOutputs.push(outdirRel);
+        const newest = Math.max(newestInputMtimeMs(packageBuildInputs(cwd, { extraOutputs })), statSync(entry).mtimeMs, 
+        // A dependency bump changes no file in the package — and that is
+        // the shape #1651 was found in. `node_modules` is far too large
+        // to stat per run, so the lockfile stands in for it.
+        newestDepSignalMtimeMs(cwd));
         return outMtime >= newest;
     }
     catch {
@@ -221,22 +241,3 @@ function isFresh(outfile, entry) {
         return false;
     }
 }
-function newestMtimeUnder(path) {
-    const st = statSync(path);
-    if (st.isFile())
-        return st.mtimeMs;
-    let max = st.mtimeMs;
-    for (const entry of readdirSync(path, { withFileTypes: true })) {
-        if (entry.name === 'node_modules' ||
-            entry.name === 'dist' ||
-            entry.name === 'lib' ||
-            entry.name.startsWith('.')) {
-            continue;
-        }
-        const child = join(path, entry.name);
-        const m = newestMtimeUnder(child);
-        if (m > max)
-            max = m;
-    }
-    return max;
-}

package/lib/commands/upgrade.js

@@ -12,11 +12,15 @@
 //      matching packages automatically without prompting; same selection
 //      logic as above but no UI loop.
 //
-//   3. `--align`: offline consistency-only mode. Finds deps declared at
-//      multiple ranges across the workspace and proposes a single range
-//      (the highest declared) — no registry calls.
+//   3. `--align`: offline repair mode. Finds deps declared at multiple ranges
+//      across the workspace and proposes a single range (the highest declared)
+//      — no registry calls. With `--exact` it repairs the second question too:
+//      a dep every manifest declares identically as `^4.1.0` is consistent and
+//      still carries an operator, so the operator goes as well.
 //
-//   4. `--check`: CI gate. Exits non-zero when any inconsistency exists.
+//   4. `--check`: CI gate. Exits non-zero when any inconsistency exists; with
+//      `--exact`, also when any matched declaration carries a range operator.
+//      Whatever `--check` rejects, `--align` with the same flags repairs.
 //
 // Filters:
 //
@@ -36,7 +40,7 @@ import { parse } from '@gjsify/semver';
 import { DEFAULT_REGISTRY, fetchPackument, parseNpmrc } from '@gjsify/npm-registry';
 import { discoverWorkspaces, filterWorkspaces } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
-import { groupByDependency, findInconsistencies, } from '../utils/dep-aggregation.js';
+import { groupByDependency, findInconsistencies, isInconsistent, } from '../utils/dep-aggregation.js';
 export const upgradeCommand = {
     command: 'upgrade',
     description: 'Workspace-aware dependency upgrades. Walks every package.json in the monorepo, groups by dep, flags inconsistencies. `--latest` / `--minor` / `--patch` for bulk-mode, `--align` for offline consistency-only mode, `--check` for CI drift detection.',
@@ -71,7 +75,7 @@ export const upgradeCommand = {
             type: 'string',
         })
             .option('align', {
-            description: 'Offline consistency mode: find deps declared at multiple ranges across the workspace and align them to the highest. No registry calls.',
+            description: 'Offline repair mode: find deps declared at multiple ranges across the workspace and align them to the highest. With `--exact`, also drop the range operator from declarations that already agree. No registry calls.',
             type: 'boolean',
             default: false,
         })
@@ -81,7 +85,7 @@ export const upgradeCommand = {
             default: false,
         })
             .option('exact', {
-            description: 'Pin without a range operator. When writing, emits `1.2.3` instead of `^1.2.3`; with `--check`, fails on any matched dep that carries one. Pair with `--filter` — a repository-wide exactness check fails on every ordinary caret dep by design.',
+            description: 'Pin without a range operator. When writing, emits `1.2.3` instead of `^1.2.3`; with `--check`, fails on any matched dep that carries one; with `--align`, repairs exactly that. Pair with `--filter` — a repository-wide exactness run touches every ordinary caret dep by design.',
             type: 'boolean',
             default: false,
         })
@@ -348,22 +352,63 @@ function runCheckMode(groups, exact = false) {
             console.error(`    ${range.padEnd(16)} — ${holders.join(', ')}`);
         }
     }
-    console.error(`\nFix: run \`gjsify upgrade --align\` (offline; aligns each dep to its highest declared range).`);
+    console.error(exact
+        ? `\nFix: run \`gjsify upgrade --align --exact\` (offline; aligns each dep to its highest declared version and drops the operator).`
+        : `\nFix: run \`gjsify upgrade --align\` (offline; aligns each dep to its highest declared range).`);
     process.exit(1);
 }
+/**
+ * The groups `--align` has work on.
+ *
+ * Inconsistency is the whole question for a bare `--align`: a dep every manifest declares
+ * identically is done. `--exact` asks a second one, and the two do not overlap — a tree
+ * where every manifest says `^4.1.0` is perfectly consistent and carries an operator on
+ * every one of those declarations, which is precisely what `--check --exact` rejects.
+ *
+ * Selecting on inconsistency alone therefore made the repair that `--check --exact`'s own
+ * failure message names answer `nothing to do` to the tree it was pointed at: the gate
+ * demanded a property the fix could not deliver, cheerfully. Measured on bauplaner's five
+ * `@girs/*` declarations, all five `^4.1.0` and all five consistent.
+ */
+function alignTargets(groups, exact) {
+    if (!exact)
+        return findInconsistencies(groups);
+    return groups.filter((g) => isInconsistent(g) || g.occurrences.some((o) => o.prefix !== ''));
+}
+/**
+ * A repair that silently skipped part of its job must not report success.
+ *
+ * The loop that produces is gate red → repair "done" → gate red, where the second red
+ * reads as if the repair had never run. `^1.x` is the shape that lands here: `--check
+ * --exact` flags the operator, and no single version can be read out of the range to pin
+ * it at, so there is nothing to write and the CLI says which deps those are instead.
+ */
+function reportUnrepairable(groups) {
+    console.error(`\ngjsify upgrade --align: ${groups.length} dep(s) left unrepaired — no version to align on:\n`);
+    for (const g of groups) {
+        console.error(`  ${ANSI.bold}${g.name}${ANSI.reset}  ${[...g.declaredRanges].join(', ')}`);
+    }
+    console.error(`\nThose ranges name no single version. Edit them by hand, or resolve one with \`--latest\`.`);
+    return process.exit(1);
+}
 function runAlignMode(groups, args) {
-    const inconsistencies = findInconsistencies(groups);
-    if (inconsistencies.length === 0) {
-        console.log(`gjsify upgrade --align: nothing to do. ${groups.length} dep(s) already consistent.`);
+    const exact = args.exact ?? false;
+    const targets = alignTargets(groups, exact);
+    if (targets.length === 0) {
+        console.log(`gjsify upgrade --align: nothing to do. ${groups.length} dep(s) already consistent` +
+            (exact ? `, every declaration pinned exactly.` : `.`));
         return;
     }
-    // For each inconsistency, the alignment target is the highest declared version
-    // — preserve the prefix of the dominant occurrence so the range shape doesn't
-    // mutate (caret stays caret, tilde stays tilde).
+    // For each target, the alignment version is the highest declared one — preserve the
+    // prefix of the dominant occurrence so the range shape doesn't mutate (caret stays
+    // caret, tilde stays tilde). Under `--exact` the prefix is dropped, in `targetRange`.
     const updates = [];
-    for (const g of inconsistencies) {
-        if (!g.highestVersion)
+    const unrepairable = [];
+    for (const g of targets) {
+        if (!g.highestVersion) {
+            unrepairable.push(g);
             continue;
+        }
         // Pick a prefix: use the prefix of the dominant range; if dominant has
         // no prefix, default to "^" (the npm-cli default).
         const dominantOcc = g.occurrences.find((o) => o.currentRange === g.dominantRange);
@@ -375,21 +420,24 @@ function runAlignMode(groups, args) {
             occurrences: g.occurrences.map((o) => ({ ...o, prefix })),
         });
     }
-    if (updates.length === 0) {
-        console.log('gjsify upgrade --align: inconsistencies present but no parseable target version. No-op.');
-        return;
-    }
-    console.log(`gjsify upgrade --align: aligning ${updates.length} inconsistent dep(s) to their highest declared version:\n`);
-    for (const u of updates) {
-        const newPrefix = u.occurrences[0]?.prefix ?? '^';
-        console.log(`  ${u.name.padEnd(28)}  ranges: ${[...u.declaredRanges].join(', ')}  →  ${targetRange(newPrefix, u.latestVersion, args.exact ?? false)}`);
-    }
-    if (args.dryRun) {
-        console.log('\n[gjsify upgrade --align] --dry-run: no files changed.');
-        return;
+    if (updates.length > 0) {
+        console.log(exact
+            ? `gjsify upgrade --align --exact: pinning ${updates.length} dep(s) to their highest declared version, without a range operator:\n`
+            : `gjsify upgrade --align: aligning ${updates.length} inconsistent dep(s) to their highest declared version:\n`);
+        for (const u of updates) {
+            const newPrefix = u.occurrences[0]?.prefix ?? '^';
+            console.log(`  ${u.name.padEnd(28)}  ranges: ${[...u.declaredRanges].join(', ')}  →  ${targetRange(newPrefix, u.latestVersion, exact)}`);
+        }
+        if (args.dryRun) {
+            console.log('\n[gjsify upgrade --align] --dry-run: no files changed.');
+        }
+        else {
+            const files = applyToFiles(updates, exact);
+            console.log(`\n✏️  updated ${updates.length} dep(s) across ${files} package.json file(s).`);
+        }
     }
-    const files = applyToFiles(updates, args.exact);
-    console.log(`\n✏️  updated ${updates.length} dep(s) across ${files} package.json file(s).`);
+    if (unrepairable.length > 0)
+        return reportUnrepairable(unrepairable);
 }
 // ─── Registry resolution (group-aware) ─────────────────────────────────
 async function resolveCandidateGroups(groups, npmrc, verbose, mode) {