@chude/memory 4.0.0

package/dist/infrastructure/embedding/background-embedder.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Background Embedder
+ *
+ * Manages background embedding processes with PID lock file lifecycle.
+ * The lock file prevents concurrent embedding runs and provides status
+ * information for the `memory status` command.
+ *
+ * Design:
+ * - Spawns a detached child process that runs `memory sync --embed --quiet`
+ * - PID lock file at {dataDir}/embedding.lock prevents double-run
+ * - Stale lock detection via process.kill(pid, 0) signal check
+ * - MEMORY_EMBED_BACKGROUND=1 env var signals background mode
+ * - Background process cleans up lock file on completion (success or failure)
+ */
+/**
+ * PID lock file data structure.
+ */
+export interface LockData {
+    pid: number;
+    startedAt: string;
+    totalMessages: number;
+}
+/**
+ * Result of a lock acquisition attempt.
+ */
+export interface AcquireResult {
+    acquired: boolean;
+    staleRemoved?: boolean | undefined;
+    existingPid?: number | undefined;
+    startedAt?: string | undefined;
+}
+/**
+ * Result of spawning a background embedding process.
+ */
+export interface SpawnResult {
+    started: boolean;
+    pid?: number | undefined;
+    reason?: "already_running" | "spawn_failed" | undefined;
+}
+/**
+ * Options for spawnBackgroundEmbedding.
+ */
+export interface SpawnBackgroundOptions {
+    dataDir?: string;
+    logDir?: string;
+    command?: string;
+}
+/**
+ * Write a PID lock file with the given data.
+ *
+ * Creates the data directory if it does not exist.
+ *
+ * @param data Lock file data (pid, startedAt, totalMessages)
+ * @param dataDir Optional override for data directory
+ */
+export declare function writeLock(data: LockData, dataDir?: string): void;
+/**
+ * Read the PID lock file.
+ *
+ * @param dataDir Optional override for data directory
+ * @returns Parsed lock data, or null if file does not exist or is invalid
+ */
+export declare function readLock(dataDir?: string): LockData | null;
+/**
+ * Remove the PID lock file.
+ *
+ * No-op if the lock file does not exist.
+ *
+ * @param dataDir Optional override for data directory
+ */
+export declare function removeLock(dataDir?: string): void;
+/**
+ * Check if a process with the given PID is alive.
+ *
+ * Uses signal 0 (existence check) which does not actually kill the process.
+ *
+ * @param pid Process ID to check
+ * @returns true if the process exists, false otherwise
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Attempt to acquire the embedding lock.
+ *
+ * - If no lock exists: creates lock and returns acquired:true
+ * - If lock held by alive process: returns acquired:false with existingPid
+ * - If lock held by dead process (stale): removes stale lock, creates new one
+ *
+ * @param pid Process ID to write into lock
+ * @param totalMessages Total message count (informational)
+ * @param dataDir Optional override for data directory
+ * @returns Acquisition result
+ */
+export declare function acquireLock(pid: number, totalMessages: number, dataDir?: string): AcquireResult;
+/**
+ * Spawn a background embedding process.
+ *
+ * Creates a detached child process that runs `memory sync --embed --quiet`
+ * with MEMORY_EMBED_BACKGROUND=1 in its environment. The parent process
+ * can exit immediately after spawning.
+ *
+ * If the lock is already held by an alive process, returns without spawning.
+ *
+ * @param options Configuration options
+ * @returns Spawn result with PID or failure reason
+ */
+export declare function spawnBackgroundEmbedding(options?: SpawnBackgroundOptions): SpawnResult;
+/**
+ * Clean up the PID lock file.
+ *
+ * Called by the background embedding process on completion (both success
+ * and failure) to release the lock.
+ *
+ * @param dataDir Optional override for data directory
+ */
+export declare function cleanupLock(dataDir?: string): void;
+/**
+ * Check if the current process is a background embedding process.
+ *
+ * The foreground sync command sets MEMORY_EMBED_BACKGROUND=1 when
+ * spawning the background process. This function checks that env var
+ * so the background process does NOT re-spawn another background process.
+ *
+ * @returns true if running as background embedding process
+ */
+export declare function isBackgroundEmbedding(): boolean;

package/dist/infrastructure/embedding/embedding-provider-factory.d.ts

