agentic-api 1.0.6 → 2.0.26

package/dist/src/rules/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types';
+export * from './types.ctrl';
+export * from './types.helpers';
+export * from './errors';
+export * from './utils.slug';
+export * from './utils.matter';
+export * from './git/index';
+export * from './messages';

package/dist/src/rules/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Export des API du dossier rules depuis agentic-server
+__exportStar(require("./types"), exports);
+__exportStar(require("./types.ctrl"), exports);
+__exportStar(require("./types.helpers"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./utils.slug"), exports);
+__exportStar(require("./utils.matter"), exports);
+__exportStar(require("./git/index"), exports);
+__exportStar(require("./messages"), exports);

package/dist/src/rules/messages.d.ts

@@ -0,0 +1,17 @@
+export declare const i18nRules: {
+    git_repo_path_not_set: string;
+    git_config_incomplete: string;
+    markdown_lint_issues: string;
+    writer_lint_warning: (slug: string) => string;
+    commit_message_update: (slug: string) => string;
+    writer_save_success: (slug: string, branch: string) => string;
+    writer_save_error_console: (slug: string) => string;
+    writer_save_error_user: (slug: string, errorMsg: string) => string;
+    publish_success: (mainBranch: string, tag: string) => string;
+    publish_error_console: string;
+    generic_server_error_publish: (errorMsg: string) => string;
+    manager_publication_success: string;
+    manager_publication_error_console: string;
+    reader_file_not_found_console: (slug: string, branch: string, path: string) => string;
+    reader_load_error_console: (slug: string, branch: string) => string;
+};

package/dist/src/rules/messages.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.i18nRules = void 0;
+exports.i18nRules = {
+    git_repo_path_not_set: 'Configuration error: GIT_REPO_PATH environment variable is not set.',
+    git_config_incomplete: 'Configuration Git incomplète: une ou plusieurs variables d\'environnement requises (GIT_REPO_PATH, DEFAULT_BRANCH_DRAFT, DEFAULT_BRANCH_MAIN) sont manquantes.',
+    markdown_lint_issues: 'Le contenu Markdown contient des problèmes de linting.',
+    writer_lint_warning: (slug) => `Service writer: Le contenu pour '${slug}' contient des problèmes de linting.`,
+    commit_message_update: (slug) => `docs(${slug}): update`,
+    writer_save_success: (slug, branch) => `Document '${slug}' sauvegardé et commit sur la branche '${branch}'.`,
+    writer_save_error_console: (slug) => `Service writer: Erreur lors de la sauvegarde du document '${slug}':`,
+    writer_save_error_user: (slug, errorMsg) => `Erreur serveur lors de la sauvegarde de ${slug}: ${errorMsg}`,
+    publish_success: (mainBranch, tag) => `Publication terminée: branche ${mainBranch} mise à jour et tag ${tag} créé et poussé.`,
+    publish_error_console: 'Service content/writer (publishGitChanges): Erreur lors de la publication:',
+    generic_server_error_publish: (errorMsg) => `Erreur serveur lors de la publication: ${errorMsg}`,
+    manager_publication_success: 'Publication réussie: La branche main a été mise à jour et l\'index de recherche reconstruit.',
+    manager_publication_error_console: 'Service publication manager: Erreur lors du processus de publication:',
+    // ADDED: Messages for reader.ts
+    reader_file_not_found_console: (slug, branch, path) => `Service reader: Fichier non trouvé pour slug '${slug}' sur la branche '${branch}'. Relatif: '${path}'.`,
+    reader_load_error_console: (slug, branch) => `Service reader: Erreur lors du chargement du fichier pour slug '${slug}' sur la branche '${branch}':`,
+};

package/dist/src/rules/types.ctrl.d.ts

@@ -0,0 +1,28 @@
+export interface RulesLintDiagnostic {
+    line: number | undefined;
+    column: number | undefined;
+    message: string;
+    rule: string | undefined;
+    source?: string | undefined;
+    fatal?: boolean | null | undefined;
+}
+export interface RulesTextlintMessage {
+    line: number;
+    column: number;
+    message: string;
+    ruleId: string;
+}
+export interface RulesTextlintResult {
+    messages: RulesTextlintMessage[];
+}
+export interface RulesSaveResult {
+    success: boolean;
+    message: string;
+    diagnostics?: RulesLintDiagnostic[];
+    commit?: string;
+}
+export interface RulesPublicationResult {
+    success: boolean;
+    message: string;
+    tag?: string;
+}

package/dist/src/rules/types.ctrl.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/rules/types.d.ts

@@ -0,0 +1,510 @@
+import { MergeConflict, MergeResult, SimpleGit } from 'simple-git';
+/**
+ * @fileoverview Types et interfaces pour le système de gestion des règles métier
+ *
+ * Ce fichier définit tous les types TypeScript utilisés dans le workflow de gestion
+ * des règles, depuis les types de haut niveau (Rules, PR) jusqu'aux types Git de bas niveau.
+ */
+/**
+ * Énumération des statuts possibles d'une règle dans le workflow
+ *
+ * Le statut d'une règle reflète sa position dans le processus de validation
+ * et de publication, basé sur la branche Git où elle se trouve.
+ *
+ * @enum {string}
+ */
+export declare enum RuleStatus {
+    /** Règle publiée et officielle (branche main) */
+    PUBLISHED = "published",
+    /** Règle en cours d'édition (branche editor/draft) */
+    EDITING = "editing",
+    /** Règle en cours de validation via pull request (branche validation) */
+    PULLREQUEST = "pullrequest",
+    /** Règle candidate pour une release (branche release) */
+    RELEASE_CANDIDATE = "candidate",
+    /** Règle en correction urgente (branche hotfix) */
+    HOTFIX = "hotfix",
+    /** Nouvelle règle non encore trackée par Git (fichier local) */
+    NEW = "new"
+}
+/**
+ * Représente un utilisateur dans le système de gestion des règles
+ *
+ * Cette interface est utilisée pour identifier les auteurs, validateurs
+ * et autres acteurs des opérations sur les règles.
+ */
+export interface RuleUser {
+    /** Nom complet de l'utilisateur */
+    name: string;
+    /** Adresse email unique de l'utilisateur */
+    email: string;
+    /** Rôle optionnel dans l'organisation (ex: "validator", "admin") */
+    role?: string;
+}
+/**
+ * Interface de base pour une règle avec informations minimales
+ *
+ * Contient les propriétés essentielles pour identifier et localiser
+ * une règle dans le système Git.
+ */
+export interface RuleCore {
+    /** Chemin relatif du fichier de règle dans le dépôt */
+    file: string;
+    /** Nom de la branche Git où se trouve cette version de la règle */
+    branch: string;
+    /** Statut actuel de la règle dans le workflow */
+    status: RuleStatus;
+}
+/**
+ * Interface complète pour une règle avec tout son contenu et métadonnées
+ *
+ * Étend RuleCore avec le contenu complet, les métadonnées front-matter
+ * et l'historique des modifications optionnel.
+ *
+ * @example
+ * ```typescript
+ * const rule: Rule = {
+ *   file: 'procedures/finance/budget-validation.md',
+ *   branch: 'rule-editor',
+ *   status: RuleStatus.EDITING,
+ *   updated: new Date('2025-01-14'),
+ *   content: '# Validation Budget\n\nProcédure pour...',
+ *   matter: {
+ *     title: 'Validation Budget',
+ *     slugs: ['budget-validation'],
+ *     tags: ['finance', 'validation'],
+ *     role: 'rule'
+ *   }
+ * };
+ * ```
+ */
+export interface Rule extends RuleCore {
+    /** Date de dernière modification de la règle */
+    updated: Date;
+    /** Contenu Markdown complet de la règle */
+    content: string;
+    /** Métadonnées front-matter parsées de la règle */
+    matter: FrontMatter;
+    /** Historique optionnel des commits pour cette règle */
+    history?: GitCommitHistory[];
+}
+/** @deprecated Utiliser Rule à la place */
+export type FileInfo = Rule;
+/** @deprecated Utiliser Rule à la place */
+export type RuleContent = Rule;
+/** @deprecated Utiliser Rule à la place */
+export type ValidationInfo = Rule;
+/**
+ * Métadonnées front-matter d'une règle (contenu YAML en en-tête)
+ *
+ * Cette interface définit toutes les métadonnées qui peuvent être spécifiées
+ * dans le front-matter YAML d'un fichier de règle Markdown.
+ *
+ * @example
+ * ```yaml
+ * ---
+ * title: Procédure de Validation Budget
+ * slugs: ["budget-validation", "validation-budget"]
+ * version: "2.1"
+ * author:
+ *   name: "Jean Dupont"
+ *   email: "jean.dupont@entreprise.com"
+ * validator: "marie.martin@entreprise.com"
+ * service: "Finance"
+ * role: "rule"
+ * tags: ["finance", "budget", "validation"]
+ * terminated: true
+ * ---
+ * ```
+ */
+export interface FrontMatter {
+    /** Identifiant documentaire stable (attribué par RAG Embeddings) */
+    id?: number;
+    /** Titre descriptif de la règle */
+    title: string;
+    oldfile?: string;
+    /** Liste des identifiants/alias pour cette règle (pour recherche) */
+    slugs: string[];
+    /** Version de la règle (optionnelle, format libre) */
+    version?: string;
+    /** Auteur original de la règle */
+    author?: RuleUser;
+    /** Email du validateur assigné à cette règle */
+    validator?: string;
+    /** Indique si la règle est finalisée et prête pour validation */
+    terminated?: boolean;
+    /** Service ou département propriétaire de cette règle */
+    service?: string;
+    /** Type de contenu de ce document */
+    role?: "rule" | "template" | "rule-helper" | "web" | "document";
+    /** Tags de catégorisation pour recherche et filtrage */
+    tags?: string[];
+    /** Date de dernière modification explicite */
+    lastModified?: Date;
+    /** Clé personnalisée pour données additionnelles */
+    custom?: string;
+    [key: string]: string | Date | number | string[] | RuleUser | boolean | undefined;
+}
+/**
+ * Représente un élément de l'historique Git d'une règle
+ *
+ * Contient les informations d'un commit spécifique affectant une règle,
+ * avec éventuellement le contenu de la règle à ce moment-là.
+ */
+export interface RuleHistoryItem {
+    /** Hash du commit Git */
+    commit: string;
+    /** Informations sur l'auteur du commit */
+    author: {
+        /** Nom de l'auteur */
+        name: string;
+        /** Email de l'auteur */
+        email: string;
+    };
+    /** Date du commit */
+    date: Date;
+    /** Message de commit */
+    message: string;
+    /** État de la règle au moment de ce commit (optionnel) */
+    rule?: Rule;
+}
+/**
+ * Détails modifiables d'une pull request de règle
+ *
+ * Interface utilisée pour mettre à jour les métadonnées d'une PR
+ * en cours de validation.
+ */
+export interface RulePullRequestDetails {
+    /** Commentaires de validation ou de révision */
+    comments?: string[];
+    /** Email du validateur assigné */
+    validator?: string;
+    /** Indique si la règle est prête pour validation finale */
+    readyForValidation?: boolean;
+}
+/**
+ * Type représentant une pull request de règle complète
+ *
+ * Combine les informations PRInfo avec la méthode toString()
+ * pour faciliter l'utilisation dans les APIs.
+ */
+export type RulePullRequest = PRInfo & {
+    /** Méthode de sérialisation vers string (nom de branche) */
+    toString(): string;
+};
+/**
+ * Interface simplifiée du SDK pour la gestion des workflows d'édition de règles
+ *
+ * Cette interface définit les opérations de base disponibles pour manipuler
+ * les règles dans le workflow Git. Version simplifiée par rapport à celle
+ * définie dans workflow.ts qui contient des méthodes additionnelles.
+ *
+ * @deprecated Utiliser l'interface RulesSDK de workflow.ts qui est plus complète
+ */
+export interface RulesSDK {
+    /** Crée une pull request pour valider des règles */
+    createPullRequest(slugs: string[], message: string, user: RuleUser, contents?: string[]): Promise<RulePullRequest>;
+    /** Charge une pull request existante */
+    loadPullRequest(slug: string): Promise<RulePullRequest>;
+    /** Ferme et merge une pull request */
+    closePullRequest(pullRequestBranch: string, user: RuleUser): Promise<PRMergeResult>;
+    /** Supprime complètement une pull request */
+    deletePullRequest(pullRequestBranch: string, user: RuleUser): Promise<void>;
+    /** Sauvegarde une règle */
+    save(slug: string, content: string, user: RuleUser, pr: RulePullRequest): Promise<void>;
+    /** Charge une règle */
+    load(slug: string, branch?: string): Promise<Rule>;
+    /** Liste les règles publiées */
+    listPublished(): Promise<Rule[]>;
+    /** Liste les brouillons */
+    listDrafts(): Promise<Rule[]>;
+    /** Liste les pull requests */
+    listPullRequests(): Promise<RulePullRequest[]>;
+    /** Liste les fichiers non trackés */
+    listFilesOutsideRepo(): Promise<Rule[]>;
+    /** Crée un candidat de release */
+    createReleaseCandidate(user: RuleUser, message: string): Promise<RulePullRequest>;
+    /** Publie une release */
+    publishRelease(releaseCandidate: RulePullRequest, user: RuleUser, message: string): Promise<PRMergeResult>;
+    /** Crée un hotfix (à implémenter) */
+    createHotfix(slug: string, user: RuleUser): Promise<string>;
+}
+/**
+ * Configuration complète pour les opérations Git du système de règles
+ *
+ * Cette interface centralise toute la configuration nécessaire pour
+ * les opérations Git de bas niveau, y compris les branches, les préfixes,
+ * la concurrence et les Git Notes.
+ *
+ * @example
+ * ```typescript
+ * const config: RulesGitConfig = {
+ *   instance: simpleGit('/path/to/repo'),
+ *   repoPath: '/path/to/repo',
+ *   draftBranch: 'rule-editor',
+ *   mainBranch: 'main',
+ *   validationPrefix: 'rule-validation-',
+ *   releasePrefix: 'rule-release-',
+ *   validationToken: 'closed',
+ *   concurrency: { maxRetries: 3, retryDelayMs: 100, timeoutMs: 5000 },
+ *   gitNotes: { namespace: 'refs/notes/pr-status', enabled: true, fallbackToCommit: true }
+ * };
+ * ```
+ */
+export interface RulesGitConfig {
+    /** Service d'embeddings pour la recherche sémantique (optionnel) */
+    embeddings?: any;
+    /** Instance SimpleGit configurée pour ce dépôt */
+    instance: SimpleGit;
+    /** Chemin absolu vers le dépôt Git */
+    repoPath: string;
+    /** Chemin relatif pour les uploads (ex: '.assets') */
+    uploadPath?: string;
+    /** Nom de la branche d'édition/draft (ex: 'rule-editor') */
+    draftBranch: string;
+    /** Nom de la branche principale/publication (ex: 'main') */
+    mainBranch: string;
+    /** Préfixe pour les branches de validation (ex: 'rule-validation-') */
+    validationPrefix: string;
+    /** Préfixe pour les branches de release (ex: 'rule-release-') */
+    releasePrefix: string;
+    /** Token utilisé dans les commits pour marquer la fermeture des PRs */
+    validationToken: string;
+    /** Configuration de gestion de la concurrence */
+    concurrency: ConcurrencyOptions;
+    /** Configuration des Git Notes */
+    gitNotes: GitNotesConfig;
+    /** Permet les opérations forcées (dangereux, pour développement) */
+    canForce?: boolean;
+    /** Force le rechargement de la configuration */
+    reset?: boolean;
+    /** URL du remote Git (optionnel pour dépôts locaux) */
+    remoteUrl?: string;
+    /** Active les logs verbeux pour debug */
+    verbose?: boolean;
+}
+/**
+ * Configuration des options de concurrence pour les opérations Git
+ *
+ * Ces options contrôlent le comportement de retry et les timeouts
+ * pour les opérations Git potentiellement concurrentes.
+ */
+export interface ConcurrencyOptions {
+    /** Nombre maximum de tentatives en cas d'échec */
+    maxRetries: number;
+    /** Délai en millisecondes entre les tentatives */
+    retryDelayMs: number;
+    /** Timeout maximum en millisecondes pour une opération */
+    timeoutMs: number;
+}
+/**
+ * Résultat d'une opération avec mécanisme de retry
+ *
+ * @template T Type du résultat en cas de succès
+ */
+export interface RetryResult<T> {
+    /** Indique si l'opération a réussi */
+    success: boolean;
+    /** Résultat de l'opération si succès */
+    result?: T;
+    /** Nombre de tentatives effectuées */
+    attempts: number;
+    /** Dernière erreur rencontrée si échec */
+    error?: Error;
+}
+/**
+ * Représentation simplifiée d'un commit Git avec ses métadonnées
+ *
+ * Interface utilisée pour transporter les informations essentielles
+ * d'un commit à travers les différentes couches du système.
+ */
+export interface GitCommitHistory {
+    /** Hash unique du commit */
+    hash: string;
+    /** Date et heure du commit */
+    date: Date;
+    /** Message de commit */
+    message: string;
+    /** Auteur du commit */
+    author: RuleUser;
+    /** Contenu du fichier à ce commit (optionnel) */
+    content?: string;
+    /** Branche où s'est produit ce commit (optionnel) */
+    branch?: string;
+}
+/**
+ * Résumé d'un fichier Git avec son commit associé
+ *
+ * Structure utilisée pour les listings rapides de fichiers
+ * sans charger tout l'historique.
+ */
+export interface GitFileSummary {
+    /** Chemin relatif du fichier */
+    filePath: string;
+    /** Contenu actuel du fichier */
+    content: string;
+    /** Informations du dernier commit affectant ce fichier */
+    commit: GitCommitHistory;
+}
+/**
+ * Informations complètes d'une Pull Request
+ *
+ * Cette interface centralise toutes les données d'une PR,
+ * incluant les métadonnées stockées dans Git Notes.
+ */
+export interface PRInfo {
+    /** Nom de la branche de la pull request */
+    branch: string;
+    /** Liste des fichiers inclus dans cette PR (peut dupliquer metadata.files) */
+    files: string[];
+    /** Indique si la PR est ouverte (true) ou fermée (false) */
+    open: boolean;
+    /** Hash du dernier commit de la branche */
+    lastCommit?: string;
+    /** Message du dernier commit */
+    lastCommitMessage?: string;
+    /** Date de dernière modification */
+    lastModified?: Date;
+    /** Métadonnées détaillées stockées dans Git Notes */
+    metadata: PRMetadata;
+    /** Méthode de sérialisation (retourne le nom de branche) */
+    toString(): string;
+}
+/**
+ * Résultat d'une opération de merge d'une Pull Request
+ *
+ * Contient toutes les informations sur le résultat d'un merge,
+ * y compris les conflits éventuels et les tags de release.
+ */
+export interface PRMergeResult {
+    /** Métadonnées de la PR mergée */
+    metadata: PRMetadata;
+    /** Indique si le merge a échoué */
+    failed: boolean;
+    /** Liste des conflits de merge détectés */
+    conflicts: MergeConflict[];
+    /** Résultat brut de l'opération Git */
+    raw: string | MergeResult;
+    /** Tag de release créé lors du merge (optionnel) */
+    releaseTag?: string;
+}
+/**
+ * Statut d'une Pull Request basé sur Git Notes
+ *
+ * Interface pour tracker l'état d'une PR au fil du temps
+ * avec toutes les informations de traçabilité.
+ */
+export interface PRStatus {
+    /** Nom de la branche de la PR */
+    branch: string;
+    /** Statut actuel de la PR */
+    status: 'open' | 'closed' | 'merged';
+    /** Date de fermeture (si fermée) */
+    closedAt?: Date;
+    /** Utilisateur ayant fermé la PR */
+    closedBy: RuleUser;
+    /** Date de création de la PR */
+    createdAt?: Date;
+    /** Utilisateur ayant créé la PR */
+    createdBy: RuleUser;
+    /** Raison de la fermeture (optionnelle) */
+    closureReason?: string;
+    /** Référence de la note Git contenant ces informations */
+    noteRef?: string;
+}
+/**
+ * Métadonnées complètes d'une Pull Request stockées dans Git Notes
+ *
+ * Cette interface définit toutes les métadonnées d'une PR qui sont
+ * persistées dans Git Notes pour assurer la traçabilité et l'état.
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": 42,
+ *   "status": "open",
+ *   "timestamp": "2025-01-14T10:30:00Z",
+ *   "createdBy": {
+ *     "name": "Jean Dupont",
+ *     "email": "jean.dupont@entreprise.com"
+ *   },
+ *   "mergeBase": "main",
+ *   "comments": ["Nouvelle procédure de validation budget"],
+ *   "validator": "marie.martin@entreprise.com",
+ *   "readyForValidation": true,
+ *   "files": ["procedures/finance/budget-validation.md"]
+ * }
+ * ```
+ */
+export interface PRMetadata {
+    /** Identifiant numérique unique de la PR */
+    id: number;
+    /** Statut actuel de la PR */
+    status: 'open' | 'closed' | 'merged';
+    /** Timestamp ISO 8601 de création/dernière modification */
+    timestamp: string;
+    /** Utilisateur ayant créé la PR */
+    createdBy: RuleUser;
+    /** Utilisateur ayant fermé la PR (si applicable) */
+    closedBy?: RuleUser;
+    /** Timestamp ISO 8601 de fermeture (si applicable) */
+    closedAt?: string;
+    /** Branche de base pour le merge (ex: 'main', 'rule-editor') */
+    mergeBase: string;
+    /** Liste des commentaires de validation/révision */
+    comments: string[];
+    /** Email du validateur assigné */
+    validator?: string;
+    /** Indique si la règle est prête pour validation finale */
+    readyForValidation?: boolean;
+    /** Liste des fichiers inclus dans cette PR */
+    files?: string[];
+}
+/**
+ * Configuration pour le système Git Notes
+ *
+ * Git Notes permet de stocker des métadonnées additionnelles
+ * associées aux commits sans modifier l'historique Git.
+ */
+export interface GitNotesConfig {
+    /** Namespace des notes Git (ex: "refs/notes/pr-status") */
+    namespace: string;
+    /** Active/désactive le système Git Notes */
+    enabled: boolean;
+    /** Utilise l'ancien système de commit en fallback si les notes échouent */
+    fallbackToCommit: boolean;
+}
+/**
+ * État de santé d'une branche Git
+ *
+ * Cette interface fournit un diagnostic complet de l'état d'une branche
+ * pour détecter les problèmes nécessitant une réparation.
+ */
+export interface GitHealthStatus {
+    /** Nom de la branche diagnostiquée */
+    branch: string;
+    /** Indique si la branche existe dans le dépôt */
+    exists: boolean;
+    /** Indique si la branche est accessible (checkout possible) */
+    accessible: boolean;
+    /** Indique si le working directory est propre */
+    clean: boolean;
+    /** Indique si un merge est en cours */
+    mergeInProgress: boolean;
+    /** Nombre de fichiers en conflit */
+    conflictedFiles: number;
+    /** Nombre de fichiers modifiés non committés */
+    modifiedFiles: number;
+    /** Nombre de fichiers non trackés */
+    untrackedFiles: number;
+    /** Nombre de fichiers stagés */
+    stagedFiles: number;
+    /** Indique si l'index Git est lisible */
+    indexReadable: boolean;
+    /** Évaluation globale de la santé */
+    healthy: boolean;
+    /** Liste des problèmes détectés */
+    issues: string[];
+    /** Recommandations de réparation */
+    recommendations: string[];
+}