@futdevpro/fdp-agent-memory 0.1.0 → 1.1.12

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

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Errors_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 errors` — a persistált `FAM_Error` rekordok CLI-tükre (dsgn-010 §11.3, dsgn-008). `--list`
+ * (default akció) a `GET /server/errors`-t hívja (`--level`/`--limit` szűréssel); `--mark-done <id>` a
+ * `POST /server/errors/mark-handled/:id`-t (occurrence-count + dedup megmarad). A `--limit` kliens-oldalon
+ * vág (a server a teljes szűrt listát adja).
+ */
+class FAM_Errors_Util {
+    /** Az `errors` parancs-deszkriptor. */
+    static command() {
+        const command = new commander_1.Command('errors');
+        command
+            .description('Persistált FAM hibák listázása / kezeltnek jelölése (dsgn-008)')
+            .option('--list', 'hiba-lista (default akció)', false)
+            .option('--level <level>', 'debug|info|warn|error|critical szűrő')
+            .option('--limit <N>', 'lista-limit (kliens-oldali vágás)')
+            .option('--mark-done <id>', 'egy hiba "kezelve" jelölése')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Errors_Util.run(command));
+        });
+        return command;
+    }
+    /** Az `errors` futtatása: mark-done VAGY list. */
+    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.markDone) {
+            const markResult = await client.post(`/server/errors/mark-handled/${encodeURIComponent(local.markDone)}`, {});
+            if (!markResult.ok) {
+                return FAM_Errors_Util.fail(globals, markResult, 'FAM-CLI-ERRORS-002');
+            }
+            return fam_output_util_1.FAM_Output_Util.success({
+                options: globals,
+                command: 'errors',
+                data: { markedHandled: local.markDone },
+            });
+        }
+        // Default: list (a `--list` opcionális — a mark-done hiányában is listázunk).
+        const query = local.level ? `?level=${encodeURIComponent(local.level)}` : '';
+        const listResult = await client.get(`/server/errors${query}`);
+        if (!listResult.ok) {
+            return FAM_Errors_Util.fail(globals, listResult, 'FAM-CLI-ERRORS-001');
+        }
+        const all = listResult.data ?? [];
+        const limit = local.limit ? Number(local.limit) : undefined;
+        const errors = limit && limit > 0 ? all.slice(0, limit) : all;
+        return fam_output_util_1.FAM_Output_Util.success({ options: globals, command: 'errors', data: { errors: errors } });
+    }
+    /** Közös hiba-render (unreachable → 3, egyébként 1). */
+    static fail(globals, result, fallbackCode) {
+        return fam_output_util_1.FAM_Output_Util.failure({
+            options: globals,
+            command: 'errors',
+            error: result.error ?? { errorCode: fallbackCode, message: 'Ismeretlen errors-hiba.' },
+            exitCode: result.unreachable ? fam_cli_const_1.FAM_CliExitCode.serverUnreachable : fam_cli_const_1.FAM_CliExitCode.operationError,
+        });
+    }
+}
+exports.FAM_Errors_Util = FAM_Errors_Util;

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

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Export_Util = void 0;
+const commander_1 = require("commander");
+const fs_1 = require("fs");
+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 export` — FEAT-007 thin-wrapper: a **non-file-derived** (kézzel/agent-írt, `source.type ∈ {manual, agent}`)
+ * bejegyzések biztonsági mentése. Ezeket re-scan NEM regenerálja → pótolhatatlan kurált érték. A szerver
+ * `export_authored` capability-jére delegál (NINCS export-logika a CLI-ben), és `--out` esetén JSON-fájlba írja
+ * (egyébként a standard success-outputon adja vissza). A `contentVector` kimarad (re-embeddel regenerálható).
+ */
+class FAM_Export_Util {
+    /** Az `export` parancs-deszkriptor. */
+    static command() {
+        const command = new commander_1.Command('export');
+        command
+            .description('A non-file-derived (kézzel/agent-írt) bejegyzések biztonsági mentése JSON-ba (FEAT-007)')
+            .option('--out <file>', 'cél JSON-fájl útvonala (alapból: a standard outputon adja vissza)')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Export_Util.run(command));
+        });
+        return command;
+    }
+    /** A flow: az `export_authored` capability invoke → opcionális fájl-írás → render. */
+    static async run(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        const result = await client.post('/api/capabilities', {
+            action: 'invoke',
+            name: 'export_authored',
+            arguments: {},
+        });
+        if (!result.ok) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'export',
+                error: result.error ?? { errorCode: 'FAM-CLI-EXPORT-002', message: 'Ismeretlen export-hiba.' },
+                exitCode: result.unreachable ? fam_cli_const_1.FAM_CliExitCode.serverUnreachable : fam_cli_const_1.FAM_CliExitCode.operationError,
+            });
+        }
+        if (local.out) {
+            try {
+                (0, fs_1.writeFileSync)(local.out, JSON.stringify(result.data, null, 2), 'utf8');
+                fam_output_util_1.FAM_Output_Util.logInfo(globals, `Authored backup kiírva: ${local.out}`);
+            }
+            catch (error) {
+                return fam_output_util_1.FAM_Output_Util.failure({
+                    options: globals,
+                    command: 'export',
+                    error: {
+                        errorCode: 'FAM-CLI-EXPORT-001',
+                        message: `A backup-fájl írása sikertelen: ${error.message}`,
+                        fixHint: 'Ellenőrizd az --out útvonal írhatóságát (mappa létezik, van jogosultság).',
+                    },
+                });
+            }
+        }
+        return fam_output_util_1.FAM_Output_Util.success({ options: globals, command: 'export', data: result.data });
+    }
+}
+exports.FAM_Export_Util = FAM_Export_Util;

