@gramatr/mcp 0.13.71 → 0.13.74

package/dist/bin/brain.js

@@ -1,28 +1,55 @@
 /**
  * brain — CLI subcommand for bulk file upload to the grāmatr brain.
  *
- * Reads local files (txt, md, csv, pdf, docx), extracts their text, and
- * pushes the content through the RAG pipeline via `add_observation` +
- * `create_entity` MCP tool calls. No flat files are ever written — all
- * state flows through MCP tool calls to the server/database.
+ * Reads local files (txt, md, csv, pdf, docx) and uploads them to the server
+ * via the `bulk_upload` MCP tool. The server is the single source of truth
+ * for validation, idempotency (sha256-based dedup), virus scanning (ClamAV),
+ * and entity/observation creation. The CLI is a thin wrapper.
+ *
+ * Migrated in epic #1904 PR 3 from the legacy `create_entity` + `add_observation`
+ * chain. The orphan-fix that PR 1 added to `resolveEntityId` is now obsolete:
+ * idempotency is enforced server-side via `on_duplicate`.
  *
  * Usage:
- *   gramatr brain upload <file>
- *   gramatr brain upload --dir <dir>
- *   gramatr brain upload --dir <dir> --recursive
- *   gramatr brain upload <file> --entity-id <id>
- *   gramatr brain upload <file> --entity-name <name>
+ *   gramatr brain upload <file> [flags]
+ *   gramatr brain upload --dir <dir> [--recursive] [flags]
  *   gramatr brain --help
+ *
+ * New flags (PR 3):
+ *   --scope <user|team|org|public>   Sharing scope (default: user)
+ *   --project-id <id>                Optional project association
+ *   --team-id <id>                   Required when --scope=team
+ *   --org-id <id>                    Required when --scope=org
+ *   --public                         Shorthand for --scope=public
+ *   --entity-type <type>             Entity type (default: reference)
+ *   --metadata <k=v>                 Repeatable. Adds to entity metadata
+ *   --tags <t1,t2,...>               Comma-separated topic tags
+ *   --on-duplicate <skip|reuse|new-version>
+ *                                    Dedup policy (default: reuse)
+ *
+ * Exit codes:
+ *   0 — all files uploaded (or skipped via on-duplicate=skip)
+ *   1 — at least one non-validation error (network/server 5xx)
+ *   2 — config error (bad flag combination, missing required value)
+ *   3 — at least one file rejected by a validator (oversize, av_*, etc.)
+ *
+ * NOTE: Until ClamAV is deployed in production (n90-co/prod-argocd-v2#409),
+ * every CLI upload returns `av_unconfigured` from the server. This is
+ * intentional fail-closed behaviour. There is no client-side bypass.
  */
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { extname, basename, join, resolve } from 'node:path';
 import { callTool } from '../proxy/local-client.js';
 // ── Supported extensions ────────────────────────────────────────────────────
 export const SUPPORTED_EXTENSIONS = new Set(['.txt', '.md', '.csv', '.pdf', '.docx']);
