@africode/core 5.0.11 → 5.0.13

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 (221) hide show
  1. package/AGENTS.md +585 -585
  2. package/AGENT_INSTRUCTIONS.md +595 -595
  3. package/COMPONENT_SCHEMA.json +1826 -1800
  4. package/LICENSE +623 -623
  5. package/README.md +476 -476
  6. package/bin/africode.js +73 -73
  7. package/bin/cli.ts +82 -82
  8. package/bin/create-africode.js +220 -220
  9. package/bin/scaffold.ts +218 -218
  10. package/components/accordion.js +183 -183
  11. package/components/alert.js +131 -131
  12. package/components/auth-form.js +154 -154
  13. package/components/auth.js +172 -172
  14. package/components/avatar.js +117 -117
  15. package/components/badge.js +104 -104
  16. package/components/base.d.ts +139 -139
  17. package/components/base.js +234 -234
  18. package/components/breadcrumb.js +76 -72
  19. package/components/button.js +164 -164
  20. package/components/card.js +144 -137
  21. package/components/carousel.js +32 -32
  22. package/components/cart-drawer.js +28 -28
  23. package/components/code-block.js +20 -20
  24. package/components/contact-form.js +25 -25
  25. package/components/cookie-consent.js +23 -23
  26. package/components/cta-banner.js +38 -38
  27. package/components/cultural-card.js +243 -243
  28. package/components/dashboard-activity-list.js +103 -103
  29. package/components/dashboard-card.js +85 -85
  30. package/components/dashboard-metric.js +81 -81
  31. package/components/dashboard-shell.js +85 -85
  32. package/components/dashboard-topbar.js +84 -84
  33. package/components/divider.js +83 -83
  34. package/components/dropdown.js +171 -171
  35. package/components/error-boundary.js +155 -155
  36. package/components/faq-accordion.js +23 -23
  37. package/components/feature-grid.js +85 -85
  38. package/components/file-uploader.js +22 -22
  39. package/components/filter-bar.js +19 -19
  40. package/components/footer.js +113 -113
  41. package/components/form.js +131 -131
  42. package/components/gallery.js +22 -22
  43. package/components/hero.js +140 -138
  44. package/components/icon.js +36 -36
  45. package/components/index.js +128 -128
  46. package/components/input.js +252 -256
  47. package/components/kanga-card.js +185 -185
  48. package/components/kyc-upload.js +173 -173
  49. package/components/language-switcher.js +108 -108
  50. package/components/loader.js +80 -80
  51. package/components/modal.js +262 -262
  52. package/components/motion.js +84 -84
  53. package/components/nav-drawer.js +216 -216
  54. package/components/navbar.js +243 -236
  55. package/components/newsletter-signup.js +24 -24
  56. package/components/pagination.js +31 -31
  57. package/components/pattern-showcase.js +225 -225
  58. package/components/pricing-card.js +100 -100
  59. package/components/product-card.js +41 -41
  60. package/components/progress.js +132 -134
  61. package/components/react.js +111 -111
  62. package/components/search-box.js +24 -24
  63. package/components/section.js +54 -54
  64. package/components/select.js +321 -322
  65. package/components/sidebar.js +180 -180
  66. package/components/simple-chart.js +22 -22
  67. package/components/skeleton.js +85 -85
  68. package/components/stepper.js +28 -28
  69. package/components/table.js +181 -181
  70. package/components/tabs.js +202 -202
  71. package/components/team-grid.js +23 -23
  72. package/components/testimonial.js +94 -94
  73. package/components/theme-toggle.js +82 -82
  74. package/components/toast.js +139 -139
  75. package/components/tooltip.js +167 -167
  76. package/components/transaction-ledger.js +138 -138
  77. package/components/ui-avatar.js +79 -79
  78. package/components/ui-badge.js +61 -61
  79. package/components/ui-button.js +149 -149
  80. package/components/ui-card.js +74 -75
  81. package/components/ui-chip.js +87 -87
  82. package/components/ui-input.js +110 -110
  83. package/components/ui-popover.js +84 -84
  84. package/components/ui-progress-ring.js +60 -60
  85. package/components/ui-select.js +85 -85
  86. package/components/ui-stat.js +75 -75
  87. package/components/ui-switch.js +85 -85
  88. package/components/ui-table.js +69 -69
  89. package/components/ui-tabs.js +99 -99
  90. package/components/ui-tag.js +64 -64
  91. package/components/ui-textarea.js +84 -84
  92. package/components/ui-tooltip.js +66 -66
  93. package/components/video-player.js +22 -22
  94. package/components/wallet-balance.js +114 -114
  95. package/core/a2ui-schema-manager.js +351 -351
  96. package/core/a2ui.js +696 -696
  97. package/core/actions.js +27 -27
  98. package/core/bun-runtime.js +396 -396
  99. package/core/cli/commands/add.js +23 -23
  100. package/core/cli/commands/audit.js +58 -58
  101. package/core/cli/commands/build.js +193 -193
  102. package/core/cli/commands/create-plugin.js +241 -241
  103. package/core/cli/commands/dev.js +248 -283
  104. package/core/cli/commands/lint.js +23 -23
  105. package/core/cli/commands/test.js +33 -34
  106. package/core/cli/migrator.js +71 -71
  107. package/core/cli/ui.js +56 -56
  108. package/core/compliance.js +823 -823
  109. package/core/config.js +265 -265
  110. package/core/db-advanced.js +478 -481
  111. package/core/db.js +282 -284
  112. package/core/enhanced-hmr.js +406 -406
  113. package/core/errors.js +222 -222
  114. package/core/file-router.js +47 -47
  115. package/core/hmr-client.js +203 -204
  116. package/core/hmr.js +205 -197
  117. package/core/html.d.ts +30 -30
  118. package/core/html.js +84 -84
  119. package/core/hydration.js +52 -52
  120. package/core/lipa-namba-journey.js +548 -605
  121. package/core/logging.js +14 -14
  122. package/core/middleware.js +145 -145
  123. package/core/motion.js +106 -106
  124. package/core/nida-cig-middleware.js +417 -460
  125. package/core/patterns.d.ts +124 -124
  126. package/core/patterns.js +947 -1001
  127. package/core/plugins/index.js +345 -345
  128. package/core/request-analytics.js +253 -253
  129. package/core/request-identity.js +93 -93
  130. package/core/router.js +386 -386
  131. package/core/sdk-browser.js +140 -140
  132. package/core/sdk-client.js +61 -61
  133. package/core/sdk.d.ts +133 -133
  134. package/core/sdk.js +148 -148
  135. package/core/seo.js +76 -76
  136. package/core/server/auth-endpoints.js +339 -339
  137. package/core/server/auth.js +180 -180
  138. package/core/server/csrf.js +200 -206
  139. package/core/server/db.js +39 -39
  140. package/core/server/middleware.js +324 -324
  141. package/core/server/rate-limit.js +238 -238
  142. package/core/server/render.js +67 -69
  143. package/core/server/router.js +23 -11
  144. package/core/session-store.js +68 -68
  145. package/core/shim.js +28 -28
  146. package/core/state.d.ts +86 -86
  147. package/core/state.js +276 -276
  148. package/core/store.d.ts +122 -122
  149. package/core/store.js +61 -61
  150. package/core/validation.d.ts +232 -232
  151. package/core/validation.js +602 -602
  152. package/core/websocket.js +656 -641
  153. package/dist/africode.js +233 -230
  154. package/dist/africode.js.map +83 -83
  155. package/dist/build-info.json +3 -3
  156. package/dist/components.js +195 -192
  157. package/dist/components.js.map +73 -73
  158. package/dist/styles/africanity.css +321 -321
  159. package/dist/styles/typography.css +140 -140
  160. package/docs/IDE-Guide.md +50 -50
  161. package/package.json +113 -113
  162. package/scripts/generate-component-schema.js +82 -79
  163. package/styles/africanity.css +321 -321
  164. package/styles/typography.css +140 -140
  165. package/templates/starter/.env.example +15 -15
  166. package/templates/starter/africode.config.js +40 -40
  167. package/templates/starter/package.json +13 -13
  168. package/templates/starter/src/index.js +18 -18
  169. package/templates/starter/src/pages/index.html +55 -55
  170. package/templates/starter/src/pages/index.js +17 -17
  171. package/templates/starter/src/styles/main.css +3 -3
  172. package/templates/starter-3d/.env.example +7 -7
  173. package/templates/starter-3d/africode.config.js +29 -29
  174. package/templates/starter-3d/components/af-model-viewer.js +125 -125
  175. package/templates/starter-3d/package.json +14 -14
  176. package/templates/starter-3d/src/pages/index.html +55 -55
  177. package/templates/starter-3d/src/pages/index.js +50 -50
  178. package/templates/starter-3d/src/styles/main.css +3 -3
  179. package/templates/starter-dashboard/.env.example +21 -21
  180. package/templates/starter-dashboard/africode.config.js +20 -20
  181. package/templates/starter-dashboard/package.json +14 -14
  182. package/templates/starter-dashboard/src/index.js +17 -17
  183. package/templates/starter-dashboard/src/pages/api/analytics.js +24 -24
  184. package/templates/starter-dashboard/src/pages/index.html +118 -118
  185. package/templates/starter-dashboard/src/pages/index.js +110 -110
  186. package/templates/starter-dashboard/src/styles/main.css +172 -172
  187. package/templates/starter-fintech/.env.example +28 -28
  188. package/templates/starter-fintech/africode.config.js +20 -20
  189. package/templates/starter-fintech/package.json +15 -15
  190. package/templates/starter-fintech/src/index.js +17 -17
  191. package/templates/starter-fintech/src/pages/api/auth.js +45 -45
  192. package/templates/starter-fintech/src/pages/api/transfer.js +65 -65
  193. package/templates/starter-fintech/src/pages/api/wallet.js +39 -39
  194. package/templates/starter-fintech/src/pages/api/webhooks/payment.js +32 -32
  195. package/templates/starter-fintech/src/pages/index.html +169 -169
  196. package/templates/starter-fintech/src/pages/index.js +161 -161
  197. package/templates/starter-fintech/src/styles/main.css +246 -246
  198. package/templates/starter-react/.env.example +15 -15
  199. package/templates/starter-react/africode.config.js +40 -40
  200. package/templates/starter-react/package.json +15 -15
  201. package/templates/starter-react/src/pages/index.html +55 -55
  202. package/templates/starter-react/src/pages/index.js +68 -68
  203. package/templates/starter-react/src/styles/main.css +3 -3
  204. package/templates/starter-tailwind/.env.example +15 -15
  205. package/templates/starter-tailwind/africode.config.js +40 -40
  206. package/templates/starter-tailwind/package.json +19 -19
  207. package/templates/starter-tailwind/src/pages/index.html +55 -55
  208. package/templates/starter-tailwind/src/pages/index.js +67 -67
  209. package/templates/starter-tailwind/src/styles/main.css +3 -3
  210. package/templates/starter-tailwind/src/styles/tailwind.css +1 -1
  211. package/templates/starter-tailwind/src/tailwind-loader.js +30 -30
  212. package/templates/starter-tailwind/tailwind.config.cjs +18 -18
  213. package/templates/starter-website/.env.example +18 -18
  214. package/templates/starter-website/africode.config.js +20 -20
  215. package/templates/starter-website/package.json +14 -14
  216. package/templates/starter-website/src/index.js +17 -17
  217. package/templates/starter-website/src/pages/index.html +124 -124
  218. package/templates/starter-website/src/pages/index.js +116 -116
  219. package/templates/starter-website/src/styles/main.css +195 -195
  220. package/bin/africode.js.1758507140 +0 -343
  221. package/core/heartbeat.js +0 -64