package/build/src/_cli/_commands/find-duplicates.command.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_FindDuplicates_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 find-duplicates --table <t>` — near-duplikátum / multiplikáció FELDERÍTŐ (read-only; user-direktíva
+ * 2026-06-21). Egy tár vektor-pool-jában megkeresi a NAGYON HASONLÓ (koszinusz ≥ `--threshold`) entry-ket és
+ * cluster-ekbe vonja — **NEM töröl**, csak megmutatja az ismétlődéseket (a user dönt). A `GET /api/duplicates/:table`
+ * REST-tükre. `--threshold` (0..1, default 0.95), `--neighbors`, `--max-entries` (O(n²)-cap), `--max-clusters`.
+ */
+class FAM_FindDuplicates_Util {
+    /** A `find-duplicates` parancs-deszkriptor. */
+    static command() {
+        const command = new commander_1.Command('find-duplicates');
+        command
+            .description('Near-duplikátum / multiplikáció felderítés egy tárban (koszinusz-cluster, NEM töröl)')
+            .requiredOption('--table <table>', 'a vizsgált tár (rules/documents/codebase/knowledge/coding_patterns/memory)')
+            .option('--threshold <n>', 'koszinusz-küszöb 0..1 (default 0.95)')
+            .option('--neighbors <n>', 'szomszéd-szám/entry (default 10)')
+            .option('--max-entries <n>', 'entry-cap az O(n²) ellen (default 3000; a capped jelzi, ha több)')
+            .option('--max-clusters <n>', 'a visszaadott cluster-ek max száma (default 100)')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_FindDuplicates_Util.run(command));
+        });
+        return command;
+    }
+    /** A `find-duplicates` futtatása: a REST `/api/duplicates/:table` query-paraméterekkel. */
+    static async run(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        const query = FAM_FindDuplicates_Util.buildQuery({
+            threshold: local.threshold,
+            neighbors: local.neighbors,
+            maxEntries: local.maxEntries,
+            maxClusters: local.maxClusters,
+        });
+        const path = `/api/duplicates/${encodeURIComponent(local.table)}${query}`;
+        const result = await client.get(path);
+        if (!result.ok) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'find-duplicates',
+                error: result.error ?? { errorCode: 'FAM-CLI-DUP-001', message: 'Ismeretlen duplikátum-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: 'find-duplicates',
+            data: result.data,
+            humanFormatter: (data) => FAM_FindDuplicates_Util.format(data),
+        });
+    }
+    /** A query-string összeállítása a megadott (definiált) opciókból. */
+    static buildQuery(options) {
+        const parts = [];
+        if (options.threshold !== undefined) {
+            parts.push(`threshold=${encodeURIComponent(options.threshold)}`);
+        }
+        if (options.neighbors !== undefined) {
+            parts.push(`neighbors=${encodeURIComponent(options.neighbors)}`);
+        }
+        if (options.maxEntries !== undefined) {
+            parts.push(`maxEntries=${encodeURIComponent(options.maxEntries)}`);
+        }
+        if (options.maxClusters !== undefined) {
+            parts.push(`maxClusters=${encodeURIComponent(options.maxClusters)}`);
+        }
+        return parts.length ? `?${parts.join('&')}` : '';
+    }
+    /** Ember-olvasható összegzés: scan-fejléc (+ capped-figyelmeztetés) + a top cluster-ek tagokkal. */
+    static format(report) {
+        const lines = [];
+        lines.push(`Near-duplikátum scan — '${report.table}' (küszöb ${report.threshold}):`);
+        lines.push(`  vizsgált ${report.scanned} / ${report.totalInPool} entry`
+            + `${report.capped ? '  ⚠ CAPPED (a tár nagyobb — emeld a --max-entries-t a teljes scan-hez)' : ''}`);
+        lines.push(`  ${report.clusterCount} duplikátum-cluster, összesen ${report.duplicateEntryCount} érintett entry`);
+        if (!report.clusterCount) {
+            lines.push('  ✓ nincs a küszöb feletti near-duplikátum.');
+            return lines.join('\n');
+        }
+        for (const [index, cluster] of report.clusters.entries()) {
+            lines.push('');
+            lines.push(`  #${index + 1} — ${cluster.size} elem (score ${cluster.minScore.toFixed(3)}…${cluster.maxScore.toFixed(3)}):`);
+            for (const member of cluster.members) {
+                const snippet = member.snippet ? `: ${member.snippet}` : '';
+                lines.push(`     • [${member.id}]${member.kind ? ` (${member.kind})` : ''}${snippet}`);
+            }
+        }
+        return lines.join('\n');
+    }
+}
+exports.FAM_FindDuplicates_Util = FAM_FindDuplicates_Util;

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

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Import_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 import claude-mem` — a claude-mem migráció CLI thin-wrapper-e (dsgn-010 §8, dsgn-009). EGYIRÁNYÚ
+ * (claude-mem → FAM; visszaimport nincs, REQ-012). Az MP-11 import-katalógusra delegál a
+ * `capabilities.invoke`-on át — NINCS külön import-logika a CLI-ben (a dedup/target-mapping/rollback
+ * MP-11/dsgn-009 SSOT). **Preview-first**: alap esetben preview, `--yes` átugorja a megerősítést.
+ *
+ * > Az import-engine MP-11; addig a `capabilities.invoke` clear "pending MP-11" hibát adhat runtime-ban
+ * > (nem néma, nem crash) — a CLI a REST-kontraktusra COMPILE-ol, függetlenül az engine-állapottól.
+ *
+ * A `migrate` setup-alias erre delegál (dsgn-010 §10).
+ */
+class FAM_Import_Util {
+    /** Az `import` parancs-deszkriptor (claude-mem + agent-memory alparancsokkal). */
+    static command() {
+        const command = new commander_1.Command('import');
+        command.description('Migráció FAM-ba (claude-mem / agent-memory; egyirányú, dsgn-009)');
+        command.addCommand(FAM_Import_Util.claudeMemCommand('claude-mem'));
+        command.addCommand(FAM_Import_Util.agentMemoryCommand('agent-memory'));
+        return command;
+    }
+    /**
+     * A `agent-memory` parancs: az agent (Claude) tartós memóriájának (`.claude/.../memory/*.md`) importja.
+     * UGYANAZ az engine (preview/run/rollback/dedup/embed), mint a claude-mem-é — csak a `from` rögzített
+     * (`agent-memory`), és a `--path` a memória-mappára mutat. Preview-first; `--yes` átugorja a megerősítést.
+     */
+    static agentMemoryCommand(commandName) {
+        const command = new commander_1.Command(commandName);
+        command
+            .description('agent-memory import (.claude/.../memory/*.md), preview-first')
+            .requiredOption('--path <dir>', 'a memória-mappa (frontmatter-es *.md fájlok)')
+            .option('--preview', 'csak preview (dedup + target-mapping); nem ír', false)
+            .option('--yes', 'preview-megerősítés átugrása (non-interactive)', false)
+            .option('--rollback <batchId>', 'egy import-batch visszavonása')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Import_Util.run(command, 'agent-memory'));
+        });
+        return command;
+    }
+    /** A `migrate` delegáló alias (dsgn-010 §10) — az `import claude-mem` flow-ra fut. */
+    static aliasCommand(aliasName) {
+        return FAM_Import_Util.claudeMemCommand(aliasName);
+    }
+    /** A `claude-mem` (vagy az alias) parancs-fa: a preview/run/rollback flag-keret. */
+    static claudeMemCommand(commandName) {
+        const command = new commander_1.Command(commandName);
+        command
+            .description('claude-mem migráció (sqlite|export-json|worker-api), preview-first')
+            .option('--from <sqlite|export-json|worker-api>', 'forrás-csatorna')
+            .option('--path <db|json>', 'SQLite/export-JSON útvonal')
+            .option('--url <workerUrl>', 'live worker base URL (worker-api)')
+            .option('--preview', 'csak preview (dedup + target-mapping); nem ír', false)
+            .option('--yes', 'preview-megerősítés átugrása (non-interactive)', false)
+            .option('--rollback <batchId>', 'egy import-batch visszavonása')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Import_Util.run(command));
+        });
+        return command;
+    }
+    /**
+     * A flow: rollback VAGY preview VAGY (preview→megerősítés→) run — a server capability-jeire delegálva.
+     * A `forcedFrom` (ha megadva, pl. az `agent-memory` subcommand) felülírja a `--from`-ot — a hívó nem
+     * adhat más csatornát.
+     */
+    static async run(command, forcedFrom) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        const from = forcedFrom ?? local.from;
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        // 1) Rollback (a többi flaget figyelmen kívül hagyja).
+        if (local.rollback) {
+            const rollbackResult = await client.post('/api/capabilities', {
+                action: 'invoke',
+                name: 'rollback_import',
+                arguments: { batchId: local.rollback },
+            });
+            return FAM_Import_Util.render(globals, 'import rollback', rollbackResult);
+        }
+        if (!from) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'import',
+                error: {
+                    errorCode: 'FAM-CLI-IMPORT-001',
+                    message: 'A --from kötelező (sqlite|export-json|worker-api), vagy adj --rollback <batchId>-t.',
+                    fixHint: 'Pl.: fam import claude-mem --from export-json --path ./export.json --preview',
+                },
+            });
+        }
+        const importArgs = {
+            source: 'claude-mem',
+            from: from,
+            path: local.path,
+            url: local.url,
+        };
+        // 2) Preview (mindig fut a run előtt; a `--yes` nélkül itt megáll).
+        const previewResult = await client.post('/api/capabilities', {
+            action: 'invoke',
+            name: 'preview_claude_mem_import',
+            arguments: importArgs,
+        });
+        if (!previewResult.ok || local.preview || !local.yes) {
+            // preview-only VAGY hiba VAGY nincs --yes → itt megállunk (idempotens, nem ír).
+            if (previewResult.ok && !local.preview && !local.yes) {
+                fam_output_util_1.FAM_Output_Util.logInfo(globals, 'Preview kész. Az íráshoz add hozzá a --yes flaget.');
+            }
+            return FAM_Import_Util.render(globals, 'import preview', previewResult);
+        }
+        // 3) Run (csak --yes esetén, preview után).
+        const runResult = await client.post('/api/capabilities', {
+            action: 'invoke',
+            name: 'import_claude_mem',
+            arguments: importArgs,
+        });
+        return FAM_Import_Util.render(globals, 'import', runResult);
+    }
+    /** Közös render (unreachable → 3, egyébként 1/0). */
+    static render(globals, commandLabel, result) {
+        if (!result.ok) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: commandLabel,
+                error: result.error ?? { errorCode: 'FAM-CLI-IMPORT-002', message: 'Ismeretlen import-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: commandLabel, data: result.data });
+    }
+}
+exports.FAM_Import_Util = FAM_Import_Util;

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

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Init_Util = void 0;
+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");
+/** A default Mongo connection-string (dsgn-010 §4). */
+const DEFAULT_MONGODB_URI = 'mongodb://0.0.0.0:29017/';
+/** A default Mongo DB-név. */
+const DEFAULT_DB_NAME = 'fdp_agent_memory';
+/**
+ * `fam init` — config-scaffold (dsgn-010 §4). Egy működő lokális `.env`-váz előállítása (a hiányzó
+ * kulcsokkal), egy MCP-kliens config-snippet kiírása, és záró-tipp (`fam doctor`). A DB-backed config
+ * seed (a `fam_config` global rekordok) a futó szervert igényli — szerver/DB hiányában **env-only
+ * fallback + warning** (a tervezés nem áll meg; dsgn-010 §4 / MP-9-detailed).
+ *
+ * A `create-config` setup-alias ennek a config-scaffold lépésére delegál (dsgn-010 §10).
+ */
+class FAM_Init_Util {
+    /** Az `init` parancs-deszkriptor. */
+    static command() {
+        const command = new commander_1.Command('init');
+        command
+            .description('Lokális config + .env váz scaffold (dsgn-010 §4)')
+            .option('--force', 'meglévő kulcsok felülírása', false)
+            .option('--mongodb-uri <uri>', `Mongo connection string (default ${DEFAULT_MONGODB_URI})`)
+            .option('--db-name <name>', `Mongo DB-név (default ${DEFAULT_DB_NAME})`)
+            .option('--embedding-provider <openai|lmstudio>', 'embedding-provider preset')
+            .option('--non-interactive', 'nincs prompt; csak flag/env/default', false)
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Init_Util.run(command));
+        });
+        return command;
+    }
+    /**
+     * A `create-config` delegáló alias (dsgn-010 §10) — ugyanazt a config-scaffold lépést futtatja, mint
+     * az `init`. Nincs külön logika (a `run`-ra delegál).
+     */
+    static configScaffoldAlias(aliasName) {
+        const command = new commander_1.Command(aliasName);
+        command
+            .description('(alias) a `fam init` config-scaffold lépése')
+            .option('--force', 'meglévő kulcsok felülírása', false)
+            .option('--mongodb-uri <uri>', 'Mongo connection string')
+            .option('--db-name <name>', 'Mongo DB-név')
+            .option('--embedding-provider <openai|lmstudio>', 'embedding-provider preset')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Init_Util.run(command));
+        });
+        return command;
+    }
+    /** A scaffold futtatása: a `.env`-váz írása + MCP-snippet + záró-tipp. */
+    static async run(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        const provider = local.embeddingProvider === 'lmstudio' ? 'lmstudio' : 'openai';
+        const desired = {
+            MONGODB_URI: local.mongodbUri ?? DEFAULT_MONGODB_URI,
+            MONGODB_DB_NAME: local.dbName ?? DEFAULT_DB_NAME,
+            EMBEDDING_PROVIDER: provider,
+        };
+        if (provider === 'openai') {
+            desired.OPENAI_API_KEY = '';
+            desired.OPENAI_EMBEDDING_MODEL = 'text-embedding-3-small';
+        }
+        else {
+            desired.LMSTUDIO_BASE_URL = 'http://localhost:1234/v1';
+            desired.LMSTUDIO_EMBEDDING_MODEL = 'text-embedding-nomic-embed-text-v1.5';
+        }
+        const envPath = (0, path_1.resolve)(process.cwd(), '.env');
+        const existing = FAM_Init_Util.readEnv(envPath);
+        const createdKeys = [];
+        for (const key of Object.keys(desired)) {
+            if (local.force || existing[key] === undefined) {
+                existing[key] = desired[key];
+                createdKeys.push(key);
+            }
+        }
+        try {
+            (0, fs_1.writeFileSync)(envPath, FAM_Init_Util.serializeEnv(existing), 'utf-8');
+        }
+        catch (writeError) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'init',
+                error: {
+                    errorCode: 'FAM-CLI-INIT-001',
+                    message: `A .env nem írható (${envPath}): ${writeError.message}.`,
+                },
+            });
+        }
+        const mcpClientSnippet = {
+            mcpServers: { 'fdp-agent-memory': { command: 'fam', args: ['start'] } },
+        };
+        const warnings = [
+            'A DB-backed config-seed a futó szervert igényli — most env-only scaffold készült (env-only fallback).',
+        ];
+        return fam_output_util_1.FAM_Output_Util.success({
+            options: globals,
+            command: 'init',
+            warnings: warnings,
+            data: {
+                configFile: '.env',
+                createdKeys: createdKeys,
+                seededConfig: { scope: 'global', preset: `${provider}-recommended` },
+                mcpClientSnippet: mcpClientSnippet,
+                nextStep: 'fam doctor',
+            },
+            humanFormatter: (data) => FAM_Init_Util.formatHuman(data),
+        });
+    }
+    /** A meglévő `.env` beolvasása kulcs→érték térképbe (vagy üres, ha nincs). */
+    static readEnv(envPath) {
+        const map = {};
+        if (!(0, fs_1.existsSync)(envPath)) {
+            return map;
+        }
+        for (const line of (0, fs_1.readFileSync)(envPath, 'utf-8').split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#')) {
+                continue;
+            }
+            const eq = trimmed.indexOf('=');
+            if (eq < 0) {
+                continue;
+            }
+            map[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+        }
+        return map;
+    }
+    /** A kulcs→érték térkép → `.env` szöveg. */
+    static serializeEnv(map) {
+        return `${Object.keys(map).map((key) => `${key}=${map[key]}`).join('\n')}\n`;
+    }
+    /** Ember-olvasható init-összefoglaló. */
+    static formatHuman(data) {
+        const typed = data;
+        const lines = [];
+        lines.push(`✓ .env scaffold kész (új kulcsok: ${(typed.createdKeys ?? []).join(', ') || '(nincs új)'}).`);
+        lines.push('\nMCP-kliens config-snippet (Claude Desktop/Code):');
+        lines.push(JSON.stringify(typed.mcpClientSnippet, null, 2));
+        lines.push(`\nKövetkező lépés: ${typed.nextStep ?? 'fam doctor'}`);
+        return lines.join('\n');
+    }
+}
+exports.FAM_Init_Util = FAM_Init_Util;

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

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Read_Util = void 0;
+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 read` — a dsgn-003 §2 `read` MCP-tool / `POST /api/read` REST CLI-tükre (dsgn-010 §7.1). Egy
+ * hívásban **több** `--query` + `--tables` blokk (a két-query Béla-eset): minden `--tables` a megelőző
+ * `--query`-hez tartozik. A CLI csak flag→server-input map (nincs külön retrieval-logika).
+ */
+class FAM_Read_Util {
+    /** A `read` parancs-deszkriptor (a `buildCli()`/`registerFAMCommands` adja a programhoz). */
+    static command() {
+        const command = new commander_1.Command('read');
+        command
+            .description('Multi-tábla + multi-query keresés (dsgn-003 §2 read REST-tükre)')
+            .option('-q, --query <phrase>', 'keresési phrase (ismételhető — minden query egy blokk)', fam_arg_util_1.FAM_Arg_Util.collect, [])
+            .option('-t, --tables <t1,t2>', 'a megelőző --query 1+ fő tára (ismételhető)', fam_arg_util_1.FAM_Arg_Util.collect, [])
+            .option('--top-k <N>', `találat-limit query-nként (default ${fam_cli_const_1.FAM_DEFAULT_TOP_K})`)
+            .option('--scope <layer=name,...>', 'opcionális subtree-scope prefilter')
+            .option('--tags <tag,...>', 'tag-szűrő')
+            .option('--kind <kind>', 'kind-szűrő')
+            .option('--min-score <f>', 'minimum-score küszöb')
+            .option('--no-content', 'kompakt lista (id+score+source), includeContent:false')
+            .action(async () => {
+            fam_output_util_1.FAM_Output_Util.exit(await FAM_Read_Util.run(command));
+        });
+        return command;
+    }
+    /** A `read` futtatása: a `--query`/`--tables` blokkok → `POST /api/read` input. */
+    static async run(command) {
+        const globals = command.optsWithGlobals();
+        const local = command.opts();
+        if (!local.query.length) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'read',
+                error: {
+                    errorCode: 'FAM-CLI-READ-001',
+                    message: 'Legalább egy --query kötelező.',
+                    fixHint: 'Pl.: fam read --query "ki az a Béla" --tables memory',
+                },
+            });
+        }
+        if (local.tables.length !== local.query.length) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'read',
+                error: {
+                    errorCode: 'FAM-CLI-READ-002',
+                    message: `Minden --query-hez pontosan egy --tables kell (${local.query.length} query / ${local.tables.length} tables).`,
+                    fixHint: 'Add meg a --tables-t minden --query után (a `reference` tár NEM adható meg).',
+                },
+            });
+        }
+        const topK = local.topK ? Number(local.topK) : undefined;
+        const minScore = local.minScore ? Number(local.minScore) : undefined;
+        const queries = local.query.map((phrase, index) => ({
+            query: phrase,
+            tables: fam_arg_util_1.FAM_Arg_Util.parseList(local.tables[index]) ?? [],
+            topK: topK,
+            minScore: minScore,
+            scopeFilter: fam_arg_util_1.FAM_Arg_Util.parseScope(local.scope),
+            tagFilter: fam_arg_util_1.FAM_Arg_Util.parseList(local.tags),
+            kindFilter: local.kind,
+        }));
+        const body = { queries: queries, includeContent: local.content !== false };
+        const client = new fam_client_service_1.FAM_CliClient_Service(globals.serverUrl);
+        const result = await client.post('/api/read', body);
+        return FAM_Read_Util.render(globals, result);
+    }
+    /** A server-választ → CLI-kimenet (siker/hiba/unreachable → 0/1/3). */
+    static render(globals, result) {
+        if (!result.ok) {
+            return fam_output_util_1.FAM_Output_Util.failure({
+                options: globals,
+                command: 'read',
+                error: result.error ?? { errorCode: 'FAM-CLI-READ-003', message: 'Ismeretlen read-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: 'read',
+            data: result.data,
+            humanFormatter: (data) => FAM_Read_Util.formatHuman(data),
+        });
+    }
+    /** Ember-olvasható read-kimenet: query-nként a hits + a dense-jelzés kötelező kiemelése (REQ-007). */
+    static formatHuman(data) {
+        const results = data.results ?? [];
+        const lines = [];
+        for (const block of results) {
+            lines.push(`\n● "${block.query ?? ''}"  [${(block.tables ?? []).join(', ')}]  (${block.totalRelevant ?? block.hits?.length ?? 0} relevant)`);
+            if (block.denseResults) {
+                lines.push(`  ⚑ DENSE RESULTS — szűkítsd: ${(block.suggestions ?? []).join(' | ') || '(adj scope-ot/tag-et)'}`);
+            }
+            for (const hit of block.hits ?? []) {
+                const preview = (hit.content ?? '').replace(/\s+/g, ' ').slice(0, 100);
+                lines.push(`  - [${(hit.score ?? 0).toFixed(3)}] ${hit.id ?? ''}  ${preview}`);
+            }
+        }
+        return lines.join('\n');
+    }
+}
+exports.FAM_Read_Util = FAM_Read_Util;