-// ── Text extraction ─────────────────────────────────────────────────────────
+// ── Text extraction (kept for backwards-compatibility tests) ────────────────
 /**
  * Extract plain text from a file buffer based on its extension.
- * Returns null if the extension is unsupported (caller decides whether to warn).
+ * Returns null if the extension is unsupported.
+ *
+ * NOTE: as of PR 3, the bulk_upload pipeline ships the raw bytes to the server
+ * (which performs its own validation + storage). This helper is preserved for
+ * existing callers and unit-test scaffolding only.
  */
 export async function extractText(filePath, buffer) {
     const ext = extname(filePath).toLowerCase();
@@ -30,7 +57,6 @@ export async function extractText(filePath, buffer) {
         return buffer.toString('utf8');
     }
     if (ext === '.pdf') {
-        // Dynamic import so the module is only loaded when a PDF is actually processed.
         const pdfParse = (await import('pdf-parse')).default;
         const result = await pdfParse(buffer);
         return result.text;
@@ -42,7 +68,7 @@ export async function extractText(filePath, buffer) {
     }
     return null;
 }
-// ── Entity resolution ───────────────────────────────────────────────────────
+// ── Entity-name derivation ──────────────────────────────────────────────────
 /**
  * Derive an entity name from a file path when no explicit name is given.
  * Strips the extension from the base name.
@@ -52,61 +78,272 @@ export function deriveEntityName(filePath) {
     const ext = extname(base);
     return ext ? base.slice(0, -ext.length) : base;
 }
+// ── Validation-error → user-message mapping ─────────────────────────────────
 /**
- * Resolve the entity ID to use for a file upload.
- *
- * Priority:
- *   1. --entity-id <id>   — use the ID directly (no server call)
- *   2. --entity-name <name> — create_entity with that name
- *   3. fallback — create_entity using the filename (without extension)
- *
- * Returns the entity ID as a string, or throws on failure.
+ * Map a server-side `UploadValidationError.reason` to the documented
+ * user-friendly CLI message. Reasons not in the table are passed through
+ * verbatim so unexpected server errors are still visible.
  */
-export async function resolveEntityId(filePath, entityId, entityName) {
-    if (entityId)
-        return entityId;
-    const name = entityName ?? deriveEntityName(filePath);
-    const result = await callTool('create_entity', {
-        name,
-        entity_type: 'reference',
-        observations: [],
-    });
-    // Both error and success bodies are JSON in result.content[0].text. Parse first
-    // so we can recognize a DuplicateEntityError as "use the existing one" instead
-    // of a hard failure. This covers the silent-orphan case where the local-client
-    // fallback chain double-invoked create_entity — first call inserted the row,
-    // retry hit the duplicate guard. Without this branch the orphan stays empty.
-    const text = result.content?.[0]?.type === 'text' ? result.content[0].text : '';
-    let parsed;
+export const VALIDATION_REASON_MESSAGES = {
+    av_unconfigured: 'Server has no antivirus scanner configured. Upload rejected. Contact your admin to deploy ClamAV.',
+    av_unavailable: 'Antivirus scanner is unreachable from the server. Upload rejected (fail-closed). Try again shortly.',
+    av_infected: 'File rejected: malware detected. Upload denied.',
+    oversize: 'File exceeds the upload size limit (25 MB by default). Reduce the file or contact your admin.',
+    magic_mismatch: 'File content type does not match the declared extension. Possible polyglot. Upload denied.',
+    docx_macro: 'DOCX contains macros (vbaProject.bin). Macros are not allowed. Upload denied.',
+    pdf_javascript: 'PDF contains embedded JavaScript. Not allowed. Upload denied.',
+    pdf_launch: 'PDF contains a /Launch action. Not allowed. Upload denied.',
+};
+const VALIDATION_REASONS = new Set(Object.keys(VALIDATION_REASON_MESSAGES));
+/**
+ * Render the user-friendly message for a validation reason. For `av_infected`
+ * the signature is appended when supplied.
+ */
+export function formatValidationMessage(reason, opts) {
+    const base = VALIDATION_REASON_MESSAGES[reason];
+    if (!base)
+        return `Upload rejected — ${reason}`;
+    if (reason === 'av_infected' && opts?.signature) {
+        return `File rejected: malware detected (signature: ${opts.signature}). Upload denied.`;
+    }
+    return base;
+}
+// ── Flag parsing ────────────────────────────────────────────────────────────
+const ALLOWED_SCOPES = new Set(['user', 'team', 'org', 'public']);
+const ALLOWED_ON_DUPLICATE = new Set(['skip', 'reuse', 'new-version']);
+// Flags that take a value (consume the next arg).
+const VALUE_FLAGS = new Set([
+    '--entity-id',
+    '--entity-name',
+    '--dir',
+    '--scope',
+    '--project-id',
+    '--team-id',
+    '--org-id',
+    '--entity-type',
+    '--metadata',
+    '--tags',
+    '--on-duplicate',
+]);
+// Repeatable flags — collect every occurrence into an array.
+const REPEATABLE_FLAGS = new Set(['--metadata']);
+export function parseUploadArgs(args) {
+    const out = {
+        positionals: [],
+        recursive: false,
+        dryRun: false,
+        publicShorthand: false,
+        metadata: [],
+    };
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (REPEATABLE_FLAGS.has(arg)) {
+            const v = args[i + 1];
+            if (v === undefined) {
+                // Treat missing value as empty so downstream validation reports it.
+                out.metadata.push('');
+            }
+            else {
+                out.metadata.push(v);
+            }
+            i += 2;
+            continue;
+        }
+        if (VALUE_FLAGS.has(arg)) {
+            const v = args[i + 1];
+            switch (arg) {
+                case '--entity-id':
+                    out.entityId = v;
+                    break;
+                case '--entity-name':
+                    out.entityName = v;
+                    break;
+                case '--dir':
+                    out.dir = v;
+                    break;
+                case '--scope':
+                    out.scope = v;
+                    break;
+                case '--project-id':
+                    out.projectId = v;
+                    break;
+                case '--team-id':
+                    out.teamId = v;
+                    break;
+                case '--org-id':
+                    out.orgId = v;
+                    break;
+                case '--entity-type':
+                    out.entityType = v;
+                    break;
+                case '--tags':
+                    out.tags = v;
+                    break;
+                case '--on-duplicate':
+                    out.onDuplicate = v;
+                    break;
+            }
+            i += 2;
+            continue;
+        }
+        if (arg === '--recursive') {
+            out.recursive = true;
+            i += 1;
+            continue;
+        }
+        if (arg === '--dry-run') {
+            out.dryRun = true;
+            i += 1;
+            continue;
+        }
+        if (arg === '--public') {
+            out.publicShorthand = true;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            i += 1;
+            continue;
+        } // unknown boolean flag — ignore
+        out.positionals.push(arg);
+        i += 1;
+    }
+    return out;
+}
+/**
+ * Validate the parsed flag combination. Returns either a normalized config or
+ * a structured error message. Pure — does not write to stderr or exit.
+ */
+export function validateUploadConfig(parsed) {
+    if (parsed.entityId && parsed.entityName) {
+        return { ok: false, message: '--entity-id and --entity-name are mutually exclusive' };
+    }
+    // Resolve scope — handle --public shorthand.
+    let scope;
+    if (parsed.publicShorthand) {
+        if (parsed.scope && parsed.scope !== 'public') {
+            return {
+                ok: false,
+                message: `--public conflicts with --scope=${parsed.scope}`,
+            };
+        }
+        scope = 'public';
+    }
+    else if (parsed.scope === undefined) {
+        scope = 'user';
+    }
+    else if (ALLOWED_SCOPES.has(parsed.scope)) {
+        scope = parsed.scope;
+    }
+    else {
+        return {
+            ok: false,
+            message: `--scope must be one of: user | team | org | public (got "${parsed.scope}")`,
+        };
+    }
+    if (scope === 'team' && !parsed.teamId) {
+        return { ok: false, message: '--scope=team requires --team-id <uuid>' };
+    }
+    if (scope === 'org' && !parsed.orgId) {
+        return { ok: false, message: '--scope=org requires --org-id <uuid>' };
+    }
+    // on-duplicate
+    let onDuplicate;
+    if (parsed.onDuplicate === undefined) {
+        onDuplicate = 'reuse';
+    }
+    else if (ALLOWED_ON_DUPLICATE.has(parsed.onDuplicate)) {
+        onDuplicate = parsed.onDuplicate;
+    }
+    else {
+        return {
+            ok: false,
+            message: `--on-duplicate must be one of: skip | reuse | new-version (got "${parsed.onDuplicate}")`,
+        };
+    }
+    // metadata k=v
+    const metadata = {};
+    for (const raw of parsed.metadata) {
+        const eq = raw.indexOf('=');
+        if (eq <= 0) {
+            return { ok: false, message: `--metadata "${raw}" must be in key=value form with non-empty key` };
+        }
+        const key = raw.slice(0, eq).trim();
+        const value = raw.slice(eq + 1);
+        if (key.length === 0) {
+            return { ok: false, message: `--metadata "${raw}" has empty key` };
+        }
+        metadata[key] = value;
+    }
+    // tags
+    const tags = [];
+    if (parsed.tags) {
+        for (const t of parsed.tags.split(',')) {
+            const trimmed = t.trim();
+            if (trimmed.length > 0)
+                tags.push(trimmed);
+        }
+    }
+    return {
+        ok: true,
+        config: {
+            scope,
+            projectId: parsed.projectId,
+            teamId: parsed.teamId,
+            orgId: parsed.orgId,
+            isPublic: scope === 'public',
+            entityType: parsed.entityType ?? 'reference',
+            metadata,
+            tags,
+            onDuplicate,
+        },
+    };
+}
+/**
+ * Build the bulk_upload tool input for a given file. Exported so tests can
+ * assert the exact shape forwarded to the server.
+ */
+export function buildBulkUploadInput(filePath, buffer, options) {
+    const filename = basename(filePath);
+    const input = {
+        content_base64: buffer.toString('base64'),
+        filename,
+        entity_type: options.config.entityType,
+        scope: options.config.scope,
+        on_duplicate: options.config.onDuplicate,
+        is_public: options.config.isPublic,
+    };
+    if (options.entityId)
+        input.entity_id = options.entityId;
+    else if (options.entityName)
+        input.entity_name = options.entityName;
+    else
+        input.entity_name = deriveEntityName(filePath);
+    if (options.config.projectId)
+        input.project_id = options.config.projectId;
+    if (options.config.teamId)
+        input.team_id = options.config.teamId;
+    if (options.config.orgId)
+        input.org_id = options.config.orgId;
+    if (Object.keys(options.config.metadata).length > 0)
+        input.metadata = options.config.metadata;
+    if (options.config.tags.length > 0)
+        input.tags = options.config.tags;
+    return input;
+}
+function parseToolBody(text) {
     try {
-        parsed = JSON.parse(text);
+        return JSON.parse(text);
     }
     catch {
-        // Non-JSON body — fall through to generic error path
-    }
-    if (parsed?.error === 'DuplicateEntityError' && parsed.existing_entity_id) {
-        // Idempotent reuse — same name + type already exists for this user. Treat
-        // it as a successful resolve so the caller can attach observations.
-        return parsed.existing_entity_id;
+        return undefined;
     }
-    if (result.isError) {
-        // gramatr-allow: B1 — CLI bin command, no @gramatr/core dependency in MCP package
-        throw new Error(`create_entity failed: ${text || 'unknown error'}`);
-    }
-    if (!parsed) {
-        // gramatr-allow: B1 — CLI bin command, no @gramatr/core dependency in MCP package
-        throw new Error(`could not parse entity id from response: ${text}`);
-    }
-    const id = parsed.id ?? parsed.entity?.id;
-    // gramatr-allow: B1 — CLI bin command, no @gramatr/core dependency in MCP package
-    if (!id)
-        throw new Error('no id in create_entity response');
-    return id;
 }
 /**
- * Upload a single file to the grāmatr brain.
+ * Upload a single file via the `bulk_upload` MCP tool.
  */
-export async function uploadFile(filePath, options = {}) {
+export async function uploadFile(filePath, options) {
     const ext = extname(filePath).toLowerCase();
     if (!SUPPORTED_EXTENSIONS.has(ext)) {
         process.stderr.write(`[gramatr] skipping ${filePath} (unsupported type: ${ext})\n`);
@@ -121,47 +358,38 @@ export async function uploadFile(filePath, options = {}) {
         process.stderr.write(`[gramatr] ✗ ${filePath}: ${message}\n`);
         return { file: filePath, error: message };
     }
-    let text;
-    try {
-        text = await extractText(filePath, buffer);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`[gramatr] ✗ ${filePath}: failed to extract text — ${message}\n`);
-        return { file: filePath, error: message };
-    }
-    if (text === null) {
-        // extractText returns null for unsupported extensions — already guarded above
-        process.stderr.write(`[gramatr] skipping ${filePath} (unsupported type: ${ext})\n`);
-        return { file: filePath, skipped: true };
-    }
-    if (text.trim().length === 0) {
+    if (buffer.length === 0) {
         process.stderr.write(`[gramatr] skipping ${filePath} (empty content)\n`);
         return { file: filePath, skipped: true };
     }
-    process.stderr.write(`[gramatr] uploading ${basename(filePath)} (${text.length} chars)...\n`);
-    let entityId;
-    try {
-        entityId = await resolveEntityId(filePath, options.entityId, options.entityName);
+    process.stderr.write(`[gramatr] uploading ${basename(filePath)} (${buffer.length} bytes)...\n`);
+    const input = buildBulkUploadInput(filePath, buffer, options);
+    const result = await callTool('bulk_upload', input);
+    const text = result.content?.[0]?.type === 'text' ? result.content[0].text : '';
+    const parsed = parseToolBody(text);
+    if (result.isError) {
+        if (parsed?.type === 'UploadValidationError' && parsed.reason) {
+            const userMsg = formatValidationMessage(parsed.reason, { signature: parsed.signature });
+            process.stderr.write(`[gramatr] ✗ ${basename(filePath)}: ${userMsg}\n`);
+            return { file: filePath, error: userMsg, validationReason: parsed.reason };
+        }
+        const errMsg = parsed?.error ?? text ?? 'unknown error';
+        process.stderr.write(`[gramatr] ✗ ${basename(filePath)}: bulk_upload failed — ${errMsg}\n`);
+        return { file: filePath, error: errMsg };
     }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`[gramatr] ✗ ${filePath}: ${message}\n`);
-        return { file: filePath, error: message };
+    if (!parsed?.entity_id) {
+        const errMsg = `bulk_upload returned no entity_id: ${text}`;
+        process.stderr.write(`[gramatr] ✗ ${basename(filePath)}: ${errMsg}\n`);
+        return { file: filePath, error: errMsg };
     }
-    const obsResult = await callTool('add_observation', {
-        entity_id: entityId,
-        content: text,
-    });
-    if (obsResult.isError) {
-        const errorText = obsResult.content?.[0]?.type === 'text'
-            ? obsResult.content[0].text
-            : 'unknown error';
-        process.stderr.write(`[gramatr] ✗ ${filePath}: add_observation failed — ${errorText}\n`);
-        return { file: filePath, entityId, error: errorText };
-    }
-    process.stderr.write(`[gramatr] ✓ ${basename(filePath)} → entity ${entityId}\n`);
-    return { file: filePath, entityId };
+    const dupSuffix = parsed.was_duplicate ? ' (duplicate)' : '';
+    process.stderr.write(`[gramatr] ✓ ${basename(filePath)} → entity ${parsed.entity_id}${dupSuffix}\n`);
+    return {
+        file: filePath,
+        entityId: parsed.entity_id,
+        observationId: parsed.observation_id,
+        wasDuplicate: parsed.was_duplicate === true,
+    };
 }
 // ── Directory collection ────────────────────────────────────────────────────
 /**
@@ -189,20 +417,10 @@ export function collectFiles(dir, recursive) {
     }
     return files;
 }
-// ── Arg helpers ─────────────────────────────────────────────────────────────
-function getFlag(args, name) {
-    const idx = args.indexOf(name);
-    if (idx === -1 || idx + 1 >= args.length)
-        return undefined;
-    return args[idx + 1];
-}
-function hasFlag(args, name) {
-    return args.includes(name);
-}
 // ── Help text ────────────────────────────────────────────────────────────────
 function printBrainHelp() {
     process.stderr.write(`
-  gramatr brain — Upload local files to the grāmatr brain
+  gramatr brain — Upload local files to the grāmatr brain (via bulk_upload)
 
   Usage:
     brain upload <file>                     Upload a single file
@@ -213,29 +431,57 @@ function printBrainHelp() {
   Supported file types:
     .txt  .md  .csv  .pdf  .docx
 
-  Entity options (controls which entity observations are added to):
-    --entity-id <id>     Attach to an existing entity by ID
-    --entity-name <name> Create (or reuse) an entity with this name
-                         Default: use filename without extension
+  Entity options:
+    --entity-id <id>          Attach to an existing entity by ID
+    --entity-name <name>      Use this entity name (server creates if missing)
+                              Default: filename without extension
+    --entity-type <type>      Entity type (default: reference)
+
+  Sharing / scope:
+    --scope <user|team|org|public>   Default: user
+    --project-id <uuid>              Optional project association
+    --team-id <uuid>                 Required when --scope=team
+    --org-id <uuid>                  Required when --scope=org
+    --public                         Shorthand for --scope=public
+
+  Metadata:
+    --metadata key=value      Repeatable. Adds entries to entity metadata
+    --tags t1,t2,t3           Comma-separated topic tags
+
+  Dedup policy:
+    --on-duplicate <skip|reuse|new-version>
+                              Server-side dedup behaviour (default: reuse)
+                                skip        — leave existing entity untouched
+                                reuse       — append observation to existing entity
+                                new-version — create "<name> v2" / v3 / ...
 
   Other flags:
-    --dry-run            Preflight: show what would be uploaded, do not write
-    --recursive          With --dir, walk subdirectories
+    --dry-run                 Preflight only — show what would be uploaded
+    --recursive               With --dir, walk subdirectories
+
+  Exit codes:
+    0   all files uploaded (or skipped via on-duplicate=skip)
+    1   at least one non-validation error (network / 5xx)
+    2   config error (bad flag combination)
+    3   at least one file rejected by a server-side validator
 
   Examples:
     brain upload project-brief.pdf
-    brain upload notes.md --entity-name "Q3 Research"
-    brain upload contract.docx --entity-id abc-123
-    brain upload --dir ./docs
-    brain upload --dir ./research --recursive
-    brain upload --dir ./docs --dry-run
+    brain upload notes.md --entity-name "Q3 Research" --tags strategy,2026
+    brain upload contract.docx --entity-id abc-123 --on-duplicate new-version
+    brain upload --dir ./docs --scope team --team-id <team-uuid>
+    brain upload --dir ./research --recursive --metadata source=arxiv --metadata year=2026
+    brain upload report.pdf --public
+
+  NOTE: bulk_upload requires ClamAV to be deployed on the server. Until then,
+        every upload returns av_unconfigured (fail-closed by design).
 
 `);
 }
 // ── Main entry point ─────────────────────────────────────────────────────────
 /**
  * runBrain — entry point for `gramatr brain <args>` subcommand.
- * Returns an exit code (0 = success, 1 = one or more errors).
+ * Returns an exit code (0/1/2/3 — see top of file).
  */
 export async function runBrain(args) {
     const subcommand = args[0];
@@ -250,35 +496,21 @@ export async function runBrain(args) {
         return 1;
     }
     // -- upload subcommand --
-    const uploadArgs = args.slice(1);
-    const entityId = getFlag(uploadArgs, '--entity-id');
-    const entityName = getFlag(uploadArgs, '--entity-name');
-    const dirArg = getFlag(uploadArgs, '--dir');
-    const recursive = hasFlag(uploadArgs, '--recursive');
-    const dryRun = hasFlag(uploadArgs, '--dry-run');
-    // Collect the positional (non-flag) arguments as file paths
-    const positionals = [];
-    let i = 0;
-    while (i < uploadArgs.length) {
-        const arg = uploadArgs[i];
-        if (arg === '--entity-id' || arg === '--entity-name' || arg === '--dir') {
-            i += 2; // skip flag + value
-        }
-        else if (arg.startsWith('--')) {
-            i += 1; // boolean flag
-        }
-        else {
-            positionals.push(arg);
-            i += 1;
-        }
+    const parsed = parseUploadArgs(args.slice(1));
+    const validation = validateUploadConfig(parsed);
+    if (!validation.ok) {
+        process.stderr.write(`[gramatr] ✗ ${validation.message}\n`);
+        process.stderr.write('  Run: gramatr brain --help\n');
+        return 2;
     }
+    const { config } = validation;
     // Build the list of files to upload
     const filePaths = [];
-    if (dirArg) {
-        const absDir = resolve(dirArg);
+    if (parsed.dir) {
+        const absDir = resolve(parsed.dir);
         let dirFiles;
         try {
-            dirFiles = collectFiles(absDir, recursive);
+            dirFiles = collectFiles(absDir, parsed.recursive);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -291,7 +523,7 @@ export async function runBrain(args) {
         }
         filePaths.push(...dirFiles);
     }
-    for (const p of positionals) {
+    for (const p of parsed.positionals) {
         filePaths.push(resolve(p));
     }
     if (filePaths.length === 0) {
@@ -299,25 +531,43 @@ export async function runBrain(args) {
         process.stderr.write('  Run: gramatr brain --help\n');
         return 1;
     }
-    if (dryRun) {
+    if (parsed.dryRun) {
         process.stderr.write(`[gramatr] dry-run — would upload ${filePaths.length} file(s):\n`);
+        process.stderr.write(`  scope=${config.scope}  entity_type=${config.entityType}  on_duplicate=${config.onDuplicate}\n`);
         for (const filePath of filePaths) {
             const ext = extname(filePath).toLowerCase();
             const supported = SUPPORTED_EXTENSIONS.has(ext);
-            const name = entityId ? `(reuse entity ${entityId})` : `entity_name=${entityName ?? deriveEntityName(filePath)}`;
+            const target = parsed.entityId
+                ? `(reuse entity ${parsed.entityId})`
+                : `entity_name=${parsed.entityName ?? deriveEntityName(filePath)}`;
             const status = supported ? 'OK' : `SKIP (unsupported: ${ext})`;
-            process.stderr.write(`  [${status}] ${filePath}  →  ${name}\n`);
+            process.stderr.write(`  [${status}] ${filePath}  →  ${target}\n`);
         }
         process.stderr.write('[gramatr] dry-run complete — no changes written\n');
         return 0;
     }
-    const options = { entityId, entityName };
+    const options = {
+        entityId: parsed.entityId,
+        entityName: parsed.entityName,
+        config,
+    };
     let hasError = false;
+    let hasValidationReject = false;
     for (const filePath of filePaths) {
         const result = await uploadFile(filePath, options);
-        if (result.error)
+        if (result.validationReason) {
+            hasValidationReject = true;
+        }
+        else if (result.error) {
             hasError = true;
+        }
     }
-    return hasError ? 1 : 0;
+    // Validator rejection takes precedence — distinct exit code so scripts can
+    // differentiate "server said no" from "transport blew up".
+    if (hasValidationReject)
+        return 3;
+    if (hasError)
+        return 1;
+    return 0;
 }
 //# sourceMappingURL=brain.js.map