# @mostajs/socle — fiche LLM
> Registre de modules runtime pour @mostajs : auto-découverte, résolution de dépendances, tri topologique, bootstrap.

- Version: 2.0.6 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
- Chemin: mostajs/mosta-socle · Statut audit: complet (dist/)

## RÔLE
Coeur d'orchestration du socle @mostajs. Découvre les modules @mostajs/* installés (via
leur manifeste wire.json dans node_modules), valide leurs dépendances, calcule l'ordre de
chargement (tri topologique), appelle la fonction register() de chaque module, et expose
un ModuleRegistry agrégeant schémas, permissions, rôles, menus, thèmes, routes, pages et
seeds. Fournit aussi des helpers d'intégration pour un hôte Next.js (route-handler,
page-handler, seed-runner) et l'(dé)installation programmatique de modules.
Aucune dépendance runtime — module socle pur.

## INSTALLATION
npm i @mostajs/socle

## EXPORTS
- Runtime: ModuleRegistry (classe), bootstrap, discoverModules, validateDependencies, resolveLoadOrder, getDependents
- Helpers: createCatchAllHandler, resolveModulePage, runAllSeeds, hasPermission, hasAllPermissions, hasAnyPermission
- Lib: installModule, installModules, uninstallModule
- Types: ModuleType, WireManifest, ModuleRegistration, SchemaDefinition, RepositoryFactory, PermissionDefinition, CategoryDefinition, PermissionContribution, RoleDefinition, MenuItem, MenuContribution, ThemeContribution, RouteHandler, RouteRegistration, PageRegistration, ResolvedPage, SeedDefinition, SeedContext, SeedFactory, SocleConfig, IModuleRegistry, BootstrapOptions, RegisterFunction
- Binaire: mostajs-socle (dist/cli.js)

## EXPORTS PAR SOUS-CHEMIN
- @mostajs/socle/types : tous les types ci-dessus
- @mostajs/socle/helpers/route-handler : createCatchAllHandler (catch-all API Next.js)
- @mostajs/socle/helpers/page-handler : resolveModulePage
- @mostajs/socle/helpers/seed-runner : runAllSeeds
- @mostajs/socle/helpers/permissions : hasPermission, hasAllPermissions, hasAnyPermission
- @mostajs/socle/lib/install-module : installModule, installModules
- @mostajs/socle/lib/uninstall-module : uninstallModule

## API — SIGNATURES
- bootstrap(config: SocleConfig, options?: BootstrapOptions): Promise<ModuleRegistry>
- discoverModules(rootDir: string): WireManifest[]  // scanne node_modules/@mostajs/*, trié par priorité
- validateDependencies(manifests): { valid: boolean; errors: string[] }
- resolveLoadOrder(manifests): WireManifest[]  // tri topologique, deps d'abord
- getDependents(moduleName, manifests): string[]
- createCatchAllHandler(getRegistry, options?: { checkPermission? }): (method) => (req, ctx) => Promise<Response>
- resolveModulePage(registry, path: string[]): ResolvedPage | null
- runAllSeeds(registry, context: SeedContext, options?): Promise<{ module; seeds: string[] }[]>
- hasPermission(userPerms: string[], required: string): boolean  // supporte le wildcard '*'
- installModule(name, options?: { projectRoot?; dryRun?; log? }): WireResult  // idempotent
- uninstallModule(name, options?): UnwireResult
- ModuleRegistry: register(), getSchemas(), getAllPermissions(), getAllRoles(), getAdminRole(), getAllMenuContributions(), getThemes(), resolveRoute(), getPageComponent(), getInstalledModules(), getModulesByType(), canUninstall(), markBooted(), isBooted()

## TYPES CLÉS
- ModuleType = 'platform' | 'core' | 'functional' | 'business'
- WireManifest { name; package; version; type: ModuleType; priority: number; dependencies?: string[]; register: string; displayName?; description?; icon? }
- ModuleRegistration { manifest; schemas?; repositories?; permissions?; roles?; menu?; i18n?; seeds?; routes?; pages?; themes? }
- SocleConfig { appName: string; slogan?; locale?; dbNamePrefix?; defaultPort? }
- RouteRegistration { path; handlers: { GET?/POST?/PUT?/DELETE?/PATCH? }; permission?: string | per-method map }
- PageRegistration { path; component; permission?; ssr? } ; ResolvedPage extends PageRegistration { params }
- SeedContext { getRepository(name); hashPassword(pwd); log(msg) }
- BootstrapOptions { rootDir?; log?; skipRegister?; registerFunctions?: Record<string, RegisterFunction> }

## PATTERN
```ts
import { bootstrap } from '@mostajs/socle';
const registry = await bootstrap({ appName: 'MonApp', defaultPort: 4567 });
// dans src/app/api/[...path]/route.ts :
import { createCatchAllHandler } from '@mostajs/socle/helpers/route-handler';
const handler = createCatchAllHandler(() => registry, { checkPermission });
export const GET = handler('GET'); export const POST = handler('POST'); // …
```

## DÉPEND DE
Aucun module @mostajs/* (dependencies vide). Module socle autonome ; les modules @mostajs/*
sont découverts dynamiquement à l'exécution, pas déclarés en dépendance.

## PIÈGES
- bootstrap() découvre les modules via leur fichier wire.json dans node_modules/@mostajs/* ; un module sans wire.json valide n'est pas chargé.
- Le rôle ADMIN n'est déclaré par aucun module : getAdminRole() le construit automatiquement comme l'union de TOUTES les permissions de TOUS les modules.
- Avec un bundler type Turbopack, l'import dynamique de register() casse (« expression too dynamic ») : passer registerFunctions dans BootstrapOptions pour fournir les register statiquement.
- resolveLoadOrder fait un tri topologique ; un cycle de dépendances ou une dépendance manquante est signalé par validateDependencies (valid=false).
- installModule/uninstallModule modifient les fichiers du projet hôte — idempotents, mais utiliser dryRun:true pour prévisualiser.
- hasPermission accepte le wildcard '*' = accès total ; en tenir compte dans les contrôles de sécurité.

## RÉFÉRENCES
- dist/cli.js (binaire mostajs-socle)
- templates/ (gabarits livrés avec le package)
- LICENSE
