@gjsify/cli 0.26.0 → 0.27.0

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

@@ -64,8 +64,22 @@ function checkNpmPackage(id, name, packageName, cwd, severity, requiredBy) {
         return { id, name, found: false, severity, requiredBy };
     }
 }
+/**
+ * The package manager whose install command we may suggest.
+ *
+ * Probe order is PLATFORM-FIRST, not a single global list. On macOS the Linux
+ * managers are absent, so a flat list ending in `brew` would work by accident —
+ * but Homebrew also runs on Linux, where it is the LAST resort rather than the
+ * first (a Fedora host with linuxbrew installed wants `sudo dnf install`, whose
+ * packages carry the distro's own GI typelibs). Keying the order on
+ * `process.platform` states that intent instead of leaving it to list position.
+ *
+ * Returning `unknown` is a supported answer, not a failure: `buildInstallCommand`
+ * then prints no command rather than a wrong one. That is the honest result on a
+ * MacPorts or Nix host, and it is why this must never fall back to "probably brew".
+ */
 export function detectPackageManager() {
-    const managers = ['apt', 'dnf', 'pacman', 'zypper', 'apk'];
+    const managers = process.platform === 'darwin' ? ['brew'] : ['apt', 'dnf', 'pacman', 'zypper', 'apk', 'brew'];
     for (const pm of managers) {
         const result = tryExecFile('which', [pm]);
         if (result !== null)
@@ -212,7 +226,12 @@ function computeNeededOptionalDeps(cwd) {
  */
 export function runAllChecks(cwd) {
     const needed = computeNeededOptionalDeps(cwd);
-    return [...runMinimalChecks(), ...runRequiredChecks(cwd), ...runOptionalChecks(needed, cwd)];
+    return [
+        ...runMinimalChecks(),
+        ...runRequiredChecks(cwd),
+        ...runNativeBuildToolchainChecks(),
+        ...runOptionalChecks(needed, cwd),
+    ];
 }
 /**
  * Minimal checks needed to run any GJS example (Node + GJS binaries only).
@@ -249,6 +268,51 @@ function runRequiredChecks(_cwd) {
     results.push(checkPkgConfig('gobject-introspection', 'GObject Introspection', 'gobject-introspection-1.0', 'required'));
     return results;
 }
+/**
+ * The native BUILD toolchain — needed to COMPILE a prebuild from source
+ * (`gjsify workspace <pkg> build:prebuilds`), never to run one.
+ *
+ * Optional by design, and the distinction is the whole point: every `*-native`
+ * package SHIPS its `.so`/`.dylib` + `.typelib` inside the tarball, so a user who
+ * installs `@gjsify/tls-native` and runs it needs none of these. Marking them
+ * `required` would fail `gjsify check` for the large majority who correctly have
+ * no Vala compiler on the machine.
+ *
+ * They are reported at all because the opposite silence is worse: without them a
+ * `build:prebuilds` failure surfaces from inside meson as a missing-compiler
+ * error naming no package and no install command. That is the concrete shape of
+ * "gjsify is supposed to be batteries-included, so why is cargo not part of it" —
+ * the tools were always required, they were just never named.
+ *
+ * NB `meson` is checked one function up at `required` severity, which is
+ * inconsistent with its own backend being optional here. That predates this
+ * function and is left alone deliberately: flipping it changes the exit code of
+ * `gjsify check` for existing users, which is a decision of its own, not a
+ * side effect of documenting the toolchain.
+ */
+function runNativeBuildToolchainChecks() {
+    // Every meson/Vala bridge in the tree — all of them need valac + ninja.
+    const valaBridges = [
+        '@gjsify/http-soup-bridge',
+        '@gjsify/http2-native',
+        '@gjsify/lightningcss-native',
+        '@gjsify/oxfmt-native',
+        '@gjsify/rolldown-native',
+        '@gjsify/sab-native',
+        '@gjsify/terminal-native',
+        '@gjsify/tls-native',
+        '@gjsify/webgl',
+        '@gjsify/webrtc-native',
+    ];
+    // 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'];
+    return [
+        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),
+    ];
+}
 /**
  * Optional system dependencies — only checked if the corresponding @gjsify/*
  * package is in use. Missing optional deps generate warnings, not errors.
@@ -286,6 +350,9 @@ const PM_PACKAGES = {
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkg-config',
         meson: 'meson',
+        ninja: 'ninja-build',
+        vala: 'valac',
+        cargo: 'cargo',
         gtk4: 'libgtk-4-dev',
         libadwaita: 'libadwaita-1-dev',
         libsoup3: 'libsoup-3.0-dev',
@@ -306,6 +373,9 @@ const PM_PACKAGES = {
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf-pkg-config',
         meson: 'meson',
+        ninja: 'ninja-build',
+        vala: 'vala',
+        cargo: 'cargo',
         gtk4: 'gtk4-devel',
         libadwaita: 'libadwaita-devel',
         libsoup3: 'libsoup3-devel',
@@ -326,6 +396,9 @@ const PM_PACKAGES = {
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
         meson: 'meson',
+        ninja: 'ninja',
+        vala: 'vala',
+        cargo: 'rust',
         gtk4: 'gtk4',
         libadwaita: 'libadwaita',
         libsoup3: 'libsoup3',
@@ -346,6 +419,9 @@ const PM_PACKAGES = {
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkg-config',
         meson: 'meson',
+        ninja: 'ninja',
+        vala: 'vala',
+        cargo: 'cargo',
         gtk4: 'gtk4-devel',
         libadwaita: 'libadwaita-devel',
         libsoup3: 'libsoup-3_0-devel',
@@ -366,6 +442,9 @@ const PM_PACKAGES = {
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
         meson: 'meson',
+        ninja: 'ninja',
+        vala: 'vala',
+        cargo: 'cargo',
         gtk4: 'gtk4.0-dev',
         libadwaita: 'libadwaita-dev',
         libsoup3: 'libsoup3-dev',
@@ -381,6 +460,49 @@ const PM_PACKAGES = {
         gnutls: 'gnutls-dev',
         nghttp2: 'nghttp2-dev',
     },
+    // macOS. Names verified against homebrew/core rather than inferred from the
+    // Linux rows — the mapping is NOT mechanical: Homebrew ships no `-dev`/`-devel`
+    // split (one formula carries headers, pkg-config file and typelib), `pkgconf`
+    // is what actually provides `bin/pkg-config`, and `libsoup` is the 3.x formula
+    // (`libsoup@2` is the old one), so a `libsoup3` guess installs nothing.
+    //
+    // TWO IDS ARE DELIBERATELY ABSENT, and in both cases the absence IS the
+    // answer — printing a command that does not deliver the dependency would be
+    // strictly worse than printing nothing:
+    //   • `manette` — homebrew/core has no libmanette formula, and packaging one
+    //     would not help: libmanette is built on the Linux input subsystem and
+    //     reports raw evdev `BTN_*` codes (see @gjsify/gamepad's button-mapping),
+    //     which macOS does not have. A macOS @gjsify/gamepad means a
+    //     GameController.framework backend, not a missing brew formula.
+    //   • `webkitgtk` — a formula by that name EXISTS, which is the trap. It is
+    //     the GTK**3** build (it depends on `gtk+3` and ships `webkit2gtk-4.x`),
+    //     while @gjsify/iframe needs the GTK4 API `webkitgtk-6.0`. homebrew/core
+    //     packages no GTK4 WebKit at all, and the formula carries no bottle — so
+    //     `brew install webkitgtk` would be an hours-long source build of the
+    //     WRONG API that still leaves `pkg-config --exists webkitgtk-6.0` false.
+    // Recorded here so the next reader does not "fix" the gap by guessing a name;
+    // both are genuine platform gaps, not table omissions.
+    brew: {
+        gjs: 'gjs',
+        'blueprint-compiler': 'blueprint-compiler',
+        'pkg-config': 'pkgconf',
+        meson: 'meson',
+        ninja: 'ninja',
+        vala: 'vala',
+        cargo: 'rust',
+        gtk4: 'gtk4',
+        libadwaita: 'libadwaita',
+        libsoup3: 'libsoup',
+        'gobject-introspection': 'gobject-introspection',
+        gstreamer: 'gstreamer',
+        'gst-app': 'gst-plugins-base',
+        'gdk-pixbuf': 'gdk-pixbuf',
+        pango: 'pango',
+        pangocairo: 'pango',
+        cairo: 'cairo',
+        gnutls: 'gnutls',
+        nghttp2: 'nghttp2',
+    },
     unknown: {},
 };
 const PM_INSTALL_PREFIX = {
@@ -389,6 +511,8 @@ const PM_INSTALL_PREFIX = {
     pacman: 'sudo pacman -S',
     zypper: 'sudo zypper install',
     apk: 'sudo apk add',
+    // No `sudo`: Homebrew refuses to run as root and tells you so.
+    brew: 'brew install',
     unknown: '',
 };
 /**

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

@@ -0,0 +1,30 @@
+/** Everything {@link resolveClearTargets} needs from the outside world. */
+export interface ClearContext {
+    /** The package directory every target must stay inside. */
+    cwd: string;
+    /** Directory listing, for wildcard expansion. Throws when absent — treated as "nothing to clear". */
+    readdir: (dir: string) => string[];
+}
+/**
+ * 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.
+ */
+export declare function hasWildcard(segment: string): boolean;
+/** Compile one wildcard segment to an anchored regex, escaping every other metachar. */
+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.
+ */
+export declare function resolveClearTargets(paths: readonly string[], ctx: ClearContext): string[];

package/lib/utils/clear-targets.js

@@ -0,0 +1,114 @@
+// 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.
+//
+// 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.
+ */
+export function hasWildcard(segment) {
+    return segment.includes('*') || segment.includes('?');
+}
+/** Compile one wildcard segment to an anchored regex, escaping every other metachar. */
+export function segmentToRegExp(segment) {
+    const body = segment
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '[^/\\\\]*')
+        .replace(/\?/g, '[^/\\\\]');
+    return new RegExp(`^${body}$`);
+}
+/**
+ * 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.
+ */
+function assertInsideCwd(absolute, original, cwd) {
+    const rel = relative(cwd, absolute);
+    if (rel === '') {
+        throw new Error(`gjsify clear: refusing to delete the working directory itself ("${original}").`);
+    }
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error(`gjsify clear: "${original}" resolves to ${absolute}, outside the working directory ${cwd}. ` +
+            'Only paths inside the package may be cleared.');
+    }
+}
+/**
+ * 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.
+ */
+export function resolveClearTargets(paths, ctx) {
+    const out = [];
+    const seen = new Set();
+    for (const target of paths) {
+        for (const absolute of expandTarget(target, ctx)) {
+            assertInsideCwd(absolute, target, ctx.cwd);
+            if (seen.has(absolute))
+                continue;
+            seen.add(absolute);
+            out.push(absolute);
+        }
+    }
+    return out;
+}
+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.
+    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.
+    const dir = resolve(ctx.cwd, parent);
+    assertInsideCwdOrSelf(dir, target, ctx.cwd);
+    const re = segmentToRegExp(leaf);
+    let names;
+    try {
+        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.
+        return [];
+    }
+    return names
+        .filter((name) => re.test(name))
+        .sort()
+        .map((name) => join(dir, name));
+}
+/**
+ * Like {@link assertInsideCwd} but tolerates `cwd` itself — a wildcard's PARENT
+ * legitimately is the package root (`*.log`), while a wildcard's MATCH can never
+ * be (it always has a name appended).
+ */
+function assertInsideCwdOrSelf(absolute, original, cwd) {
+    if (relative(cwd, absolute) === '')
+        return;
+    assertInsideCwd(absolute, original, cwd);
+}

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

