atabey 0.0.16 → 0.0.17

package/dist/src/modules/engines/file-lock.d.ts

@@ -0,0 +1,41 @@
+/**
+ * [ENGINE] File Lock — Conflict Resolution for Multi-Agent File Access
+ *
+ * Prevents two agents from writing to the same file simultaneously.
+ * Uses .atabey/locks/ directory with per-file lock files.
+ *
+ * Flow:
+ * 1. Agent A acquires lock on src/file.ts → writes .atabey/locks/src/file.ts.lock
+ * 2. Agent B tries to write src/file.ts → lock exists → WAITING state
+ * 3. Agent A releases lock → Agent B can proceed
+ *
+ * Stale lock detection: locks older than 5 minutes are auto-released.
+ */
+export declare class FileLock {
+    private static LOCKS_DIR;
+    private static STALE_TIMEOUT_MS;
+    /**
+     * Attempts to acquire a lock for a file on behalf of an agent.
+     * Returns true if lock acquired, false if another agent holds it.
+     */
+    static acquire(agentName: string, filePath: string): boolean;
+    /**
+     * Releases a lock held by an agent.
+     * Only the lock-owning agent can release (others get warning).
+     */
+    static release(agentName: string, filePath: string): boolean;
+    /**
+     * Checks if a file is currently locked.
+     * Returns the locking agent name or null.
+     */
+    static isLocked(filePath: string): string | null;
+    /**
+     * Lists all currently active locks.
+     */
+    static listLocks(): Array<{
+        agent: string;
+        file: string;
+        acquiredAt: string;
+    }>;
+    private static getLockPath;
+}

package/dist/src/modules/engines/file-lock.js

