@dxos/introspect-tools 0.0.0 → 0.8.4-main.03d5cd7b56

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dxos/introspect-tools",
3
- "version": "0.0.0",
3
+ "version": "0.8.4-main.03d5cd7b56",
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",
@@ -26,17 +26,17 @@
26
26
  "src"
27
27
  ],
28
28
  "dependencies": {
29
- "@dxos/effect-zod": "workspace:*",
30
- "@dxos/util": "workspace:*",
31
- "effect": "catalog:",
32
- "zod": "catalog:"
29
+ "effect": "3.20.0",
30
+ "zod": "^4.0.0",
31
+ "@dxos/util": "0.8.4-main.03d5cd7b56",
32
+ "@dxos/effect-zod": "0.8.4-main.03d5cd7b56"
33
33
  },
34
34
  "devDependencies": {
35
- "@types/node": "catalog:",
36
- "typescript": "catalog:",
37
- "vitest": "catalog:"
35
+ "@types/node": "22.10.2",
36
+ "typescript": "^6.0.3",
37
+ "vitest": "4.1.5"
38
38
  },
39
39
  "publishConfig": {
40
40
  "access": "public"
41
41
  }
42
- }
42
+ }
package/src/index.ts CHANGED
@@ -8,6 +8,36 @@
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
+ OperationSchema,
14
+ PackageDetailSchema,
15
+ PackageSchema,
16
+ PluginDetailSchema,
17
+ PluginIdSchema,
18
+ PluginSchema,
19
+ SchemaSchema,
20
+ SourceLocationSchema,
21
+ SurfaceSchema,
22
+ SymbolDetailSchema,
23
+ SymbolIncludeSchema,
24
+ SymbolKindSchema,
25
+ SymbolMatchSchema,
26
+ type Capability,
27
+ type Operation,
28
+ type Package,
29
+ type PackageDetail,
30
+ type Plugin,
31
+ type PluginDetail,
32
+ type PluginId,
33
+ type SchemaContribution,
34
+ type SourceLocation,
35
+ type Surface,
36
+ type SymbolDetail,
37
+ type SymbolInclude,
38
+ type SymbolKind,
39
+ type SymbolMatch,
40
+ } from './output-schemas';
11
41
  export {
12
42
  FindSymbolInput,
13
43
  GetPackageInput,
@@ -20,6 +50,8 @@ export {
20
50
  ListSchemasInput,
21
51
  ListSurfacesInput,
22
52
  ListSymbolsInput,
53
+ PickerAnnotationId,
54
+ getPicker,
23
55
  type FindSymbolArgs,
24
56
  type GetPackageArgs,
25
57
  type GetSymbolArgs,
@@ -30,4 +62,5 @@ export {
30
62
  type ListSchemasArgs,
31
63
  type ListSurfacesArgs,
32
64
  type ListSymbolsArgs,
65
+ type PickerKind,
33
66
  } from './schemas';
@@ -0,0 +1,168 @@
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;
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 to return. Default ${DEFAULT_LIST_LIMIT}; max ${MAX_LIST_LIMIT}.
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
- description: 'Restrict to contributions from this plugin id (e.g. "org.dxos.plugin.markdown").',
159
+ [PickerAnnotationId]: 'plugin-id' satisfies PickerKind,
137
160
  }),
138
161
  ...ListOptionsInput.fields,
139
162
  });