@dxos/introspect-tools 0.0.0 → 0.8.4-main.05e74ebcff
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +105 -0
- package/dist/lib/browser/index.mjs +258 -42
- package/dist/lib/browser/index.mjs.map +4 -4
- package/dist/lib/browser/meta.json +1 -1
- package/dist/lib/node-esm/index.mjs +258 -42
- package/dist/lib/node-esm/index.mjs.map +4 -4
- package/dist/lib/node-esm/meta.json +1 -1
- package/dist/types/src/index.d.ts +2 -1
- package/dist/types/src/index.d.ts.map +1 -1
- package/dist/types/src/metadata.d.ts +8 -0
- package/dist/types/src/metadata.d.ts.map +1 -1
- package/dist/types/src/metadata.test.d.ts +2 -0
- package/dist/types/src/metadata.test.d.ts.map +1 -0
- package/dist/types/src/output-schemas.d.ts +250 -0
- package/dist/types/src/output-schemas.d.ts.map +1 -0
- package/dist/types/src/schemas.d.ts +21 -0
- package/dist/types/src/schemas.d.ts.map +1 -1
- package/dist/types/tsconfig.tsbuildinfo +1 -1
- package/package.json +10 -10
- package/src/index.ts +42 -0
- package/src/metadata.test.ts +55 -0
- package/src/metadata.ts +44 -0
- package/src/output-schemas.ts +223 -0
- package/src/schemas.ts +45 -3
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dxos/introspect-tools",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.4-main.05e74ebcff",
|
|
4
4
|
"description": "Tool definitions (Effect Schema inputs + metadata) shared between the introspect-mcp server and downstream consumers (react-ui-introspect, etc.). Browser-safe — no Node-only dependencies.",
|
|
5
5
|
"homepage": "https://dxos.org",
|
|
6
6
|
"bugs": "https://github.com/dxos/dxos/issues",
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
"type": "git",
|
|
9
9
|
"url": "https://github.com/dxos/dxos"
|
|
10
10
|
},
|
|
11
|
-
"license": "
|
|
11
|
+
"license": "FSL-1.1-Apache-2.0",
|
|
12
12
|
"author": "info@dxos.org",
|
|
13
13
|
"sideEffects": false,
|
|
14
14
|
"type": "module",
|
|
@@ -26,17 +26,17 @@
|
|
|
26
26
|
"src"
|
|
27
27
|
],
|
|
28
28
|
"dependencies": {
|
|
29
|
-
"
|
|
30
|
-
"
|
|
31
|
-
"
|
|
32
|
-
"zod": "
|
|
29
|
+
"effect": "3.20.0",
|
|
30
|
+
"zod": "^4.0.0",
|
|
31
|
+
"@dxos/util": "0.8.4-main.05e74ebcff",
|
|
32
|
+
"@dxos/effect-zod": "0.8.4-main.05e74ebcff"
|
|
33
33
|
},
|
|
34
34
|
"devDependencies": {
|
|
35
|
-
"@types/node": "
|
|
36
|
-
"typescript": "
|
|
37
|
-
"vitest": "
|
|
35
|
+
"@types/node": "22.10.2",
|
|
36
|
+
"typescript": "^6.0.3",
|
|
37
|
+
"vitest": "4.1.6"
|
|
38
38
|
},
|
|
39
39
|
"publishConfig": {
|
|
40
40
|
"access": "public"
|
|
41
41
|
}
|
|
42
|
-
}
|
|
42
|
+
}
|
package/src/index.ts
CHANGED
|
@@ -8,11 +8,49 @@
|
|
|
8
8
|
|
|
9
9
|
export { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, type ListOptions } from './limits';
|
|
10
10
|
export { TOOL_METADATA, inputSchemaToZod, type ToolMetadata } from './metadata';
|
|
11
|
+
export {
|
|
12
|
+
CapabilitySchema,
|
|
13
|
+
IdiomHostKindSchema,
|
|
14
|
+
IdiomHostSchema,
|
|
15
|
+
IdiomSchema,
|
|
16
|
+
OperationSchema,
|
|
17
|
+
PackageDetailSchema,
|
|
18
|
+
PackageSchema,
|
|
19
|
+
PluginDetailSchema,
|
|
20
|
+
PluginIdSchema,
|
|
21
|
+
PluginSchema,
|
|
22
|
+
SchemaSchema,
|
|
23
|
+
SourceLocationSchema,
|
|
24
|
+
SurfaceSchema,
|
|
25
|
+
SymbolDetailSchema,
|
|
26
|
+
SymbolIncludeSchema,
|
|
27
|
+
SymbolKindSchema,
|
|
28
|
+
SymbolMatchSchema,
|
|
29
|
+
type Capability,
|
|
30
|
+
type Idiom,
|
|
31
|
+
type IdiomHost,
|
|
32
|
+
type IdiomHostKind,
|
|
33
|
+
type Operation,
|
|
34
|
+
type Package,
|
|
35
|
+
type PackageDetail,
|
|
36
|
+
type Plugin,
|
|
37
|
+
type PluginDetail,
|
|
38
|
+
type PluginId,
|
|
39
|
+
type PluginsFile,
|
|
40
|
+
type SchemaContribution,
|
|
41
|
+
type SourceLocation,
|
|
42
|
+
type Surface,
|
|
43
|
+
type SymbolDetail,
|
|
44
|
+
type SymbolInclude,
|
|
45
|
+
type SymbolKind,
|
|
46
|
+
type SymbolMatch,
|
|
47
|
+
} from './output-schemas';
|
|
11
48
|
export {
|
|
12
49
|
FindSymbolInput,
|
|
13
50
|
GetPackageInput,
|
|
14
51
|
GetSymbolInput,
|
|
15
52
|
ListCapabilitiesInput,
|
|
53
|
+
ListIdiomsInput,
|
|
16
54
|
ListOperationsInput,
|
|
17
55
|
ListOptionsInput,
|
|
18
56
|
ListPackagesInput,
|
|
@@ -20,14 +58,18 @@ export {
|
|
|
20
58
|
ListSchemasInput,
|
|
21
59
|
ListSurfacesInput,
|
|
22
60
|
ListSymbolsInput,
|
|
61
|
+
PickerAnnotationId,
|
|
62
|
+
getPicker,
|
|
23
63
|
type FindSymbolArgs,
|
|
24
64
|
type GetPackageArgs,
|
|
25
65
|
type GetSymbolArgs,
|
|
26
66
|
type ListCapabilitiesArgs,
|
|
67
|
+
type ListIdiomsArgs,
|
|
27
68
|
type ListOperationsArgs,
|
|
28
69
|
type ListPackagesArgs,
|
|
29
70
|
type ListPluginsArgs,
|
|
30
71
|
type ListSchemasArgs,
|
|
31
72
|
type ListSurfacesArgs,
|
|
32
73
|
type ListSymbolsArgs,
|
|
74
|
+
type PickerKind,
|
|
33
75
|
} from './schemas';
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
import { describe, test } from 'vitest';
|
|
6
|
+
|
|
7
|
+
import { TOOL_METADATA } from './metadata';
|
|
8
|
+
|
|
9
|
+
// Top-level field key each tool's outputSchema must expose. MCP requires
|
|
10
|
+
// `structuredContent` to be a JSON object, so every tool wraps its
|
|
11
|
+
// result(s) under a stable key — this is the contract downstream
|
|
12
|
+
// consumers (e.g. dxos/edge introspect-service) bind to.
|
|
13
|
+
const EXPECTED_OUTPUT_KEYS: Record<string, string> = {
|
|
14
|
+
list_packages: 'packages',
|
|
15
|
+
get_package: 'package',
|
|
16
|
+
list_symbols: 'symbols',
|
|
17
|
+
find_symbol: 'matches',
|
|
18
|
+
get_symbol: 'symbol',
|
|
19
|
+
list_plugins: 'plugins',
|
|
20
|
+
list_surfaces: 'surfaces',
|
|
21
|
+
list_capabilities: 'capabilities',
|
|
22
|
+
list_operations: 'operations',
|
|
23
|
+
list_schemas: 'schemas',
|
|
24
|
+
list_idioms: 'idioms',
|
|
25
|
+
};
|
|
26
|
+
|
|
27
|
+
describe('TOOL_METADATA', () => {
|
|
28
|
+
test('every entry declares title, description, inputSchema, outputSchema', ({ expect }) => {
|
|
29
|
+
for (const [name, meta] of Object.entries(TOOL_METADATA)) {
|
|
30
|
+
expect(meta.title, `${name}.title`).toBeTypeOf('string');
|
|
31
|
+
expect(meta.description, `${name}.description`).toBeTypeOf('string');
|
|
32
|
+
expect(meta.inputSchema, `${name}.inputSchema`).toBeDefined();
|
|
33
|
+
expect(meta.inputSchema.fields, `${name}.inputSchema.fields`).toBeDefined();
|
|
34
|
+
expect(meta.outputSchema, `${name}.outputSchema`).toBeDefined();
|
|
35
|
+
expect(meta.outputSchema.fields, `${name}.outputSchema.fields`).toBeDefined();
|
|
36
|
+
}
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
test('outputSchema top-level key matches the documented convention', ({ expect }) => {
|
|
40
|
+
for (const [name, expectedKey] of Object.entries(EXPECTED_OUTPUT_KEYS)) {
|
|
41
|
+
const meta = TOOL_METADATA[name];
|
|
42
|
+
expect(meta, `tool ${name} missing from TOOL_METADATA`).toBeDefined();
|
|
43
|
+
const keys = Object.keys(meta.outputSchema.fields);
|
|
44
|
+
expect(keys, `${name}.outputSchema fields`).toEqual([expectedKey]);
|
|
45
|
+
}
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
test('all registered tools have an expected output key entry', ({ expect }) => {
|
|
49
|
+
// Catches new tools added to TOOL_METADATA without a corresponding
|
|
50
|
+
// documented output-key convention.
|
|
51
|
+
for (const name of Object.keys(TOOL_METADATA)) {
|
|
52
|
+
expect(EXPECTED_OUTPUT_KEYS[name], `tool ${name} missing from EXPECTED_OUTPUT_KEYS`).toBeDefined();
|
|
53
|
+
}
|
|
54
|
+
});
|
|
55
|
+
});
|
package/src/metadata.ts
CHANGED
|
@@ -16,11 +16,23 @@ import type { z } from 'zod';
|
|
|
16
16
|
import { effectFieldsToZod } from '@dxos/effect-zod';
|
|
17
17
|
import { trim } from '@dxos/util';
|
|
18
18
|
|
|
19
|
+
import {
|
|
20
|
+
CapabilitySchema,
|
|
21
|
+
IdiomSchema,
|
|
22
|
+
OperationSchema,
|
|
23
|
+
PackageSchema,
|
|
24
|
+
PluginSchema,
|
|
25
|
+
SchemaSchema,
|
|
26
|
+
SurfaceSchema,
|
|
27
|
+
SymbolDetailSchema,
|
|
28
|
+
SymbolMatchSchema,
|
|
29
|
+
} from './output-schemas';
|
|
19
30
|
import {
|
|
20
31
|
FindSymbolInput,
|
|
21
32
|
GetPackageInput,
|
|
22
33
|
GetSymbolInput,
|
|
23
34
|
ListCapabilitiesInput,
|
|
35
|
+
ListIdiomsInput,
|
|
24
36
|
ListOperationsInput,
|
|
25
37
|
ListPackagesInput,
|
|
26
38
|
ListPluginsInput,
|
|
@@ -52,6 +64,15 @@ export type ToolMetadata = {
|
|
|
52
64
|
* (react-ui-form, etc.) use this directly.
|
|
53
65
|
*/
|
|
54
66
|
inputSchema: Schema.Struct<any>;
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Effect Schema struct describing the tool's success return shape.
|
|
70
|
+
* MCP's `structuredContent` must be a JSON object, so each tool wraps
|
|
71
|
+
* its item(s) under a stable top-level key (e.g. `{ packages: [...] }`,
|
|
72
|
+
* `{ package: null | {...} }`). Consumers building Effect AI Tools can
|
|
73
|
+
* pass this directly as `success` to `Tool.make`.
|
|
74
|
+
*/
|
|
75
|
+
outputSchema: Schema.Struct<any>;
|
|
55
76
|
};
|
|
56
77
|
|
|
57
78
|
/**
|
|
@@ -71,6 +92,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
|
|
|
71
92
|
Returns lightweight rows; call get_package for dependency and entry-point detail.
|
|
72
93
|
`,
|
|
73
94
|
inputSchema: ListPackagesInput,
|
|
95
|
+
outputSchema: Schema.Struct({ packages: Schema.Array(PackageSchema) }),
|
|
74
96
|
},
|
|
75
97
|
get_package: {
|
|
76
98
|
title: 'Get package detail',
|
|
@@ -80,6 +102,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
|
|
|
80
102
|
Use after list_packages or when the user references a package directly.
|
|
81
103
|
`,
|
|
82
104
|
inputSchema: GetPackageInput,
|
|
105
|
+
outputSchema: Schema.Struct({ package: Schema.NullOr(PackageSchema) }),
|
|
83
106
|
},
|
|
84
107
|
list_symbols: {
|
|
85
108
|
title: 'List all exported symbols of a package',
|
|
@@ -89,6 +112,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
|
|
|
89
112
|
Returns lightweight rows with refs you can pass to get_symbol; capped at 30 — refine with \`kind\` or call get_symbol directly.
|
|
90
113
|
`,
|
|
91
114
|
inputSchema: ListSymbolsInput,
|
|
115
|
+
outputSchema: Schema.Struct({ symbols: Schema.Array(SymbolMatchSchema) }),
|
|
92
116
|
},
|
|
93
117
|
find_symbol: {
|
|
94
118
|
title: 'Find an exported symbol by name',
|
|
@@ -98,6 +122,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
|
|
|
98
122
|
Returns refs you can pass to get_symbol. Ranking: exact match, then prefix, then substring.
|
|
99
123
|
`,
|
|
100
124
|
inputSchema: FindSymbolInput,
|
|
125
|
+
outputSchema: Schema.Struct({ matches: Schema.Array(SymbolMatchSchema) }),
|
|
101
126
|
},
|
|
102
127
|
get_symbol: {
|
|
103
128
|
title: 'Get symbol detail',
|
|
@@ -107,6 +132,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
|
|
|
107
132
|
Pass include=["source"] to expand the full declaration text, include=["jsdoc"] for the full JSDoc body.
|
|
108
133
|
`,
|
|
109
134
|
inputSchema: GetSymbolInput,
|
|
135
|
+
outputSchema: Schema.Struct({ symbol: Schema.NullOr(SymbolDetailSchema) }),
|
|
110
136
|
},
|
|
111
137
|
list_plugins: {
|
|
112
138
|
title: 'List Composer plugins',
|
|
@@ -116,6 +142,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
|
|
|
116
142
|
Filter by \`id\` substring (e.g. "markdown") to narrow the list.
|
|
117
143
|
`,
|
|
118
144
|
inputSchema: ListPluginsInput,
|
|
145
|
+
outputSchema: Schema.Struct({ plugins: Schema.Array(PluginSchema) }),
|
|
119
146
|
},
|
|
120
147
|
list_surfaces: {
|
|
121
148
|
title: 'List surfaces',
|
|
@@ -125,6 +152,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
|
|
|
125
152
|
Filter by \`id\` (plugin id) to scope to a single plugin's surfaces.
|
|
126
153
|
`,
|
|
127
154
|
inputSchema: ListSurfacesInput,
|
|
155
|
+
outputSchema: Schema.Struct({ surfaces: Schema.Array(SurfaceSchema) }),
|
|
128
156
|
},
|
|
129
157
|
list_capabilities: {
|
|
130
158
|
title: 'List capability contributions',
|
|
@@ -133,6 +161,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
|
|
|
133
161
|
keys are produced (or required) by which plugins. Filter by \`id\` (plugin id) to scope to a single plugin.
|
|
134
162
|
`,
|
|
135
163
|
inputSchema: ListCapabilitiesInput,
|
|
164
|
+
outputSchema: Schema.Struct({ capabilities: Schema.Array(CapabilitySchema) }),
|
|
136
165
|
},
|
|
137
166
|
list_operations: {
|
|
138
167
|
title: 'List operations',
|
|
@@ -144,6 +173,7 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
|
|
|
144
173
|
to scope to a single plugin.
|
|
145
174
|
`,
|
|
146
175
|
inputSchema: ListOperationsInput,
|
|
176
|
+
outputSchema: Schema.Struct({ operations: Schema.Array(OperationSchema) }),
|
|
147
177
|
},
|
|
148
178
|
list_schemas: {
|
|
149
179
|
title: 'List schemas',
|
|
@@ -153,6 +183,20 @@ export const TOOL_METADATA: Record<string, ToolMetadata> = {
|
|
|
153
183
|
Filter by \`id\` (plugin id, e.g. "org.dxos.plugin.markdown") to scope to a single plugin's schemas.
|
|
154
184
|
`,
|
|
155
185
|
inputSchema: ListSchemasInput,
|
|
186
|
+
outputSchema: Schema.Struct({ schemas: Schema.Array(SchemaSchema) }),
|
|
187
|
+
},
|
|
188
|
+
list_idioms: {
|
|
189
|
+
title: 'List idioms',
|
|
190
|
+
description: trim`
|
|
191
|
+
List idioms catalogued across the monorepo. An *idiom* is a JSDoc-tagged
|
|
192
|
+
reference example (\`@idiom <slug>\`) that pins the canonical way to use a
|
|
193
|
+
symbol — applicability, anti-pattern, and links to related idioms. Use this
|
|
194
|
+
to discover how a feature is meant to be used, or to find a worked example
|
|
195
|
+
before writing new code. Filter by \`slug\` substring or by \`hostKind\`
|
|
196
|
+
(\`symbol\`, \`story\`, \`test\`).
|
|
197
|
+
`,
|
|
198
|
+
inputSchema: ListIdiomsInput,
|
|
199
|
+
outputSchema: Schema.Struct({ idioms: Schema.Array(IdiomSchema) }),
|
|
156
200
|
},
|
|
157
201
|
};
|
|
158
202
|
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
// Effect Schema definitions for every introspect tool *result* (output) shape.
|
|
6
|
+
//
|
|
7
|
+
// These are the source of truth for the data returned by `@dxos/introspect`.
|
|
8
|
+
// `@dxos/introspect/src/types.ts` re-derives its TypeScript types from these
|
|
9
|
+
// schemas, and downstream consumers that can't depend on `@dxos/introspect`
|
|
10
|
+
// (browser/worker contexts — `@dxos/introspect` pulls Node-only `ts-morph`
|
|
11
|
+
// and `glob`) import the schemas directly.
|
|
12
|
+
|
|
13
|
+
import * as Schema from 'effect/Schema';
|
|
14
|
+
|
|
15
|
+
//
|
|
16
|
+
// Primitives
|
|
17
|
+
//
|
|
18
|
+
|
|
19
|
+
export const SymbolKindSchema = Schema.Literal(
|
|
20
|
+
'function',
|
|
21
|
+
'class',
|
|
22
|
+
'interface',
|
|
23
|
+
'type',
|
|
24
|
+
'enum',
|
|
25
|
+
'variable',
|
|
26
|
+
'namespace',
|
|
27
|
+
'unknown',
|
|
28
|
+
);
|
|
29
|
+
export type SymbolKind = typeof SymbolKindSchema.Type;
|
|
30
|
+
|
|
31
|
+
export const SymbolIncludeSchema = Schema.Literal('source', 'jsdoc');
|
|
32
|
+
export type SymbolInclude = typeof SymbolIncludeSchema.Type;
|
|
33
|
+
|
|
34
|
+
export const SourceLocationSchema = Schema.Struct({
|
|
35
|
+
file: Schema.String,
|
|
36
|
+
line: Schema.Number,
|
|
37
|
+
column: Schema.Number,
|
|
38
|
+
});
|
|
39
|
+
export type SourceLocation = typeof SourceLocationSchema.Type;
|
|
40
|
+
|
|
41
|
+
export const PluginIdSchema = Schema.String;
|
|
42
|
+
export type PluginId = typeof PluginIdSchema.Type;
|
|
43
|
+
|
|
44
|
+
//
|
|
45
|
+
// Packages
|
|
46
|
+
//
|
|
47
|
+
|
|
48
|
+
export const PackageSchema = Schema.Struct({
|
|
49
|
+
name: Schema.String,
|
|
50
|
+
version: Schema.String,
|
|
51
|
+
private: Schema.Boolean,
|
|
52
|
+
/** Path relative to the monorepo root (no trailing slash). */
|
|
53
|
+
path: Schema.String,
|
|
54
|
+
description: Schema.optional(Schema.String),
|
|
55
|
+
});
|
|
56
|
+
export type Package = typeof PackageSchema.Type;
|
|
57
|
+
|
|
58
|
+
export const PackageDetailSchema = Schema.Struct({
|
|
59
|
+
...PackageSchema.fields,
|
|
60
|
+
/** Workspace dependencies (other packages in the monorepo). */
|
|
61
|
+
workspaceDependencies: Schema.Array(Schema.String),
|
|
62
|
+
/** External (catalog or pinned) dependency names. */
|
|
63
|
+
externalDependencies: Schema.Array(Schema.String),
|
|
64
|
+
/** Resolved entry points (relative to package root). */
|
|
65
|
+
entryPoints: Schema.Array(Schema.String),
|
|
66
|
+
/** Number of exported symbols at the top level. */
|
|
67
|
+
exportCount: Schema.Number,
|
|
68
|
+
});
|
|
69
|
+
export type PackageDetail = typeof PackageDetailSchema.Type;
|
|
70
|
+
|
|
71
|
+
//
|
|
72
|
+
// Symbols
|
|
73
|
+
//
|
|
74
|
+
|
|
75
|
+
export const SymbolMatchSchema = Schema.Struct({
|
|
76
|
+
ref: Schema.String,
|
|
77
|
+
package: Schema.String,
|
|
78
|
+
name: Schema.String,
|
|
79
|
+
kind: SymbolKindSchema,
|
|
80
|
+
/** One-line summary from JSDoc, if any. */
|
|
81
|
+
summary: Schema.optional(Schema.String),
|
|
82
|
+
});
|
|
83
|
+
export type SymbolMatch = typeof SymbolMatchSchema.Type;
|
|
84
|
+
|
|
85
|
+
export const SymbolDetailSchema = Schema.Struct({
|
|
86
|
+
ref: Schema.String,
|
|
87
|
+
package: Schema.String,
|
|
88
|
+
name: Schema.String,
|
|
89
|
+
kind: SymbolKindSchema,
|
|
90
|
+
signature: Schema.String,
|
|
91
|
+
jsdoc: Schema.optional(Schema.String),
|
|
92
|
+
summary: Schema.optional(Schema.String),
|
|
93
|
+
location: SourceLocationSchema,
|
|
94
|
+
/** Source text — only present when `include` requested it. */
|
|
95
|
+
source: Schema.optional(Schema.String),
|
|
96
|
+
});
|
|
97
|
+
export type SymbolDetail = typeof SymbolDetailSchema.Type;
|
|
98
|
+
|
|
99
|
+
//
|
|
100
|
+
// Plugins / surfaces / capabilities / operations / schemas
|
|
101
|
+
//
|
|
102
|
+
|
|
103
|
+
export const PluginSchema = Schema.Struct({
|
|
104
|
+
/** e.g. `org.dxos.plugin.code`. */
|
|
105
|
+
id: PluginIdSchema,
|
|
106
|
+
/** npm package name, e.g. `@dxos/plugin-code`. */
|
|
107
|
+
package: Schema.String,
|
|
108
|
+
name: Schema.optional(Schema.String),
|
|
109
|
+
description: Schema.optional(Schema.String),
|
|
110
|
+
icon: Schema.optional(Schema.String),
|
|
111
|
+
iconHue: Schema.optional(Schema.String),
|
|
112
|
+
/** Static tags read from `meta.tags` (e.g. `['labs']`). Empty array if absent. */
|
|
113
|
+
tags: Schema.Array(Schema.String),
|
|
114
|
+
/**
|
|
115
|
+
* Ids of other plugins this plugin depends on, derived from its package's
|
|
116
|
+
* `workspace:*` dependencies. Sorted for deterministic output. Empty array
|
|
117
|
+
* if the plugin's package has no dependencies on other plugin packages.
|
|
118
|
+
*/
|
|
119
|
+
dependsOn: Schema.Array(PluginIdSchema),
|
|
120
|
+
/** Source location of the `meta` declaration. */
|
|
121
|
+
metaLocation: SourceLocationSchema,
|
|
122
|
+
});
|
|
123
|
+
export type Plugin = typeof PluginSchema.Type;
|
|
124
|
+
|
|
125
|
+
export const SurfaceSchema = Schema.Struct({
|
|
126
|
+
pluginId: PluginIdSchema,
|
|
127
|
+
/** Surface id passed to `Surface.create({ id })`. */
|
|
128
|
+
id: Schema.String,
|
|
129
|
+
/** One or more roles the surface answers to. */
|
|
130
|
+
role: Schema.Array(Schema.String),
|
|
131
|
+
location: SourceLocationSchema,
|
|
132
|
+
});
|
|
133
|
+
export type Surface = typeof SurfaceSchema.Type;
|
|
134
|
+
|
|
135
|
+
export const CapabilitySchema = Schema.Struct({
|
|
136
|
+
pluginId: PluginIdSchema,
|
|
137
|
+
/** Identifier expression as written in source, e.g. `Capabilities.ReactSurface`. */
|
|
138
|
+
type: Schema.String,
|
|
139
|
+
location: SourceLocationSchema,
|
|
140
|
+
});
|
|
141
|
+
export type Capability = typeof CapabilitySchema.Type;
|
|
142
|
+
|
|
143
|
+
export const OperationSchema = Schema.Struct({
|
|
144
|
+
pluginId: PluginIdSchema,
|
|
145
|
+
/** Operation identifier expression. */
|
|
146
|
+
type: Schema.String,
|
|
147
|
+
location: SourceLocationSchema,
|
|
148
|
+
});
|
|
149
|
+
export type Operation = typeof OperationSchema.Type;
|
|
150
|
+
|
|
151
|
+
export const SchemaSchema = Schema.Struct({
|
|
152
|
+
pluginId: PluginIdSchema,
|
|
153
|
+
/** Identifier expression as written in `addSchemaModule`, e.g. `CodeProject.CodeProject`. */
|
|
154
|
+
name: Schema.String,
|
|
155
|
+
/** Resolved typename (e.g. `org.dxos.type.codeProject`) when statically extractable. */
|
|
156
|
+
typename: Schema.optional(Schema.String),
|
|
157
|
+
location: SourceLocationSchema,
|
|
158
|
+
});
|
|
159
|
+
export type SchemaContribution = typeof SchemaSchema.Type;
|
|
160
|
+
|
|
161
|
+
export const PluginDetailSchema = Schema.Struct({
|
|
162
|
+
...PluginSchema.fields,
|
|
163
|
+
surfaces: Schema.Array(SurfaceSchema),
|
|
164
|
+
capabilities: Schema.Array(CapabilitySchema),
|
|
165
|
+
operations: Schema.Array(OperationSchema),
|
|
166
|
+
schemas: Schema.Array(SchemaSchema),
|
|
167
|
+
});
|
|
168
|
+
export type PluginDetail = typeof PluginDetailSchema.Type;
|
|
169
|
+
|
|
170
|
+
//
|
|
171
|
+
// Idioms
|
|
172
|
+
//
|
|
173
|
+
|
|
174
|
+
export const IdiomHostKindSchema = Schema.Literal('story', 'test', 'symbol');
|
|
175
|
+
export type IdiomHostKind = typeof IdiomHostKindSchema.Type;
|
|
176
|
+
|
|
177
|
+
export const IdiomHostSchema = Schema.Struct({
|
|
178
|
+
/** Path relative to the scan root. */
|
|
179
|
+
file: Schema.String,
|
|
180
|
+
/** 1-indexed line where the JSDoc opens. */
|
|
181
|
+
line: Schema.Number,
|
|
182
|
+
/** Best-effort name of the export immediately following the JSDoc. */
|
|
183
|
+
symbol: Schema.optional(Schema.String),
|
|
184
|
+
/** Detected host kind based on file location and symbol shape. */
|
|
185
|
+
kind: IdiomHostKindSchema,
|
|
186
|
+
});
|
|
187
|
+
export type IdiomHost = typeof IdiomHostSchema.Type;
|
|
188
|
+
|
|
189
|
+
export const IdiomSchema = Schema.Struct({
|
|
190
|
+
/** Globally unique AT Protocol NSID (https://atproto.com/specs/nsid). */
|
|
191
|
+
slug: Schema.String,
|
|
192
|
+
/** Leading JSDoc paragraph (rationale). */
|
|
193
|
+
summary: Schema.optional(Schema.String),
|
|
194
|
+
/** Applicability (required field per IDIOMS.md). */
|
|
195
|
+
applies: Schema.String,
|
|
196
|
+
/** Anti-pattern this replaces. */
|
|
197
|
+
insteadOf: Schema.optional(Schema.String),
|
|
198
|
+
/** Raw {@link …} targets named under `uses:`. */
|
|
199
|
+
uses: Schema.Array(Schema.String),
|
|
200
|
+
/** Slugs of related idioms. */
|
|
201
|
+
related: Schema.Array(Schema.String),
|
|
202
|
+
host: IdiomHostSchema,
|
|
203
|
+
});
|
|
204
|
+
export type Idiom = typeof IdiomSchema.Type;
|
|
205
|
+
|
|
206
|
+
//
|
|
207
|
+
// Sidecar file format
|
|
208
|
+
//
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* Shape of the `plugins.json` sidecar stored in R2 / written by the cache
|
|
212
|
+
* upload script. Uses plain mutable arrays so callers can work with standard
|
|
213
|
+
* JSON.parse output without readonly friction.
|
|
214
|
+
*/
|
|
215
|
+
export type PluginsFile = {
|
|
216
|
+
version: 1;
|
|
217
|
+
plugins: Plugin[];
|
|
218
|
+
surfaces: Surface[];
|
|
219
|
+
capabilities: Capability[];
|
|
220
|
+
operations: Operation[];
|
|
221
|
+
schemas: SchemaContribution[];
|
|
222
|
+
idioms?: Idiom[];
|
|
223
|
+
};
|
package/src/schemas.ts
CHANGED
|
@@ -13,11 +13,29 @@
|
|
|
13
13
|
// - Required fields: `.annotations({ description })` on the primitive itself.
|
|
14
14
|
|
|
15
15
|
import * as Schema from 'effect/Schema';
|
|
16
|
+
import * as SchemaAST from 'effect/SchemaAST';
|
|
16
17
|
|
|
17
18
|
import { trim } from '@dxos/util';
|
|
18
19
|
|
|
19
20
|
import { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from './limits';
|
|
20
21
|
|
|
22
|
+
/**
|
|
23
|
+
* Annotation key for fields whose value should be picked from a known
|
|
24
|
+
* enumeration that the MCP server can produce on demand. Consumers
|
|
25
|
+
* (e.g. `@dxos/react-ui-introspect`'s ToolForm) read this annotation off
|
|
26
|
+
* the field's AST and render a Combobox over the matching list.
|
|
27
|
+
*
|
|
28
|
+
* The kind names a domain rather than a specific tool — e.g. `plugin-id`
|
|
29
|
+
* means "any tool that emits plugin ids works" — so adding a new tool
|
|
30
|
+
* doesn't require new picker plumbing.
|
|
31
|
+
*/
|
|
32
|
+
export const PickerAnnotationId = '@dxos/introspect-tools/picker';
|
|
33
|
+
|
|
34
|
+
export type PickerKind = 'plugin-id' | 'package-name';
|
|
35
|
+
|
|
36
|
+
export const getPicker = (ast: SchemaAST.AST): PickerKind | undefined =>
|
|
37
|
+
(ast.annotations as Record<string, unknown>)[PickerAnnotationId] as PickerKind | undefined;
|
|
38
|
+
|
|
21
39
|
/**
|
|
22
40
|
* Pagination + projection options shared by every list-style tool. Spread its
|
|
23
41
|
* `.fields` into a tool's `Schema.Struct({...})` so the same pair of knobs
|
|
@@ -32,7 +50,7 @@ export const ListOptionsInput = Schema.Struct({
|
|
|
32
50
|
).annotations({
|
|
33
51
|
title: 'Limit',
|
|
34
52
|
description: trim`
|
|
35
|
-
Maximum number of items
|
|
53
|
+
Maximum number of items. Default ${DEFAULT_LIST_LIMIT}; max ${MAX_LIST_LIMIT}.
|
|
36
54
|
`,
|
|
37
55
|
}),
|
|
38
56
|
compact: Schema.optional(Schema.Boolean).annotations({
|
|
@@ -56,10 +74,10 @@ export const ListPackagesInput = Schema.Struct({
|
|
|
56
74
|
name: Schema.optional(Schema.String).annotations({
|
|
57
75
|
title: 'Name filter',
|
|
58
76
|
description: 'Substring of the package name (case-insensitive).',
|
|
77
|
+
[PickerAnnotationId]: 'package-name' satisfies PickerKind,
|
|
59
78
|
}),
|
|
60
79
|
pathPrefix: Schema.optional(Schema.String).annotations({
|
|
61
80
|
title: 'Path prefix',
|
|
62
|
-
description: 'Restrict to packages whose path starts with this segment, e.g. "packages/plugins".',
|
|
63
81
|
}),
|
|
64
82
|
privateOnly: Schema.optional(Schema.Boolean).annotations({
|
|
65
83
|
title: 'Private only',
|
|
@@ -72,6 +90,7 @@ export const GetPackageInput = Schema.Struct({
|
|
|
72
90
|
name: Schema.String.annotations({
|
|
73
91
|
title: 'Package name',
|
|
74
92
|
description: 'Exact package name, e.g. "@dxos/echo".',
|
|
93
|
+
[PickerAnnotationId]: 'package-name' satisfies PickerKind,
|
|
75
94
|
}),
|
|
76
95
|
});
|
|
77
96
|
|
|
@@ -83,6 +102,7 @@ export const ListSymbolsInput = Schema.Struct({
|
|
|
83
102
|
package: Schema.String.annotations({
|
|
84
103
|
title: 'Package',
|
|
85
104
|
description: 'Exact package name, e.g. "@dxos/ai".',
|
|
105
|
+
[PickerAnnotationId]: 'package-name' satisfies PickerKind,
|
|
86
106
|
}),
|
|
87
107
|
kind: Schema.optional(SymbolKindEnum).annotations({
|
|
88
108
|
title: 'Kind',
|
|
@@ -123,6 +143,9 @@ export const GetSymbolInput = Schema.Struct({
|
|
|
123
143
|
//
|
|
124
144
|
|
|
125
145
|
export const ListPluginsInput = Schema.Struct({
|
|
146
|
+
// No picker annotation — this is a free-form substring filter, not an
|
|
147
|
+
// exact-match selector. Picking from the list of known plugin ids would
|
|
148
|
+
// defeat the purpose of `list_plugins`.
|
|
126
149
|
id: Schema.optional(Schema.String).annotations({
|
|
127
150
|
title: 'Plugin id',
|
|
128
151
|
description: 'Substring of the plugin id (case-insensitive). Omit to list every plugin.',
|
|
@@ -133,7 +156,7 @@ export const ListPluginsInput = Schema.Struct({
|
|
|
133
156
|
const PluginIdFilter = Schema.Struct({
|
|
134
157
|
id: Schema.optional(Schema.String).annotations({
|
|
135
158
|
title: 'Plugin id',
|
|
136
|
-
|
|
159
|
+
[PickerAnnotationId]: 'plugin-id' satisfies PickerKind,
|
|
137
160
|
}),
|
|
138
161
|
...ListOptionsInput.fields,
|
|
139
162
|
});
|
|
@@ -143,6 +166,24 @@ export const ListCapabilitiesInput = PluginIdFilter;
|
|
|
143
166
|
export const ListOperationsInput = PluginIdFilter;
|
|
144
167
|
export const ListSchemasInput = PluginIdFilter;
|
|
145
168
|
|
|
169
|
+
//
|
|
170
|
+
// Idioms
|
|
171
|
+
//
|
|
172
|
+
|
|
173
|
+
const IdiomHostKindEnum = Schema.Literal('story', 'test', 'symbol');
|
|
174
|
+
|
|
175
|
+
export const ListIdiomsInput = Schema.Struct({
|
|
176
|
+
slug: Schema.optional(Schema.String).annotations({
|
|
177
|
+
title: 'Slug filter',
|
|
178
|
+
description: 'Substring of the idiom slug (case-insensitive). Omit to list every idiom.',
|
|
179
|
+
}),
|
|
180
|
+
hostKind: Schema.optional(IdiomHostKindEnum).annotations({
|
|
181
|
+
title: 'Host kind',
|
|
182
|
+
description: 'Filter idioms by their host site: `symbol` (production code), `story`, or `test`.',
|
|
183
|
+
}),
|
|
184
|
+
...ListOptionsInput.fields,
|
|
185
|
+
});
|
|
186
|
+
|
|
146
187
|
//
|
|
147
188
|
// Inferred TypeScript types — handy for downstream consumers.
|
|
148
189
|
//
|
|
@@ -157,3 +198,4 @@ export type ListSurfacesArgs = typeof ListSurfacesInput.Type;
|
|
|
157
198
|
export type ListCapabilitiesArgs = typeof ListCapabilitiesInput.Type;
|
|
158
199
|
export type ListOperationsArgs = typeof ListOperationsInput.Type;
|
|
159
200
|
export type ListSchemasArgs = typeof ListSchemasInput.Type;
|
|
201
|
+
export type ListIdiomsArgs = typeof ListIdiomsInput.Type;
|