agentic-qe 3.9.13 → 3.9.15

package/dist/init/browser-engine-installer.d.ts

@@ -13,6 +13,21 @@
  *   - No new runtime deps: shells out to `npm install -g vibium` via child_process.
  */
 import { type SpawnSyncReturns } from 'node:child_process';
+/**
+ * Default Vibium npm spec. Major-line pin via caret (`^26.3.18`) — npm
+ * semver will accept any 26.x.y >= 26.3.18 but reject 27.0.0+. The intent
+ * is to auto-receive security patches and additive minor features while
+ * blocking breaking-change major bumps, which is where Vibium's CLI
+ * contract (`go`, `--headless`, `viewport`, exit codes) can change.
+ *
+ * This is NOT a minor-line pin. If a future Vibium 26.y release changes
+ * the primitives' expectations, the CI smoke gate (scripts/smoke-test.sh)
+ * is the belt-and-suspenders check.
+ *
+ * Bump procedure: update this constant (e.g. to ^27.0.0 at a major), run
+ * scripts/smoke-test.sh against the new version, then land the bump.
+ */
+export declare const DEFAULT_VIBIUM_SPEC = "vibium@^26.3.18";
 /**
  * Spawner injected into {@link installBrowserEngine} so tests can mock the
  * shell-out without monkey-patching the child_process module (ESM namespaces
@@ -26,7 +41,7 @@ export type Spawner = (bin: string, args: string[], options: {
 export interface BrowserEngineInstallerOptions {
     /** Skip installation entirely (for --minimal or --no-browser-engine). */
     skip?: boolean;
-    /** Package name/version spec. Defaults to "vibium". */
+    /** Package name/version spec. Defaults to {@link DEFAULT_VIBIUM_SPEC}. */
     packageSpec?: string;
     /** Override the npm binary (default: "npm"). */
     npmBin?: string;
