1
import { readFile } from 'fs/promises';
2
import { join } from 'path';
3
+import { z } from 'zod';
4
import { getMetaToolOverride } from './meta-tool-overrides';
5
5
-export interface MetaToolParameter {
6
- type: string;
7
- description: string;
8
- required?: string[] | boolean;
9
- default?: unknown;
10
- enum?: string[];
11
- examples?: unknown[];
12
- items?: Record<string, unknown>;
13
- properties?: Record<string, MetaToolParameter>;
14
-}
6
+const jsonTypeSchema = z.enum([
7
+ 'string',
8
+ 'number',
9
+ 'integer',
10
+ 'boolean',
11
+ 'object',
12
+ 'array',
13
+ 'null',
14
+]);
15
16
-export interface MetaToolSchema {
17
- type: string;
18
- properties: Record<string, MetaToolParameter>;
19
- required?: string[];
20
-}
21
-
22
-export interface MetaTool {
23
- slug: string;
24
- name: string;
25
- displayName: string;
26
- description: string;
27
- tags: string[];
28
- inputParameters: MetaToolSchema;
29
- responseSchema: MetaToolSchema;
30
- /** Hand-written Modal-voice copy, merged over the API data at read time. */
31
- summary?: string;
32
- whenToUse?: string;
33
- usageNote?: string;
34
-}
16
+// Normalize the schema fields used by the reference renderers. The generated
17
+// snapshot remains unchanged; `any` is a display label for an unrestricted type.
18
+const parameterSchema = z.object({
19
+ type: z
20
+ .union([jsonTypeSchema, z.array(jsonTypeSchema).min(1)])
21
+ .optional()
22
+ .transform(type => {
23
+ if (type === undefined) return 'any';
24
+ return Array.isArray(type) ? type.join(' | ') : type;
25
+ }),
26
+ description: z
27
+ .string()
28
+ .default('')
29
+ .transform(description =>
30
+ description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim()
31
+ ),
32
+ required: z.array(z.string()).default([]),
33
+ default: z.unknown().optional(),
34
+ enum: z
35
+ .array(z.union([z.string(), z.number(), z.boolean(), z.null()]))
36
+ .default([])
37
+ .transform(values => values.map(value => String(value))),
38
+ get properties(): z.ZodDefault<z.ZodRecord<z.ZodString, typeof parameterSchema>> {
39
+ return z.record(z.string(), parameterSchema).default({});
40
+ },
41
+ get items(): z.ZodOptional<typeof parameterSchema> {
42
+ return parameterSchema.optional();
43
+ },
44
+});
45
36
-const META_TOOLS_PATH = join(process.cwd(), 'public/data/meta-tools.json');
46
+type ParsedParameter = z.infer<typeof parameterSchema>;
47
38
-let cached: { list: MetaTool[]; bySlug: Map<string, MetaTool> } | null = null;
48
+export type MetaToolParameter = Omit<
49
+ ParsedParameter,
50
+ 'type' | 'default' | 'properties' | 'items'
51
+> & {
52
+ typeLabel: string;
53
+ defaultLabel: string | null;
54
+ properties: Record<string, MetaToolParameter>;
55
+ items?: MetaToolParameter;
56
+};
57
40
-function buildCache(tools: MetaTool[]) {
41
- cached = {
42
- list: tools,
43
- bySlug: new Map(tools.map(t => [t.slug, t])),
58
+/** Project schema nodes into one display model before they reach either renderer. */
59
+function toDisplayParameter({
60
+ type,
61
+ default: defaultValue,
62
+ properties,
63
+ items,
64
+ ...parameter
65
+}: ParsedParameter): MetaToolParameter {
66
+ const displayItems = items ? toDisplayParameter(items) : undefined;
67
+ const typeLabel =
68
+ type === 'array' ? `array<${displayItems ? displayItems.typeLabel : 'any'}>` : type;
69
+ const defaultLabel =
70
+ defaultValue === undefined || defaultValue === null || defaultValue === ''
71
+ ? null
72
+ : String(defaultValue);
73
+ return {
74
+ ...parameter,
75
+ typeLabel,
76
+ defaultLabel,
77
+ properties: Object.fromEntries(
78
+ Object.entries(properties).map(([name, value]) => [name, toDisplayParameter(value)])
79
+ ),
80
+ items: displayItems,
81
};
45
- return cached;
82
}
83
48
-/** Merge the hand-written override copy over the API-sourced tool. */
49
-function applyOverride(tool: MetaTool): MetaTool {
50
- const override = getMetaToolOverride(tool.slug);
51
- if (!override) return tool;
52
- return { ...tool, ...override };
53
-}
84
+export type MetaToolSchema = MetaToolParameter;
85
55
-function parse(data: string): MetaTool[] {
56
- const tools = JSON.parse(data) as MetaTool[];
86
+export const metaToolSchema = z
87
+ .object({
88
+ slug: z.string(),
89
+ name: z.string(),
90
+ displayName: z.string(),
91
+ description: z.string(),
92
+ tags: z.array(z.string()),
93
+ inputParameters: parameterSchema.transform(toDisplayParameter),
94
+ responseSchema: parameterSchema.transform(toDisplayParameter),
95
+ })
96
+ .transform(tool => {
97
+ const override = getMetaToolOverride(tool.slug);
98
+ return {
99
+ ...tool,
100
+ summary: override ? override.summary : tool.description,
101
+ whenToUse: override ? override.whenToUse : '',
102
+ usageNote: override?.usageNote ?? '',
103
+ };
104
+ });
105
58
- if (!Array.isArray(tools)) {
59
- throw new Error('meta-tools.json must contain an array');
60
- }
106
+export type MetaTool = z.infer<typeof metaToolSchema>;
107
62
- return tools.map(applyOverride);
108
+const metaToolsSchema = z.array(metaToolSchema);
109
+const META_TOOLS_PATH = join(process.cwd(), 'public/data/meta-tools.json');
110
+
111
+let cached: { list: MetaTool[]; bySlug: Map<string, MetaTool> } | null = null;
112
+
113
+async function getCache() {
114
+ if (cached) return cached;
115
+ const data = await readFile(META_TOOLS_PATH, 'utf-8');
116
+ const list = metaToolsSchema.parse(JSON.parse(data));
117
+ cached = { list, bySlug: new Map(list.map(tool => [tool.slug, tool])) };
118
+ return cached;
119
}
120
121
export async function getAllMetaTools(): Promise<MetaTool[]> {
66
- if (cached) return cached.list;
67
- const data = await readFile(META_TOOLS_PATH, 'utf-8');
68
- return buildCache(parse(data)).list;
122
+ return (await getCache()).list;
123
}
124
125
export async function getMetaToolBySlug(slug: string): Promise<MetaTool | null> {
72
- if (cached) return cached.bySlug.get(slug) ?? null;
73
- const data = await readFile(META_TOOLS_PATH, 'utf-8');
74
- return buildCache(parse(data)).bySlug.get(slug) ?? null;
75
-}
\ No newline at end of file
126
+ return (await getCache()).bySlug.get(slug) ?? null;
127
+}