@@ -0,0 +1,41 @@
+/** Everything {@link planCopy} needs from the outside world. */
+export interface CopyContext {
+    /** The package directory every DESTINATION must stay inside. */
+    cwd: string;
+    /** Directory listing, for wildcard expansion. Throws when absent — treated as "no matches". */
+    readdir: (dir: string) => string[];
+}
+/** One resolved source → destination pair. Both absolute. */
+export interface CopyOperation {
+    from: string;
+    to: string;
+}
+/**
+ * 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.
+ *
+ * The rule, in full:
+ *   - a trailing `/` (or `\`) on the destination — the explicit spelling;
+ *   - more than one source;
+ *   - 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.
+ */
+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.
+ */
+export declare function planCopy(args: readonly string[], ctx: CopyContext): CopyOperation[];

package/lib/utils/copy-targets.js

@@ -0,0 +1,145 @@
+// 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.
+//
+// See `commands/copy.ts` for why the command exists at all.
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+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.
+ *
+ * The rule, in full:
+ *   - a trailing `/` (or `\`) on the destination — the explicit spelling;
+ *   - more than one source;
+ *   - 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.
+ */
+export function isDirectoryDestination(sources, dest) {
+    if (dest.endsWith('/') || dest.endsWith('\\'))
+        return true;
+    if (sources.length > 1)
+        return true;
+    return sources.some((s) => hasWildcard(s));
+}
+/**
+ * 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
+ * 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.
+ */
+function assertWritableDestination(absolute, original, cwd, allowSelf) {
+    const rel = relative(cwd, absolute);
+    if (rel === '') {
+        if (allowSelf)
+            return;
+        throw new Error(`gjsify copy: "${original}" is the working directory itself. ` +
+            'Name a file, or add a trailing "/" to copy INTO the directory.');
+    }
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error(`gjsify copy: "${original}" resolves to ${absolute}, outside the working directory ${cwd}. ` +
+            'Only paths inside the package may be written.');
+    }
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+function expandSource(source, ctx) {
+    const leaf = basename(source);
+    const parent = dirname(source);
+    if (hasWildcard(parent)) {
+        throw new Error(`gjsify copy: a wildcard is only supported in the last path segment — got "${source}".`);
+    }
+    if (!hasWildcard(leaf))
+        return [resolve(ctx.cwd, source)];
+    const dir = resolve(ctx.cwd, parent);
+    const re = segmentToRegExp(leaf);
+    let names;
+    try {
+        names = ctx.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((name) => re.test(name))
+        .sort()
+        .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.
+ */
+export function planCopy(args, ctx) {
+    if (args.length < 2) {
+        throw new Error('gjsify copy: needs at least one source and a destination. Usage: gjsify copy <sources…> <dest>');
+    }
+    const sources = args.slice(0, -1);
+    const dest = args[args.length - 1];
+    if (dest === '') {
+        throw new Error('gjsify copy: the destination is empty.');
+    }
+    const intoDirectory = isDirectoryDestination(sources, dest);
+    const absDest = resolve(ctx.cwd, dest);
+    assertWritableDestination(absDest, dest, ctx.cwd, intoDirectory);
+    const expanded = [];
+    for (const source of sources) {
+        if (source === '')
+            throw new Error('gjsify copy: a source path is empty.');
+        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.
+        throw new Error(`gjsify copy: "${dest}" names a single destination, but ${expanded.length} sources resolved.`);
+    }
+    const ops = [];
+    const seenDest = new Set();
+    for (const from of expanded) {
+        const to = intoDirectory ? join(absDest, basename(from)) : absDest;
+        if (from === to) {
+            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.
+            throw new Error(`gjsify copy: two sources would both be written to ${to}.`);
+        }
+        seenDest.add(to);
+        ops.push({ from, to });
+    }
+    return ops;
+}