@@ -0,0 +1,44 @@
+/**
+ * EmbeddingProviderFactory
+ *
+ * Creates embedding providers from configuration. Caches provider instances
+ * to avoid redundant resource allocation. The factory does NOT call
+ * initialize() -- the caller controls when the ONNX runtime loads.
+ *
+ * Supported providers:
+ * - "local" -> TransformersJsProvider
+ * - "openai" -> OpenAiProvider
+ * - "ollama" -> OllamaProvider
+ */
+import type { IEmbeddingProvider } from "../../domain/ports/embedding.js";
+import type { EmbeddingConfigData } from "../hooks/config-manager.js";
+export declare class EmbeddingProviderFactory {
+    private cache;
+    /**
+     * Generate a cache key from embedding config.
+     */
+    private cacheKey;
+    /**
+     * Create an embedding provider from config.
+     *
+     * The returned provider is NOT initialized -- call initialize()
+     * before embed(). Repeated calls with the same config return the
+     * cached instance.
+     *
+     * @throws Error if provider type is unsupported
+     */
+    create(config: EmbeddingConfigData): IEmbeddingProvider;
+    /**
+     * Create an embedding provider from a MemoryConfig object.
+     *
+     * Reads the embedding section and delegates to create().
+     * Returns null if embedding is disabled.
+     */
+    createFromConfig(memoryConfig: {
+        embedding?: EmbeddingConfigData;
+    }): IEmbeddingProvider | null;
+    /**
+     * Dispose all cached providers and clear the cache.
+     */
+    dispose(): Promise<void>;
+}

package/dist/infrastructure/embedding/index.d.ts

@@ -0,0 +1,5 @@
+export { TransformersJsProvider } from "./transformers-js-provider.js";
+export { OpenAiProvider } from "./openai-provider.js";
+export { OllamaProvider } from "./ollama-provider.js";
+export { EmbeddingProviderFactory } from "./embedding-provider-factory.js";
+export { writeLock, readLock, removeLock, isProcessAlive, acquireLock, spawnBackgroundEmbedding, cleanupLock, isBackgroundEmbedding, type LockData, type AcquireResult, type SpawnResult, type SpawnBackgroundOptions, } from "./background-embedder.js";

package/dist/infrastructure/embedding/ollama-provider.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Ollama Embedding Provider
+ *
+ * Infrastructure adapter implementing IEmbeddingProvider using the
+ * Ollama HTTP API. Communicates via native fetch() -- no npm
+ * dependencies required.
+ *
+ * Key design decisions:
+ * - Server reachability check during initialize(): GET /api/tags verifies
+ *   the Ollama server is running. Failure throws an actionable error
+ *   with recovery instructions.
+ * - Single-request batch: Ollama /api/embed accepts array input and
+ *   returns embeddings[] in the same order.
+ * - Model-not-found detection: 404 responses include a hint to pull
+ *   the model via `ollama pull`.
+ */
+import type { IEmbeddingProvider, DownloadProgress } from "../../domain/ports/embedding.js";
+import { EmbeddingResult } from "../../domain/value-objects/embedding-result.js";
+interface OllamaProviderOptions {
+    model?: string | undefined;
+    dimensions?: number | undefined;
+    baseUrl?: string | undefined;
+}
+export declare class OllamaProvider implements IEmbeddingProvider {
+    readonly name = "ollama";
+    readonly model: string;
+    readonly dimensions: number;
+    private readonly baseUrl;
+    private _ready;
+    constructor(options?: OllamaProviderOptions);
+    initialize(_onProgress?: (progress: DownloadProgress) => void): Promise<void>;
+    embed(text: string): Promise<EmbeddingResult>;
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    isReady(): boolean;
+    dispose(): Promise<void>;
+    /**
+     * Throw an error with an actionable hint for model-not-found cases.
+     */
+    private throwWithHint;
+}
+export {};

