atabey 0.0.11 → 0.0.13

package/framework-mcp/dist/framework-mcp/src/utils/compliance.js

@@ -0,0 +1,292 @@
+import ts from "typescript";
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "./security.js";
+/**
+ * Enterprise Compliance Guardrail
+ * Checks content against corporate standards using AST analysis before allowing file mutations.
+ */
+export function verifyCorporateCompliance(content, filePath) {
+    // Skip compliance checks for non-source files or specific ignored files
+    if (filePath.endsWith(".json") || filePath.endsWith(".md") || filePath.endsWith(".env.example")) {
+        return;
+    }
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+    const errors = [];
+    /**
+     * Recursive AST Visitor
+     */
+    function visit(node) {
+        // 1. Zero Console Policy
+        if (ts.isPropertyAccessExpression(node)) {
+            const expression = node.expression;
+            const name = node.name.text;
+            if (ts.isIdentifier(expression) && expression.text === "console") {
+                if (["log", "warn", "error"].includes(name)) {
+                    // Check if file is exempt
+                    if (!filePath.includes("logger.ts") && !filePath.includes("check.ts") && !filePath.includes("cli.ts") && !filePath.includes("compliance.ts")) {
+                        errors.push(`[ERROR] Corporate Compliance Breach: 'console.${name}' usage is forbidden at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}.`);
+                    }
+                }
+            }
+            // 2. Unsafe DOM Policy (Avoid XSS)
+            if (name === "innerHTML" || name === "outerHTML") {
+                errors.push(`[ERROR] Corporate Compliance Breach: Unsafe usage of '${name}' detected at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}. Avoid XSS.`);
+            }
+        }
+        // 3. No Explicit Any Policy
+        if (ts.isTypeReferenceNode(node)) {
+            if (ts.isIdentifier(node.typeName) && node.typeName.text === "any") {
+                if (!filePath.includes("definitions.ts") && !filePath.includes("types.ts")) {
+                    errors.push(`[ERROR] Corporate Compliance Breach: 'any' type is forbidden at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}.`);
+                }
+            }
+        }
+        // 4. Zero UI Library Policy
+        if (ts.isImportDeclaration(node)) {
+            const moduleSpecifier = node.moduleSpecifier;
+            if (ts.isStringLiteral(moduleSpecifier)) {
+                const forbiddenLibs = ["@chakra-ui", "mui", "@shadcn", "antd", "bootstrap"];
+                const lib = forbiddenLibs.find(l => moduleSpecifier.text.includes(l));
+                if (lib) {
+                    errors.push(`[ERROR] Corporate Compliance Breach: External UI library '${lib}' usage is FORBIDDEN at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}. Build atomic components manually instead.`);
+                }
+                // 5. Secure CLI Policy (No direct child_process)
+                if (moduleSpecifier.text === "child_process") {
+                    errors.push(`[ERROR] Corporate Compliance Breach: Direct 'child_process' usage is forbidden at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}. Use secure framework APIs.`);
+                }
+            }
+        }
+        // Handle 'any' as a keyword type
+        if (node.kind === ts.SyntaxKind.AnyKeyword) {
+            if (!filePath.includes("definitions.ts") && !filePath.includes("types.ts")) {
+                errors.push(`[ERROR] Corporate Compliance Breach: 'any' keyword is forbidden at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}.`);
+            }
+        }
+        // 6. SQL Safety Policy (Kysely only)
+        if (ts.isTaggedTemplateExpression(node)) {
+            const tag = node.tag;
+            if (ts.isIdentifier(tag) && tag.text === "sql") {
+                errors.push(`[ERROR] Corporate Compliance Breach: Raw SQL tagged template detected at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}. Use Kysely query builder.`);
+            }
+        }
+        // 7. Atomic FS Policy (No raw fs mutations)
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+            const prop = node.expression;
+            if (ts.isIdentifier(prop.expression) && prop.expression.text === "fs") {
+                if (["writeFileSync", "appendFileSync"].includes(prop.name.text)) {
+                    // Lock files are exempt
+                    const args = node.arguments;
+                    const firstArgText = args.length > 0 ? args[0].getText(sourceFile).toLowerCase() : "";
+                    if (!firstArgText.includes("lock")) {
+                        errors.push(`[ERROR] Corporate Compliance Breach: Raw 'fs.${prop.name.text}' mutation detected at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}. Use atomic utilities instead.`);
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    // 8. Hardcoded Secrets & PII Guard
+    const piiKeywords = [
+        { regex: /API_KEY\s*=\s*['"][^'"]+['"]/i, msg: "Hardcoded API Key" },
+        { regex: /SECRET\s*=\s*['"][^'"]+['"]/i, msg: "Hardcoded Secret" },
+        { regex: /PASSWORD\s*=\s*['"][^'"]+['"]/i, msg: "Hardcoded Password" },
+        { regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/, msg: "PII Detected: Email Address" },
+        { regex: /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/, msg: "PII Detected: Credit Card Pattern" }
+    ];
+    for (const { regex, msg } of piiKeywords) {
+        if (regex.test(content)) {
+            if (msg.includes("Email") && (filePath.endsWith("README.md") || filePath.endsWith("package.json") || filePath.includes("CONTRIBUTING"))) {
+                continue;
+            }
+            errors.push(`[ERROR] Corporate Compliance Breach: ${msg} detected.`);
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(errors.join("\n"));
+    }
+}
+/**
+ * Enterprise Compliance Scanner
+ * Scans a directory for compliance issues.
+ */
+export function scanProjectCompliance(targetDir = "src") {
+    const issues = [];
+    if (!fs.existsSync(targetDir))
+        return [];
+    const files = getAllFiles(targetDir);
+    for (const file of files) {
+        // Skip exempt files
+        if (file.includes("compliance") || file.includes("definitions") || file.includes("logger") || file.includes("cli/index.ts"))
+            continue;
+        const content = fs.readFileSync(file, "utf8");
+        try {
+            verifyCorporateCompliance(content, file);
+        }
+        catch (err) {
+            const errorLines = err.message.split("\n");
+            for (const errorLine of errorLines) {
+                const match = errorLine.match(/line (\d+)\./);
+                const line = match ? parseInt(match[1]) : 0;
+                issues.push({ file, line, rule: errorLine });
+            }
+        }
+        // Technical Debt (TODO/FIXME)
+        const lines = content.split("\n");
+        lines.forEach((line, index) => {
+            if (/\b(TODO|FIXME)\b/i.test(line)) {
+                issues.push({ file, line: index + 1, rule: "Unresolved Technical Debt (TODO/FIXME) found" });
+            }
+        });
+    }
+    return issues;
+}
+function getAllFiles(dirPath, arrayOfFiles = []) {
+    const files = fs.readdirSync(dirPath);
+    files.forEach((file) => {
+        const fullPath = path.join(dirPath, file);
+        if (fs.statSync(fullPath).isDirectory()) {
+            if (file !== "node_modules" && !file.startsWith(".")) {
+                arrayOfFiles = getAllFiles(fullPath, arrayOfFiles);
+            }
+        }
+        else {
+            const ext = path.extname(fullPath);
+            if ([".ts", ".tsx", ".js", ".jsx"].includes(ext)) {
+                arrayOfFiles.push(fullPath);
+            }
+        }
+    });
+    return arrayOfFiles;
+}
+export function isHighRiskOperation(content, filePath) {
+    const fileName = filePath.toLowerCase();
+    // 1. Database Deletions
+    if (fileName.endsWith(".sql") || fileName.endsWith(".ts") || fileName.endsWith(".js") || fileName.endsWith(".go")) {
+        const dropRegex = /\b(DROP\s+(DATABASE|TABLE|SCHEMA|VIEW|INDEX)|TRUNCATE\s+TABLE)\b/i;
+        if (dropRegex.test(content)) {
+            return { isRisk: true, reason: "Database structural deletion detected (DROP/TRUNCATE)" };
+        }
+    }
+    // 2. Package Updates
+    if (fileName.endsWith("package.json")) {
+        return { isRisk: true, reason: "Dependency/package update operation detected" };
+    }
+    // 3. Deployment Scripts
+    if (fileName.includes("deploy") ||
+        fileName.includes("dockerfile") ||
+        fileName.includes("docker-compose") ||
+        fileName.includes("k8s") ||
+        fileName.includes("github/workflows")) {
+        return { isRisk: true, reason: "Infrastructure or deployment script mutation detected" };
+    }
+    return { isRisk: false };
+}
+export async function verifyRiskAndAwaitApproval(projectRoot, content, filePath) {
+    const assessment = isHighRiskOperation(content, filePath);
+    if (!assessment.isRisk) {
+        return;
+    }
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const absoluteFrameworkPath = path.isAbsolute(frameworkDir)
+        ? frameworkDir
+        : path.resolve(projectRoot, frameworkDir);
+    const statusPath = path.join(absoluteFrameworkPath, "memory", "status.json");
+    const statePath = path.join(absoluteFrameworkPath, "memory", "state.json");
+    const messagesDir = path.join(absoluteFrameworkPath, "messages");
+    const managerMsgPath = path.join(messagesDir, "manager.json");
+    let activeAgent = null;
+    let traceId = "UNKNOWN";
+    if (fs.existsSync(statePath)) {
+        try {
+            const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+            if (state && state.traceId)
+                traceId = state.traceId;
+        }
+        catch { /* ignore */ }
+    }
+    let statusData = {};
+    if (fs.existsSync(statusPath)) {
+        try {
+            statusData = JSON.parse(fs.readFileSync(statusPath, "utf8"));
+            for (const [agentName, info] of Object.entries(statusData)) {
+                if (info.state === "EXECUTING") {
+                    activeAgent = agentName.startsWith("@") ? agentName : `@${agentName}`;
+                    break;
+                }
+            }
+        }
+        catch { /* ignore */ }
+    }
+    if (!activeAgent)
+        throw new Error(`Security Exception: High-risk operation blocked. ${assessment.reason}.`);
+    const statusKey = activeAgent.replace("@", "");
+    const originalTask = statusData[statusKey]?.task || "Executing task";
+    statusData[statusKey] = {
+        state: "WAITING_FOR_APPROVAL",
+        task: `[PAUSED] Waiting for approval: ${assessment.reason} on ${filePath}`
+    };
+    try {
+        fs.writeFileSync(statusPath, JSON.stringify(statusData, null, 2));
+    }
+    catch { /* ignore */ }
+    if (!fs.existsSync(messagesDir))
+        fs.mkdirSync(messagesDir, { recursive: true });
+    const alertMsg = {
+        timestamp: new Date().toISOString(),
+        from: activeAgent,
+        to: "@manager",
+        category: "ALERT",
+        content: `High-risk operation: ${assessment.reason} on ${filePath}`,
+        traceId: traceId,
+        status: "PENDING",
+        priority: "HIGH",
+        requiresApproval: true,
+        action: `MUTATION:${filePath}`
+    };
+    try {
+        fs.appendFileSync(managerMsgPath, JSON.stringify(alertMsg) + "\n");
+    }
+    catch (err) {
+        statusData[statusKey] = { state: "EXECUTING", task: originalTask };
+        fs.writeFileSync(statusPath, JSON.stringify(statusData, null, 2));
+        throw new Error("Security Exception: Failed to queue approval request.", { cause: err });
+    }
+    const pollIntervalMs = 500;
+    const timeoutMs = 60000;
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+        if (fs.existsSync(managerMsgPath)) {
+            try {
+                const lines = fs.readFileSync(managerMsgPath, "utf8").trim().split("\n");
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    const parsed = JSON.parse(line);
+                    if (parsed.traceId === traceId && parsed.category === "ALERT" && parsed.action === `MUTATION:${filePath}`) {
+                        if (parsed.status === "APPROVED") {
+                            statusData[statusKey] = { state: "EXECUTING", task: originalTask };
+                            fs.writeFileSync(statusPath, JSON.stringify(statusData, null, 2));
+                            return;
+                        }
+                        else if (parsed.status === "PROCESSED" || parsed.status === "DENIED") {
+                            throw new Error("Security Exception: High-risk operation was explicitly DENIED.");
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                if (err.message.includes("explicitly DENIED"))
+                    throw err;
+            }
+        }
+    }
+    statusData[statusKey] = { state: "EXECUTING", task: originalTask };
+    try {
+        fs.writeFileSync(statusPath, JSON.stringify(statusData, null, 2));
+    }
+    catch { /* ignore */ }
+    throw new Error("Security Exception: High-risk operation timed out waiting for approval.");
+}

package/framework-mcp/dist/framework-mcp/src/utils/errors.js

@@ -0,0 +1,68 @@
+/**
+ * Enterprise Base Error class for the Agent Atabey Framework.
+ */
+export class AtabeyBaseError extends Error {
+    code;
+    timestamp;
+    details;
+    solution;
+    constructor(message, code = "ATABEY_INTERNAL_ERROR", details, solution) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.timestamp = new Date();
+        this.details = details;
+        this.solution = solution;
+        // Ensure proper prototype chain and capture stack trace
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Converts the error into a structured JSON log format.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            timestamp: this.timestamp.toISOString(),
+            details: this.details,
+            solution: this.solution,
+            stack: this.stack,
+        };
+    }
+}
+/**
+ * Thrown when configuration loading or validation fails.
+ */
+export class ConfigurationError extends AtabeyBaseError {
+    constructor(message, details, solution) {
+        super(message, "CONFIGURATION_ERROR", details, solution);
+    }
+}
+/**
+ * Thrown when data schema or payload validation fails.
+ */
+export class ValidationError extends AtabeyBaseError {
+    constructor(message, details, solution) {
+        super(message, "VALIDATION_ERROR", details, solution);
+    }
+}
+/**
+ * Thrown when adapter initialization or execution fails.
+ */
+export class AdapterError extends AtabeyBaseError {
+    constructor(message, adapterId, details, solution) {
+        super(`Adapter '${adapterId}' failure: ${message}`, "ADAPTER_ERROR", details, solution);
+    }
+}
+/**
+ * Thrown when orchestration or agent communication fails.
+ */
+export class OrchestrationError extends AtabeyBaseError {
+    constructor(message, details, solution) {
+        super(message, "ORCHESTRATION_ERROR", details, solution);
+    }
+}

package/framework-mcp/dist/framework-mcp/src/utils/fs.js

@@ -0,0 +1,47 @@
+import fs from "fs";
+import path from "path";
+/**
+ * Ensures directory existence.
+ */
+export function ensureDir(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+/**
+ * Atomically writes a text file.
+ * Uses a temp file + rename pattern to prevent partial writes.
+ * Compatible with src/shared/fs.ts writeTextFile API.
+ */
+export function writeTextFile(filePath, content) {
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+    const tempPath = `${filePath}.${Math.random().toString(36).slice(2, 9)}.tmp`;
+    const finalContent = content.endsWith("\n") ? content : `${content}\n`;
+    try {
+        fs.writeFileSync(tempPath, finalContent, "utf8");
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (err) {
+        if (fs.existsSync(tempPath)) {
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch { /* ignore */ }
+        }
+        throw err;
+    }
+}
+/** @deprecated Use writeTextFile instead */
+export const writeTextFileAtomic = writeTextFile;
+/**
+ * Appends content to a file. Creates parent directories if missing.
+ * Compatible with src/shared/fs.ts appendFile API.
+ */
+export function appendFile(filePath, content) {
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+    fs.appendFileSync(filePath, content, "utf8");
+}
+/** @deprecated Use appendFile instead */
+export const appendFileSafe = appendFile;

package/framework-mcp/dist/framework-mcp/src/utils/memory.js

@@ -0,0 +1,74 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+const CWD = process.cwd();
+const HOME = os.homedir();
+const FRAMEWORK = {
+    CORE_DIR: ".atabey",
+};
+const FRAMEWORK_DIR_CANDIDATES = [
+    ".atabey",
+    ".agents",
+    ".claude",
+    ".gemini",
+    ".grok",
+    ".cursor",
+];
+const MCP = {
+    TEST_DIR_ENV: "ATABEY_TEST_DIR",
+};
+function findFrameworkDir(basePath) {
+    try {
+        const pkgPath = path.join(basePath, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            if (pkg.atabey && typeof pkg.atabey.frameworkDir === "string") {
+                const customDir = path.join(basePath, pkg.atabey.frameworkDir);
+                if (fs.existsSync(customDir))
+                    return customDir;
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+export function isFrameworkDevelopmentRepo() {
+    try {
+        const pkgPath = path.join(CWD, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            if (pkg.name === "atabey") {
+                return true;
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return false;
+}
+export function getConfigDir() {
+    const localDir = findFrameworkDir(CWD);
+    if (localDir)
+        return localDir;
+    // Check for standard local directories if package.json doesn't specify
+    const localCandidates = [...FRAMEWORK_DIR_CANDIDATES, ".agent"];
+    for (const cand of localCandidates) {
+        const p = path.join(CWD, cand);
+        if (fs.existsSync(p))
+            return p;
+    }
+    // In dev repo, don't fall back to global dir. Point to local default.
+    if (isFrameworkDevelopmentRepo()) {
+        return path.join(CWD, FRAMEWORK.CORE_DIR);
+    }
+    return path.join(HOME, FRAMEWORK.CORE_DIR);
+}
+export function getFrameworkDir() {
+    const testDir = process.env[MCP.TEST_DIR_ENV];
+    if (testDir)
+        return testDir;
+    return getConfigDir();
+}

package/framework-mcp/dist/framework-mcp/src/utils/metrics.js

@@ -0,0 +1,56 @@
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "./security.js";
+export const Metrics = {
+    /**
+     * Estimates tokens based on character count (rough heuristic: 1 token ~= 4 chars).
+     */
+    estimateTokens: (text) => {
+        return Math.ceil(text.length / 4);
+    },
+    /**
+     * Logs the token usage and action to the observability metrics file.
+     */
+    logUsage: (projectRoot, agent, action, tokens) => {
+        Metrics.saveMetric(projectRoot, {
+            timestamp: new Date().toISOString(),
+            agent,
+            action,
+            estimatedTokens: tokens
+        });
+    },
+    /**
+     * Logs an error occurrence to the observability metrics file.
+     */
+    logError: (projectRoot, agent, action, error) => {
+        Metrics.saveMetric(projectRoot, {
+            timestamp: new Date().toISOString(),
+            agent,
+            action: `ERROR: ${action}`,
+            estimatedTokens: 0,
+            error
+        });
+    },
+    /**
+     * Internal helper to save metric entries.
+     */
+    saveMetric: (projectRoot, entry) => {
+        const frameworkDir = resolveFrameworkDir(projectRoot);
+        const metricsPath = path.join(projectRoot, frameworkDir, "observability/metrics.json");
+        try {
+            const metricsDir = path.dirname(metricsPath);
+            if (!fs.existsSync(metricsDir))
+                fs.mkdirSync(metricsDir, { recursive: true });
+            let currentMetrics = [];
+            if (fs.existsSync(metricsPath)) {
+                currentMetrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+            }
+            currentMetrics.push(entry);
+            // Keep only last 100 entries to save space
+            if (currentMetrics.length > 100)
+                currentMetrics.shift();
+            fs.writeFileSync(metricsPath, JSON.stringify(currentMetrics, null, 2));
+        }
+        catch { /* ignore: metrics should not block the main process */ }
+    }
+};

package/framework-mcp/dist/framework-mcp/src/utils/permissions.js

@@ -0,0 +1,71 @@
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "./security.js";
+function globToRegex(glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const step1 = escaped.replace(/\*\*/g, "__DBL_STR__");
+    const step2 = step1.replace(/\*/g, "[^/]*");
+    const regexStr = "^" + step2.replace(/__DBL_STR__/g, ".*") + "$";
+    return new RegExp(regexStr);
+}
+/**
+ * Validates if the active agent has write permission for the target file.
+ * Automatically identifies the active agent by checking the status.json store
+ * for the agent in the "EXECUTING" state.
+ */
+export function verifyWritePermission(projectRoot, targetFilePath) {
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const absoluteFrameworkPath = path.isAbsolute(frameworkDir)
+        ? frameworkDir
+        : path.resolve(projectRoot, frameworkDir);
+    const matrixPath = path.join(absoluteFrameworkPath, "permission-matrix.json");
+    // If no permission matrix exists, skip enforcement (default allow)
+    if (!fs.existsSync(matrixPath)) {
+        return;
+    }
+    let matrix;
+    try {
+        matrix = JSON.parse(fs.readFileSync(matrixPath, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`Failed to parse permission-matrix.json: ${String(e)}`, { cause: e });
+    }
+    // Determine the active agent from status.json
+    const statusPath = path.join(absoluteFrameworkPath, "memory", "status.json");
+    let activeAgent = null;
+    if (fs.existsSync(statusPath)) {
+        try {
+            const status = JSON.parse(fs.readFileSync(statusPath, "utf8"));
+            // Find an agent that is currently in the EXECUTING state
+            for (const [agentName, info] of Object.entries(status)) {
+                const data = info;
+                if (data.state === "EXECUTING") {
+                    activeAgent = agentName.startsWith("@") ? agentName : `@${agentName}`;
+                    break;
+                }
+            }
+        }
+        catch (e) {
+            // Log warning but don't crash, default to allowing if status can't be parsed
+            process.stderr.write(`[Permissions] Warning: Failed to read status.json: ${String(e)}\n`);
+        }
+    }
+    // If no active executing agent is found, default to allowing
+    if (!activeAgent) {
+        return;
+    }
+    const agentRules = matrix[activeAgent];
+    // If no rules defined for the agent, default to allowing
+    if (!agentRules || !agentRules.write) {
+        return;
+    }
+    // Resolve target path relative to project root for glob matching
+    const relativeTargetPath = path.relative(projectRoot, path.resolve(projectRoot, targetFilePath));
+    const allowed = agentRules.write.some(glob => {
+        const regex = globToRegex(glob);
+        return regex.test(relativeTargetPath);
+    });
+    if (!allowed) {
+        throw new Error(`Permission Denied: Agent ${activeAgent} is not authorized to write to "${relativeTargetPath}". Matrix rules restrict writes to: [${agentRules.write.join(", ")}].`);
+    }
+}

package/framework-mcp/dist/framework-mcp/src/utils/security.js

@@ -0,0 +1,60 @@
+import path from "path";
+import fs from "fs";
+import { FRAMEWORK, MCP, UNIFIED_HUB_DIR } from "../constants.js"; // New import
+import os from "os"; // Need os.homedir()
+/**
+ * Validates and resolves a user-provided path to prevent path traversal attacks.
+ * Ensures the resolved path stays within the project root boundary.
+ */
+export function safePath(projectRoot, userPath) {
+    const resolved = path.resolve(projectRoot, userPath);
+    const normalizedRoot = path.resolve(projectRoot);
+    if (!resolved.startsWith(normalizedRoot + path.sep) && resolved !== normalizedRoot) {
+        throw new Error(`Access denied: path "${userPath}" escapes project root.`);
+    }
+    return resolved;
+}
+/**
+ * Resolves the active framework directory.
+ * Priority: ATABEY_TEST_DIR (env) -> package.json `atabey.frameworkDir` -> `.atabey` -> other adapter dirs -> global HOME.
+ */
+export function resolveFrameworkDir(projectRoot) {
+    // For test environments, use the explicitly set test directory.
+    const testDir = process.env[MCP.TEST_DIR_ENV];
+    if (testDir)
+        return testDir;
+    // 1. Authoritative source: read from package.json if present
+    try {
+        const pkgPath = path.join(projectRoot, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            const atabeyConfig = pkg["atabey"];
+            if (atabeyConfig && typeof atabeyConfig["frameworkDir"] === "string") {
+                // Ensure the path is relative if it's within the project, otherwise use as-is.
+                const resolvedDir = path.resolve(projectRoot, atabeyConfig["frameworkDir"]);
+                if (resolvedDir.startsWith(path.resolve(projectRoot))) {
+                    return path.relative(projectRoot, resolvedDir);
+                }
+                return atabeyConfig["frameworkDir"];
+            }
+        }
+    }
+    catch {
+        // ignore — fall through to filesystem scan
+    }
+    // 2. Filesystem scan in projectRoot for common framework directories
+    const localCandidates = [
+        FRAMEWORK.CORE_DIR, // .atabey
+        UNIFIED_HUB_DIR, // .agents
+        // Add other adapter specific directories if needed, or remove if unified is strictly enforced
+    ];
+    for (const candidate of localCandidates) {
+        const candidatePath = path.join(projectRoot, candidate);
+        if (fs.existsSync(candidatePath)) {
+            return candidate;
+        }
+    }
+    // 3. Fallback to global home directory.
+    const homeDir = os.homedir();
+    return path.join(homeDir, FRAMEWORK.CORE_DIR);
+}