@futdevpro/fdp-agent-memory 0.1.0 → 1.1.14

package/build/src/_cli/_commands/scan-projects.command.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ScanProjects_Util = void 0;
+const fs_1 = require("fs");
+const commander_1 = require("commander");
+const fam_output_util_1 = require("../_collections/fam-output.util");
+const fam_client_service_1 = require("../_services/fam-client.service");
+const fam_cli_const_1 = require("../_collections/fam-cli.const");
+const fam_project_discovery_util_1 = require("../_collections/fam-project-discovery.util");
+/**
+ * `fam scan-projects` — több projekt **SOROS** scan-orchestrátora (robusztus, NINCS konkurrens embed-thrash).
+ * A projekt-listát `--config` (explicit JSON) VAGY `--root` (auto-felderítés: `package.json`/`.git` markerek,
+ * a scope-név a package.json `name`-jéből) adja. Projektenként: előbb `dryRun` (idő-becslés), majd a VALÓS scan,
+ * és VÁRJA a teljes választ, mielőtt a következőre lép. Ez a megfelelő minta a Packages / teljes CURSOR scanhez.
+ */
+class FAM_ScanProjects_Util {
+    /** A `scan-projects` parancs-deszkriptor. */
+    static command() {
+        const command = new commander_1.Command('scan-projects');
+        command
+            .description('Több projekt SOROS scan-je (auto-felderítés --root-tal vagy explicit --config-gal; nincs '
+            + 'konkurrens thrash). ⚠️ MINDEN projekt-gyökérbe előbb `.fdpfamignore` + `--dry-run` (lásd lent).')
+            .option('--root <dir>', 'projekt-gyökerek auto-felderítése e mappa alatt (package.json/.git markerek)')
+            .option('--config <file.json>', 'explicit projekt-lista: [{ path, project, org?, table? }]')
+            .option('--depth <n>', 'auto-felderítés max mélysége (default 3)', '3')
+            .option('--org <name>', 'default organization az auto-felderítéshez', 'FutDevPro')
+            .option('--table <documents|codebase>', 'default cél-tár', 'codebase')
+            .option('--dry-run', 'csak becslés MINDEN projektre, NEM ír', false)
+            .option('--stop-on-error', 'az első hibánál leáll (default: folytatja a többivel)', false)
+            .addHelpText('before', '\n⚠️  TISZTA MULTI-SCAN — ELŐBB minden projektbe IGNORE-FÁJL:\n'
+            + '   Mivel ez TÖBB projektet szkennel egyszerre, a junk gyorsan elszaporodik. MINDEN érintett\n'
+            + '   projekt-gyökérbe tegyél `.fdpfamignore`-t (a default fedi a node_modules/Library/__pycache__/\n'
+            + '   site-packages/dist/build/Logs-féle junkot; a projekt-specifikusat ott add hozzá), és FUTTASD\n'
+            + '   ELŐSZÖR `--dry-run`-nal (per-projekt fájl/chunk-becslés). Utólag kitakarítani (törlés +\n'
+            + '   re-embed minden projekten) sokkal drágább, mint eleve tisztán szkennelni.\n')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_ScanProjects_Util.run(command));
+        });
+        return command;
+    }
+    /** A `scan-projects` futtatása: projekt-lista feloldás → SOROS dryRun+scan → összesítő. */
+    static async run(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        let specs;
+        try {
+            if (local.config) {
+                specs = fam_project_discovery_util_1.FAM_ProjectDiscovery_Util.parseConfig((0, fs_1.readFileSync)(local.config, 'utf-8'));
+            }
+            else if (local.root) {
+                specs = fam_project_discovery_util_1.FAM_ProjectDiscovery_Util.discover(local.root, Number(local.depth) || 3, { org: local.org, table: local.table });
+            }
+            else {
+                return fam_output_util_1.FAM_Output_Util.failure({
+                    options: globals, command: 'scan-projects',
+                    error: {
+                        errorCode: 'FAM-CLI-SCANP-001',
+                        message: '`--root <dir>` (auto-felderítés) VAGY `--config <file.json>` (explicit lista) kötelező.',
+                        fixHint: 'Pl.: fam scan-projects --root E:/.../NPM-packages   vagy   --config projects.json',
+                    },
+                });
+            }
+        }
+        catch (error) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals, command: 'scan-projects',
+                error: { errorCode: 'FAM-CLI-SCANP-002', message: `A projekt-lista feloldása sikertelen: ${error?.message}` },
+            });
+        }
+        if (!specs.length) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals, command: 'scan-projects',
+                error: { errorCode: 'FAM-CLI-SCANP-003', message: 'Nincs felderített/megadott projekt.' },
+                exitCode: fam_cli_const_1.FAM_CliExitCode.operationError,
+            });
+        }
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        const projects = [];
+        let okCount = 0;
+        FAM_ScanProjects_Util.progress(globals, `=== ${specs.length} projekt SOROS scan-je${local.dryRun ? ' (dryRun)' : ''} ===`);
+        for (let i = 0; i < specs.length; i++) {
+            const spec = specs[i];
+            FAM_ScanProjects_Util.progress(globals, `[${i + 1}/${specs.length}] ${spec.project} (${spec.path})`);
+            // 1) dryRun — idő-becslés
+            const dry = await client.post('/api/write', FAM_ScanProjects_Util.body(spec, true, local));
+            const dryScan = dry.ok ? dry.data?.scan : undefined;
+            if (dryScan) {
+                FAM_ScanProjects_Util.progress(globals, `  becslés: ${dryScan.filesProcessed} fájl, ${dryScan.chunks} chunk, ~${dryScan.estimate?.estimatedSeconds ?? '?'}s embed`);
+            }
+            if (local.dryRun) {
+                projects.push({ project: spec.project, dryRun: dryScan });
+                okCount += dry.ok ? 1 : 0;
+                continue;
+            }
+            // 2) VALÓS scan — VÁRJUK a teljes választ (soros, nincs konkurrencia)
+            const startedAt = Date.now();
+            const real = await client.post('/api/write', FAM_ScanProjects_Util.body(spec, false, local));
+            const seconds = Math.round((Date.now() - startedAt) / 1000);
+            const realScan = real.ok ? real.data?.scan : undefined;
+            if (real.ok && realScan) {
+                okCount++;
+                FAM_ScanProjects_Util.progress(globals, `  kész: ${realScan.filesProcessed} fájl, ${realScan.chunks} chunk, ${JSON.stringify(realScan.verdicts)}, ${realScan.status} (${seconds}s)`);
+                projects.push({ project: spec.project, scan: realScan, seconds: seconds });
+            }
+            else {
+                FAM_ScanProjects_Util.progress(globals, `  HIBA: ${real.error?.message ?? 'ismeretlen scan-hiba'}`);
+                projects.push({ project: spec.project, error: real.error });
+                if (local.stopOnError) {
+                    break;
+                }
+            }
+        }
+        FAM_ScanProjects_Util.progress(globals, `=== KÉSZ: ${okCount}/${specs.length} ok ===`);
+        return fam_output_util_1.FAM_Output_Util.success({
+            options: globals, command: 'scan-projects',
+            data: { total: specs.length, ok: okCount, projects: projects },
+        });
+    }
+    /** A scan-request body egy projekt-spec-hez (dryRun vagy valós). */
+    static body(spec, dryRun, defaults) {
+        return {
+            table: spec.table ?? defaults.table ?? 'codebase',
+            operation: 'scan-project',
+            scopePath: [
+                { layer: 'organization', rawName: spec.org ?? defaults.org ?? 'FutDevPro' },
+                { layer: 'project', rawName: spec.project },
+            ],
+            scan: { path: spec.path, dryRun: dryRun },
+        };
+    }
+    /** Ember-olvasható haladás-sor a stderr-re (a `--json` stdout-ot nem szennyezi; `--quiet` esetén néma). */
+    static progress(globals, line) {
+        if (!globals.quiet) {
+            process.stderr.write(`${line}\n`);
+        }
+    }
+}
+exports.FAM_ScanProjects_Util = FAM_ScanProjects_Util;

