@grafema/util 0.3.0-beta

package/dist/utils/lazyDownload.js

@@ -0,0 +1,175 @@
+/**
+ * Lazy binary downloader for Grafema.
+ *
+ * Downloads Haskell analyzer binaries from GitHub Releases on first use.
+ * Binaries are cached in ~/.grafema/bin/ and reused across projects.
+ *
+ * Asset naming convention: {binary-name}-{platform}
+ * Example: grafema-analyzer-darwin-arm64
+ */
+import { existsSync, mkdirSync, chmodSync, renameSync, unlinkSync, createWriteStream } from 'fs';
+import { join } from 'path';
+import { get as httpsGet } from 'https';
+import { getPlatformDir } from './findRfdbBinary.js';
+const GITHUB_REPO = 'Disentinel/grafema';
+/** All analyzer binaries that can be lazy-downloaded. */
+const DOWNLOADABLE_BINARIES = [
+    'grafema-analyzer',
+    'grafema-resolve',
+    'haskell-analyzer',
+    'haskell-resolve',
+    'grafema-rust-analyzer',
+    'grafema-rust-resolve',
+    'grafema-java-analyzer',
+    'java-resolve',
+    'java-parser',
+    'grafema-kotlin-analyzer',
+    'kotlin-resolve',
+    'kotlin-parser',
+    'jvm-cross-resolve',
+    'grafema-python-analyzer',
+    'python-resolve',
+    'grafema-go-analyzer',
+    'go-resolve',
+    'go-parser',
+    'grafema-cpp-analyzer',
+    'cpp-resolve',
+];
+/**
+ * Get the directory where lazy-downloaded binaries are stored.
+ */
+export function getGrafemaBinDir() {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    return join(home, '.grafema', 'bin');
+}
+/**
+ * Check if a binary name is eligible for lazy download.
+ */
+export function isDownloadable(binaryName) {
+    return DOWNLOADABLE_BINARIES.includes(binaryName);
+}
+/**
+ * Find a binary in ~/.grafema/bin/.
+ */
+export function findInGrafemaBin(binaryName) {
+    const binDir = getGrafemaBinDir();
+    const p = join(binDir, binaryName);
+    return existsSync(p) ? p : null;
+}
+/**
+ * Simple HTTPS GET that follows redirects (GitHub uses 302 → S3).
+ */
+function httpsGetFollowRedirects(url) {
+    return new Promise((resolve, reject) => {
+        const req = httpsGet(url, { headers: { 'User-Agent': 'grafema-cli' } }, (res) => {
+            if (res.statusCode === 301 || res.statusCode === 302) {
+                const location = res.headers.location;
+                if (!location)
+                    return reject(new Error('Redirect without location'));
+                httpsGetFollowRedirects(location).then(resolve, reject);
+                return;
+            }
+            resolve(res);
+        });
+        req.on('error', reject);
+    });
+}
+/**
+ * Find the latest binaries-v* release tag from GitHub API.
+ */
+async function findLatestReleaseTag() {
+    const url = `https://api.github.com/repos/${GITHUB_REPO}/releases?per_page=30`;
+    const res = await httpsGetFollowRedirects(url);
+    const chunks = [];
+    for await (const chunk of res) {
+        chunks.push(chunk);
+    }
+    const body = Buffer.concat(chunks).toString('utf-8');
+    if (res.statusCode !== 200) {
+        throw new Error(`GitHub API returned ${res.statusCode}: ${body.slice(0, 200)}`);
+    }
+    const releases = JSON.parse(body);
+    const binRelease = releases.find(r => r.tag_name.startsWith('binaries-v'));
+    if (!binRelease) {
+        throw new Error('No binaries-v* release found on GitHub');
+    }
+    return binRelease.tag_name;
+}
+/**
+ * Download a single binary from a GitHub Release.
+ *
+ * @param binaryName - e.g. "grafema-analyzer"
+ * @param tag - e.g. "binaries-v0.3.0-beta"
+ * @param onProgress - optional callback for download progress
+ * @returns Path to the downloaded binary
+ */
+export async function downloadBinary(binaryName, tag, onProgress) {
+    const platform = getPlatformDir();
+    const assetName = `${binaryName}-${platform}`;
+    const binDir = getGrafemaBinDir();
+    // Ensure ~/.grafema/bin/ exists
+    if (!existsSync(binDir)) {
+        mkdirSync(binDir, { recursive: true });
+    }
+    const targetPath = join(binDir, binaryName);
+    const tmpPath = `${targetPath}.downloading`;
+    // Resolve tag
+    const releaseTag = tag || await findLatestReleaseTag();
+    const downloadUrl = `https://github.com/${GITHUB_REPO}/releases/download/${releaseTag}/${assetName}`;
+    const log = onProgress || (() => { });
+    log(`Downloading ${binaryName} for ${platform}...`);
+    // Download to temp file
+    const res = await httpsGetFollowRedirects(downloadUrl);
+    if (res.statusCode !== 200) {
+        throw new Error(`Failed to download ${assetName}: HTTP ${res.statusCode}. ` +
+            `Check that release ${releaseTag} has asset ${assetName}.`);
+    }
+    const contentLength = parseInt(res.headers['content-length'] || '0', 10);
+    const sizeMB = contentLength > 0 ? `${(contentLength / 1024 / 1024).toFixed(1)}MB` : 'unknown size';
+    log(`  ${assetName} (${sizeMB})`);
+    await new Promise((resolve, reject) => {
+        const file = createWriteStream(tmpPath);
+        res.pipe(file);
+        file.on('finish', () => { file.close(); resolve(); });
+        file.on('error', (err) => { unlinkSync(tmpPath); reject(err); });
+        res.on('error', (err) => { unlinkSync(tmpPath); reject(err); });
+    });
+    // Atomic rename + make executable
+    renameSync(tmpPath, targetPath);
+    chmodSync(targetPath, 0o755);
+    log(`  Installed to ${targetPath}`);
+    return targetPath;
+}
+/**
+ * Ensure a binary exists, downloading it if missing and eligible.
+ *
+ * This is the main entry point for lazy downloading. Call it before
+ * spawning an analyzer binary. Returns the path if found or downloaded,
+ * null if the binary can't be obtained.
+ *
+ * @param binaryName - e.g. "grafema-analyzer"
+ * @param existingPath - path from findBinary() (null = not found locally)
+ * @param onProgress - optional callback for download progress
+ */
+export async function ensureBinary(binaryName, existingPath, onProgress) {
+    // Already found locally
+    if (existingPath)
+        return existingPath;
+    // Check ~/.grafema/bin/ first (may have been downloaded previously)
+    const cached = findInGrafemaBin(binaryName);
+    if (cached)
+        return cached;
+    // Not downloadable (e.g. rfdb-server, grafema-orchestrator — these must be in npm package)
+    if (!isDownloadable(binaryName))
+        return null;
+    // Download
+    try {
+        return await downloadBinary(binaryName, undefined, onProgress);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        (onProgress || console.error)(`Failed to download ${binaryName}: ${msg}`);
+        return null;
+    }
+}
+//# sourceMappingURL=lazyDownload.js.map