package/dist/infrastructure/embedding/openai-provider.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OpenAI Embedding Provider
+ *
+ * Infrastructure adapter implementing IEmbeddingProvider using the
+ * OpenAI embeddings API. Communicates via native fetch() -- no npm
+ * dependencies required.
+ *
+ * Key design decisions:
+ * - No API health check during initialize(): mark ready immediately
+ *   to avoid blocking on network calls during startup.
+ * - Single-request batch: OpenAI accepts array input, returns indexed
+ *   data[] that we sort by index for deterministic ordering.
+ * - Error messages include HTTP status for programmatic handling.
+ */
+import type { IEmbeddingProvider, DownloadProgress } from "../../domain/ports/embedding.js";
+import { EmbeddingResult } from "../../domain/value-objects/embedding-result.js";
+interface OpenAiProviderOptions {
+    apiKey: string;
+    model?: string | undefined;
+    dimensions?: number | undefined;
+    baseUrl?: string | undefined;
+    providerId?: string | undefined;
+}
+export declare class OpenAiProvider implements IEmbeddingProvider {
+    readonly name: string;
+    readonly model: string;
+    readonly dimensions: number;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private _ready;
+    constructor(options: OpenAiProviderOptions);
+    initialize(_onProgress?: (progress: DownloadProgress) => void): Promise<void>;
+    embed(text: string): Promise<EmbeddingResult>;
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    isReady(): boolean;
+    dispose(): Promise<void>;
+}
+export {};

package/dist/infrastructure/embedding/transformers-js-provider.d.ts

@@ -0,0 +1,34 @@
+/**
+ * TransformersJsProvider
+ *
+ * Infrastructure adapter implementing IEmbeddingProvider using
+ * @huggingface/transformers v3 with all-MiniLM-L6-v2 as the default model.
+ *
+ * Key design decisions:
+ * - Dynamic import: The @huggingface/transformers module is loaded lazily
+ *   inside initialize() via `await import(...)`. This ensures FTS5-only
+ *   searches never load the ONNX runtime.
+ * - WASM fallback: When native ONNX runtime fails, falls back to WASM
+ *   backend with numThreads=1 for maximum compatibility.
+ * - Progress reporting: Forwards Transformers.js progress events to the
+ *   onProgress callback as DownloadProgress objects.
+ */
+import type { IEmbeddingProvider, DownloadProgress } from "../../domain/ports/embedding.js";
+import { EmbeddingResult } from "../../domain/value-objects/embedding-result.js";
+interface TransformersJsProviderOptions {
+    model?: string;
+    dimensions?: number;
+}
+export declare class TransformersJsProvider implements IEmbeddingProvider {
+    readonly name = "transformers-js";
+    readonly model: string;
+    readonly dimensions: number;
+    private _pipeline;
+    constructor(options?: TransformersJsProviderOptions);
+    initialize(onProgress?: (progress: DownloadProgress) => void): Promise<void>;
+    embed(text: string): Promise<EmbeddingResult>;
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    isReady(): boolean;
+    dispose(): Promise<void>;
+}
+export {};

package/dist/infrastructure/external/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * External tool adapters barrel export.
+ *
+ * Infrastructure adapters that delegate to external CLI tools
+ * via subprocess invocation.
+ */
+export { QmdRunner, isQmdAvailable, getQmdInfo } from "./qmd-runner.js";

package/dist/infrastructure/external/qmd-runner.d.ts

@@ -0,0 +1,36 @@
+/**
+ * QmdRunner
+ *
+ * Infrastructure adapter that shells out to the qmd CLI for searching
+ * markdown files. Implements the IExternalSearchProvider domain port.
+ *
+ * qmd is an optional peer dependency -- this adapter gracefully handles
+ * the case where qmd is not installed.
+ */
+import type { IExternalSearchProvider, QmdSearchResult, QmdHealthInfo } from "../../domain/ports/index.js";
+export declare class QmdRunner implements IExternalSearchProvider {
+    /**
+     * Execute a search query against qmd and return parsed results.
+     *
+     * Spawns `qmd search <query> --json` and parses the JSON output.
+     */
+    search(query: string): Promise<QmdSearchResult[]>;
+    /**
+     * Check if qmd binary is available in PATH.
+     */
+    isAvailable(): boolean;
+    /**
+     * Get health info including binary path.
+     */
+    getHealthInfo(): QmdHealthInfo;
+}
+/**
+ * Standalone convenience function: check if qmd is available.
+ * Used by doctor command and other non-DI contexts.
+ */
+export declare function isQmdAvailable(): boolean;
+/**
+ * Standalone convenience function: get qmd health info.
+ * Used by doctor command and other non-DI contexts.
+ */
+export declare function getQmdInfo(): QmdHealthInfo;