package/build/src/_cli/_commands/scan.command.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Scan_Util = void 0;
+const fs_1 = require("fs");
+const commander_1 = require("commander");
+const fam_arg_util_1 = require("../_collections/fam-arg.util");
+const fam_output_util_1 = require("../_collections/fam-output.util");
+const fam_client_service_1 = require("../_services/fam-client.service");
+const fam_cli_const_1 = require("../_collections/fam-cli.const");
+/**
+ * `fam scan` — a `write --operation scan-*` kényelmi wrapper-e (dsgn-010 §7.3, dsgn-004). A `--path`
+ * típusa dönti el a műveletet (file → `scan-file`, dir → `scan-folder`); a `--table` opcionális (megadva
+ * mindent oda kényszerít, különben a server-router dönt: docs→documents, code→codebase). A secret-guard
+ * MINDIG hozzáadódik az `--exclude`-hoz (`.env`/kulcs/`node_modules`/`.git`; opt-out NEM megengedett).
+ */
+class FAM_Scan_Util {
+    /** A `scan` parancs-deszkriptor. */
+    static command() {
+        const command = new commander_1.Command('scan');
+        command
+            .description('Ingest egy fájlra/mappára (auto-routing docs→documents / code→codebase; dsgn-004). '
+            + '⚠️ Mappa-scan ELŐTT: készíts `.fdpfamignore`-t + ellenőrizz `--dry-run`-nal (lásd lent).')
+            .requiredOption('--path <file|dir>', 'a scan-elendő fájl vagy mappa')
+            .option('--table <documents|codebase>', 'felülírja az auto-routingot (mindent ide)')
+            .option('--include <glob,...>', 'include glob-szűrők')
+            .option('--exclude <glob,...>', 'exclude glob-szűrők (a secret-guard mellé)')
+            .option('--scope <layer=name,...>', 'scope-lánc (KÖTELEZŐ)')
+            .option('--dry-run', 'nem ír; tervezett fájl/chunk/verdikt-szám', false)
+            .addHelpText('before', '\n⚠️  TISZTA SCAN — ELŐBB az IGNORE-FÁJL:\n'
+            + '   1) Hozz létre `.fdpfamignore`-t a scan-gyökérben (a `.gitignore` mintájára) a projekt-\n'
+            + '      specifikus junk-mappákra (a default már fedi: node_modules/Library/__pycache__/\n'
+            + '      site-packages/dist/build/coverage/Logs/obj/bin + *.meta/*.csproj/*.sln).\n'
+            + '   2) Futtasd ELŐSZÖR `--dry-run`-nal: ellenőrizd a fájl/chunk-számot.\n'
+            + '   A beszkennelt junkot UTÓLAG kitakarítani (törlés + re-embed) sokkal drágább,\n'
+            + '   mint eleve tisztán szkennelni.\n')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Scan_Util.run(command));
+        });
+        return command;
+    }
+    /** A `scan` futtatása: path-típus → operation, secret-guard merge, `POST /api/write`. */
+    static async run(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        const scopePath = fam_arg_util_1.FAM_Arg_Util.parseScope(local.scope);
+        if (!scopePath) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'scan',
+                error: {
+                    errorCode: 'FAM-CLI-SCAN-001',
+                    message: 'A scan-hez --scope KÖTELEZŐ (dsgn-002 §3.2).',
+                    fixHint: 'Add meg pl.: --scope "organization=FutDevPro,project=Adventor"',
+                },
+            });
+        }
+        if (!(0, fs_1.existsSync)(local.path)) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'scan',
+                error: {
+                    errorCode: 'FAM-CLI-SCAN-002',
+                    message: `A --path nem létezik: ${local.path}.`,
+                    fixHint: 'Ellenőrizd az útvonalat (abszolút vagy a futtatási mappához relatív).',
+                },
+            });
+        }
+        const isDirectory = (0, fs_1.statSync)(local.path).isDirectory();
+        const operation = isDirectory ? 'scan-folder' : 'scan-file';
+        const exclude = [
+            ...(fam_arg_util_1.FAM_Arg_Util.parseList(local.exclude) ?? []),
+            ...fam_cli_const_1.FAM_SCAN_SECRET_GUARD,
+        ];
+        const body = {
+            table: local.table ?? 'codebase',
+            operation: operation,
+            scopePath: scopePath,
+            scan: {
+                path: local.path,
+                include: fam_arg_util_1.FAM_Arg_Util.parseList(local.include),
+                exclude: exclude,
+                dryRun: local.dryRun === true,
+            },
+        };
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        const result = await client.post('/api/write', body);
+        if (!result.ok) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'scan',
+                error: result.error ?? { errorCode: 'FAM-CLI-SCAN-003', message: 'Ismeretlen scan-hiba.' },
+                exitCode: result.unreachable ? fam_cli_const_1.FAM_CliExitCode.serverUnreachable : fam_cli_const_1.FAM_CliExitCode.operationError,
+            });
+        }
+        return fam_output_util_1.FAM_Output_Util.success({ options: globals, command: 'scan', data: result.data });
+    }
+}
+exports.FAM_Scan_Util = FAM_Scan_Util;

