@futdevpro/fdp-agent-memory 0.1.0 → 1.1.12

package/LICENSE

@@ -0,0 +1,21 @@
+    FDP License
+
+    Copyright (c) Future Development Program Ltd. (HU)
+
+    Permission is not granted, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

package/README.md

@@ -22,7 +22,7 @@ in-memory pool-ba hidratálódnak — **NINCS Atlas-dependencia**.
 
 > **Boundary:** **nincs auth / jogosultságkezelés** (lokális, single-user); FDP Templates package
 > nélkül (Pure Dynamo). Az MCP-transport MVP1-ben **stdio** (nincs hálózati port az MCP-felületnek;
-> a `39185`-ös port a REST/UI réteghez tartozik). HTTP/SSE transport későbbi fázis (BACKLOG).
+> a `39265`-ös port a REST/UI réteghez tartozik). HTTP/SSE transport későbbi fázis (BACKLOG).
 
 ## 2. Install
 
@@ -66,8 +66,8 @@ LMSTUDIO_EMBEDDING_MODEL=nomic-embed-text-v1.5
 # OPENAI_EMBEDDING_MODEL=text-embedding-3-large
 
 # Portok (a REST/UI réteg; NEM az MCP-stdio)
-FAM_SERVER_PORT=39185
-FAM_CLIENT_PORT=4205
+FAM_SERVER_PORT=39265
+FAM_CLIENT_PORT=4226
 ```
 
 ### Teljes env-var referencia
@@ -81,8 +81,8 @@ FAM_CLIENT_PORT=4205
 | `OPENAI_EMBEDDING_MODEL` | nem | `text-embedding-3-large` | OpenAI embedding-modell. |
 | `LMSTUDIO_BASE_URL` | ha `provider=lmstudio` | `http://127.0.0.1:1234/v1` | LM Studio OpenAI-kompatibilis endpoint. |
 | `LMSTUDIO_EMBEDDING_MODEL` | ha `provider=lmstudio` | — | A betöltött embedding-modell neve. |
