@mapomodule/mcp 0.0.0-stage → 1.0.0-beta.1

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 (153) hide show
  1. package/README.md +479 -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 +263 -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 +121 -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/indexer.d.ts +0 -0
  21. package/dist/runtime/core/indexer.js +193 -0
  22. package/dist/runtime/core/knowledge.d.ts +0 -0
  23. package/dist/runtime/core/knowledge.js +76 -0
  24. package/dist/runtime/core/openapi.d.ts +0 -0
  25. package/dist/runtime/core/openapi.js +229 -0
  26. package/dist/runtime/core/prompts.d.ts +0 -0
  27. package/dist/runtime/core/prompts.js +108 -0
  28. package/dist/runtime/core/recipes.d.ts +0 -0
  29. package/dist/runtime/core/recipes.js +297 -0
  30. package/dist/runtime/core/resources.d.ts +0 -0
  31. package/dist/runtime/core/resources.js +88 -0
  32. package/dist/runtime/core/scaffold/fields.d.ts +0 -0
  33. package/dist/runtime/core/scaffold/fields.js +64 -0
  34. package/dist/runtime/core/scaffold/index.d.ts +0 -0
  35. package/dist/runtime/core/scaffold/index.js +74 -0
  36. package/dist/runtime/core/scaffold/templates.d.ts +0 -0
  37. package/dist/runtime/core/scaffold/templates.js +349 -0
  38. package/dist/runtime/core/schema-source.d.ts +0 -0
  39. package/dist/runtime/core/schema-source.js +70 -0
  40. package/dist/runtime/core/search.d.ts +0 -0
  41. package/dist/runtime/core/search.js +173 -0
  42. package/dist/runtime/core/tokenize.d.ts +0 -0
  43. package/dist/runtime/core/tokenize.js +96 -0
  44. package/dist/runtime/core/tool-spec.d.ts +0 -0
  45. package/dist/runtime/core/tool-spec.js +3 -0
  46. package/dist/runtime/core/tools/api.d.ts +0 -0
  47. package/dist/runtime/core/tools/api.js +192 -0
  48. package/dist/runtime/core/tools/app.d.ts +0 -0
  49. package/dist/runtime/core/tools/app.js +141 -0
  50. package/dist/runtime/core/tools/backend.d.ts +0 -0
  51. package/dist/runtime/core/tools/backend.js +143 -0
  52. package/dist/runtime/core/tools/docs.d.ts +0 -0
  53. package/dist/runtime/core/tools/docs.js +150 -0
  54. package/dist/runtime/core/tools/scaffold.d.ts +0 -0
  55. package/dist/runtime/core/tools/scaffold.js +127 -0
  56. package/dist/runtime/core/types.d.ts +0 -0
  57. package/dist/runtime/core/types.js +0 -0
  58. package/dist/runtime/core/write.d.ts +0 -0
  59. package/dist/runtime/core/write.js +53 -0
  60. package/dist/runtime/mcp/handlers/mapo/index.js +13 -0
  61. package/dist/runtime/mcp/handlers/mapo/prompts/crud-page.js +3 -0
  62. package/dist/runtime/mcp/handlers/mapo/prompts/custom-field.js +3 -0
  63. package/dist/runtime/mcp/handlers/mapo/prompts/debug-form.js +3 -0
  64. package/dist/runtime/mcp/handlers/mapo/prompts/migrate-v1.js +3 -0
  65. package/dist/runtime/mcp/handlers/mapo/prompts/theme.js +3 -0
  66. package/dist/runtime/mcp/handlers/mapo/resources/app-manifest.js +19 -0
  67. package/dist/runtime/mcp/handlers/mapo/resources/docs.js +34 -0
  68. package/dist/runtime/mcp/handlers/mapo/resources/fields.js +34 -0
  69. package/dist/runtime/mcp/handlers/mapo/resources/knowledge-index.js +22 -0
  70. package/dist/runtime/mcp/handlers/mapo/tools/backend-schema.js +3 -0
  71. package/dist/runtime/mcp/handlers/mapo/tools/component-api.js +3 -0
  72. package/dist/runtime/mcp/handlers/mapo/tools/composable-api.js +3 -0
  73. package/dist/runtime/mcp/handlers/mapo/tools/doctor.js +3 -0
  74. package/dist/runtime/mcp/handlers/mapo/tools/get-doc.js +3 -0
  75. package/dist/runtime/mcp/handlers/mapo/tools/inspect-app.js +3 -0
  76. package/dist/runtime/mcp/handlers/mapo/tools/list-field-types.js +3 -0
  77. package/dist/runtime/mcp/handlers/mapo/tools/list-recipes.js +3 -0
  78. package/dist/runtime/mcp/handlers/mapo/tools/scaffold.js +3 -0
  79. package/dist/runtime/mcp/handlers/mapo/tools/search-docs.js +3 -0
  80. package/dist/runtime/nitro/context.d.ts +0 -0
  81. package/dist/runtime/nitro/context.js +21 -0
  82. package/dist/runtime/nitro/to-mcp-prompt.d.ts +0 -0
  83. package/dist/runtime/nitro/to-mcp-prompt.js +23 -0
  84. package/dist/runtime/nitro/to-mcp-tool.d.ts +0 -0
  85. package/dist/runtime/nitro/to-mcp-tool.js +28 -0
  86. package/dist/runtime/types/virtual-modules.d.ts +6 -0
  87. package/dist/types.d.mts +9 -0
  88. package/package.json +73 -4
  89. package/src/__tests__/cli.test.ts +121 -0
  90. package/src/__tests__/doctor.test.ts +145 -0
  91. package/src/__tests__/fixtures/drf-schema.json +142 -0
  92. package/src/__tests__/fixtures.ts +198 -0
  93. package/src/__tests__/indexer.test.ts +114 -0
  94. package/src/__tests__/knowledge.test.ts +209 -0
  95. package/src/__tests__/openapi.test.ts +256 -0
  96. package/src/__tests__/recipes.test.ts +44 -0
  97. package/src/__tests__/resources.test.ts +69 -0
  98. package/src/__tests__/scaffold.test.ts +153 -0
  99. package/src/__tests__/search.test.ts +105 -0
  100. package/src/__tests__/tools.test.ts +226 -0
  101. package/src/__tests__/write.test.ts +134 -0
  102. package/src/build/extract-components.ts +135 -0
  103. package/src/build/extract-composables.ts +125 -0
  104. package/src/build/extract-fields.ts +250 -0
  105. package/src/build/index.ts +103 -0
  106. package/src/cli.ts +364 -0
  107. package/src/index.ts +65 -0
  108. package/src/module.ts +214 -0
  109. package/src/runtime/core/doctor.ts +204 -0
  110. package/src/runtime/core/indexer.ts +279 -0
  111. package/src/runtime/core/knowledge.ts +121 -0
  112. package/src/runtime/core/openapi.ts +417 -0
  113. package/src/runtime/core/prompts.ts +150 -0
  114. package/src/runtime/core/recipes.ts +361 -0
  115. package/src/runtime/core/resources.ts +144 -0
  116. package/src/runtime/core/scaffold/fields.ts +127 -0
  117. package/src/runtime/core/scaffold/index.ts +120 -0
  118. package/src/runtime/core/scaffold/templates.ts +394 -0
  119. package/src/runtime/core/schema-source.ts +123 -0
  120. package/src/runtime/core/search.ts +282 -0
  121. package/src/runtime/core/tokenize.ts +146 -0
  122. package/src/runtime/core/tool-spec.ts +74 -0
  123. package/src/runtime/core/tools/api.ts +300 -0
  124. package/src/runtime/core/tools/app.ts +200 -0
  125. package/src/runtime/core/tools/backend.ts +197 -0
  126. package/src/runtime/core/tools/docs.ts +215 -0
  127. package/src/runtime/core/tools/scaffold.ts +176 -0
  128. package/src/runtime/core/types.ts +133 -0
  129. package/src/runtime/core/write.ts +119 -0
  130. package/src/runtime/mcp/handlers/mapo/index.ts +22 -0
  131. package/src/runtime/mcp/handlers/mapo/prompts/crud-page.ts +4 -0
  132. package/src/runtime/mcp/handlers/mapo/prompts/custom-field.ts +4 -0
  133. package/src/runtime/mcp/handlers/mapo/prompts/debug-form.ts +4 -0
  134. package/src/runtime/mcp/handlers/mapo/prompts/migrate-v1.ts +4 -0
  135. package/src/runtime/mcp/handlers/mapo/prompts/theme.ts +4 -0
  136. package/src/runtime/mcp/handlers/mapo/resources/app-manifest.ts +28 -0
  137. package/src/runtime/mcp/handlers/mapo/resources/docs.ts +41 -0
  138. package/src/runtime/mcp/handlers/mapo/resources/fields.ts +37 -0
  139. package/src/runtime/mcp/handlers/mapo/resources/knowledge-index.ts +24 -0
  140. package/src/runtime/mcp/handlers/mapo/tools/backend-schema.ts +4 -0
  141. package/src/runtime/mcp/handlers/mapo/tools/component-api.ts +4 -0
  142. package/src/runtime/mcp/handlers/mapo/tools/composable-api.ts +4 -0
  143. package/src/runtime/mcp/handlers/mapo/tools/doctor.ts +4 -0
  144. package/src/runtime/mcp/handlers/mapo/tools/get-doc.ts +4 -0
  145. package/src/runtime/mcp/handlers/mapo/tools/inspect-app.ts +4 -0
  146. package/src/runtime/mcp/handlers/mapo/tools/list-field-types.ts +4 -0
  147. package/src/runtime/mcp/handlers/mapo/tools/list-recipes.ts +4 -0
  148. package/src/runtime/mcp/handlers/mapo/tools/scaffold.ts +4 -0
  149. package/src/runtime/mcp/handlers/mapo/tools/search-docs.ts +4 -0
  150. package/src/runtime/nitro/context.ts +41 -0
  151. package/src/runtime/nitro/to-mcp-prompt.ts +30 -0
  152. package/src/runtime/nitro/to-mcp-tool.ts +35 -0
  153. package/src/runtime/types/virtual-modules.d.ts +6 -0