package/build/src/_cli/_commands/seed.command.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Seed_Util = void 0;
+const commander_1 = require("commander");
+const fam_output_util_1 = require("../_collections/fam-output.util");
+const fam_client_service_1 = require("../_services/fam-client.service");
+const fam_cli_const_1 = require("../_collections/fam-cli.const");
+/**
+ * `fam seed-example` — minta-bejegyzések seed-elése (dsgn-010 §10). A `capabilities.invoke
+ * seed_example` eszközre delegál (a server-réteg ezt is discoverable-ként expozeálja); a minta-tartalom
+ * + scope a server-oldalon van (a CLI csak triggereli). Nincs külön seed-logika a CLI-ben.
+ */
+class FAM_Seed_Util {
+    /** A `seed-example` parancs-deszkriptor (a `commandName` a top-level név). */
+    static command(commandName) {
+        const command = new commander_1.Command(commandName);
+        command
+            .description('Minta-bejegyzések seed-elése (capabilities.invoke seed_example)')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Seed_Util.run(command));
+        });
+        return command;
+    }
+    /** A seed-trigger: `POST /api/capabilities {action:invoke, name:seed_example}`. */
+    static async run(command) {
+        const globals = command.optsWithGlobals();
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        const result = await client.post('/api/capabilities', { action: 'invoke', name: 'seed_example' });
+        if (!result.ok) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'seed-example',
+                error: result.error ?? { errorCode: 'FAM-CLI-SEED-001', message: 'Ismeretlen seed-hiba.' },
+                exitCode: result.unreachable ? fam_cli_const_1.FAM_CliExitCode.serverUnreachable : fam_cli_const_1.FAM_CliExitCode.operationError,
+            });
+        }
+        return fam_output_util_1.FAM_Output_Util.success({ options: globals, command: 'seed-example', data: result.data });
+    }
+}
+exports.FAM_Seed_Util = FAM_Seed_Util;