@@ -1,345 +1,345 @@
1
- /**
2
- * AfriCode Plugin Registry
3
- *
4
- * A minimal, strict, and predictable plug-in architecture for the AfriCode Framework.
5
- * Employs deterministic execution, strong boundary isolation, and a stable context
6
- * contract to prevent ecosystem bloat and ensure framework resilience.
7
- */
8
-
9
- // Core framework version to check plugin compatibility
10
- export const AFRICODE_VERSION = '5.0.0';
11
-
12
- // Only these specific hooks are permitted in v1
13
- export const ALLOWED_HOOKS = new Set([
14
- 'onConfigLoad',
15
- 'onComponentRegister',
16
- 'onRouteRegister',
17
- 'onStateInit',
18
- 'onServerStart',
19
- 'onRequest',
20
- 'onResponse',
21
- 'onError',
22
- 'onCliCommandRegister',
23
- ]);
24
-
25
- // Protected core CLI commands that plugins cannot overwrite
26
- const PROTECTED_CLI_COMMANDS = new Set([
27
- 'dev',
28
- 'build',
29
- 'start',
30
- 'test',
31
- 'lint',
32
- 'audit',
33
- 'add',
34
- 'migrate',
35
- 'create',
36
- 'help',
37
- ]);
38
-
39
- export class AfriPluginRegistry {
40
- constructor(options = {}) {
41
- this.plugins = new Map();
42
- // Mode mapping: safe (swallow errors), strict (propagate crashes immediately)
43
- this.mode = options.mode || 'safe';
44
-
45
- // Plugin state tracking
46
- this.disabledPlugins = new Set();
47
-
48
- // Internal structured store for deterministic hook execution (arrays maintain registration order)
49
- this.hooks = {
50
- onConfigLoad: [],
51
- onComponentRegister: [],
52
- onRouteRegister: [],
53
- onStateInit: [],
54
- onServerStart: [],
55
- onRequest: [],
56
- onResponse: [],
57
- onError: [],
58
- onCliCommandRegister: [],
59
- };
60
-
61
- // Store plugin-registered CLI commands
62
- this.pluginCommands = new Map();
63
- }
64
-
65
- /**
66
- * Registers a new plugin into the framework.
67
- * @param {Object} manifest - The Plugin manifest
68
- * @param {Object} hooks - The hooks implementation
69
- */
70
- register(manifest, hooks) {
71
- this._validateManifest(manifest);
72
- this._validateCompatibility(manifest.compatibleWith);
73
- this._validateHooks(manifest.name, hooks);
74
-
75
- if (this.plugins.has(manifest.name)) {
76
- console.warn(`[AfriCode Plugin] Plugin '${manifest.name}' is already registered. Skipping.`);
77
- return;
78
- }
79
-
80
- this.plugins.set(manifest.name, manifest);
81
-
82
- // Bind hooks into the deterministic execution pipeline
83
- for (const [hookName, handler] of Object.entries(hooks)) {
84
- this.hooks[hookName].push({
85
- pluginName: manifest.name,
86
- handler,
87
- });
88
- }
89
-
90
- // Observability Hook
91
- this._logObservability('onPluginLoad', manifest.name, `Registered v${manifest.version}`);
92
- }
93
-
94
- /**
95
- * Disable a plugin at runtime. Safely ejects it from the pipeline.
96
- */
97
- disable(pluginName) {
98
- if (!this.plugins.has(pluginName)) {
99
- return;
100
- }
101
- this.disabledPlugins.add(pluginName);
102
- this._logObservability('onPluginDisable', pluginName, 'Plugin forcefully disabled.');
103
- }
104
-
105
- /**
106
- * Enable a previously disabled plugin.
107
- */
108
- enable(pluginName) {
109
- this.disabledPlugins.delete(pluginName);
110
- }
111
-
112
- /**
113
- * Returns a stable, public snapshot of the plugin registry for docs/debugging.
114
- */
115
- getSnapshot() {
116
- return {
117
- frameworkVersion: AFRICODE_VERSION,
118
- mode: this.mode,
119
- plugins: [...this.plugins.values()].map((manifest) => ({
120
- name: manifest.name,
121
- version: manifest.version,
122
- compatibleWith: manifest.compatibleWith,
123
- hooks: Array.isArray(manifest.hooks) ? [...manifest.hooks] : [],
124
- disabled: this.disabledPlugins.has(manifest.name)
125
- })),
126
- allowedHooks: [...ALLOWED_HOOKS],
127
- protectedCliCommands: [...PROTECTED_CLI_COMMANDS]
128
- };
129
- }
130
-
131
- /**
132
- * Returns the canonical plugin lifecycle description.
133
- */
134
- getLifecycleGuide() {
135
- return [
136
- { step: 'manifest', description: 'Validate name, version, and compatibleWith.' },
137
- { step: 'hooks', description: 'Allow only approved hook names and function handlers.' },
138
- { step: 'register', description: 'Bind hooks in registration order.' },
139
- { step: 'emit', description: 'Execute with a restricted stable context.' },
140
- { step: 'disable', description: 'Skip disabled plugins without mutating the rest.' },
141
- { step: 'strict-mode', description: 'Propagate failures immediately when configured.' }
142
- ];
143
- }
144
-
145
- /**
146
- * Execute a specific hook safely across all registered plugins in registration order.
147
- * @param {string} hookName - The name of the hook to trigger
148
- * @param {Object} context - A stable execution context exposed to plugins
149
- */
150
- async emit(hookName, context = {}) {
151
- if (!ALLOWED_HOOKS.has(hookName)) {
152
- throw new Error(`[AfriCode Plugin] Attempted to emit unknown hook: ${hookName}`);
153
- }
154
-
155
- const handlers = this.hooks[hookName];
156
- if (!handlers || handlers.length === 0) {
157
- return context;
158
- }
159
-
160
- // Clone context defensively to prevent deep framework mutation
161
- // but allow mutations on specifically designed properties.
162
- const stableContext = this._buildStableContext(hookName, context);
163
-
164
- for (const { pluginName, handler } of handlers) {
165
- if (this.disabledPlugins.has(pluginName)) {
166
- continue;
167
- } // Skip disabled plugins
168
-
169
- const hookPromise = async () => {
170
- const startTime = performance.now();
171
- await handler(stableContext);
172
- const latency = performance.now() - startTime;
173
-
174
- // Deep trace for heavy hooks taking >50ms
175
- if (latency > 50) {
176
- this._logObservability(
177
- 'onHookComplete',
178
- pluginName,
179
- `Hook ${hookName} resolved in ${latency.toFixed(2)}ms`
180
- );
181
- }
182
- };
183
-
184
- const timeoutPromise = new Promise((_, reject) =>
185
- setTimeout(() => reject(new Error(`[Timeout] Plugin Execution exceeded 200ms`)), 200)
186
- );
187
-
188
- try {
189
- // Execution Guarantee: Plugin must resolve within 200ms boundary
190
- await Promise.race([hookPromise(), timeoutPromise]);
191
- } catch (error) {
192
- this._logObservability(
193
- 'onPluginError',
194
- pluginName,
195
- `Failed during '${hookName}': ${error.message}`
196
- );
197
-
198
- // Isolation Policy: Bubble crash explicitly if registry runs in 'strict' mode
199
- if (this.mode === 'strict') {
200
- throw error;
201
- }
202
-
203
- // Safe mode: Prevent crash mapping downstream
204
- if (hookName !== 'onError') {
205
- await this.emit('onError', {
206
- error,
207
- source: `plugin:${pluginName}`,
208
- hook: hookName,
209
- });
210
- }
211
- }
212
- }
213
-
214
- return stableContext;
215
- }
216
-
217
- /**
218
- * Internal observability tracking logger to format structured output guarantees
219
- */
220
- _logObservability(event, pluginName, metadata) {
221
- const timestamp = new Date().toISOString();
222
- console.log(
223
- `[AfriCode Observability] ${timestamp} | EVENT: ${event} | PLUGIN: ${pluginName} | ${metadata}`
224
- );
225
- }
226
-
227
- /**
228
- * Validates the schema of a plugin manifest.
229
- */
230
- _validateManifest(manifest) {
231
- if (!manifest || typeof manifest !== 'object') {
232
- throw new Error('[AfriCode Plugin] Plugin manifest must be a valid object.');
233
- }
234
- if (!manifest.name || typeof manifest.name !== 'string') {
235
- throw new Error("[AfriCode Plugin] Plugin manifest is missing a valid 'name' property.");
236
- }
237
- if (!manifest.version || typeof manifest.version !== 'string') {
238
- throw new Error(
239
- `[AfriCode Plugin: ${manifest.name}] Manifest is missing a valid 'version' property.`
240
- );
241
- }
242
- if (!manifest.compatibleWith) {
243
- throw new Error(
244
- `[AfriCode Plugin: ${manifest.name}] Manifest is missing 'compatibleWith' boundary property.`
245
- );
246
- }
247
- }
248
-
249
- /**
250
- * Optional lightweight boundary check against standard semantic mapping.
251
- */
252
- _validateCompatibility(compatibleWith) {
253
- // In a full production scenario, use a semantic versioning library.
254
- // For v1, we provide a structured warning if versions mismatched wildly.
255
- if (typeof compatibleWith !== 'string') {
256
- return;
257
- }
258
-
259
- // Very basic extraction of major version target (e.g., ^2.0.0 or ~3.0.0)
260
- const targetMajor = compatibleWith.match(/\d+/)?.[0];
261
- const currentMajor = AFRICODE_VERSION.split('.')[0];
262
-
263
- if (targetMajor && targetMajor !== currentMajor) {
264
- console.warn(
265
- `[AfriCode Plugin Warning] Plugin requires compatibility '${compatibleWith}' but framework is v${AFRICODE_VERSION}. Unexpected behavior may occur.`
266
- );
267
- }
268
- }
269
-
270
- /**
271
- * Ensures plugins only utilize globally permitted v1 hooks.
272
- */
273
- _validateHooks(pluginName, hooks) {
274
- if (!hooks || typeof hooks !== 'object') {
275
- throw new Error(`[AfriCode Plugin: ${pluginName}] Hooks object is missing or invalid.`);
276
- }
277
-
278
- for (const hookName of Object.keys(hooks)) {
279
- if (!ALLOWED_HOOKS.has(hookName)) {
280
- throw new Error(
281
- `[AfriCode Plugin: ${pluginName}] Invalid hook attempt: '${hookName}'. Authorized hooks are explicitly scoped.`
282
- );
283
- }
284
- if (typeof hooks[hookName] !== 'function') {
285
- throw new Error(`[AfriCode Plugin: ${pluginName}] Hook '${hookName}' must be a function.`);
286
- }
287
- }
288
- }
289
-
290
- /**
291
- * Scopes the contextual payload based on the specific hook type.
292
- * Prevents plugins from pulling down random core internals.
293
- */
294
- _buildStableContext(hookName, payload = {}) {
295
- switch (hookName) {
296
- case 'onCliCommandRegister':
297
- return {
298
- // Safe command registration mechanism
299
- registerCommand: (commandName, commandHandler) => {
300
- if (PROTECTED_CLI_COMMANDS.has(commandName)) {
301
- console.warn(
302
- `[AfriCode Plugin] Refused to overwrite core framework CLI command: '${commandName}'.`
303
- );
304
- return false;
305
- }
306
- this.pluginCommands.set(commandName, commandHandler);
307
- return true;
308
- },
309
- };
310
- case 'onRouteRegister':
311
- return {
312
- addRoute: payload.addRoute, // The framework passes a strict routing interface
313
- router: payload.router,
314
- };
315
- case 'onServerStart':
316
- return { port: payload.port };
317
- case 'onStateInit':
318
- return { store: payload.store };
319
- case 'onComponentRegister':
320
- return { componentName: payload.name, componentClass: payload.component };
321
- case 'onRequest':
322
- case 'onResponse':
323
- // Plugins receive specific restricted request/response maps
324
- return { req: payload.req, res: payload.res, meta: payload.meta || {} };
325
- case 'onError':
326
- return { error: payload.error, source: payload.source };
327
- case 'onConfigLoad': {
328
- // Security Hardening: Never dump RAW process.env unconditionally
329
- // Mask sensitive keys by delivering a tailored subset mapping.
330
- const env = typeof process !== 'undefined' ? process.env : {};
331
- const safeEnvSubset = {
332
- NODE_ENV: env.NODE_ENV || 'development',
333
- PORT: env.PORT || 3000,
334
- // Blacklist database IPs, JWT secrets, Stripe Keys from rogue downstream plugins
335
- };
336
- return { config: payload.config, env: safeEnvSubset };
337
- }
338
- default:
339
- return payload;
340
- }
341
- }
342
- }
343
-
344
- // Global static registry instance for core
345
- export const registry = new AfriPluginRegistry();
1
+ /**
2
+ * AfriCode Plugin Registry
3
+ *
4
+ * A minimal, strict, and predictable plug-in architecture for the AfriCode Framework.
5
+ * Employs deterministic execution, strong boundary isolation, and a stable context
6
+ * contract to prevent ecosystem bloat and ensure framework resilience.
7
+ */
8
+
9
+ // Core framework version to check plugin compatibility
10
+ export const AFRICODE_VERSION = '5.0.0';
11
+
12
+ // Only these specific hooks are permitted in v1
13
+ export const ALLOWED_HOOKS = new Set([
14
+ 'onConfigLoad',
15
+ 'onComponentRegister',
16
+ 'onRouteRegister',
17
+ 'onStateInit',
18
+ 'onServerStart',
19
+ 'onRequest',
20
+ 'onResponse',
21
+ 'onError',
22
+ 'onCliCommandRegister',
23
+ ]);
24
+
25
+ // Protected core CLI commands that plugins cannot overwrite
26
+ const PROTECTED_CLI_COMMANDS = new Set([
27
+ 'dev',
28
+ 'build',
29
+ 'start',
30
+ 'test',
31
+ 'lint',
32
+ 'audit',
33
+ 'add',
34
+ 'migrate',
35
+ 'create',
36
+ 'help',
37
+ ]);
38
+
39
+ export class AfriPluginRegistry {
40
+ constructor(options = {}) {
41
+ this.plugins = new Map();
42
+ // Mode mapping: safe (swallow errors), strict (propagate crashes immediately)
43
+ this.mode = options.mode || 'safe';
44
+
45
+ // Plugin state tracking
46
+ this.disabledPlugins = new Set();
47
+
48
+ // Internal structured store for deterministic hook execution (arrays maintain registration order)
49
+ this.hooks = {
50
+ onConfigLoad: [],
51
+ onComponentRegister: [],
52
+ onRouteRegister: [],
53
+ onStateInit: [],
54
+ onServerStart: [],
55
+ onRequest: [],
56
+ onResponse: [],
57
+ onError: [],
58
+ onCliCommandRegister: [],
59
+ };
60
+
61
+ // Store plugin-registered CLI commands
62
+ this.pluginCommands = new Map();
63
+ }
64
+
65
+ /**
66
+ * Registers a new plugin into the framework.
67
+ * @param {Object} manifest - The Plugin manifest
68
+ * @param {Object} hooks - The hooks implementation
69
+ */
70
+ register(manifest, hooks) {
71
+ this._validateManifest(manifest);
72
+ this._validateCompatibility(manifest.compatibleWith);
73
+ this._validateHooks(manifest.name, hooks);
74
+
75
+ if (this.plugins.has(manifest.name)) {
76
+ console.warn(`[AfriCode Plugin] Plugin '${manifest.name}' is already registered. Skipping.`);
77
+ return;
78
+ }
79
+
80
+ this.plugins.set(manifest.name, manifest);
81
+
82
+ // Bind hooks into the deterministic execution pipeline
83
+ for (const [hookName, handler] of Object.entries(hooks)) {
84
+ this.hooks[hookName].push({
85
+ pluginName: manifest.name,
86
+ handler,
87
+ });
88
+ }
89
+
90
+ // Observability Hook
91
+ this._logObservability('onPluginLoad', manifest.name, `Registered v${manifest.version}`);
92
+ }
93
+
94
+ /**
95
+ * Disable a plugin at runtime. Safely ejects it from the pipeline.
96
+ */
97
+ disable(pluginName) {
98
+ if (!this.plugins.has(pluginName)) {
99
+ return;
100
+ }
101
+ this.disabledPlugins.add(pluginName);
102
+ this._logObservability('onPluginDisable', pluginName, 'Plugin forcefully disabled.');
103
+ }
104
+
105
+ /**
106
+ * Enable a previously disabled plugin.
107
+ */
108
+ enable(pluginName) {
109
+ this.disabledPlugins.delete(pluginName);
110
+ }
111
+
112
+ /**
113
+ * Returns a stable, public snapshot of the plugin registry for docs/debugging.
114
+ */
115
+ getSnapshot() {
116
+ return {
117
+ frameworkVersion: AFRICODE_VERSION,
118
+ mode: this.mode,
119
+ plugins: [...this.plugins.values()].map((manifest) => ({
120
+ name: manifest.name,
121
+ version: manifest.version,
122
+ compatibleWith: manifest.compatibleWith,
123
+ hooks: Array.isArray(manifest.hooks) ? [...manifest.hooks] : [],
124
+ disabled: this.disabledPlugins.has(manifest.name)
125
+ })),
126
+ allowedHooks: [...ALLOWED_HOOKS],
127
+ protectedCliCommands: [...PROTECTED_CLI_COMMANDS]
128
+ };
129
+ }
130
+
131
+ /**
132
+ * Returns the canonical plugin lifecycle description.
133
+ */
134
+ getLifecycleGuide() {
135
+ return [
136
+ { step: 'manifest', description: 'Validate name, version, and compatibleWith.' },
137
+ { step: 'hooks', description: 'Allow only approved hook names and function handlers.' },
138
+ { step: 'register', description: 'Bind hooks in registration order.' },
139
+ { step: 'emit', description: 'Execute with a restricted stable context.' },
140
+ { step: 'disable', description: 'Skip disabled plugins without mutating the rest.' },
141
+ { step: 'strict-mode', description: 'Propagate failures immediately when configured.' }
142
+ ];
143
+ }
144
+
145
+ /**
146
+ * Execute a specific hook safely across all registered plugins in registration order.
147
+ * @param {string} hookName - The name of the hook to trigger
148
+ * @param {Object} context - A stable execution context exposed to plugins
149
+ */
150
+ async emit(hookName, context = {}) {
151
+ if (!ALLOWED_HOOKS.has(hookName)) {
152
+ throw new Error(`[AfriCode Plugin] Attempted to emit unknown hook: ${hookName}`);
153
+ }
154
+
155
+ const handlers = this.hooks[hookName];
156
+ if (!handlers || handlers.length === 0) {
157
+ return context;
158
+ }
159
+
160
+ // Clone context defensively to prevent deep framework mutation
161
+ // but allow mutations on specifically designed properties.
162
+ const stableContext = this._buildStableContext(hookName, context);
163
+
164
+ for (const { pluginName, handler } of handlers) {
165
+ if (this.disabledPlugins.has(pluginName)) {
166
+ continue;
167
+ } // Skip disabled plugins
168
+
169
+ const hookPromise = async () => {
170
+ const startTime = performance.now();
171
+ await handler(stableContext);
172
+ const latency = performance.now() - startTime;
173
+
174
+ // Deep trace for heavy hooks taking >50ms
175
+ if (latency > 50) {
176
+ this._logObservability(
177
+ 'onHookComplete',
178
+ pluginName,
179
+ `Hook ${hookName} resolved in ${latency.toFixed(2)}ms`
180
+ );
181
+ }
182
+ };
183
+
184
+ const timeoutPromise = new Promise((_, reject) =>
185
+ setTimeout(() => reject(new Error(`[Timeout] Plugin Execution exceeded 200ms`)), 200)
186
+ );
187
+
188
+ try {
189
+ // Execution Guarantee: Plugin must resolve within 200ms boundary
190
+ await Promise.race([hookPromise(), timeoutPromise]);
191
+ } catch (error) {
192
+ this._logObservability(
193
+ 'onPluginError',
194
+ pluginName,
195
+ `Failed during '${hookName}': ${error.message}`
196
+ );
197
+
198
+ // Isolation Policy: Bubble crash explicitly if registry runs in 'strict' mode
199
+ if (this.mode === 'strict') {
200
+ throw error;
201
+ }
202
+
203
+ // Safe mode: Prevent crash mapping downstream
204
+ if (hookName !== 'onError') {
205
+ await this.emit('onError', {
206
+ error,
207
+ source: `plugin:${pluginName}`,
208
+ hook: hookName,
209
+ });
210
+ }
211
+ }
212
+ }
213
+
214
+ return stableContext;
215
+ }
216
+
217
+ /**
218
+ * Internal observability tracking logger to format structured output guarantees
219
+ */
220
+ _logObservability(event, pluginName, metadata) {
221
+ const timestamp = new Date().toISOString();
222
+ console.log(
223
+ `[AfriCode Observability] ${timestamp} | EVENT: ${event} | PLUGIN: ${pluginName} | ${metadata}`
224
+ );
225
+ }
226
+
227
+ /**
228
+ * Validates the schema of a plugin manifest.
229
+ */
230
+ _validateManifest(manifest) {
231
+ if (!manifest || typeof manifest !== 'object') {
232
+ throw new Error('[AfriCode Plugin] Plugin manifest must be a valid object.');
233
+ }
234
+ if (!manifest.name || typeof manifest.name !== 'string') {
235
+ throw new Error("[AfriCode Plugin] Plugin manifest is missing a valid 'name' property.");
236
+ }
237
+ if (!manifest.version || typeof manifest.version !== 'string') {
238
+ throw new Error(
239
+ `[AfriCode Plugin: ${manifest.name}] Manifest is missing a valid 'version' property.`
240
+ );
241
+ }
242
+ if (!manifest.compatibleWith) {
243
+ throw new Error(
244
+ `[AfriCode Plugin: ${manifest.name}] Manifest is missing 'compatibleWith' boundary property.`
245
+ );
246
+ }
247
+ }
248
+
249
+ /**
250
+ * Optional lightweight boundary check against standard semantic mapping.
251
+ */
252
+ _validateCompatibility(compatibleWith) {
253
+ // In a full production scenario, use a semantic versioning library.
254
+ // For v1, we provide a structured warning if versions mismatched wildly.
255
+ if (typeof compatibleWith !== 'string') {
256
+ return;
257
+ }
258
+
259
+ // Very basic extraction of major version target (e.g., ^2.0.0 or ~3.0.0)
260
+ const targetMajor = compatibleWith.match(/\d+/)?.[0];
261
+ const currentMajor = AFRICODE_VERSION.split('.')[0];
262
+
263
+ if (targetMajor && targetMajor !== currentMajor) {
264
+ console.warn(
265
+ `[AfriCode Plugin Warning] Plugin requires compatibility '${compatibleWith}' but framework is v${AFRICODE_VERSION}. Unexpected behavior may occur.`
266
+ );
267
+ }
268
+ }
269
+
270
+ /**
271
+ * Ensures plugins only utilize globally permitted v1 hooks.
272
+ */
273
+ _validateHooks(pluginName, hooks) {
274
+ if (!hooks || typeof hooks !== 'object') {
275
+ throw new Error(`[AfriCode Plugin: ${pluginName}] Hooks object is missing or invalid.`);
276
+ }
277
+
278
+ for (const hookName of Object.keys(hooks)) {
279
+ if (!ALLOWED_HOOKS.has(hookName)) {
280
+ throw new Error(
281
+ `[AfriCode Plugin: ${pluginName}] Invalid hook attempt: '${hookName}'. Authorized hooks are explicitly scoped.`
282
+ );
283
+ }
284
+ if (typeof hooks[hookName] !== 'function') {
285
+ throw new Error(`[AfriCode Plugin: ${pluginName}] Hook '${hookName}' must be a function.`);
286
+ }
287
+ }
288
+ }
289
+
290
+ /**
291
+ * Scopes the contextual payload based on the specific hook type.
292
+ * Prevents plugins from pulling down random core internals.
293
+ */
294
+ _buildStableContext(hookName, payload = {}) {
295
+ switch (hookName) {
296
+ case 'onCliCommandRegister':
297
+ return {
298
+ // Safe command registration mechanism
299
+ registerCommand: (commandName, commandHandler) => {
300
+ if (PROTECTED_CLI_COMMANDS.has(commandName)) {
301
+ console.warn(
302
+ `[AfriCode Plugin] Refused to overwrite core framework CLI command: '${commandName}'.`
303
+ );
304
+ return false;
305
+ }
306
+ this.pluginCommands.set(commandName, commandHandler);
307
+ return true;
308
+ },
309
+ };
310
+ case 'onRouteRegister':
311
+ return {
312
+ addRoute: payload.addRoute, // The framework passes a strict routing interface
313
+ router: payload.router,
314
+ };
315
+ case 'onServerStart':
316
+ return { port: payload.port };
317
+ case 'onStateInit':
318
+ return { store: payload.store };
319
+ case 'onComponentRegister':
320
+ return { componentName: payload.name, componentClass: payload.component };
321
+ case 'onRequest':
322
+ case 'onResponse':
323
+ // Plugins receive specific restricted request/response maps
324
+ return { req: payload.req, res: payload.res, meta: payload.meta || {} };
325
+ case 'onError':
326
+ return { error: payload.error, source: payload.source };
327
+ case 'onConfigLoad': {
328
+ // Security Hardening: Never dump RAW process.env unconditionally
329
+ // Mask sensitive keys by delivering a tailored subset mapping.
330
+ const env = typeof process !== 'undefined' ? process.env : {};
331
+ const safeEnvSubset = {
332
+ NODE_ENV: env.NODE_ENV || 'development',
333
+ PORT: env.PORT || 3000,
334
+ // Blacklist database IPs, JWT secrets, Stripe Keys from rogue downstream plugins
335
+ };
336
+ return { config: payload.config, env: safeEnvSubset };
337
+ }
338
+ default:
339
+ return payload;
340
+ }
341
+ }
342
+ }
343
+
344
+ // Global static registry instance for core
345
+ export const registry = new AfriPluginRegistry();