package/dist/infrastructure/hooks/auto-memory-writer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * AutoMemoryWriter
+ *
+ * Infrastructure adapter implementing IAmbientContextWriter.
+ * Writes context.md (complete overwrite) and updates MEMORY.md
+ * using marker-based merge to preserve user content.
+ */
+import type { IAmbientContextWriter } from "../../domain/ports/services.js";
+/**
+ * Merge block content into existing MEMORY.md content using markers.
+ *
+ * Rules:
+ * - If markers exist: replace content between them, preserve everything else
+ * - If no markers: append block with markers at end
+ * - If empty: create block with markers
+ * - Content outside markers is never modified
+ *
+ * Exported as a pure function for direct unit testing.
+ *
+ * @param existing Current file content (may be empty)
+ * @param blockContent New content to place between markers
+ * @returns Merged content
+ */
+export declare function mergeMemoryBlock(existing: string, blockContent: string): string;
+/**
+ * Infrastructure adapter for writing ambient context artifacts.
+ *
+ * Implements the IAmbientContextWriter domain port.
+ * Uses synchronous filesystem operations wrapped in async methods
+ * to match the port contract.
+ */
+export declare class AutoMemoryWriter implements IAmbientContextWriter {
+    /**
+     * Write the full context file (complete overwrite).
+     *
+     * Creates the directory recursively if it does not exist.
+     *
+     * @param autoMemoryDir Directory path for the auto-memory artifacts
+     * @param content Content to write as context.md
+     */
+    writeContextFile(autoMemoryDir: string, content: string): Promise<void>;
+    /**
+     * Update the MEMORY.md block using marker-based merge.
+     *
+     * Creates the directory and file if they do not exist.
+     * Replaces content between markers, preserves content outside.
+     *
+     * @param autoMemoryDir Directory path for the auto-memory artifacts
+     * @param blockContent Content to place between markers
+     */
+    updateMemoryBlock(autoMemoryDir: string, blockContent: string): Promise<void>;
+}