package/dist/utils/lazyDownload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazyDownload.js","sourceRoot":"","sources":["../../src/utils/lazyDownload.ts"],"names":[],"mappings":"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"}

package/dist/utils/moduleResolution.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Module Resolution Utilities (REG-320)
+ *
+ * Unified module path resolution logic extracted from:
+ * - MountPointResolver.resolveImportSource()
+ * - JSModuleIndexer.resolveModulePath()
+ * - FunctionCallResolver._resolveImportPath()
+ * - IncrementalModuleIndexer.tryResolve()
+ *
+ * Provides consistent module resolution across all plugins.
+ */
+/**
+ * Default file extensions to try when resolving modules.
+ * Order: exact match first, then JS variants, then TS variants.
+ */
+export declare const DEFAULT_EXTENSIONS: string[];
+/**
+ * Default index files to try when resolving directory imports.
+ * Order: JS variants first (most common), then TS variants.
+ */
+export declare const DEFAULT_INDEX_FILES: string[];
+/**
+ * Options for module path resolution.
+ *
+ * @example Filesystem mode (default)
+ * ```ts
+ * resolveModulePath('/app/utils')
+ * // → '/app/utils.js' if exists
+ * ```
+ *
+ * @example In-memory mode (for enrichment plugins)
+ * ```ts
+ * resolveModulePath('/app/utils', {
+ *   useFilesystem: false,
+ *   fileIndex: new Set(['/app/utils.ts'])
+ * })
+ * // → '/app/utils.ts'
+ * ```
+ */
+export interface ModuleResolutionOptions {
+    /**
+     * Use filesystem for path verification.
+     * Default: true
+     *
+     * When true: uses existsSync() to check if files exist
+     * When false: uses fileIndex.has() for lookup
+     *
+     * Performance note: For high-frequency calls during enrichment,
+     * use in-memory mode (useFilesystem: false) with a pre-built fileIndex.
+     * For indexing phase, filesystem mode is acceptable.
+     */
+    useFilesystem?: boolean;
+    /**
+     * Pre-built set of known file paths.
+     * Required when useFilesystem=false.
+     *
+     * Throws Error if useFilesystem=false and fileIndex is not provided.
+     */
+    fileIndex?: Set<string> | null;
+    /**
+     * Extensions to try (in order).
+     * Default: ['', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx']
+     *
+     * Empty string '' means try exact path first.
+     */
+    extensions?: string[];
+    /**
+     * Index files to try (in order).
+     * Default: ['index.js', 'index.ts', 'index.mjs', 'index.cjs', 'index.jsx', 'index.tsx']
+     */
+    indexFiles?: string[];
+}
+/**
+ * Resolve a base path to an actual file by trying extensions and index files.
+ *
+ * @param basePath - Absolute path (without extension) to resolve
+ * @param options - Resolution options (filesystem vs in-memory, extensions, index files)
+ * @returns Resolved file path or null if not found
+ *
+ * @example Filesystem mode (default)
+ * ```ts
+ * resolveModulePath('/app/utils')
+ * // → '/app/utils.js' (if exists)
+ * ```
+ *
+ * @example In-memory mode (for enrichment plugins)
+ * ```ts
+ * resolveModulePath('/app/utils', {
+ *   useFilesystem: false,
+ *   fileIndex: new Set(['/app/utils.ts'])
+ * })
+ * // → '/app/utils.ts'
+ * ```
+ *
+ * Note: Symbolic links are followed by existsSync(). Assumes all paths
+ * are within the project workspace as determined by discovery phase.
+ */
+export declare function resolveModulePath(basePath: string, options?: ModuleResolutionOptions): string | null;
+/**
+ * Check if import specifier is a relative import.
+ *
+ * @param specifier - The import specifier (e.g., './utils', 'lodash')
+ * @returns true if relative import (./ or ../), false otherwise
+ *
+ * @example
+ * ```ts
+ * isRelativeImport('./utils')      // true
+ * isRelativeImport('../shared')    // true
+ * isRelativeImport('lodash')       // false
+ * isRelativeImport('@scope/pkg')   // false
+ * isRelativeImport('node:fs')      // false
+ * ```
+ */
+export declare function isRelativeImport(specifier: string): boolean;
+/**
+ * Resolve relative import specifier to actual file path.
+ *
+ * Combines relative path resolution with module path resolution.
+ * Returns null for non-relative specifiers (bare modules, scoped packages).
+ *
+ * @param specifier - The import specifier (e.g., './utils', '../shared')
+ * @param containingFile - The file containing the import
+ * @param options - Resolution options
+ * @returns Resolved file path or null if not found or not relative
+ *
+ * @example
+ * ```ts
+ * // From /project/src/main.js, import './utils'
+ * resolveRelativeSpecifier('./utils', '/project/src/main.js')
+ * // → '/project/src/utils.js' (if exists)
+ * ```
+ */
+export declare function resolveRelativeSpecifier(specifier: string, containingFile: string, options?: ModuleResolutionOptions): string | null;
+//# sourceMappingURL=moduleResolution.d.ts.map