package/build/src/_cli/_commands/serve.command.js

@@ -0,0 +1,373 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Serve_Util = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const net = tslib_1.__importStar(require("net"));
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const commander_1 = require("commander");
+const fam_console_util_1 = require("../../_collections/fam-console.util");
+const fam_output_util_1 = require("../_collections/fam-output.util");
+const fam_cli_const_1 = require("../_collections/fam-cli.const");
+const fam_client_service_1 = require("../_services/fam-client.service");
+/**
+ * `fam serve` — **állandó, leválasztott (detached) FAM REST-primary biztosítása** (ensure-szemantika). A
+ * core-architektúra javítása (user-direktíva 2026-06-21): a dev-/agent-műveletekhez a szervert NE a hívó
+ * (CLI / agent-task) **gyereke**ként futtassuk — mert akkor a hívó futásával együtt MEGHAL (és OOM-nál nincs,
+ * ami túlélje). Helyette: **megnézzük, fut-e** (`/api/health`), és ha nem, **külön processzként, leválasztva,
+ * saját ablakban** indítjuk, ami **túléli ezt a futást** — legközelebb már csak rácsatlakozunk.
+ *
+ * **Hogyan illeszkedik a meglévő mintákhoz:**
+ *   - **FEAT-002** („egy szerver, sok bridge"): ha már fut egy egészséges primary a porton → NEM indítunk
+ *     másodikat (idempotens reuse). Az MCP-kliensek külön `fam start`-ja úgyis ehhez a REST-primary-hoz
+ *     bridge-el.
+ *   - **FEAT-001** (activity-konzol): a detach-olt szerver a saját, látható activity-ablakát nyitja (a
+ *     `fam-activity-<port>.log` tail-je) → ez a „fixen megnyíló ablak, ami mindig fut". A tee `fs`-sel a
+ *     fájlba ír, így `stdio:'ignore'` mellett is működik.
+ *
+ * A boot **REST-only** (a belépő argumentum-nélküli ága): tiszta HTTP-primary, MCP-stdio nélkül (a detach-olt
+ * processnek nincs stdin-kliense). A heap-plafon a nagy korpusz boot-hidratálásához emelt (`--max-old-space-size`,
+ * default 16 GB; `--heap`/`FAM_MAX_OLD_SPACE_MB`). `--foreground` → attached futás (debug). `--status` → csak
+ * ellenőrzés (sosem indít).
+ */
+class FAM_Serve_Util {
+    /** A REST-primary default portja (a belépő `FAM_SERVER_PORT`-jával egyezik). */
+    static DEFAULT_PORT = 39265;
+    /** A detach-olt szerver default heap-plafonja MB-ban (a nagy pool-hidratáláshoz; vö. `FAM_Start_Util`). */
+    static DEFAULT_HEAP_MB = 16384;
+    /** A health-bevárás default felső korlátja (s) — a boot + Mongo-connect + pool-hidratálás ennyi alatt. */
+    static DEFAULT_WAIT_SEC = 40;
+    /** A health-poll periódusa (ms) a detach-olt boot bevárásakor. */
+    static HEALTH_POLL_MS = 1000;
+    /** Az utolsó `fam serve` indítás állapot-fájlja (port + db + heap) — a `--restart`/auto-restart innen tudja, mit. */
+    static STATE_FILE = (0, path_1.join)((0, os_1.tmpdir)(), 'fam-serve-state.json');
+    /** A `serve` parancs-deszkriptor. */
+    static command() {
+        const command = new commander_1.Command('serve');
+        command
+            .description('Állandó, leválasztott (detached) FAM REST-szerver biztosítása — fut-e? ha nem, külön ablakban indítja')
+            .option('--port <port>', 'REST-port (env: FAM_SERVER_PORT)', undefined)
+            .option('--heap <mb>', 'heap-plafon MB (env: FAM_MAX_OLD_SPACE_MB; 0 → node-default)', undefined)
+            .option('--wait <seconds>', 'health-bevárás felső korlátja (s)', undefined)
+            .option('--status', 'csak ellenőrzés: fut-e? (sosem indít)', false)
+            .option('--restart', 'a futó szerver leállítása + újraindítása (dev)', false)
+            .option('--foreground', 'attached futás (ne detacheljen, ne nyisson ablakot — debug)', false)
+            .option('--mongodb-uri <uri>', 'Mongo connection string (env-felülírás)')
+            .option('--db-name <name>', 'Mongo DB-név (env-felülírás)')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Serve_Util.run(command));
+        });
+        return command;
+    }
+    /**
+     * A tiszta indítási döntés (a spawn/HTTP ELŐTT, unit-tesztelhető). `--status` SOSEM indít (csak riport:
+     * fut → `reuse-running`, nem-fut → `report-down`). Egyébként: ha fut + `--restart` → `restart`; ha fut →
+     * `reuse-running` (idempotens); ha nem fut → `spawn` (a `--restart` nem-futó szervernél = sima spawn).
+     */
+    static decideAction(set) {
+        if (set.statusOnly) {
+            return set.reachable ? 'reuse-running' : 'report-down';
+        }
+        if (set.reachable) {
+            return set.restart ? 'restart' : 'reuse-running';
+        }
+        return 'spawn';
+    }
+    /** A REST-port feloldása (`--port` → `FAM_SERVER_PORT` → default 39265). Érvénytelen → default. */
+    static resolvePort(override) {
+        const raw = override ?? process.env.FAM_SERVER_PORT;
+        if (raw === undefined || String(raw).trim() === '') {
+            return FAM_Serve_Util.DEFAULT_PORT;
+        }
+        const parsed = Number(raw);
+        return Number.isInteger(parsed) && parsed > 0 && parsed < 65536 ? parsed : FAM_Serve_Util.DEFAULT_PORT;
+    }
+    /** A heap-plafon (MB) feloldása (`--heap` → `FAM_MAX_OLD_SPACE_MB` → default 16384). `0`/érvénytelen → 0 (node-default). */
+    static resolveHeapMb(override) {
+        const raw = override ?? process.env.FAM_MAX_OLD_SPACE_MB;
+        if (raw === undefined || String(raw).trim() === '') {
+            return FAM_Serve_Util.DEFAULT_HEAP_MB;
+        }
+        const parsed = Number(raw);
+        return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0;
+    }
+    /** A health-bevárás felső korlátja ms-ban (`--wait` s → ms; default 40s). Érvénytelen → default. */
+    static resolveWaitMs(override) {
+        if (override === undefined || String(override).trim() === '') {
+            return FAM_Serve_Util.DEFAULT_WAIT_SEC * 1000;
+        }
+        const parsed = Number(override);
+        return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed * 1000) : FAM_Serve_Util.DEFAULT_WAIT_SEC * 1000;
+    }
+    /** A teljes parancs-folyamat: health-check → döntés → reuse / status-riport / detached-spawn → health-bevárás. */
+    static async run(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        // `--restart` explicit `--port`/env nélkül → az UTOLSÓ indított szerver állapotából (port + db + heap),
+        // hogy a `fam serve --restart` (és az opt-in post-commit auto-restart) a HELYES szervert állítsa vissza
+        // (nem vakon a default 39265-öt). Az explicit flag-ek mindig győznek.
+        const lastState = local.restart && !local.port && !process.env.FAM_SERVER_PORT ? FAM_Serve_Util.loadServeState() : null;
+        if (lastState) {
+            if (!local.dbName) {
+                local.dbName = lastState.dbName;
+            }
+            if (!local.mongodbUri) {
+                local.mongodbUri = lastState.mongodbUri;
+            }
+            if (!local.heap && lastState.heapMb) {
+                local.heap = String(lastState.heapMb);
+            }
+        }
+        const port = lastState?.port ?? FAM_Serve_Util.resolvePort(local.port);
+        const healthUrl = `http://127.0.0.1:${port}`;
+        const client = new fam_client_service_1.FAM_CliClient_Service(healthUrl);
+        const reachable = await client.isReachable();
+        const action = FAM_Serve_Util.decideAction({
+            reachable: reachable,
+            statusOnly: Boolean(local.status),
+            restart: Boolean(local.restart),
+        });
+        if (action === 'reuse-running') {
+            const version = await FAM_Serve_Util.fetchVersion(client);
+            return fam_output_util_1.FAM_Output_Util.success({
+                options: globals,
+                command: 'serve',
+                data: { running: true, spawned: false, url: healthUrl, port: port, version: version },
+                humanFormatter: () => `✓ A FAM szerver MÁR FUT (reuse — nem indítok másodikat): ${healthUrl}${version ? ` — v${version}` : ''}`,
+            });
+        }
+        if (action === 'report-down') {
+            return fam_output_util_1.FAM_Output_Util.success({
+                options: globals,
+                command: 'serve',
+                data: { running: false, spawned: false, url: healthUrl, port: port, version: null },
+                humanFormatter: () => `• A FAM szerver NEM fut ezen a porton: ${healthUrl} (--status → nem indítok).`,
+            });
+        }
+        if (action === 'restart') {
+            fam_output_util_1.FAM_Output_Util.logInfo(globals, `FAM szerver RESTART: a(z) ${port} porton futó szerver leállítása…`);
+            await FAM_Serve_Util.stopServerOnPort(port);
+            // A health-down NEM elég: az új szerver bind-preflight-je a TÉNYLEGESEN SZABAD (bindolható) portot
+            // igényli (a kill utáni process-halál + TIME_WAIT lassú lehet) → a port bindolhatóságát várjuk.
+            const freed = await FAM_Serve_Util.waitForPortFree(port, 12000);
+            if (!freed) {
+                fam_output_util_1.FAM_Output_Util.logInfo(globals, `⚠ a(z) ${port} port 12s alatt nem szabadult fel — az indítás megpróbálom, `
+                    + 'de ha bind-hiba van, futtasd újra a `fam serve --restart`-ot.');
+            }
+        }
+        return FAM_Serve_Util.spawnServer({ globals: globals, local: local, port: port, healthUrl: healthUrl, client: client });
+    }
+    /** Az új szerver indítása (detached default, vagy `--foreground`) + a health-bevárás + a riport. */
+    static async spawnServer(set) {
+        const entry = FAM_Serve_Util.resolveServerEntry();
+        if (!entry) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: set.globals,
+                command: 'serve',
+                error: {
+                    errorCode: 'FAM-CLI-SERVE-001',
+                    message: 'A FAM szerver-belépő nem található (build/src/index.js).',
+                    fixHint: 'Buildeld a szervert (`cd server && pnpm run build-base`), vagy állítsd be a `FAM_SERVER_ENTRY` env-et.',
+                },
+            });
+        }
+        // A window-/foreground-szerver env-override-jai (a többit a szerver a saját `.env`-jéből olvassa):
+        // FAM_SHOW_CONSOLE=false → NINCS külön FEAT-001 tail-ablak (a serve-ablak MAGA a látható konzol → nincs
+        // dupla ablak; a user-direktíva szerint az Activity Monitor így redundáns).
+        const envOverrides = {
+            FAM_SERVER_PORT: String(set.port),
+            FAM_SHOW_CONSOLE: 'false',
+            // File-log → a detached szerver logjai (import-progress is) FÁJLBÓL OLVASHATÓK (tail), ablak nélkül.
+            FAM_LOG_FILE: (0, path_1.join)((0, os_1.tmpdir)(), `fam-server-${set.port}.log`),
+        };
+        if (set.local.mongodbUri) {
+            envOverrides.MONGODB_URI = set.local.mongodbUri;
+        }
+        if (set.local.dbName) {
+            envOverrides.MONGODB_DB_NAME = set.local.dbName;
+        }
+        const heapMb = FAM_Serve_Util.resolveHeapMb(set.local.heap);
+        const nodeArgs = heapMb > 0 ? [`--max-old-space-size=${heapMb}`] : [];
+        const detached = !set.local.foreground;
+        fam_output_util_1.FAM_Output_Util.logInfo(set.globals, `FAM szerver indítása (${detached ? 'DETACHED — külön, látható ablak, túléli a CLI-t' : 'foreground (attached)'}): `
+            + `node ${nodeArgs.join(' ')} ${entry}  (REST :${set.port}, heap ${heapMb > 0 ? `${heapMb}MB` : 'node-default'}).`);
+        if (!detached) {
+            // Foreground (debug): a child stdio inherit, a CLI a process-exit-kódját örökli (vö. `FAM_Start_Util`).
+            return FAM_Serve_Util.runForeground([...nodeArgs, entry], { ...process.env, ...envOverrides });
+        }
+        // DETACHED: a szervert egy KÜLÖN, LÁTHATÓ konzol-ablakban indítjuk (a `start`/terminál teljesen leválasztja
+        // a CLI-ről → túléli; az ablak a szerver élő stdout/stderr-jét mutatja). REST-only primary (a belépő
+        // argumentum-nélküli ága). A FEAT-001 tail-monitort kikapcsoljuk (FAM_SHOW_CONSOLE=false) — nincs dupla ablak.
+        try {
+            fam_console_util_1.FAM_Console_Util.spawnServerWindow({
+                command: process.execPath,
+                args: [...nodeArgs, entry],
+                envOverrides: envOverrides,
+                port: set.port,
+            });
+        }
+        catch (spawnError) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: set.globals,
+                command: 'serve',
+                error: {
+                    errorCode: 'FAM-CLI-SERVE-002',
+                    message: `A szerver-ablak nem indítható: ${spawnError.message}.`,
+                    fixHint: 'Futtasd `fam serve --foreground`-dal (attached, ablak nélkül) a hiba láttatásához.',
+                },
+            });
+        }
+        const waitMs = FAM_Serve_Util.resolveWaitMs(set.local.wait);
+        const healthy = await FAM_Serve_Util.waitForHealthy(set.client, waitMs);
+        if (!healthy) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: set.globals,
+                command: 'serve',
+                error: {
+                    errorCode: 'FAM-CLI-SERVE-003',
+                    message: `Megnyitottam a szerver-ablakot, de ${Math.round(waitMs / 1000)}s alatt nem lett egészséges: ${set.healthUrl}/api/health.`,
+                    fixHint: 'Nézd a megnyílt szerver-ablakot (a boot-hibák ott láthatók). Gyakori ok: a Mongo nem fut, vagy a pool-hidratálás hosszabb (emeld a `--wait`-et).',
+                },
+            });
+        }
+        // Az indítás állapotának mentése → a `fam serve --restart` (és az opt-in post-commit auto-restart)
+        // a HELYES portot/db-t/heap-et állítja vissza, nem vakon a default-ot.
+        FAM_Serve_Util.writeServeState({
+            port: set.port,
+            dbName: set.local.dbName,
+            mongodbUri: set.local.mongodbUri,
+            heapMb: heapMb,
+        });
+        const version = await FAM_Serve_Util.fetchVersion(set.client);
+        return fam_output_util_1.FAM_Output_Util.success({
+            options: set.globals,
+            command: 'serve',
+            data: { running: true, spawned: true, detached: true, url: set.healthUrl, port: set.port, heapMb: heapMb, version: version },
+            humanFormatter: () => `✓ FAM szerver elindítva (DETACHED, külön látható ablak${version ? `, v${version}` : ''}): ${set.healthUrl} — túléli ezt a futást, legközelebb csak rácsatlakozom.`,
+        });
+    }
+    /** Attached (`--foreground`) futás: a child stdio inherit, a CLI a process-exit-kódját örökli. */
+    static runForeground(args, childEnv) {
+        const child = (0, child_process_1.spawn)(process.execPath, args, { stdio: 'inherit', env: childEnv });
+        return new Promise((resolvePromise) => {
+            child.on('error', (spawnError) => {
+                fam_output_util_1.FAM_Output_Util.logError(`✗ A szerver-process nem indítható: ${spawnError.message}`);
+                resolvePromise(fam_cli_const_1.FAM_CliExitCode.operationError);
+            });
+            child.on('exit', (code) => {
+                resolvePromise(code === 0 || code === null ? fam_cli_const_1.FAM_CliExitCode.ok : fam_cli_const_1.FAM_CliExitCode.operationError);
+            });
+        });
+    }
+    /** A `/api/health` zöldre-fordulásának bevárása (poll), felső korláttal. `true`, ha időben egészséges lett. */
+    static async waitForHealthy(client, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (await client.isReachable(1500)) {
+                return true;
+            }
+            await FAM_Serve_Util.sleep(FAM_Serve_Util.HEALTH_POLL_MS);
+        }
+        return false;
+    }
+    /** A port LE-állásának bevárása (a `--restart` kill után, mielőtt újraindítunk), felső korláttal. */
+    static async waitForPortFree(port, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (await FAM_Serve_Util.isPortFree(port)) {
+                return true;
+            }
+            await FAM_Serve_Util.sleep(FAM_Serve_Util.HEALTH_POLL_MS);
+        }
+        return false;
+    }
+    /** Bindolható-e (szabad-e) a port? Egy próba-`listen` a loopbackon, azonnali close — `true`, ha köthető. */
+    static isPortFree(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 megadott porton FIGYELŐ process leállítása (a `--restart` magja). Platform-natív, fail-safe: Windows →
+     * `Get-NetTCPConnection`+`Stop-Process`; POSIX → `lsof -ti:<port> | xargs kill`. A hiba nem dob (a respawn
+     * a port-bevárással úgyis kezeli, ha mégis él valami).
+     */
+    static async stopServerOnPort(port) {
+        const isWin = process.platform === 'win32';
+        const command = isWin ? (process.env.ComSpec ?? 'powershell.exe') : 'sh';
+        const psScript = `$ErrorActionPreference='SilentlyContinue';`
+            + `(Get-NetTCPConnection -LocalPort ${port} -State Listen).OwningProcess | Select-Object -Unique | `
+            + `ForEach-Object { Stop-Process -Id $_ -Force };`
+            // A serve-ablakot (a fam-server-<port>.ps1-t futtató powershell) is leállítjuk → nincs árva,
+            // „[FAM szerver kilépett]" zombi-ablak a restart után (különben halmozódnak).
+            + `Get-CimInstance Win32_Process -Filter "Name='powershell.exe'" | `
+            + `Where-Object { $_.CommandLine -like '*fam-server-${port}*' } | `
+            + `ForEach-Object { Stop-Process -Id $_.ProcessId -Force }`;
+        const args = isWin
+            ? ['-NoProfile', '-Command', psScript]
+            : ['-c', `lsof -ti tcp:${port} | xargs -r kill -9`];
+        const exe = isWin ? 'powershell.exe' : command;
+        await new Promise((resolveKill) => {
+            try {
+                const child = (0, child_process_1.spawn)(exe, args, { stdio: 'ignore' });
+                child.on('error', () => resolveKill());
+                child.on('exit', () => resolveKill());
+            }
+            catch {
+                resolveKill();
+            }
+        });
+    }
+    /** A futó szerver verziója a `GET /api/health` `version` mezőjéből (vagy `null`, ha nem elérhető). Fail-safe. */
+    static async fetchVersion(client) {
+        const result = await client.get('/api/health');
+        return result.ok && result.data && typeof result.data.version === 'string' ? result.data.version : null;
+    }
+    /** Az indítás-állapot mentése (fail-safe — a state-write SOHA nem dönti meg a parancsot). */
+    static writeServeState(state) {
+        try {
+            (0, fs_1.writeFileSync)(FAM_Serve_Util.STATE_FILE, JSON.stringify(state));
+        }
+        catch {
+            /* a state-fájl hibája nem kritikus (a --restart ekkor a default-ra esik vissza) */
+        }
+    }
+    /** Az utolsó indítás-állapot betöltése (vagy `null`, ha nincs/olvashatatlan). Fail-safe. */
+    static loadServeState() {
+        try {
+            if (!(0, fs_1.existsSync)(FAM_Serve_Util.STATE_FILE)) {
+                return null;
+            }
+            const parsed = JSON.parse((0, fs_1.readFileSync)(FAM_Serve_Util.STATE_FILE, 'utf8'));
+            return typeof parsed.port === 'number' && parsed.port > 0 ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Egyszerű ms-alvás (a health-poll köze). */
+    static sleep(ms) {
+        return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+    }
+    /** A szerver-belépő feloldása (env → resolve → repo-relatív; a publikus boundary szerint spawn, nem import). */
+    static resolveServerEntry() {
+        const fromEnv = process.env.FAM_SERVER_ENTRY;
+        if (fromEnv && (0, fs_1.existsSync)(fromEnv)) {
+            return fromEnv;
+        }
+        // A serve a SZERVER-package CLI-jában él: a serve.command.js futás-időben
+        // `<server>/build/src/_cli/_commands/`, így a belépő (`<server>/build/src/index.js`) 2 szint feljebb.
+        const candidates = [
+            (0, path_1.resolve)(__dirname, '../../index.js'),
+            (0, path_1.resolve)(process.cwd(), 'build/src/index.js'),
+            (0, path_1.resolve)(process.cwd(), 'server/build/src/index.js'),
+        ];
+        return candidates.find((candidate) => (0, fs_1.existsSync)(candidate));
+    }
+}
+exports.FAM_Serve_Util = FAM_Serve_Util;