@@ -34,6 +49,8 @@ export interface BrowserEngineInstallerOptions {
     timeoutMs?: number;
     /** Test seam — inject a spawner to avoid hitting real processes. */
     spawner?: Spawner;
+    /** Test seam — inject a platform probe for cross-OS diagnostic tests. */
+    platformProbe?: PlatformProbe;
 }
 export type BrowserEngineInstallStatus = 'already-installed' | 'installed' | 'skipped' | 'install-failed' | 'npm-unavailable';
 export interface BrowserEngineInstallResult {
@@ -41,7 +58,49 @@ export interface BrowserEngineInstallResult {
     version?: string;
     message?: string;
     packageSpec: string;
+    /**
+     * Platform diagnostic emitted after a successful install. Present when
+     * the current host is one where Vibium's first-run Chrome auto-download
+     * is known to fail (e.g. Linux aarch64 at v26.3.x) and we were able to
+     * point at a system browser, or couldn't and are saying so explicitly.
+     */
+    platformHint?: PlatformHint;
+}
+export interface PlatformHint {
+    /**
+     * Short machine-readable tag for the condition being reported. Consumers
+     * can assert on this in tests or suppress the hint in known-good envs.
+     */
+    code: 'linux-arm64-system-chromium-found' | 'linux-arm64-no-system-chromium';
+    /** Single-line human message suitable for `console.warn`. */
+    message: string;
+    /**
+     * Optional filesystem path to a system browser binary the user can point
+     * Vibium at via `VIBIUM_BROWSER_PATH`.
+     */
+    browserPath?: string;
 }
+/**
+ * Injectable seam for `os.platform()` / `os.arch()`. Tests override this
+ * to simulate running on a different host.
+ */
+export interface PlatformProbe {
+    platform: () => NodeJS.Platform;
+    arch: () => string;
+    existsSync: (path: string) => boolean;
+}
+/**
+ * Build a platform hint for hosts where Vibium's first-run Chrome auto-
+ * download is known to fail. Today that's just Linux aarch64 at the
+ * pinned Vibium version (v26.3.x). Returns `undefined` when no hint
+ * applies, so callers can cheaply check for presence.
+ *
+ * Intentionally conservative: we don't mutate the user's env or create
+ * symlinks — we surface a diagnostic with an exact `VIBIUM_BROWSER_PATH`
+ * export the user can add. Silent modifications to system state are out
+ * of scope for an installer that runs during `aqe init`.
+ */
+export declare function diagnosePlatform(probe?: PlatformProbe): PlatformHint | undefined;
 /**
  * Detect whether `vibium` is already on PATH. Returns the version string
  * on success, `null` otherwise. Uses a short timeout because we don't want

package/dist/init/browser-engine-installer.js

@@ -13,7 +13,74 @@
  *   - No new runtime deps: shells out to `npm install -g vibium` via child_process.
  */
 import { spawnSync as realSpawnSync } from 'node:child_process';
+import * as os from 'node:os';
+import * as fs from 'node:fs';
 import { toErrorMessage } from '../shared/error-utils.js';
+/**
+ * Default Vibium npm spec. Major-line pin via caret (`^26.3.18`) — npm
+ * semver will accept any 26.x.y >= 26.3.18 but reject 27.0.0+. The intent
+ * is to auto-receive security patches and additive minor features while
+ * blocking breaking-change major bumps, which is where Vibium's CLI
+ * contract (`go`, `--headless`, `viewport`, exit codes) can change.
+ *
+ * This is NOT a minor-line pin. If a future Vibium 26.y release changes
+ * the primitives' expectations, the CI smoke gate (scripts/smoke-test.sh)
+ * is the belt-and-suspenders check.
+ *
+ * Bump procedure: update this constant (e.g. to ^27.0.0 at a major), run
+ * scripts/smoke-test.sh against the new version, then land the bump.
+ */
+export const DEFAULT_VIBIUM_SPEC = 'vibium@^26.3.18';
+const defaultPlatformProbe = {
+    platform: () => os.platform(),
+    arch: () => os.arch(),
+    existsSync: (p) => fs.existsSync(p),
+};
+/**
+ * Candidate paths for a system chromium binary on Linux distributions that
+ * package Chromium (Debian, Ubuntu, Fedora, Arch). Order matters: we return
+ * the first match, so list the most common locations first.
+ */
+const LINUX_SYSTEM_CHROMIUM_PATHS = [
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/snap/bin/chromium',
+];
+/**
+ * Build a platform hint for hosts where Vibium's first-run Chrome auto-
+ * download is known to fail. Today that's just Linux aarch64 at the
+ * pinned Vibium version (v26.3.x). Returns `undefined` when no hint
+ * applies, so callers can cheaply check for presence.
+ *
+ * Intentionally conservative: we don't mutate the user's env or create
+ * symlinks — we surface a diagnostic with an exact `VIBIUM_BROWSER_PATH`
+ * export the user can add. Silent modifications to system state are out
+ * of scope for an installer that runs during `aqe init`.
+ */
+export function diagnosePlatform(probe = defaultPlatformProbe) {
+    if (probe.platform() !== 'linux')
+        return undefined;
+    if (probe.arch() !== 'arm64')
+        return undefined;
+    const browserPath = LINUX_SYSTEM_CHROMIUM_PATHS.find((p) => probe.existsSync(p));
+    if (browserPath) {
+        return {
+            code: 'linux-arm64-system-chromium-found',
+            browserPath,
+            message: `Linux aarch64 detected. Vibium v26.3.x does not auto-download Chrome for Testing on ARM64. ` +
+                `Found system browser at ${browserPath}. Export VIBIUM_BROWSER_PATH=${browserPath} before running vibium.`,
+        };
+    }
+    return {
+        code: 'linux-arm64-no-system-chromium',
+        message: `Linux aarch64 detected. Vibium v26.3.x does not auto-download Chrome for Testing on ARM64, and no system ` +
+            `chromium was found on PATH (checked: ${LINUX_SYSTEM_CHROMIUM_PATHS.join(', ')}). ` +
+            `Install via \`apt-get install chromium\` (or your distro's equivalent), then export ` +
+            `VIBIUM_BROWSER_PATH=/usr/bin/chromium before running vibium.`,
+    };
+}
 function tryRun(spawner, bin, args, timeoutMs) {
     return spawner(bin, args, {
         encoding: 'utf8',
@@ -51,17 +118,20 @@ export function detectVibium(spawner = defaultSpawner, timeoutMs = 5_000) {
  * assets phase can log/summarize — never throws for expected failures.
  */
 export function installBrowserEngine(options = {}) {
-    const packageSpec = options.packageSpec || 'vibium';
+    const packageSpec = options.packageSpec || DEFAULT_VIBIUM_SPEC;
     if (options.skip) {
         return { status: 'skipped', packageSpec, message: 'install skipped by options' };
     }
     const spawner = options.spawner || defaultSpawner;
+    const platformProbe = options.platformProbe || defaultPlatformProbe;
+    const platformHint = diagnosePlatform(platformProbe);
     const alreadyInstalled = detectVibium(spawner);
     if (alreadyInstalled) {
         return {
             status: 'already-installed',
             version: alreadyInstalled,
             packageSpec,
+            platformHint,
         };
     }
     const npmBin = options.npmBin || 'npm';
@@ -71,7 +141,7 @@ export function installBrowserEngine(options = {}) {
         return {
             status: 'npm-unavailable',
             packageSpec,
-            message: 'npm is not available on PATH. Install Node.js + npm, then run `npm install -g vibium`.',
+            message: `npm is not available on PATH. Install Node.js + npm, then run \`npm install -g ${packageSpec}\`.`,
         };
     }
     const timeoutMs = options.timeoutMs || 180_000;
@@ -87,6 +157,6 @@ export function installBrowserEngine(options = {}) {
         };
     }
     const version = detectVibium(spawner) || 'unknown';
-    return { status: 'installed', version, packageSpec };
+    return { status: 'installed', version, packageSpec, platformHint };
 }
 //# sourceMappingURL=browser-engine-installer.js.map

package/dist/init/phases/09-assets.js

@@ -8,7 +8,7 @@ import { BasePhase, } from './phase-interface.js';
 import { createSkillsInstaller } from '../skills-installer.js';
 import { createAgentsInstaller } from '../agents-installer.js';
 import { createN8nInstaller } from '../n8n-installer.js';
-import { installBrowserEngine } from '../browser-engine-installer.js';
+import { installBrowserEngine, DEFAULT_VIBIUM_SPEC, } from '../browser-engine-installer.js';
 import { initializeOverlays } from '../../routing/qe-agent-registry.js';
 /**
  * Assets phase - installs skills and agents
@@ -123,6 +123,13 @@ export class AssetsPhase extends BasePhase {
                         // 'already-installed' handled by the pre-flight branch above
                     }
                 }
+                // ADR-091 GAP-05: surface platform diagnostics when the host is one
+                // where Vibium's first-run Chrome auto-download is known to fail.
+                // Today that's just Linux aarch64 at v26.3.x; printed for both
+                // `installed` and `already-installed` results. Non-fatal.
+                if (browserEngine?.platformHint) {
+                    context.services.warn(`  Browser engine platform hint: ${browserEngine.platformHint.message}`);
+                }
             }
             catch (error) {
                 // M9 (devil's-advocate finding): the previous catch re-emitted the
@@ -136,7 +143,7 @@ export class AssetsPhase extends BasePhase {
             }
         }
         else {
-            browserEngine = { status: 'skipped', packageSpec: 'vibium', message: 'minimal mode' };
+            browserEngine = { status: 'skipped', packageSpec: DEFAULT_VIBIUM_SPEC, message: 'minimal mode' };
         }
         // Install n8n platform (optional)
         if (options.withN8n) {