package/dist/infrastructure/hooks/config-manager.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Configuration Manager
+ *
+ * Manages memory configuration with defaults.
+ * Configuration stored at the XDG config path via centralized paths module.
+ *
+ * Implements graceful handling of missing/invalid config files.
+ */
+/**
+ * Embedding configuration data interface
+ *
+ * Plain object shape for embedding config stored in JSON.
+ * The factory validates via domain value objects when needed.
+ */
+export interface EmbeddingConfigData {
+    /** Whether embedding generation is enabled */
+    enabled: boolean;
+    /** Provider identifier (e.g., "local", "openai", "ollama") */
+    provider: string;
+    /** Model identifier (e.g., "Xenova/all-MiniLM-L6-v2") */
+    model: string;
+    /** Number of dimensions in the embedding vectors */
+    dimensions: number;
+    /** Number of messages to embed per batch */
+    batchSize: number;
+    /** @deprecated Prefer apiKeyEnv or runtime environment injection. */
+    apiKey?: string;
+    /** Environment variable name that contains the provider API key */
+    apiKeyEnv?: string;
+    /** Opaque secret reference for external secret managers; never resolved here */
+    apiKeyRef?: string;
+    /** Base URL override for provider API endpoint */
+    baseUrl?: string;
+}
+export interface ApiKeyResolution {
+    apiKey?: string;
+    source: "environment" | "plaintext-config" | "missing";
+    envVar?: string;
+    ref?: string;
+    deprecatedPlaintext: boolean;
+}
+/**
+ * Search configuration data interface
+ *
+ * Plain object shape for search config stored in JSON.
+ */
+export interface SearchConfigData {
+    /** Default search mode */
+    defaultMode: "auto" | "fts" | "vector" | "hybrid";
+    /** Temporal decay settings */
+    temporalDecay: {
+        /** Whether temporal decay is enabled */
+        enabled: boolean;
+        /** Half-life in days for temporal decay */
+        halfLifeDays: number;
+    };
+    /** Whether the embedding hint has been shown (one-time) */
+    hintShown?: boolean;
+}
+/**
+ * Default search configuration
+ *
+ * Auto mode with 30-day temporal decay half-life.
+ */
+export declare const DEFAULT_SEARCH_CONFIG: SearchConfigData;
+/**
+ * Ambient context configuration data interface
+ *
+ * Controls automatic context generation into Claude Code's
+ * auto memory directory during sync.
+ */
+export interface AmbientContextConfigData {
+    /** Whether ambient context generation is enabled */
+    enabled: boolean;
+    /** Token budget for context.md generation */
+    budget: number;
+}
+/**
+ * Default ambient context configuration
+ *
+ * Enabled by default with 800 token budget.
+ */
+export declare const DEFAULT_AMBIENT_CONTEXT_CONFIG: AmbientContextConfigData;
+/**
+ * Remote sync configuration data interface
+ *
+ * Plain object shape for remote sync config stored in JSON.
+ */
+export interface RemoteSyncConfigData {
+    /** Whether remote synchronization is enabled */
+    enabled: boolean;
+    /** Git repository URL for synchronization */
+    repositoryUrl?: string;
+    /** Whether to automatically push on sync */
+    autoPush: boolean;
+    /** Whether to automatically pull on sync */
+    autoPull: boolean;
+}
+/**
+ * Default remote sync configuration
+ */
+export declare const DEFAULT_REMOTE_SYNC_CONFIG: RemoteSyncConfigData;
+export interface LegacyMemoryFilesConfigData {
+    /** Whether legacy ~/.memory / MEMORY_HOME markdown indexing and writes are enabled */
+    enabled: boolean;
+}
+export declare const DEFAULT_LEGACY_MEMORY_FILES_CONFIG: LegacyMemoryFilesConfigData;
+/**
+ * Memory configuration interface
+ *
+ * All options from CONTEXT.md:
+ * - autoSync: Enable automatic hook-based sync
+ * - recoveryOnStartup: Scan for unsaved sessions on first command
+ * - syncOnCompaction: Trigger sync on PreCompact event
+ * - timeout: Sync timeout in milliseconds
+ * - logLevel: Logging verbosity
+ * - logRetentionDays: Days to keep log files
+ * - showFailures: Show failure notifications to user
+ * - embedding: Embedding provider configuration
+ * - search: Hybrid search configuration
+ * - ambientContext: Ambient context generation configuration
+ * - machineId: Unique identifier for the local machine
+ * - remoteSync: Remote sync configuration
+ * - legacyMemoryFiles: Explicit opt-in for pre-v4 ~/.memory / MEMORY_HOME sidecar files
+ */
+export interface MemoryConfig {
+    /** Enable automatic hook-based sync */
+    autoSync: boolean;
+    /** Scan for unsaved sessions on first command */
+    recoveryOnStartup: boolean;
+    /** Trigger sync on PreCompact event */
+    syncOnCompaction: boolean;
+    /** Sync timeout in milliseconds */
+    timeout: number;
+    /** Logging verbosity */
+    logLevel: "debug" | "info" | "warn" | "error";
+    /** Days to keep log files */
+    logRetentionDays: number;
+    /** Show failure notifications to user */
+    showFailures: boolean;
+    /** Embedding provider configuration */
+    embedding: EmbeddingConfigData;
+    /** Hybrid search configuration */
+    search: SearchConfigData;
+    /** Ambient context generation configuration */
+    ambientContext: AmbientContextConfigData;
+    /** Unique identifier for the local machine */
+    machineId: string;
+    /** Remote sync configuration */
+    remoteSync: RemoteSyncConfigData;
+    /** Legacy memory-file sidecar compatibility */
+    legacyMemoryFiles: LegacyMemoryFilesConfigData;
+}
+/**
+ * Provider-specific default model and dimensions
+ *
+ * Maps provider identifiers to their default model and dimensions.
+ * Used by resolveProviderDefaults() to apply correct defaults
+ * when a user sets provider without explicit model/dimensions.
+ */
+export declare const PROVIDER_DEFAULTS: Record<string, {
+    model: string;
+    dimensions: number;
+}>;
+/**
+ * Resolve provider-specific defaults for model and dimensions
+ *
+ * After deep-merging user config with DEFAULT_EMBEDDING_CONFIG,
+ * checks if the provider was changed from "local" and whether
+ * model/dimensions were user-explicit. If not, applies provider-specific
+ * defaults from PROVIDER_DEFAULTS.
+ *
+ * Uses `in` operator to check field presence in the raw user JSON:
+ * - "model" in userEmbedding returns true even if value matches a default
+ * - This correctly preserves user-explicit values
+ *
+ * @param merged The deep-merged embedding config
+ * @param userEmbedding The raw user embedding section from JSON (before merge)
+ * @returns Resolved embedding config with correct provider defaults
+ */
+export declare function resolveProviderDefaults(merged: EmbeddingConfigData, userEmbedding: Partial<EmbeddingConfigData> | undefined): EmbeddingConfigData;
+export declare function resolveEmbeddingApiKey(config: Pick<EmbeddingConfigData, "apiKey" | "apiKeyEnv" | "apiKeyRef">, providerEnvVars: string[]): ApiKeyResolution;
+/**
+ * Default embedding configuration
+ *
+ * Local provider with all-MiniLM-L6-v2 model (384 dimensions).
+ * Enabled by default so embedding features are opt-out.
+ */
+export declare const DEFAULT_EMBEDDING_CONFIG: EmbeddingConfigData;
+/**
+ * Default configuration with all features enabled
+ *
+ * Matches CONTEXT.md specification:
+ * - All sync features enabled (autoSync, recoveryOnStartup, syncOnCompaction)
+ * - 5 second timeout (matches OpenClaw pattern)
+ * - Info log level for reasonable verbosity
+ * - 7 day log retention
+ * - Silent failures by default (never interrupt user)
+ * - Local embedding provider with all-MiniLM-L6-v2
+ */
+export declare const DEFAULT_CONFIG: MemoryConfig;
+/**
+ * Get the path to the config directory.
+ *
+ * @param configPathOverride Optional explicit config file path (used by
+ *   tests). The directory is derived from this path.
+ * @returns Path to the config directory
+ */
+export declare function getConfigDir(configPathOverride?: string): string;
+/**
+ * Get the path to the config file.
+ *
+ * @param configPathOverride Optional explicit config file path (used by tests)
+ * @returns Path to config.json
+ */
+export declare function getConfigPath(configPathOverride?: string): string;
+/**
+ * Load configuration from disk
+ *
+ * Gracefully handles:
+ * - Missing config file (returns defaults)
+ * - Invalid JSON (returns defaults with warning)
+ * - Partial config (merges with defaults)
+ *
+ * @returns Complete configuration with defaults applied
+ */
+export declare function loadConfig(configPathOverride?: string): MemoryConfig;
+/**
+ * Save configuration to disk
+ *
+ * Creates the config directory if it doesn't exist.
+ * Merges partial config with existing config (if present).
+ * Writes JSON with 2-space indent for readability.
+ *
+ * @param config Partial configuration to save (merged with existing)
+ */
+export declare function saveConfig(config: Partial<MemoryConfig>, configPathOverride?: string): void;

