@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.
Files changed (166) hide show
  1. package/README.md +509 -2
  2. package/bin/mapo-mcp.mjs +3 -0
  3. package/dist/build.d.mts +18 -0
  4. package/dist/build.d.ts +18 -0
  5. package/dist/build.mjs +351 -0
  6. package/dist/cli.d.mts +7 -0
  7. package/dist/cli.d.ts +7 -0
  8. package/dist/cli.mjs +274 -0
  9. package/dist/index.d.mts +68 -0
  10. package/dist/index.d.ts +68 -0
  11. package/dist/index.mjs +1 -0
  12. package/dist/knowledge/api.json +1 -0
  13. package/dist/knowledge/docs.json +1 -0
  14. package/dist/module.d.mts +16 -0
  15. package/dist/module.d.ts +16 -0
  16. package/dist/module.json +9 -0
  17. package/dist/module.mjs +124 -0
  18. package/dist/runtime/core/doctor.d.ts +0 -0
  19. package/dist/runtime/core/doctor.js +128 -0
  20. package/dist/runtime/core/endpoint.d.ts +0 -0
  21. package/dist/runtime/core/endpoint.js +8 -0
  22. package/dist/runtime/core/indexer.d.ts +0 -0
  23. package/dist/runtime/core/indexer.js +194 -0
  24. package/dist/runtime/core/instructions.d.ts +0 -0
  25. package/dist/runtime/core/instructions.js +10 -0
  26. package/dist/runtime/core/knowledge.d.ts +0 -0
  27. package/dist/runtime/core/knowledge.js +76 -0
  28. package/dist/runtime/core/openapi.d.ts +0 -0
  29. package/dist/runtime/core/openapi.js +229 -0
  30. package/dist/runtime/core/overview.d.ts +0 -0
  31. package/dist/runtime/core/overview.js +15 -0
  32. package/dist/runtime/core/prompts.d.ts +0 -0
  33. package/dist/runtime/core/prompts.js +108 -0
  34. package/dist/runtime/core/recipes.d.ts +0 -0
  35. package/dist/runtime/core/recipes.js +496 -0
  36. package/dist/runtime/core/resources.d.ts +0 -0
  37. package/dist/runtime/core/resources.js +92 -0
  38. package/dist/runtime/core/scaffold/fields.d.ts +0 -0
  39. package/dist/runtime/core/scaffold/fields.js +64 -0
  40. package/dist/runtime/core/scaffold/index.d.ts +0 -0
  41. package/dist/runtime/core/scaffold/index.js +74 -0
  42. package/dist/runtime/core/scaffold/templates.d.ts +0 -0
  43. package/dist/runtime/core/scaffold/templates.js +349 -0
  44. package/dist/runtime/core/schema-source.d.ts +0 -0
  45. package/dist/runtime/core/schema-source.js +70 -0
  46. package/dist/runtime/core/search.d.ts +0 -0
  47. package/dist/runtime/core/search.js +173 -0
  48. package/dist/runtime/core/tokenize.d.ts +0 -0
  49. package/dist/runtime/core/tokenize.js +96 -0
  50. package/dist/runtime/core/tool-spec.d.ts +0 -0
  51. package/dist/runtime/core/tool-spec.js +3 -0
  52. package/dist/runtime/core/tools/api.d.ts +0 -0
  53. package/dist/runtime/core/tools/api.js +192 -0
  54. package/dist/runtime/core/tools/app.d.ts +0 -0
  55. package/dist/runtime/core/tools/app.js +141 -0
  56. package/dist/runtime/core/tools/backend.d.ts +0 -0
  57. package/dist/runtime/core/tools/backend.js +143 -0
  58. package/dist/runtime/core/tools/docs.d.ts +0 -0
  59. package/dist/runtime/core/tools/docs.js +154 -0
  60. package/dist/runtime/core/tools/scaffold.d.ts +0 -0
  61. package/dist/runtime/core/tools/scaffold.js +127 -0
  62. package/dist/runtime/core/types.d.ts +0 -0
  63. package/dist/runtime/core/types.js +0 -0
  64. package/dist/runtime/core/write.d.ts +0 -0
  65. package/dist/runtime/core/write.js +53 -0
  66. package/dist/runtime/mcp/handlers/mapo/index.js +7 -0
  67. package/dist/runtime/mcp/handlers/mapo/prompts/crud-page.js +3 -0
  68. package/dist/runtime/mcp/handlers/mapo/prompts/custom-field.js +3 -0
  69. package/dist/runtime/mcp/handlers/mapo/prompts/debug-form.js +3 -0
  70. package/dist/runtime/mcp/handlers/mapo/prompts/migrate-v1.js +3 -0
  71. package/dist/runtime/mcp/handlers/mapo/prompts/theme.js +3 -0
  72. package/dist/runtime/mcp/handlers/mapo/resources/app-manifest.js +19 -0
  73. package/dist/runtime/mcp/handlers/mapo/resources/docs.js +34 -0
  74. package/dist/runtime/mcp/handlers/mapo/resources/fields.js +34 -0
  75. package/dist/runtime/mcp/handlers/mapo/resources/knowledge-index.js +22 -0
  76. package/dist/runtime/mcp/handlers/mapo/resources/overview.js +20 -0
  77. package/dist/runtime/mcp/handlers/mapo/tools/backend-schema.js +3 -0
  78. package/dist/runtime/mcp/handlers/mapo/tools/component-api.js +3 -0
  79. package/dist/runtime/mcp/handlers/mapo/tools/composable-api.js +3 -0
  80. package/dist/runtime/mcp/handlers/mapo/tools/doctor.js +3 -0
  81. package/dist/runtime/mcp/handlers/mapo/tools/get-doc.js +3 -0
  82. package/dist/runtime/mcp/handlers/mapo/tools/inspect-app.js +3 -0
  83. package/dist/runtime/mcp/handlers/mapo/tools/list-field-types.js +3 -0
  84. package/dist/runtime/mcp/handlers/mapo/tools/list-recipes.js +3 -0
  85. package/dist/runtime/mcp/handlers/mapo/tools/scaffold.js +3 -0
  86. package/dist/runtime/mcp/handlers/mapo/tools/search-docs.js +3 -0
  87. package/dist/runtime/nitro/context.d.ts +0 -0
  88. package/dist/runtime/nitro/context.js +21 -0
  89. package/dist/runtime/nitro/to-mcp-prompt.d.ts +0 -0
  90. package/dist/runtime/nitro/to-mcp-prompt.js +23 -0
  91. package/dist/runtime/nitro/to-mcp-tool.d.ts +0 -0
  92. package/dist/runtime/nitro/to-mcp-tool.js +28 -0
  93. package/dist/runtime/types/virtual-modules.d.ts +6 -0
  94. package/dist/types.d.mts +9 -0
  95. package/package.json +73 -4
  96. package/src/__tests__/cli.test.ts +137 -0
  97. package/src/__tests__/doctor.test.ts +145 -0
  98. package/src/__tests__/endpoint.test.ts +31 -0
  99. package/src/__tests__/fixtures/drf-schema.json +142 -0
  100. package/src/__tests__/fixtures.ts +198 -0
  101. package/src/__tests__/indexer.test.ts +114 -0
  102. package/src/__tests__/knowledge.test.ts +225 -0
  103. package/src/__tests__/openapi.test.ts +256 -0
  104. package/src/__tests__/overview.test.ts +105 -0
  105. package/src/__tests__/recipes.test.ts +55 -0
  106. package/src/__tests__/resources.test.ts +69 -0
  107. package/src/__tests__/scaffold.test.ts +153 -0
  108. package/src/__tests__/search.test.ts +105 -0
  109. package/src/__tests__/tools.test.ts +226 -0
  110. package/src/__tests__/write.test.ts +134 -0
  111. package/src/build/extract-components.ts +135 -0
  112. package/src/build/extract-composables.ts +125 -0
  113. package/src/build/extract-fields.ts +250 -0
  114. package/src/build/index.ts +103 -0
  115. package/src/cli.ts +375 -0
  116. package/src/index.ts +65 -0
  117. package/src/module.ts +213 -0
  118. package/src/runtime/core/doctor.ts +204 -0
  119. package/src/runtime/core/endpoint.ts +27 -0
  120. package/src/runtime/core/indexer.ts +285 -0
  121. package/src/runtime/core/instructions.ts +18 -0
  122. package/src/runtime/core/knowledge.ts +121 -0
  123. package/src/runtime/core/openapi.ts +417 -0
  124. package/src/runtime/core/overview.ts +44 -0
  125. package/src/runtime/core/prompts.ts +150 -0
  126. package/src/runtime/core/recipes.ts +574 -0
  127. package/src/runtime/core/resources.ts +150 -0
  128. package/src/runtime/core/scaffold/fields.ts +127 -0
  129. package/src/runtime/core/scaffold/index.ts +120 -0
  130. package/src/runtime/core/scaffold/templates.ts +394 -0
  131. package/src/runtime/core/schema-source.ts +123 -0
  132. package/src/runtime/core/search.ts +282 -0
  133. package/src/runtime/core/tokenize.ts +146 -0
  134. package/src/runtime/core/tool-spec.ts +74 -0
  135. package/src/runtime/core/tools/api.ts +300 -0
  136. package/src/runtime/core/tools/app.ts +201 -0
  137. package/src/runtime/core/tools/backend.ts +197 -0
  138. package/src/runtime/core/tools/docs.ts +218 -0
  139. package/src/runtime/core/tools/scaffold.ts +176 -0
  140. package/src/runtime/core/types.ts +133 -0
  141. package/src/runtime/core/write.ts +119 -0
  142. package/src/runtime/mcp/handlers/mapo/index.ts +16 -0
  143. package/src/runtime/mcp/handlers/mapo/prompts/crud-page.ts +4 -0
  144. package/src/runtime/mcp/handlers/mapo/prompts/custom-field.ts +4 -0
  145. package/src/runtime/mcp/handlers/mapo/prompts/debug-form.ts +4 -0
  146. package/src/runtime/mcp/handlers/mapo/prompts/migrate-v1.ts +4 -0
  147. package/src/runtime/mcp/handlers/mapo/prompts/theme.ts +4 -0
  148. package/src/runtime/mcp/handlers/mapo/resources/app-manifest.ts +28 -0
  149. package/src/runtime/mcp/handlers/mapo/resources/docs.ts +41 -0
  150. package/src/runtime/mcp/handlers/mapo/resources/fields.ts +37 -0
  151. package/src/runtime/mcp/handlers/mapo/resources/knowledge-index.ts +24 -0
  152. package/src/runtime/mcp/handlers/mapo/resources/overview.ts +22 -0
  153. package/src/runtime/mcp/handlers/mapo/tools/backend-schema.ts +4 -0
  154. package/src/runtime/mcp/handlers/mapo/tools/component-api.ts +4 -0
  155. package/src/runtime/mcp/handlers/mapo/tools/composable-api.ts +4 -0
  156. package/src/runtime/mcp/handlers/mapo/tools/doctor.ts +4 -0
  157. package/src/runtime/mcp/handlers/mapo/tools/get-doc.ts +4 -0
  158. package/src/runtime/mcp/handlers/mapo/tools/inspect-app.ts +4 -0
  159. package/src/runtime/mcp/handlers/mapo/tools/list-field-types.ts +4 -0
  160. package/src/runtime/mcp/handlers/mapo/tools/list-recipes.ts +4 -0
  161. package/src/runtime/mcp/handlers/mapo/tools/scaffold.ts +4 -0
  162. package/src/runtime/mcp/handlers/mapo/tools/search-docs.ts +4 -0
  163. package/src/runtime/nitro/context.ts +41 -0
  164. package/src/runtime/nitro/to-mcp-prompt.ts +30 -0
  165. package/src/runtime/nitro/to-mcp-tool.ts +35 -0
  166. package/src/runtime/types/virtual-modules.d.ts +6 -0
