@massa-ai/core 1.2.1

package/dist/tools/search_project.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Search Project Tool
+ *
+ * Thin MCP tool layer — validates input and delegates to SearchController.
+ * All business logic lives in controllers/search-controller.ts.
+ */
+import { IToolHandler, ToolResponse } from "@massa-ai/shared";
+export declare class SearchProjectTool implements IToolHandler {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            projectId: {
+                type: string;
+                description: string;
+            };
+            projectPath: {
+                type: string;
+                description: string;
+            };
+            maxResults: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            minScore: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            responseMode: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            autoReindex: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+            include: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            exclude: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            explainScores: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+            format: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            fields: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            sessionId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    private controller;
+    constructor();
+    handle(params: unknown): Promise<ToolResponse>;
+}
+//# sourceMappingURL=search_project.d.ts.map

package/dist/tools/search_project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search_project.d.ts","sourceRoot":"","sources":["../../src/tools/search_project.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAsB9D,qBAAa,iBAAkB,YAAW,YAAY;IACpD,IAAI,SAAoB;IACxB,WAAW,SACiE;IAC5E,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA2ET;IAEF,OAAO,CAAC,UAAU,CAAmB;;IAM/B,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CA8BrD"}

package/dist/tools/search_project.js

@@ -0,0 +1,115 @@
+/**
+ * Search Project Tool
+ *
+ * Thin MCP tool layer — validates input and delegates to SearchController.
+ * All business logic lives in controllers/search-controller.ts.
+ */
+import { logger } from "@massa-ai/shared";
+import { SearchController } from "../controllers/search-controller.js";
+import { serializeToolResponse } from "./serialize.js";
+import { SearchServiceError } from "../services/search/search-diagnostics.js";
+export class SearchProjectTool {
+    name = "search_project";
+    description = "Search for code in an indexed project using semantic and keyword search";
+    inputSchema = {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "Search query (natural language or keywords)",
+            },
+            projectId: {
+                type: "string",
+                description: "Project ID to search in",
+            },
+            projectPath: {
+                type: "string",
+                description: "Project path (required for autoReindex)",
+            },
+            maxResults: {
+                type: "number",
+                description: "Maximum number of results to return",
+                default: 10,
+            },
+            minScore: {
+                type: "number",
+                description: "Minimum relevance score (0-1)",
+                default: 0.3,
+            },
+            responseMode: {
+                type: "string",
+                enum: ["summary", "full", "enriched"],
+                description: "Response format: 'summary' (preview only), 'full' (full content), 'enriched' (full content + fileImports + parentSymbol)",
+                default: "summary",
+            },
+            autoReindex: {
+                type: "boolean",
+                description: "Automatically reindex if project index is stale (can increase latency)",
+                default: false,
+            },
+            include: {
+                type: "array",
+                items: { type: "string" },
+                description: "Glob patterns to include (e.g., ['src/components/**/*.tsx', 'src/utils/**'])",
+            },
+            exclude: {
+                type: "array",
+                items: { type: "string" },
+                description: "Glob patterns to exclude (e.g., ['**/*.test.*', '**/*.spec.*'])",
+            },
+            explainScores: {
+                type: "boolean",
+                description: "Include detailed score breakdown (vector, keyword, RRF components)",
+                default: false,
+            },
+            format: {
+                type: "string",
+                enum: ["json", "toon", "tree"],
+                description: "Output format. 'toon' (default) encodes the raw object. 'json' emits the raw object. 'tree' (Wave 5 FR-06) emits a text-indented grouped model via the shared groupRowsByPrefix helper (groups results by file). Default: toon.",
+                default: "toon",
+            },
+            fields: {
+                type: "array",
+                items: { type: "string" },
+                description: "Projection — keep only these keys (dotted paths supported, e.g. ['nodes.symbol']). Absent/empty → full data.",
+            },
+            sessionId: {
+                type: "string",
+                description: "Session ID for search hook scoping (enables session memory persistence)",
+            },
+        },
+        required: ["query", "projectId"],
+    };
+    controller;
+    constructor() {
+        this.controller = SearchController.getInstance();
+    }
+    async handle(params) {
+        const p = params;
+        const format = p.format || "toon";
+        const { fields } = p;
+        try {
+            const result = await this.controller.searchProject(p);
+            // Wave 5 FR-07: tree format groups results by file via the shared
+            // groupRowsByPrefix helper. json/toon unchanged when tree not selected.
+            const groupOpts = format === "tree" ? { format, fields, groupBy: { file: "filePath" } } : { format, fields };
+            return serializeToolResponse(result, groupOpts);
+        }
+        catch (error) {
+            logger.error("Failed to search project", error, {
+                query: p.query,
+                projectId: p.projectId,
+            });
+            // Transport layers own status codes and the shared sanitized envelope.
+            // Preserve the typed error so HTTP and MCP cannot mistake an outage for
+            // an ordinary tool-level failure returned with status 200.
+            if (error instanceof SearchServiceError)
+                throw error;
+            return {
+                success: false,
+                error: `Failed to search project: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=search_project.js.map

package/dist/tools/search_project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search_project.js","sourceRoot":"","sources":["../../src/tools/search_project.ts"],"names":[],"mappings":"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"}

package/dist/tools/serialize-interfaces.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Serialize interfaces — Wave 5 FR-06 / N5 / AD-W5-020.
+ *
+ * Explicit TypeScript contracts for the grouped-format helper exported by
+ * `serialize.ts`. B3 (and any downstream consumer) imports these verbatim —
+ * no re-implementation. Interface drift fails the batch per FR-26 / AC-28.
+ *
+ * The grouped model is the single shape both `format:"tree"` (text-indented)
+ * and `format:"json"` (when `grouped:true` is selected) emit. One shared
+ * helper (`groupRowsByPrefix`) produces it; both encoders route through it
+ * (AD-W5-011). A mutation test in `serialize.test.ts` asserts both formats
+ * change together when the helper is mutated.
+ */
+/**
+ * Options for {@link GroupedResult} grouping via `groupRowsByPrefix`.
+ *
+ * Field-name style: the caller passes the NAME of the field on each row to
+ * use for grouping, not the value. This keeps the helper row-shape-agnostic
+ * (works for impacted symbols, search results, references, etc.) without
+ * per-tool adapters.
+ *
+ *   groupRowsByPrefix(impacted, { file: "file" })
+ *     → derives a 2-segment prefix from each row's `file` field
+ *       (`src/services/foo.ts` → `src/services`) and groups by that prefix.
+ *
+ *   groupRowsByPrefix(results, { qnPrefix: "qnPrefix", file: "filePath" })
+ *     → groups by the row's explicit `qnPrefix` field; `filePath` is kept as
+ *       a representative file per group when all rows in the group share one.
+ */
+export interface GroupRowsByPrefixOptions {
+    /**
+     * Field name on each row whose value is the explicit group key (the 2-
+     * segment prefix). When omitted, the prefix is derived from `file` via
+     * `twoSegmentPrefix`. When the row has no such field, `(other)` is used.
+     */
+    qnPrefix?: string;
+    /**
+     * Field name on each row whose value is the file path. Used to derive the
+     * group key when `qnPrefix` is not present, and to populate the
+     * representative `file` on each group when all rows in the group share one.
+     */
+    file?: string;
+    /**
+     * Cap rows per group. Default 50. Rows past the cap within a group are
+     * dropped and counted in `rows_omitted` (Wave 4 N4 parity).
+     */
+    maxRowsPerGroup?: number;
+    /**
+     * Cap groups. Default 20. Groups past the cap (sorted by row count desc)
+     * fold into a single `(other)` overflow group; their count is surfaced in
+     * `groups_omitted`.
+     */
+    maxGroups?: number;
+}
+/**
+ * One row inside a grouped result. Opaque — the helper does not interpret row
+ * contents beyond the `qnPrefix` / `file` fields used for grouping.
+ */
+export type GroupedRow = Record<string, unknown>;
+/**
+ * One group in a grouped result. `rows` is the (possibly truncated) list of
+ * rows assigned to this group; `rows_shown` / `rows_omitted` mirror the Wave 4
+ * N4 `*_shown` / `*_omitted` pair at the group level.
+ */
+export interface GroupedGroup {
+    /** 2-segment path prefix that keys this group, or `(other)` for overflow. */
+    qnPrefix: string;
+    /**
+     * Representative file path for the group when all rows share one (only set
+     * when `opts.file` was provided). Undefined when the group spans multiple
+     * files or no file field was used.
+     */
+    file?: string;
+    /** Rows emitted for this group (capped at `maxRowsPerGroup`). */
+    rows: GroupedRow[];
+    /** Rows emitted for this group (== rows.length). */
+    rows_shown: number;
+    /** Rows dropped from this group by the per-group cap. */
+    rows_omitted: number;
+}
+/**
+ * Result of `groupRowsByPrefix`. The single shape both `format:"tree"` and
+ * `format:"json"` (with `grouped:true`) emit. Totals mirror the Wave 4 N4
+ * `*_total` / `*_shown` / `*_omitted` pattern at both the rows and groups
+ * level so callers can surface exact pre-clamp counts.
+ */
+export interface GroupedResult {
+    /** Pre-clamp total rows received by the helper. */
+    rows_total: number;
+    /** Rows emitted across all groups (sum of per-group rows_shown). */
+    rows_shown: number;
+    /** Rows dropped by per-group caps (sum of per-group rows_omitted). */
+    rows_omitted: number;
+    /** Pre-clamp count of distinct groups. */
+    groups_total: number;
+    /** Groups emitted (includes the `(other)` overflow group when present). */
+    groups_shown: number;
+    /** Distinct groups folded into `(other)` by the groups cap. */
+    groups_omitted: number;
+    /** Emitted groups, sorted by row count desc then qnPrefix asc. */
+    groups: GroupedGroup[];
+}
+//# sourceMappingURL=serialize-interfaces.d.ts.map

package/dist/tools/serialize-interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-interfaces.d.ts","sourceRoot":"","sources":["../../src/tools/serialize-interfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB"}

package/dist/tools/serialize-interfaces.js

@@ -0,0 +1,15 @@
+/**
+ * Serialize interfaces — Wave 5 FR-06 / N5 / AD-W5-020.
+ *
+ * Explicit TypeScript contracts for the grouped-format helper exported by
+ * `serialize.ts`. B3 (and any downstream consumer) imports these verbatim —
+ * no re-implementation. Interface drift fails the batch per FR-26 / AC-28.
+ *
+ * The grouped model is the single shape both `format:"tree"` (text-indented)
+ * and `format:"json"` (when `grouped:true` is selected) emit. One shared
+ * helper (`groupRowsByPrefix`) produces it; both encoders route through it
+ * (AD-W5-011). A mutation test in `serialize.test.ts` asserts both formats
+ * change together when the helper is mutated.
+ */
+export {};
+//# sourceMappingURL=serialize-interfaces.js.map

package/dist/tools/serialize-interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-interfaces.js","sourceRoot":"","sources":["../../src/tools/serialize-interfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/tools/serialize.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared serializer for tool success-path responses.
+ *
+ * Owns two concerns that were previously inlined per-tool:
+ *   1. `fields` projection (shallow + dotted walk; arrays element-wise)
+ *   2. `format` encoding (json raw object | toon string)
+ *
+ * Contract (plan-critic boundary): wrap ONLY the success-path return of a tool.
+ * Error / catch / not-found branches — including any `data:{hint}` on the error
+ * branch — are returned directly and MUST NOT pass through this helper. This
+ * keeps the error wire-shape byte-identical and avoids projecting/throwing on
+ * partial data.
+ *
+ * Defaults are resolved by the CALLING tool and passed in as literals; this
+ * helper never picks a default. The helper only branches on the literal
+ * "toon" — anything else (including "json" or undefined) returns the raw object.
+ */
+import type { ToolResponse } from "@massa-ai/shared";
+import type { GroupRowsByPrefixOptions, GroupedResult, GroupedRow } from "./serialize-interfaces.js";
+export interface SerializeOpts {
+    format?: "json" | "toon" | "tree";
+    fields?: string[];
+    /**
+     * Wave 5 FR-06 / N5: when `true` AND a `groupBy` field is present, the
+     * helper runs `groupRowsByPrefix` and emits the grouped model (AD-W5-011).
+     * `format:"tree"` implies grouped output (text-indented). `format:"json"`
+     * with `grouped:true` emits the same grouped model as JSON. One shared
+     * helper drives both — a mutation test asserts they change together.
+     */
+    grouped?: boolean;
+    /**
+     * Grouping options for `groupRowsByPrefix`. Required when `grouped:true`
+     * or `format:"tree"` is used with array/row-shaped data.
+     */
+    groupBy?: GroupRowsByPrefixOptions;
+}
+/**
+ * Project (and optionally TOON-encode / group) a tool success-path result.
+ *
+ * Projection runs BEFORE encoding so `fields` composes with all formats.
+ *
+ * `format:"tree"` (Wave 5 FR-06 / N5) emits a text-indented grouped model:
+ *   group header lines (prefix + counts), then each row under it, indented.
+ *   Both `tree` and `json` (with `grouped:true`) route through ONE shared
+ *   `groupRowsByPrefix` helper (AD-W5-011) so a mutation in the helper
+ *   changes both formats together (AC-6 mutation test).
+ */
+export declare function serializeToolResponse(result: unknown, opts?: SerializeOpts): ToolResponse;
+/**
+ * Field projection per spec AC P3 / design.md §2.
+ *
+ * - absent/empty `fields` → full data (no projection)
+ * - array `data`          → element-wise map
+ * - non-object `data`     → unchanged (scalar)
+ * - object `data`         → pick present keys; dotted walks via projectPath
+ * - unknown key / broken midpath → silently dropped (no throw)
+ */
+export declare function projectFields(data: unknown, fields?: string[]): unknown;
+/**
+ * M26: Unescape an escaped JSON string and parse it into a nested structure.
+ *
+ * If the value is a string that looks like escaped JSON (starts with `{` or
+ * `[` after unescaping, or has escaped quotes `\"`), attempt to JSON.parse it.
+ * On success, return the parsed nested structure. On failure, return the
+ * original value with no throw (clear error is handled by the caller).
+ *
+ * If the value is already an object/array, return it as-is (no re-parsing).
+ * If the value is a scalar (number, boolean, null), return it as-is.
+ */
+export declare function unescapeJsonField(value: unknown): unknown;
+/**
+ * Group rows by a 2-segment path prefix derived from each row (or taken from
+ * an explicit `qnPrefix` field). Cap rows per group + cap groups; fold
+ * overflow into `(other)`. Pure: no I/O.
+ *
+ * @param rows  Row-shaped objects (search results, impacted symbols, refs…).
+ * @param opts  Grouping options. `file` = field name holding the file path
+ *              (used to derive the prefix + representative file per group);
+ *              `qnPrefix` = explicit prefix field (wins over `file` when set).
+ */
+export declare function groupRowsByPrefix(rows: readonly GroupedRow[], opts?: GroupRowsByPrefixOptions): GroupedResult;
+/**
+ * Extract the 2-segment path prefix: drop the filename (last segment), then
+ * keep up to 2 leading directory segments. Same heuristic as
+ * `impact-analysis.ts#twoSegmentPrefix` so the rollup is consistent across
+ * tools (FR-03 parity).
+ *
+ *   `path/to/file.ts`   → `path/to`
+ *   `a/b/c/d.ts`        → `a/b`
+ *   `src/a.ts`          → `src`
+ *   `root.ts`           → `root.ts`
+ */
+export declare function twoSegmentPrefix(filePath: string): string;
+/**
+ * Render a {@link GroupedResult} as a text-indented tree string (AD-W5-011).
+ * Each group is a header line `prefix (shown/total rows)` followed by its
+ * rows indented two spaces. Counts are surfaced so a caller can see
+ * truncation without parsing JSON.
+ */
+export declare function groupedToTree(grouped: GroupedResult): string;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/tools/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/tools/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EACV,wBAAwB,EACxB,aAAa,EAEb,UAAU,EACX,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,wBAAwB,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,GAAE,aAAkB,GACvB,YAAY,CAyBd;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CA0BvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA8BzD;AAgFD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,UAAU,EAAE,EAC3B,IAAI,GAAE,wBAA6B,GAClC,aAAa,CAsFf;AAwBD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAkB5D"}