@gjsify/cli 0.10.0 → 0.12.0

package/lib/utils/install-global.d.ts

@@ -10,6 +10,47 @@ export interface GlobalLayout {
  * `GJSIFY_GLOBAL_PREFIX` and `GJSIFY_GLOBAL_BIN_DIR` escape hatches for tests.
  */
 export declare function defaultGlobalLayout(): GlobalLayout;
+/**
+ * The GJS-native tooling bridges the global CLI needs to run a build under GJS.
+ *
+ * These are declared OPTIONAL peer dependencies of `@gjsify/cli` (so a plain
+ * `npm install @gjsify/cli` on Node — where the npm `rolldown` / `lightningcss`
+ * / `oxfmt` crates work — does not force a linux prebuild fetch). But a *global
+ * GJS install* exists precisely to run the GJS CLI, where there is NO npm
+ * fallback: `@gjsify/rolldown-native` is the only bundler engine (`gjsify build`
+ * hard-fails without it), `@gjsify/lightningcss-native` backs CSS lowering, and
+ * `@gjsify/oxfmt-native` backs `gjsify format`/`fix`. So the global installer
+ * lays them down explicitly, on top of the cli's resolved runtime deps.
+ *
+ * `@gjsify/rolldown-native` is the load-bearing one (build is dead without it);
+ * the other two degrade gracefully at runtime (CSS / format fall back), so all
+ * three are installed best-effort: a platform with no published prebuild for
+ * the engine just gets a warning + continue, mirroring how the optional-peer
+ * story already degrades on Node.
+ */
+export declare const GJS_ENGINE_PACKAGES: readonly ["@gjsify/rolldown-native", "@gjsify/lightningcss-native", "@gjsify/oxfmt-native"];
+/** True when `<prefix>/node_modules/@gjsify/rolldown-native` is laid down. */
+export declare function hasBundlerEngineInstalled(prefix: string): boolean;
+/**
+ * Best-effort install of the GJS-native engine packages into a global prefix.
+ *
+ * Each engine is installed in its own `installPackages` call so one engine that
+ * has no published prebuild for the current platform (the resolver throws "No
+ * version of … satisfies …", or the registry 404s) does NOT abort the others —
+ * it warns and continues. The bundler engine (`@gjsify/rolldown-native`) is the
+ * one a build truly needs; the failure surfaces a clear, actionable message.
+ *
+ * `version` is the dist-tag / version the top-level `@gjsify/cli` resolved to,
+ * so the engines move in lockstep with the bundle. It may be a concrete version
+ * (`0.11.0`) or a dist-tag (`latest`, `next`); both are valid spec suffixes.
+ *
+ * @param installFn Injected to keep this unit-testable without a real registry —
+ *   defaults to the production `installPackages` backend.
+ */
+export declare function installGjsEnginePackages(prefix: string, version: string, opts?: {
+    verbose?: boolean;
+    installFn?: (spec: string) => Promise<void>;
+}): Promise<void>;
 export interface LinkedBin {
     /** The bin-name (key from `bin` / `gjsify.bin`). */
     name: string;

package/lib/utils/install-global.js

@@ -39,6 +39,80 @@ export function defaultGlobalLayout() {
         binDir: binOverride ?? path.join(home, '.local', 'bin'),
     };
 }
+/**
+ * The GJS-native tooling bridges the global CLI needs to run a build under GJS.
+ *
+ * These are declared OPTIONAL peer dependencies of `@gjsify/cli` (so a plain
+ * `npm install @gjsify/cli` on Node — where the npm `rolldown` / `lightningcss`
+ * / `oxfmt` crates work — does not force a linux prebuild fetch). But a *global
+ * GJS install* exists precisely to run the GJS CLI, where there is NO npm
+ * fallback: `@gjsify/rolldown-native` is the only bundler engine (`gjsify build`
+ * hard-fails without it), `@gjsify/lightningcss-native` backs CSS lowering, and
+ * `@gjsify/oxfmt-native` backs `gjsify format`/`fix`. So the global installer
+ * lays them down explicitly, on top of the cli's resolved runtime deps.
+ *
+ * `@gjsify/rolldown-native` is the load-bearing one (build is dead without it);
+ * the other two degrade gracefully at runtime (CSS / format fall back), so all
+ * three are installed best-effort: a platform with no published prebuild for
+ * the engine just gets a warning + continue, mirroring how the optional-peer
+ * story already degrades on Node.
+ */
+export const GJS_ENGINE_PACKAGES = [
+    '@gjsify/rolldown-native',
+    '@gjsify/lightningcss-native',
+    '@gjsify/oxfmt-native',
+];
+/** True when `<prefix>/node_modules/@gjsify/rolldown-native` is laid down. */
+export function hasBundlerEngineInstalled(prefix) {
+    return fs.existsSync(path.join(prefix, 'node_modules', '@gjsify/rolldown-native', 'package.json'));
+}
+/**
+ * Best-effort install of the GJS-native engine packages into a global prefix.
+ *
+ * Each engine is installed in its own `installPackages` call so one engine that
+ * has no published prebuild for the current platform (the resolver throws "No
+ * version of … satisfies …", or the registry 404s) does NOT abort the others —
+ * it warns and continues. The bundler engine (`@gjsify/rolldown-native`) is the
+ * one a build truly needs; the failure surfaces a clear, actionable message.
+ *
+ * `version` is the dist-tag / version the top-level `@gjsify/cli` resolved to,
+ * so the engines move in lockstep with the bundle. It may be a concrete version
+ * (`0.11.0`) or a dist-tag (`latest`, `next`); both are valid spec suffixes.
+ *
+ * @param installFn Injected to keep this unit-testable without a real registry —
+ *   defaults to the production `installPackages` backend.
+ */
+export async function installGjsEnginePackages(prefix, version, opts = {}) {
+    const verbose = opts.verbose ?? false;
+    const installOne = opts.installFn ??
+        (async (spec) => {
+            // Lazy import to avoid a static cycle (install-backend → … → here)
+            // and to keep this module importable from the lighter unit tests.
+            const { installPackages } = await import('./install-backend.js');
+            await installPackages({ prefix, specs: [spec], verbose });
+        });
+    for (const name of GJS_ENGINE_PACKAGES) {
+        const spec = version ? `${name}@${version}` : name;
+        try {
+            await installOne(spec);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // `@gjsify/rolldown-native` is the bundler engine — its absence
+            // means `gjsify build` (and storybook / anything that builds) will
+            // hard-fail under GJS. Make that one loud; the other two degrade
+            // gracefully so a plain note suffices.
+            if (name === '@gjsify/rolldown-native') {
+                console.warn(`\nWarning: could not install the GJS bundler engine ${name}@${version} — ${msg}\n` +
+                    `  \`gjsify build\` (and storybook / flatpak) will fail under GJS until it is present.\n` +
+                    `  This usually means no prebuild is published for this platform (${process.platform}/${process.arch}).`);
+            }
+            else if (verbose) {
+                console.warn(`gjsify install: optional GJS engine ${name}@${version} not installed — ${msg}`);
+            }
+        }
+    }
+}
 /**
  * Install each top-level package's bin entries into `binDir` as small POSIX
  * `sh` launchers that exec the real bin. Reads each package's installed

package/lib/utils/install-progress.js

@@ -73,14 +73,38 @@ function makeTtyReporter(stream) {
         },
     };
 }
-// ──── Plain reporter — one line per phase begin + end (non-TTY) ────────────
+// ──── Plain reporter — phase begin/end + periodic heartbeat (non-TTY) ──────
+//
+// On a non-TTY (piped to a log file, CI, or captured output) the bar can't
+// `\r`-overwrite, so per-package lines are suppressed to avoid flooding the
+// log. But emitting NOTHING between `beginPhase` and `endPhase` makes a long
+// download/extract phase look frozen — the exact "no further output for 25+
+// minutes" symptom of a slow install. So we emit a low-frequency heartbeat:
+// at most one line per HEARTBEAT_MS, AND only after at least a few packages of
+// real progress, so a fast warm install (most nodes skipped) stays quiet while
+// a genuinely long phase reports `… N/M (X%)` every few seconds. This mirrors
+// what npm (`--loglevel http`) and pnpm log on non-TTY: progress you can watch
+// without it being one line per file.
+const HEARTBEAT_MS = 5_000;
 function makePlainReporter(stream) {
+    let lastHeartbeat = 0;
+    let lastReported = 0;
     return {
         beginPhase(phase, total) {
+            lastHeartbeat = Date.now();
+            lastReported = 0;
             stream.write(`gjsify install: ${PHASE_LABEL[phase]} ${total} package(s)\n`);
         },
-        update() {
-            // Per-package output would flood logs; skip on non-TTY.
+        update(ev) {
+            const now = Date.now();
+            if (now - lastHeartbeat < HEARTBEAT_MS)
+                return;
+            if (ev.current <= lastReported)
+                return;
+            lastHeartbeat = now;
+            lastReported = ev.current;
+            const pct = ev.total > 0 ? Math.round((ev.current / ev.total) * 100) : 0;
+            stream.write(`gjsify install: ${PHASE_LABEL[ev.phase]} ${ev.current}/${ev.total} (${pct}%)\n`);
         },
         endPhase(phase) {
             stream.write(`gjsify install: ${PHASE_LABEL[phase]} done\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.10.0",
+    "version": "0.12.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -120,19 +120,19 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.10.0",
-        "@gjsify/create-app": "^0.10.0",
-        "@gjsify/node-globals": "^0.10.0",
-        "@gjsify/node-polyfills": "^0.10.0",
-        "@gjsify/npm-registry": "^0.10.0",
-        "@gjsify/resolve-npm": "^0.10.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.10.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.10.0",
-        "@gjsify/semver": "^0.10.0",
-        "@gjsify/tar": "^0.10.0",
-        "@gjsify/tsc": "^0.10.0",
-        "@gjsify/web-polyfills": "^0.10.0",
-        "@gjsify/workspace": "^0.10.0",
+        "@gjsify/buffer": "^0.12.0",
+        "@gjsify/create-app": "^0.12.0",
+        "@gjsify/node-globals": "^0.12.0",
+        "@gjsify/node-polyfills": "^0.12.0",
+        "@gjsify/npm-registry": "^0.12.0",
+        "@gjsify/resolve-npm": "^0.12.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.12.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.12.0",
+        "@gjsify/semver": "^0.12.0",
+        "@gjsify/tar": "^0.12.0",
+        "@gjsify/tsc": "^0.12.0",
+        "@gjsify/web-polyfills": "^0.12.0",
+        "@gjsify/workspace": "^0.12.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -140,13 +140,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.10.0",
+        "@gjsify/unit": "^0.12.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.10.0",
-        "@gjsify/rolldown-native": "^0.10.0"
+        "@gjsify/oxfmt-native": "^0.12.0",
+        "@gjsify/rolldown-native": "^0.12.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {

package/showcases.json

@@ -49,6 +49,13 @@
             "package": "@gjsify/example-node-express-webserver",
             "description": "Express web server on GJS via @gjsify/http",
             "needsWebgl": false
+        },
+        {
+            "name": "adwaita-storybook",
+            "category": "gtk",
+            "package": "@gjsify/example-gtk-adwaita-storybook",
+            "description": "Interactive Libadwaita component browser — author one story per widget, rendered natively (GTK) and in the browser",
+            "needsWebgl": false
         }
     ]
 }