@mapomodule/mcp 0.0.0-stage → 1.0.0-beta.2
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/README.md +509 -2
- package/bin/mapo-mcp.mjs +3 -0
- package/dist/build.d.mts +18 -0
- package/dist/build.d.ts +18 -0
- package/dist/build.mjs +351 -0
- package/dist/cli.d.mts +7 -0
- package/dist/cli.d.ts +7 -0
- package/dist/cli.mjs +274 -0
- package/dist/index.d.mts +68 -0
- package/dist/index.d.ts +68 -0
- package/dist/index.mjs +1 -0
- package/dist/knowledge/api.json +1 -0
- package/dist/knowledge/docs.json +1 -0
- package/dist/module.d.mts +16 -0
- package/dist/module.d.ts +16 -0
- package/dist/module.json +9 -0
- package/dist/module.mjs +124 -0
- package/dist/runtime/core/doctor.d.ts +0 -0
- package/dist/runtime/core/doctor.js +128 -0
- package/dist/runtime/core/endpoint.d.ts +0 -0
- package/dist/runtime/core/endpoint.js +8 -0
- package/dist/runtime/core/indexer.d.ts +0 -0
- package/dist/runtime/core/indexer.js +194 -0
- package/dist/runtime/core/instructions.d.ts +0 -0
- package/dist/runtime/core/instructions.js +10 -0
- package/dist/runtime/core/knowledge.d.ts +0 -0
- package/dist/runtime/core/knowledge.js +76 -0
- package/dist/runtime/core/openapi.d.ts +0 -0
- package/dist/runtime/core/openapi.js +229 -0
- package/dist/runtime/core/overview.d.ts +0 -0
- package/dist/runtime/core/overview.js +15 -0
- package/dist/runtime/core/prompts.d.ts +0 -0
- package/dist/runtime/core/prompts.js +108 -0
- package/dist/runtime/core/recipes.d.ts +0 -0
- package/dist/runtime/core/recipes.js +496 -0
- package/dist/runtime/core/resources.d.ts +0 -0
- package/dist/runtime/core/resources.js +92 -0
- package/dist/runtime/core/scaffold/fields.d.ts +0 -0
- package/dist/runtime/core/scaffold/fields.js +64 -0
- package/dist/runtime/core/scaffold/index.d.ts +0 -0
- package/dist/runtime/core/scaffold/index.js +74 -0
- package/dist/runtime/core/scaffold/templates.d.ts +0 -0
- package/dist/runtime/core/scaffold/templates.js +349 -0
- package/dist/runtime/core/schema-source.d.ts +0 -0
- package/dist/runtime/core/schema-source.js +70 -0
- package/dist/runtime/core/search.d.ts +0 -0
- package/dist/runtime/core/search.js +173 -0
- package/dist/runtime/core/tokenize.d.ts +0 -0
- package/dist/runtime/core/tokenize.js +96 -0
- package/dist/runtime/core/tool-spec.d.ts +0 -0
- package/dist/runtime/core/tool-spec.js +3 -0
- package/dist/runtime/core/tools/api.d.ts +0 -0
- package/dist/runtime/core/tools/api.js +192 -0
- package/dist/runtime/core/tools/app.d.ts +0 -0
- package/dist/runtime/core/tools/app.js +141 -0
- package/dist/runtime/core/tools/backend.d.ts +0 -0
- package/dist/runtime/core/tools/backend.js +143 -0
- package/dist/runtime/core/tools/docs.d.ts +0 -0
- package/dist/runtime/core/tools/docs.js +154 -0
- package/dist/runtime/core/tools/scaffold.d.ts +0 -0
- package/dist/runtime/core/tools/scaffold.js +127 -0
- package/dist/runtime/core/types.d.ts +0 -0
- package/dist/runtime/core/types.js +0 -0
- package/dist/runtime/core/write.d.ts +0 -0
- package/dist/runtime/core/write.js +53 -0
- package/dist/runtime/mcp/handlers/mapo/index.js +7 -0
- package/dist/runtime/mcp/handlers/mapo/prompts/crud-page.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/prompts/custom-field.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/prompts/debug-form.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/prompts/migrate-v1.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/prompts/theme.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/resources/app-manifest.js +19 -0
- package/dist/runtime/mcp/handlers/mapo/resources/docs.js +34 -0
- package/dist/runtime/mcp/handlers/mapo/resources/fields.js +34 -0
- package/dist/runtime/mcp/handlers/mapo/resources/knowledge-index.js +22 -0
- package/dist/runtime/mcp/handlers/mapo/resources/overview.js +20 -0
- package/dist/runtime/mcp/handlers/mapo/tools/backend-schema.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/component-api.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/composable-api.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/doctor.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/get-doc.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/inspect-app.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/list-field-types.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/list-recipes.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/scaffold.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/search-docs.js +3 -0
- package/dist/runtime/nitro/context.d.ts +0 -0
- package/dist/runtime/nitro/context.js +21 -0
- package/dist/runtime/nitro/to-mcp-prompt.d.ts +0 -0
- package/dist/runtime/nitro/to-mcp-prompt.js +23 -0
- package/dist/runtime/nitro/to-mcp-tool.d.ts +0 -0
- package/dist/runtime/nitro/to-mcp-tool.js +28 -0
- package/dist/runtime/types/virtual-modules.d.ts +6 -0
- package/dist/types.d.mts +9 -0
- package/package.json +73 -4
- package/src/__tests__/cli.test.ts +137 -0
- package/src/__tests__/doctor.test.ts +145 -0
- package/src/__tests__/endpoint.test.ts +31 -0
- package/src/__tests__/fixtures/drf-schema.json +142 -0
- package/src/__tests__/fixtures.ts +198 -0
- package/src/__tests__/indexer.test.ts +114 -0
- package/src/__tests__/knowledge.test.ts +225 -0
- package/src/__tests__/openapi.test.ts +256 -0
- package/src/__tests__/overview.test.ts +105 -0
- package/src/__tests__/recipes.test.ts +55 -0
- package/src/__tests__/resources.test.ts +69 -0
- package/src/__tests__/scaffold.test.ts +153 -0
- package/src/__tests__/search.test.ts +105 -0
- package/src/__tests__/tools.test.ts +226 -0
- package/src/__tests__/write.test.ts +134 -0
- package/src/build/extract-components.ts +135 -0
- package/src/build/extract-composables.ts +125 -0
- package/src/build/extract-fields.ts +250 -0
- package/src/build/index.ts +103 -0
- package/src/cli.ts +375 -0
- package/src/index.ts +65 -0
- package/src/module.ts +213 -0
- package/src/runtime/core/doctor.ts +204 -0
- package/src/runtime/core/endpoint.ts +27 -0
- package/src/runtime/core/indexer.ts +285 -0
- package/src/runtime/core/instructions.ts +18 -0
- package/src/runtime/core/knowledge.ts +121 -0
- package/src/runtime/core/openapi.ts +417 -0
- package/src/runtime/core/overview.ts +44 -0
- package/src/runtime/core/prompts.ts +150 -0
- package/src/runtime/core/recipes.ts +574 -0
- package/src/runtime/core/resources.ts +150 -0
- package/src/runtime/core/scaffold/fields.ts +127 -0
- package/src/runtime/core/scaffold/index.ts +120 -0
- package/src/runtime/core/scaffold/templates.ts +394 -0
- package/src/runtime/core/schema-source.ts +123 -0
- package/src/runtime/core/search.ts +282 -0
- package/src/runtime/core/tokenize.ts +146 -0
- package/src/runtime/core/tool-spec.ts +74 -0
- package/src/runtime/core/tools/api.ts +300 -0
- package/src/runtime/core/tools/app.ts +201 -0
- package/src/runtime/core/tools/backend.ts +197 -0
- package/src/runtime/core/tools/docs.ts +218 -0
- package/src/runtime/core/tools/scaffold.ts +176 -0
- package/src/runtime/core/types.ts +133 -0
- package/src/runtime/core/write.ts +119 -0
- package/src/runtime/mcp/handlers/mapo/index.ts +16 -0
- package/src/runtime/mcp/handlers/mapo/prompts/crud-page.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/prompts/custom-field.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/prompts/debug-form.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/prompts/migrate-v1.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/prompts/theme.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/resources/app-manifest.ts +28 -0
- package/src/runtime/mcp/handlers/mapo/resources/docs.ts +41 -0
- package/src/runtime/mcp/handlers/mapo/resources/fields.ts +37 -0
- package/src/runtime/mcp/handlers/mapo/resources/knowledge-index.ts +24 -0
- package/src/runtime/mcp/handlers/mapo/resources/overview.ts +22 -0
- package/src/runtime/mcp/handlers/mapo/tools/backend-schema.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/component-api.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/composable-api.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/doctor.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/get-doc.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/inspect-app.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/list-field-types.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/list-recipes.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/scaffold.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/search-docs.ts +4 -0
- package/src/runtime/nitro/context.ts +41 -0
- package/src/runtime/nitro/to-mcp-prompt.ts +30 -0
- package/src/runtime/nitro/to-mcp-tool.ts +35 -0
- package/src/runtime/types/virtual-modules.d.ts +6 -0
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Diagnostic rules over the app snapshot.
|
|
3
|
+
*
|
|
4
|
+
* Pure and transport-agnostic so the whole rule set is unit-testable against a
|
|
5
|
+
* crafted manifest. Every finding must be *actionable*: what is wrong, why it
|
|
6
|
+
* matters, and the exact change to make.
|
|
7
|
+
*/
|
|
8
|
+
import type { MapoAppManifest } from "../../index.js";
|
|
9
|
+
|
|
10
|
+
export type DoctorSeverity = "error" | "warning" | "info";
|
|
11
|
+
|
|
12
|
+
export interface DoctorFinding {
|
|
13
|
+
rule: string;
|
|
14
|
+
severity: DoctorSeverity;
|
|
15
|
+
message: string;
|
|
16
|
+
/** Concrete change to apply. */
|
|
17
|
+
fix?: string;
|
|
18
|
+
/** Documentation path that explains the topic. */
|
|
19
|
+
doc?: string;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** Mirrors `MAPO_DEFAULTS` in `@mapomodule/core`. */
|
|
23
|
+
const AUTH_DEFAULTS: Record<string, string> = {
|
|
24
|
+
authLoginUrl: "/api/auth/login",
|
|
25
|
+
userInfoApi: "/api/profiles/me/",
|
|
26
|
+
logoutUrl: "/api/auth/logout",
|
|
27
|
+
loginUrl: "/login",
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
/** Mirrors `MAPO_MEDIA_DEFAULTS.endpoints` in `@mapomodule/uikit`. */
|
|
31
|
+
const MEDIA_ENDPOINT_DEFAULTS = {
|
|
32
|
+
media: "/api/media",
|
|
33
|
+
folders: "/api/media-folders",
|
|
34
|
+
};
|
|
35
|
+
|
|
36
|
+
/** Locales Mapo ships UI catalogs for. */
|
|
37
|
+
const BUNDLED_LOCALES = new Set(["en", "it"]);
|
|
38
|
+
|
|
39
|
+
const MEDIA_FIELD_TYPES = new Set(["media", "media-m2m", "enhanced-media"]);
|
|
40
|
+
|
|
41
|
+
function section(
|
|
42
|
+
manifest: MapoAppManifest,
|
|
43
|
+
key: string,
|
|
44
|
+
): Record<string, unknown> {
|
|
45
|
+
const value = manifest.config[key];
|
|
46
|
+
return value && typeof value === "object"
|
|
47
|
+
? (value as Record<string, unknown>)
|
|
48
|
+
: {};
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** Runs every rule and returns the findings, most severe first. */
|
|
52
|
+
export function runDoctor(manifest: MapoAppManifest): DoctorFinding[] {
|
|
53
|
+
const findings: DoctorFinding[] = [];
|
|
54
|
+
const core = section(manifest, "mapoCore");
|
|
55
|
+
const media = section(manifest, "mapoMedia");
|
|
56
|
+
const moduleNames = new Set(manifest.modules.map((module) => module.name));
|
|
57
|
+
|
|
58
|
+
// 1. Module order. `@nuxt/ui` must be registered before Mapo: installing it
|
|
59
|
+
// from inside another module makes @nuxt/icon's SSR component loop.
|
|
60
|
+
const order = manifest.moduleOrder;
|
|
61
|
+
const uiIndex = order.indexOf("@nuxt/ui");
|
|
62
|
+
const mapoIndex = order.findIndex(
|
|
63
|
+
(name) => name === "mapomodule" || name.startsWith("@mapomodule/"),
|
|
64
|
+
);
|
|
65
|
+
|
|
66
|
+
if (mapoIndex !== -1 && uiIndex === -1) {
|
|
67
|
+
findings.push({
|
|
68
|
+
rule: "nuxt-ui-missing",
|
|
69
|
+
severity: "error",
|
|
70
|
+
message:
|
|
71
|
+
"`@nuxt/ui` is not declared in `modules[]`, but Mapo's UI layer requires it.",
|
|
72
|
+
fix: 'Add "@nuxt/ui" as the first entry of `modules[]`.',
|
|
73
|
+
doc: "guide/getting-started.md",
|
|
74
|
+
});
|
|
75
|
+
} else if (mapoIndex !== -1 && uiIndex > mapoIndex) {
|
|
76
|
+
findings.push({
|
|
77
|
+
rule: "nuxt-ui-order",
|
|
78
|
+
severity: "error",
|
|
79
|
+
message:
|
|
80
|
+
`\`@nuxt/ui\` is declared after \`${order[mapoIndex]}\` in modules[]. ` +
|
|
81
|
+
"Icons break during SSR when Nuxt UI is initialised after Mapo.",
|
|
82
|
+
fix: 'Move "@nuxt/ui" before the Mapo entry in `modules[]`.',
|
|
83
|
+
doc: "guide/compatibility.md",
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
// 2. Mapo itself must be there. A partial install is worth catching early.
|
|
88
|
+
if (!moduleNames.has("@mapomodule/core")) {
|
|
89
|
+
findings.push({
|
|
90
|
+
rule: "core-missing",
|
|
91
|
+
severity: "error",
|
|
92
|
+
message:
|
|
93
|
+
"`@mapomodule/core` is not installed — auth, `useCrud` and route middleware are unavailable.",
|
|
94
|
+
fix: 'Add "mapomodule" to `modules[]`.',
|
|
95
|
+
doc: "guide/getting-started.md",
|
|
96
|
+
});
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
// 3. The login route must exist, or the auth middleware redirects to a 404.
|
|
100
|
+
const loginUrl =
|
|
101
|
+
typeof core.loginUrl === "string" ? core.loginUrl : AUTH_DEFAULTS.loginUrl!;
|
|
102
|
+
const hasLoginRoute = manifest.routes.some(
|
|
103
|
+
(route) => route.path === loginUrl,
|
|
104
|
+
);
|
|
105
|
+
|
|
106
|
+
if (!hasLoginRoute && manifest.routes.length > 0) {
|
|
107
|
+
findings.push({
|
|
108
|
+
rule: "login-route-missing",
|
|
109
|
+
severity: "error",
|
|
110
|
+
message: `No page matches \`loginUrl\` (\`${loginUrl}\`); the auth middleware would redirect to a missing route.`,
|
|
111
|
+
fix: `Create \`pages${loginUrl}.vue\` rendering <MapoLogin /> with \`definePageMeta({ layout: false })\`, or change \`mapo.loginUrl\`.`,
|
|
112
|
+
doc: "howto/auth-permissions.md",
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// 4. Untouched auth configuration: fine for a demo, wrong against a backend.
|
|
117
|
+
const authKeys = ["authLoginUrl", "userInfoApi", "logoutUrl"];
|
|
118
|
+
const allDefault = authKeys.every(
|
|
119
|
+
(key) => (core[key] ?? AUTH_DEFAULTS[key]) === AUTH_DEFAULTS[key],
|
|
120
|
+
);
|
|
121
|
+
|
|
122
|
+
if (allDefault) {
|
|
123
|
+
findings.push({
|
|
124
|
+
rule: "auth-endpoints-default",
|
|
125
|
+
severity: "info",
|
|
126
|
+
message:
|
|
127
|
+
"Auth endpoints are still the Mapo defaults — fine for a mock backend, not for a real one.",
|
|
128
|
+
fix: "Set `mapo.authLoginUrl`, `mapo.userInfoApi` and `mapo.logoutUrl` to your backend routes.",
|
|
129
|
+
doc: "howto/backend-integration.md",
|
|
130
|
+
});
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
// 5. Nothing built yet.
|
|
134
|
+
const adminRoutes = manifest.routes.filter(
|
|
135
|
+
(route) => route.path !== loginUrl,
|
|
136
|
+
);
|
|
137
|
+
if (adminRoutes.length === 0) {
|
|
138
|
+
findings.push({
|
|
139
|
+
rule: "no-admin-pages",
|
|
140
|
+
severity: "warning",
|
|
141
|
+
message:
|
|
142
|
+
"The app has no admin page yet (only the login route was found).",
|
|
143
|
+
fix: 'Create a page with `definePageMeta({ layout: "mapo-default", middleware: ["auth"] })`.',
|
|
144
|
+
doc: "howto/first-admin-page.md",
|
|
145
|
+
});
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
// 6. Locales without a Mapo catalog fall back to the default locale for
|
|
149
|
+
// framework strings; app strings are unaffected.
|
|
150
|
+
const uncovered = manifest.locales.filter(
|
|
151
|
+
(locale) => !BUNDLED_LOCALES.has(locale),
|
|
152
|
+
);
|
|
153
|
+
if (uncovered.length) {
|
|
154
|
+
findings.push({
|
|
155
|
+
rule: "locale-without-catalog",
|
|
156
|
+
severity: "warning",
|
|
157
|
+
message: `Mapo ships UI catalogs for en and it only; ${uncovered.join(", ")} will fall back for framework strings.`,
|
|
158
|
+
fix: "Add the missing `mapo.*` keys to your own `i18n/locales/<code>.json`.",
|
|
159
|
+
doc: "howto/i18n.md",
|
|
160
|
+
});
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
// 7. Media fields registered while the endpoints are untouched and no
|
|
164
|
+
// integration provides them.
|
|
165
|
+
const usesMedia = manifest.fieldTypes.some((field) =>
|
|
166
|
+
MEDIA_FIELD_TYPES.has(field.type),
|
|
167
|
+
);
|
|
168
|
+
const endpoints = (media.endpoints ?? {}) as Record<string, string>;
|
|
169
|
+
const mediaDefaults =
|
|
170
|
+
(endpoints.media ?? MEDIA_ENDPOINT_DEFAULTS.media) ===
|
|
171
|
+
MEDIA_ENDPOINT_DEFAULTS.media &&
|
|
172
|
+
(endpoints.folders ?? MEDIA_ENDPOINT_DEFAULTS.folders) ===
|
|
173
|
+
MEDIA_ENDPOINT_DEFAULTS.folders;
|
|
174
|
+
|
|
175
|
+
if (
|
|
176
|
+
usesMedia &&
|
|
177
|
+
mediaDefaults &&
|
|
178
|
+
!moduleNames.has("mapo-integrations-camomilla")
|
|
179
|
+
) {
|
|
180
|
+
findings.push({
|
|
181
|
+
rule: "media-endpoints-default",
|
|
182
|
+
severity: "info",
|
|
183
|
+
message:
|
|
184
|
+
"Media field types are registered but the media endpoints are still the defaults " +
|
|
185
|
+
`(\`${MEDIA_ENDPOINT_DEFAULTS.media}\`, \`${MEDIA_ENDPOINT_DEFAULTS.folders}\`) and no integration provides them.`,
|
|
186
|
+
fix: "Set `mapo.uikit.media.endpoints`, or install an integration that serves them.",
|
|
187
|
+
doc: "howto/media-manager.md",
|
|
188
|
+
});
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
const rank: Record<DoctorSeverity, number> = {
|
|
192
|
+
error: 0,
|
|
193
|
+
warning: 1,
|
|
194
|
+
info: 2,
|
|
195
|
+
};
|
|
196
|
+
return findings.sort((a, b) => rank[a.severity] - rank[b.severity]);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** What the build-time snapshot structurally cannot see. */
|
|
200
|
+
export const DOCTOR_BLIND_SPOTS = [
|
|
201
|
+
"field types registered at runtime by `defineFormField()` inside a plugin",
|
|
202
|
+
"`definePageMeta` values (layout, middleware, permissions) of your pages",
|
|
203
|
+
"anything that depends on a request, such as the logged-in user's permissions",
|
|
204
|
+
];
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where the Mapo MCP handler answers.
|
|
3
|
+
*
|
|
4
|
+
* `@nuxtjs/mcp-toolkit` mounts named handlers at `/mcp/<name>` whatever its
|
|
5
|
+
* `mcp.route` option says, and Nitro serves every server route under the app's
|
|
6
|
+
* `app.baseURL`. An app served under `/backoffice/` therefore answers at
|
|
7
|
+
* `/backoffice/mcp/mapo`, and a request to `/mcp/mapo` misses it: the dev
|
|
8
|
+
* server answers with a redirect, which MCP clients follow as a GET.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Directory name under `runtime/mcp/handlers/`, which the toolkit turns into
|
|
13
|
+
* the handler name and the route segment. It is not configurable: folder
|
|
14
|
+
* handlers always take their name from the directory.
|
|
15
|
+
*/
|
|
16
|
+
export const MCP_HANDLER_NAME = "mapo";
|
|
17
|
+
|
|
18
|
+
/** Path of the handler under an `app.baseURL` such as `/`, `/backoffice/` or `./`. */
|
|
19
|
+
export function mcpEndpointPath(baseURL = "/"): string {
|
|
20
|
+
const base = `/${baseURL.replace(/^\.?\/+/, "")}`.replace(/\/*$/, "/");
|
|
21
|
+
return `${base}mcp/${MCP_HANDLER_NAME}`;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** Full URL of the handler on an origin such as `http://localhost:3000`. */
|
|
25
|
+
export function mcpEndpointUrl(origin: string, baseURL = "/"): string {
|
|
26
|
+
return `${origin.replace(/\/+$/, "")}${mcpEndpointPath(baseURL)}`;
|
|
27
|
+
}
|
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Build-time knowledge indexer.
|
|
3
|
+
*
|
|
4
|
+
* Turns the repository's markdown docs into heading-sized chunks plus a BM25
|
|
5
|
+
* inverted index, so `mapo_search_docs` can answer with the relevant section
|
|
6
|
+
* instead of dumping whole files into the model's context.
|
|
7
|
+
*
|
|
8
|
+
* Runs from `scripts/build-knowledge.mjs` after the package build.
|
|
9
|
+
*/
|
|
10
|
+
import { readdirSync, readFileSync, statSync } from "node:fs";
|
|
11
|
+
import { join, relative, sep } from "node:path";
|
|
12
|
+
import { tokenize } from "./tokenize.js";
|
|
13
|
+
import type { Bm25Index, DocChunk, DocsKnowledge } from "./types.js";
|
|
14
|
+
|
|
15
|
+
export const KNOWLEDGE_VERSION = 1;
|
|
16
|
+
|
|
17
|
+
/** Chunks larger than this are split further (H3, then paragraphs). */
|
|
18
|
+
const MAX_CHUNK_CHARS = 3500;
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Directories under the docs root that are not app-building docs: internal
|
|
22
|
+
* planning, and `contributing/`, whose procedures for changing Mapo itself
|
|
23
|
+
* would otherwise compete with the answers for app developers.
|
|
24
|
+
*/
|
|
25
|
+
const EXCLUDED_DIRS = new Set([
|
|
26
|
+
"node_modules",
|
|
27
|
+
"roadmap",
|
|
28
|
+
"contributing",
|
|
29
|
+
".vitepress",
|
|
30
|
+
"dist",
|
|
31
|
+
]);
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Internal pages that are not user documentation. `DECISIONS.md` is an
|
|
35
|
+
* Italian-language decision log for maintainers, and `AGENTS.md` / `CLAUDE.md`
|
|
36
|
+
* are the manuals of the agents that edit the docs; surfacing them to
|
|
37
|
+
* assistants only pollutes results.
|
|
38
|
+
*/
|
|
39
|
+
const EXCLUDED_FILES = new Set(["DECISIONS.md", "AGENTS.md", "CLAUDE.md"]);
|
|
40
|
+
|
|
41
|
+
/** Field boosts baked into the term frequencies. */
|
|
42
|
+
const BOOST = { heading: 3, title: 2, tags: 3, text: 1 } as const;
|
|
43
|
+
|
|
44
|
+
const PKG_BY_PREFIX: Array<[string, string]> = [
|
|
45
|
+
["uikit/form", "@mapomodule/form"],
|
|
46
|
+
["uikit", "@mapomodule/uikit"],
|
|
47
|
+
["modules/core", "@mapomodule/core"],
|
|
48
|
+
["modules/store", "@mapomodule/store"],
|
|
49
|
+
["modules/utils", "@mapomodule/utils"],
|
|
50
|
+
["modules/i18n", "@mapomodule/i18n"],
|
|
51
|
+
["modules/api", "@mapomodule/core"],
|
|
52
|
+
["modules/camomilla", "mapo-integrations-camomilla"],
|
|
53
|
+
];
|
|
54
|
+
|
|
55
|
+
/** Pages that are pure API reference rather than task-oriented docs. */
|
|
56
|
+
const REFERENCE_PATH = /(?:^|\/)api\.md$/;
|
|
57
|
+
/** Headings that introduce a props/slots/emits table inside any page. */
|
|
58
|
+
const REFERENCE_HEADING = /^(props|slots|emits|events|exposed|api)\b/i;
|
|
59
|
+
|
|
60
|
+
/** GitHub-compatible heading slug (matches VitePress anchors). */
|
|
61
|
+
export function slugify(heading: string): string {
|
|
62
|
+
return heading
|
|
63
|
+
.toLowerCase()
|
|
64
|
+
.replace(/`/g, "")
|
|
65
|
+
.replace(/[^\w\s-]/g, "")
|
|
66
|
+
.trim()
|
|
67
|
+
.replace(/\s+/g, "-");
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function toPosix(path: string): string {
|
|
71
|
+
return sep === "/" ? path : path.split(sep).join("/");
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** Recursively collects `*.md` files, skipping internal directories. */
|
|
75
|
+
export function collectMarkdownFiles(root: string): string[] {
|
|
76
|
+
const files: string[] = [];
|
|
77
|
+
|
|
78
|
+
const walk = (dir: string) => {
|
|
79
|
+
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
|
80
|
+
if (entry.name.startsWith(".") && entry.name !== ".vitepress") continue;
|
|
81
|
+
const full = join(dir, entry.name);
|
|
82
|
+
if (entry.isDirectory()) {
|
|
83
|
+
if (EXCLUDED_DIRS.has(entry.name)) continue;
|
|
84
|
+
walk(full);
|
|
85
|
+
} else if (
|
|
86
|
+
entry.isFile() &&
|
|
87
|
+
entry.name.endsWith(".md") &&
|
|
88
|
+
!EXCLUDED_FILES.has(entry.name)
|
|
89
|
+
) {
|
|
90
|
+
files.push(full);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
};
|
|
94
|
+
|
|
95
|
+
walk(root);
|
|
96
|
+
return files.sort();
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** Symbols worth boosting: components, composables, field types, page meta keys. */
|
|
100
|
+
export function extractTags(text: string): string[] {
|
|
101
|
+
const tags = new Set<string>();
|
|
102
|
+
|
|
103
|
+
for (const match of text.matchAll(/\bMapo[A-Z][A-Za-z0-9]*/g))
|
|
104
|
+
tags.add(match[0]);
|
|
105
|
+
for (const match of text.matchAll(/\buse[A-Z][A-Za-z0-9]*/g))
|
|
106
|
+
tags.add(match[0]);
|
|
107
|
+
for (const match of text.matchAll(/\btype:\s*["']([a-z0-9-]+)["']/g)) {
|
|
108
|
+
if (match[1]) tags.add(match[1]);
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
return [...tags];
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
interface RawSection {
|
|
115
|
+
heading: string;
|
|
116
|
+
level: number;
|
|
117
|
+
lines: string[];
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Splits markdown at H2 (and H3 when a section is too long), ignoring headings
|
|
122
|
+
* that appear inside fenced code blocks.
|
|
123
|
+
*/
|
|
124
|
+
export function splitSections(markdown: string): {
|
|
125
|
+
title: string;
|
|
126
|
+
sections: RawSection[];
|
|
127
|
+
} {
|
|
128
|
+
const lines = markdown.replace(/\r\n/g, "\n").split("\n");
|
|
129
|
+
const sections: RawSection[] = [];
|
|
130
|
+
let title = "";
|
|
131
|
+
let current: RawSection = { heading: "", level: 1, lines: [] };
|
|
132
|
+
let fence: string | null = null;
|
|
133
|
+
|
|
134
|
+
for (const line of lines) {
|
|
135
|
+
const fenceMatch = /^\s*(```|~~~)/.exec(line);
|
|
136
|
+
if (fenceMatch) {
|
|
137
|
+
if (fence && line.trimStart().startsWith(fence)) fence = null;
|
|
138
|
+
else if (!fence) fence = fenceMatch[1]!;
|
|
139
|
+
current.lines.push(line);
|
|
140
|
+
continue;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
if (!fence) {
|
|
144
|
+
const heading = /^(#{1,3})\s+(.*)$/.exec(line);
|
|
145
|
+
if (heading) {
|
|
146
|
+
const level = heading[1]!.length;
|
|
147
|
+
const text = heading[2]!.trim();
|
|
148
|
+
if (level === 1 && !title) {
|
|
149
|
+
title = text;
|
|
150
|
+
current.heading ||= text;
|
|
151
|
+
continue;
|
|
152
|
+
}
|
|
153
|
+
if (level >= 2) {
|
|
154
|
+
if (current.lines.some((l) => l.trim())) sections.push(current);
|
|
155
|
+
current = { heading: text, level, lines: [] };
|
|
156
|
+
continue;
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
current.lines.push(line);
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
if (current.lines.some((l) => l.trim())) sections.push(current);
|
|
165
|
+
return { title, sections };
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/** Breaks an oversized section body into paragraph-aligned windows. */
|
|
169
|
+
function splitLongText(text: string): string[] {
|
|
170
|
+
if (text.length <= MAX_CHUNK_CHARS) return [text];
|
|
171
|
+
|
|
172
|
+
const parts: string[] = [];
|
|
173
|
+
let buffer = "";
|
|
174
|
+
for (const paragraph of text.split(/\n{2,}/)) {
|
|
175
|
+
if (buffer && buffer.length + paragraph.length > MAX_CHUNK_CHARS) {
|
|
176
|
+
parts.push(buffer.trim());
|
|
177
|
+
buffer = "";
|
|
178
|
+
}
|
|
179
|
+
buffer += `${paragraph}\n\n`;
|
|
180
|
+
}
|
|
181
|
+
if (buffer.trim()) parts.push(buffer.trim());
|
|
182
|
+
return parts;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/** Chunks a single markdown file. `path` is relative to the docs root. */
|
|
186
|
+
export function chunkMarkdown(path: string, markdown: string): DocChunk[] {
|
|
187
|
+
const posixPath = toPosix(path);
|
|
188
|
+
const segments = posixPath.split("/");
|
|
189
|
+
const section = segments.length > 1 ? segments[0]! : "root";
|
|
190
|
+
const group = segments.length > 2 ? segments[1] : undefined;
|
|
191
|
+
const pkg = PKG_BY_PREFIX.find(([prefix]) =>
|
|
192
|
+
posixPath.startsWith(prefix),
|
|
193
|
+
)?.[1];
|
|
194
|
+
|
|
195
|
+
const { title, sections } = splitSections(markdown);
|
|
196
|
+
const docTitle = title || segments.at(-1)!.replace(/\.md$/, "");
|
|
197
|
+
const isReferencePage = REFERENCE_PATH.test(posixPath);
|
|
198
|
+
const chunks: DocChunk[] = [];
|
|
199
|
+
const seenAnchors = new Map<string, number>();
|
|
200
|
+
|
|
201
|
+
for (const rawSection of sections) {
|
|
202
|
+
const heading = rawSection.heading || docTitle;
|
|
203
|
+
const body = rawSection.lines.join("\n").trim();
|
|
204
|
+
if (!body) continue;
|
|
205
|
+
|
|
206
|
+
const parts = splitLongText(body);
|
|
207
|
+
parts.forEach((text, partIndex) => {
|
|
208
|
+
const baseAnchor = rawSection.heading ? slugify(rawSection.heading) : "";
|
|
209
|
+
const seen = seenAnchors.get(baseAnchor) ?? 0;
|
|
210
|
+
seenAnchors.set(baseAnchor, seen + 1);
|
|
211
|
+
// Duplicate headings inside one page get `-1`, `-2`… like VitePress does.
|
|
212
|
+
const anchor = `${baseAnchor}${seen > 0 ? `-${seen}` : ""}`;
|
|
213
|
+
|
|
214
|
+
chunks.push({
|
|
215
|
+
id: `${posixPath}#${anchor}${partIndex > 0 ? `~${partIndex}` : ""}`,
|
|
216
|
+
path: posixPath,
|
|
217
|
+
section,
|
|
218
|
+
...(group ? { group } : {}),
|
|
219
|
+
...(pkg ? { pkg } : {}),
|
|
220
|
+
title: docTitle,
|
|
221
|
+
heading,
|
|
222
|
+
anchor,
|
|
223
|
+
level: rawSection.heading ? rawSection.level : 1,
|
|
224
|
+
...(isReferencePage || REFERENCE_HEADING.test(heading)
|
|
225
|
+
? { kind: "reference" as const }
|
|
226
|
+
: {}),
|
|
227
|
+
text,
|
|
228
|
+
tags: extractTags(text),
|
|
229
|
+
});
|
|
230
|
+
});
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
return chunks;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/** Builds the BM25 inverted index over already-chunked docs. */
|
|
237
|
+
export function buildIndex(chunks: DocChunk[]): Bm25Index {
|
|
238
|
+
const terms: Record<string, Array<[number, number]>> = {};
|
|
239
|
+
const lengths: number[] = [];
|
|
240
|
+
|
|
241
|
+
chunks.forEach((chunk, chunkIndex) => {
|
|
242
|
+
const counts = new Map<string, number>();
|
|
243
|
+
const add = (input: string, boost: number) => {
|
|
244
|
+
for (const token of tokenize(input)) {
|
|
245
|
+
counts.set(token, (counts.get(token) ?? 0) + boost);
|
|
246
|
+
}
|
|
247
|
+
};
|
|
248
|
+
|
|
249
|
+
add(chunk.text, BOOST.text);
|
|
250
|
+
add(chunk.heading, BOOST.heading);
|
|
251
|
+
add(chunk.title, BOOST.title);
|
|
252
|
+
add(chunk.tags.join(" "), BOOST.tags);
|
|
253
|
+
|
|
254
|
+
let length = 0;
|
|
255
|
+
for (const [term, frequency] of counts) {
|
|
256
|
+
(terms[term] ??= []).push([chunkIndex, frequency]);
|
|
257
|
+
length += frequency;
|
|
258
|
+
}
|
|
259
|
+
lengths.push(length);
|
|
260
|
+
});
|
|
261
|
+
|
|
262
|
+
const total = chunks.length;
|
|
263
|
+
const avgLength = total ? lengths.reduce((a, b) => a + b, 0) / total : 0;
|
|
264
|
+
return { terms, lengths, avgLength, total };
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/** Reads every doc under `docsRoot` and returns the full knowledge payload. */
|
|
268
|
+
export function buildDocsKnowledge(docsRoot: string): DocsKnowledge {
|
|
269
|
+
const files = collectMarkdownFiles(docsRoot);
|
|
270
|
+
const chunks: DocChunk[] = [];
|
|
271
|
+
|
|
272
|
+
for (const file of files) {
|
|
273
|
+
if (!statSync(file).isFile()) continue;
|
|
274
|
+
const markdown = readFileSync(file, "utf-8");
|
|
275
|
+
chunks.push(...chunkMarkdown(relative(docsRoot, file), markdown));
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
return {
|
|
279
|
+
version: KNOWLEDGE_VERSION,
|
|
280
|
+
generatedAt: new Date().toISOString(),
|
|
281
|
+
docsRoot: "docs",
|
|
282
|
+
chunks,
|
|
283
|
+
index: buildIndex(chunks),
|
|
284
|
+
};
|
|
285
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Server instructions: what a client receives on `initialize`, and what most
|
|
3
|
+
* clients put in front of the model before any tool call. The Nuxt handler and
|
|
4
|
+
* the stdio CLI both use this text, so the two transports describe Mapo the
|
|
5
|
+
* same way. It stays short; the long form is the overview page (`overview.ts`).
|
|
6
|
+
*
|
|
7
|
+
* Every `mapo_*` name below must be a real tool: a test checks it.
|
|
8
|
+
*/
|
|
9
|
+
export const MAPO_INSTRUCTIONS = `Mapo v2 is a Nuxt 4 admin framework (Vue 3, Nuxt UI v4, Pinia, @nuxtjs/i18n) for building backoffices on a REST API that follows Django REST Framework conventions. An app registers "@nuxt/ui" and then "mapomodule", and configures everything under the \`mapo\` key. The packages: @mapomodule/core ($mapoFetch, useCrud, useMapoAuth, the auth/permissions/roles middleware), store (Pinia stores), uikit (layouts, sidebar, MapoList, MapoDetail, media and menu managers, theming, MapoOverride), form (FieldDescriptor arrays rendered through a field registry, useMapoForm), i18n and utils. A page is declarative: definePageMeta (layout, middleware, label, icon, permissions) plus one Mapo component with props; the sidebar is built from route metadata. Mapo v2 is a rewrite of v1 (Nuxt 2, Vuex, Axios): v1 APIs do not exist here.
|
|
10
|
+
|
|
11
|
+
Workflow:
|
|
12
|
+
1. New to the project or the task? Read the overview: the mapo://overview resource, or mapo_get_doc({ path: "guide/concepts.md" }).
|
|
13
|
+
2. Call mapo_inspect_app before writing code for this project: it reports the Mapo modules installed, the field types actually registered, the components available and the real configuration. mapo_doctor explains anything that looks misconfigured. Both need the app's dev server.
|
|
14
|
+
3. Start from mapo_list_recipes to find the canonical approach: Mapo ships a lot out of the box, and each recipe names the page that documents it.
|
|
15
|
+
4. Use mapo_search_docs for anything the recipes do not cover, then mapo_get_doc to read the exact section. Prefer these over recalling Mapo APIs from memory.
|
|
16
|
+
5. Never invent component props, slots or field types: look them up with mapo_component_api, mapo_list_field_types and mapo_composable_api, which read the installed source.
|
|
17
|
+
6. mapo_backend_schema maps the backend's OpenAPI schema to field descriptors, and mapo_scaffold generates pages, fields and overrides in Mapo's own patterns (a dry run unless asked to write).
|
|
18
|
+
7. Cite the doc path you relied on when you produce code.`;
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Loads the knowledge base generated at package build time.
|
|
3
|
+
*
|
|
4
|
+
* The Nitro side is handed an absolute directory (computed by the module, which
|
|
5
|
+
* knows where the package lives); the CLI resolves it from its own location.
|
|
6
|
+
*/
|
|
7
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
8
|
+
import { dirname, join, resolve } from "node:path";
|
|
9
|
+
import { fileURLToPath } from "node:url";
|
|
10
|
+
import { KNOWLEDGE_VERSION } from "./indexer.js";
|
|
11
|
+
import type { ApiKnowledge, DocsKnowledge } from "./types.js";
|
|
12
|
+
|
|
13
|
+
export const DOCS_KNOWLEDGE_FILE = "docs.json";
|
|
14
|
+
export const API_KNOWLEDGE_FILE = "api.json";
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Bumped whenever the shape of `api.json` changes. Lives here, not in the
|
|
18
|
+
* build entry, so the writer imports it from the reader and the two can never
|
|
19
|
+
* disagree about what version means.
|
|
20
|
+
*/
|
|
21
|
+
export const API_KNOWLEDGE_VERSION = 1;
|
|
22
|
+
|
|
23
|
+
const cache = new Map<string, DocsKnowledge>();
|
|
24
|
+
const apiCache = new Map<string, ApiKnowledge>();
|
|
25
|
+
|
|
26
|
+
/** Directory layouts we may be imported from: `dist/`, `dist/runtime/core/`, `src/…`. */
|
|
27
|
+
const CANDIDATE_SUFFIXES = [
|
|
28
|
+
"knowledge",
|
|
29
|
+
"../knowledge",
|
|
30
|
+
"../../knowledge",
|
|
31
|
+
"../../../knowledge",
|
|
32
|
+
"../dist/knowledge",
|
|
33
|
+
"../../dist/knowledge",
|
|
34
|
+
"../../../dist/knowledge",
|
|
35
|
+
"../../../../dist/knowledge",
|
|
36
|
+
];
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Finds `knowledge/docs.json`, starting from `fromUrl` (defaults to this file).
|
|
40
|
+
* `MAPO_MCP_KNOWLEDGE_DIR` wins when set — used by tests and by the CLI when it
|
|
41
|
+
* runs against a source checkout.
|
|
42
|
+
*/
|
|
43
|
+
export function resolveKnowledgeDir(
|
|
44
|
+
fromUrl: string = import.meta.url,
|
|
45
|
+
): string | null {
|
|
46
|
+
const override = process.env.MAPO_MCP_KNOWLEDGE_DIR;
|
|
47
|
+
if (override && existsSync(join(override, DOCS_KNOWLEDGE_FILE)))
|
|
48
|
+
return override;
|
|
49
|
+
|
|
50
|
+
const base = dirname(fileURLToPath(fromUrl));
|
|
51
|
+
for (const suffix of CANDIDATE_SUFFIXES) {
|
|
52
|
+
const candidate = resolve(base, suffix);
|
|
53
|
+
if (existsSync(join(candidate, DOCS_KNOWLEDGE_FILE))) return candidate;
|
|
54
|
+
}
|
|
55
|
+
return null;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export class KnowledgeNotBuiltError extends Error {
|
|
59
|
+
constructor(searchedFrom: string) {
|
|
60
|
+
super(
|
|
61
|
+
`Mapo knowledge base not found (looked around ${searchedFrom}). ` +
|
|
62
|
+
`Build it with \`pnpm --filter @mapomodule/mcp knowledge\`.`,
|
|
63
|
+
);
|
|
64
|
+
this.name = "KnowledgeNotBuiltError";
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Reads and caches `docs.json`. Throws a directive error when it is missing. */
|
|
69
|
+
export function loadDocsKnowledge(dir?: string | null): DocsKnowledge {
|
|
70
|
+
const directory = dir ?? resolveKnowledgeDir();
|
|
71
|
+
if (!directory)
|
|
72
|
+
throw new KnowledgeNotBuiltError(fileURLToPath(import.meta.url));
|
|
73
|
+
|
|
74
|
+
const cached = cache.get(directory);
|
|
75
|
+
if (cached) return cached;
|
|
76
|
+
|
|
77
|
+
const file = join(directory, DOCS_KNOWLEDGE_FILE);
|
|
78
|
+
if (!existsSync(file)) throw new KnowledgeNotBuiltError(directory);
|
|
79
|
+
|
|
80
|
+
const knowledge = JSON.parse(readFileSync(file, "utf-8")) as DocsKnowledge;
|
|
81
|
+
if (knowledge.version !== KNOWLEDGE_VERSION) {
|
|
82
|
+
throw new Error(
|
|
83
|
+
`Mapo knowledge base version mismatch: found ${knowledge.version}, expected ${KNOWLEDGE_VERSION}. Rebuild it.`,
|
|
84
|
+
);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
cache.set(directory, knowledge);
|
|
88
|
+
return knowledge;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Reads and caches `api.json` — the component, field and composable surface
|
|
93
|
+
* extracted from source at build time.
|
|
94
|
+
*/
|
|
95
|
+
export function loadApiKnowledge(dir?: string | null): ApiKnowledge {
|
|
96
|
+
const directory = dir ?? resolveKnowledgeDir();
|
|
97
|
+
if (!directory)
|
|
98
|
+
throw new KnowledgeNotBuiltError(fileURLToPath(import.meta.url));
|
|
99
|
+
|
|
100
|
+
const cached = apiCache.get(directory);
|
|
101
|
+
if (cached) return cached;
|
|
102
|
+
|
|
103
|
+
const file = join(directory, API_KNOWLEDGE_FILE);
|
|
104
|
+
if (!existsSync(file)) throw new KnowledgeNotBuiltError(directory);
|
|
105
|
+
|
|
106
|
+
const api = JSON.parse(readFileSync(file, "utf-8")) as ApiKnowledge;
|
|
107
|
+
if (api.version !== API_KNOWLEDGE_VERSION) {
|
|
108
|
+
throw new Error(
|
|
109
|
+
`Mapo API surface version mismatch: found ${api.version}, expected ${API_KNOWLEDGE_VERSION}. Rebuild it.`,
|
|
110
|
+
);
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
apiCache.set(directory, api);
|
|
114
|
+
return api;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** Test helper — drops the in-process cache. */
|
|
118
|
+
export function clearKnowledgeCache(): void {
|
|
119
|
+
cache.clear();
|
|
120
|
+
apiCache.clear();
|
|
121
|
+
}
|