@gjsify/cli 0.52.0 → 0.53.0

package/lib/commands/upgrade.d.ts

@@ -29,6 +29,21 @@ export declare const upgradeCommand: Command<unknown, UpgradeOptions>;
  * Returns the number of offending declarations so the caller can exit once for both arms.
  */
 export declare function reportInexactRanges(groups: readonly DependencyGroup[]): number;
+/**
+ * Check that every lockfile resolution satisfies the ranges declared for it.
+ *
+ * `gjsify upgrade --check` compares declared ranges against each other across
+ * workspaces. It does NOT compare the resolution against any of them, so a
+ * lockfile entry that violates every declaration in the repo passes silently.
+ *
+ * This check reads the lockfile, resolves each entry's version, and verifies
+ * it satisfies at least one declared range for that dependency.
+ *
+ * @param groups dependency groups with declared ranges
+ * @param cwd working directory
+ * @returns number of violations
+ */
+export declare function checkLockfileRangeViolations(groups: readonly DependencyGroup[], cwd: string): number;
 /**
  * The range a dependency will be WRITTEN at.
  *

package/lib/commands/upgrade.js

@@ -36,7 +36,7 @@ import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { createInterface } from 'node:readline/promises';
-import { parse } from '@gjsify/semver';
+import { parse, satisfies } 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';
@@ -325,7 +325,81 @@ export function reportInexactRanges(groups) {
     }
     return total;
 }
-function runCheckMode(groups, exact = false) {
+/**
+ * Check that every lockfile resolution satisfies the ranges declared for it.
+ *
+ * `gjsify upgrade --check` compares declared ranges against each other across
+ * workspaces. It does NOT compare the resolution against any of them, so a
+ * lockfile entry that violates every declaration in the repo passes silently.
+ *
+ * This check reads the lockfile, resolves each entry's version, and verifies
+ * it satisfies at least one declared range for that dependency.
+ *
+ * @param groups dependency groups with declared ranges
+ * @param cwd working directory
+ * @returns number of violations
+ */
+export function checkLockfileRangeViolations(groups, cwd) {
+    const lockPath = join(cwd, 'gjsify-lock.json');
+    if (!existsSync(lockPath))
+        return 0;
+    let lock;
+    try {
+        lock = JSON.parse(readFileSync(lockPath, 'utf-8'));
+    }
+    catch {
+        return 0;
+    }
+    if (!lock.packages)
+        return 0;
+    // Build a map: dep name -> set of declared ranges
+    const declaredRanges = new Map();
+    for (const g of groups) {
+        const ranges = declaredRanges.get(g.name) ?? new Set();
+        for (const occ of g.occurrences) {
+            ranges.add(occ.currentRange);
+        }
+        declaredRanges.set(g.name, ranges);
+    }
+    let violations = 0;
+    for (const [key, entry] of Object.entries(lock.packages)) {
+        if (!entry.version)
+            continue;
+        // Only check direct dependencies — the single-segment "node_modules/<name>" form.
+        // A deep transitive resolution (e.g. "node_modules/a/node_modules/b") is pinned by
+        // its parent, not by the root's declared range, and must not be checked against it.
+        const parts = key.split('node_modules/');
+        if (parts.length !== 2)
+            continue;
+        const depName = parts[1];
+        const ranges = declaredRanges.get(depName);
+        if (!ranges || ranges.size === 0)
+            continue;
+        // Check if the resolved version satisfies at least one declared range
+        let satisfied = false;
+        for (const range of ranges) {
+            try {
+                if (entry.version && satisfies(entry.version, range)) {
+                    satisfied = true;
+                    break;
+                }
+            }
+            catch {
+                // Invalid range, skip
+            }
+        }
+        if (!satisfied) {
+            console.error(`  ${depName}: lockfile has ${entry.version}, but declared ranges are ${[...ranges].join(', ')}`);
+            violations++;
+        }
+    }
+    if (violations > 0) {
+        console.error(`gjsify upgrade --check: FAIL. ${violations} lockfile entr${violations === 1 ? 'y' : 'ies'} violate declared ranges:\n`);
+    }
+    return violations;
+}
+function runCheckMode(groups, exact = false, cwd = process.cwd()) {
+    const lockfileViolations = checkLockfileRangeViolations(groups, cwd);
     const inexact = exact ? reportInexactRanges(groups) : 0;
     const inconsistencies = findInconsistencies(groups);
     if (inconsistencies.length === 0 && inexact > 0) {

package/lib/commands/webext/index.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../../types/index.js';
+export declare const webextCommand: Command;

package/lib/commands/webext/index.js

@@ -0,0 +1,15 @@
+// `gjsify webext` — yargs subcommand-group dispatcher (ADR 0077).
+//
+// Wires {build, zip, dev}; each is a self-contained `Command<>` in `subcommands.ts`,
+// the same composition `flatpak/index.ts` uses.
+import { webextBuildCommand, webextDevCommand, webextZipCommand } from './subcommands.js';
+export const webextCommand = {
+    command: 'webext <subcommand>',
+    description: 'Browser extensions: build, zip and develop one WebExtension for Chrome, Edge, Firefox and Safari.',
+    builder: (yargs) => yargs
+        .command(webextBuildCommand.command, webextBuildCommand.description, webextBuildCommand.builder, webextBuildCommand.handler)
+        .command(webextZipCommand.command, webextZipCommand.description, webextZipCommand.builder, webextZipCommand.handler)
+        .command(webextDevCommand.command, webextDevCommand.description, webextDevCommand.builder, webextDevCommand.handler)
+        .demandCommand(1)
+        .strict(),
+};

package/lib/commands/webext/subcommands.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from '../../types/index.js';
+interface WebextArgs {
+    target?: string[];
+    outDir?: string;
+    define: string[];
+    mode?: string;
+    launch: boolean;
+    browserBinary?: string;
+    profile?: string;
+    headless: boolean;
+    debounce: number;
+}
+export declare const webextBuildCommand: Command<unknown, WebextArgs>;
+export declare const webextZipCommand: Command<unknown, WebextArgs>;
+export declare const webextDevCommand: Command<unknown, WebextArgs>;
+export {};

package/lib/commands/webext/subcommands.js

@@ -0,0 +1,204 @@
+// `gjsify webext build|zip|dev` — browser extensions as a project shape
+// (ADR 0077). The command owns the folder around the bundles: one per target,
+// with a manifest composed for that target, pages, icons, public files and
+// locales. The bundles themselves are ordinary `gjsify build --app browser`
+// runs, re-entered in-process like `gjsify dev` does.
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { buildWebext } from '../../utils/webext/build.js';
+import { resolveWebextConfig, selectTargets } from '../../utils/webext/config.js';
+import { defaultDevProfile, resolveWebExt, WEB_EXT_MISSING, webExtRunArgs, } from '../../utils/webext/launch.js';
+function loadConfig(cwd) {
+    const manifest = join(cwd, 'package.json');
+    if (!existsSync(manifest))
+        throw new Error(`gjsify webext: no package.json in ${cwd}.`);
+    return resolveWebextConfig(JSON.parse(readFileSync(manifest, 'utf8')), cwd);
+}
+/** `--define K=V` entries on top of the config's map, the way `gjsify build` spells them. */
+function effectiveDefines(config, flags) {
+    const out = { ...config.define };
+    for (const flag of flags) {
+        const at = flag.indexOf('=');
+        if (at <= 0)
+            throw new Error(`gjsify webext: --define "${flag}" is not KEY=VALUE.`);
+        out[flag.slice(0, at)] = flag.slice(at + 1);
+    }
+    return out;
+}
+/** One bundle, through the ordinary build command in this process. */
+async function bundleInProcess(request) {
+    const { runCli } = await import('../../cli-app.js');
+    const argv = ['build', request.entry, '--app', 'browser', '--format', request.format, '--outfile', request.outfile];
+    for (const [key, value] of Object.entries(request.define))
+        argv.push('--define', `${key}=${value}`);
+    if (!request.minify)
+        argv.push('--no-minify');
+    await runCli(argv);
+}
+const targetOption = {
+    description: 'Build only these targets (default: every target in gjsify.webext.targets).',
+    type: 'string',
+    array: true,
+};
+const outDirOption = {
+    description: 'Output directory (default: gjsify.webext.outDir, else .output).',
+    type: 'string',
+};
+const defineOption = {
+    description: 'Compile-time constant for every bundle, KEY=VALUE (repeatable); wins over gjsify.webext.define.',
+    type: 'string',
+    array: true,
+    default: [],
+};
+async function runBuild(args, zip) {
+    const cwd = process.cwd();
+    const config = loadConfig(cwd);
+    const mode = args.mode === 'development' ? 'development' : 'production';
+    await buildWebext({
+        config,
+        targets: selectTargets(config, args.target),
+        outDir: args.outDir ? resolve(cwd, args.outDir) : config.outDir,
+        mode,
+        define: effectiveDefines(config, args.define),
+        inPlace: false,
+        zip,
+        bundle: bundleInProcess,
+    });
+}
+export const webextBuildCommand = {
+    command: 'build',
+    description: 'Build one extension folder per target: bundles, pages, icons, locales and the manifest.',
+    builder: (yargs) => yargs
+        .option('target', targetOption)
+        .option('out-dir', outDirOption)
+        .option('define', defineOption)
+        .option('mode', {
+        description: 'Passed to the manifest as ctx.mode; development also skips minification.',
+        type: 'string',
+        choices: ['production', 'development'],
+        default: 'production',
+    }),
+    handler: (args) => runBuild(args, false),
+};
+export const webextZipCommand = {
+    command: 'zip',
+    description: 'Production build, then one store-ready <name>-<version>-<target>.zip per target.',
+    builder: (yargs) => yargs.option('target', targetOption).option('out-dir', outDirOption).option('define', defineOption),
+    handler: (args) => runBuild(args, true),
+};
+/** The dev target when none is asked for: the first Firefox target, since web-ext's Firefox driver needs no extra binary. */
+function devTarget(config, requested) {
+    if (requested && requested.length > 1)
+        throw new Error('gjsify webext dev: pass one --target.');
+    const [chosen] = selectTargets(config, requested);
+    if (requested && requested.length === 1)
+        return chosen;
+    return config.targets.find((t) => t.browser === 'firefox') ?? chosen;
+}
+/**
+ * What the loop watches: every top-level directory except `node_modules`,
+ * dot-directories and the output, recursively; the project root itself only
+ * for its own entries (`manifest.ts`, `package.json`); and `watch` extras.
+ */
+function devWatchTargets(config, outDir) {
+    const skip = (name) => name === 'node_modules' || name.startsWith('.');
+    const out = [{ path: config.root, recursive: false }];
+    for (const entry of readdirSync(config.root, { withFileTypes: true })) {
+        const full = join(config.root, entry.name);
+        if (!entry.isDirectory() || skip(entry.name) || full === outDir || outDir.startsWith(full + sep))
+            continue;
+        out.push({ path: full, recursive: true });
+    }
+    for (const extra of config.watch)
+        out.push({ path: extra, recursive: true });
+    return out;
+}
+export const webextDevCommand = {
+    command: 'dev',
+    description: 'Build one target in development mode, launch it in a browser via web-ext, and rebuild in place on change.',
+    builder: (yargs) => yargs
+        .option('target', {
+        ...targetOption,
+        description: 'The target to run (default: the first Firefox target).',
+    })
+        .option('out-dir', { description: 'Output directory (default: <outDir>-dev).', type: 'string' })
+        .option('define', defineOption)
+        .option('launch', {
+        description: 'Start a browser with the extension (--no-launch only rebuilds).',
+        type: 'boolean',
+        default: true,
+    })
+        .option('browser-binary', { description: 'Browser executable web-ext should start.', type: 'string' })
+        .option('profile', {
+        description: 'Browser profile directory (default: $XDG_CACHE_HOME/gjsify/webext/<name>/<target>).',
+        type: 'string',
+    })
+        .option('headless', { description: 'Start the browser without a window.', type: 'boolean', default: false })
+        .option('debounce', { description: 'Quiet window in ms before a rebuild.', type: 'number', default: 200 }),
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const config = loadConfig(cwd);
+        const target = devTarget(config, args.target);
+        const outDir = args.outDir ? resolve(cwd, args.outDir) : `${config.outDir}-dev`;
+        const define = effectiveDefines(config, args.define);
+        const sourceDir = join(outDir, target.id);
+        let webExt = null;
+        if (args.launch) {
+            webExt = resolveWebExt(cwd);
+            if (webExt === null)
+                throw new Error(WEB_EXT_MISSING);
+        }
+        let browser = null;
+        const stopBrowser = () => {
+            browser?.kill();
+        };
+        // Registered BEFORE the loop's own handlers, which end in process.exit.
+        process.on('SIGINT', stopBrowser);
+        process.on('SIGTERM', stopBrowser);
+        const launch = async () => {
+            if (webExt === null || browser !== null)
+                return;
+            const profile = args.profile ? resolve(cwd, args.profile) : defaultDevProfile(config.name, target);
+            // web-ext creates the profile directory but not its parent (ENOENT on a fresh machine).
+            mkdirSync(dirname(profile), { recursive: true });
+            const argv = webExtRunArgs({
+                sourceDir,
+                target,
+                profile,
+                browserBinary: args.browserBinary,
+                headless: args.headless,
+            });
+            console.log(`[webext] launching ${target.id} with profile ${profile}`);
+            const { spawnSupervised } = await import('../../utils/watch-loop.js');
+            browser = await spawnSupervised(webExt.cmd, argv, webExt.env);
+            browser.on('exit', (code) => {
+                console.log(`[webext] browser closed (${code ?? 0}) — stopping`);
+                process.exit(0);
+            });
+        };
+        const { runWatchLoop } = await import('../../utils/watch-loop.js');
+        await runWatchLoop({
+            dir: cwd,
+            dirLabel: '.',
+            label: 'webext',
+            watch: devWatchTargets(config, outDir),
+            ignore: (changed) => changed === outDir || changed.startsWith(outDir + sep),
+            build: async () => {
+                await buildWebext({
+                    config,
+                    targets: [target],
+                    outDir,
+                    mode: 'development',
+                    define,
+                    inPlace: true,
+                    zip: false,
+                    bundle: bundleInProcess,
+                });
+                // After the first SUCCESSFUL build: web-ext on a folder with no manifest.json exits at once.
+                await launch();
+            },
+            spawnChild: null,
+            debounceMs: args.debounce,
+        });
+    },
+};

package/lib/types/config-data.d.ts

@@ -743,7 +743,7 @@ export interface ShipFlatpakOptions {
  * here (ADR 0024 § 8; the window is `utils/ship/flatpak-config.ts`). They are
  * NOT marked `@deprecated`: for the subcommands in this group they are still
  * the only spelling, and those commands have not moved under `ship` yet
- * (`status/open-todos.md`). Nothing else in this block is deprecated at all —
+ * (`status/open-todos/README.md`). Nothing else in this block is deprecated at all —
  * the {@link AppMetadata} half is a designed alias, not a legacy one.
  */
 export interface ConfigDataFlatpak extends AppMetadata {

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

@@ -138,7 +138,7 @@ export declare function buildLauncherShims(opts: {
  * 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
+ * stays in `status/open-todos/README.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.
@@ -178,7 +178,7 @@ export declare function buildNativeEnvPreamble(scanRoot: string, bakedDirs?: rea
  *
  * 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`.
+ * `status/open-todos/README.md`.
  */
 export declare function dyldFallbackPreamble(platform: string): string;
 /** POSIX `sh` single-quoting for a launcher's target path. */
@@ -263,6 +263,12 @@ export declare function buildShLauncher(targetAbs: string, opts: {
     envPreamble?: string;
     isGjsBundle: boolean;
     nodeFallbackAbs?: string;
+    /**
+     * The gjs to exec — `GJS_CONSOLE` for the CLI's self-shim. NAMED rather
+     * than pathed by default, so a missing interpreter fails the same way on
+     * every OS.
+     */
+    gjs?: string;
 }): string;
 /** True when a bin target is a GJS-runnable bundle rather than a Node script. */
 export declare function isGjsBundlePath(target: string): boolean;

package/lib/utils/bin-shim.js

@@ -349,7 +349,7 @@ function shQuote(s) {
  * 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
+ * stays in `status/open-todos/README.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.
@@ -449,7 +449,7 @@ export function buildNativeEnvPreamble(scanRoot, bakedDirs = [], target = {}) {
  *
  * 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`.
+ * `status/open-todos/README.md`.
  */
 export function dyldFallbackPreamble(platform) {
     if (platform !== 'darwin')
@@ -556,15 +556,16 @@ export function pickBinMap(pkgName, pkgJson) {
  */
 export function buildShLauncher(targetAbs, opts) {
     const preamble = opts.isGjsBundle ? (opts.envPreamble ?? '') : '';
+    const gjs = opts.gjs === undefined || opts.gjs === 'gjs' ? 'gjs' : shQuote(opts.gjs);
     if (opts.isGjsBundle && opts.nodeFallbackAbs !== undefined) {
         // The preamble only ever configures the GI search path, so it stays
         // inside the gjs branch — exporting it around a Node exec would be
         // inert at best and misleading to anyone reading the shim.
-        return (`#!/bin/sh\nif command -v gjs >/dev/null 2>&1; then\n${preamble}` +
-            `exec gjs -m ${shQuote(targetAbs)} "$@"\nfi\n` +
+        return (`#!/bin/sh\nif command -v ${gjs} >/dev/null 2>&1; then\n${preamble}` +
+            `exec ${gjs} -m ${shQuote(targetAbs)} "$@"\nfi\n` +
             `exec node ${shQuote(opts.nodeFallbackAbs)} "$@"\n`);
     }
-    const exec = opts.isGjsBundle ? `exec gjs -m ${shQuote(targetAbs)} "$@"` : `exec ${shQuote(targetAbs)} "$@"`;
+    const exec = opts.isGjsBundle ? `exec ${gjs} -m ${shQuote(targetAbs)} "$@"` : `exec ${shQuote(targetAbs)} "$@"`;
     return `#!/bin/sh\n${preamble}${exec}\n`;
 }
 /** True when a bin target is a GJS-runnable bundle rather than a Node script. */

package/lib/utils/bundle-inputs.d.ts

@@ -0,0 +1,84 @@
+import type { RolldownPluginOption } from 'rolldown';
+/**
+ * Bumped when the shape changes; a manifest of any other version is ignored.
+ *
+ * v2 adds `watchList`. A v1 manifest says nothing about whether the engine that
+ * wrote it could report a watch list at all, and the safe reading of "unknown"
+ * is "do not trust it": see {@link readBundleInputs}.
+ */
+export declare const BUNDLE_INPUTS_VERSION = 2;
+/** What a manifest says, once parsed. */
+export interface BundleInputs {
+    inputs: string[];
+    /** `false` = this bundle's build could not see plugin-read inputs at all. */
+    watchList: boolean;
+}
+/** The manifest that belongs to `outfile`. */
+export declare function bundleInputsPath(outfile: string): string;
+export interface BundleInputsRecorder {
+    /** Pass to the bundler as a plugin; it observes, it never transforms. */
+    plugin: RolldownPluginOption;
+    /**
+     * The build's own watch list — what the engine reports, which is its module
+     * set PLUS everything a plugin declared with `this.addWatchFile`. That is
+     * the only account of a file the bundler never turned into a module: the
+     * CSS plugin follows a stylesheet's `@import` chain with its own `readFile`,
+     * and no graph mentions the imported file.
+     */
+    addWatchFiles(watch: {
+        files: readonly string[];
+        reportedByEngine: boolean;
+    }): void;
+    /** The recorded inputs so far: sorted, deduplicated, existing files only. */
+    inputs(): string[];
+    /**
+     * Persist the manifest beside `outfile`, so the NEXT freshness check can
+     * judge against the same set. Never throws: a manifest that cannot be
+     * written must not fail a test run — it degrades the check to the package
+     * walk, and says so.
+     */
+    write(): void;
+}
+/**
+ * A plugin that records every module the build transforms, plus the writer for
+ * the manifest.
+ *
+ * `transform` rather than a graph API (`getModuleIds`/`getModuleInfo`) because
+ * it is the one hook both engines run and the native bridge translates
+ * (`bundler-pick.ts` picks it verbatim). Every module that reaches the
+ * transform stage was LOADED from disk, so the observed set is what the build
+ * read — the modules it then tree-shook away are still inputs of the next
+ * build, which is the direction that errs safely.
+ *
+ * The observation is KEPT alongside {@link BundleInputsRecorder.addWatchFiles}
+ * rather than replaced by it, and neither engine is the reason: the native
+ * engine has no watch list to hand over (`BundleResult` carries warnings and
+ * output only, and its JS context had no `addWatchFile` at all until
+ * `rolldown-native` grew one), so on GJS the observed set is the only account
+ * of the modules; on npm the watch list is a superset of it. Union: the cost of
+ * a redundant path is a `stat`, the cost of a missing one is a stale green.
+ */
+export declare function createBundleInputsRecorder(outfile: string): BundleInputsRecorder;
+/**
+ * The inputs recorded for `outfile` by the build that wrote it, or `null` when
+ * there is none to trust — never written, unreadable, or written by another
+ * version of this shape. `null` is the fallback the caller must handle, not an
+ * error: a bundle built by an older CLI, or copied in from elsewhere, has no
+ * manifest and is judged by the package walk alone.
+ */
+export declare function readBundleInputs(outfile: string): BundleInputs | null;
+/**
+ * Newest mtime (ms) among recorded inputs, or 0 for an empty set.
+ *
+ * A recorded input that has since VANISHED counts as CHANGED, exactly as the
+ * package walk counts one that vanished mid-walk: an input we cannot read is
+ * not evidence that the artifact is current. A workspace-package source deleted
+ * while the bundle still imports it is precisely that case, and skipping it
+ * would rerun a bundle built from a file that no longer exists.
+ *
+ * Safe only because the toolchain's own scratch is never RECORDED
+ * ({@link isToolchainScratch}): the globals-inject stub and the cached plugin
+ * bundles are written and deleted between builds, and treating their absence as
+ * a change would rebuild on every run, forever.
+ */
+export declare function newestBundleInputMtimeMs(inputs: readonly string[]): number;