@happyvertical/smrt-dev-mcp 0.40.37 → 0.40.39

package/AGENTS.md

@@ -8,7 +8,7 @@ deterministic SMRT ecosystem knowledge, and portable agent workflows.
 | Tool | Purpose |
 |------|---------|
 | `generate-smrt-class` | Generates `@smrt()` class with fields, decorator config, imports |
-| `introspect-project` | Scans project directory for SMRT objects, returns class/field/relationship report |
+| `introspect-project` | Scans project directory for SMRT objects; compact summary by default, `detail: 'full'` for field/schema/method detail |
 | `review-smrt-project` | Advisory downstream ecosystem alignment review for dependencies, storage, app shell, auth/tenancy, and manifest generation |
 | `reflect-knowledge` | Reports deterministic SMRT + HappyVertical SDK knowledge coverage and freshness |
 | `reflect-domain-knowledge` | Reports downstream/domain artifact coverage and freshness |
@@ -23,6 +23,46 @@ deterministic SMRT ecosystem knowledge, and portable agent workflows.
 | `list-agent-skills` | Lists bundled harness-agnostic agent skills |
 | `get-agent-skill` | Returns a bundled agent skill as Markdown plus optional references |
 
+## Knowledge Discovery (#2143)
+
+Discovery reads the workspace globs instead of assuming `<root>/packages`:
+`pnpm-workspace.yaml` `packages:` (literals, `dir/*`, `**`, `!` negations), then
+`package.json#workspaces`, then a `packages/*` fallback. `findProjectRoot` looks
+for a workspace declaration only — requiring a literal `packages/` directory is
+what mis-rooted every `apps/*` product. The workspace root is indexed whenever it
+has a `package.json`, which is how single-package repos resolve; it is scanned
+with the member package directories excluded so it can own objects without
+absorbing theirs.
+
+Workspace globs are a filesystem trust boundary. Absolute paths and `..`
+segments are rejected, and every matched directory is realpath-confined to the
+workspace root before its manifest is read. All positive globs share a 10,000
+directory-entry traversal budget; exceeding it is a fatal diagnostic that
+returns no partially discovered package set. This cardinality limit preserves
+valid deeply nested `**` workspaces without allowing repeated globstars to
+amplify into unbounded filesystem work. Discovery also stops before package
+reads when more than 512 packages match, revalidates confinement immediately
+before reading each package, and runs at most eight scanner fallbacks at once.
+
+Per package, objects resolve in this order, and the winner is recorded in
+`objectSource` with a reason:
+
+1. `domain-artifact` — `.smrt/`, `dist/`, or `src/manifest/smrt-knowledge.json`
+2. `manifest` — package-local manifest, after ownership validation
+3. `scanner` — `OxcScanner` + `ManifestAdapter` over the package's sources
+4. `none` — with a machine-readable reason
+
+The index exposes `coverage` and `diagnostics` (`schemaVersion: 2`). Zero
+discovered objects is an **error-grade** diagnostic that names the roots and
+artifact paths checked plus the fix, and it propagates into
+`smrt-architecture`/`smrt-review`/`reflect-*` results and prompt bundles.
+
+A workspace-root package has an empty `relativeDirectory`, so package paths are
+built with `packageRelativePath`/`packageDocPaths` rather than interpolation —
+otherwise emitted docs read `/AGENTS.md` and changed-file matching compares
+against a leading `/` and selects nothing. The root owns any changed path no
+member package owns, mirroring the member-excluded scan.
+
 ## Agent Skills
 
 Bundled skills live under `agent-skills/`. They are plain Markdown procedures
@@ -55,7 +95,7 @@ launcher or a small wrapper script with an absolute Node path.
 ## Key Files
 
 - `src/index.ts` — MCP server setup, tool registration
-- `src/knowledge/index.ts` — deterministic SMRT, SDK, and downstream domain knowledge discovery
+- `src/knowledge/index.ts` — deterministic SMRT, SDK, and downstream domain knowledge discovery; workspace-glob expansion, provenance, coverage, and diagnostics
 - `src/agent-skills.ts` — bundled skill registry and file loader
 - `agent-skills/smrt-code-review/SKILL.md` — downstream SMRT review procedure
 - `src/tools/generate-smrt-class.ts` — class generation logic and package-ready templates