@@ -0,0 +1,168 @@
+import fs from "fs";
+import path from "path";
+import { logger } from "../../shared/logger.js";
+import { AtabeyStorage } from "../../shared/storage.js";
+/**
+ * [ENGINE] File Lock — Conflict Resolution for Multi-Agent File Access
+ *
+ * Prevents two agents from writing to the same file simultaneously.
+ * Uses .atabey/locks/ directory with per-file lock files.
+ *
+ * Flow:
+ * 1. Agent A acquires lock on src/file.ts → writes .atabey/locks/src/file.ts.lock
+ * 2. Agent B tries to write src/file.ts → lock exists → WAITING state
+ * 3. Agent A releases lock → Agent B can proceed
+ *
+ * Stale lock detection: locks older than 5 minutes are auto-released.
+ */
+export class FileLock {
+    static LOCKS_DIR = ".atabey/locks";
+    static STALE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+    /**
+     * Attempts to acquire a lock for a file on behalf of an agent.
+     * Returns true if lock acquired, false if another agent holds it.
+     */
+    static acquire(agentName, filePath) {
+        const lockFile = FileLock.getLockPath(filePath);
+        const lockDir = path.dirname(lockFile);
+        // Ensure locks directory exists
+        if (!fs.existsSync(lockDir)) {
+            fs.mkdirSync(lockDir, { recursive: true });
+        }
+        // Check if lock already exists
+        if (fs.existsSync(lockFile)) {
+            try {
+                const lockData = JSON.parse(fs.readFileSync(lockFile, "utf8"));
+                // Check if lock is stale (older than 5 min)
+                const lockAge = Date.now() - new Date(lockData.acquiredAt).getTime();
+                if (lockAge > FileLock.STALE_TIMEOUT_MS) {
+                    logger.warn(`[FILE_LOCK] Stale lock detected for ${filePath} (age: ${Math.round(lockAge / 1000)}s). Overriding.`);
+                    fs.unlinkSync(lockFile);
+                }
+                else {
+                    // Lock is held by another agent — conflict
+                    logger.warn(`[FILE_LOCK] CONFLICT: ${agentName} cannot write ${filePath} — locked by ${lockData.agent}`);
+                    AtabeyStorage.saveLog({
+                        agent: agentName,
+                        action: "FILE_LOCK_CONFLICT",
+                        trace_id: AtabeyStorage.getMetadata("traceId") || "N/A",
+                        status: "BLOCKED",
+                        summary: `File ${filePath} is locked by ${lockData.agent}. Waiting for release.`
+                    });
+                    return false;
+                }
+            }
+            catch {
+                // Corrupted lock file — remove and retry
+                fs.unlinkSync(lockFile);
+            }
+        }
+        // Acquire lock
+        fs.writeFileSync(lockFile, JSON.stringify({
+            agent: agentName,
+            file: filePath,
+            acquiredAt: new Date().toISOString(),
+            traceId: AtabeyStorage.getMetadata("traceId") || "N/A"
+        }, null, 2));
+        logger.debug(`[FILE_LOCK] ${agentName} acquired lock on ${filePath}`);
+        return true;
+    }
+    /**
+     * Releases a lock held by an agent.
+     * Only the lock-owning agent can release (others get warning).
+     */
+    static release(agentName, filePath) {
+        const lockFile = FileLock.getLockPath(filePath);
+        if (!fs.existsSync(lockFile)) {
+            return true; // No lock to release
+        }
+        try {
+            const lockData = JSON.parse(fs.readFileSync(lockFile, "utf8"));
+            if (lockData.agent !== agentName) {
+                logger.warn(`[FILE_LOCK] ${agentName} tried to release lock held by ${lockData.agent} on ${filePath}`);
+                return false;
+            }
+            fs.unlinkSync(lockFile);
+            logger.debug(`[FILE_LOCK] ${agentName} released lock on ${filePath}`);
+            return true;
+        }
+        catch {
+            // Corrupted lock file — just remove it
+            try {
+                fs.unlinkSync(lockFile);
+            }
+            catch { /* ignore */ }
+            return true;
+        }
+    }
+    /**
+     * Checks if a file is currently locked.
+     * Returns the locking agent name or null.
+     */
+    static isLocked(filePath) {
+        const lockFile = FileLock.getLockPath(filePath);
+        if (!fs.existsSync(lockFile))
+            return null;
+        try {
+            const lockData = JSON.parse(fs.readFileSync(lockFile, "utf8"));
+            // Check for stale lock
+            const lockAge = Date.now() - new Date(lockData.acquiredAt).getTime();
+            if (lockAge > FileLock.STALE_TIMEOUT_MS) {
+                fs.unlinkSync(lockFile);
+                return null;
+            }
+            return lockData.agent;
+        }
+        catch {
+            try {
+                fs.unlinkSync(lockFile);
+            }
+            catch { /* ignore */ }
+            return null;
+        }
+    }
+    /**
+     * Lists all currently active locks.
+     */
+    static listLocks() {
+        const locksDir = path.join(process.cwd(), FileLock.LOCKS_DIR);
+        if (!fs.existsSync(locksDir))
+            return [];
+        const locks = [];
+        const walkDir = (dir) => {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walkDir(fullPath);
+                }
+                else if (entry.name.endsWith(".lock")) {
+                    try {
+                        const data = JSON.parse(fs.readFileSync(fullPath, "utf8"));
+                        const lockAge = Date.now() - new Date(data.acquiredAt).getTime();
+                        if (lockAge <= FileLock.STALE_TIMEOUT_MS) {
+                            locks.push(data);
+                        }
+                        else {
+                            fs.unlinkSync(fullPath); // Clean stale
+                        }
+                    }
+                    catch {
+                        try {
+                            fs.unlinkSync(fullPath);
+                        }
+                        catch { /* ignore */ }
+                    }
+                }
+            }
+        };
+        walkDir(locksDir);
+        return locks;
+    }
+    static getLockPath(filePath) {
+        // Convert absolute/relative path to lock file path
+        const relativePath = path.relative(process.cwd(), filePath).replace(/^\.\.\//, "");
+        return path.join(process.cwd(), FileLock.LOCKS_DIR, `${relativePath}.lock`);
+    }
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/src/modules/engines/file-lock.js.map

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

package/dist/src/modules/engines/phase-engine.d.ts

@@ -0,0 +1,82 @@
+/**
+ * [ENGINE] Phase Engine — State Machine for Development Lifecycle
+ *
+ * Implements the PHASE_0 → PHASE_4 state machine from ATABEY.md.
+ * Prevents phase skipping and enforces rollback when contracts break.
+ *
+ * Phases:
+ *   PHASE_0 (Discovery & Setup)     → Requirements analysis, docs validation
+ *   PHASE_1 (Architecture & Contracts) → Data models, API schemas, types
+ *   PHASE_2 (Core Development)      → Feature implementation
+ *   PHASE_3 (Integration & Testing) → System integration, QA
+ *   PHASE_4 (Optimization & Deployment) → Performance audit, deploy
+ *
+ * Rollback:
+ *   If contracts break during PHASE_2+ → auto rollback to PHASE_1
+ */
+export type Phase = "PHASE_0" | "PHASE_1" | "PHASE_2" | "PHASE_3" | "PHASE_4" | "ROLLBACK_PHASE_1";
+export interface PhaseTransition {
+    from: Phase;
+    to: Phase;
+    timestamp: string;
+    reason: string;
+    triggeredBy: string;
+}
+export interface PhaseRequirements {
+    phase: Phase;
+    name: string;
+    allowedWork: string[];
+    successCriteria: string[];
+    prohibitedWork: string[];
+}
+/**
+ * Phase Engine — manages the development lifecycle state machine.
+ * Stored in Storage metadata under "phase" key.
+ * Transition history stored in `.atabey/logs/phase-transitions.json`.
+ */
+export declare class PhaseEngine {
+    private static readonly VALID_TRANSITIONS;
+    private static readonly PHASE_DEFINITIONS;
+    /**
+     * Returns the current phase from storage.
+     */
+    static getCurrentPhase(): Phase;
+    /**
+     * Attempts to transition to a new phase.
+     * Validates that the transition is allowed by the state machine.
+     */
+    static transitionTo(targetPhase: Phase, reason: string, triggeredBy: string): Promise<{
+        success: boolean;
+        from: Phase;
+        to: Phase;
+        error?: string;
+    }>;
+    /**
+     * Checks if a given work type is allowed in the current phase.
+     */
+    static isWorkAllowed(work: string): boolean;
+    /**
+     * Returns the requirements for the current phase.
+     */
+    static getCurrentPhaseRequirements(): PhaseRequirements;
+    /**
+     * Checks if all success criteria for the current phase are met.
+     */
+    static checkPhaseCompletion(): Promise<{
+        complete: boolean;
+        missingCriteria: string[];
+    }>;
+    /**
+     * Marks a success criterion as completed.
+     */
+    static markCriteriaMet(criteria: string, agent: string): Promise<void>;
+    /**
+     * Detects if contracts are broken and auto-triggers rollback.
+     * Called by ContractEngine when contract_hash changes unexpectedly.
+     */
+    static detectBrokenContracts(triggeredBy: string): Promise<void>;
+    /**
+     * Notifies all agents to switch to WAITING state during rollback.
+     */
+    private static notifyAgentsOfRollback;
+}

package/dist/src/modules/engines/phase-engine.js

@@ -0,0 +1,211 @@
+/**
+ * [ENGINE] Phase Engine — State Machine for Development Lifecycle
+ *
+ * Implements the PHASE_0 → PHASE_4 state machine from ATABEY.md.
+ * Prevents phase skipping and enforces rollback when contracts break.
+ *
+ * Phases:
+ *   PHASE_0 (Discovery & Setup)     → Requirements analysis, docs validation
+ *   PHASE_1 (Architecture & Contracts) → Data models, API schemas, types
+ *   PHASE_2 (Core Development)      → Feature implementation
+ *   PHASE_3 (Integration & Testing) → System integration, QA
+ *   PHASE_4 (Optimization & Deployment) → Performance audit, deploy
+ *
+ * Rollback:
+ *   If contracts break during PHASE_2+ → auto rollback to PHASE_1
+ */
+import { logger } from "../../shared/logger.js";
+import { AtabeyStorage } from "../../shared/storage.js";
+/**
+ * Phase Engine — manages the development lifecycle state machine.
+ * Stored in Storage metadata under "phase" key.
+ * Transition history stored in `.atabey/logs/phase-transitions.json`.
+ */
+export class PhaseEngine {
+    static VALID_TRANSITIONS = {
+        "PHASE_0": ["PHASE_1"],
+        "PHASE_1": ["PHASE_2", "ROLLBACK_PHASE_1"],
+        "PHASE_2": ["PHASE_3", "ROLLBACK_PHASE_1"],
+        "PHASE_3": ["PHASE_4", "ROLLBACK_PHASE_1"],
+        "PHASE_4": ["PHASE_0"], // Release → restart cycle
+        "ROLLBACK_PHASE_1": ["PHASE_1"], // Rollback → fix → re-enter PHASE_1
+    };
+    static PHASE_DEFINITIONS = {
+        "PHASE_0": {
+            phase: "PHASE_0",
+            name: "Discovery & Setup",
+            allowedWork: ["Requirement analysis", "Documentation validation", "Environment setup", "Scaffolding"],
+            successCriteria: ["docs/README.md validated", "Technology stack confirmed", "Target audience identified"],
+            prohibitedWork: ["Any code implementation", "Database migrations", "API development"],
+        },
+        "PHASE_1": {
+            phase: "PHASE_1",
+            name: "Architecture & Contracts",
+            allowedWork: ["Type definitions", "API schema design", "Interface design", "Contract versioning"],
+            successCriteria: ["contract.version.json created", "All shared types defined", "Frontend + Backend approve schemas"],
+            prohibitedWork: ["Business logic implementation", "Database queries", "UI components"],
+        },
+        "PHASE_2": {
+            phase: "PHASE_2",
+            name: "Core Development",
+            allowedWork: ["Feature implementation", "Business logic", "API endpoints", "UI components", "Tests"],
+            successCriteria: ["All features implemented", "Tests passing", "Contract hash verified"],
+            prohibitedWork: ["Production deployment", "Schema changes without rollback"],
+        },
+        "PHASE_3": {
+            phase: "PHASE_3",
+            name: "Integration & Testing",
+            allowedWork: ["System integration", "End-to-end testing", "Performance testing", "Security audit"],
+            successCriteria: ["All integration tests pass", "No critical bugs", "Security scan clean"],
+            prohibitedWork: ["New features", "Schema changes"],
+        },
+        "PHASE_4": {
+            phase: "PHASE_4",
+            name: "Optimization & Deployment",
+            allowedWork: ["Performance optimization", "Deployment", "Post-release monitoring"],
+            successCriteria: ["Deployment successful", "Health checks passing", "Rollback plan ready"],
+            prohibitedWork: ["New features", "Schema changes"],
+        },
+        "ROLLBACK_PHASE_1": {
+            phase: "ROLLBACK_PHASE_1",
+            name: "Contract Rollback",
+            allowedWork: ["Contract repair", "Type definition fixes", "Schema corrections"],
+            successCriteria: ["Contracts fixed", "contract_hash recalculated"],
+            prohibitedWork: ["New features", "Deployment"],
+        },
+    };
+    /**
+     * Returns the current phase from storage.
+     */
+    static getCurrentPhase() {
+        const phase = AtabeyStorage.getMetadata("phase");
+        return phase || "PHASE_0";
+    }
+    /**
+     * Attempts to transition to a new phase.
+     * Validates that the transition is allowed by the state machine.
+     */
+    static async transitionTo(targetPhase, reason, triggeredBy) {
+        const currentPhase = PhaseEngine.getCurrentPhase();
+        const allowedTransitions = PhaseEngine.VALID_TRANSITIONS[currentPhase];
+        if (!allowedTransitions || !allowedTransitions.includes(targetPhase)) {
+            const errorMsg = `Phase transition ${currentPhase} → ${targetPhase} is NOT ALLOWED. Allowed: ${allowedTransitions?.join(", ") || "none"}`;
+            logger.warn(`[PHASE] ${errorMsg}`);
+            AtabeyStorage.saveLog({
+                agent: triggeredBy,
+                action: "PHASE_TRANSITION_BLOCKED",
+                trace_id: AtabeyStorage.getMetadata("traceId") || "N/A",
+                status: "FAILED",
+                summary: errorMsg
+            });
+            return {
+                success: false,
+                from: currentPhase,
+                to: targetPhase,
+                error: errorMsg,
+            };
+        }
+        // Execute transition
+        AtabeyStorage.setMetadata("phase", targetPhase);
+        const transition = {
+            from: currentPhase,
+            to: targetPhase,
+            timestamp: new Date().toISOString(),
+            reason,
+            triggeredBy,
+        };
+        // Log transition
+        AtabeyStorage.saveLog({
+            agent: triggeredBy,
+            action: "PHASE_TRANSITION",
+            trace_id: AtabeyStorage.getMetadata("traceId") || "N/A",
+            status: "SUCCESS",
+            summary: `${currentPhase} → ${targetPhase}: ${reason}`
+        });
+        logger.info(`[PHASE] ${currentPhase} → ${targetPhase} (by ${triggeredBy}): ${reason}`);
+        // If entering ROLLBACK, notify all agents to switch to WAITING
+        if (targetPhase === "ROLLBACK_PHASE_1") {
+            await PhaseEngine.notifyAgentsOfRollback();
+        }
+        return {
+            success: true,
+            from: currentPhase,
+            to: targetPhase,
+        };
+    }
+    /**
+     * Checks if a given work type is allowed in the current phase.
+     */
+    static isWorkAllowed(work) {
+        const currentPhase = PhaseEngine.getCurrentPhase();
+        const phaseDef = PhaseEngine.PHASE_DEFINITIONS[currentPhase];
+        if (!phaseDef)
+            return false;
+        const workLower = work.toLowerCase();
+        return phaseDef.allowedWork.some(allowed => workLower.includes(allowed.toLowerCase()));
+    }
+    /**
+     * Returns the requirements for the current phase.
+     */
+    static getCurrentPhaseRequirements() {
+        const currentPhase = PhaseEngine.getCurrentPhase();
+        return PhaseEngine.PHASE_DEFINITIONS[currentPhase] || PhaseEngine.PHASE_DEFINITIONS["PHASE_0"];
+    }
+    /**
+     * Checks if all success criteria for the current phase are met.
+     */
+    static async checkPhaseCompletion() {
+        const phaseDef = PhaseEngine.getCurrentPhaseRequirements();
+        const missingCriteria = [];
+        for (const criteria of phaseDef.successCriteria) {
+            // Check if the criteria has been logged as completed
+            const logs = AtabeyStorage.getLogs();
+            const isCompleted = logs.some(l => l.action === "PHASE_CRITERIA_MET" &&
+                l.summary.includes(criteria));
+            if (!isCompleted) {
+                missingCriteria.push(criteria);
+            }
+        }
+        return {
+            complete: missingCriteria.length === 0,
+            missingCriteria,
+        };
+    }
+    /**
+     * Marks a success criterion as completed.
+     */
+    static async markCriteriaMet(criteria, agent) {
+        AtabeyStorage.saveLog({
+            agent,
+            action: "PHASE_CRITERIA_MET",
+            trace_id: AtabeyStorage.getMetadata("traceId") || "N/A",
+            status: "SUCCESS",
+            summary: criteria
+        });
+        logger.info(`[PHASE] Criteria met: ${criteria} (by ${agent})`);
+    }
+    /**
+     * Detects if contracts are broken and auto-triggers rollback.
+     * Called by ContractEngine when contract_hash changes unexpectedly.
+     */
+    static async detectBrokenContracts(triggeredBy) {
+        const currentPhase = PhaseEngine.getCurrentPhase();
+        if (currentPhase === "PHASE_2" || currentPhase === "PHASE_3" || currentPhase === "PHASE_4") {
+            logger.warn(`[PHASE] Broken contracts detected in ${currentPhase}. Auto-rolling back to PHASE_1.`);
+            await PhaseEngine.transitionTo("ROLLBACK_PHASE_1", "Contract hash mismatch detected — automatic rollback", triggeredBy);
+        }
+    }
+    /**
+     * Notifies all agents to switch to WAITING state during rollback.
+     */
+    static async notifyAgentsOfRollback() {
+        const agents = AtabeyStorage.getAllAgents();
+        for (const agent of agents) {
+            if (agent.state === "EXECUTING" || agent.state === "COMPLETED") {
+                AtabeyStorage.updateAgentStatus(agent.name, "WAITING", `Contract rollback in progress — phase reset to PHASE_1`);
+            }
+        }
+        logger.info("[PHASE] All agents notified of rollback. Waiting for contract fixes.");
+    }
+}
+//# sourceMappingURL=phase-engine.js.map

package/dist/src/modules/engines/phase-engine.js.map

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

package/dist/src/modules/engines/policy-engine.d.ts

@@ -0,0 +1,63 @@
+/**
+ * [ENGINE] Policy Engine — Language, CLI, Dashboard & Parallel Rules
+ *
+ * Combines remaining vision items:
+ * 5. API Versioning Strategy — URL versioning enforcement
+ * 7. Dashboard Live Features — WebSocket ApprovalCenter, CompliancePanel
+ * 8. CLI Command Map — .atabey/cli-commands.json management
+ * 9. Language Policy Enforcer — English-only comments/variables
+ * 10. Parallel Execution Rules — dependency lock, ownership, commit logging
+ */
+export interface CliCommandEntry {
+    command: string;
+    agent: string;
+    description: string;
+    outputFormat?: "json" | "text";
+}
+export interface LanguageViolation {
+    file: string;
+    line: number;
+    type: "turkish_comment" | "non_english_variable" | "ui_text_not_english";
+    content: string;
+}
+/**
+ * Policy Engine — enforces language policy, manages CLI command map,
+ * provides dashboard live data, and enforces parallel execution rules.
+ */
+export declare class PolicyEngine {
+    /**
+     * Validates that API endpoints use versioned paths (/api/v{N}/...).
+     */
+    static validateApiVersioning(filePath: string, content: string): string[];
+    /**
+     * Returns dashboard live data for WebSocket broadcast.
+     */
+    static getDashboardData(): Record<string, unknown>;
+    /**
+     * Gets the CLI command map from .atabey/cli-commands.json.
+     */
+    static getCliCommands(): CliCommandEntry[];
+    /**
+     * Saves CLI command map.
+     */
+    static saveCliCommand(command: CliCommandEntry): void;
+    private static getDefaultCommands;
+    /**
+     * Scans files for language policy violations.
+     * Rules: comments in English, variable/function names in English, UI text in English.
+     */
+    static scanLanguagePolicy(filePath: string, content: string): LanguageViolation[];
+    /**
+     * Checks implicit dependency lock — if an agent's required output
+     * is not ready, the dependent agent switches to WAITING state.
+     */
+    static checkImplicitDependency(agentName: string, requiredAgent: string): boolean;
+    /**
+     * Enforces file ownership — an agent cannot modify files outside its scope.
+     */
+    static enforceOwnership(agentName: string, filePath: string): boolean;
+    /**
+     * Logs commit-level information for traceability.
+     */
+    static logCommit(agentName: string, message: string, traceId: string): void;
+}