package/dist/utils/moduleResolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleResolution.d.ts","sourceRoot":"","sources":["../../src/utils/moduleResolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,UAAqD,CAAC;AAerF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,UAO/B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAE/B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,GAAG,IAAI,CAuDf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,GAAG,IAAI,CAYf"}

package/dist/utils/moduleResolution.js

@@ -0,0 +1,189 @@
+/**
+ * Module Resolution Utilities (REG-320)
+ *
+ * Unified module path resolution logic extracted from:
+ * - MountPointResolver.resolveImportSource()
+ * - JSModuleIndexer.resolveModulePath()
+ * - FunctionCallResolver._resolveImportPath()
+ * - IncrementalModuleIndexer.tryResolve()
+ *
+ * Provides consistent module resolution across all plugins.
+ */
+import { existsSync, statSync } from 'fs';
+import { dirname, extname, resolve, join } from 'path';
+/**
+ * Default file extensions to try when resolving modules.
+ * Order: exact match first, then JS variants, then TS variants.
+ */
+export const DEFAULT_EXTENSIONS = ['', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx'];
+/**
+ * TypeScript extension redirects (REG-426).
+ * Maps JS-family extensions to their TS equivalents.
+ * Used when an import specifies a .js extension but only a .ts file exists.
+ * This matches TypeScript's own module resolution behavior for ESM.
+ */
+const TS_EXTENSION_REDIRECTS = {
+    '.js': ['.ts', '.tsx'],
+    '.jsx': ['.tsx'],
+    '.mjs': ['.mts'],
+    '.cjs': ['.cts'],
+};
+/**
+ * Default index files to try when resolving directory imports.
+ * Order: JS variants first (most common), then TS variants.
+ */
+export const DEFAULT_INDEX_FILES = [
+    'index.js',
+    'index.ts',
+    'index.mjs',
+    'index.cjs',
+    'index.jsx',
+    'index.tsx'
+];
+/**
+ * Check if path exists using the configured method.
+ */
+function pathExists(testPath, useFilesystem, fileIndex) {
+    if (useFilesystem) {
+        return existsSync(testPath);
+    }
+    return fileIndex?.has(testPath) ?? false;
+}
+/**
+ * Check if path is a directory (filesystem mode only).
+ */
+function isDirectory(path, useFilesystem) {
+    if (!useFilesystem) {
+        // In in-memory mode, we can't check if it's a directory
+        // The fileIndex should only contain file paths, not directories
+        return false;
+    }
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a base path to an actual file by trying extensions and index files.
+ *
+ * @param basePath - Absolute path (without extension) to resolve
+ * @param options - Resolution options (filesystem vs in-memory, extensions, index files)
+ * @returns Resolved file path or null if not found
+ *
+ * @example Filesystem mode (default)
+ * ```ts
+ * resolveModulePath('/app/utils')
+ * // → '/app/utils.js' (if exists)
+ * ```
+ *
+ * @example In-memory mode (for enrichment plugins)
+ * ```ts
+ * resolveModulePath('/app/utils', {
+ *   useFilesystem: false,
+ *   fileIndex: new Set(['/app/utils.ts'])
+ * })
+ * // → '/app/utils.ts'
+ * ```
+ *
+ * Note: Symbolic links are followed by existsSync(). Assumes all paths
+ * are within the project workspace as determined by discovery phase.
+ */
+export function resolveModulePath(basePath, options) {
+    const useFilesystem = options?.useFilesystem ?? true;
+    const fileIndex = options?.fileIndex;
+    const extensions = options?.extensions ?? DEFAULT_EXTENSIONS;
+    const indexFiles = options?.indexFiles ?? DEFAULT_INDEX_FILES;
+    // Validation: fail fast if misconfigured
+    if (!useFilesystem && !fileIndex) {
+        throw new Error('fileIndex is required when useFilesystem=false');
+    }
+    // Handle empty path gracefully
+    if (!basePath) {
+        return null;
+    }
+    // Normalize path (remove trailing slash)
+    const normalizedPath = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+    // Try extensions (including '' for exact match)
+    for (const ext of extensions) {
+        const testPath = normalizedPath + ext;
+        if (pathExists(testPath, useFilesystem, fileIndex)) {
+            // In filesystem mode, don't return directories
+            if (useFilesystem && ext === '' && isDirectory(testPath, useFilesystem)) {
+                // It's a directory, skip to index files
+                continue;
+            }
+            return testPath;
+        }
+    }
+    // TypeScript extension redirect (REG-426):
+    // import './foo.js' → try ./foo.ts when ./foo.js doesn't exist
+    const ext = extname(normalizedPath);
+    const tsAlternatives = TS_EXTENSION_REDIRECTS[ext];
+    if (tsAlternatives) {
+        const withoutExt = normalizedPath.slice(0, -ext.length);
+        for (const tsExt of tsAlternatives) {
+            const testPath = withoutExt + tsExt;
+            if (pathExists(testPath, useFilesystem, fileIndex)) {
+                return testPath;
+            }
+        }
+    }
+    // Try index files in directory
+    for (const indexFile of indexFiles) {
+        const testPath = join(normalizedPath, indexFile);
+        if (pathExists(testPath, useFilesystem, fileIndex)) {
+            return testPath;
+        }
+    }
+    return null;
+}
+/**
+ * Check if import specifier is a relative import.
+ *
+ * @param specifier - The import specifier (e.g., './utils', 'lodash')
+ * @returns true if relative import (./ or ../), false otherwise
+ *
+ * @example
+ * ```ts
+ * isRelativeImport('./utils')      // true
+ * isRelativeImport('../shared')    // true
+ * isRelativeImport('lodash')       // false
+ * isRelativeImport('@scope/pkg')   // false
+ * isRelativeImport('node:fs')      // false
+ * ```
+ */
+export function isRelativeImport(specifier) {
+    return specifier.startsWith('./') || specifier.startsWith('../');
+}
+/**
+ * Resolve relative import specifier to actual file path.
+ *
+ * Combines relative path resolution with module path resolution.
+ * Returns null for non-relative specifiers (bare modules, scoped packages).
+ *
+ * @param specifier - The import specifier (e.g., './utils', '../shared')
+ * @param containingFile - The file containing the import
+ * @param options - Resolution options
+ * @returns Resolved file path or null if not found or not relative
+ *
+ * @example
+ * ```ts
+ * // From /project/src/main.js, import './utils'
+ * resolveRelativeSpecifier('./utils', '/project/src/main.js')
+ * // → '/project/src/utils.js' (if exists)
+ * ```
+ */
+export function resolveRelativeSpecifier(specifier, containingFile, options) {
+    // Only handle relative imports
+    if (!isRelativeImport(specifier)) {
+        return null;
+    }
+    // Resolve relative path to absolute base path
+    const dir = dirname(containingFile);
+    const basePath = resolve(dir, specifier);
+    // Use main resolution function
+    return resolveModulePath(basePath, options);
+}
+//# sourceMappingURL=moduleResolution.js.map

package/dist/utils/moduleResolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleResolution.js","sourceRoot":"","sources":["../../src/utils/moduleResolution.ts"],"names":[],"mappings":"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"}

package/dist/utils/resolveNodeFile.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolve a node's file path to an absolute path.
+ *
+ * After REG-408, node.file stores paths relative to projectPath.
+ * This utility resolves them back to absolute for file system access.
+ * Also handles legacy absolute paths for backward compatibility.
+ *
+ * @param nodeFile - The file field from a graph node (relative or absolute)
+ * @param projectPath - The absolute project root path
+ * @returns Absolute file path
+ */
+export declare function resolveNodeFile(nodeFile: string, projectPath: string): string;
+//# sourceMappingURL=resolveNodeFile.d.ts.map

package/dist/utils/resolveNodeFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveNodeFile.d.ts","sourceRoot":"","sources":["../../src/utils/resolveNodeFile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAG7E"}

package/dist/utils/resolveNodeFile.js

@@ -0,0 +1,18 @@
+/**
+ * Resolve a node's file path to an absolute path.
+ *
+ * After REG-408, node.file stores paths relative to projectPath.
+ * This utility resolves them back to absolute for file system access.
+ * Also handles legacy absolute paths for backward compatibility.
+ *
+ * @param nodeFile - The file field from a graph node (relative or absolute)
+ * @param projectPath - The absolute project root path
+ * @returns Absolute file path
+ */
+import { isAbsolute, join } from 'path';
+export function resolveNodeFile(nodeFile, projectPath) {
+    if (isAbsolute(nodeFile))
+        return nodeFile;
+    return join(projectPath, nodeFile);
+}
+//# sourceMappingURL=resolveNodeFile.js.map

package/dist/utils/resolveNodeFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveNodeFile.js","sourceRoot":"","sources":["../../src/utils/resolveNodeFile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAExC,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,WAAmB;IACnE,IAAI,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1C,OAAO,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;AACrC,CAAC"}

package/dist/utils/startRfdbServer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared utility for starting rfdb-server
+ *
+ * Single authoritative function for spawning rfdb-server. All spawn sites
+ * (RFDBServerBackend, CLI server command, ParallelAnalysisRunner) delegate here.
+ *
+ * If pidPath is provided, checks for an existing server via PID file before
+ * spawning. Returns null when an existing server is detected (caller should
+ * not kill it).
+ */
+import { spawn, type ChildProcess } from 'child_process';
+export interface StartRfdbServerOptions {
+    dbPath: string;
+    socketPath: string;
+    /** Override binary path; if absent, findRfdbBinary() is called */
+    binaryPath?: string;
+    /** If provided, PID file is written after spawn and checked before spawn */
+    pidPath?: string;
+    /** Socket poll timeout in ms (default: 5000) */
+    waitTimeoutMs?: number;
+    /** Optional logger for debug messages */
+    logger?: {
+        debug(msg: string): void;
+    };
+    /** Internal: dependency injection for testing */
+    _deps?: {
+        spawn?: typeof spawn;
+        findRfdbBinary?: () => string | null;
+        existsSync?: (path: string) => boolean;
+        unlinkSync?: (path: string) => void;
+        writeFileSync?: (path: string, data: string) => void;
+        readFileSync?: (path: string, encoding: 'utf8') => string;
+        killProcess?: (pid: number, signal: number) => boolean;
+    };
+}
+/**
+ * Check if an existing server is running based on PID file.
+ *
+ * Returns:
+ * - 'alive' — PID file exists, process is alive, socket is present
+ * - 'stale' — PID file exists but process is dead or PID is invalid
+ * - 'none'  — no PID file
+ */
+export declare function checkExistingServer(pidPath: string, socketPath: string, deps: {
+    existsSync: (path: string) => boolean;
+    readFileSync: (path: string, encoding: 'utf8') => string;
+    killProcess: (pid: number, signal: number) => boolean;
+}): 'alive' | 'stale' | 'none';
+/**
+ * Start an rfdb-server process (or detect existing one via PID file).
+ *
+ * 0. Check PID file for existing server (if pidPath provided)
+ * 1. Resolve binary (explicit or via findRfdbBinary)
+ * 2. Remove stale socket
+ * 3. Spawn detached process
+ * 4. Write PID file (if pidPath provided)
+ * 5. Poll for socket file up to waitTimeoutMs
+ * 6. Return ChildProcess (caller decides whether to kill later)
+ *
+ * Returns null if an existing server is already running (pidPath + alive PID).
+ */
+export declare function startRfdbServer(options: StartRfdbServerOptions): Promise<ChildProcess | null>;
+//# sourceMappingURL=startRfdbServer.d.ts.map

package/dist/utils/startRfdbServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startRfdbServer.d.ts","sourceRoot":"","sources":["../../src/utils/startRfdbServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAIzD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACtC,iDAAiD;IACjD,KAAK,CAAC,EAAE;QACN,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;QACrC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QACvC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QACpC,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QACrD,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;QAC1D,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;KACxD,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE;IACJ,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACzD,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;CACvD,GACA,OAAO,GAAG,OAAO,GAAG,MAAM,CA4B5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAiGnG"}