@@ -73,3 +113,50 @@ launcher or a small wrapper script with an absolute Node path.
 - **Skill loading**: bundled skills must be included in `package.json` `files`
   because runtime reads them from the installed package directory
 - **Field type mapping**: `text`, `integer`, `decimal`, `boolean`, `datetime`, `json` — maps to SMRT field helpers (but prefer TypeScript defaults per framework convention)
+- **Never call `ManifestGenerator` from a tool path**: `generateSchemas` and
+  friends write progress lines to **stdout** through the SDK logger, which is the
+  MCP server's JSON-RPC channel. Suppressing `console.log` is not enough. The
+  knowledge scanner fallback therefore skips schema enrichment, so
+  scanner-provenance packages carry no `columnType` and contribute 0 to the
+  `uuidColumns` fact — `objectSource` makes that visible.
+- **Aggregate manifests poison relationship facts**: a runtime
+  `.smrt/manifest.json` frequently registers a package's dependencies too.
+  Objects whose `packageName`/`qualifiedName` disagree with the owning package are
+  rejected with a diagnostic. A *consuming* package's artifact can also
+  re-qualify its dependency's objects under its own name, which prefixes cannot
+  detect. `summarizeRelationshipsV2` therefore collapses a shared
+  `className::tableName` **only across a dependency edge** (a package can only
+  restate its own dependencies' objects) and reports
+  `duplicate-object-identity`. Two unrelated packages that happen to share a
+  class and table name — `Account::accounts` exists in both smrt-messages and
+  smrt-ledgers — are distinct objects and both keep contributing.
+  - Grouping is by **connected component**, not a greedy pairwise match: two
+    independent consumers restating one shared dependency have no edge to each
+    other, so a greedy pass would keep both and double-count.
+  - The surviving copy is the one the others **depend on**, since ownership
+    follows the dependency direction. Provenance is not a sufficient signal —
+    preferring a `scanner` copy kept `smrt-support`'s compatibility subtype over
+    the canonical `smrt-projects` model and changed the facts.
+- **Budgets are enforced at the transport boundary**: `KnowledgePackage` carries
+  the full `agentDoc` and domain manifest, so the MCP handlers project a compact
+  package record unless `detail: 'full'`. Library callers (the CLI) still receive
+  the full objects.
+- **Private packages skip packaging checks**: the `files` allowlist governs npm
+  publication, so `private: true` packages are exempt; authored docs are still
+  required. A workspace root is exempt from both — but **only when member
+  packages exist**. In a single-package repo the root is the published package,
+  so exempting every root would make the freshness gate a no-op for exactly the
+  layout #2143 added support for.
+- **Nested workspace members own no canonical docs**: instruction chains are
+  additive, so a package nested inside another workspace package (
+  `packages/smrt-playground/host`) must not carry `AGENTS.md`/`CLAUDE.md` — an
+  agent would load the parent's and its own. Those two checks are skipped for it
+  and a `nested-agents-md` error fires if one reappears; the expertise belongs in
+  the parent's linked `agents/<module>.md`.
+- **`maxChars` budgets the objects payload, not the whole response**: project
+  metadata and diagnostics are always returned in full, because a diagnostic is
+  how discovery reports that it found nothing (#2143). Budgeting it away would
+  hide the failure the caller needs to see.
+- **Coverage and diagnostics are computed before scope filtering**: they answer
+  "did discovery work", which is a whole-workspace property. Deriving them from
+  the scoped subset made `scope: 'sdk'` report a false discovery failure.

package/README.md

@@ -57,6 +57,70 @@ args = []
 
 Set `DEBUG=true` in the environment to enable diagnostic logging.
 
+## Workspace Discovery And Coverage
+
+Package discovery reads the workspace globs, so `apps/*` products are indexed
+the same as `packages/*` ones. Resolution order:
+
+1. `pnpm-workspace.yaml` `packages:` — literals, `dir/*`, `**`, and `!` negations
+2. `package.json#workspaces` (array or `{ packages: [...] }`)
+3. `packages/*` as a last-resort fallback
+
+Workspace globs must remain relative to the declared root: absolute paths and
+`..` segments are rejected, and matched directories are realpath-confined before
+their manifests are read. Positive globs share a 10,000 directory-entry
+traversal budget. Exceeding it stops discovery with an error diagnostic and no
+partial package set; deeply nested valid `**` matches remain supported because
+the limit is based on work performed rather than directory depth. A separate
+512-package cap prevents broad matches from fanning out package reads, package
+paths are revalidated immediately before those reads, and scanner fallbacks run
+with at most eight concurrent scanners.
+
+The workspace root is also indexed when it has a `package.json`, which is how
+single-package repositories work; it is scanned with the member package
+directories excluded so it can own objects without absorbing theirs. Per package, objects resolve from a domain
+artifact, then a package-local manifest, then a source scan
+(`@happyvertical/smrt-scanner`) — the same fallback `introspect-project` uses, so
+both paths agree on one root. Every package records `objectSource`
+(`domain-artifact | manifest | scanner | none`) plus a reason.
+
+Manifest objects that belong to another package are rejected rather than counted:
+a runtime `.smrt/manifest.json` is often an aggregate registering a package's
+dependencies too, and counting those inflates the relationship facts. A consuming
+package's artifact can also restate its dependency's objects under its own name,
+so `Relationships-v2` collapses a shared `className::tableName` across a
+dependency edge — by connected component, keeping the copy the others depend on —
+and reports `duplicate-object-identity`. Unrelated packages that share a class
+name stay distinct.
+
+The index therefore carries two extra blocks (`schemaVersion: 2`):
+
+- `coverage` — `workspaceGlobs`, `workspaceGlobSource`, `packageDirs`,
+  `packagesWithObjects`, and `packagesWithoutObjects` with a reason, the artifact
+  paths checked, and a remedy for each
+- `diagnostics` — discovery problems. Discovering **zero** objects is an
+  error-grade diagnostic naming the roots and artifact paths checked plus the
+  commands to fix it, so an unseen project is never reported as a project with no
+  model. `smrt-architecture`, `smrt-review`, and the `reflect-*` tools surface it.
+
+## Response Budgets
+
+Knowledge and introspection tools return a **summary** by default and accept
+`detail: "full"` for the complete payload.
+
+- `introspect-project` summary returns one compact record per object
+  (`className`, `qualifiedName`, `extends`, `tableName`, `tenantScope`,
+  `fieldCount`, compact relationship strings, `mcpOperations`). A response that
+  exceeds its character budget reports a `truncated` block with the omitted count
+  and filter guidance instead of being silently cut. `maxChars` overrides the
+  budget.
+- `smrt-architecture`, `smrt-review`, and the `build-*-context` tools list
+  authored `AGENTS.md` and module docs **by path** rather than embedding them,
+  and return compact package records.
+
+The `smrt dev:knowledge-*` CLI commands request `detail: "full"`, so their output
+is unchanged.
+
 ## Knowledge Boundary
 
 `smrt-dev-mcp` is model-agnostic. Its review and architecture tools do not call
@@ -157,9 +221,11 @@ available it falls back to `@happyvertical/smrt-scanner`.
 |-----------|------|----------|-------------|
 | `directory` | `string` | No | Project directory (default: cwd) |
 | `manifestPath` | `string` | No | Explicit manifest artifact path |
-| `includeFields` | `boolean` | No | Include field details |
-| `includeRelationships` | `boolean` | No | Analyze relationships |
-| `includeMethods` | `boolean` | No | Include public method details |
+| `detail` | `'summary' \| 'full'` | No | Default `summary`. `full` returns field, schema, and method detail |
+| `maxChars` | `number` | No | Response character budget; overflow is reported under `truncated` |
+| `includeFields` | `boolean` | No | Include field details (`detail: "full"` only) |
+| `includeRelationships` | `boolean` | No | Analyze relationships (`detail: "full"` only) |
+| `includeMethods` | `boolean` | No | Include public method details (`detail: "full"` only) |
 
 ### `review-smrt-project`
 
@@ -277,6 +343,7 @@ risks, questions, and the reusable architecture prompt bundle.
 | `idea` | `string` | No | Product or implementation idea |
 | `documentation` | `string` | No | Existing docs or requirements |
 | `focus` | `string` | No | Architecture concern to prioritize |
+| `detail` | `'summary' \| 'full'` | No | Default `summary`; `full` embeds authored docs and full package records |
 
 ### `list-agent-skills`
 

package/dist/index.d.ts

@@ -154,6 +154,8 @@ export declare const TOOLS: ({
             };
             directory?: undefined;
             manifestPath?: undefined;
+            detail?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -188,6 +190,16 @@ export declare const TOOLS: ({
                 type: string;
                 description: string;
             };
+            detail: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
+            maxChars: {
+                type: string;
+                description: string;
+            };
             includeFields: {
                 type: string;
                 description: string;
@@ -267,6 +279,8 @@ export declare const TOOLS: ({
             includeMcpConfig?: undefined;
             includeCliConfig?: undefined;
             manifestPath?: undefined;
+            detail?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -309,6 +323,8 @@ export declare const TOOLS: ({
             includeCliConfig?: undefined;
             directory?: undefined;
             manifestPath?: undefined;
+            detail?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -361,6 +377,8 @@ export declare const TOOLS: ({
             includeCliConfig?: undefined;
             directory?: undefined;
             manifestPath?: undefined;
+            detail?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -411,6 +429,8 @@ export declare const TOOLS: ({
             includeCliConfig?: undefined;
             directory?: undefined;
             manifestPath?: undefined;
+            detail?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -469,6 +489,8 @@ export declare const TOOLS: ({
             includeCliConfig?: undefined;
             directory?: undefined;
             manifestPath?: undefined;
+            detail?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -506,6 +528,12 @@ export declare const TOOLS: ({
             documentation: {
                 type: string;
             };
+            detail: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
             className?: undefined;
             properties?: undefined;
             baseClass?: undefined;
@@ -521,6 +549,7 @@ export declare const TOOLS: ({
             includeCliConfig?: undefined;
             directory?: undefined;
             manifestPath?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -567,6 +596,12 @@ export declare const TOOLS: ({
             package: {
                 type: string;
             };
+            detail: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
             className?: undefined;
             properties?: undefined;
             baseClass?: undefined;
@@ -582,6 +617,7 @@ export declare const TOOLS: ({
             includeCliConfig?: undefined;
             directory?: undefined;
             manifestPath?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -623,6 +659,12 @@ export declare const TOOLS: ({
                 enum: string[];
                 default: string;
             };
+            detail: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
             className?: undefined;
             properties?: undefined;
             baseClass?: undefined;
@@ -638,6 +680,7 @@ export declare const TOOLS: ({
             includeCliConfig?: undefined;
             directory?: undefined;
             manifestPath?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -672,6 +715,12 @@ export declare const TOOLS: ({
             focus: {
                 type: string;
             };
+            detail: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
             className?: undefined;
             properties?: undefined;
             baseClass?: undefined;
@@ -687,6 +736,7 @@ export declare const TOOLS: ({
             includeCliConfig?: undefined;
             directory?: undefined;
             manifestPath?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -730,6 +780,12 @@ export declare const TOOLS: ({
             package: {
                 type: string;
             };
+            detail: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
             className?: undefined;
             properties?: undefined;
             baseClass?: undefined;
@@ -745,6 +801,7 @@ export declare const TOOLS: ({
             includeCliConfig?: undefined;
             directory?: undefined;
             manifestPath?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -780,6 +837,8 @@ export declare const TOOLS: ({
             includeCliConfig?: undefined;
             directory?: undefined;
             manifestPath?: undefined;
+            detail?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;
@@ -831,6 +890,8 @@ export declare const TOOLS: ({
             includeCliConfig?: undefined;
             directory?: undefined;
             manifestPath?: undefined;
+            detail?: undefined;
+            maxChars?: undefined;
             includeFields?: undefined;
             includeRelationships?: undefined;
             includeMethods?: undefined;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmCH,eAAO,MAAM,cAAc,QAAuB,CAAC;AAcnD,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAyXjB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoCH,eAAO,MAAM,cAAc,QAAuB,CAAC;AAcnD,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAgbjB,CAAC"}