atabey 0.0.37 → 0.1.0

package/dist/shared/src/modules/concurrency/lock.d.ts

@@ -0,0 +1,82 @@
+/**
+ * [LOCK] Multi-user Distributed Lock Mechanism
+ *
+ * Git-based lock system. Enables team members to work on the same
+ * files/resources without conflicts.
+ *
+ * Usage:
+ *   const lock = new DistributedLock("database/schema.sql");
+ *   if (lock.acquire("user-123", 60000)) {
+ *     // Apply changes
+ *     lock.release("user-123");
+ *   }
+ */
+export type LockStatus = "LOCKED" | "AVAILABLE" | "STALE" | "EXPIRED";
+export interface LockInfo {
+    resource: string;
+    ownerId: string;
+    ownerName: string;
+    acquiredAt: string;
+    expiresAt: string;
+    reason: string;
+    traceId?: string;
+}
+export declare class DistributedLock {
+    private static TABLE;
+    /**
+     * Initialize the locks table (run once at startup).
+     */
+    static initialize(): void;
+    /**
+     * Attempts to acquire a lock on a resource.
+     *
+     * @param resource - Lock resource name (e.g., "apps/backend/src/types/user.ts")
+     * @param ownerId - Unique owner identifier (e.g., "yusuf", "ci-bot-01")
+     * @param options - Optional parameters
+     * @returns true if lock acquired, false if already locked
+     */
+    static acquire(resource: string, ownerId: string, options?: {
+        ownerName?: string;
+        ttlMs?: number;
+        reason?: string;
+        traceId?: string;
+        force?: boolean;
+    }): boolean;
+    /**
+     * Releases a lock. Only the lock owner can release.
+     *
+     * @param resource - Lock resource name
+     * @param ownerId - Owner identifier for verification
+     * @returns true if released successfully
+     */
+    static release(resource: string, ownerId: string): boolean;
+    /**
+     * Checks if a resource is locked.
+     */
+    static isLocked(resource: string): boolean;
+    /**
+     * Gets lock information for a resource.
+     */
+    static getLock(resource: string): LockInfo | null;
+    /**
+     * Lists all active locks.
+     */
+    static listActiveLocks(): LockInfo[];
+    /**
+     * Lists all locks owned by a specific owner.
+     */
+    static listOwnerLocks(ownerId: string): LockInfo[];
+    /**
+     * Releases all locks owned by a specific owner (e.g., on disconnect).
+     */
+    static releaseAllByOwner(ownerId: string): number;
+    /**
+     * Releases all expired/stale locks.
+     */
+    private static releaseStaleLocks;
+    /**
+     * Generates a unique owner ID for the current user/machine.
+     * Uses git config user.name or hostname as fallback.
+     */
+    static getLocalOwnerId(): string;
+}

package/dist/shared/src/modules/concurrency/lock.js

