@piecemaker-legal/piecemaker 1.0.6 → 1.0.7

package/server/piecemaker/knowledge/pipeline.ts

@@ -1,12 +1,14 @@
+import { createRequire } from 'node:module';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
 
 import type { KnowledgeStore } from '../../../plugins/piecemaker-dossier/src/knowledge.js';
-import type { GlinerDocument, GlinerMappingDocument, JsonData } from '../../../plugins/piecemaker-dossier/src/types.js';
 import { persistScanResult, scanResultOperations } from '../../../plugins/piecemaker-dossier/src/scan-result.js';
+import type { GlinerDocument, GlinerMappingDocument, JsonData } from '../../../plugins/piecemaker-dossier/src/types.js';
+
+import type { KnowledgeScanProgress } from './scan-jobs.js';
 
 type ProjectLookup = {
   getProjectById(projectId: string): { project_id: string; project_path: string } | null;
@@ -19,6 +21,29 @@ type PipelineOptions = {
   pythonPath?: string;
 };
 
+type OriginalFile = { path: string; resource?: boolean };
+
+type OriginalsPipeline = {
+  caseMappingFile(caseRoot: string): string;
+  listOriginals(caseRoot: string): Promise<OriginalFile[]>;
+  runManagedPythonJob(options: {
+    action: 'convert' | 'anonymize';
+    script: string;
+    args: string[];
+    onProgress?: (progress: KnowledgeScanProgress) => void;
+    signal?: AbortSignal;
+  }): Promise<unknown>;
+  writeCaseMapping(caseRoot: string, document: GlinerMappingDocument): unknown;
+};
+
+const require = createRequire(import.meta.url);
+const {
+  caseMappingFile,
+  listOriginals,
+  runManagedPythonJob,
+  writeCaseMapping,
+} = require('../vendor/websocket-server/originals-pipeline.cjs') as OriginalsPipeline;
+
 const SUPPORTED_EXTENSIONS = new Set(['.pdf', '.docx', '.doc', '.odt', '.rtf', '.txt', '.md', '.png', '.jpg', '.jpeg', '.tif', '.tiff', '.bmp']);
 
 function relativeKey(projectPath: string, filePath: string): string {
@@ -26,15 +51,18 @@ function relativeKey(projectPath: string, filePath: string): string {
   return crypto.createHash('sha256').update(relative).digest('hex');
 }
 
-function listedFiles(projectPath: string): string[] {
-  return fs.readdirSync(projectPath, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && SUPPORTED_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
-    .map((entry) => path.join(projectPath, entry.name));
+/** Pièces scannées par défaut : même liste que l'administration, récursive, hors Markdown généré. */
+export async function defaultScanFiles(projectPath: string): Promise<string[]> {
+  const root = fs.realpathSync(projectPath);
+  const originals = await listOriginals(root);
+  return originals
+    .filter((file) => !file.resource)
+    .map((file) => path.resolve(root, file.path));
 }
 
-function safeFiles(projectPath: string, requested: unknown): string[] {
+async function safeFiles(projectPath: string, requested: unknown): Promise<string[]> {
   const root = fs.realpathSync(projectPath);
-  const candidates = Array.isArray(requested) && requested.length ? requested : listedFiles(root);
+  const candidates = Array.isArray(requested) && requested.length ? requested : await defaultScanFiles(root);
   return [...new Set(candidates.map((candidate) => {
     const raw = String(candidate || '');
     const resolved = path.resolve(root, raw);
@@ -45,29 +73,18 @@ function safeFiles(projectPath: string, requested: unknown): string[] {
   }))];
 }
 
-function runProcess(executable: string, args: string[], cwd: string): Promise<{ stdout: string; stderr: string }> {
-  return new Promise((resolve, reject) => {
-    const child = spawn(executable, args, { cwd, env: process.env, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.setEncoding('utf8');
-    child.stderr.setEncoding('utf8');
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => {
-      if (code === 0) resolve({ stdout, stderr });
-      else reject(new Error(stderr.trim() || stdout.trim() || `Pipeline failed with code ${code ?? 1}.`));
-    });
-  });
-}
-
 function parseObject(filePath: string): JsonData {
-  const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8').replace(/^/, '')) as unknown;
+  const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '')) as unknown;
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('Invalid pipeline output.');
   return parsed as JsonData;
 }
 
+function readDocumentIndex(projectPath: string): JsonData {
+  const indexPath = path.join(projectPath, '.piecemaker', 'document-index.json');
+  if (!fs.existsSync(indexPath)) return { documents: {} };
+  return parseObject(indexPath);
+}
+
 function documentsFromIndex(projectPath: string, files: string[], documentIndex: JsonData): GlinerDocument[] {
   const entries = documentIndex.documents && typeof documentIndex.documents === 'object' && !Array.isArray(documentIndex.documents)
     ? documentIndex.documents as Record<string, JsonData>
@@ -128,46 +145,61 @@ function textValue(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
 }
 
+async function withPythonPath<T>(pythonPath: string, run: () => Promise<T>): Promise<T> {
+  const previous = process.env.PYTHON_PATH;
+  process.env.PYTHON_PATH = pythonPath;
+  try {
+    return await run();
+  } finally {
+    if (previous === undefined) delete process.env.PYTHON_PATH;
+    else process.env.PYTHON_PATH = previous;
+  }
+}
+
 export function createKnowledgePipeline(options: PipelineOptions) {
   const script = path.join(options.applicationRoot, 'server', 'piecemaker', 'vendor', 'websocket-server', 'scripts', 'convert_and_scan_pipeline.py');
   return {
-    async scan(projectId: string, requestedFiles?: unknown) {
+    async scan(projectId: string, requestedFiles?: unknown, onProgress?: (progress: KnowledgeScanProgress) => void, signal?: AbortSignal) {
       const project = options.projects.getProjectById(projectId);
       if (!project) throw new Error('Project not found.');
       const projectPath = fs.realpathSync(project.project_path);
-      const files = safeFiles(projectPath, requestedFiles);
+      const explicitFiles = Array.isArray(requestedFiles) && requestedFiles.length > 0;
+      const files = await safeFiles(projectPath, requestedFiles);
       if (!files.length) throw new Error('No supported file to scan.');
-      const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'piecemaker-knowledge-'));
-      const mappingFile = path.join(temporaryRoot, 'mapping.json');
-      const stateFile = path.join(temporaryRoot, 'state.json');
+      const mappingFile = caseMappingFile(projectPath);
+      const stateFile = path.join(projectPath, '.piecemaker', 'anonymization-state.json');
       const outputDirectory = path.join(projectPath, 'Fichiers convertis PieceMaker');
+      fs.mkdirSync(path.dirname(mappingFile), { recursive: true });
+      fs.mkdirSync(path.dirname(stateFile), { recursive: true });
       fs.mkdirSync(outputDirectory, { recursive: true });
-      try {
-        fs.writeFileSync(mappingFile, JSON.stringify(mappingSeed(projectId, projectPath, options.store)), { mode: 0o600 });
-        const args = [
-          script,
-          ...files,
-          '-o',
-          outputDirectory,
-          '--mapping-file',
-          mappingFile,
-          '--case-root',
-          projectPath,
-          '--state-file',
-          stateFile,
-        ];
-        const processResult = await runProcess(pythonExecutable(options.pythonPath), args, projectPath);
-        const mapping = parseObject(mappingFile) as GlinerMappingDocument;
-        const documentIndex = parseObject(path.join(temporaryRoot, 'document-index.json'));
-        const documents = documentsFromIndex(projectPath, files, documentIndex);
-        const scanResult = { projectId, mapping, documents };
-        const result = Array.isArray(requestedFiles) && requestedFiles.length
-          ? options.store.update({ projectId, operations: scanResultOperations(scanResult) })
-          : persistScanResult(scanResult, options.store);
-        return { ...result, documents: documents.length, stdout: processResult.stdout.trim(), stderr: processResult.stderr.trim() };
-      } finally {
-        fs.rmSync(temporaryRoot, { recursive: true, force: true });
-      }
+      fs.writeFileSync(mappingFile, JSON.stringify(mappingSeed(projectId, projectPath, options.store)), { mode: 0o600 });
+      const args = [
+        ...files,
+        '-o',
+        outputDirectory,
+        '--mapping-file',
+        mappingFile,
+        '--case-root',
+        projectPath,
+        '--state-file',
+        stateFile,
+      ];
+      if (!explicitFiles) args.push('--skip-existing');
+      await withPythonPath(pythonExecutable(options.pythonPath), () => runManagedPythonJob({
+        action: 'anonymize',
+        script,
+        args,
+        onProgress,
+        signal,
+      }));
+      const mapping = parseObject(mappingFile) as GlinerMappingDocument;
+      writeCaseMapping(projectPath, mapping);
+      const documents = documentsFromIndex(projectPath, files, readDocumentIndex(projectPath));
+      const scanResult = { projectId, mapping, documents };
+      const result = explicitFiles
+        ? options.store.update({ projectId, operations: scanResultOperations(scanResult) })
+        : persistScanResult(scanResult, options.store);
+      return { ...result, documents: documents.length };
     },
   };
 }

package/server/piecemaker/knowledge/routes.ts

@@ -17,13 +17,11 @@ export function createKnowledgeRouter(service: KnowledgeService) {
       response.status(statusFor(error)).json({ error: error instanceof Error ? error.message : 'Knowledge operation failed.' });
     });
   };
-  router.get('/knowledge/overview', (request, response) => respond(() => service.overview(request.query.projectId), response));
-  router.get('/knowledge/mapping', (request, response) => respond(() => service.mapping(request.query.projectId), response));
-  router.get('/knowledge/chronology', (request, response) => respond(() => service.chronology(request.query.projectId), response));
   router.get('/knowledge/graph', (request, response) => respond(() => service.graph(request.query.projectId), response));
-  router.get('/knowledge/agents', (request, response) => respond(() => service.agents(request.query.projectId), response));
   router.post('/knowledge/query', (request, response) => respond(() => service.query(request.body), response));
   router.post('/knowledge/update', (request, response) => respond(() => service.update(request.body), response));
   router.post('/knowledge/scan', (request, response) => respond(() => service.scan(request.body?.projectId, request.body?.files), response));
+  router.get('/knowledge/scan/job', (request, response) => respond(() => service.scanJob(request.query.id, request.query.projectId), response));
+  router.post('/knowledge/scan/cancel', (request, response) => respond(() => service.cancelScan(request.body?.id, request.body?.projectId), response));
   return router;
 }

package/server/piecemaker/knowledge/scan-jobs.ts

@@ -0,0 +1,111 @@
+import crypto from 'node:crypto';
+
+export type KnowledgeScanPhase = 'convert' | 'scan' | 'commit';
+
+export type KnowledgeScanProgress = {
+  phase: KnowledgeScanPhase;
+  percent: number;
+  processed: number;
+  total: number;
+};
+
+export type KnowledgeScanJob = {
+  id: string;
+  projectId: string;
+  source: 'knowledge';
+  action: 'anonymize';
+  state: 'running' | 'done' | 'error' | 'cancelled';
+  phase: KnowledgeScanPhase;
+  percent: number;
+  processed: number;
+  total: number;
+  error: string | null;
+  startedAt: string;
+  finishedAt: string | null;
+};
+
+const COMPLETED_RETENTION_MS = 5 * 60_000;
+
+function isPending(job: KnowledgeScanJob): boolean {
+  return job.state === 'running';
+}
+
+export function createKnowledgeScanJobs() {
+  const jobs = new Map<string, KnowledgeScanJob>();
+  const controllers = new Map<string, AbortController>();
+
+  const prune = () => {
+    const deadline = Date.now() - COMPLETED_RETENTION_MS;
+    for (const [id, job] of jobs) {
+      if (isPending(job)) continue;
+      if (Date.parse(job.finishedAt || job.startedAt) < deadline) jobs.delete(id);
+    }
+  };
+
+  const runningForProject = (projectId: string): KnowledgeScanJob | null => {
+    for (const job of jobs.values()) if (job.projectId === projectId && isPending(job)) return job;
+    return null;
+  };
+
+  return {
+    start(projectId: string, run: (report: (progress: KnowledgeScanProgress) => void, signal: AbortSignal) => Promise<unknown>): KnowledgeScanJob {
+      prune();
+      const running = runningForProject(projectId);
+      if (running) return running;
+      const job: KnowledgeScanJob = {
+        id: crypto.randomUUID(),
+        projectId,
+        source: 'knowledge',
+        action: 'anonymize',
+        state: 'running',
+        phase: 'convert',
+        percent: 0,
+        processed: 0,
+        total: 0,
+        error: null,
+        startedAt: new Date().toISOString(),
+        finishedAt: null,
+      };
+      jobs.set(job.id, job);
+      const report = (progress: KnowledgeScanProgress) => {
+        if (job.state !== 'running') return;
+        job.phase = progress.phase;
+        job.percent = Math.max(job.percent, Math.min(100, progress.percent));
+        job.processed = progress.processed;
+        job.total = progress.total || job.total;
+      };
+      const controller = new AbortController();
+      controllers.set(job.id, controller);
+      run(report, controller.signal).then(() => {
+        if (job.state !== 'running') return;
+        job.state = 'done';
+        job.phase = 'commit';
+        job.percent = 100;
+      }, (error: unknown) => {
+        if (job.state !== 'running') return;
+        job.state = 'error';
+        job.error = error instanceof Error ? error.message : String(error);
+      }).finally(() => {
+        controllers.delete(job.id);
+        job.finishedAt = job.finishedAt || new Date().toISOString();
+      });
+      return job;
+    },
+    get(id: unknown): KnowledgeScanJob | null {
+      prune();
+      return typeof id === 'string' ? jobs.get(id) || null : null;
+    },
+    runningForProject(projectId: string): KnowledgeScanJob | null {
+      prune();
+      return runningForProject(projectId);
+    },
+    cancel(job: KnowledgeScanJob | null): KnowledgeScanJob | null {
+      if (!job || job.state !== 'running') return job;
+      job.state = 'cancelled';
+      job.finishedAt = new Date().toISOString();
+      controllers.get(job.id)?.abort();
+      controllers.delete(job.id);
+      return job;
+    },
+  };
+}

package/server/piecemaker/knowledge/service.ts

@@ -1,11 +1,10 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
 import type { KnowledgeStore } from '../../../plugins/piecemaker-dossier/src/knowledge.js';
 import { exclusionNodeOperation } from '../../../plugins/piecemaker-dossier/src/scan-result.js';
 import type { KnowledgeQueryInput, KnowledgeUpdateInput } from '../../../plugins/piecemaker-dossier/src/types.js';
+
 import { legacyExclusions } from './pipeline.js';
 import type { createKnowledgePipeline } from './pipeline.js';
+import { createKnowledgeScanJobs } from './scan-jobs.js';
 
 type ProjectLookup = {
   getProjectById(projectId: string): { project_id: string; project_path: string } | null;
@@ -17,6 +16,7 @@ function projectId(value: unknown): string {
 }
 
 export function createKnowledgeService(store: KnowledgeStore, projects: ProjectLookup, pipeline: ReturnType<typeof createKnowledgePipeline>) {
+  const scanJobs = createKnowledgeScanJobs();
   const ensureProject = (value: unknown): string => {
     const id = projectId(value);
     if (!projects.getProjectById(id)) throw new Error('Project not found.');
@@ -39,42 +39,27 @@ export function createKnowledgeService(store: KnowledgeStore, projects: ProjectL
     update(input: KnowledgeUpdateInput) {
       return store.update({ ...input, projectId: ensureProject(input.projectId) });
     },
-    overview(value: unknown) {
-      const id = ensureProject(value);
-      const nodes = snapshot(id).nodes;
-      const counts = nodes.reduce<Record<string, number>>((result, node) => {
-        result[node.kind] = (result[node.kind] || 0) + 1;
-        return result;
-      }, {});
-      return { projectId: id, counts, total: nodes.length };
-    },
-    mapping(value: unknown) {
-      const id = ensureProject(value);
-      const current = snapshot(id);
-      return { projectId: id, nodes: current.nodes.filter((node) => node.kind !== 'document'), mappings: current.mappings, exclusions: current.exclusions || [] };
-    },
-    chronology(value: unknown) {
-      const id = ensureProject(value);
-      const current = snapshot(id);
-      return { projectId: id, documents: current.nodes.filter((node) => node.kind === 'document'), links: current.links.filter((link) => link.relation === 'mentions') };
-    },
     graph(value: unknown) {
       const id = ensureProject(value);
       return snapshot(id);
     },
-    agents(value: unknown) {
+    scan(value: unknown, files?: unknown) {
       const id = ensureProject(value);
-      const project = projects.getProjectById(id);
-      if (!project) throw new Error('Project not found.');
-      const root = fs.realpathSync(project.project_path);
-      const candidate = path.join(root, 'AGENTS.md');
-      if (!fs.existsSync(candidate)) return { projectId: id, content: '', exists: false };
-      const real = fs.realpathSync(candidate);
-      if (real !== root && !real.startsWith(`${root}${path.sep}`)) throw new Error('Invalid AGENTS.md path.');
-      return { projectId: id, content: fs.readFileSync(real, 'utf8').slice(0, 2_000_000), exists: true };
+      return {
+        job: scanJobs.start(id, async (report, signal) => {
+          const result = await pipeline.scan(id, files, report, signal);
+          store.markAnonymizationComplete(id);
+          return result;
+        }),
+      };
     },
-    scan(value: unknown, files?: unknown) {
-      return pipeline.scan(ensureProject(value), files);
+    scanJob(jobId: unknown, value?: unknown) {
+      const job = scanJobs.get(jobId) || (value ? scanJobs.runningForProject(ensureProject(value)) : null);
+      return { job };
+    },
+    cancelScan(jobId: unknown, value?: unknown) {
+      const job = scanJobs.get(jobId) || (value ? scanJobs.runningForProject(ensureProject(value)) : null);
+      return { job: scanJobs.cancel(job) };
     },
   };
 }

package/server/piecemaker/library/connector-installation.ts

@@ -0,0 +1,248 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const TOML = require('@iarna/toml') as {
+  parse(value: string): Record<string, unknown>;
+  stringify(value: Record<string, unknown>): string;
+};
+
+export type LibraryConnectorConfig = {
+  transport: 'http' | 'stdio';
+  url?: string;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  headers?: Record<string, string>;
+};
+
+type FileSnapshot = { filePath: string; previous: string | null };
+
+function readJson(filePath: string) {
+  if (!fs.existsSync(filePath)) return {};
+  const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function readToml(filePath: string) {
+  if (!fs.existsSync(filePath)) return {};
+  const value = TOML.parse(fs.readFileSync(filePath, 'utf8'));
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function writeJson(filePath: string, value: Record<string, unknown>) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}
+
+function writeToml(filePath: string, value: Record<string, unknown>) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(filePath, TOML.stringify(value), { mode: 0o600 });
+}
+
+function snapshotFile(filePath: string): FileSnapshot {
+  return { filePath, previous: fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null };
+}
+
+function restoreFile({ filePath, previous }: FileSnapshot) {
+  if (previous === null) {
+    fs.rmSync(filePath, { force: true });
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(filePath, previous, { mode: 0o600 });
+}
+
+function assertWorkspaceFile(workspace: string, filePath: string) {
+  const resolvedWorkspace = fs.realpathSync(workspace);
+  const parent = path.dirname(filePath);
+  if (fs.existsSync(parent)) {
+    const resolvedParent = fs.realpathSync(parent);
+    if (resolvedParent !== resolvedWorkspace && !resolvedParent.startsWith(resolvedWorkspace + path.sep)) {
+      throw new Error(`Répertoire de composants hors du dossier : ${parent}`);
+    }
+  } else if (!parent.startsWith(resolvedWorkspace + path.sep) && parent !== resolvedWorkspace) {
+    throw new Error(`Répertoire de composants hors du dossier : ${parent}`);
+  }
+}
+
+function objectRecord(value: unknown) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function claudeServer(config: LibraryConnectorConfig) {
+  if (config.transport === 'http') {
+    return {
+      type: 'http',
+      url: config.url,
+      ...(config.headers && Object.keys(config.headers).length ? { headers: config.headers } : {}),
+    };
+  }
+  return {
+    type: 'stdio',
+    command: config.command,
+    args: config.args ?? [],
+    ...(config.env && Object.keys(config.env).length ? { env: config.env } : {}),
+  };
+}
+
+function cursorServer(config: LibraryConnectorConfig, enabled: boolean) {
+  const server = config.transport === 'http'
+    ? { url: config.url, ...(config.headers && Object.keys(config.headers).length ? { headers: config.headers } : {}) }
+    : { command: config.command, args: config.args ?? [], ...(config.env && Object.keys(config.env).length ? { env: config.env } : {}) };
+  return enabled ? server : { ...server, disabled: true };
+}
+
+function codexServer(config: LibraryConnectorConfig, enabled: boolean) {
+  if (config.transport === 'http') {
+    return {
+      url: config.url,
+      enabled,
+      ...(config.headers && Object.keys(config.headers).length ? { http_headers: config.headers } : {}),
+    };
+  }
+  return {
+    command: config.command,
+    args: config.args ?? [],
+    enabled,
+    ...(config.env && Object.keys(config.env).length ? { env: config.env } : {}),
+  };
+}
+
+function grokServer(config: LibraryConnectorConfig, enabled: boolean) {
+  if (config.transport === 'http') {
+    return {
+      url: config.url,
+      enabled,
+      ...(config.headers && Object.keys(config.headers).length ? { headers: config.headers } : {}),
+    };
+  }
+  return {
+    command: config.command,
+    args: config.args ?? [],
+    enabled,
+    ...(config.env && Object.keys(config.env).length ? { env: config.env } : {}),
+  };
+}
+
+function opencodeServer(config: LibraryConnectorConfig, enabled: boolean) {
+  if (config.transport === 'http') {
+    return {
+      type: 'remote',
+      url: config.url,
+      enabled,
+      ...(config.headers && Object.keys(config.headers).length ? { headers: config.headers } : {}),
+    };
+  }
+  return {
+    type: 'local',
+    command: [config.command, ...(config.args ?? [])].filter(Boolean),
+    enabled,
+    ...(config.env && Object.keys(config.env).length ? { environment: config.env } : {}),
+  };
+}
+
+function opencodeConfigPath(workspace: string) {
+  const jsonPath = path.join(workspace, 'opencode.json');
+  const jsoncPath = path.join(workspace, 'opencode.jsonc');
+  if (fs.existsSync(jsonPath)) return jsonPath;
+  if (fs.existsSync(jsoncPath)) return jsoncPath;
+  return jsonPath;
+}
+
+export function parseConnectorConfig(content: string): LibraryConnectorConfig {
+  const parsed = JSON.parse(content) as LibraryConnectorConfig;
+  if (parsed?.transport !== 'http' && parsed?.transport !== 'stdio') throw new Error('Connecteur invalide.');
+  if (parsed.transport === 'http' && typeof parsed.url !== 'string') throw new Error('Connecteur invalide.');
+  if (parsed.transport === 'stdio' && typeof parsed.command !== 'string') throw new Error('Connecteur invalide.');
+  return parsed;
+}
+
+export function normalizeProviderConnector(raw: unknown): LibraryConnectorConfig | null {
+  const config = objectRecord(raw);
+  if (typeof config.url === 'string' || config.type === 'http' || config.type === 'remote' || config.type === 'sse') {
+    const url = typeof config.url === 'string' ? config.url : '';
+    if (!url) return null;
+    const headers = { ...objectRecord(config.headers), ...objectRecord(config.http_headers) };
+    return {
+      transport: 'http',
+      url,
+      headers: Object.fromEntries(Object.entries(headers).filter((entry): entry is [string, string] => typeof entry[1] === 'string')),
+    };
+  }
+  const commandParts = typeof config.command === 'string'
+    ? [config.command, ...(Array.isArray(config.args) ? config.args.filter((value): value is string => typeof value === 'string') : [])]
+    : Array.isArray(config.command) ? config.command.filter((value): value is string => typeof value === 'string') : [];
+  if (!commandParts[0]) return null;
+  const env = { ...objectRecord(config.env), ...objectRecord(config.environment) };
+  return {
+    transport: 'stdio',
+    command: commandParts[0],
+    args: commandParts.slice(1),
+    env: Object.fromEntries(Object.entries(env).filter((entry): entry is [string, string] => typeof entry[1] === 'string')),
+  };
+}
+
+export function prepareConnectorInstallation(workspace: string, name: string, config: LibraryConnectorConfig, enabled: boolean) {
+  const mcpJsonPath = path.join(workspace, '.mcp.json');
+  const claudeSettingsPath = path.join(workspace, '.claude', 'settings.local.json');
+  const codexPath = path.join(workspace, '.codex', 'config.toml');
+  const cursorPath = path.join(workspace, '.cursor', 'mcp.json');
+  const opencodePath = opencodeConfigPath(workspace);
+  const grokPath = path.join(workspace, '.grok', 'config.toml');
+  for (const filePath of [mcpJsonPath, claudeSettingsPath, codexPath, cursorPath, opencodePath, grokPath]) {
+    assertWorkspaceFile(workspace, filePath);
+  }
+
+  const snapshots = [mcpJsonPath, claudeSettingsPath, codexPath, cursorPath, opencodePath, grokPath].map(snapshotFile);
+
+  return () => {
+    try {
+      const mcpJson = readJson(mcpJsonPath);
+      const mcpServers = objectRecord(mcpJson.mcpServers);
+      if (enabled) mcpServers[name] = claudeServer(config);
+      else delete mcpServers[name];
+      mcpJson.mcpServers = mcpServers;
+      writeJson(mcpJsonPath, mcpJson);
+
+      const claudeSettings = readJson(claudeSettingsPath);
+      const disabled = Array.isArray(claudeSettings.disabledMcpServers)
+        ? claudeSettings.disabledMcpServers.filter((entry) => entry !== name)
+        : [];
+      claudeSettings.disabledMcpServers = enabled ? disabled : [...disabled, name];
+      writeJson(claudeSettingsPath, claudeSettings);
+
+      const codexConfig = readToml(codexPath);
+      const codexServers = objectRecord(codexConfig.mcp_servers);
+      codexServers[name] = enabled
+        ? codexServer(config, true)
+        : { ...objectRecord(codexServers[name]), ...codexServer(config, false), enabled: false };
+      codexConfig.mcp_servers = codexServers;
+      writeToml(codexPath, codexConfig);
+
+      const cursorConfig = readJson(cursorPath);
+      const cursorServers = objectRecord(cursorConfig.mcpServers);
+      cursorServers[name] = cursorServer(config, enabled);
+      cursorConfig.mcpServers = cursorServers;
+      writeJson(cursorPath, cursorConfig);
+
+      const opencodeConfig = readJson(opencodePath);
+      const opencodeServers = objectRecord(opencodeConfig.mcp);
+      opencodeServers[name] = opencodeServer(config, enabled);
+      opencodeConfig.mcp = opencodeServers;
+      writeJson(opencodePath, opencodeConfig);
+
+      const grokConfig = readToml(grokPath);
+      const grokServers = objectRecord(grokConfig.mcp_servers);
+      grokServers[name] = enabled
+        ? grokServer(config, true)
+        : { ...objectRecord(grokServers[name]), ...grokServer(config, false), enabled: false };
+      grokConfig.mcp_servers = grokServers;
+      writeToml(grokPath, grokConfig);
+    } catch (error) {
+      for (const snapshot of snapshots.reverse()) restoreFile(snapshot);
+      throw error;
+    }
+  };
+}