atabey 0.0.7 → 0.0.8

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

@@ -0,0 +1,173 @@
+import fs from "fs";
+import path from "path";
+import ts from "typescript";
+/**
+ * Enterprise Compliance Scanner (AST-Based)
+ * Scans the project source code for governance and discipline violations.
+ */
+export function scanProjectCompliance(targetDir = "src") {
+    const issues = [];
+    if (!fs.existsSync(targetDir))
+        return [];
+    const files = getAllFiles(targetDir);
+    for (const file of files) {
+        // Absolute skip for critical framework and utility files to avoid self-flagging
+        if (file.includes("compliance") ||
+            file.includes("definitions") ||
+            file.includes("agents/registry") ||
+            file.includes("scaffold-ops.ts") ||
+            file.includes("logger") ||
+            file.includes("errors") ||
+            file.includes("shared/fs") ||
+            file.includes("commands/git") ||
+            file.includes("commands/lint") ||
+            file.includes("commands/script") ||
+            file.includes("commands/check") ||
+            file.includes("cli/index.ts") ||
+            file.includes("adapters/shared"))
+            continue;
+        const content = fs.readFileSync(file, "utf8");
+        // --- 1. AST-Based Analysis (For Language Rules) ---
+        const sourceFile = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true);
+        const visit = (node) => {
+            // Rule: No console.log allowed (excluding UI and warn/error helpers)
+            if (ts.isPropertyAccessExpression(node)) {
+                const expression = node.expression;
+                const name = node.name.text;
+                if (ts.isIdentifier(expression) && expression.text === "console" && name === "log") {
+                    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                    issues.push({ file, line: line + 1, rule: "No console.log allowed (Use logger instead)" });
+                }
+                // Rule: innerHTML / outerHTML check
+                if (name === "innerHTML" || name === "outerHTML") {
+                    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                    issues.push({ file, line: line + 1, rule: `Unsafe assignment/usage of '${name}' detected (Avoid XSS)` });
+                }
+            }
+            // Rule: No 'any' type usage
+            if (ts.isTypeReferenceNode(node)) {
+                if (ts.isIdentifier(node.typeName) && node.typeName.text === "any") {
+                    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                    issues.push({ file, line: line + 1, rule: "Usage of 'any' type is forbidden" });
+                }
+            }
+            if (node.kind === ts.SyntaxKind.AnyKeyword) {
+                const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                issues.push({ file, line: line + 1, rule: "Usage of 'any' keyword is forbidden" });
+            }
+            // Rule: Zero UI Library & child_process 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) {
+                        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                        issues.push({ file, line: line + 1, rule: `Forbidden UI library '${lib}' usage detected` });
+                    }
+                    if (moduleSpecifier.text === "child_process") {
+                        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                        issues.push({ file, line: line + 1, rule: "Direct child_process module usage is forbidden. Command execution must be managed through secure framework APIs." });
+                    }
+                }
+            }
+            // Rule: child_process dynamic usage & Raw SQL templates
+            if (ts.isCallExpression(node)) {
+                const expression = node.expression;
+                if (ts.isIdentifier(expression) && expression.text === "require") {
+                    const args = node.arguments;
+                    if (args.length > 0 && ts.isStringLiteral(args[0]) && args[0].text === "child_process") {
+                        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                        issues.push({ file, line: line + 1, rule: "Direct child_process module usage is forbidden. Command execution must be managed through secure framework APIs." });
+                    }
+                }
+            }
+            if (node.kind === ts.SyntaxKind.ImportKeyword) {
+                const parent = node.parent;
+                if (parent && ts.isCallExpression(parent)) {
+                    const args = parent.arguments;
+                    if (args.length > 0 && ts.isStringLiteral(args[0]) && args[0].text === "child_process") {
+                        const { line } = sourceFile.getLineAndCharacterOfPosition(parent.getStart());
+                        issues.push({ file, line: line + 1, rule: "Direct child_process module usage is forbidden. Command execution must be managed through secure framework APIs." });
+                    }
+                }
+            }
+            if (ts.isTaggedTemplateExpression(node)) {
+                const tag = node.tag;
+                if (ts.isIdentifier(tag) && tag.text === "sql") {
+                    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                    issues.push({ file, line: line + 1, rule: "Raw SQL tagged template detected. Use Kysely query builder instead." });
+                }
+            }
+            // Rule: Raw fs mutation check (Use atomic utilities)
+            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)) {
+                        // Skip if it's explicitly allowed (e.g. lock files)
+                        const args = node.arguments;
+                        let isLockFile = false;
+                        if (args.length > 0) {
+                            const firstArgText = args[0].getText(sourceFile).toLowerCase();
+                            if (firstArgText.includes("lock")) {
+                                isLockFile = true;
+                            }
+                        }
+                        if (!isLockFile) {
+                            const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                            issues.push({ file, line: line + 1, rule: "Use atomic utilities (writeTextFile) instead of raw fs mutations" });
+                        }
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        // --- 2. Pattern-Based Analysis (For Secrets & PII & Debt) ---
+        const lines = content.split("\n");
+        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" }
+        ];
+        lines.forEach((line, index) => {
+            const lineNum = index + 1;
+            const trimmedLine = line.trim();
+            if (trimmedLine.startsWith("//") || trimmedLine.startsWith("*"))
+                return;
+            // PII & Secret Guard
+            for (const { regex, msg } of piiKeywords) {
+                if (regex.test(line)) {
+                    // Allow emails in specific files
+                    if (msg.includes("Email") && (file.endsWith("README.md") || file.endsWith("package.json") || file.includes("CONTRIBUTING"))) {
+                        continue;
+                    }
+                    issues.push({ file, line: lineNum, rule: `Corporate Compliance Breach: ${msg}` });
+                }
+            }
+            // Technical Debt (TODO/FIXME)
+            if (/\b(TODO|FIXME)\b/i.test(line)) {
+                issues.push({ file, line: lineNum, 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()) {
+            arrayOfFiles = getAllFiles(fullPath, arrayOfFiles);
+        }
+        else {
+            const ext = path.extname(fullPath);
+            if ([".ts", ".tsx", ".js", ".jsx"].includes(ext)) {
+                arrayOfFiles.push(fullPath);
+            }
+        }
+    });
+    return arrayOfFiles;
+}

package/framework-mcp/dist/src/cli/utils/config-schema.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+/**
+ * Standard Color Palette Schema
+ */
+export const ColorPaletteSchema = z.object({
+    primary: z.string().regex(/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/),
+    secondary: z.string().regex(/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/),
+    accent: z.string().regex(/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/),
+});
+/**
+ * Agent Atabey config.json Schema
+ */
+export const ConfigSchema = z.object({
+    name: z.string().default("Agent Atabey"),
+    version: z.string(),
+    frameworkDir: z.string().optional(),
+    theme: z.object({
+        palette: z.string(),
+        colors: ColorPaletteSchema
+    }).optional(),
+    paths: z.object({
+        backend: z.string(),
+        frontend: z.string(),
+        docs: z.string(),
+        tests: z.string(),
+    }).default({
+        backend: "apps/backend",
+        frontend: "apps/web",
+        docs: "docs",
+        tests: "tests"
+    })
+});
+/**
+ * MCP mcp.json Schema
+ */
+export const McpConfigSchema = z.object({
+    mcpServers: z.record(z.object({
+        command: z.string(),
+        args: z.array(z.string()),
+        env: z.record(z.string()).optional()
+    }))
+});

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

@@ -0,0 +1,137 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { remapFrameworkContent } from "../adapters/index.js"; // Import from the new adapters.js
+import { ensureDir, writeTextFile, writeJsonFile, appendFile } from "../../shared/fs.js";
+export { ensureDir, writeTextFile, writeJsonFile, appendFile };
+export function updateGitIgnore(targetPath, frameworkDir = ".atabey", dryRun = false) {
+    const IGNORE_LINES = [
+        "# Agent Atabey",
+        `${frameworkDir}/logs/*.json`,
+        `${frameworkDir}/*.lock`,
+        `${frameworkDir}/memory/`,
+        ".env",
+        ".DS_Store",
+    ];
+    let content = "";
+    if (fs.existsSync(targetPath)) {
+        content = fs.readFileSync(targetPath, "utf8");
+    }
+    const lines = content.split("\n").map((l) => l.trim());
+    let added = false;
+    for (const line of IGNORE_LINES) {
+        if (!lines.includes(line)) {
+            content += (content.endsWith("\n") || content === "" ? "" : "\n") + line + "\n";
+            added = true;
+        }
+    }
+    if (added) {
+        if (dryRun) {
+            console.warn(`[DRY RUN] Would update .gitignore at ${targetPath}`);
+        }
+        else {
+            writeTextFile(targetPath, content);
+            console.warn("[OK] .gitignore updated.");
+        }
+    }
+}
+export function copyDir(src, dest, skipSet = new Set(), nonDestructive = false, frameworkDir = ".gemini", targetScope = "", sanitizeJson, adapterId = "gemini", dryRun = false) {
+    const DEFAULT_SKIP = new Set(["node_modules", ".git", ".DS_Store", "package-lock.json"]);
+    const actualSkip = new Set([...DEFAULT_SKIP, ...skipSet]);
+    if (!fs.existsSync(dest) && !dryRun) {
+        fs.mkdirSync(dest, { recursive: true });
+    }
+    fs.readdirSync(src, { withFileTypes: true }).forEach((entry) => {
+        if (actualSkip.has(entry.name))
+            return;
+        const srcPath = path.join(src, entry.name);
+        // Physical folder remapping during copy.
+        // In unified mode (frameworkDir === ".atabey") folder names are always standard —
+        // agents/ stays agents/, knowledge/ stays knowledge/.
+        // Only remap when using a legacy non-unified adapter directory.
+        let effectiveEntryName = entry.name;
+        if (entry.isDirectory() && frameworkDir !== ".atabey") {
+            if (entry.name === "agents") {
+                if (adapterId === "antigravity-cli")
+                    effectiveEntryName = "skills";
+                else if (adapterId === "grok")
+                    effectiveEntryName = "plugins";
+            }
+            else if (entry.name === "knowledge") {
+                if (adapterId === "antigravity-cli")
+                    effectiveEntryName = "rules";
+            }
+        }
+        const destPath = path.join(dest, effectiveEntryName);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath, skipSet, nonDestructive, frameworkDir, targetScope, sanitizeJson, adapterId, dryRun);
+        }
+        else {
+            if (nonDestructive && fs.existsSync(destPath)) {
+                return;
+            }
+            const ext = path.extname(entry.name);
+            const textExtensions = [".md", ".json", ".js", ".ts", ".txt", ""];
+            if (textExtensions.includes(ext)) {
+                let content = fs.readFileSync(srcPath, "utf8");
+                content = remapFrameworkContent(content, frameworkDir, adapterId); // Use the new remap function
+                if (ext === ".json") {
+                    try {
+                        const json = JSON.parse(content);
+                        writeJsonFile(destPath, sanitizeJson(json, targetScope), dryRun);
+                    }
+                    catch {
+                        const fallback = content.replace(/workspace:[^"'\s]*/g, "*");
+                        writeTextFile(destPath, fallback, dryRun);
+                    }
+                }
+                else {
+                    content = content.replace(/workspace:[^"'\s]*/g, "*");
+                    content = remapFrameworkContent(content, frameworkDir, adapterId); // Apply remap once to the final content
+                    writeTextFile(destPath, content, dryRun);
+                }
+            }
+            else {
+                if (dryRun) {
+                    console.warn(`[DRY RUN] Would copy binary file: ${destPath}`);
+                }
+                else {
+                    fs.copyFileSync(srcPath, destPath);
+                }
+            }
+        }
+    });
+}
+export function collectFiles(dir, extensions) {
+    let results = [];
+    if (!fs.existsSync(dir))
+        return results;
+    const list = fs.readdirSync(dir);
+    list.forEach((file) => {
+        file = path.join(dir, file);
+        const stat = fs.statSync(file);
+        if (stat && stat.isDirectory()) {
+            if (!file.includes("node_modules") && !file.includes(".git")) {
+                results = results.concat(collectFiles(file, extensions));
+            }
+        }
+        else if (extensions.includes(path.extname(file))) {
+            results.push(file);
+        }
+    });
+    return results;
+}
+export function computeTypesHash(projectRoot, sharedDir) {
+    const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => {
+        const fullPath = path.join(d, e.name);
+        return e.isDirectory() ? walk(fullPath) : (e.name.endsWith(".ts") ? [fullPath] : []);
+    });
+    const hash = crypto.createHash("sha256");
+    for (const filePath of walk(sharedDir).sort()) {
+        hash.update(path.relative(projectRoot, filePath));
+        hash.update("\0");
+        hash.update(fs.readFileSync(filePath));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}

package/framework-mcp/dist/src/cli/utils/i18n.js

@@ -0,0 +1,30 @@
+export const TRANSLATIONS = {
+    tr: {
+        welcome: "Agent Atabey İnteraktif Kuruluma Hoş Geldiniz!",
+        select_backend: "Kurumsal Backend Dilini Seçin",
+        select_frontend: "Kurumsal Frontend Altyapısını Seçin",
+        select_language: "Framework İletişim Dilini Seçin",
+        select_dirs: "Dahil edilecek framework dizinlerini seçin (örn: 1,2,3) veya HEPSİ için Enter:",
+        select_agents: "Dahil edilecek çekirdek ajanları seçin (örn: 1,2) veya HEPSİ için Enter:",
+        select_palette: "Renk paletini seçin (1-3) veya Enter (Modern Blue):",
+        init_success: "Agent Atabey başarıyla kuruldu!",
+        constitution_title: "Atabey Anayasası — Disiplin ve Nizam",
+        status_title: "Durum Çizelgesi",
+        agent_ready: "HAZIR",
+        next_steps: "Sonraki Adımlar:",
+    },
+    en: {
+        welcome: "Welcome to Agent Atabey Interactive Setup!",
+        select_backend: "Select Enterprise Backend Language",
+        select_frontend: "Select Enterprise Frontend Framework/Build Tool",
+        select_language: "Select Framework Communication Language",
+        select_dirs: "Enter directory numbers to include (e.g. 1,2,3) or Enter for ALL:",
+        select_agents: "Enter agent numbers to include (e.g. 1,2) or Enter for ALL:",
+        select_palette: "Select palette (1-3) or Enter (Modern Blue):",
+        init_success: "Agent Atabey initialized successfully!",
+        constitution_title: "Atabey Constitution — Discipline and Order",
+        status_title: "Status Board",
+        agent_ready: "READY",
+        next_steps: "Next Steps:",
+    }
+};

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

@@ -0,0 +1,276 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { logger } from "../../shared/logger.js";
+import { ensureDir, writeTextFile, writeJsonFile } from "../../shared/fs.js";
+import { Storage } from "../../shared/storage.js";
+import { FRAMEWORK, FRAMEWORK_DIR_CANDIDATES, MCP, } from "../../shared/constants.js";
+export { generateULID } from "./time.js";
+const CWD = process.cwd();
+const HOME = os.homedir();
+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 (err) {
+        logger.debug("Failed to read package.json in findFrameworkDir", err);
+    }
+    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 (err) {
+        logger.debug("Failed to read package.json in isFrameworkDevelopmentRepo", err);
+    }
+    return false;
+}
+export function getLocalFrameworkDir() {
+    const localDir = findFrameworkDir(CWD);
+    return localDir || path.join(CWD, FRAMEWORK.CORE_DIR);
+}
+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();
+}
+export function getDocumentStorePath() {
+    const frameworkDir = getFrameworkDir();
+    return path.join(frameworkDir, "memory");
+}
+export function initDocumentStore(frameworkDir) {
+    const storePath = frameworkDir ? path.join(frameworkDir, "memory") : getDocumentStorePath();
+    ensureDir(storePath);
+    ensureDir(path.join(storePath, "tasks"));
+    ensureDir(path.join(storePath, "history"));
+    const stateFile = path.join(storePath, "state.json");
+    if (!fs.existsSync(stateFile)) {
+        writeJsonFile(stateFile, { phase: "PHASE_0", traceId: "T-000", managerState: "ACTIVE" });
+    }
+    const statusFile = path.join(storePath, "status.json");
+    if (!fs.existsSync(statusFile)) {
+        writeJsonFile(statusFile, {});
+    }
+    // Initialize SQLite
+    Storage.setMetadata("phase", "PHASE_0");
+    Storage.setMetadata("traceId", "T-000");
+    Storage.setMetadata("managerState", "ACTIVE");
+    // Ensure the initial Markdown view is created
+    syncMarkdownMemory(frameworkDir);
+}
+export function readState() {
+    const phase = Storage.getMetadata("phase") || "PHASE_0";
+    const traceId = Storage.getMetadata("traceId") || "T-000";
+    const managerState = Storage.getMetadata("managerState") || "ACTIVE";
+    return { phase, traceId, managerState };
+}
+export function readStatus() {
+    const agents = Storage.getAllAgents();
+    const status = {};
+    agents.forEach((a) => {
+        const name = a.name.startsWith("@") ? a.name : `@${a.name}`;
+        status[name] = { state: a.state, task: a.task, lastUpdated: a.last_updated };
+    });
+    return status;
+}
+export function listTasks() {
+    return Storage.getTasks();
+}
+export function getMemoryPath() {
+    return path.join(getDocumentStorePath(), "state.json");
+}
+export function readActiveTraceId(memoryContent) {
+    try {
+        const state = JSON.parse(memoryContent);
+        return state.traceId || null;
+    }
+    catch (_e) { /* ignore */
+        return null;
+    }
+}
+export function updateProjectMemory(section, content) {
+    if (section === "HISTORY") {
+        updateDocumentStore("history", { content }, new Date().toISOString().replace(/[:.]/g, "-"));
+    }
+    else {
+        const state = readState() || {};
+        state[section] = content;
+        updateDocumentStore("state", state);
+    }
+}
+export function initializeMemory(memoryPathOrBase, targetBaseOrDryRun) {
+    const targetBase = typeof targetBaseOrDryRun === "string" ? targetBaseOrDryRun : memoryPathOrBase;
+    initDocumentStore(targetBase);
+    logger.info("[OK] Document store initialized.");
+}
+export function getConfiguredPaths() {
+    const defaultPaths = { backend: "apps/backend", frontend: "apps/web", mobile: "apps/mobile", docs: "docs", tests: "tests" };
+    try {
+        const frameworkDir = getConfigDir();
+        const configPath = path.join(frameworkDir, "config.json");
+        if (fs.existsSync(configPath)) {
+            const rawConfig = JSON.parse(fs.readFileSync(configPath, "utf8"));
+            return rawConfig.paths || defaultPaths;
+        }
+    }
+    catch (err) {
+        logger.debug("Critical config read failure", err);
+    }
+    return defaultPaths;
+}
+export function updateDocumentStore(type, data, id, frameworkDir) {
+    const storePath = frameworkDir ? path.join(frameworkDir, "memory") : getDocumentStorePath();
+    ensureDir(storePath);
+    switch (type) {
+        case "state":
+            writeJsonFile(path.join(storePath, "state.json"), data);
+            break;
+        case "status": {
+            const status = data;
+            for (const [agent, info] of Object.entries(status)) {
+                Storage.updateAgentStatus(agent, info.state, info.task, info.lastUpdated);
+            }
+            break;
+        }
+        case "task": {
+            Storage.saveTask(data);
+            break;
+        }
+        case "history": {
+            const db = Storage.getDB();
+            db.prepare(`
+                INSERT INTO logs (agent, action, summary)
+                VALUES (?, ?, ?)
+            `).run("@manager", "HISTORY_UPDATE", data.content);
+            break;
+        }
+    }
+    // Auto-sync Markdown view after any change
+    syncMarkdownMemory(frameworkDir);
+}
+/**
+ * Single Source of Truth Bridge: JSON -> Markdown
+ * Regenerates PROJECT_MEMORY.md from structured state.
+ */
+export function syncMarkdownMemory(fDir) {
+    const frameworkDir = fDir || getFrameworkDir();
+    const storePath = path.join(frameworkDir, "memory");
+    const mdPath = path.join(storePath, "PROJECT_MEMORY.md");
+    try {
+        const state = readState();
+        const status = readStatus();
+        const tasks = Storage.getTasks();
+        if (!state)
+            return;
+        const lines = [
+            "# [MEMORY] Agent Atabey — Project Memory",
+            "",
+            "## 📍 Current State",
+            `- **Phase:** ${state.phase || "PHASE_0"}`,
+            `- **Trace ID:** ${state.traceId || "N/A"}`,
+            `- **@manager state:** ${state.managerState || "ACTIVE"}`,
+        ];
+        // Add custom sections from state
+        const internalFields = ["phase", "traceId", "managerState"];
+        Object.entries(state).forEach(([key, value]) => {
+            if (!internalFields.includes(key) && value) {
+                lines.push("", `## 📌 ${key}`, String(value));
+            }
+        });
+        lines.push("", "## 📋 Active Tasks", "| Trace ID | Task | Agent | Priority | Status |", "| :--- | :--- | :--- | :--- | :--- |");
+        tasks.forEach(t => {
+            if (t.status !== "COMPLETED") {
+                lines.push(`| ${t.traceId} | ${t.description} | ${t.agent} | ${t.priority} | ${t.status} |`);
+            }
+        });
+        lines.push("", "## [AI] Agent Statuses");
+        lines.push("| Agent | State | Active Task | Last Updated |");
+        lines.push("| :--- | :--- | :--- | :--- |");
+        for (const [agent, info] of Object.entries(status)) {
+            const data = info;
+            const displayAgent = agent.startsWith("@") ? agent : `@${agent}`;
+            lines.push(`| ${displayAgent} | ${data.state} | ${data.task} | ${data.lastUpdated || "-"} |`);
+        }
+        lines.push("", "## 📜 HISTORY");
+        // Add last 5 history items
+        const historyDir = path.join(storePath, "history");
+        if (fs.existsSync(historyDir)) {
+            const histFiles = fs.readdirSync(historyDir)
+                .filter(f => f.endsWith(".json"))
+                .sort()
+                .reverse()
+                .slice(0, 10);
+            histFiles.forEach(f => {
+                const hist = JSON.parse(fs.readFileSync(path.join(historyDir, f), "utf8"));
+                lines.push(`### ${f.replace(".json", "")}`);
+                lines.push(hist.content);
+                lines.push("");
+            });
+        }
+        writeTextFile(mdPath, lines.join("\n"));
+        logger.debug("Markdown memory synchronized.");
+    }
+    catch (err) {
+        logger.debug("Markdown memory sync failed", err);
+    }
+}
+export function acquireMemoryLock(lockPath) {
+    try {
+        fs.writeFileSync(lockPath, String(Date.now()), { flag: "wx" });
+        return true;
+    }
+    catch (err) {
+        const error = err;
+        if (error.code === "EEXIST") {
+            try {
+                const stat = fs.statSync(lockPath);
+                if (Date.now() - stat.mtimeMs > 10000) {
+                    fs.unlinkSync(lockPath);
+                    fs.writeFileSync(lockPath, String(Date.now()), { flag: "wx" });
+                    return true;
+                }
+            }
+            catch (_e) { /* ignore */
+                // Ignore
+            }
+        }
+        return false;
+    }
+}
+export function releaseMemoryLock(lockPath) {
+    if (fs.existsSync(lockPath))
+        fs.unlinkSync(lockPath);
+}