@futdevpro/fdp-agent-memory 0.1.0 → 1.1.12

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

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Start_Util = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const commander_1 = require("commander");
+const fam_output_util_1 = require("../_collections/fam-output.util");
+const fam_cli_const_1 = require("../_collections/fam-cli.const");
+/**
+ * `fam start` — az MCP-szerver indítása **stdio** transporton (dsgn-010 §6, dsgn-003 §1). A szerver a
+ * `build/src/index.js start`-on indul (a 3 hirdetett eszközzel: read/write/capabilities). stdio módban a
+ * **stdout a JSON-RPC csatorna** → minden CLI-/szerver-log a **stderr**-re; a `--json` itt NEM értelmezett
+ * (a transport maga JSON-RPC). A CLI maga NEM daemonizál (a process-menedzsment a hívóé / az MCP-kliensé).
+ *
+ * A szerver-belépő feloldása (a publikus boundary szerint a CLI NEM importálja a szerver-kódot, csak
+ * spawn-olja): a `FAM_SERVER_ENTRY` env, különben a node_modules-beli telepített
+ * `@futdevpro/fdp-agent-memory/build/src/index.js`, különben a repo-relatív `../server/build/src/index.js`.
+ *
+ * A `start-server` setup-alias erre delegál (dsgn-010 §10).
+ */
+class FAM_Start_Util {
+    /** A `start` parancs-deszkriptor. */
+    static command() {
+        const command = new commander_1.Command('start');
+        command
+            .description('Az MCP-szerver indítása stdio-transporton (read/write/capabilities)')
+            .option('--transport <stdio>', 'transport (MVP1: csak stdio)', 'stdio')
+            .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)')
+            .option('--log-level <level>', 'log-szint')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Start_Util.run(command));
+        });
+        return command;
+    }
+    /** A `start-server` delegáló alias (dsgn-010 §10) — a `start`-ra fut. */
+    static aliasCommand(aliasName) {
+        const command = new commander_1.Command(aliasName);
+        command
+            .description('(alias) a `fam start` — MCP-szerver stdio-n')
+            .option('--transport <stdio>', 'transport (MVP1: csak stdio)', 'stdio')
+            .option('--mongodb-uri <uri>', 'Mongo connection string')
+            .option('--db-name <name>', 'Mongo DB-név')
+            .option('--log-level <level>', 'log-szint')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Start_Util.run(command));
+        });
+        return command;
+    }
+    /** A szerver-process spawn-olása (`node <entry> start`); a CLI a process-exit-kódját örökli. */
+    static async run(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        const entry = FAM_Start_Util.resolveServerEntry();
+        if (!entry) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'start',
+                error: {
+                    errorCode: 'FAM-CLI-START-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.',
+                },
+            });
+        }
+        const childEnv = { ...process.env };
+        if (local.mongodbUri) {
+            childEnv.MONGODB_URI = local.mongodbUri;
+        }
+        if (local.dbName) {
+            childEnv.MONGODB_DB_NAME = local.dbName;
+        }
+        if (local.logLevel) {
+            childEnv.LOG_LEVEL = local.logLevel;
+        }
+        // FAM-REV-062: a vektor-pool boot-hidratálása (sok ezer 2560-dim vektor) memória-igényes; a nagy
+        // korpuszon (teljes CURSOR felé) a default ~4GB heap OOM-közelbe ér (igazolt heap-WARNING 93%). A
+        // spawnolt szerver heap-plafonját megemeljük (`--max-old-space-size`, MB). Hangolható: `FAM_MAX_OLD_SPACE_MB`
+        // (default 8192); `0`/üres → node-default (constrained gépeken). A flag a SCRIPT ELŐTT kell (node-CLI flag).
+        const nodeArgs = [];
+        const heapMb = FAM_Start_Util.resolveHeapMb();
+        if (heapMb > 0) {
+            nodeArgs.push(`--max-old-space-size=${heapMb}`);
+            fam_output_util_1.FAM_Output_Util.logInfo(globals, `FAM szerver heap-plafon: --max-old-space-size=${heapMb}MB (FAM_MAX_OLD_SPACE_MB).`);
+        }
+        fam_output_util_1.FAM_Output_Util.logInfo(globals, `FAM szerver indítása (stdio): node ${nodeArgs.join(' ')} ${entry} start`);
+        // stdio: a child stdin/stdout a JSON-RPC csatorna (inherit), a stderr is inherit (logok).
+        const child = (0, child_process_1.spawn)(process.execPath, [...nodeArgs, entry, 'start'], {
+            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 spawnolt szerver heap-plafonja MB-ban (FAM-REV-062). `FAM_MAX_OLD_SPACE_MB` env felülírja; default 8192.
+     * `0` (vagy nem-pozitív / nem-szám) → 0 (= ne adjunk flag-et, node-default heap — constrained gépeken hasznos).
+     */
+    static resolveHeapMb() {
+        const raw = process.env.FAM_MAX_OLD_SPACE_MB;
+        if (raw === undefined || raw.trim() === '') {
+            return 16384;
+        }
+        const parsed = Number(raw);
+        return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0;
+    }
+    /** 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 build-layout (tsconfig `rootDir: ./src` → `build/_commands/start.command.js`): a `__dirname`
+        // futás-időben `<cli>/build/_commands`, így a CLI-gyökér 2, a repo-gyökér 3 szint feljebb.
+        const candidates = [
+            // A telepített publikus package belépője (a `@futdevpro/fdp-agent-memory` bin) — a CLI
+            // node_modules-jában (a workspace-ben szibling-csomagként).
+            (0, path_1.resolve)(__dirname, '../../node_modules/@futdevpro/fdp-agent-memory/build/src/index.js'),
+            // Repo-relatív fallback (a CLI build-jéből a sibling server/).
+            (0, path_1.resolve)(__dirname, '../../../server/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_Start_Util = FAM_Start_Util;

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

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Stats_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 stats` — a high-level stats aggregátum CLI-tükre (dsgn-010 §11.2, dsgn-011 §3). `--table` nélkül
+ * minden fő tár (`GET /api/stats`: elem-szám, embedding-státusz, utolsó ingest, üres/ok jelzés);
+ * `--table <t>` az adott tár részletei (`GET /api/stats/:table`); `--scopes` a scope-fát kérné a
+ * capability-eszközről (`get_scope_tree`, late-bind MP-12 → addig jelzett).
+ */
+class FAM_Stats_Util {
+    /** A `stats` parancs-deszkriptor. */
+    static command() {
+        const command = new commander_1.Command('stats');
+        command
+            .description('Tár- és scope-szintű statisztika (count/ingest/vektor-státusz/embedding-költség)')
+            .option('--table <table>', 'egy tár részletes statja')
+            .option('--scopes', 'scope-fa + layer-statisztikák (get_scope_tree)', false)
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Stats_Util.run(command));
+        });
+        return command;
+    }
+    /** A `stats` futtatása: `--table`/`--scopes` → a megfelelő REST/capability-hívás. */
+    static async run(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        if (local.scopes) {
+            // A scope-fa a capability-eszközön át (a `/api/stats` REST nem adja).
+            const scopeResult = await client.post('/api/capabilities', { action: 'invoke', name: 'get_scope_tree' });
+            return FAM_Stats_Util.render(globals, scopeResult);
+        }
+        const path = local.table ? `/api/stats/${encodeURIComponent(local.table)}` : '/api/stats';
+        const result = await client.get(path);
+        return FAM_Stats_Util.render(globals, result);
+    }
+    /** Közös render (unreachable → 3, egyébként 1/0). */
+    static render(globals, result) {
+        if (!result.ok) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'stats',
+                error: result.error ?? { errorCode: 'FAM-CLI-STATS-001', message: 'Ismeretlen stats-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: 'stats', data: result.data });
+    }
+}
+exports.FAM_Stats_Util = FAM_Stats_Util;

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

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Write_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");
+/** A scope-kötelező write-műveletek (dsgn-002 §3.2). */
+const SCOPE_REQUIRED_OPERATIONS = [
+    'create', 'scan-file', 'scan-folder', 'scan-project', 'import',
+];
+/**
+ * `fam write` — a dsgn-003 §3 `write` MCP-tool / `POST /api/write` REST CLI-tükre (dsgn-010 §7.2).
+ * MINDIG pontosan **1** `--table`; a `--scope` KÖTELEZŐ `create`/`scan-*`/`import`-nál. A `delete`
+ * soft-delete default (dsgn-001 §8). A CLI csak flag→server-input map (nincs külön write-logika).
+ */
+class FAM_Write_Util {
+    /** A `write` parancs-deszkriptor. */
+    static command() {
+        const command = new commander_1.Command('write');
+        command
+            .description('Explicit, 1-táras írás (create/update/delete/scan-*/re-embed/import; dsgn-003 §3). '
+            + '⚠️ scan-folder/scan-project ELŐTT: `.fdpfamignore` a scan-gyökérbe + ellenőrzés `--scan-dry-run`-nal '
+            + '(vagy használd a `fam scan` parancsot, ott a részletes figyelmeztetés) — tisztán szkennelni olcsóbb.')
+            .requiredOption('--table <table>', 'pontosan egy fő tár (vagy reference)')
+            .requiredOption('--operation <op>', 'create|update|delete|scan-file|scan-folder|scan-project|re-embed|import')
+            .option('--scope <layer=name,...>', 'scope-lánc (KÖTELEZŐ create/scan-*/import-nál)')
+            .option('--kind <kind>', 'kind')
+            .option('--tags <tag,...>', 'tagek')
+            .option('--weight <f>', 'retrieval-súly')
+            .option('--importance <f>', 'kvalitatív hangsúly (0..1)')
+            .option('--content <text>', 'inline tartalom (create/update)')
+            .option('--file <path>', 'tartalom fájlból (create/update)')
+            .option('--target-by <id|sourceFilePath|query>', 'update/delete cél-azonosítás módja')
+            .option('--target-value <v>', 'update/delete cél-azonosító érték')
+            .option('--dry-run', 'nem ír, csak a tervezett hatást jelzi', false)
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Write_Util.run(command));
+        });
+        return command;
+    }
+    /** A `write` futtatása: a flag-ek → `POST /api/write` input + scope-kötelezőség-ellenőrzés. */
+    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 (SCOPE_REQUIRED_OPERATIONS.includes(local.operation) && !scopePath) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'write',
+                error: {
+                    errorCode: 'FAM-CLI-WRITE-001',
+                    message: `A(z) '${local.operation}' művelethez --scope KÖTELEZŐ (dsgn-002 §3.2).`,
+                    fixHint: 'Add meg pl.: --scope "organization=FutDevPro,project=Adventor"',
+                },
+            });
+        }
+        let content = local.content;
+        if (local.file) {
+            try {
+                content = (0, fs_1.readFileSync)(local.file, 'utf-8');
+            }
+            catch (fileError) {
+                return fam_output_util_1.FAM_Output_Util.failure({
+                    options: globals,
+                    command: 'write',
+                    error: {
+                        errorCode: 'FAM-CLI-WRITE-002',
+                        message: `A --file nem olvasható: ${local.file} (${fileError.message}).`,
+                    },
+                });
+            }
+        }
+        const body = {
+            table: local.table,
+            operation: local.operation,
+            scopePath: scopePath,
+            kind: local.kind,
+            tags: fam_arg_util_1.FAM_Arg_Util.parseList(local.tags),
+            content: content,
+            weight: local.weight ? Number(local.weight) : undefined,
+            importance: local.importance ? Number(local.importance) : undefined,
+            target: local.targetBy && local.targetValue
+                ? { by: local.targetBy, value: local.targetValue }
+                : undefined,
+            scan: local.dryRun ? { path: '', dryRun: true } : undefined,
+        };
+        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: 'write',
+                error: result.error ?? { errorCode: 'FAM-CLI-WRITE-003', message: 'Ismeretlen write-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: 'write', data: result.data });
+    }
+}
+exports.FAM_Write_Util = FAM_Write_Util;