@@ -0,0 +1,159 @@
+/**
+ * [LOCK] Multi-user Distributed Lock Mechanism
+ *
+ * Git-based lock system. Enables team members to work on the same
+ * files/resources without conflicts.
+ *
+ * Usage:
+ *   const lock = new DistributedLock("database/schema.sql");
+ *   if (lock.acquire("user-123", 60000)) {
+ *     // Apply changes
+ *     lock.release("user-123");
+ *   }
+ */
+import { execSync } from "child_process";
+import os from "os";
+import { databaseHolder } from "../storage/database.js";
+export class DistributedLock {
+    static TABLE = "distributed_locks";
+    /**
+     * Initialize the locks table (run once at startup).
+     */
+    static initialize() {
+        const db = databaseHolder.getDB();
+        db.exec(`
+            CREATE TABLE IF NOT EXISTS ${this.TABLE} (
+                resource TEXT PRIMARY KEY,
+                ownerId TEXT NOT NULL,
+                ownerName TEXT NOT NULL,
+                acquiredAt TEXT NOT NULL,
+                expiresAt TEXT NOT NULL,
+                reason TEXT,
+                traceId TEXT
+            )
+        `);
+    }
+    /**
+     * Attempts to acquire a lock on a resource.
+     *
+     * @param resource - Lock resource name (e.g., "apps/backend/src/types/user.ts")
+     * @param ownerId - Unique owner identifier (e.g., "yusuf", "ci-bot-01")
+     * @param options - Optional parameters
+     * @returns true if lock acquired, false if already locked
+     */
+    static acquire(resource, ownerId, options = {}) {
+        const db = databaseHolder.getDB();
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + (options.ttlMs || 60000)).toISOString();
+        const ownerName = options.ownerName || ownerId;
+        const reason = options.reason || "No reason provided";
+        // Clean up stale locks first
+        this.releaseStaleLocks();
+        // If force=true, override existing lock directly using INSERT OR REPLACE
+        if (options.force) {
+            db.prepare(`
+                INSERT OR REPLACE INTO ${this.TABLE} (resource, ownerId, ownerName, acquiredAt, expiresAt, reason, traceId)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+            `).run(resource, ownerId, ownerName, now.toISOString(), expiresAt, reason, options.traceId || null);
+            return true;
+        }
+        // Acquire new lock atomically using INSERT OR IGNORE.
+        // If the resource is already locked, changes will be 0.
+        const result = db.prepare(`
+            INSERT OR IGNORE INTO ${this.TABLE} (resource, ownerId, ownerName, acquiredAt, expiresAt, reason, traceId)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        `).run(resource, ownerId, ownerName, now.toISOString(), expiresAt, reason, options.traceId || null);
+        return result.changes > 0;
+    }
+    /**
+     * Releases a lock. Only the lock owner can release.
+     *
+     * @param resource - Lock resource name
+     * @param ownerId - Owner identifier for verification
+     * @returns true if released successfully
+     */
+    static release(resource, ownerId) {
+        const db = databaseHolder.getDB();
+        const result = db.prepare(`DELETE FROM ${this.TABLE} WHERE resource = ? AND ownerId = ?`).run(resource, ownerId);
+        return result.changes > 0;
+    }
+    /**
+     * Checks if a resource is locked.
+     */
+    static isLocked(resource) {
+        const db = databaseHolder.getDB();
+        const nowIso = new Date().toISOString();
+        const lock = db.prepare(`SELECT * FROM ${this.TABLE} WHERE resource = ? AND expiresAt > ?`).get(resource, nowIso);
+        return !!lock;
+    }
+    /**
+     * Gets lock information for a resource.
+     */
+    static getLock(resource) {
+        const db = databaseHolder.getDB();
+        this.releaseStaleLocks();
+        const lock = db.prepare(`SELECT * FROM ${this.TABLE} WHERE resource = ?`).get(resource);
+        return lock || null;
+    }
+    /**
+     * Lists all active locks.
+     */
+    static listActiveLocks() {
+        const db = databaseHolder.getDB();
+        this.releaseStaleLocks();
+        const nowIso = new Date().toISOString();
+        return db.prepare(`SELECT * FROM ${this.TABLE} WHERE expiresAt > ? ORDER BY acquiredAt DESC`).all(nowIso);
+    }
+    /**
+     * Lists all locks owned by a specific owner.
+     */
+    static listOwnerLocks(ownerId) {
+        const db = databaseHolder.getDB();
+        return db.prepare(`SELECT * FROM ${this.TABLE} WHERE ownerId = ? ORDER BY acquiredAt DESC`).all(ownerId);
+    }
+    /**
+     * Releases all locks owned by a specific owner (e.g., on disconnect).
+     */
+    static releaseAllByOwner(ownerId) {
+        const db = databaseHolder.getDB();
+        const result = db.prepare(`DELETE FROM ${this.TABLE} WHERE ownerId = ?`).run(ownerId);
+        return result.changes;
+    }
+    /**
+     * Releases all expired/stale locks.
+     */
+    static releaseStaleLocks() {
+        const db = databaseHolder.getDB();
+        const nowIso = new Date().toISOString();
+        const result = db.prepare(`DELETE FROM ${this.TABLE} WHERE expiresAt < ?`).run(nowIso);
+        return result.changes;
+    }
+    /**
+     * Generates a unique owner ID for the current user/machine.
+     * Uses git config user.name or hostname as fallback.
+     */
+    static getLocalOwnerId() {
+        // Try git config
+        try {
+            const name = execSync("git config user.name", { encoding: "utf8" }).trim();
+            if (name)
+                return name;
+        }
+        catch {
+            // Fallback
+        }
+        // Try environment
+        if (process.env.USER)
+            return process.env.USER;
+        if (process.env.USERNAME)
+            return process.env.USERNAME;
+        // Fallback to hostname
+        try {
+            return os.hostname();
+        }
+        catch {
+            return "unknown-user";
+        }
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/shared/src/modules/concurrency/lock.js.map

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

package/dist/shared/src/modules/concurrency/resilience.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Polly-style resilience primitives — no external deps.
+ *
+ * - withRetry: exponential backoff + jitter for transient failures
+ * - CircuitBreaker: closed → open → half-open state machine
+ * - withResilience: compose retry + circuit breaker
+ *
+ * Typical use: LLM provider rate limits, timeouts, 5xx, network blips.
+ */
+export type CircuitState = "closed" | "open" | "half-open";
+export interface RetryOptions {
+    /** Max attempts including the first try. Default: 3 */
+    maxAttempts?: number;
+    /** Initial delay in ms. Default: 100 */
+    baseDelayMs?: number;
+    /** Cap on delay in ms. Default: 10_000 */
+    maxDelayMs?: number;
+    /** Exponential factor. Default: 2 */
+    factor?: number;
+    /** Add random jitter [0, delay). Default: true */
+    jitter?: boolean;
+    /** Return true to retry this error. Default: retry all */
+    retryIf?: (error: unknown, attempt: number) => boolean;
+    /** Optional hook before each sleep */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+    /** Optional abort signal */
+    signal?: AbortSignal;
+}
+export interface CircuitBreakerOptions {
+    /** Failures in closed state before opening. Default: 5 */
+    failureThreshold?: number;
+    /** Successes in half-open before closing. Default: 2 */
+    successThreshold?: number;
+    /** Time to wait in open before half-open probe. Default: 30_000 */
+    openMs?: number;
+    /** Optional name for error messages */
+    name?: string;
+}
+export declare class CircuitOpenError extends Error {
+    readonly circuit: string;
+    readonly retryAfterMs: number;
+    constructor(circuit: string, retryAfterMs: number);
+}
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private openedAt;
+    private readonly failureThreshold;
+    private readonly successThreshold;
+    private readonly openMs;
+    private readonly name;
+    constructor(options?: CircuitBreakerOptions);
+    getState(): CircuitState;
+    getStats(): {
+        state: CircuitState;
+        failures: number;
+        successes: number;
+        name: string;
+    };
+    /** Manual reset (e.g. after operator intervention). */
+    reset(): void;
+    exec<T>(fn: () => Promise<T>): Promise<T>;
+    private maybeTransitionToHalfOpen;
+    private onSuccess;
+    private onFailure;
+    private trip;
+}
+export declare function computeBackoffDelay(attempt: number, options?: Pick<RetryOptions, "baseDelayMs" | "maxDelayMs" | "factor" | "jitter">): number;
+export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
+export interface ResilienceOptions {
+    retry?: RetryOptions;
+    circuitBreaker?: CircuitBreaker;
+    /** If true, CircuitOpenError is not retried (default true). */
+    skipRetryOnOpenCircuit?: boolean;
+}
+/**
+ * Execute `fn` through optional circuit breaker + retry with exponential backoff.
+ */
+export declare function withResilience<T>(fn: (attempt: number) => Promise<T>, options?: ResilienceOptions): Promise<T>;
+/** Heuristic: retry rate limits, timeouts, and common transient network errors. */
+export declare function isTransientError(error: unknown): boolean;
+export declare function getCircuitBreaker(name: string, options?: CircuitBreakerOptions): CircuitBreaker;
+export declare function resetAllCircuitBreakers(): void;

