agentic-qe 3.9.14 → 3.9.16

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) {

package/dist/integrations/ruvector/brain-diff.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Brain Export Diff
+ *
+ * Compares two brain exports (JSONL directory or RVF file) and returns a
+ * structured diff.
+ *
+ * Two levels of comparison:
+ *   - Manifest-level (always available): version, checksum, per-table record
+ *     counts, exported_at, domain list delta.
+ *   - Record-level (JSONL exports only): for each table with a PK, the set of
+ *     added / removed / changed record IDs. For append-only tables only counts
+ *     are reported.
+ *
+ * For RVF exports, record-level diff is not supported by this module (the
+ * kernel is opaque without @ruvector/rvf-node). Export as JSONL for full diff.
+ */
+import { type TableExportConfig } from './brain-shared.js';
+export type ExportFormat = 'rvf' | 'jsonl';
+export interface ManifestSummary {
+    readonly format: ExportFormat;
+    readonly version: string;
+    readonly exportedAt: string;
+    readonly sourceDb: string;
+    readonly checksum: string;
+    readonly totalRecords: number;
+    readonly domains: readonly string[];
+    readonly tableRecordCounts: Record<string, number>;
+}
+export interface TableDiff {
+    readonly tableName: string;
+    readonly countA: number;
+    readonly countB: number;
+    readonly delta: number;
+    /** Only populated for JSONL↔JSONL record-level diffs on PK tables. */
+    readonly added?: readonly string[];
+    readonly removed?: readonly string[];
+    readonly changed?: readonly string[];
+}
+export interface BrainDiffResult {
+    readonly pathA: string;
+    readonly pathB: string;
+    readonly formatA: ExportFormat;
+    readonly formatB: ExportFormat;
+    readonly manifestA: ManifestSummary;
+    readonly manifestB: ManifestSummary;
+    readonly checksumMatch: boolean;
+    readonly versionMatch: boolean;
+    readonly identical: boolean;
+    readonly recordLevel: boolean;
+    readonly tableDiffs: readonly TableDiff[];
+    readonly domainsOnlyInA: readonly string[];
+    readonly domainsOnlyInB: readonly string[];
+}
+export interface BrainDiffOptions {
+    /** Restrict comparison to a single table (by table name). */
+    readonly tableFilter?: string;
+    /** Cap on the number of IDs retained per added/removed/changed list. */
+    readonly maxIdsPerBucket?: number;
+}
+/**
+ * Compute the diff between two brain exports.
+ *
+ * Both paths may be JSONL directories or `.rvf` files. Record-level diff is
+ * only available when both sides are JSONL.
+ */
+export declare function diffBrains(pathA: string, pathB: string, options?: BrainDiffOptions): BrainDiffResult;
+declare function pkFor(config: TableExportConfig): string;
+/**
+ * Read a JSONL file and build a Map<identity, contentHash>.
+ *
+ * For PK tables the identity is the PK column value. For append-only tables
+ * the identity is a concatenation of the dedup columns (collisions are
+ * treated as "same record").
+ */
+declare function buildIdentityMap(filePath: string, config: TableExportConfig): Map<string, string>;
+declare function identityOf(row: Record<string, unknown>, config: TableExportConfig): string | undefined;
+declare function stableStringify(obj: Record<string, unknown>): string;
+export interface DiffSummary {
+    readonly tablesChanged: number;
+    readonly totalAdded: number;
+    readonly totalRemoved: number;
+    readonly totalChanged: number;
+    readonly recordCountDelta: number;
+}
+export declare function summarizeDiff(result: BrainDiffResult): DiffSummary;
+export declare const __test__: {
+    stableStringify: typeof stableStringify;
+    identityOf: typeof identityOf;
+    buildIdentityMap: typeof buildIdentityMap;
+    pkFor: typeof pkFor;
+};
+export {};
+//# sourceMappingURL=brain-diff.d.ts.map

package/dist/integrations/ruvector/brain-diff.js

@@ -0,0 +1,281 @@
+/**
+ * Brain Export Diff
+ *
+ * Compares two brain exports (JSONL directory or RVF file) and returns a
+ * structured diff.
+ *
+ * Two levels of comparison:
+ *   - Manifest-level (always available): version, checksum, per-table record
+ *     counts, exported_at, domain list delta.
+ *   - Record-level (JSONL exports only): for each table with a PK, the set of
+ *     added / removed / changed record IDs. For append-only tables only counts
+ *     are reported.
+ *
+ * For RVF exports, record-level diff is not supported by this module (the
+ * kernel is opaque without @ruvector/rvf-node). Export as JSONL for full diff.
+ */
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { safeJsonParse } from '../../shared/safe-json.js';
+import { brainInfoFromRvf } from './brain-rvf-exporter.js';
+import { readJsonl, sha256, TABLE_CONFIGS, PK_COLUMNS, } from './brain-shared.js';
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Compute the diff between two brain exports.
+ *
+ * Both paths may be JSONL directories or `.rvf` files. Record-level diff is
+ * only available when both sides are JSONL.
+ */
+export function diffBrains(pathA, pathB, options = {}) {
+    const resolvedA = resolve(pathA);
+    const resolvedB = resolve(pathB);
+    const formatA = detectFormat(resolvedA);
+    const formatB = detectFormat(resolvedB);
+    const manifestA = readManifestSummary(resolvedA, formatA);
+    const manifestB = readManifestSummary(resolvedB, formatB);
+    const recordLevel = formatA === 'jsonl' && formatB === 'jsonl';
+    const tableDiffs = computeTableDiffs({
+        pathA: resolvedA,
+        pathB: resolvedB,
+        manifestA,
+        manifestB,
+        recordLevel,
+        tableFilter: options.tableFilter,
+        maxIdsPerBucket: options.maxIdsPerBucket ?? 500,
+    });
+    const domainsA = new Set(manifestA.domains);
+    const domainsB = new Set(manifestB.domains);
+    const domainsOnlyInA = manifestA.domains.filter((d) => !domainsB.has(d));
+    const domainsOnlyInB = manifestB.domains.filter((d) => !domainsA.has(d));
+    const checksumMatch = manifestA.checksum === manifestB.checksum;
+    const versionMatch = manifestA.version === manifestB.version;
+    const identical = checksumMatch &&
+        versionMatch &&
+        tableDiffs.every((t) => t.delta === 0 &&
+            (t.added?.length ?? 0) === 0 &&
+            (t.removed?.length ?? 0) === 0 &&
+            (t.changed?.length ?? 0) === 0);
+    return {
+        pathA: resolvedA,
+        pathB: resolvedB,
+        formatA,
+        formatB,
+        manifestA,
+        manifestB,
+        checksumMatch,
+        versionMatch,
+        identical,
+        recordLevel,
+        tableDiffs,
+        domainsOnlyInA,
+        domainsOnlyInB,
+    };
+}
+// ============================================================================
+// Format detection + manifest reading
+// ============================================================================
+function detectFormat(path) {
+    if (!existsSync(path)) {
+        throw new Error(`Path not found: ${path}`);
+    }
+    if (path.endsWith('.rvf'))
+        return 'rvf';
+    const s = statSync(path);
+    if (s.isFile()) {
+        // Any single file that isn't .rvf is treated as an error — JSONL exports
+        // are directories.
+        throw new Error(`Unsupported brain export: ${path} (expected a .rvf file or a JSONL directory)`);
+    }
+    // Directory: assume JSONL
+    return 'jsonl';
+}
+function readManifestSummary(path, format) {
+    if (format === 'rvf') {
+        return readRvfManifestSummary(path);
+    }
+    return readJsonlManifestSummary(path);
+}
+function readJsonlManifestSummary(dir) {
+    const manifestPath = join(dir, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+        throw new Error(`Manifest not found at ${manifestPath}`);
+    }
+    const raw = safeJsonParse(readFileSync(manifestPath, 'utf-8'));
+    return toManifestSummary(raw, 'jsonl');
+}
+function readRvfManifestSummary(rvfPath) {
+    // Delegate to the RVF exporter's info path so we honour its format handling.
+    const raw = brainInfoFromRvf(rvfPath);
+    return toManifestSummary(raw, 'rvf');
+}
+function toManifestSummary(raw, format) {
+    return {
+        format,
+        version: raw.version ?? 'unknown',
+        exportedAt: raw.exportedAt ?? 'unknown',
+        sourceDb: raw.sourceDb ?? 'unknown',
+        checksum: raw.checksum ?? '',
+        totalRecords: raw.stats?.totalRecords ?? 0,
+        domains: raw.domains ?? [],
+        tableRecordCounts: raw.tableRecordCounts ?? {},
+    };
+}
+function computeTableDiffs(input) {
+    const configs = input.tableFilter
+        ? TABLE_CONFIGS.filter((c) => c.tableName === input.tableFilter)
+        : TABLE_CONFIGS;
+    if (input.tableFilter && configs.length === 0) {
+        throw new Error(`Unknown table: ${input.tableFilter}`);
+    }
+    const diffs = [];
+    for (const config of configs) {
+        const countA = input.manifestA.tableRecordCounts[config.tableName] ?? 0;
+        const countB = input.manifestB.tableRecordCounts[config.tableName] ?? 0;
+        const delta = countB - countA;
+        let added;
+        let removed;
+        let changed;
+        if (input.recordLevel && hasIdentity(config)) {
+            const recordDiff = recordLevelDiff(join(input.pathA, config.fileName), join(input.pathB, config.fileName), config, input.maxIdsPerBucket);
+            added = recordDiff.added;
+            removed = recordDiff.removed;
+            changed = recordDiff.changed;
+        }
+        diffs.push({
+            tableName: config.tableName,
+            countA,
+            countB,
+            delta,
+            ...(added !== undefined ? { added } : {}),
+            ...(removed !== undefined ? { removed } : {}),
+            ...(changed !== undefined ? { changed } : {}),
+        });
+    }
+    return diffs;
+}
+function hasIdentity(_config) {
+    // PK tables always have identity; append-only tables can be deduped via
+    // their dedup columns, which is good enough to compute added/removed.
+    return true;
+}
+function pkFor(config) {
+    if (config.dedupColumns && config.dedupColumns.length > 0) {
+        // Composite identity — joined with a separator unlikely to occur in values.
+        return config.dedupColumns.join('
');
+    }
+    return PK_COLUMNS[config.tableName] ?? 'id';
+}
+function recordLevelDiff(fileA, fileB, config, maxIdsPerBucket) {
+    const mapA = buildIdentityMap(fileA, config);
+    const mapB = buildIdentityMap(fileB, config);
+    const added = [];
+    const removed = [];
+    const changed = [];
+    // In A but not in B → removed.
+    for (const [id, hashA] of mapA) {
+        const hashB = mapB.get(id);
+        if (hashB === undefined) {
+            if (removed.length < maxIdsPerBucket)
+                removed.push(id);
+        }
+        else if (hashB !== hashA) {
+            // Append-only tables use dedup columns as identity, so if the identity
+            // matches the record IS the same — guard via dedup flag.
+            if (config.dedupColumns && config.dedupColumns.length > 0)
+                continue;
+            if (changed.length < maxIdsPerBucket)
+                changed.push(id);
+        }
+    }
+    // In B but not in A → added.
+    for (const id of mapB.keys()) {
+        if (!mapA.has(id)) {
+            if (added.length < maxIdsPerBucket)
+                added.push(id);
+        }
+    }
+    added.sort();
+    removed.sort();
+    changed.sort();
+    return { added, removed, changed };
+}
+/**
+ * Read a JSONL file and build a Map<identity, contentHash>.
+ *
+ * For PK tables the identity is the PK column value. For append-only tables
+ * the identity is a concatenation of the dedup columns (collisions are
+ * treated as "same record").
+ */
+function buildIdentityMap(filePath, config) {
+    const map = new Map();
+    if (!existsSync(filePath))
+        return map;
+    const rows = readJsonl(filePath, safeJsonParse);
+    for (const row of rows) {
+        const id = identityOf(row, config);
+        if (id === undefined)
+            continue;
+        // Stable content hash: JSON-stringify with sorted keys.
+        const content = stableStringify(row);
+        map.set(id, sha256Hex(content));
+    }
+    return map;
+}
+function identityOf(row, config) {
+    if (config.dedupColumns && config.dedupColumns.length > 0) {
+        const parts = [];
+        for (const col of config.dedupColumns) {
+            const v = row[col];
+            if (v === undefined || v === null)
+                return undefined;
+            parts.push(String(v));
+        }
+        return parts.join('
');
+    }
+    const pk = PK_COLUMNS[config.tableName] ?? 'id';
+    const v = row[pk];
+    if (v === undefined || v === null)
+        return undefined;
+    return String(v);
+}
+function stableStringify(obj) {
+    const keys = Object.keys(obj).sort();
+    const ordered = {};
+    for (const k of keys)
+        ordered[k] = obj[k];
+    return JSON.stringify(ordered);
+}
+function sha256Hex(s) {
+    // sha256() from brain-shared operates on utf-8 strings; both paths yield the
+    // same hash for the same input. Kept as a thin wrapper for readability.
+    return sha256(s);
+}
+export function summarizeDiff(result) {
+    let tablesChanged = 0;
+    let totalAdded = 0;
+    let totalRemoved = 0;
+    let totalChanged = 0;
+    for (const t of result.tableDiffs) {
+        const hasChange = t.delta !== 0 ||
+            (t.added && t.added.length > 0) ||
+            (t.removed && t.removed.length > 0) ||
+            (t.changed && t.changed.length > 0);
+        if (hasChange)
+            tablesChanged++;
+        totalAdded += t.added?.length ?? 0;
+        totalRemoved += t.removed?.length ?? 0;
+        totalChanged += t.changed?.length ?? 0;
+    }
+    return {
+        tablesChanged,
+        totalAdded,
+        totalRemoved,
+        totalChanged,
+        recordCountDelta: result.manifestB.totalRecords - result.manifestA.totalRecords,
+    };
+}
+// Export internal helpers for test access without widening the public API.
+export const __test__ = { stableStringify, identityOf, buildIdentityMap, pkFor };
+//# sourceMappingURL=brain-diff.js.map

package/dist/integrations/ruvector/brain-search.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Brain Export Search
+ *
+ * Offline, read-only filtered search over a JSONL brain export directory.
+ * Useful for exploring what a snapshot contains without importing it.
+ *
+ * Defaults to searching qe_patterns but can target any of the 25 exported
+ * tables via the `table` option. Supports filters by domain, pattern_type,
+ * date range, and a substring query that matches `name` + `description`.
+ *
+ * RVF exports are not supported directly by this module — callers should use
+ * `aqe brain export --format jsonl` for searchable snapshots.
+ */
+export interface BrainSearchOptions {
+    /** Table to search. Defaults to 'qe_patterns'. */
+    readonly table?: string;
+    /** Restrict to these domains (matched against the table's domain column). */
+    readonly domains?: readonly string[];
+    /** Restrict to rows with this exact pattern_type (qe_patterns only). */
+    readonly patternType?: string;
+    /** ISO timestamp — only rows at or after this are included. */
+    readonly since?: string;
+    /** ISO timestamp — only rows at or before this are included. */
+    readonly until?: string;
+    /** Case-insensitive substring matched against name + description. */
+    readonly query?: string;
+    /** Max rows to return. Defaults to 20. */
+    readonly limit?: number;
+}
+export interface BrainSearchHit {
+    /** Primary-key identity string (best effort per table). */
+    readonly id: string;
+    /** Minimal surface shown in default CLI output. */
+    readonly display: {
+        readonly name?: string;
+        readonly description?: string;
+        readonly domain?: string;
+        readonly patternType?: string;
+        readonly confidence?: number;
+        readonly updatedAt?: string;
+    };
+    /** Full raw row for callers that want more (used by --json). */
+    readonly row: Record<string, unknown>;
+}
+export interface BrainSearchResult {
+    readonly table: string;
+    readonly inputPath: string;
+    readonly totalScanned: number;
+    readonly totalMatched: number;
+    readonly limit: number;
+    readonly hits: readonly BrainSearchHit[];
+    readonly truncated: boolean;
+}
+/**
+ * Search a brain export directory for rows matching the given filters.
+ *
+ * Throws if the path isn't a JSONL export directory, if the requested table
+ * isn't known, or if the JSONL file for that table is missing.
+ */
+export declare function searchBrain(inputPath: string, options?: BrainSearchOptions): BrainSearchResult;
+interface FilterContext {
+    readonly domainColumn?: string;
+    readonly domains?: Set<string>;
+    readonly patternType?: string;
+    readonly since?: string;
+    readonly until?: string;
+    readonly queryLower?: string;
+}
+declare function rowMatches(row: Record<string, unknown>, ctx: FilterContext): boolean;
+declare function pickTimestamp(row: Record<string, unknown>): string | undefined;
+declare function toHit(row: Record<string, unknown>, tableName: string, domainColumn: string | undefined): BrainSearchHit;
+export declare const __test__: {
+    pickTimestamp: typeof pickTimestamp;
+    rowMatches: typeof rowMatches;
+    toHit: typeof toHit;
+};
+export {};
+//# sourceMappingURL=brain-search.d.ts.map