@@ -0,0 +1,256 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { fileURLToPath } from "node:url";
3
+ import { afterEach, describe, expect, it } from "vitest";
4
+ import {
5
+ endpointsByModel,
6
+ listModels,
7
+ renderFields,
8
+ resolveSchema,
9
+ toFields,
10
+ toScaffoldSpecs,
11
+ } from "../runtime/core/openapi.js";
12
+ import {
13
+ SchemaUnavailableError,
14
+ clearSchemaCache,
15
+ loadOpenApiDocument,
16
+ } from "../runtime/core/schema-source.js";
17
+ import type { OpenApiDocument } from "../runtime/core/openapi.js";
18
+
19
+ const fixturePath = fileURLToPath(
20
+ new URL("./fixtures/drf-schema.json", import.meta.url),
21
+ );
22
+ const doc = JSON.parse(readFileSync(fixturePath, "utf-8")) as OpenApiDocument;
23
+
24
+ /** The mapped field for one Article property. */
25
+ function field(key: string) {
26
+ return toFields(doc, "Article", { includeReadOnly: true })!.fields.find(
27
+ (entry) => entry.key === key,
28
+ );
29
+ }
30
+
31
+ afterEach(() => clearSchemaCache());
32
+
33
+ describe("resolveSchema", () => {
34
+ it("follows a $ref to its component", () => {
35
+ const { schema, ref } = resolveSchema(doc, {
36
+ $ref: "#/components/schemas/Tag",
37
+ });
38
+ expect(ref).toBe("Tag");
39
+ expect(schema.properties?.label?.maxLength).toBe(40);
40
+ });
41
+
42
+ it("unwraps the allOf DRF emits for nullable relations, keeping siblings", () => {
43
+ const { schema, ref } = resolveSchema(doc, {
44
+ allOf: [{ $ref: "#/components/schemas/Author" }],
45
+ nullable: true,
46
+ readOnly: true,
47
+ });
48
+
49
+ expect(ref).toBe("Author");
50
+ expect(schema.nullable).toBe(true);
51
+ expect(schema.readOnly).toBe(true); // the sibling wins over the component
52
+ });
53
+ });
54
+
55
+ describe("endpointsByModel", () => {
56
+ it("finds collection endpoints, paginated or plain", () => {
57
+ const endpoints = endpointsByModel(doc);
58
+
59
+ expect(endpoints.get("Article")).toBe("/api/articles/"); // {count, results}
60
+ expect(endpoints.get("Author")).toBe("/api/authors/"); // bare array
61
+ expect(endpoints.get("Tag")).toBe("/api/tags/");
62
+ });
63
+
64
+ it("ignores detail routes", () => {
65
+ // `/api/articles/{id}/` must not win over the collection route.
66
+ expect(endpointsByModel(doc).get("Article")).not.toContain("{id}");
67
+ });
68
+
69
+ it("reports nothing for a component no route serves", () => {
70
+ expect(endpointsByModel(doc).has("Editor")).toBe(false);
71
+ });
72
+ });
73
+
74
+ describe("mapProperty", () => {
75
+ it.each([
76
+ ["title", "text"],
77
+ ["body", "textarea"],
78
+ ["summary", "textarea"],
79
+ ["status", "select"],
80
+ ["published_at", "datetime"],
81
+ ["release_date", "date"],
82
+ ["is_featured", "boolean"],
83
+ ["priority", "number"],
84
+ ["contact_email", "email"],
85
+ ["canonical_url", "url"],
86
+ ["cover", "file"],
87
+ ["author", "fks"],
88
+ ["tags", "m2m"],
89
+ ])("maps %j to %j", (key, type) => {
90
+ expect(field(key)?.type).toBe(type);
91
+ });
92
+
93
+ it("keeps the length limit of a short string and lengthens the rest", () => {
94
+ expect(field("title")?.attrs).toEqual({ maxLength: 200 });
95
+ expect(field("summary")?.type).toBe("textarea");
96
+ });
97
+
98
+ it("turns choices into select items with readable labels", () => {
99
+ expect(field("status")?.attrs).toEqual({
100
+ items: [
101
+ { label: "Draft", value: "draft" },
102
+ { label: "Published", value: "published" },
103
+ { label: "Archived", value: "archived" },
104
+ ],
105
+ });
106
+ });
107
+
108
+ it("prefers the schema title over the derived label", () => {
109
+ expect(field("status")?.label).toBe("Publication status");
110
+ expect(field("published_at")?.label).toBe("Published at");
111
+ });
112
+
113
+ it("carries numeric bounds", () => {
114
+ expect(field("priority")?.attrs).toEqual({ min: 1, max: 10 });
115
+ });
116
+
117
+ it("resolves the endpoint of a relation from the paths section", () => {
118
+ expect(field("author")?.attrs).toEqual({
119
+ endpoint: "/api/authors/",
120
+ itemValue: "id",
121
+ });
122
+ expect(field("tags")?.attrs).toEqual({
123
+ endpoint: "/api/tags/",
124
+ itemValue: "id",
125
+ });
126
+ expect(field("author")?.note).toBeUndefined();
127
+ });
128
+
129
+ it("says so when the endpoint could not be inferred", () => {
130
+ const editor = field("editor")!;
131
+ expect(editor.type).toBe("fks");
132
+ expect(editor.note).toContain("no list endpoint");
133
+ });
134
+
135
+ it("flags an array of plain values instead of pretending it is a repeater", () => {
136
+ expect(field("keywords")?.type).toBe("repeater");
137
+ expect(field("keywords")?.note).toContain("review");
138
+ });
139
+
140
+ it("marks required and read-only from the schema", () => {
141
+ expect(field("title")?.required).toBe(true);
142
+ expect(field("body")?.required).toBeUndefined();
143
+ expect(field("created_at")?.readonly).toBe(true);
144
+ });
145
+ });
146
+
147
+ describe("toFields", () => {
148
+ it("skips read-only properties by default and explains why", () => {
149
+ const result = toFields(doc, "Article")!;
150
+
151
+ expect(result.fields.map((entry) => entry.key)).not.toContain("id");
152
+ expect(result.skipped.map((entry) => entry.key)).toEqual(
153
+ expect.arrayContaining(["id", "created_at"]),
154
+ );
155
+ expect(result.notes.join(" ")).toContain("includeReadOnly");
156
+ });
157
+
158
+ it("reports the model's own endpoint", () => {
159
+ expect(toFields(doc, "Article")!.endpoint).toBe("/api/articles/");
160
+ });
161
+
162
+ it("never emits a type the app does not register", () => {
163
+ const result = toFields(doc, "Article", {
164
+ knownTypes: new Set(["text", "textarea", "select"]),
165
+ })!;
166
+
167
+ expect(
168
+ result.fields.every((entry) =>
169
+ ["text", "textarea", "select"].includes(entry.type),
170
+ ),
171
+ ).toBe(true);
172
+ expect(
173
+ result.skipped.find((entry) => entry.key === "tags")?.reason,
174
+ ).toContain("m2m");
175
+ });
176
+
177
+ it("returns null for an unknown model", () => {
178
+ expect(toFields(doc, "Nope")).toBeNull();
179
+ });
180
+ });
181
+
182
+ describe("rendering", () => {
183
+ it("emits descriptors as TypeScript, with the uncertainty as a comment", () => {
184
+ const code = renderFields(toFields(doc, "Article")!);
185
+
186
+ expect(code).toContain("const fields: FieldDescriptor<Article>[] = [");
187
+ expect(code).toContain(
188
+ '{ key: "title", type: "text", label: "Title", required: true',
189
+ );
190
+ expect(code).toContain("// no list endpoint found for Editor");
191
+ });
192
+
193
+ it("produces specs mapo_scaffold accepts", () => {
194
+ const specs = toScaffoldSpecs(toFields(doc, "Article")!);
195
+ expect(specs).toContain("title:text:Title");
196
+ expect(specs).toContain("status:select:Publication status");
197
+ });
198
+ });
199
+
200
+ describe("listModels", () => {
201
+ it("lists components with their endpoint and size", () => {
202
+ const models = listModels(doc);
203
+ expect(models.map((model) => model.name)).toEqual([
204
+ "Article",
205
+ "Author",
206
+ "Editor",
207
+ "Tag",
208
+ ]);
209
+ expect(models[0]!.endpoint).toBe("/api/articles/");
210
+ expect(models[0]!.fieldCount).toBeGreaterThan(10);
211
+ expect(
212
+ models.find((model) => model.name === "Editor")!.endpoint,
213
+ ).toBeUndefined();
214
+ });
215
+ });
216
+
217
+ describe("loadOpenApiDocument", () => {
218
+ it("reads a local file", async () => {
219
+ const loaded = await loadOpenApiDocument(fixturePath);
220
+ expect(loaded.info?.title).toBe("Example CMS API");
221
+ });
222
+
223
+ it("reports a missing file", async () => {
224
+ await expect(loadOpenApiDocument("/nope/schema.json")).rejects.toThrow(
225
+ SchemaUnavailableError,
226
+ );
227
+ });
228
+
229
+ it("recognises YAML and points at the JSON query param", async () => {
230
+ const { writeFileSync, mkdtempSync } = await import("node:fs");
231
+ const { tmpdir } = await import("node:os");
232
+ const { join } = await import("node:path");
233
+ const path = join(
234
+ mkdtempSync(join(tmpdir(), "mapo-schema-")),
235
+ "schema.yaml",
236
+ );
237
+ writeFileSync(path, "openapi: 3.0.3\ninfo:\n title: x\n");
238
+
239
+ await expect(loadOpenApiDocument(path)).rejects.toThrow(/format=json/);
240
+ });
241
+
242
+ it("rejects a document without component schemas", async () => {
243
+ const { writeFileSync, mkdtempSync } = await import("node:fs");
244
+ const { tmpdir } = await import("node:os");
245
+ const { join } = await import("node:path");
246
+ const path = join(
247
+ mkdtempSync(join(tmpdir(), "mapo-schema-")),
248
+ "empty.json",
249
+ );
250
+ writeFileSync(path, JSON.stringify({ openapi: "3.0.3", paths: {} }));
251
+
252
+ await expect(loadOpenApiDocument(path)).rejects.toThrow(
253
+ /components\.schemas/,
254
+ );
255
+ });
256
+ });
@@ -0,0 +1,105 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { MAPO_INSTRUCTIONS } from "../runtime/core/instructions.js";
3
+ import { overviewSummary, renderOverview } from "../runtime/core/overview.js";
4
+ import { OVERVIEW_DOC, OVERVIEW_URI } from "../runtime/core/resources.js";
5
+ import { apiTools } from "../runtime/core/tools/api.js";
6
+ import { appTools } from "../runtime/core/tools/app.js";
7
+ import { backendTools } from "../runtime/core/tools/backend.js";
8
+ import { docsTools, listRecipesTool } from "../runtime/core/tools/docs.js";
9
+ import { scaffoldTools } from "../runtime/core/tools/scaffold.js";
10
+ import { makeContext, makeKnowledge } from "./fixtures.js";
11
+
12
+ const CONCEPTS_DOC = `# Concepts
13
+
14
+ How Mapo fits together.
15
+
16
+ ## What Mapo is
17
+
18
+ Mapo is a set of Nuxt 4 modules for building admin interfaces.
19
+
20
+ The stack is Nuxt 4, Vue 3 and Nuxt UI.
21
+
22
+ You install one meta-package next to Nuxt UI, in this order:
23
+
24
+ \`\`\`ts
25
+ export default defineNuxtConfig({ modules: ["@nuxt/ui", "mapomodule"] });
26
+ \`\`\`
27
+
28
+ ## The packages
29
+
30
+ Each package has one role.
31
+ `;
32
+
33
+ const withConcepts = () => makeKnowledge({ [OVERVIEW_DOC]: CONCEPTS_DOC });
34
+
35
+ describe("renderOverview", () => {
36
+ it("serves the whole concepts page", () => {
37
+ const text = renderOverview(withConcepts());
38
+ expect(text).toContain("# Concepts");
39
+ expect(text).toContain("## The packages");
40
+ });
41
+
42
+ it("points at the other tools when the page is not indexed", () => {
43
+ const text = renderOverview(
44
+ makeKnowledge({ "howto/x.md": "# X\n\nText." }),
45
+ );
46
+ expect(text).toContain(OVERVIEW_DOC);
47
+ expect(text).toContain("mapo_list_recipes");
48
+ });
49
+ });
50
+
51
+ describe("overviewSummary", () => {
52
+ it("keeps the prose of the section and drops the code sample with its lead-in", () => {
53
+ const summary = overviewSummary(withConcepts())!;
54
+ expect(summary.startsWith("Mapo is a set of Nuxt 4 modules")).toBe(true);
55
+ expect(summary).toContain("The stack is");
56
+ expect(summary).not.toContain("defineNuxtConfig");
57
+ expect(summary).not.toContain("in this order");
58
+ expect(summary).toContain(OVERVIEW_URI);
59
+ });
60
+
61
+ it("is null when the page or the section is missing", () => {
62
+ const otherSection = makeKnowledge({
63
+ [OVERVIEW_DOC]: "# Concepts\n\n## Something else\n\nText.",
64
+ });
65
+ expect(overviewSummary(otherSection)).toBeNull();
66
+ expect(overviewSummary(makeKnowledge({}))).toBeNull();
67
+ });
68
+ });
69
+
70
+ describe("mapo_list_recipes without a task", () => {
71
+ it("opens with the overview when the concepts page is indexed", async () => {
72
+ const output = await listRecipesTool.run(
73
+ {},
74
+ makeContext({ [OVERVIEW_DOC]: CONCEPTS_DOC }),
75
+ );
76
+ expect(output.startsWith("Mapo is a set of Nuxt 4 modules")).toBe(true);
77
+ expect(output).toContain("Mapo recipes:");
78
+ });
79
+
80
+ it("lists the recipes alone when the page is missing", async () => {
81
+ const output = await listRecipesTool.run({}, makeContext());
82
+ expect(output).toMatch(/^\d+ Mapo recipes:/);
83
+ });
84
+ });
85
+
86
+ describe("server instructions", () => {
87
+ const toolNames = [
88
+ ...docsTools,
89
+ ...apiTools,
90
+ ...appTools,
91
+ ...scaffoldTools,
92
+ ...backendTools,
93
+ ].map((tool) => tool.name);
94
+
95
+ it("name only tools that exist", () => {
96
+ const named = MAPO_INSTRUCTIONS.match(/\bmapo_[a-z_]+/g) ?? [];
97
+ expect(named.length).toBeGreaterThan(5);
98
+ for (const name of named) expect(toolNames, name).toContain(name);
99
+ });
100
+
101
+ it("point at the overview", () => {
102
+ expect(MAPO_INSTRUCTIONS).toContain(OVERVIEW_URI);
103
+ expect(MAPO_INSTRUCTIONS).toContain(OVERVIEW_DOC);
104
+ });
105
+ });
@@ -0,0 +1,55 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { matchRecipes, RECIPES } from "../runtime/core/recipes.js";
3
+
4
+ describe("recipe table", () => {
5
+ it("has unique ids and non-empty metadata", () => {
6
+ const ids = RECIPES.map((recipe) => recipe.id);
7
+ expect(new Set(ids).size).toBe(ids.length);
8
+
9
+ for (const recipe of RECIPES) {
10
+ expect(recipe.doc.endsWith(".md")).toBe(true);
11
+ expect(recipe.keywords.length).toBeGreaterThan(2);
12
+ expect(recipe.summary.length).toBeGreaterThan(20);
13
+ }
14
+ });
15
+ });
16
+
17
+ describe("matchRecipes", () => {
18
+ it.each([
19
+ ["register a custom form field component", "custom-field"],
20
+ ["how do I paginate a list of articles with filters", "crud-list"],
21
+ ["let editors reorder the navigation entries", "menu-manager"],
22
+ ["port a v1 project to v2", "migration"],
23
+ ["protect the dashboard route with permissions", "auth-permissions"],
24
+ ["how do the packages fit together", "concepts"],
25
+ ["show a field only when another field is checked", "conditional-fields"],
26
+ ["autosave a draft while the user edits", "form-draft"],
27
+ ["generate the fields from a json schema", "schema-to-form"],
28
+ ["put a hint below one form field with a slot", "form-slots"],
29
+ ["edit a repeater item fullscreen", "focus-mode"],
30
+ ["add my page to the sidebar with an icon", "sidebar-navigation"],
31
+ ["change the branding of the login page", "login-page"],
32
+ ["TS2307 cannot find module mapomodule/types", "imports"],
33
+ ["connect claude code or copilot through mcp", "ai-assistant"],
34
+ ["set up the camomilla session cookie", "camomilla"],
35
+ ])("maps %j to the %j recipe", (query, expectedId) => {
36
+ expect(matchRecipes(query)[0]?.id).toBe(expectedId);
37
+ });
38
+
39
+ it("surfaces both plausible recipes for an ambiguous request", () => {
40
+ // "upload an image" points at media, "in a form" at field types: show both.
41
+ const ids = matchRecipes("upload an image and pick it in a form").map(
42
+ (recipe) => recipe.id,
43
+ );
44
+ expect(ids).toContain("media-manager");
45
+ expect(ids.length).toBeGreaterThan(1);
46
+ });
47
+
48
+ it("stays silent when the query is unrelated", () => {
49
+ expect(matchRecipes("what is the weather today")).toEqual([]);
50
+ });
51
+
52
+ it("caps the number of matches", () => {
53
+ expect(matchRecipes("form field list page", 1)).toHaveLength(1);
54
+ });
55
+ });
@@ -0,0 +1,69 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import {
3
+ DOCS_URI_PREFIX,
4
+ FIELD_URI_PREFIX,
5
+ docResourceList,
6
+ fieldResourceList,
7
+ renderDocResource,
8
+ renderFieldResource,
9
+ renderKnowledgeIndex,
10
+ } from "../runtime/core/resources.js";
11
+ import { makeApi, makeContext } from "./fixtures.js";
12
+
13
+ const context = makeContext();
14
+
15
+ describe("renderKnowledgeIndex", () => {
16
+ it("maps out recipes, pages and every extracted symbol", () => {
17
+ const index = renderKnowledgeIndex(context.knowledge(), context.api());
18
+ expect(index).toContain("## Recipes");
19
+ expect(index).toContain("howto/crud-list.md");
20
+ expect(index).toContain("MapoList, MapoDetail");
21
+ expect(index).toContain("select, text");
22
+ expect(index).toContain("useCrud");
23
+ });
24
+ });
25
+
26
+ describe("renderDocResource", () => {
27
+ it("returns the whole page", () => {
28
+ const text = renderDocResource(context.knowledge(), "howto/crud-list.md")!;
29
+ expect(text).toContain("# CRUD list view");
30
+ expect(text).toContain("Bulk actions");
31
+ });
32
+
33
+ it("returns null for an unknown path", () => {
34
+ expect(renderDocResource(context.knowledge(), "nope.md")).toBeNull();
35
+ });
36
+ });
37
+
38
+ describe("renderFieldResource", () => {
39
+ it("describes the contract of a field type", () => {
40
+ const text = renderFieldResource(makeApi(), "select")!;
41
+ expect(text).toContain("# Field type `select`");
42
+ expect(text).toContain("component: NuiSelectMenu");
43
+ expect(text).toContain("`items`: readonly string[] (required)");
44
+ expect(text).toContain("## Shared descriptor properties");
45
+ });
46
+
47
+ it("returns null for an unregistered type", () => {
48
+ expect(renderFieldResource(makeApi(), "nope")).toBeNull();
49
+ });
50
+ });
51
+
52
+ describe("resource listings", () => {
53
+ it("addresses every doc page under the docs prefix", () => {
54
+ const resources = docResourceList(context.knowledge());
55
+ expect(resources.length).toBeGreaterThan(0);
56
+ for (const resource of resources) {
57
+ expect(resource.uri.startsWith(DOCS_URI_PREFIX)).toBe(true);
58
+ expect(resource.mimeType).toBe("text/markdown");
59
+ }
60
+ });
61
+
62
+ it("addresses every field type under the fields prefix", () => {
63
+ const resources = fieldResourceList(makeApi());
64
+ expect(resources.map((resource) => resource.uri)).toEqual([
65
+ `${FIELD_URI_PREFIX}select`,
66
+ `${FIELD_URI_PREFIX}text`,
67
+ ]);
68
+ });
69
+ });
@@ -0,0 +1,153 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import {
3
+ humanise,
4
+ parseFields,
5
+ UnknownFieldTypeError,
6
+ } from "../runtime/core/scaffold/fields.js";
7
+ import { SCAFFOLD_KINDS, scaffold } from "../runtime/core/scaffold/index.js";
8
+ import { makeApi } from "./fixtures.js";
9
+
10
+ const api = makeApi();
11
+
12
+ describe("field specs", () => {
13
+ it("parses key, type and label", () => {
14
+ expect(parseFields(["title:text:Article title"])).toEqual([
15
+ { key: "title", type: "text", label: "Article title" },
16
+ ]);
17
+ });
18
+
19
+ it("defaults the type to text and derives a readable label", () => {
20
+ expect(parseFields(["published_at"])).toEqual([
21
+ { key: "published_at", type: "text", label: "Published at" },
22
+ ]);
23
+ });
24
+
25
+ it("rejects a type the registry does not know", () => {
26
+ expect(() => parseFields(["title:wysiwyg"], api)).toThrow(
27
+ UnknownFieldTypeError,
28
+ );
29
+ try {
30
+ parseFields(["title:wysiwyg"], api);
31
+ } catch (error) {
32
+ // The message must let the caller recover on its own.
33
+ expect((error as Error).message).toContain("select, text");
34
+ expect((error as Error).message).toContain("defineFormField");
35
+ }
36
+ });
37
+
38
+ it("humanises identifiers", () => {
39
+ expect(humanise("is_featured")).toBe("Is featured");
40
+ expect(humanise("coverImage")).toBe("Cover image");
41
+ });
42
+ });
43
+
44
+ describe("scaffold", () => {
45
+ it("covers every advertised kind", () => {
46
+ for (const kind of SCAFFOLD_KINDS) {
47
+ const result = scaffold({ kind, name: "articles", api });
48
+ expect(result.files.length, kind).toBeGreaterThan(0);
49
+ expect(result.docs.length, kind).toBeGreaterThan(0);
50
+ for (const file of result.files) {
51
+ expect(file.content.length, `${kind} → ${file.path}`).toBeGreaterThan(
52
+ 50,
53
+ );
54
+ expect(file.path.startsWith("/"), `${kind} → ${file.path}`).toBe(false);
55
+ }
56
+ }
57
+ });
58
+
59
+ it("derives model, route and endpoint from the resource name", () => {
60
+ const [file] = scaffold({ kind: "list-page", name: "articles", api }).files;
61
+
62
+ expect(file!.path).toBe("app/pages/articles/index.vue");
63
+ expect(file!.content).toContain("interface Article {");
64
+ expect(file!.content).toContain('endpoint="/api/articles"');
65
+ expect(file!.content).toContain('detail-base="/articles"');
66
+ });
67
+
68
+ it.each([
69
+ ["categories", "Category"],
70
+ ["boxes", "Box"],
71
+ ["articles", "Article"],
72
+ // Irregular plurals are left alone rather than guessed at.
73
+ ["media", "Media"],
74
+ ["star-rating", "StarRating"],
75
+ ])("singularises %j into %j", (name, model) => {
76
+ const result = scaffold({ kind: "detail-page", name, api });
77
+ expect(result.files[0]!.content).toContain(`interface ${model} {`);
78
+ });
79
+
80
+ it("honours explicit endpoint and route", () => {
81
+ const [file] = scaffold({
82
+ kind: "list-page",
83
+ name: "articles",
84
+ endpoint: "/api/cms/posts",
85
+ route: "/content/posts",
86
+ api,
87
+ }).files;
88
+
89
+ expect(file!.path).toBe("app/pages/content/posts/index.vue");
90
+ expect(file!.content).toContain('endpoint="/api/cms/posts"');
91
+ });
92
+
93
+ it("emits descriptors with the requested types and a typed model", () => {
94
+ const [file] = scaffold({
95
+ kind: "detail-page",
96
+ name: "articles",
97
+ fields: ["title:text:Title", "featured:select:Featured"],
98
+ api,
99
+ }).files;
100
+
101
+ expect(file!.content).toContain('key: "title"');
102
+ expect(file!.content).toContain('type: "select"');
103
+ expect(file!.content).toContain("title: string;");
104
+ // `select` declares a required `items` attr: the skeleton must show it.
105
+ expect(file!.content).toContain("attrs: { items: undefined /* TODO */ }");
106
+ });
107
+
108
+ it("generates both the component and its registration for a custom field", () => {
109
+ const result = scaffold({ kind: "custom-field", name: "star-rating", api });
110
+
111
+ expect(result.files.map((file) => file.path)).toEqual([
112
+ "app/components/StarRatingField.vue",
113
+ "app/plugins/star-rating-field.ts",
114
+ ]);
115
+ expect(result.files[1]!.content).toContain('defineFormField("star-rating"');
116
+ expect(result.notes.join(" ")).toContain("mapo_inspect_app");
117
+ });
118
+
119
+ it("keeps the login page out of the admin layout", () => {
120
+ const [file] = scaffold({ kind: "login-page", api }).files;
121
+
122
+ expect(file!.path).toBe("app/pages/login.vue");
123
+ expect(file!.content).toContain("layout: false");
124
+ expect(file!.content).toContain("<MapoLogin />");
125
+ });
126
+
127
+ it("imports types from the aggregate package a consumer installs", () => {
128
+ for (const kind of [
129
+ "list-page",
130
+ "detail-page",
131
+ "standalone-form",
132
+ ] as const) {
133
+ const content = scaffold({ kind, name: "articles", api }).files[0]!
134
+ .content;
135
+ expect(content, kind).toContain('from "mapomodule/types"');
136
+ }
137
+ });
138
+
139
+ it("puts every page behind the auth middleware and the admin layout", () => {
140
+ for (const kind of [
141
+ "list-page",
142
+ "detail-page",
143
+ "standalone-form",
144
+ "menu-page",
145
+ "media-page",
146
+ ] as const) {
147
+ const content = scaffold({ kind, name: "articles", api }).files[0]!
148
+ .content;
149
+ expect(content, kind).toContain('layout: "mapo-default"');
150
+ expect(content, kind).toContain('middleware: ["auth"]');
151
+ }
152
+ });
153
+ });