package/dist/infrastructure/hooks/git-syncer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Git Syncer Hook
+ *
+ * Secure, shell-less transport manager utilizing Bun's subprocess spawner
+ * to synchronize machine-specific log files via a private Git repository
+ * without user credential storage.
+ */
+export interface SyncResult {
+    success: boolean;
+    rebuildNeeded: boolean;
+    error?: string;
+}
+export interface GitCommandResult {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface GitSyncerDeps {
+    runGit?: (args: string[], cwd: string) => Promise<GitCommandResult>;
+    existsSync?: (path: string) => boolean;
+    readFileSync?: (path: string, encoding: BufferEncoding) => string;
+    getAllLogFiles?: (eventsDir?: string) => string[];
+    now?: () => Date;
+}
+/**
+ * Runs a git command securely using Bun's shell-less spawner.
+ */
+export declare function runGit(args: string[], cwd: string, env?: NodeJS.ProcessEnv): Promise<GitCommandResult>;
+/**
+ * GitSyncer infrastructure hook.
+ * Encapsulates Git transport operations for Multi-Device synchronization.
+ */
+export declare class GitSyncer {
+    private readonly eventsDir;
+    private readonly deps;
+    constructor(eventsDir?: string, deps?: GitSyncerDeps);
+    isGitRepo(): Promise<boolean>;
+    initRepo(): Promise<boolean>;
+    configureRemote(remoteUrl: string): Promise<boolean>;
+    removeRemote(): Promise<boolean>;
+    getRemoteUrl(): Promise<string | null>;
+    sync(machineId: string, remoteUrl: string, autoPull?: boolean, autoPush?: boolean): Promise<SyncResult>;
+}