package/dist/shared/src/modules/concurrency/resilience.js

@@ -0,0 +1,217 @@
+/**
+ * Polly-style resilience primitives — no external deps.
+ *
+ * - withRetry: exponential backoff + jitter for transient failures
+ * - CircuitBreaker: closed → open → half-open state machine
+ * - withResilience: compose retry + circuit breaker
+ *
+ * Typical use: LLM provider rate limits, timeouts, 5xx, network blips.
+ */
+export class CircuitOpenError extends Error {
+    circuit;
+    retryAfterMs;
+    constructor(circuit, retryAfterMs) {
+        super(`[CircuitBreaker:${circuit}] Circuit is OPEN — rejecting call. Retry after ~${retryAfterMs}ms`);
+        this.name = "CircuitOpenError";
+        this.circuit = circuit;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class CircuitBreaker {
+    state = "closed";
+    failures = 0;
+    successes = 0;
+    openedAt = 0;
+    failureThreshold;
+    successThreshold;
+    openMs;
+    name;
+    constructor(options = {}) {
+        this.failureThreshold = options.failureThreshold ?? 5;
+        this.successThreshold = options.successThreshold ?? 2;
+        this.openMs = options.openMs ?? 30_000;
+        this.name = options.name ?? "default";
+    }
+    getState() {
+        this.maybeTransitionToHalfOpen();
+        return this.state;
+    }
+    getStats() {
+        return {
+            state: this.getState(),
+            failures: this.failures,
+            successes: this.successes,
+            name: this.name,
+        };
+    }
+    /** Manual reset (e.g. after operator intervention). */
+    reset() {
+        this.state = "closed";
+        this.failures = 0;
+        this.successes = 0;
+        this.openedAt = 0;
+    }
+    async exec(fn) {
+        this.maybeTransitionToHalfOpen();
+        if (this.state === "open") {
+            const retryAfterMs = Math.max(0, this.openMs - (Date.now() - this.openedAt));
+            throw new CircuitOpenError(this.name, retryAfterMs);
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (err) {
+            this.onFailure();
+            throw err;
+        }
+    }
+    maybeTransitionToHalfOpen() {
+        if (this.state === "open" && Date.now() - this.openedAt >= this.openMs) {
+            this.state = "half-open";
+            this.successes = 0;
+        }
+    }
+    onSuccess() {
+        if (this.state === "half-open") {
+            this.successes++;
+            if (this.successes >= this.successThreshold) {
+                this.state = "closed";
+                this.failures = 0;
+                this.successes = 0;
+            }
+            return;
+        }
+        // closed: decay failure count on success
+        this.failures = 0;
+    }
+    onFailure() {
+        this.failures++;
+        this.successes = 0;
+        if (this.state === "half-open") {
+            this.trip();
+            return;
+        }
+        if (this.failures >= this.failureThreshold) {
+            this.trip();
+        }
+    }
+    trip() {
+        this.state = "open";
+        this.openedAt = Date.now();
+    }
+}
+export function computeBackoffDelay(attempt, options = {}) {
+    const base = options.baseDelayMs ?? 100;
+    const max = options.maxDelayMs ?? 10_000;
+    const factor = options.factor ?? 2;
+    const jitter = options.jitter !== false;
+    // attempt is 1-based for first retry after failure → attempt 1 => base * factor^0
+    const exp = Math.max(0, attempt - 1);
+    let delay = Math.min(max, base * Math.pow(factor, exp));
+    if (jitter) {
+        delay = Math.floor(Math.random() * delay);
+    }
+    return delay;
+}
+export async function withRetry(fn, options = {}) {
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+    const retryIf = options.retryIf ?? (() => true);
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        if (options.signal?.aborted) {
+            throw options.signal.reason ?? new Error("Aborted");
+        }
+        try {
+            return await fn(attempt);
+        }
+        catch (err) {
+            lastError = err;
+            const isLast = attempt >= maxAttempts;
+            if (isLast || !retryIf(err, attempt)) {
+                throw err;
+            }
+            const delay = computeBackoffDelay(attempt, options);
+            options.onRetry?.(err, attempt, delay);
+            await sleep(delay, options.signal);
+        }
+    }
+    throw lastError;
+}
+/**
+ * Execute `fn` through optional circuit breaker + retry with exponential backoff.
+ */
+export async function withResilience(fn, options = {}) {
+    const breaker = options.circuitBreaker;
+    const skipOpen = options.skipRetryOnOpenCircuit !== false;
+    const retryOpts = {
+        ...options.retry,
+        retryIf: (err, attempt) => {
+            if (skipOpen && err instanceof CircuitOpenError)
+                return false;
+            return options.retry?.retryIf ? options.retry.retryIf(err, attempt) : true;
+        },
+    };
+    return withRetry(async (attempt) => {
+        if (breaker) {
+            return breaker.exec(() => fn(attempt));
+        }
+        return fn(attempt);
+    }, retryOpts);
+}
+/** Heuristic: retry rate limits, timeouts, and common transient network errors. */
+export function isTransientError(error) {
+    if (error instanceof CircuitOpenError)
+        return false;
+    if (!error)
+        return false;
+    const msg = error instanceof Error ? error.message : String(error);
+    const lower = msg.toLowerCase();
+    const code = error.code;
+    const status = error.status;
+    if (status === 429 || status === 502 || status === 503 || status === 504)
+        return true;
+    if (code === "ETIMEDOUT" || code === "ECONNRESET" || code === "EAI_AGAIN" || code === "ENOTFOUND") {
+        return true;
+    }
+    if (lower.includes("rate limit") ||
+        lower.includes("too many requests") ||
+        lower.includes("timeout") ||
+        lower.includes("temporar") ||
+        lower.includes("econnreset") ||
+        lower.includes("socket hang up")) {
+        return true;
+    }
+    return false;
+}
+/** Shared breakers for common services (lazy). */
+const breakers = new Map();
+export function getCircuitBreaker(name, options) {
+    let b = breakers.get(name);
+    if (!b) {
+        b = new CircuitBreaker({ name, ...options });
+        breakers.set(name, b);
+    }
+    return b;
+}
+export function resetAllCircuitBreakers() {
+    for (const b of breakers.values())
+        b.reset();
+    breakers.clear();
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error("Aborted"));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason ?? new Error("Aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=resilience.js.map

package/dist/shared/src/modules/concurrency/resilience.js.map

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

package/dist/shared/src/modules/concurrency/worker-pool.d.ts

@@ -0,0 +1,52 @@
+/**
+ * In-Memory Worker Pool — worker_threads based, no Redis/BullMQ.
+ *
+ * Heavy / isolable work runs off the main thread. Concurrency is capped
+ * (default os.cpus().length) via an internal queue so RAM/CPU stay bounded.
+ *
+ * Thread-safety note: SQLite (better-sqlite3) bindings are NOT thread-safe.
+ * Worker threads MUST NOT access AtabeyStorage or any SQLite connection.
+ * Only CPU-bound isolable work (hash, tokenize, etc.) should be dispatched
+ * to the worker pool.
+ */
+export interface WorkerPoolOptions {
+    /** Max concurrent worker jobs. Default: os.cpus().length (clamped 1–16). */
+    maxConcurrency?: number;
+    /** Idle workers retained in the pool. Default: min(2, maxConcurrency). */
+    minWorkers?: number;
+    /** Per-job timeout in ms. Default: 30_000. */
+    jobTimeoutMs?: number;
+    /** Optional absolute path to worker script (tests / monorepo layouts). */
+    workerScript?: string;
+}
+export declare class WorkerPool {
+    private readonly maxConcurrency;
+    private readonly minWorkers;
+    private readonly jobTimeoutMs;
+    private readonly workerScript;
+    private readonly workers;
+    private readonly queue;
+    private readonly inflight;
+    private jobSeq;
+    private closed;
+    constructor(options?: WorkerPoolOptions);
+    /**
+     * Run a named job type on a worker thread.
+     * Returns when the worker posts a result (or on timeout/error).
+     */
+    run<T = unknown>(type: string, payload?: unknown): Promise<T>;
+    getStats(): {
+        maxConcurrency: number;
+        workers: number;
+        busy: number;
+        pending: number;
+        inflight: number;
+    };
+    close(): Promise<void>;
+    private failWorkerJob;
+    private spawnWorker;
+    private removeWorker;
+    private dispatch;
+}
+export declare function getDefaultWorkerPool(options?: WorkerPoolOptions): WorkerPool;
+export declare function resetDefaultWorkerPool(): Promise<void>;