package/build/src/_cli/_models/interfaces/fam-cli-global-options.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/src/_cli/_models/interfaces/fam-cli-output.interface.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * A CLI egységes kimenet- és hiba-shape-jei (dsgn-010 §3/§12). Egy fájlban a szorosan összetartozó
+ * burok-/hiba-interfészek (a `*.interface.ts` az egy-export-per-file konvenció ismert kivétele).
+ *
+ * Minden `--json` parancs-kimenet a `FAM_CliEnvelope` burokban jelenik meg a stdout-on (és semmi más a
+ * stdout-on); minden log/diag a stderr-re megy, hogy a `… --json | jq` pipe tiszta legyen.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/src/_cli/_models/interfaces/fam-client-result.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/src/_cli/_services/fam-client.service.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_CliClient_Service = void 0;
+const fam_cli_const_1 = require("../_collections/fam-cli.const");
+/**
+ * `FAM_CliClient_Service` — a CLI → szerver elérési réteg (dsgn-010 §9). A `read`/`write`/`scan`/
+ * `stats`/`errors`/`config`/`capabilities` parancsok ezen át hívják a futó szerver REST-felületét
+ * (`FAM_SERVER_URL`/`--server-url`, default `http://127.0.0.1:39265`), így öröklik a szerver
+ * Mongo-kapcsolatát + hidratált vektor-pool-ját.
+ *
+ * **Elérhetőség (dsgn-010 §9):** ha a remote szerver nem elérhető → `unreachable:true` (a hívó exit `3`
+ * + fix-tipp). **Hiba-átvitel (dsgn-008):** a server `{ ok:false, error:{errorCode,message} }` testjét a
+ * CLI NEM nyeli el — a `FAM_ClientResult.error`-ba viszi tovább.
+ *
+ * > MVP1: a dsgn-010 §9 **embedded one-shot** fallback (in-process `App`) NINCS bekötve a CLI-be (a
+ * > szerver `App` boundary-okból nem importálható a publikus CLI-ből; lásd a riport "deferred"
+ * > szekcióját) — a data-parancsok a remote utat használják, és elérhetetlen szervernél tiszta exit `3`-at
+ * > + fix-tippet adnak (`fam start`). A `doctor` env-szintű al-checkjei szerver nélkül is futnak.
+ */
+class FAM_CliClient_Service {
+    /** A feloldott base-URL (a `/api`/`/server` útak elé). */
+    baseUrl;
+    /**
+     * @param serverUrlOverride a `--server-url` flag (felülírja az env-et); ha nincs, az env
+     *        `FAM_SERVER_URL`, különben a `FAM_DEFAULT_SERVER_URL`.
+     */
+    constructor(serverUrlOverride) {
+        const raw = serverUrlOverride || process.env.FAM_SERVER_URL || fam_cli_const_1.FAM_DEFAULT_SERVER_URL;
+        this.baseUrl = raw.replace(/\/+$/, '');
+    }
+    /** A feloldott szerver base-URL (a fix-tippekhez / diaghoz). */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    /**
+     * Elérhetőség-próba a `GET /api/health`-en (dsgn-010 §9). `true`, ha a szerver válaszol `2xx`-szel.
+     * Hibát NEM dob (a nem-elérhetőség normál állapot, amit a hívó exit `3`-ra fordít). **Timeout** (default
+     * 2000ms, `timeoutMs`-szel állítható): egy fél-halott / nem-válaszoló primary NE akassza meg határtalanul
+     * a hívót (pl. a `fam start` PRIMARY-vs-BRIDGE döntését) — timeout/abort → `false` (nem elérhető).
+     */
+    async isReachable(timeoutMs = 2000) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(`${this.baseUrl}/api/health`, { signal: controller.signal });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** `GET <path>` (a `path` a base-URL utáni rész, pl. `/api/stats`). */
+    async get(path) {
+        return this.request('GET', path);
+    }
+    /** `POST <path>` JSON-body-val (pl. `/api/read`, `/api/write`, `/api/capabilities`). */
+    async post(path, body) {
+        return this.request('POST', path, body);
+    }
+    /** `PUT <path>` JSON-body-val (a `/api/config` set). */
+    async put(path, body) {
+        return this.request('PUT', path, body);
+    }
+    /**
+     * A közös HTTP-réteg: a server-választ `FAM_ClientResult`-tá fordítja. Elérhetetlen szerver →
+     * `unreachable:true`; a `{ ok:false, error }` test → `error` átvitel; egyéb non-2xx → szintetikus
+     * `FAM_CLI-HTTP-001` (nem néma); siker → `data`.
+     */
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        let response;
+        try {
+            response = await fetch(url, {
+                method: method,
+                headers: body === undefined ? {} : { 'content-type': 'application/json' },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (networkError) {
+            return {
+                ok: false,
+                unreachable: true,
+                error: {
+                    errorCode: 'FAM-CLI-CLIENT-003',
+                    message: `A FAM szerver elérhetetlen: ${url} (${networkError.message}).`,
+                    fixHint: 'Indítsd a szervert (`fam start`), vagy adj `--server-url`-t / `FAM_SERVER_URL`-t.',
+                },
+            };
+        }
+        const payload = await this.parseBody(response);
+        if (!response.ok) {
+            return { ok: false, error: this.extractError(payload, response.status) };
+        }
+        // A szerver `{ ok:false, error }` testet is adhat 2xx-szel (a `/config` set / capabilities-invoke);
+        // ezt is hiba-átvitelnek vesszük (dsgn-008, nem nyeljük el).
+        if (this.isServerErrorBody(payload)) {
+            return { ok: false, error: this.extractError(payload, response.status) };
+        }
+        return { ok: true, data: payload };
+    }
+    /** A válasz-body JSON-ként (vagy `null`, ha üres/nem-JSON — nem dob). */
+    async parseBody(response) {
+        const text = await response.text();
+        if (!text) {
+            return null;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return { __raw: text };
+        }
+    }
+    /** `true`, ha a payload a server `{ ok:false, error }` hibatestje. */
+    isServerErrorBody(payload) {
+        if (!payload || typeof payload !== 'object') {
+            return false;
+        }
+        const candidate = payload;
+        return candidate.ok === false && typeof candidate.error === 'object' && candidate.error !== null;
+    }
+    /** A server-hibatest → `FAM_CliError` (vagy szintetikus HTTP-hiba, ha a test nem strukturált). */
+    extractError(payload, status) {
+        if (this.isServerErrorBody(payload)) {
+            const serverError = payload.error;
+            return {
+                errorCode: typeof serverError.errorCode === 'string' ? serverError.errorCode : 'FAM-CLI-HTTP-001',
+                message: typeof serverError.message === 'string' ? serverError.message : `HTTP ${status}.`,
+            };
+        }
+        return {
+            errorCode: 'FAM-CLI-HTTP-001',
+            message: `A szerver HTTP ${status}-t adott (nem strukturált hibatest).`,
+        };
+    }
+}
+exports.FAM_CliClient_Service = FAM_CliClient_Service;

package/build/src/_cli/register-commands.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFAMCommands = registerFAMCommands;
+const read_command_1 = require("./_commands/read.command");
+const write_command_1 = require("./_commands/write.command");
+const scan_command_1 = require("./_commands/scan.command");
+const scan_projects_command_1 = require("./_commands/scan-projects.command");
+const config_command_1 = require("./_commands/config.command");
+const stats_command_1 = require("./_commands/stats.command");
+const find_duplicates_command_1 = require("./_commands/find-duplicates.command");
+const errors_command_1 = require("./_commands/errors.command");
+const init_command_1 = require("./_commands/init.command");
+const doctor_command_1 = require("./_commands/doctor.command");
+const start_command_1 = require("./_commands/start.command");
+const serve_command_1 = require("./_commands/serve.command");
+const seed_command_1 = require("./_commands/seed.command");
+const import_command_1 = require("./_commands/import.command");
+const export_command_1 = require("./_commands/export.command");
+const capture_command_1 = require("./_commands/capture.command");
+/**
+ * Regisztrálja az összes FDP Agent Memory-specifikus CLI command-ot (dsgn-010 §2 `buildCli()`).
+ *
+ * A scaffold-minta szerint a globális `program` singleton-re fűzünk (a `registerDynamoCommands` generikus
+ * parancsai mellé): először a globális opció-keret (`--json` / `--server-url` / `--quiet`), majd a **10
+ * parancs-csoport** (`init`/`doctor`/`start`/`read`/`write`/`scan`/`import`/`config`/`stats`/`errors`) és a
+ * **7 delegáló setup-alias** (`validate-env`/`test-db`/`test-embedding`/`create-config`/`migrate`/
+ * `seed-example`/`start-server`). Az alias-ok NEM duplikálnak logikát — a gazdaparancs al-checkjére/
+ * lépésére delegálnak (dsgn-010 §10).
+ *
+ * Minden parancs-csoport egy `{Group}_Util` (egy-export-per-file `*.command.ts`); a globális opciókat a
+ * sub-command-handler-ek a `optsWithGlobals()`-ból olvassák.
+ */
+function registerFAMCommands(program, version) {
+    void version;
+    // --- Globális opció-keret (dsgn-010 §3): a stdout-tisztaság + a remote-elérés + a csendes mód. ---
+    program
+        .option('--json', 'gépi-olvasható JSON kimenet (minden parancsra)', false)
+        .option('--server-url <url>', 'FAM szerver REST URL (env: FAM_SERVER_URL)')
+        .option('--quiet', 'csak hibák a stderr-re', false);
+    // --- A 10 parancs-csoport + 7 delegáló setup-alias (dsgn-010 §13/1, §2/§10). ---
+    const famCommands = [
+        // 10 parancs-csoport.
+        init_command_1.FAM_Init_Util.command(),
+        doctor_command_1.FAM_Doctor_Util.command(),
+        start_command_1.FAM_Start_Util.command(),
+        serve_command_1.FAM_Serve_Util.command(),
+        read_command_1.FAM_Read_Util.command(),
+        write_command_1.FAM_Write_Util.command(),
+        scan_command_1.FAM_Scan_Util.command(),
+        scan_projects_command_1.FAM_ScanProjects_Util.command(),
+        import_command_1.FAM_Import_Util.command(),
+        export_command_1.FAM_Export_Util.command(),
+        capture_command_1.FAM_Capture_Util.command(),
+        config_command_1.FAM_Config_Util.command(),
+        stats_command_1.FAM_Stats_Util.command(),
+        find_duplicates_command_1.FAM_FindDuplicates_Util.command(),
+        errors_command_1.FAM_Errors_Util.command(),
+        // 7 delegáló alias (README copy-paste-elhetőség, nincs külön logika; dsgn-010 §10).
+        doctor_command_1.FAM_Doctor_Util.aliasCommand('validate-env', ['env']),
+        doctor_command_1.FAM_Doctor_Util.aliasCommand('test-db', ['mongodb']),
+        doctor_command_1.FAM_Doctor_Util.aliasCommand('test-embedding', ['embedding']),
+        init_command_1.FAM_Init_Util.configScaffoldAlias('create-config'),
+        import_command_1.FAM_Import_Util.aliasCommand('migrate'),
+        seed_command_1.FAM_Seed_Util.command('seed-example'),
+        start_command_1.FAM_Start_Util.aliasCommand('start-server'),
+    ];
+    for (const command of famCommands) {
+        applyExitMapping(command);
+        program.addCommand(command);
+    }
+}
+/**
+ * A dsgn-010 §3 exit-kód-mapping rákötése egy FAM parancsra ÉS minden al-parancsára (rekurzívan): a
+ * commander használati/argument-hibái `2`-vel lépnek ki (a parancs-handler-ek `0`/`1`/`3` kódjait a
+ * `process.exitCode` adja, ezeket nem érinti). A root `program` saját override-ja a top-level hibákat
+ * fedi; ez a sub-command-okat (pl. `config get`, `import claude-mem`) is befedi.
+ */
+function applyExitMapping(command) {
+    command.exitOverride((error) => {
+        const cleanExit = ['commander.help', 'commander.helpDisplayed', 'commander.version'];
+        process.exit(cleanExit.includes(error.code) ? 0 : 2);
+    });
+    for (const sub of command.commands) {
+        applyExitMapping(sub);
+    }
+}

package/build/src/_collections/config-catalog.const.js

@@ -26,8 +26,28 @@ const GLOBAL_ONLY = [fam_config_level_type_enum_1.FAM_ConfigLevel.global];
  */
 exports.SCAN_IGNORE_PATTERNS_DEFAULT = [
     '**/node_modules/**', '**/.git/**', '**/build/**', '**/dist/**', '**/coverage/**',
-    '**/*.min.js', '**/*.map', '**/.env', '**/.env.*', '**/*.pem', '**/*.key',
+    // Framework build-/futás-cache + generált kimenet (FAM-REV-056) — sosem forrás, gyakran minifikált/bináris-
+    // szerű (pl. az Angular `.angular/cache/.../babel-webpack` ezreket számláló, embed-timeout-ot okozó junk-ja).
+    '**/.angular/**', '**/.nx/**', '**/.cache/**', '**/.turbo/**', '**/.next/**', '**/.nuxt/**', '**/.svelte-kit/**',
+    // Generált report-ok / logok / teszt-artefaktumok (FAM-REV-057) — minifikált HTML / nagy JSON-log → embed-hang
+    // (pl. dynamo-ngx: 515KB playwright-report HTML, 320KB .dynamo/logs status.json, 173KB logs/cicd-report.json).
+    '**/playwright-report/**', '**/test-results/**', '**/.dynamo/**', '**/logs/**', '**/*.log', '**/*-report.json',
+    '**/*.min.js', '**/*.min.css', '**/*.map', '**/.env', '**/.env.*', '**/*.pem', '**/*.key',
     '**/*.secret', '**/secrets/**', '**/*.lock', '**/package-lock.json', '**/pnpm-lock.yaml',
+    // Python (L4) — bytecode/venv/teszt-/lint-cache + telepített csomagok (SOHA nem forrás; a `*.pyc`/`*.pyo`
+    // amúgy a binary-routing kizárja, de a mappa-szintű ignore a bejárást is megspórolja). A `src/`/`tests/`
+    // `.py` forrás MARAD.
+    '**/__pycache__/**', '**/.pytest_cache/**', '**/.mypy_cache/**', '**/.ruff_cache/**', '**/.tox/**',
+    '**/venv/**', '**/.venv/**', '**/site-packages/**', '**/*.egg-info/**', '**/.ipynb_checkpoints/**',
+    // C# / Unity (L5) — a Unity GENERÁLT cache-/build-/log-mappái (a `Library/` GB-os lehet!) + a generált
+    // projekt-fájlok + az asset-metaadat (`.meta`: assetenként EGY → óriási zaj). A `.cs` forrás az `Assets/`
+    // alatt MARAD. A mappa-nevek PascalCase-ek (Unity-konvenció), ezért EXPLICIT uppercase minták (a `logs`
+    // lowercase NEM matchelné a Unity `Logs/`-át).
+    '**/Library/**', '**/Temp/**', '**/Obj/**', '**/obj/**', '**/bin/**', '**/Logs/**', '**/Build/**', '**/Builds/**',
+    '**/.vs/**', '**/*.csproj', '**/*.sln', '**/*.meta', '**/*.unity', '**/*.prefab', '**/*.asset',
+    // A `.fdpfamignore` SAJÁT MAGÁT kizárja: ignore-spec-ként OLVASSUK (FAM_FamIgnore_Util.loadFromDir,
+    // a walk/routing megkerülésével), de SOHA nem ingesteljük content-ként (a router amúgy is skip-elné).
+    '**/.fdpfamignore',
 ];
 /**
  * A teljes katalógus (dsgn-007 §4). A kulcsok dotted-formában; a `FAM_ConfigKey` típus ebből
@@ -39,6 +59,11 @@ exports.CONFIG_CATALOG = {
         type: 'number', default: 5, min: 1, max: 200, integer: true, levels: ALL_LEVELS,
         description: 'Alap visszaadott találat-szám (CCAP DEFAULT_TOP_K=5).',
     },
+    'read.deepTopK': {
+        type: 'number', default: 25, min: 1, max: 200, integer: true, levels: ALL_LEVELS,
+        description: 'A `depth:"deep"` (mély feltárás) read-mód találat-száma: ennyit ad vissza, ha a query NEM '
+            + 'ad explicit topK-t. Sokkal több chunk/kontextus egy-egy mély feltáráshoz (a query topK felülírja).',
+    },
     'read.maxResults': {
         type: 'number', default: 50, min: 1, max: 500, integer: true, levels: ALL_LEVELS,
         description: 'A topK effektív felső korlátja (CCAP DEFAULT_PAGE_SIZE=50, cap 500).',
@@ -51,6 +76,22 @@ exports.CONFIG_CATALOG = {
         type: 'number', default: 0.0, min: 0.0, max: 1.0, levels: ALL_LEVELS,
         description: 'Minimum similarity-score küszöb (CCAP default 0 = nincs vágás).',
     },
+    'read.relevanceFloor': {
+        type: 'number', default: 0.5, min: 0.0, max: 1.0, levels: ALL_LEVELS,
+        description: 'Confidence-padló a nyers cosine score-on: a relevancia-JELZÉSEK (totalRelevant / '
+            + 'denseResults / truncated / suggestions) CSAK az e fölötti hit-eket számolják „magabiztosan '
+            + 'relevánsnak". A returnedHits ettől függetlenül best-effort (recall). Ha a legjobb score is e '
+            + 'ALATT van → a read jelzi, hogy valószínűleg nincs lefedve (north-star). Modell-függő (qwen3 '
+            + 'zaj-padló ~0.44); állítsd a provider/modell szerint.',
+    },
+    'read.importChunkWeight': {
+        type: 'number', default: 0.4, min: 0.0, max: 1.0, levels: ALL_LEVELS,
+        description: 'Az import-only chunkok (`chunkType:"imports"`) read-idejű rangsor-szorzója (FAM-REV-060). '
+            + 'A szimbólum-név query-knél az import-sorok (`import { X } from "./y"`) magas cosine-t kapnak, de '
+            + 'alacsony az ÉRTÉKük (csak import, nem definíció) → e szorzóval a `finalScore = score × weight × '
+            + 'importChunkWeight` a definíció-chunkok ALÁ rangsorolja őket. READ-time (nincs re-embed); a nyers '
+            + 'cosine score (relevancia-jelzések) NEM változik, csak a ranking. 1 = nincs csökkentés.',
+    },
     'read.denseResultRatio': {
         type: 'number', default: 2.0, min: 1.0, max: 50.0, levels: ALL_LEVELS,
         description: 'Dense-jelzés ratio-kapuja: totalRelevant >= ratio*topK → denseResults (dsgn-005 §4.2).',
@@ -125,6 +166,15 @@ exports.CONFIG_CATALOG = {
         type: 'number', default: 64, min: 1, max: 512, integer: true, levels: ALL_LEVELS,
         description: 'Embed-batch méret (token-/rate-limit védelem).',
     },
+    'embedding.taskPrefixMode': {
+        type: 'string', default: 'auto', enumValues: ['auto', 'off', 'on'], levels: ALL_LEVELS,
+        description: 'Embedding task-prefix (FEAT-004): query/document aszimmetrikus prefix '
+            + '(`search_query:` / `search_document:`) instruction-tuned modelleknek (nomic-embed-*). '
+            + '`auto` = modell-név alapján (nomic→on, openai→off; a `mock` provider MINDIG kihagyva a '
+            + 'determinizmusért); `on` = erőltetve (a nomic-sémával); `off` = soha. A prefix ÉLESÍTI a '
+            + 'szeparációt + leszállítja a zaj-padlót (a 2026-06-20 live-teszt szerint nomic-nál ~0.5–0.63 '
+            + 'a nem-kapcsolódóknál is). A séma BE-/KIKAPCSOLÁSA `re-embed`-et igényel (a doc-oldal konzisztenciájához).',
+    },
     // --- 4.4. Embedding cost — cap + warn (fogyasztó: dsgn-006 / dsgn-008) ---
     'embedding.costCapUsd': {
         type: 'number-or-null', default: null, min: 0, levels: ALL_LEVELS,
@@ -155,6 +205,22 @@ exports.CONFIG_CATALOG = {
         type: 'boolean', default: false, levels: ALL_LEVELS,
         description: 'Symlink-követés (path-traversal védelem, dsgn-004).',
     },
+    'scan.testFileWeight': {
+        type: 'number', default: 0.5, min: 0.0, max: 10.0, levels: ALL_LEVELS,
+        description: 'A teszt-/spec-fájlok (`*.spec.*` / `*.test.*`) DEFAULT retrieval-súlya (FAM-REV-058) — a próza-'
+            + 'nehéz specek különben az IMPLEMENTÁCIÓ fölé rangsorolnak. <1 → a forrás alá; explicit scan-`weights` '
+            + 'felülírja; 1 = nincs csökkentés.',
+    },
+    'scan.estimateMsPerChunk': {
+        type: 'number', default: 250, min: 1, max: 10000, integer: true, levels: ALL_LEVELS,
+        description: 'A `dryRun` pre-scan idő-becsléshez: becsült embed-idő chunkonként (ms). DURVA, gép-/modell-/'
+            + 'provider-függő — a futó scan MÉRT ETA-ja pontosítja. Kalibráld a saját embedding-sebességedhez.',
+    },
+    'scan.progressIntervalMs': {
+        type: 'number', default: 2000, min: 250, max: 60000, integer: true, levels: ALL_LEVELS,
+        description: 'A futás-közbeni scan-progress log min. időköze (ms) — a nagy scan haladását ennyente jelzi '
+            + 'a konzolon (`[famIngest]` activity-sor). A végső 100% mindig kibocsátódik.',
+    },
     // --- 4.6. Reference / scope (fogyasztó: dsgn-002) ---
     'reference.cacheTtlMs': {
         type: 'number', default: 60000, min: 0, max: 3600000, integer: true, levels: GLOBAL_ONLY,