@futdevpro/fdp-agent-memory 0.1.0 → 1.1.12

package/build/src/_collections/fam-console.util.js

@@ -0,0 +1,367 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Console_Util = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const fs = tslib_1.__importStar(require("fs"));
+const os = tslib_1.__importStar(require("os"));
+const path = tslib_1.__importStar(require("path"));
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+/**
+ * `FAM_Console_Util` (FEAT-001) — `fam start`-kor (a PRIMARY példánynál) megnyit egy KÜLÖN, vizuálisan
+ * látható terminál-ablakot, ami a szerver folyó tevékenységét mutatja.
+ *
+ * **Miért nem a process saját konzolja?** MCP-stdio módban a process stdout-ja a JSON-RPC csatorna —
+ * azt NEM szabad konzol-ablakká tenni. Ezért a látható ablak egy KÜLÖN monitor-process, ami a szerver
+ * **activity-logját tail-eli**: a `tee`-vel a `console.*` kimenetet egy log-fájlba is írjuk (a meglévő
+ * stderr/stdout mellé), és egy platform-natív terminál-ablakot indítunk, ami azt a fájlt követi.
+ *
+ * **Default ON.** Kikapcsolható: `FAM_SHOW_CONSOLE=false|0|off|no` (a docker-compose ezt állítja, mert
+ * a konténerben nincs GUI). Minden lépés **fail-safe** (try/catch) — az ablak hibája SOHA nem töri a bootot.
+ *
+ * **Részletesség (`isVerbose`, `FAM_CONSOLE_VERBOSE`):** default VERBOSE → MINDEN `console.*` log-sor a
+ * monitorba kerül (user-direktíva). `FAM_CONSOLE_VERBOSE=false` → kurált allowlist (`isActivityRelevant`).
+ */
+class FAM_Console_Util {
+    /**
+     * A monitor-lock **frissesség-küszöbe** (ms): ha a lockfile mtime-ja ennél régebbi, a monitor-ablakot
+     * HALOTTNAK tekintjük (bezárták) → új nyitható. A nyitott ablak `MONITOR_HEARTBEAT_MS`-enként frissíti a
+     * lockot (a PID-alapú check helyett — az törékeny: async PID-write-race a `start`-detach miatt + Windows
+     * PID-reuse → FELESLEGES dupla ablakok szerver-restartkor; a frissesség mindkettőt megoldja).
+     */
+    static MONITOR_STALE_MS = 10_000;
+    /** A monitor-ablak heartbeat-periódusa (ms): ennyente frissíti a lockfile mtime-ját, amíg él. */
+    static MONITOR_HEARTBEAT_MS = 3_000;
+    /**
+     * Az activity-monitor-ablak engedélyezett-e. **Default OFF** (opt-in) — user-direktíva 2026-06-21: a külön
+     * FEAT-001 tail-monitort kivettük, mert a `fam serve` saját LÁTHATÓ konzol-ablakot ad (az a szerver-aktivitás),
+     * így a külön monitor redundáns. Csak EXPLICIT `FAM_SHOW_CONSOLE=true|1|on|yes` esetén nyílik (ritka:
+     * pl. ha valaki a stdio-MCP `fam start`-ot primary-ként futtatja és mégis tail-ablakot szeretne).
+     */
+    static isEnabled() {
+        const raw = (process.env.FAM_SHOW_CONSOLE ?? '').trim().toLowerCase();
+        return raw === 'true' || raw === '1' || raw === 'on' || raw === 'yes';
+    }
+    /**
+     * Az activity-LOG **verbose**-e (`FAM_CONSOLE_VERBOSE`). **Default ON** (user-direktíva: a monitor MINDEN
+     * log-sort írjon ki) → a `console.*` minden nem-üres sora a monitor-ablakba kerül. `false|0|off|no` → a
+     * **kurált** allowlist (csak `[fam…]` + mongo-connect + hiba/figyelmeztetés; a boot-zaj kimarad). A kettő
+     * trade-off: VERBOSE = teljes átláthatóság (de zajosabb), kurált = csak a lényeg.
+     */
+    static isVerbose() {
+        const raw = (process.env.FAM_CONSOLE_VERBOSE ?? '').trim().toLowerCase();
+        return raw !== 'false' && raw !== '0' && raw !== 'off' && raw !== 'no';
+    }
+    /**
+     * **File-log (`FAM_LOG_FILE`)** — ha az env be van állítva, a `console.*` MINDEN sorát (SZŰRETLEN) rácsatolja
+     * arra a fájlra, FÜGGETLENÜL a monitor-ablaktól (`FAM_SHOW_CONSOLE`). A `fam serve` ezt állítja be a detached
+     * szerverre → a szerver logjai (köztük az import-progress) **FÁJLBÓL OLVASHATÓK** (tail-elhetők), nem csak a
+     * GUI-ablakból. Append-mód (boot-szeparátorral), fail-safe (a log-write SOHA nem dönti meg a szervert).
+     */
+    static installFileLog() {
+        const logPath = (process.env.FAM_LOG_FILE ?? '').trim();
+        if (!logPath) {
+            return;
+        }
+        try {
+            fs.appendFileSync(logPath, `# --- FAM server log — (re)start ${new Date().toISOString()} ---\n`);
+        }
+        catch {
+            return; // nem írható a fájl → csendben kihagyjuk (nem blokkoljuk a bootot)
+        }
+        const append = (line) => {
+            try {
+                fs.appendFileSync(logPath, `${line}\n`);
+            }
+            catch {
+                /* a fájl-append hibája soha nem dönti meg a szervert */
+            }
+        };
+        const stringify = (value) => {
+            if (typeof value === 'string') {
+                return value;
+            }
+            try {
+                return JSON.stringify(value);
+            }
+            catch {
+                return String(value);
+            }
+        };
+        const wrap = (original) => {
+            return (...args) => {
+                original(...args);
+                append(args.map(stringify).join(' '));
+            };
+        };
+        console.log = wrap(console.log);
+        console.info = wrap(console.info);
+        console.warn = wrap(console.warn);
+        console.error = wrap(console.error);
+    }
+    /**
+     * A PRIMARY szerver activity-konzol-ablakának megnyitása: log-fájl-tee + platform-natív monitor-ablak.
+     * Disabled (`FAM_SHOW_CONSOLE` off) vagy bármilyen hiba esetén CSENDES no-op (a boot folytatódik).
+     */
+    static openActivityConsole(set) {
+        if (!FAM_Console_Util.isEnabled()) {
+            return;
+        }
+        try {
+            const logPath = path.join(os.tmpdir(), `fam-activity-${set.port}.log`);
+            const lockPath = path.join(os.tmpdir(), `fam-activity-${set.port}.lock`);
+            // A log-fájl PERSISTÁL a (reconnect miatti) szerver-újraindulások között: header CSAK ha új,
+            // különben separator. A folyó monitor-ablak UGYANAZT a fájlt tail-eli, így a tevékenység
+            // akkumulálódik (nem csonkol minden bootkor — ez okozta a „nincs érdemi info"-t).
+            const mode = FAM_Console_Util.isVerbose() ? 'VERBOSE (minden log)' : 'kurált (allowlist)';
+            if (!fs.existsSync(logPath)) {
+                fs.writeFileSync(logPath, `# FAM activity log — port ${set.port} — ${new Date().toISOString()} — mód: ${mode}\n`);
+            }
+            else {
+                fs.appendFileSync(logPath, `# --- szerver-process (újra)indult — ${new Date().toISOString()} — mód: ${mode} ---\n`);
+            }
+            FAM_Console_Util.teeConsoleToFile(logPath);
+            // EGYETLEN monitor-ablak: ha már fut egy (a lockfile-beli PID él), NEM nyitunk újat — csak tee-zünk
+            // a közös logba (ezt mutatja a meglévő ablak). Így a reconnect-churn NEM spamel új terminálokat.
+            if (FAM_Console_Util.isMonitorAlive(lockPath)) {
+                return;
+            }
+            FAM_Console_Util.spawnMonitorWindow(logPath, lockPath, set.port);
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM console] activity-ablak megnyitása sikertelen (a szerver fut tovább): ${error?.message}`);
+        }
+    }
+    /**
+     * Fut-e már egy ÉLŐ monitor-ablak ehhez a porthoz? **Frissesség-alapú** (a régi PID-check helyett): a nyitott
+     * ablak `MONITOR_HEARTBEAT_MS`-enként frissíti a lockfile-t (mtime), így ha az mtime `MONITOR_STALE_MS`-nél
+     * frissebb → él (reuse, NEM nyitunk újat); ha régebbi → az ablakot bezárták → új nyitható. Ez immun a Windows
+     * `start`-detach okozta async PID-write-race-re ÉS a PID-reuse-ra (a két ok, ami szerver-restartkor dupla
+     * ablakot nyitott). Hiányzó/olvashatatlan lock → nincs élő ablak.
+     */
+    static isMonitorAlive(lockPath) {
+        try {
+            if (!fs.existsSync(lockPath)) {
+                return false;
+            }
+            const ageMs = Date.now() - fs.statSync(lockPath).mtimeMs;
+            return ageMs < FAM_Console_Util.MONITOR_STALE_MS;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** A `console.*` kimenet rácsatolása a log-fájlra (a meglévő stderr/stdout MELLÉ — nem helyette). */
+    static teeConsoleToFile(logPath) {
+        const append = (line) => {
+            try {
+                fs.appendFileSync(logPath, `${line}\n`);
+            }
+            catch {
+                /* a fájl-append hibája soha nem dönti meg a szervert */
+            }
+        };
+        const stringify = (value) => {
+            if (typeof value === 'string') {
+                return value;
+            }
+            try {
+                return JSON.stringify(value);
+            }
+            catch {
+                return String(value);
+            }
+        };
+        const wrap = (original) => {
+            return (...args) => {
+                original(...args);
+                // A stderr/stdout a TELJES kimenetet kapja (változatlan); az activity-LOGba viszont CSAK a
+                // tevékenység-releváns sorok kerülnek — a boot-banner (ASCII-art, endpoint-mount, mongoose-
+                // warning) így nem szemeteli az ablakot, és a [fam*] activity nem süllyed el (a user-panasz).
+                const line = args.map(stringify).join(' ');
+                if (FAM_Console_Util.isActivityRelevant(line)) {
+                    append(line);
+                }
+            };
+        };
+        console.log = wrap(console.log.bind(console));
+        console.info = wrap(console.info.bind(console));
+        console.warn = wrap(console.warn.bind(console));
+        console.error = wrap(console.error.bind(console));
+        console.debug = wrap(console.debug.bind(console));
+    }
+    /**
+     * Activity-releváns-e egy log-sor → bekerül-e a monitor-ablakba. **VERBOSE módban** (default, `isVerbose`)
+     * MINDEN nem-üres sor átmegy (a user „minden logot" direktívája). **Kurált módban** (`FAM_CONSOLE_VERBOSE=
+     * false`) allowlist: minden `[fam…]`/`[FAM …]` sor (famRead/famWrite/famIngest + `[FAM hydrate]`/`[FAM MCP]`
+     * boot-státusz), a `Connected to MongoDB`, a `…successfully`, és MINDEN hiba/figyelmeztetés (hogy a problémák
+     * SOHA ne tűnjenek el); minden más (a teljes Express/Dynamo boot-banner) kimarad (stderr-en marad).
+     */
+    static isActivityRelevant(line) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            return false;
+        }
+        // VERBOSE (default): minden nem-üres sor a monitorba — teljes átláthatóság (user-direktíva).
+        if (FAM_Console_Util.isVerbose()) {
+            return true;
+        }
+        if (/^\[fam/i.test(trimmed)) {
+            return true;
+        }
+        if (/connected to mongodb|successfully/i.test(trimmed)) {
+            return true;
+        }
+        return /\b(error|warn|warning|fail|failed|exception|critical)\b/i.test(trimmed);
+    }
+    /**
+     * Platform-natív terminál-ablak indítása, ami a log-fájlt tail-eli (detached, fail-safe). Az ablak
+     * `MONITOR_HEARTBEAT_MS`-enként **frissíti a lockot** (heartbeat), így a következő (reconnect/restart miatti)
+     * boot az mtime-frissességből látja, hogy él → NEM nyit újat (`isMonitorAlive`). A spawn ELŐTT egy
+     * provisional friss lockot is írunk (a közel-egyidejű boot-race ellen).
+     */
+    static spawnMonitorWindow(logPath, lockPath, port) {
+        try {
+            FAM_Console_Util.touchLock(lockPath); // provisional friss mtime — a spawn alatti race-dupla ellen
+            if (process.platform === 'win32') {
+                // A monitor-logikát egy temp `.ps1`-be írjuk + `-File`-lal futtatjuk → NINCS `-Command`-escaping-
+                // rémálom (a sok `()[]{}|::`). A script HEARTBEAT-eli a lockot (a régi async `$PID`-write helyett —
+                // az okozta a PID-race/reuse dupla-ablakokat), és StreamReader-rel STREAMING-tail-el (UTF-8, a
+                // `Get-Content -Wait` helyett, hogy a heartbeat a [fam*]-zaj alatt is frissen tartsa a lockot).
+                const scriptPath = path.join(os.tmpdir(), `fam-activity-monitor-${port}.ps1`);
+                fs.writeFileSync(scriptPath, FAM_Console_Util.windowsMonitorScript(logPath, lockPath, port));
+                const child = (0, child_process_1.spawn)(process.env.ComSpec ?? 'cmd.exe', ['/c', 'start', '', 'powershell', '-NoExit', '-ExecutionPolicy', 'Bypass', '-File', scriptPath], { detached: true, stdio: 'ignore', windowsHide: false });
+                child.unref();
+                return;
+            }
+            // mac/linux: a tail MELLETT egy heartbeat-loop (a lockot frissíti, amíg a tail — így az ablak — él);
+            // a `kill -0 $tailPid` figyeli a tail-t, így az ablak bezárásakor a loop is kilép (nincs árva heartbeat).
+            const heartbeatSec = Math.max(1, Math.round(FAM_Console_Util.MONITOR_HEARTBEAT_MS / 1000));
+            const shellCmd = `tail -n 200 -f '${logPath}' & tp=$!; `
+                + `while kill -0 $tp 2>/dev/null; do : > '${lockPath}'; sleep ${heartbeatSec}; done`;
+            if (process.platform === 'darwin') {
+                const script = `tell application "Terminal" to do script "${shellCmd.replace(/"/g, '\\"')}"`;
+                const child = (0, child_process_1.spawn)('osascript', ['-e', script], { detached: true, stdio: 'ignore' });
+                child.unref();
+                return;
+            }
+            const terminal = FAM_Console_Util.findLinuxTerminal();
+            if (!terminal) {
+                fsm_dynamo_1.DyFM_Log.warn('[FAM console] nincs ismert Linux terminál-emulátor — az activity-ablak kihagyva '
+                    + `(a log a fájlban: ${logPath}; tail-eld kézzel, vagy FAM_SHOW_CONSOLE=false).`);
+                return;
+            }
+            const child = (0, child_process_1.spawn)(terminal, ['-e', 'sh', '-c', shellCmd], { detached: true, stdio: 'ignore' });
+            child.unref();
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM console] a monitor-ablak indítása sikertelen: ${error?.message}`);
+        }
+    }
+    /**
+     * A Windows monitor-`.ps1` tartalma: UTF-8 streaming-tail (StreamReader; a `Get-Content -Wait` helyett, hogy
+     * a heartbeat akkor is frissüljön, ha sok a log-sor) + `MONITOR_HEARTBEAT_MS`-enkénti lock-frissítés (a
+     * heartbeat). Az ablak bezárásakor a PowerShell-process megszűnik → a lock mtime elöregszik → `isMonitorAlive`
+     * false → a következő boot új ablakot nyit (helyesen). A path-okban a `'`-eket megdupláljuk (PS escape, defenzív).
+     */
+    static windowsMonitorScript(logPath, lockPath, port) {
+        const log = logPath.replace(/'/g, "''");
+        const lock = lockPath.replace(/'/g, "''");
+        return [
+            'try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}',
+            `try { $host.UI.RawUI.WindowTitle='FAM activity (${port})' } catch {}`,
+            `$log='${log}'`,
+            `$lock='${lock}'`,
+            'if (Test-Path -LiteralPath $log) { Get-Content -LiteralPath $log -Tail 200 -Encoding UTF8 | Write-Host }',
+            "$fs=[System.IO.File]::Open($log,'Open','Read','ReadWrite')",
+            '$sr=New-Object System.IO.StreamReader($fs,[System.Text.Encoding]::UTF8)',
+            '$sr.BaseStream.Seek(0,[System.IO.SeekOrigin]::End) | Out-Null',
+            '$beat=0',
+            'while ($true) {',
+            '  $line=$sr.ReadLine()',
+            '  if ($null -ne $line) { Write-Host $line } else { Start-Sleep -Milliseconds 400 }',
+            '  $now=[DateTimeOffset]::Now.ToUnixTimeMilliseconds()',
+            `  if (($now - $beat) -ge ${FAM_Console_Util.MONITOR_HEARTBEAT_MS}) { [System.IO.File]::WriteAllText($lock,[string]$now); $beat=$now }`,
+            '}',
+        ].join('\r\n');
+    }
+    /** A lockfile mtime-jának frissítése (a monitor „élő" jelzése, heartbeat). Fail-safe. */
+    static touchLock(lockPath) {
+        try {
+            fs.writeFileSync(lockPath, String(Date.now()));
+        }
+        catch {
+            /* a lock-write hibája soha nem dönti meg a szervert */
+        }
+    }
+    /** Az első elérhető Linux terminál-emulátor (PATH-on), vagy null. */
+    static findLinuxTerminal() {
+        const candidates = ['x-terminal-emulator', 'gnome-terminal', 'konsole', 'xfce4-terminal', 'xterm'];
+        for (const candidate of candidates) {
+            for (const dir of (process.env.PATH ?? '').split(path.delimiter)) {
+                if (dir && fs.existsSync(path.join(dir, candidate))) {
+                    return candidate;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Egy VISIBLE, OLVASHATÓ terminál-ablak nyitása, amiben a megadott parancs (a FAM REST-szerver) FUT. A
+     * `fam serve` (FEAT-003) ezt használja: a `start`/terminál TELJESEN LEVÁLASZTJA a szervert a hívóról (saját
+     * konzol-ablak), így túléli a CLI-t, és az ablak a szerver **élő stdout/stderr-jét** mutatja közvetlenül.
+     * Ezért a szervert `FAM_SHOW_CONSOLE=false`-szal indítjuk (a serve env-override-ja) — a FEAT-001 külön
+     * tail-monitor-ablak ehhez **redundáns** (nem nyílik 2. ablak). Fail-safe (a hívó `--foreground`-ra eshet vissza).
+     */
+    static spawnServerWindow(set) {
+        if (process.platform === 'win32') {
+            // Launcher-`.ps1` (mint a FEAT-001 monitor) → NINCS `-Command`-escaping-rémálom; `-NoExit` → az ablak
+            // a szerver kilépése (vagy crash) UTÁN is nyitva marad (a hiba látható).
+            const scriptPath = path.join(os.tmpdir(), `fam-server-${set.port}.ps1`);
+            fs.writeFileSync(scriptPath, FAM_Console_Util.windowsServerScript(set));
+            const child = (0, child_process_1.spawn)(process.env.ComSpec ?? 'cmd.exe', ['/c', 'start', '', 'powershell', '-NoExit', '-ExecutionPolicy', 'Bypass', '-File', scriptPath], { detached: true, stdio: 'ignore', windowsHide: false });
+            child.unref();
+            return;
+        }
+        // mac/linux: a terminál a szervert futtatja; a kilépés után az ablak nyitva marad (`exec $SHELL`).
+        const exports = Object.entries(set.envOverrides)
+            .map(([key, value]) => `export ${key}='${value.replace(/'/g, `'\\''`)}'`).join('; ');
+        const invocation = [set.command, ...set.args].map((arg) => `'${arg.replace(/'/g, `'\\''`)}'`).join(' ');
+        const shellCmd = `${exports}; ${invocation}; echo; echo '[FAM szerver kilépett — fam serve --restart újraindítja]'; exec $SHELL`;
+        if (process.platform === 'darwin') {
+            const script = `tell application "Terminal" to do script "${shellCmd.replace(/"/g, '\\"')}"`;
+            const child = (0, child_process_1.spawn)('osascript', ['-e', script], { detached: true, stdio: 'ignore' });
+            child.unref();
+            return;
+        }
+        const terminal = FAM_Console_Util.findLinuxTerminal();
+        if (!terminal) {
+            fsm_dynamo_1.DyFM_Log.warn('[FAM serve] nincs ismert Linux terminál-emulátor — futtasd `fam serve --foreground`-dal '
+                + '(vagy nyiss kézzel egy ablakot a szerverhez).');
+            return;
+        }
+        const child = (0, child_process_1.spawn)(terminal, ['-e', 'sh', '-c', shellCmd], { detached: true, stdio: 'ignore' });
+        child.unref();
+    }
+    /**
+     * A Windows szerver-launcher `.ps1` tartalma: UTF-8 konzol + ablakcím, az env-override-ok (`$env:X='...'`),
+     * majd a szerver futtatása (`& command args`). A `'`-eket megdupláljuk (PS string-escape). A `-NoExit`
+     * (a spawn-oldalon) tartja nyitva az ablakot kilépés után.
+     */
+    static windowsServerScript(set) {
+        const esc = (value) => value.replace(/'/g, "''");
+        const lines = [
+            'try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}',
+            `try { $host.UI.RawUI.WindowTitle='FAM server :${set.port}' } catch {}`,
+        ];
+        for (const [key, value] of Object.entries(set.envOverrides)) {
+            lines.push(`$env:${key}='${esc(value)}'`);
+        }
+        const invocation = [set.command, ...set.args].map((arg) => `'${esc(arg)}'`).join(' ');
+        lines.push(`& ${invocation}`);
+        lines.push("Write-Host ''");
+        lines.push("Write-Host \"[FAM szerver kilépett — exit $LASTEXITCODE — 'fam serve --restart' újraindítja]\"");
+        return lines.join('\r\n');
+    }
+}
+exports.FAM_Console_Util = FAM_Console_Util;

package/build/src/_collections/fam-entry-bootstrap.util.js

@@ -1,15 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FAM_EntryBootstrap_Util = void 0;
+const tslib_1 = require("tslib");
+const net = tslib_1.__importStar(require("net"));
+const commander_1 = require("commander");
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
 const app_server_1 = require("../app.server");
 const package_json_1 = require("../../package.json");
 const mcp_1 = require("../_modules/mcp");
+const fam_client_service_1 = require("../_cli/_services/fam-client.service");
+const register_commands_1 = require("../_cli/register-commands");
+const fam_console_util_1 = require("./fam-console.util");
+const fam_mcp_bridge_util_1 = require("./fam-mcp-bridge.util");
+/** A REST-szerver portja (env-override; default 39265). */
+const SERVER_PORT = Number(process.env.FAM_SERVER_PORT) || 39265;
 /** Az MCP-szerver SDK-neve (REQ-001, dsgn-003 §5). */
 const MCP_SERVER_NAME = 'fdp-agent-memory';
 /**
  * `FAM_EntryBootstrap_Util` (MP-6, dsgn-010 §6 / dsgn-012 §4) — a `node build/src/index.js [start]`
  * (és a publikált `fam start` bin) belépési orchestrátora. A `fam start` MINDKÉT csatornát felhúzza:
- *   - **REST szerver** (port 39185, `App extends DyNTS_App`) — a CLI (MP-9) + UI (MP-10) belépője,
+ *   - **REST szerver** (port 39265, `App extends DyNTS_App`) — a CLI (MP-9) + UI (MP-10) belépője,
  *   - **MCP stdio szerver** — a `read`/`write`/`capabilities` 3 tool a JSON-RPC stdio transporton.
  *
  * A kettő KÜLÖN csatorna (stdio JSON-RPC vs. HTTP), így egyszerre futhat: a REST a HTTP-porton, az MCP
@@ -17,9 +27,14 @@ const MCP_SERVER_NAME = 'fdp-agent-memory';
  * `App` connect + `postProcess` boot).
  *
  * **stdio-konvenció (dsgn-003 §1, dsgn-010 §6):** stdio módban a stdout a JSON-RPC csatorna — minden
- * log/diag a stderr-re kerül. Ezért a boot ELŐTT a `console.log`/`info`/`warn` stdout-írásait a
- * stderr-re irányítjuk (a `DyFM_Log` ezeken megy); az MCP `StdioServerTransport` közvetlenül a
- * `process.stdout`-ra ír (nem console-on át), így a JSON-RPC framing tiszta marad.
+ * log/diag a stderr-re kerül. Ezért a boot ELŐTT KÉT védelmet húzunk fel:
+ *   (1) `redirectConsoleToStderr` — a `console.log`/`info`/`warn`/`debug` (amin a `DyFM_Log` megy) a
+ *       stderr-re irányítása;
+ *   (2) `guardStdoutForJsonRpc` — a `process.stdout.write` guard-olása: a `DyNTS_App` boot-bannerje és a
+ *       terminál-ablakcím OSC-escape (`\x1b]0;…`) KÖZVETLENÜL a `process.stdout`-ra ír (NEM `console`-on
+ *       át), így a (1) nem fogja meg — a guard nélkül ezek a JSON-RPC framing elé ragadnának és az
+ *       MCP-kliens connect-je elbukna. A guard a JSON-RPC frame-eket (a `StdioServerTransport`
+ *       `{…}\n` írásait) átengedi a valódi stdout-ra, minden mást a stderr-re terel.
  */
 class FAM_EntryBootstrap_Util {
     /**
@@ -30,10 +45,74 @@ class FAM_EntryBootstrap_Util {
     static async main(argv) {
         const command = argv[2];
         const isStart = command === 'start' || command === 'start-server';
+        const isRestOnly = command === undefined;
+        // (A) Management-CLI parancsok (init/doctor/read/write/scan/import/config/stats/errors/seed-example)
+        // — a beépített `fam` CLI (a szerver REST-jét hívó VÉKONY kliens; a publikus boundary szerint NEM
+        // importálja a szerver-logikát, REST-en megy). Ezekhez NEM húzzuk fel a szervert (dsgn-010 §2).
+        if (!isStart && !isRestOnly) {
+            FAM_EntryBootstrap_Util.runManagementCli(argv);
+            return;
+        }
         if (isStart) {
             // stdio-konvenció: a log-stdout-ot a stderr-re irányítjuk a JSON-RPC csatorna tisztaságáért.
+            // (1) console.* (DyFM_Log) → stderr, (2) process.stdout.write guard — a DyNTS_App boot-bannerje
+            // + a terminál-ablakcím OSC-escape közvetlenül a stdout-ra ír (console-t megkerülve), ezért a
+            // (1) önmagában nem elég; guard nélkül a JSON-RPC framing sérül és az MCP-connect bukik.
             FAM_EntryBootstrap_Util.redirectConsoleToStderr();
+            FAM_EntryBootstrap_Util.guardStdoutForJsonRpc();
+        }
+        // (FEAT-002, „egy szerver, sok bridge") — fut-e már egy EGÉSZSÉGES FAM-primary (REST `/api/health`
+        // a porton)? A `isReachable` timeout-os (fél-halott primary nem akaszt). A feloldott URL-t is
+        // logoljuk, hogy a user MINDIG lássa, melyik példányhoz/portra dől a döntés.
+        // KRITIKUS: a check a TÉNYLEGES bind-portot (`SERVER_PORT`) nézze, NEM a CLI-default 39265-öt — különben
+        // egy másik porton (pl. `FAM_SERVER_PORT=39191`, `fam serve --port`) induló szerver tévesen „már fut"-ot
+        // látna a globális 39265-re, és kihagyná a saját bootját. (Az explicit `FAM_SERVER_URL` továbbra is győz.)
+        const reachabilityUrl = process.env.FAM_SERVER_URL || `http://127.0.0.1:${SERVER_PORT}`;
+        const client = new fam_client_service_1.FAM_CliClient_Service(reachabilityUrl);
+        const serverAlreadyRunning = await client.isReachable();
+        // VERZIÓ-FIGYELŐ (user 2026-06-21: „ez figyeli a verziót?"): a reachability eddig CSAK a health-et nézte,
+        // a verziót NEM → egy RÉGEBBI futó primary-t is reuse-olt volna (az új kód nem futott volna). Most lekérjük
+        // a futó primary verzióját, és ha eltér a most-bootolótól, EXPLICITEN JELEZZÜK (a reuse a régi kóddal megy
+        // tovább — a `fam serve --restart` cseréli le; itt nem ölünk, csak figyelmeztetünk).
+        const runningVersion = serverAlreadyRunning ? await FAM_EntryBootstrap_Util.fetchPrimaryVersion(client) : null;
+        const versionNote = runningVersion && runningVersion !== package_json_1.version
+            ? ` ⚠ A futó primary v${runningVersion} ≠ a most-bootoló v${package_json_1.version} — az ÚJ kódhoz: 'fam serve --restart'.`
+            : '';
+        const versionTag = runningVersion ? `, v${runningVersion}` : '';
+        if (isStart && serverAlreadyRunning) {
+            // SECONDARY → MCP-stdio BRIDGE a futó primary-hoz (NINCS 2. REST/ablak/LVS-pool; a tool-ok a
+            // primary REST-tükrét hívják, így közös Mongo + hidratált pool — port-ütközés elkerülve).
+            fsm_dynamo_1.DyFM_Log.info(`[FAM] SECONDARY mód: már fut egy egészséges FAM-primary (${client.getBaseUrl()}${versionTag}) → `
+                + `MCP-stdio BRIDGE csatlakozás (közös Mongo + hidratált pool, NINCS 2. REST/monitor/pool).${versionNote}`);
+            await fam_mcp_bridge_util_1.FAM_McpBridge_Util.start({ name: MCP_SERVER_NAME, version: package_json_1.version });
+            return;
+        }
+        if (isRestOnly && serverAlreadyRunning) {
+            // REST-only boot, de már fut egy szerver → NEM bootolunk második REST-et (egy szerver elég).
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM] már fut egy egészséges FAM-primary (${client.getBaseUrl()}${versionTag}) — a második REST-boot kihagyva.${versionNote}`);
+            return;
         }
+        // PRIMARY-jelölt (nincs egészséges futó primary). Port pre-flight: ha a portot MÁS tartja (egy nem-FAM
+        // process, VAGY egy fél-halott FAM-szerver, ami már nem válaszol a `/api/health`-en), a kötés EADDRINUSE-
+        // szal bukna egy nyers stack-kel. Ehelyett TISZTA, akcióképes hibát adunk és kilépünk (nem crashelünk).
+        const portFree = await FAM_EntryBootstrap_Util.isServerPortFree(SERVER_PORT);
+        if (!portFree) {
+            fsm_dynamo_1.DyFM_Log.error(`[FAM] a(z) ${SERVER_PORT} port FOGLALT, de nem egy egészséges FAM-primary (a /api/health `
+                + 'nem válaszolt időben). Valószínű ok: egy korábbi, fél-halott FAM-szerver-process, vagy MÁS '
+                + 'alkalmazás tartja a portot. Teendő: (1) állítsd le a portot tartó processt, VAGY (2) indíts másik '
+                + 'porton (`FAM_SERVER_PORT=<port>`). A PRIMARY-boot megszakítva (nincs crash-stack).');
+            return;
+        }
+        // PRIMARY (nincs futó szerver, a port szabad) — a teljes szerver felhúzása.
+        fsm_dynamo_1.DyFM_Log.info(`[FAM] PRIMARY mód: nincs futó FAM-primary → teljes szerver felhúzása (REST :${SERVER_PORT}`
+            + `${isStart ? ' + MCP stdio' : ''}). Activity-monitor: ${fam_console_util_1.FAM_Console_Util.isEnabled() ? 'ON' : 'OFF'}`
+            + `${fam_console_util_1.FAM_Console_Util.isEnabled() ? ` (${fam_console_util_1.FAM_Console_Util.isVerbose() ? 'VERBOSE — minden log' : 'kurált'})` : ''}.`);
+        // File-log (FAM_LOG_FILE): a `fam serve` ezt állítja be → a detached szerver logjai (köztük az
+        // import-progress) FÁJLBÓL OLVASHATÓK (tail), a monitor-ablak nélkül is. Fail-safe, env-gated.
+        fam_console_util_1.FAM_Console_Util.installFileLog();
+        // (FEAT-001) A PRIMARY egy KÜLÖN, látható activity-konzol-ablakot nyit (env-gated, fail-safe,
+        // docker-ben OFF). Az MCP-stdio JSON-RPC csatornát NEM érinti (külön monitor-process tail-el).
+        fam_console_util_1.FAM_Console_Util.openActivityConsole({ port: SERVER_PORT });
         // (1) REST szerver felhúzása (a DyNTS_App ctor indítja a connect + setup + postProcess láncot;
         // a DyNTS_App a side-effect-konstruktor mintát követi — az `index.ts` is így indít).
         FAM_EntryBootstrap_Util.startRestApp();
@@ -42,6 +121,51 @@ class FAM_EntryBootstrap_Util {
             await mcp_1.FAM_McpServer_Service.getInstance().start({ name: MCP_SERVER_NAME, version: package_json_1.version });
         }
     }
+    /**
+     * A beépített management-CLI (`fam <command>`, dsgn-010) felhúzása + parse-olása. A `commander`
+     * `program` singleton-re fűzi a 10 parancs-csoportot + 7 alias-t (`registerFAMCommands`), majd
+     * a `start`-ot itt NEM kezeljük (azt a `main` előbb elkapja → közvetlen szerver-boot). A parancs-
+     * handler-ek a saját `process.exitCode`-jukkal lépnek ki (a `commander` használati-hibái `2`-vel).
+     */
+    static runManagementCli(argv) {
+        commander_1.program
+            .name('fam')
+            .description('FDP Agent Memory — MCP-szerver + management CLI')
+            .version(package_json_1.version, '-v, --version', 'output the current version');
+        commander_1.program.exitOverride((error) => {
+            const cleanExit = ['commander.help', 'commander.helpDisplayed', 'commander.version'];
+            process.exit(cleanExit.includes(error.code) ? 0 : 2);
+        });
+        (0, register_commands_1.registerFAMCommands)(commander_1.program, package_json_1.version);
+        commander_1.program.parse(argv);
+    }
+    /**
+     * A futó FAM-primary verziója a `GET /api/health` `version` mezőjéből (a verzió-figyelőhöz). Fail-safe:
+     * hiba / hiányzó mező → `null` (a hívó a reuse-t verzió-jelölés nélkül folytatja).
+     */
+    static async fetchPrimaryVersion(client) {
+        try {
+            const result = await client.get('/api/health');
+            return result.ok && result.data && typeof result.data.version === 'string' ? result.data.version : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Szabad-e a szerver-port (egy rövid próba-`listen` a loopbackon, majd azonnali close)? `true` → köthető;
+     * `false` → már foglalt (EADDRINUSE / EACCES). A pre-flight a PRIMARY-boot ELŐTT fut: így a port-ütközést
+     * TISZTA hibaüzenettel kezeljük, nem egy nyers `DyNTS_App`-boot-közbeni EADDRINUSE-stack-kel. Fail-safe.
+     * (Apró TOCTOU-ablak marad a check és a valós kötés között — a ritka versenyt a kliens-reconnect oldja.)
+     */
+    static isServerPortFree(port) {
+        return new Promise((resolveCheck) => {
+            const tester = net.createServer();
+            tester.once('error', () => resolveCheck(false));
+            tester.once('listening', () => tester.close(() => resolveCheck(true)));
+            tester.listen(port, '127.0.0.1');
+        });
+    }
     /**
      * A REST `App` felhúzása (a `DyNTS_App` ctor a connect + setup + postProcess láncot indítja —
      * side-effect-konstruktor minta, az App-ot nem kell elkapni, a globális service-be regisztrálódik).
@@ -64,6 +188,36 @@ class FAM_EntryBootstrap_Util {
         console.warn = toStderr;
         console.debug = toStderr;
     }
+    /**
+     * A `process.stdout.write` guard-olása stdio módban (dsgn-003 §1). A `DyNTS_App` boot-bannerje és a
+     * terminál-ablakcím OSC-escape (`\x1b]0;…\x07`) KÖZVETLENÜL a `process.stdout`-ra ír (a `console.*`-ot
+     * megkerülve), ezért a `redirectConsoleToStderr` nem fogja meg — guard nélkül ezek a JSON-RPC frame elé
+     * ragadnának ugyanazon a soron, és az MCP-kliens parse-olása (connect) elbukna. A guard a JSON-RPC
+     * frame-eket (a `StdioServerTransport` `{…}\n` írásait) a VALÓDI stdout-ra engedi, minden mást a
+     * stderr-re terel. A `process.stdout` stream-objektum maga érintetlen (a transport `once('drain')`-je
+     * tovább működik); csak a `write` metódust burkoljuk.
+     */
+    static guardStdoutForJsonRpc() {
+        const realStdoutWrite = process.stdout.write.bind(process.stdout);
+        const guardedWrite = (chunk, encodingOrCb, callback) => {
+            const sink = FAM_EntryBootstrap_Util.isJsonRpcFrame(chunk)
+                ? realStdoutWrite
+                : process.stderr.write.bind(process.stderr);
+            return sink(chunk, encodingOrCb, callback);
+        };
+        // A felülírt overload-os szignatúrát egy lokális cast hidalja át (Node stream-típus plumbing).
+        process.stdout.write = guardedWrite;
+    }
+    /**
+     * Egy stdout-write chunk JSON-RPC frame-e? A `StdioServerTransport.send` a `serializeMessage`-dzsel
+     * `JSON.stringify(message) + '\n'`-t ír — mindig `{`-fel kezdődik és tartalmazza a `"jsonrpc"` mezőt.
+     * A boot-banner (ASCII-art) és az OSC-escape egyike sem ilyen, így biztosan a stderr-re kerülnek.
+     */
+    static isJsonRpcFrame(chunk) {
+        const text = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+        const trimmed = text.trimStart();
+        return trimmed.startsWith('{') && trimmed.includes('"jsonrpc"');
+    }
     /** Egy log-argumentum string-reprezentációja (objektum → JSON, primitív → String). */
     static stringifyArg(arg) {
         if (typeof arg === 'string') {

package/build/src/_collections/fam-error-factory.util.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FAM_Error_Util = void 0;
-exports.createFamError = createFamError;
 const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
 const error_codes_const_1 = require("./error-codes.const");
 const fam_error_context_util_1 = require("./fam-error-context.util");
@@ -54,11 +53,3 @@ class FAM_Error_Util {
     }
 }
 exports.FAM_Error_Util = FAM_Error_Util;
-/**
- * Kényelmi factory-függvény (a `FAM_Error_Util.create` rövid alakja) — a réteg-MP-k ezt hívják a
- * hiba-emisszió 1. lépéséhez. Pl.: `throw createFamError({ errorCode: FAM_ERROR_CODES.dbConnect,
- * message: '...', context: { operation: 'connect' } })`.
- */
-function createFamError(params) {
-    return FAM_Error_Util.create(params);
-}

package/build/src/_collections/fam-mcp-bridge.util.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_McpBridge_Util = void 0;
+const fam_core_tools_const_1 = require("../_modules/mcp/_collections/fam-core-tools.const");
+const fam_mcp_adapter_service_1 = require("../_modules/mcp/_services/fam-mcp-adapter.service");
+const fam_client_service_1 = require("../_cli/_services/fam-client.service");
+/**
+ * `FAM_McpBridge_Util` (FEAT-002, topology „egy szerver, sok bridge") — ha `fam start`-kor MÁR fut egy
+ * FAM-szerver (primary, REST a 39265-ön), az új process NEM bootol második szervert (port-ütközés +
+ * dupla LVS-pool elkerülése), hanem **MCP-stdio bridge**-ként a futó primary-hoz csatlakozik.
+ *
+ * A 3 advertised core-tool (`read`/`write`/`capabilities`) DEFINÍCIÓJA (név/leírás/schema) VÁLTOZATLAN
+ * (a `FAM_CORE_TOOLS` single-source), csak a handler proxy-zik: a primary REST-tükrét (`/api/read` |
+ * `/api/write` | `/api/capabilities`) hívja a `FAM_CliClient_Service`-en át — így a bridge ugyanazt a
+ * Mongo-kapcsolatot + hidratált vektor-pool-t használja, mint a primary (paritás, dsgn-003 §6.5).
+ *
+ * A REST-tükör success-body-ja a NYERS tool-eredmény (`res.send(data)`), így a `{ data: r.data }`
+ * pontosan az in-process handler `{ data }` alakját adja vissza (nincs dupla-wrap).
+ */
+class FAM_McpBridge_Util {
+    /**
+     * A stdio MCP-bridge indítása: a 3 core-tool REST-proxy handlerrel regisztrálva + a stdio transport.
+     * A `client` a futó primary-t hívja (`FAM_SERVER_URL`/default `http://127.0.0.1:39265`).
+     */
+    static async start(set) {
+        const adapter = new fam_mcp_adapter_service_1.FAM_Mcp_Adapter_Service({ name: set.name, version: set.version });
+        const client = new fam_client_service_1.FAM_CliClient_Service();
+        for (const tool of fam_core_tools_const_1.FAM_CORE_TOOLS) {
+            const bridged = {
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                handler: async (args) => {
+                    const result = await client.post(`/api/${tool.name}`, args ?? {});
+                    if (!result.ok) {
+                        // A primary hibáját MCP-hibaként felszínre hozzuk (NEM némítjuk; dsgn-008).
+                        const code = result.error?.errorCode ?? 'FAM-MCP-BRIDGE-001';
+                        const message = result.error?.message ?? 'A FAM bridge REST-hívása sikertelen.';
+                        throw new Error(`${code}: ${message}`);
+                    }
+                    return { data: result.data };
+                },
+            };
+            adapter.registerTool(bridged);
+        }
+        await adapter.startStdio();
+    }
+}
+exports.FAM_McpBridge_Util = FAM_McpBridge_Util;