@gramatr/mcp 0.13.71 → 0.13.74

package/dist/bin/brain.d.ts

@@ -1,23 +1,50 @@
 /**
  * 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.
  */
 export declare const SUPPORTED_EXTENSIONS: Set<string>;
 /**
  * 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 declare function extractText(filePath: string, buffer: Buffer): Promise<string | null>;
 /**
@@ -26,30 +53,84 @@ export declare function extractText(filePath: string, buffer: Buffer): Promise<s
  */
 export declare function deriveEntityName(filePath: string): string;
 /**
- * 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 declare function resolveEntityId(filePath: string, entityId: string | undefined, entityName: string | undefined): Promise<string>;
+export declare const VALIDATION_REASON_MESSAGES: Record<string, string>;
+/**
+ * Render the user-friendly message for a validation reason. For `av_infected`
+ * the signature is appended when supplied.
+ */
+export declare function formatValidationMessage(reason: string, opts?: {
+    signature?: string;
+}): string;
+export interface ParsedArgs {
+    positionals: string[];
+    entityId?: string;
+    entityName?: string;
+    dir?: string;
+    recursive: boolean;
+    dryRun: boolean;
+    scope?: string;
+    projectId?: string;
+    teamId?: string;
+    orgId?: string;
+    publicShorthand: boolean;
+    entityType?: string;
+    metadata: string[];
+    tags?: string;
+    onDuplicate?: string;
+}
+export declare function parseUploadArgs(args: string[]): ParsedArgs;
+export interface ValidatedConfig {
+    scope: 'user' | 'team' | 'org' | 'public';
+    projectId?: string;
+    teamId?: string;
+    orgId?: string;
+    isPublic: boolean;
+    entityType: string;
+    metadata: Record<string, string>;
+    tags: string[];
+    onDuplicate: 'skip' | 'reuse' | 'new-version';
+}
+export interface ValidationFailure {
+    ok: false;
+    message: string;
+}
+export interface ValidationSuccess {
+    ok: true;
+    config: ValidatedConfig;
+}
+/**
+ * Validate the parsed flag combination. Returns either a normalized config or
+ * a structured error message. Pure — does not write to stderr or exit.
+ */
+export declare function validateUploadConfig(parsed: ParsedArgs): ValidationFailure | ValidationSuccess;
 export interface UploadFileOptions {
     entityId?: string;
     entityName?: string;
+    config: ValidatedConfig;
 }
 export interface UploadResult {
     file: string;
     entityId?: string;
+    observationId?: string;
+    wasDuplicate?: boolean;
     error?: string;
+    /** True iff the failure was a server-side validation rejection. */
+    validationReason?: string;
     skipped?: boolean;
 }
 /**
- * Upload a single file to the grāmatr brain.
+ * Build the bulk_upload tool input for a given file. Exported so tests can
+ * assert the exact shape forwarded to the server.
+ */
+export declare function buildBulkUploadInput(filePath: string, buffer: Buffer, options: UploadFileOptions): Record<string, unknown>;
+/**
+ * Upload a single file via the `bulk_upload` MCP tool.
  */
-export declare function uploadFile(filePath: string, options?: UploadFileOptions): Promise<UploadResult>;
+export declare function uploadFile(filePath: string, options: UploadFileOptions): Promise<UploadResult>;
 /**
  * Collect all supported files in a directory.
  * @param dir        Absolute or relative path to the directory
@@ -58,7 +139,7 @@ export declare function uploadFile(filePath: string, options?: UploadFileOptions
 export declare function collectFiles(dir: string, recursive: boolean): string[];
 /**
  * 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 declare function runBrain(args: string[]): Promise<number>;
 //# sourceMappingURL=brain.d.ts.map

package/dist/bin/brain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../../src/bin/brain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,eAAO,MAAM,oBAAoB,aAAoD,CAAC;AAItF;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqBxB;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIzD;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAAC,MAAM,CAAC,CAkDjB;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,YAAY,CAAC,CA+DvB;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,EAAE,CAqBtE;AAmDD;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2F9D"}
+{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../../src/bin/brain.ts"],"names":[],"mappings":"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"}