-| `FAM_SERVER_PORT` | nem | `39185` | REST/UI szerver-port (NEM az MCP-stdio). |
-| `FAM_CLIENT_PORT` | nem | `4205` | Angular UI dev-port (külön kliens-app). |
+| `FAM_SERVER_PORT` | nem | `39265` | REST/UI szerver-port (NEM az MCP-stdio). |
+| `FAM_CLIENT_PORT` | nem | `4226` | Angular UI dev-port (külön kliens-app). |
 | `FAM_CONFIG_OVERRIDE` | nem | — | Opcionális boot-time config-override JSON-path (a DB-backed config-on felül). |
 
 > **A futás-idejű minőségi paraméterek (`topK` / `minScore` / chunk-méret / overlap / dense-küszöb /
@@ -197,8 +197,8 @@ fam create-config   # DB-backed config seedelése reasonable default-okkal
 fam start           # az MCP-szerver indítása stdio-n (CSAK a szerver)
 ```
 
-> `fam start` az **MCP-szervert stdio-n** ÉS a **REST/UI réteget** indítja (port `39185`). A beépített
-> **admin UI a <http://localhost:39185/api/app>** alatt érhető el — a **szerver szolgálja ki**, nincs
+> `fam start` az **MCP-szervert stdio-n** ÉS a **REST/UI réteget** indítja (port `39265`). A beépített
+> **admin UI a <http://localhost:39265/api/app>** alatt érhető el — a **szerver szolgálja ki**, nincs
 > külön kliens-process (egy `fam start` = teljes lokál felület). Ez az a parancs, amit az MCP-kliens
 > config `command`-ja is meghív. (Alternatíva: `docker compose -f docker-compose.local.yml up` —
 > ugyanez konténerből, lokál Mongo-val.)

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@futdevpro/fdp-agent-memory",
-    "version": "0.1.0",
+    "version": "1.1.12",
     "description": "Local-first, vector-backed multi-table agent memory exposed as an MCP server (read/write/capabilities). Public, FDP-Templates-free, no auth.",
     "private": false,
     "publishConfig": {
@@ -17,9 +17,9 @@
     },
     "files": [
         "build",
-        "bin",
         "client-dist",
-        "README.md"
+        "README.md",
+        "LICENSE"
     ],
     "engines": {
         "node": ">=20"
@@ -54,11 +54,12 @@
     "author": "FutDevPro",
     "license": "FDP",
     "dependencies": {
-        "@futdevpro/fsm-dynamo": "^1.16",
-        "@futdevpro/nts-dynamo": "^1.15",
+        "@futdevpro/fsm-dynamo": "^1.16.7",
+        "@futdevpro/nts-dynamo": "^1.15.72",
         "@modelcontextprotocol/sdk": "^1.12.0",
         "axios": "~1.8.1",
         "better-sqlite3": "^12.4.1",
+        "commander": "^12.1.0",
         "crypto-js": "~4.2.0",
         "dotenv": "^16.4.7",
         "express": "4.21.2",

package/build/src/_cli/_collections/fam-arg.util.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Arg_Util = void 0;
+/**
+ * `FAM_Arg_Util` — közös flag-parserek a CLI-parancsokhoz (dsgn-010 §7). A `--scope` `layer=name,...`
+ * párokká → a server `scopePath`/`scopeFilter` wire-shape-jévé (`{ layer, rawName }[]`), a `--tags`/
+ * comma-listák tömbbé, és a commander **ismételhető** opcióinak collector-függvényei (`--query`/`--tables`).
+ *
+ * Statikus util (nincs állapot) — a CLI csak flag→server-input map, NEM domain-logika (a scope-feloldás a
+ * server-réteg felelőssége; itt csak a nyers `{ layer, rawName }` shape-re alakítunk).
+ */
+class FAM_Arg_Util {
+    /**
+     * Egy `--scope "organization=FutDevPro,project=Adventor"` string → a server `FAM_RawScopeLayer[]`
+     * wire-shape-je (`{ layer, rawName }[]`). Üres / hiányzó → `undefined` (nincs scope-prefilter).
+     */
+    static parseScope(raw) {
+        if (!raw) {
+            return undefined;
+        }
+        const pairs = [];
+        for (const segment of raw.split(',')) {
+            const trimmed = segment.trim();
+            if (!trimmed) {
+                continue;
+            }
+            const eq = trimmed.indexOf('=');
+            if (eq < 0) {
+                continue;
+            }
+            pairs.push({ layer: trimmed.slice(0, eq).trim(), rawName: trimmed.slice(eq + 1).trim() });
+        }
+        return pairs.length ? pairs : undefined;
+    }
+    /** Egy comma-lista (`"a,b,c"`) → trimmelt, nem-üres tömb (vagy `undefined`). */
+    static parseList(raw) {
+        if (!raw) {
+            return undefined;
+        }
+        const items = raw.split(',').map((item) => item.trim()).filter((item) => item.length > 0);
+        return items.length ? items : undefined;
+    }
+    /** A commander ismételhető-opció collector-e (minden megjelenés a tömbbe gyűlik). */
+    static collect(value, previous) {
+        return [...previous, value];
+    }
+}
+exports.FAM_Arg_Util = FAM_Arg_Util;

package/build/src/_cli/_collections/fam-cli.const.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * FAM CLI globális konstansok (dsgn-010 §3/§9). Egy fájlban a szorosan összetartozó CLI-szintű
+ * konstansok (exit-kód-térkép, default szerver-URL, CCAP retrieval-defaultok) — ezek NEM
+ * domain-konstansok (azok a szerver-réteg SSOT-jai), csak a CLI-front-end keretértékei.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_SCAN_SECRET_GUARD = exports.FAM_DEFAULT_TOP_K = exports.FAM_DEFAULT_SERVER_URL = exports.FAM_CliExitCode = void 0;
+/**
+ * Egységes CLI exit-kódok (dsgn-010 §3). A `--json` mód a nem-`2` hibákra is `ok:false` burkot ír,
+ * így a hívó scriptek egységesen kezelhetik a kimenetet.
+ */
+var FAM_CliExitCode;
+(function (FAM_CliExitCode) {
+    /** Siker (`ok:true`). */
+    FAM_CliExitCode[FAM_CliExitCode["ok"] = 0] = "ok";
+    /** Művelet-hiba (`ok:false` + strukturált `error`). */
+    FAM_CliExitCode[FAM_CliExitCode["operationError"] = 1] = "operationError";
+    /** Használati / argument-hiba (a commander adja). */
+    FAM_CliExitCode[FAM_CliExitCode["usageError"] = 2] = "usageError";
+    /** A remote szerver elérhetetlen (`FAM_SERVER_URL`/`--server-url`). */
+    FAM_CliExitCode[FAM_CliExitCode["serverUnreachable"] = 3] = "serverUnreachable";
+})(FAM_CliExitCode || (exports.FAM_CliExitCode = FAM_CliExitCode = {}));
+/** A CLI remote default szerver-URL-je (dsgn-010 §9; `FAM_SERVER_URL` env felülírja). */
+exports.FAM_DEFAULT_SERVER_URL = 'http://127.0.0.1:39265';
+/** A retrieval top-K CCAP-örökség default-ja (dsgn-007 `read.topK`). */
+exports.FAM_DEFAULT_TOP_K = 5;
+/**
+ * A `scan` alap secret-guard exclude-mintái (dsgn-004 §security). Ezek MINDIG hozzáadódnak a
+ * felhasználói `--exclude`-hoz; opt-out NEM megengedett titok-mintákra.
+ */
+exports.FAM_SCAN_SECRET_GUARD = [
+    '**/.env',
+    '**/.env.*',
+    '**/*.pem',
+    '**/*.key',
+    '**/id_rsa*',
+    '**/node_modules/**',
+    '**/.git/**',
+];

package/build/src/_cli/_collections/fam-output.util.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Output_Util = void 0;
+const fam_cli_const_1 = require("./fam-cli.const");
+/**
+ * `FAM_Output_Util` — a CLI egységes kimenet- és exit-kód-rétege (dsgn-010 §3/§12). MINDEN parancs ezen
+ * át ír: a `--json` mód a stdout-ra KIZÁRÓLAG egyetlen JSON-burkot tesz (a `… --json | jq` pipe-tisztaság
+ * invariáns), minden log/diag a stderr-re megy. Néma hiba TILOS (dsgn-008): a hibák strukturált
+ * `FAM_CliError`-rá fordulnak és mindig megjelennek (default- és `--json`-kimeneten is).
+ *
+ * Statikus util (nincs állapot, nincs függőség) — a workspace-konvenció szerinti util-service.
+ */
+class FAM_Output_Util {
+    /** Egy nem-blokkoló diag-sor a stderr-re (a `--quiet` elnyomja). */
+    static logInfo(options, line) {
+        if (!options.quiet) {
+            process.stderr.write(`${line}\n`);
+        }
+    }
+    /** Egy hiba-sor a stderr-re (a `--quiet` NEM nyomja el — hibák mindig láthatók). */
+    static logError(line) {
+        process.stderr.write(`${line}\n`);
+    }
+    /**
+     * Siker-kimenet: a parancs-payload + opcionális warning/uncertainty. `--json` → egyetlen burok a
+     * stdout-ra; különben a `humanFormatter`-rel formázott szöveg (ha nincs formatter, a payload pretty-JSON).
+     * Visszatérési exit-kód: `0`.
+     */
+    static success(input) {
+        const envelope = {
+            ok: true,
+            command: input.command,
+            data: input.data,
+            warnings: input.warnings ?? [],
+            uncertaintyNotes: input.uncertaintyNotes ?? [],
+            error: null,
+        };
+        if (input.options.json) {
+            process.stdout.write(`${JSON.stringify(envelope)}\n`);
+        }
+        else {
+            const text = input.humanFormatter
+                ? input.humanFormatter(input.data)
+                : JSON.stringify(input.data, null, 2);
+            process.stdout.write(`${text}\n`);
+            for (const warning of envelope.warnings) {
+                FAM_Output_Util.logInfo(input.options, `⚠ ${warning}`);
+            }
+            for (const note of envelope.uncertaintyNotes) {
+                FAM_Output_Util.logInfo(input.options, `~ ${note}`);
+            }
+        }
+        return fam_cli_const_1.FAM_CliExitCode.ok;
+    }
+    /**
+     * Hiba-kimenet: a strukturált `FAM_CliError` + a kapott exit-kód (default `1` művelet-hiba; `3`
+     * szerver-elérhetetlen). `--json` → `ok:false` burok a stdout-ra; különben a hiba a stderr-re
+     * (és a `fixHint`, ha van). A `2` (argument-hiba) a commander saját útja — ide NEM jut.
+     */
+    static failure(input) {
+        const code = input.exitCode ?? fam_cli_const_1.FAM_CliExitCode.operationError;
+        const envelope = {
+            ok: false,
+            command: input.command,
+            data: null,
+            warnings: [],
+            uncertaintyNotes: [],
+            error: input.error,
+        };
+        if (input.options.json) {
+            process.stdout.write(`${JSON.stringify(envelope)}\n`);
+        }
+        else {
+            FAM_Output_Util.logError(`✗ [${input.error.errorCode}] ${input.error.message}`);
+            if (input.error.fixHint) {
+                FAM_Output_Util.logError(`  → ${input.error.fixHint}`);
+            }
+        }
+        return code;
+    }
+    /** A kapott exit-kóddal lép ki (a handler-ek visszatérési értéke ezen át fut a process-exit-re). */
+    static exit(code) {
+        process.exitCode = code;
+    }
+}
+exports.FAM_Output_Util = FAM_Output_Util;

package/build/src/_cli/_collections/fam-project-discovery.util.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ProjectDiscovery_Util = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * `FAM_ProjectDiscovery_Util` (a `fam scan-projects` magja) — projekt-gyökerek **auto-felderítése** egy mappa
+ * alatt + a `--config` JSON-lista parse-je. PURE (fs-olvasás, nincs hálózat). A scope-nevet a `package.json`
+ * `name`-jéből deriválja (a user-kérte „package.json-ből olvas projekt-elnevezéseket"), fallback a dir-név.
+ *
+ * **Felderítés-szabály:** egy könyvtár PROJEKT-GYÖKÉR, ha van `package.json` VAGY `.git`. Ott MEGÁLLUNK (nem
+ * megyünk beljebb — egy monorepo gyökere egy projektnek számít). A `node_modules` + rejtett mappák kihagyva.
+ */
+class FAM_ProjectDiscovery_Util {
+    /** A projekt-gyökér markerek (bármelyik megléte → projekt). */
+    static MARKERS = ['package.json', '.git'];
+    /** Projekt-gyökér-e a könyvtár (van `package.json` vagy `.git`). */
+    static isProjectRoot(dir) {
+        return FAM_ProjectDiscovery_Util.MARKERS.some((marker) => (0, fs_1.existsSync)((0, path_1.join)(dir, marker)));
+    }
+    /** A scope leaf-név: a `package.json` `name` bare alakja (`@scope/x` → `x`), vagy a dir-név. */
+    static projectName(dir) {
+        try {
+            const pkgPath = (0, path_1.join)(dir, 'package.json');
+            if ((0, fs_1.existsSync)(pkgPath)) {
+                const name = JSON.parse((0, fs_1.readFileSync)(pkgPath, 'utf-8')).name;
+                if (typeof name === 'string' && name.trim()) {
+                    return name.trim().replace(/^@[^/]+\//, '');
+                }
+            }
+        }
+        catch {
+            // fallback a dir-névre
+        }
+        return (0, path_1.basename)(dir);
+    }
+    /**
+     * Projekt-gyökerek felderítése `root` alatt `maxDepth`-ig. Ha a `root` maga projekt → csak az. Egyébként
+     * rekurzívan a nem-rejtett alkönyvtárakban (egy projekt-gyökérnél MEGÁLL). Determinisztikus (név szerint rendezett).
+     */
+    static discover(root, maxDepth, defaults) {
+        const result = [];
+        const visit = (dir, depth) => {
+            if (depth > maxDepth) {
+                return;
+            }
+            if (FAM_ProjectDiscovery_Util.isProjectRoot(dir)) {
+                result.push({
+                    path: dir, project: FAM_ProjectDiscovery_Util.projectName(dir),
+                    org: defaults?.org, table: defaults?.table,
+                });
+                return; // egy projektbe NEM megyünk beljebb
+            }
+            let entries;
+            try {
+                entries = (0, fs_1.readdirSync)(dir).sort();
+            }
+            catch {
+                return;
+            }
+            for (const name of entries) {
+                if (name.startsWith('.') || name === 'node_modules') {
+                    continue;
+                }
+                const child = (0, path_1.join)(dir, name);
+                try {
+                    if ((0, fs_1.statSync)(child).isDirectory()) {
+                        visit(child, depth + 1);
+                    }
+                }
+                catch {
+                    // olvashatatlan bejegyzés → kihagyjuk
+                }
+            }
+        };
+        visit(root, 0);
+        return result;
+    }
+    /** A `--config` JSON-lista → projekt-spec-ek (validálva: `path` + `project` kötelező soronként). */
+    static parseConfig(content) {
+        const parsed = JSON.parse(content);
+        if (!Array.isArray(parsed)) {
+            throw new Error('A scan-projects config egy JSON-tömb legyen: [{ "path": "...", "project": "..." }, ...]');
+        }
+        return parsed.map((raw, index) => {
+            const entry = (raw && typeof raw === 'object') ? raw : {};
+            if (typeof entry.path !== 'string' || typeof entry.project !== 'string') {
+                throw new Error(`A config[${index}] hiányos: a 'path' és a 'project' (string) kötelező.`);
+            }
+            return {
+                path: entry.path, project: entry.project,
+                org: typeof entry.org === 'string' ? entry.org : undefined,
+                table: typeof entry.table === 'string' ? entry.table : undefined,
+            };
+        });
+    }
+}
+exports.FAM_ProjectDiscovery_Util = FAM_ProjectDiscovery_Util;

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

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Capture_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 capture` — FEAT-006 thin-wrapper: egy session-observation auto-capture-je a `memory`-tárba. A szerver
+ * `auto_capture` capability-jére delegál (content-hash dedup → idempotens, agent-provenance + auto-embed). A
+ * `content` pozícionális argumentumként VAGY stdin-en (pipe) — a hook-használat (`echo "..." | fam capture`)
+ * természetes útja. Az opciók: `--session` (provenance), `--tag` (ismételhető), `--kind`.
+ */
+class FAM_Capture_Util {
+    /** A `capture` parancs-deszkriptor. */
+    static command() {
+        const command = new commander_1.Command('capture');
+        command
+            .description('Session-observation auto-capture a memory-tárba (content-hash dedup, FEAT-006)')
+            .argument('[content]', 'a megfigyelés szövege (elhagyva: stdin-ről olvas)')
+            .option('--session <id>', 'opcionális session-azonosító (provenance a source.path-ban)')
+            .option('--tag <tag...>', 'opcionális tag (ismételhető)')
+            .option('--kind <kind>', 'opcionális kind (default: observation)')
+            .action(async (content) => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Capture_Util.run(command, content));
+        });
+        return command;
+    }
+    /** A flow: content (arg VAGY stdin) → `auto_capture` capability invoke → render. */
+    static async run(command, contentArg) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        const content = (contentArg ?? await FAM_Capture_Util.readStdin()).trim();
+        if (!content) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'capture',
+                error: {
+                    errorCode: 'FAM-CLI-CAPTURE-001',
+                    message: 'A `content` kötelező (pozícionális argumentum VAGY stdin-pipe).',
+                    fixHint: 'Pl.: fam capture "megfigyelés" — vagy: echo "megfigyelés" | fam capture',
+                },
+            });
+        }
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        const result = await client.post('/api/capabilities', {
+            action: 'invoke',
+            name: 'auto_capture',
+            arguments: { content: content, sessionId: local.session, tags: local.tag, kind: local.kind },
+        });
+        if (!result.ok) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'capture',
+                error: result.error ?? { errorCode: 'FAM-CLI-CAPTURE-002', message: 'Ismeretlen capture-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: 'capture', data: result.data });
+    }
+    /** A stdin teljes beolvasása (pipe-használat). TTY (interaktív, nincs pipe) → üres string. */
+    static async readStdin() {
+        if (process.stdin.isTTY) {
+            return '';
+        }
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(chunk);
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    }
+}
+exports.FAM_Capture_Util = FAM_Capture_Util;

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

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Config_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 config get|set` — a DB-backed scoped config CLI-tükre (dsgn-010 §11.1, dsgn-007). A `get`
+ * (`GET /api/config?table=`) a teljes effektív (merge-elt) configot adja a precedencia-forrással; a `set`
+ * (`PUT /api/config`) egy értéket ír a megadott szinten (global < table < scope). A kulcsok a dsgn-007
+ * `CONFIG_CATALOG` dotted nevei (a CLI nem vezet be saját config-névteret).
+ */
+class FAM_Config_Util {
+    /** A `config` parancs-deszkriptor (get/set alparanccsal). */
+    static command() {
+        const command = new commander_1.Command('config');
+        command.description('Scoped config olvasás/írás (dsgn-007 dotted kulcsok)');
+        command.addCommand(FAM_Config_Util.getCommand());
+        command.addCommand(FAM_Config_Util.setCommand());
+        return command;
+    }
+    /** `config get` — effektív (merge-elt) config az adott szinten. */
+    static getCommand() {
+        const command = new commander_1.Command('get');
+        command
+            .description('Az effektív (merge-elt) config az adott kontextusra')
+            .option('--key <key>', 'egy konkrét kulcs (dsgn-007 dotted)')
+            .option('--table <table>', 'table-szintű kontextus')
+            .option('--scope <layer=name,...>', 'scope-szintű kontextus')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Config_Util.runGet(command));
+        });
+        return command;
+    }
+    /** `config set` — egy config-érték írása egy szinten. */
+    static setCommand() {
+        const command = new commander_1.Command('set');
+        command
+            .description('Egy config-érték beállítása egy szinten (global<table<scope)')
+            .requiredOption('--key <key>', 'a CONFIG_CATALOG dotted kulcsa')
+            .requiredOption('--value <value>', 'az új érték')
+            .option('--table <table>', 'table-szint')
+            .option('--scope <layer=name,...>', 'scope-szint')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Config_Util.runSet(command));
+        });
+        return command;
+    }
+    /** A `config get` futtatása. */
+    static async runGet(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        const query = local.table ? `?table=${encodeURIComponent(local.table)}` : '';
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        const result = await client.get(`/api/config${query}`);
+        if (!result.ok) {
+            return FAM_Config_Util.fail(globals, 'config get', result, 'FAM-CLI-CONFIG-001');
+        }
+        // Egy konkrét kulcs szűrése (a server a teljes effektívet adja).
+        const data = local.key && result.data?.effective
+            ? { key: local.key, value: result.data.effective[local.key] }
+            : result.data;
+        return fam_output_util_1.FAM_Output_Util.success({ options: globals, command: 'config get', data: data });
+    }
+    /** A `config set` futtatása. */
+    static async runSet(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        const body = {
+            key: local.key,
+            value: local.value,
+            table: local.table,
+            scopeId: local.scope,
+        };
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        const result = await client.put('/api/config', body);
+        if (!result.ok) {
+            return FAM_Config_Util.fail(globals, 'config set', result, 'FAM-CLI-CONFIG-002');
+        }
+        return fam_output_util_1.FAM_Output_Util.success({ options: globals, command: 'config set', data: result.data });
+    }
+    /** Közös hiba-render a config-parancsokhoz (unreachable → 3, egyébként 1). */
+    static fail(globals, command, result, fallbackCode) {
+        return fam_output_util_1.FAM_Output_Util.failure({
+            options: globals,
+            command: command,
+            error: result.error ?? { errorCode: fallbackCode, message: 'Ismeretlen config-hiba.' },
+            exitCode: result.unreachable ? fam_cli_const_1.FAM_CliExitCode.serverUnreachable : fam_cli_const_1.FAM_CliExitCode.operationError,
+        });
+    }
+}
+exports.FAM_Config_Util = FAM_Config_Util;

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

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Doctor_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");
+/** A 6 doctor al-check ↔ capability-eszköz mátrix (dsgn-010 §5.2). */
+const CHECK_MATRIX = [
+    { name: 'env', capability: 'validate_environment', fixHint: 'Hiányzó env (pl. MONGODB_URI) → `fam init` vagy állítsd be a `.env`-ben.' },
+    { name: 'mongodb', capability: 'test_mongodb_connection', fixHint: 'Mongo nem elérhető → indítsd a Mongo-t, ellenőrizd a portot / MONGODB_URI-t.' },
+    { name: 'config', capability: 'get_config_status', fixHint: 'Nincs fam_config global rekord → `fam init` vagy `fam config set …`.' },
+    { name: 'embedding', capability: 'test_embedding_provider', fixHint: 'OpenAI 401 → ellenőrizd OPENAI_API_KEY-t; LM Studio: indítsd a szervert + tölts be modellt.' },
+    { name: 'vector', capability: 'test_vector_search', fixHint: 'Vektor-pool üres/nem-hidratált → `fam write … re-embed` vagy ellenőrizd a Mongo-persist réteget.' },
+    { name: 'collections', capability: 'get_table_stats', fixHint: 'Hiányzó collection → indítsd a szervert egyszer (auto-create), majd `fam doctor`.' },
+];
+/**
+ * `fam doctor` — a setup/diag al-checkek aggregátora (dsgn-010 §5). Lefuttatja mind a 6 al-checket a
+ * dsgn-003 capability-diagnostics eszközökön át (`POST /api/capabilities {action:invoke}`), és minden
+ * FAIL/WARN mellé KONKRÉT fix-tippet ad — néma hiba TILOS (dsgn-008). Szerver hiányában a checkek
+ * `WARN`-ot adnak "szerver szükséges" tippel (az `env` is a server-capabilityn megy MVP1-ben).
+ *
+ * A 3 diagnosztikai setup-alias (`validate-env`/`test-db`/`test-embedding`) a `doctor` EGYETLEN
+ * al-checkjére delegál — nincs külön implementáció (dsgn-010 §10).
+ */
+class FAM_Doctor_Util {
+    /** A `doctor` parancs-deszkriptor (mind a 6 al-check). */
+    static command() {
+        const command = new commander_1.Command('doctor');
+        command
+            .description('Health-report: env/mongodb/config/embedding/vector/collections (dsgn-010 §5)')
+            .option('--fix-hints', 'fix-tipp minden FAIL/WARN mellé (default be)', true)
+            .option('--skip <check,...>', 'check-ek kihagyása (pl. embedding,vector)')
+            .action(async () => {
+            const globals = command.optsWithGlobals();
+            const skip = (command.opts().skip ?? '')
+                .split(',').map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+            const names = CHECK_MATRIX.map((descriptor) => descriptor.name).filter((name) => !skip.includes(name));
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Doctor_Util.runChecks(globals, names));
+        });
+        return command;
+    }
+    /**
+     * Egy delegáló alias-parancs, ami a `doctor` EGYETLEN al-checkjére fut (dsgn-010 §2/§10). Nincs külön
+     * logika — ugyanazt a capability-invoke-ot hívja, mint a `doctor` az adott checkre.
+     */
+    static aliasCommand(aliasName, checks) {
+        const descriptor = CHECK_MATRIX.find((entry) => entry.name === checks[0]);
+        const command = new commander_1.Command(aliasName);
+        command
+            .description(`(alias) a \`fam doctor\` '${checks.join(',')}' al-checkje`)
+            .action(async () => {
+            const globals = command.optsWithGlobals();
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Doctor_Util.runChecks(globals, descriptor ? checks : []));
+        });
+        return command;
+    }
+    /** A megadott al-checkek lefuttatása + aggregált health-report (exit 0 ha nincs FAIL, különben 1). */
+    static async runChecks(globals, names) {
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        const reachable = await client.isReachable();
+        const checks = [];
+        for (const name of names) {
+            const descriptor = CHECK_MATRIX.find((entry) => entry.name === name);
+            if (!descriptor) {
+                continue;
+            }
+            checks.push(reachable
+                ? await FAM_Doctor_Util.runCapabilityCheck(client, descriptor)
+                : FAM_Doctor_Util.serverlessWarn(descriptor, client.getBaseUrl()));
+        }
+        const summary = { ok: 0, warn: 0, fail: 0 };
+        for (const check of checks) {
+            summary[check.status] += 1;
+        }
+        const health = summary.fail ? 'fail' : summary.warn ? 'warn' : 'ok';
+        const exitCode = summary.fail ? fam_cli_const_1.FAM_CliExitCode.operationError : fam_cli_const_1.FAM_CliExitCode.ok;
+        fam_output_util_1.FAM_Output_Util.success({
+            options: globals,
+            command: 'doctor',
+            data: { health: health, checks: checks, summary: summary },
+            humanFormatter: () => FAM_Doctor_Util.formatHuman(checks, summary),
+        });
+        return exitCode;
+    }
+    /** Egy capability-invoke-on át futtatott check → `FAM_DoctorCheck`. */
+    static async runCapabilityCheck(client, descriptor) {
+        const result = await client.post('/api/capabilities', { action: 'invoke', name: descriptor.capability });
+        if (result.ok) {
+            return { name: descriptor.name, status: 'ok' };
+        }
+        // A late-bind eszközök (pl. MP-12) clear "pending MP-X" hibát adnak → WARN (nem FAIL, nem néma).
+        const isPending = (result.error?.message ?? '').toLowerCase().includes('pending');
+        return {
+            name: descriptor.name,
+            status: isPending ? 'warn' : 'fail',
+            detail: result.error?.message,
+            fixHint: descriptor.fixHint,
+        };
+    }
+    /** Szerver-hiányos WARN (a check a server-réteget igényli; dsgn-010 §5.3 kockázat). */
+    static serverlessWarn(descriptor, baseUrl) {
+        return {
+            name: descriptor.name,
+            status: 'warn',
+            detail: `A '${descriptor.name}' check a futó szervert igényli (${baseUrl} elérhetetlen).`,
+            fixHint: `Indítsd a szervert (\`fam start\`), vagy adj \`--server-url\`-t. (Default: ${fam_cli_const_1.FAM_DEFAULT_SERVER_URL})`,
+        };
+    }
+    /** Ember-olvasható health-banner (`✓`/`⚠`/`✗` soronként + záró Health). */
+    static formatHuman(checks, summary) {
+        const glyph = { ok: '✓', warn: '⚠', fail: '✗' };
+        const lines = [];
+        for (const check of checks) {
+            lines.push(`${glyph[check.status]} ${check.name}${check.detail ? `  — ${check.detail}` : ''}`);
+            if (check.status !== 'ok' && check.fixHint) {
+                lines.push(`    → ${check.fixHint}`);
+            }
+        }
+        lines.push(`\nHealth: ${summary.ok}/${checks.length} OK, ${summary.warn} WARN, ${summary.fail} FAIL`);
+        return lines.join('\n');
+    }
+}
+exports.FAM_Doctor_Util = FAM_Doctor_Util;