@@ -0,0 +1,229 @@
1
+ function refName(ref) {
2
+ return ref.split("/").pop() ?? ref;
3
+ }
4
+ export function resolveSchema(doc, schema, depth = 0) {
5
+ if (!schema || depth > 5) return { schema: schema ?? {} };
6
+ if (schema.$ref) {
7
+ const name = refName(schema.$ref);
8
+ const target = doc.components?.schemas?.[name];
9
+ if (!target) return { schema: {}, ref: name };
10
+ const resolved = resolveSchema(doc, target, depth + 1);
11
+ return { schema: resolved.schema, ref: resolved.ref ?? name };
12
+ }
13
+ if (schema.allOf?.length) {
14
+ const merged = schema.allOf.reduce(
15
+ (accumulator, member) => {
16
+ const resolved = resolveSchema(doc, member, depth + 1);
17
+ return {
18
+ schema: { ...accumulator.schema, ...resolved.schema },
19
+ ref: resolved.ref ?? accumulator.ref
20
+ };
21
+ },
22
+ { schema: {} }
23
+ );
24
+ const { allOf: _allOf, ...siblings } = schema;
25
+ return { schema: { ...merged.schema, ...siblings }, ref: merged.ref };
26
+ }
27
+ return { schema };
28
+ }
29
+ export function endpointsByModel(doc) {
30
+ const byModel = /* @__PURE__ */ new Map();
31
+ for (const [path, operations] of Object.entries(doc.paths ?? {})) {
32
+ if (/\{[^}]+\}/.test(path)) continue;
33
+ const get = operations?.get;
34
+ const schema = get?.responses?.["200"]?.content?.["application/json"]?.schema;
35
+ if (!schema) continue;
36
+ const direct = schema.$ref ? refName(schema.$ref) : void 0;
37
+ const results = schema.properties?.results;
38
+ const paginated = results?.items?.$ref ? refName(results.items.$ref) : void 0;
39
+ const array = schema.items?.$ref ? refName(schema.items.$ref) : void 0;
40
+ const model = paginated ?? array ?? direct;
41
+ if (model && !byModel.has(model)) byModel.set(model, path);
42
+ }
43
+ return byModel;
44
+ }
45
+ function labelFor(key, schema) {
46
+ if (schema.title) return schema.title;
47
+ return key.replace(/[_-]+/g, " ").trim().toLowerCase().replace(/^./, (character) => character.toUpperCase());
48
+ }
49
+ const TEXTAREA_THRESHOLD = 500;
50
+ function enumItems(schema) {
51
+ return (schema.enum ?? []).map((value) => ({
52
+ label: String(value).replace(/[_-]+/g, " ").replace(/^./, (character) => character.toUpperCase()),
53
+ value
54
+ }));
55
+ }
56
+ export function mapProperty(doc, key, raw, options = {}) {
57
+ const { schema, ref } = resolveSchema(doc, raw);
58
+ const endpoints = options.endpoints ?? /* @__PURE__ */ new Map();
59
+ const base = {
60
+ key,
61
+ type: "text",
62
+ label: labelFor(key, schema),
63
+ ...options.required ? { required: true } : {},
64
+ ...schema.readOnly ? { readonly: true } : {}
65
+ };
66
+ if (schema.enum?.length) {
67
+ return { ...base, type: "select", attrs: { items: enumItems(schema) } };
68
+ }
69
+ if (schema.type === "boolean") return { ...base, type: "boolean" };
70
+ if (schema.type === "integer" || schema.type === "number") {
71
+ const attrs2 = {};
72
+ if (schema.minimum !== void 0) attrs2.min = schema.minimum;
73
+ if (schema.maximum !== void 0) attrs2.max = schema.maximum;
74
+ return {
75
+ ...base,
76
+ type: "number",
77
+ ...Object.keys(attrs2).length ? { attrs: attrs2 } : {}
78
+ };
79
+ }
80
+ if (schema.type === "array") {
81
+ const item = resolveSchema(doc, schema.items);
82
+ if (item.ref) {
83
+ const endpoint = endpoints.get(item.ref);
84
+ return {
85
+ ...base,
86
+ type: "m2m",
87
+ attrs: {
88
+ endpoint: endpoint ?? `/api/${item.ref.toLowerCase()}/`,
89
+ itemValue: "id"
90
+ },
91
+ ...endpoint ? {} : {
92
+ note: `no list endpoint found for ${item.ref}; check attrs.endpoint`
93
+ }
94
+ };
95
+ }
96
+ if (item.schema.enum?.length) {
97
+ return {
98
+ ...base,
99
+ type: "select",
100
+ attrs: { multiple: true, items: enumItems(item.schema) }
101
+ };
102
+ }
103
+ return {
104
+ ...base,
105
+ type: "repeater",
106
+ note: "array of plain values: a repeater expects objects, so review this one"
107
+ };
108
+ }
109
+ if (ref && (schema.type === "object" || schema.properties)) {
110
+ const endpoint = endpoints.get(ref);
111
+ return {
112
+ ...base,
113
+ type: "fks",
114
+ attrs: {
115
+ endpoint: endpoint ?? `/api/${ref.toLowerCase()}/`,
116
+ itemValue: "id"
117
+ },
118
+ ...endpoint ? {} : { note: `no list endpoint found for ${ref}; check attrs.endpoint` }
119
+ };
120
+ }
121
+ if (schema.type === "object") {
122
+ return {
123
+ ...base,
124
+ type: "text",
125
+ note: "free-form object: consider a repeater or a custom field"
126
+ };
127
+ }
128
+ switch (schema.format) {
129
+ case "date-time":
130
+ return { ...base, type: "datetime" };
131
+ case "date":
132
+ return { ...base, type: "date" };
133
+ case "time":
134
+ return { ...base, type: "time" };
135
+ case "email":
136
+ return { ...base, type: "email" };
137
+ case "uri":
138
+ case "url":
139
+ return { ...base, type: "url" };
140
+ case "binary":
141
+ return { ...base, type: "file" };
142
+ default:
143
+ break;
144
+ }
145
+ const attrs = {};
146
+ if (schema.maxLength !== void 0) attrs.maxLength = schema.maxLength;
147
+ const long = schema.maxLength === void 0 || schema.maxLength >= TEXTAREA_THRESHOLD;
148
+ return {
149
+ ...base,
150
+ type: long ? "textarea" : "text",
151
+ ...Object.keys(attrs).length ? { attrs } : {}
152
+ };
153
+ }
154
+ export function listModels(doc) {
155
+ const endpoints = endpointsByModel(doc);
156
+ return Object.entries(doc.components?.schemas ?? {}).map(([name, schema]) => ({
157
+ name,
158
+ ...schema.title ? { title: schema.title } : {},
159
+ ...schema.description ? { description: schema.description } : {},
160
+ ...endpoints.has(name) ? { endpoint: endpoints.get(name) } : {},
161
+ fieldCount: Object.keys(schema.properties ?? {}).length
162
+ })).sort((a, b) => a.name.localeCompare(b.name));
163
+ }
164
+ export function toFields(doc, model, options = {}) {
165
+ const schema = doc.components?.schemas?.[model];
166
+ if (!schema) return null;
167
+ const endpoints = endpointsByModel(doc);
168
+ const required = new Set(schema.required ?? []);
169
+ const fields = [];
170
+ const skipped = [];
171
+ const notes = [];
172
+ for (const [key, property] of Object.entries(schema.properties ?? {})) {
173
+ const { schema: resolved } = resolveSchema(doc, property);
174
+ if (resolved.readOnly && !options.includeReadOnly) {
175
+ skipped.push({ key, reason: "read-only in the API" });
176
+ continue;
177
+ }
178
+ const mapped = mapProperty(doc, key, property, {
179
+ required: required.has(key),
180
+ endpoints
181
+ });
182
+ if (!mapped) {
183
+ skipped.push({ key, reason: "no sensible field type" });
184
+ continue;
185
+ }
186
+ if (options.knownTypes && !options.knownTypes.has(mapped.type)) {
187
+ skipped.push({
188
+ key,
189
+ reason: `maps to \`${mapped.type}\`, which this app does not register`
190
+ });
191
+ continue;
192
+ }
193
+ fields.push(mapped);
194
+ }
195
+ if (skipped.some((entry) => entry.reason === "read-only in the API")) {
196
+ notes.push(
197
+ "Read-only properties were skipped; pass includeReadOnly to keep them as readonly fields."
198
+ );
199
+ }
200
+ return {
201
+ model,
202
+ ...endpoints.has(model) ? { endpoint: endpoints.get(model) } : {},
203
+ fields,
204
+ skipped,
205
+ notes
206
+ };
207
+ }
208
+ export function renderFields(result) {
209
+ const body = result.fields.map((field) => {
210
+ const parts = [
211
+ `key: "${field.key}"`,
212
+ `type: "${field.type}"`,
213
+ `label: "${field.label}"`
214
+ ];
215
+ if (field.required) parts.push("required: true");
216
+ if (field.readonly) parts.push("readonly: true");
217
+ if (field.attrs) parts.push(`attrs: ${JSON.stringify(field.attrs)}`);
218
+ const comment = field.note ? ` // ${field.note}` : "";
219
+ return ` { ${parts.join(", ")} },${comment}`;
220
+ }).join("\n");
221
+ return `const fields: FieldDescriptor<${result.model}>[] = [
222
+ ${body}
223
+ ];`;
224
+ }
225
+ export function toScaffoldSpecs(result) {
226
+ return result.fields.map(
227
+ (field) => `${field.key}:${field.type}:${field.label}`
228
+ );
229
+ }
File without changes
@@ -0,0 +1,108 @@
1
+ import { z } from "zod";
2
+ const optional = (description) => z.string().optional().describe(description);
3
+ export const crudPagePrompt = {
4
+ name: "mapo-crud-page",
5
+ title: "Build a CRUD page",
6
+ description: "List + detail pages for a resource, following Mapo's canonical pattern.",
7
+ argsSchema: {
8
+ resource: optional("Resource name, e.g. 'articles'"),
9
+ fields: optional("Fields to edit, e.g. 'title, body, status, cover image'")
10
+ },
11
+ render: ({
12
+ resource,
13
+ fields
14
+ }) => `Build the admin pages for ${resource ?? "a resource I will name"} in this Mapo project${fields ? `, editing: ${fields}` : ""}.
15
+
16
+ Follow this order and do not skip a step:
17
+ 1. mapo_inspect_app \u2014 see which field types are registered, which components exist and how the app is configured.
18
+ 2. mapo_list_field_types \u2014 pick the right \`type\` for each field, and read the \`attrs\` it accepts. Never invent a type.
19
+ 3. mapo_scaffold with kind "list-page", then kind "detail-page", passing \`fields\` as \`key:type:Label\` specs. Review the output before writing anything.
20
+ 4. mapo_component_api for MapoList and MapoDetail if you need a prop, slot or event that the scaffold does not cover.
21
+
22
+ Then adapt the generated code to the real backend payload, and tell me which endpoints it expects.`
23
+ };
24
+ export const customFieldPrompt = {
25
+ name: "mapo-custom-field",
26
+ title: "Create a custom field type",
27
+ description: "A new field component plus its registration in the form registry.",
28
+ argsSchema: {
29
+ type: optional("Type name, e.g. 'star-rating'"),
30
+ behaviour: optional("What the field should do")
31
+ },
32
+ render: ({
33
+ type,
34
+ behaviour
35
+ }) => `Add a custom form field type${type ? ` called \`${type}\`` : ""} to this Mapo project${behaviour ? `: ${behaviour}` : ""}.
36
+
37
+ Steps:
38
+ 1. mapo_list_field_types \u2014 check no built-in type already does this; overriding a built-in is a different decision than adding one.
39
+ 2. mapo_get_doc { path: "uikit/form/registry.md" } \u2014 the registration contract.
40
+ 3. mapo_scaffold with kind "custom-field" \u2014 it generates both the component and the plugin that registers the type.
41
+ 4. Implement the component body. It must accept \`modelValue\`, \`descriptor\`, \`errors\`, \`readonly\`, \`disabled\` and emit \`update:modelValue\`. Nothing else.
42
+
43
+ Remember that types registered at runtime are invisible to mapo_inspect_app, which reads a build-time snapshot.`
44
+ };
45
+ export const debugFormPrompt = {
46
+ name: "mapo-debug-form",
47
+ title: "Debug a Mapo form",
48
+ description: "Diagnose a form that does not render, validate or save as expected.",
49
+ argsSchema: {
50
+ symptom: optional("What goes wrong, e.g. 'the select is empty'")
51
+ },
52
+ render: ({
53
+ symptom
54
+ }) => `A Mapo form is not behaving${symptom ? `: ${symptom}` : ""}. Diagnose it.
55
+
56
+ Steps:
57
+ 1. mapo_doctor \u2014 rule out a configuration problem before reading any code.
58
+ 2. mapo_inspect_app { include: ["fields", "config"] } \u2014 confirm the field type used is actually registered.
59
+ 3. mapo_list_field_types { type: "<the type>" } \u2014 check the descriptor's \`attrs\` against what the code passes; a missing required attr is the usual cause of an empty or inert field.
60
+ 4. mapo_search_docs for the specific behaviour (validation, translatable fields, repeater, accessors) and read the section with mapo_get_doc.
61
+
62
+ Report the cause before proposing a fix, and quote the doc path you relied on.`
63
+ };
64
+ export const migratePrompt = {
65
+ name: "mapo-migrate-v1",
66
+ title: "Migrate from Mapo v1",
67
+ description: "Port v1 code to the v2 APIs.",
68
+ argsSchema: {
69
+ area: optional("What to migrate, e.g. 'the list configuration'")
70
+ },
71
+ render: ({
72
+ area
73
+ }) => `Migrate this code from Mapo v1 to v2${area ? `, focusing on ${area}` : ""}.
74
+
75
+ Steps:
76
+ 1. mapo_get_doc { path: "migration/v1-to-v2.md" } \u2014 read it before changing anything.
77
+ 2. mapo_component_api / mapo_list_field_types for every symbol you touch: v1 names survive in training data long after they stop existing, so check each one against the installed source.
78
+ 3. mapo_search_docs for anything the migration page does not cover.
79
+
80
+ Do not port v1 patterns that v2 replaced (Vuex stores, Axios instances, config objects where v2 takes declarative props). Point them out instead.`
81
+ };
82
+ export const themePrompt = {
83
+ name: "mapo-theme",
84
+ title: "Restyle the admin",
85
+ description: "Change the look of a Mapo admin, from tokens to full component replacement.",
86
+ argsSchema: {
87
+ goal: optional(
88
+ "What should change, e.g. 'brand colours and a denser sidebar'"
89
+ )
90
+ },
91
+ render: ({ goal }) => `Restyle this Mapo admin${goal ? `: ${goal}` : ""}.
92
+
93
+ Pick the lightest layer that does the job, in this order:
94
+ 1. mapo_get_doc { path: "howto/theming.md" } \u2014 CSS tokens and Nuxt UI defaults cover most requests.
95
+ 2. mapo_scaffold with kind "theme-override" for the token file and the nuxt.config fragment.
96
+ 3. Layout slots, if the change is structural \u2014 mapo_component_api on the layout components to see which slots exist.
97
+ 4. The MapoOverride system only as a last resort: mapo_get_doc { path: "uikit/mapoverride.md" }. Replacing a component means owning its updates.
98
+
99
+ Say which layer you chose and why.`
100
+ };
101
+ export const PROMPTS = [
102
+ crudPagePrompt,
103
+ customFieldPrompt,
104
+ debugFormPrompt,
105
+ migratePrompt,
106
+ themePrompt
107
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
108
+ ];
File without changes
@@ -0,0 +1,297 @@
1
+ import { tokenize } from "./tokenize.js";
2
+ export const RECIPES = [
3
+ {
4
+ id: "first-admin-page",
5
+ task: "Create the first admin page",
6
+ keywords: [
7
+ "scaffold",
8
+ "start",
9
+ "setup",
10
+ "layout",
11
+ "definePageMeta",
12
+ "dashboard",
13
+ "sidebar entry"
14
+ ],
15
+ doc: "howto/first-admin-page.md",
16
+ seeAlso: ["guide/getting-started.md"],
17
+ summary: "Page meta, mapo-default layout, auth middleware and sidebar registration."
18
+ },
19
+ {
20
+ id: "crud-list",
21
+ task: "Build a CRUD list page",
22
+ keywords: [
23
+ "MapoList",
24
+ "table",
25
+ "columns",
26
+ "pagination",
27
+ "filters",
28
+ "tabs",
29
+ "bulk",
30
+ "quick edit",
31
+ "search",
32
+ "sorting"
33
+ ],
34
+ doc: "howto/crud-list.md",
35
+ seeAlso: ["uikit/list.md"],
36
+ summary: "MapoList with server-side pagination, filters, tabs, bulk actions and quick edit."
37
+ },
38
+ {
39
+ id: "crud-detail",
40
+ task: "Build a CRUD detail or edit page",
41
+ keywords: [
42
+ "MapoDetail",
43
+ "form",
44
+ "save",
45
+ "delete",
46
+ "translations",
47
+ "sidebar fields",
48
+ "patch"
49
+ ],
50
+ doc: "howto/crud-detail.md",
51
+ seeAlso: ["uikit/detail.md", "uikit/form/index.md"],
52
+ summary: "MapoDetail wired to useCrud, with body/sidebar field descriptors and save flow."
53
+ },
54
+ {
55
+ id: "standalone-form",
56
+ task: "Use the form engine outside a detail page",
57
+ keywords: [
58
+ "MapoForm",
59
+ "useMapoForm",
60
+ "standalone",
61
+ "modal",
62
+ "wizard",
63
+ "custom submit"
64
+ ],
65
+ doc: "howto/form-standalone.md",
66
+ seeAlso: ["uikit/form/composable.md"],
67
+ summary: "MapoForm / useMapoForm driven by your own state and submit handler."
68
+ },
69
+ {
70
+ id: "field-types",
71
+ task: "Pick a form field type",
72
+ keywords: [
73
+ "descriptor",
74
+ "field type",
75
+ "text",
76
+ "select",
77
+ "editor",
78
+ "repeater",
79
+ "seo",
80
+ "map",
81
+ "fks",
82
+ "m2m",
83
+ "datetime"
84
+ ],
85
+ doc: "uikit/form/add-fields.md",
86
+ seeAlso: ["uikit/form/index.md"],
87
+ summary: "Every built-in field type, the component behind it and its attrs."
88
+ },
89
+ {
90
+ id: "custom-field",
91
+ task: "Create and register a custom field type",
92
+ keywords: [
93
+ "defineFormField",
94
+ "registry",
95
+ "custom component",
96
+ "mapping",
97
+ "own field",
98
+ "extend fields"
99
+ ],
100
+ doc: "uikit/form/registry.md",
101
+ heading: "Add types globally \u2014 `defineFormField()` (recommended)",
102
+ seeAlso: ["uikit/form/custom-fields.md", "uikit/form/reusable-fields.md"],
103
+ summary: "Register a component in the field registry, then use it through descriptor.type."
104
+ },
105
+ {
106
+ id: "form-validation",
107
+ task: "Validate form fields",
108
+ keywords: [
109
+ "validate",
110
+ "validateAsync",
111
+ "required",
112
+ "errors",
113
+ "rules",
114
+ "async validation"
115
+ ],
116
+ doc: "uikit/form/validation.md",
117
+ summary: "Sync and debounced async validation on descriptors, plus error display."
118
+ },
119
+ {
120
+ id: "form-i18n",
121
+ task: "Make form fields translatable",
122
+ keywords: [
123
+ "translatable",
124
+ "synci18n",
125
+ "translations",
126
+ "languages",
127
+ "lang switch"
128
+ ],
129
+ doc: "uikit/form/i18n.md",
130
+ seeAlso: ["howto/i18n.md"],
131
+ summary: "translatable descriptors, per-language models and the detail language switcher."
132
+ },
133
+ {
134
+ id: "media-manager",
135
+ task: "Use the media manager and media fields",
136
+ keywords: [
137
+ "upload",
138
+ "image",
139
+ "gallery",
140
+ "folders",
141
+ "MapoMediaManager",
142
+ "enhanced-media",
143
+ "MapoDropArea"
144
+ ],
145
+ doc: "howto/media-manager.md",
146
+ seeAlso: ["uikit/media.md"],
147
+ summary: "Media endpoints configuration, media fields and the picker dialog."
148
+ },
149
+ {
150
+ id: "menu-manager",
151
+ task: "Build a navigation menu editor",
152
+ keywords: [
153
+ "MapoMenuManager",
154
+ "tree",
155
+ "drag and drop",
156
+ "nodes",
157
+ "navigation"
158
+ ],
159
+ doc: "howto/menu-manager.md",
160
+ seeAlso: ["uikit/menu-manager.md"],
161
+ summary: "Tree editor for menus with drag-and-drop nodes and per-node forms."
162
+ },
163
+ {
164
+ id: "i18n",
165
+ task: "Translate the admin UI",
166
+ keywords: [
167
+ "locale",
168
+ "language",
169
+ "vue-i18n",
170
+ "catalog",
171
+ "useMapoT",
172
+ "messages"
173
+ ],
174
+ doc: "howto/i18n.md",
175
+ seeAlso: ["modules/i18n.md"],
176
+ summary: "Locale setup, overriding Mapo strings and adding your own catalogs."
177
+ },
178
+ {
179
+ id: "auth-permissions",
180
+ task: "Protect routes with auth and permissions",
181
+ keywords: [
182
+ "login",
183
+ "middleware",
184
+ "roles",
185
+ "useCanAccessRoute",
186
+ "session",
187
+ "logout",
188
+ "django permissions"
189
+ ],
190
+ doc: "howto/auth-permissions.md",
191
+ seeAlso: ["uikit/login.md"],
192
+ summary: "Auth middleware, permission route meta and the Django-backed permission model."
193
+ },
194
+ {
195
+ id: "feedback",
196
+ task: "Show toasts and confirm dialogs",
197
+ keywords: [
198
+ "snackbar",
199
+ "toast",
200
+ "notification",
201
+ "confirm",
202
+ "dialog",
203
+ "alert"
204
+ ],
205
+ doc: "howto/feedback.md",
206
+ seeAlso: ["uikit/feedback.md"],
207
+ summary: "Snackbar and confirm stores, plus their root components."
208
+ },
209
+ {
210
+ id: "theming",
211
+ task: "Theme and restyle the admin",
212
+ keywords: [
213
+ "css variables",
214
+ "tailwind",
215
+ "nuxt ui",
216
+ "colors",
217
+ "dark mode",
218
+ "tokens",
219
+ "design"
220
+ ],
221
+ doc: "howto/theming.md",
222
+ seeAlso: ["uikit/theming.md"],
223
+ summary: "CSS tokens, Nuxt UI defaults and where to put the override stylesheet."
224
+ },
225
+ {
226
+ id: "override-components",
227
+ task: "Replace or extend a Mapo component",
228
+ keywords: [
229
+ "MapoOverride",
230
+ "slots",
231
+ "swap component",
232
+ "customize layout",
233
+ "topbar",
234
+ "sidebar"
235
+ ],
236
+ doc: "uikit/mapoverride.md",
237
+ seeAlso: ["uikit/layout.md"],
238
+ summary: "The MapoOverride system and the layout slots that avoid full replacements."
239
+ },
240
+ {
241
+ id: "backend-integration",
242
+ task: "Connect a custom or Django backend",
243
+ keywords: [
244
+ "api",
245
+ "endpoints",
246
+ "csrf",
247
+ "camomilla",
248
+ "drf",
249
+ "proxy",
250
+ "useCrud",
251
+ "rest"
252
+ ],
253
+ doc: "howto/backend-integration.md",
254
+ seeAlso: ["modules/camomilla.md", "modules/api.md"],
255
+ summary: "Endpoint conventions, CSRF/session handling and the camomilla integration."
256
+ },
257
+ {
258
+ id: "migration",
259
+ task: "Migrate a v1 project to v2",
260
+ keywords: ["v1", "upgrade", "legacy", "vuex", "axios", "breaking changes"],
261
+ doc: "migration/v1-to-v2.md",
262
+ summary: "What changed between Mapo v1 and v2 and how to port each piece."
263
+ }
264
+ ];
265
+ const TASK_WEIGHT = 1.5;
266
+ const KEYWORD_WEIGHT = 1;
267
+ const MATCH_THRESHOLD = 3;
268
+ const RECIPE_TERMS = RECIPES.map((recipe) => ({
269
+ recipe,
270
+ task: new Set(tokenize(recipe.task)),
271
+ keywords: new Set(tokenize(recipe.keywords.join(" ")))
272
+ }));
273
+ const DOCUMENT_FREQUENCY = /* @__PURE__ */ new Map();
274
+ for (const entry of RECIPE_TERMS) {
275
+ for (const term of /* @__PURE__ */ new Set([...entry.task, ...entry.keywords])) {
276
+ DOCUMENT_FREQUENCY.set(term, (DOCUMENT_FREQUENCY.get(term) ?? 0) + 1);
277
+ }
278
+ }
279
+ function idf(term) {
280
+ const frequency = DOCUMENT_FREQUENCY.get(term);
281
+ return frequency ? Math.log(1 + RECIPES.length / frequency) : 0;
282
+ }
283
+ export function matchRecipes(query, limit = 2) {
284
+ const queryTerms = new Set(tokenize(query));
285
+ if (!queryTerms.size) return [];
286
+ const matches = [];
287
+ for (const { recipe, task, keywords } of RECIPE_TERMS) {
288
+ let score = 0;
289
+ for (const term of queryTerms) {
290
+ if (task.has(term)) score += TASK_WEIGHT * idf(term);
291
+ else if (keywords.has(term)) score += KEYWORD_WEIGHT * idf(term);
292
+ }
293
+ if (score >= MATCH_THRESHOLD)
294
+ matches.push({ ...recipe, score: Number(score.toFixed(2)) });
295
+ }
296
+ return matches.sort((a, b) => b.score - a.score).slice(0, limit);
297
+ }
File without changes