@arka-labs/nemesis 1.2.0

package/lib/sync/nemesis-client.js

@@ -0,0 +1,379 @@
+/**
+ * Nemesis MCP Client — wraps 8 Nemesis reference tools.
+ * Tries HTTP remote first, falls back to local registre JSON files.
+ * In-memory cache with configurable TTL.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { debug } from '../core/logger.js';
+
+/** Default registre directory (relative to project root) */
+const DEFAULT_REGISTRE_DIR = '.owner/spec-in/registre-gestion-de-projet';
+
+/** Default TTL for cache entries (5 minutes) */
+const DEFAULT_CACHE_TTL = 5 * 60 * 1000;
+
+/** Bloc ID to file mapping */
+const BLOC_FILES = {
+  B00: 'B00_gouvernance.json',
+  B05: 'B05_equipe.json',
+  B10: 'B10_mission_contract.json',
+  B15: 'B15_execution.json',
+  B20: 'B20_odm.json',
+  B25: 'B25_controle_evidence.json',
+  B30: 'B30_qa.json',
+  B35: 'B35_transactions.json',
+  B40: 'B40_validation.json',
+};
+
+/** Situation → bloc mapping (from NAVIGATION.json quick_routes) */
+const SITUATION_BLOC_MAP = {
+  onboarding: 'B05',
+  review: 'B25',
+  architecture: 'B10',
+  implementation: 'B15',
+  documentation: 'B20',
+  audit: 'B30',
+  debugging: 'B15',
+  validation: 'B40',
+  dispatch: 'B35',
+  qa: 'B30',
+  general: 'B00',
+};
+
+/**
+ * Simple in-memory cache with TTL.
+ */
+function createCache(ttl = DEFAULT_CACHE_TTL) {
+  const store = new Map();
+
+  return {
+    get(key) {
+      const entry = store.get(key);
+      if (!entry) return undefined;
+      if (Date.now() - entry.ts > ttl) {
+        store.delete(key);
+        return undefined;
+      }
+      return entry.value;
+    },
+    set(key, value) {
+      store.set(key, { value, ts: Date.now() });
+    },
+    clear() {
+      store.clear();
+    },
+    size() {
+      return store.size;
+    },
+  };
+}
+
+/**
+ * Load Nemesis config from ~/.nemesis/config.json.
+ */
+function loadNemesisConfig() {
+  const configFile = join(homedir(), '.nemesis', 'config.json');
+  if (!existsSync(configFile)) return {};
+  try {
+    return JSON.parse(readFileSync(configFile, 'utf-8'));
+  } catch (e) {
+    debug(`loadNemesisConfig: ${e.message}`);
+    return {};
+  }
+}
+
+/**
+ * Read a bloc JSON file from the local registre.
+ *
+ * @param {string} registreDir - absolute path to registre directory
+ * @param {string} filename - e.g. "B00_gouvernance.json"
+ * @returns {object|null}
+ */
+function readBlocFile(registreDir, filename) {
+  const filepath = join(registreDir, filename);
+  if (!existsSync(filepath)) return null;
+  try {
+    return JSON.parse(readFileSync(filepath, 'utf-8'));
+  } catch (e) {
+    debug(`readBlocFile ${filename}: ${e.message}`);
+    return null;
+  }
+}
+
+/**
+ * Create a Nemesis MCP client.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.baseUrl] - Nemesis MCP server URL
+ * @param {string} [opts.projectRoot] - project root for local fallback
+ * @param {string} [opts.registreDir] - override registre directory (absolute)
+ * @param {number} [opts.timeout] - HTTP timeout in ms (default 5000)
+ * @param {number} [opts.cacheTtl] - cache TTL in ms (default 5min)
+ * @returns {object} client with 8 tool methods
+ */
+export function createNemesisClient(opts = {}) {
+  const config = loadNemesisConfig();
+  const {
+    baseUrl = config.nemesis_url || process.env.NEMESIS_URL || 'https://nemesis.arkalabs.app:3003',
+    projectRoot = process.cwd(),
+    timeout = 5000,
+    cacheTtl = DEFAULT_CACHE_TTL,
+  } = opts;
+
+  const registreDir = opts.registreDir || join(projectRoot, DEFAULT_REGISTRE_DIR);
+  const cache = createCache(cacheTtl);
+
+  /**
+   * HTTP request to the Nemesis MCP server.
+   * Returns null on any failure (timeout, network, 4xx, 5xx).
+   */
+  async function remoteRequest(path) {
+    try {
+      const url = `${baseUrl}${path}`;
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      const res = await fetch(url, {
+        method: 'GET',
+        headers: { 'Content-Type': 'application/json' },
+        signal: controller.signal,
+      });
+      clearTimeout(timer);
+      if (!res.ok) return null;
+      const json = await res.json();
+      return json?.data ?? json;
+    } catch (e) {
+      debug(`remoteRequest: ${e.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Try remote first, then local fallback. Cache the result.
+   *
+   * @param {string} cacheKey
+   * @param {string} remotePath - HTTP path
+   * @param {function} localFallback - () => data | null
+   * @returns {Promise<object|null>}
+   */
+  async function fetchWithFallback(cacheKey, remotePath, localFallback) {
+    const cached = cache.get(cacheKey);
+    if (cached !== undefined) return cached;
+
+    let data = await remoteRequest(remotePath);
+    let source = 'remote';
+
+    if (!data) {
+      data = localFallback();
+      source = 'local';
+    }
+
+    if (data) {
+      data._source = source;
+      cache.set(cacheKey, data);
+    }
+
+    return data;
+  }
+
+  return {
+    baseUrl,
+    registreDir,
+    cache,
+
+    /**
+     * Navigate — given a situation, return the relevant bloc + rules.
+     *
+     * @param {string} situation - e.g. "onboarding", "review", "implementation"
+     * @returns {Promise<{ bloc: string, blocData: object, rules: object[] } | null>}
+     */
+    async navigate(situation) {
+      const blocId = SITUATION_BLOC_MAP[situation] || 'B00';
+      return fetchWithFallback(
+        `navigate:${situation}`,
+        `/nemesis/navigate?situation=${encodeURIComponent(situation)}`,
+        () => {
+          const filename = BLOC_FILES[blocId];
+          if (!filename) return null;
+          const blocData = readBlocFile(registreDir, filename);
+          if (!blocData) return null;
+          return {
+            bloc: blocId,
+            situation,
+            atoms: blocData.atoms || [],
+            count: blocData.count || 0,
+          };
+        },
+      );
+    },
+
+    /**
+     * Bloc — return all atoms for a given bloc.
+     *
+     * @param {string} blocId - e.g. "B00", "B05", "B10"
+     * @returns {Promise<{ bloc: string, atoms: object[], count: number } | null>}
+     */
+    async bloc(blocId) {
+      return fetchWithFallback(
+        `bloc:${blocId}`,
+        `/nemesis/bloc/${encodeURIComponent(blocId)}`,
+        () => {
+          const filename = BLOC_FILES[blocId];
+          if (!filename) return null;
+          const data = readBlocFile(registreDir, filename);
+          if (!data) return null;
+          return {
+            bloc: data.bloc || blocId,
+            atoms: data.atoms || [],
+            count: data.count || 0,
+          };
+        },
+      );
+    },
+
+    /**
+     * Rules — return all rules, optionally filtered by priority.
+     *
+     * @param {object} [filter]
+     * @param {string} [filter.priority] - e.g. "REQUIRED", "FORBIDDEN", "BLOCKING"
+     * @returns {Promise<{ rules: object[], count: number } | null>}
+     */
+    async rules(filter = {}) {
+      const priorityParam = filter.priority ? `?priority=${encodeURIComponent(filter.priority)}` : '';
+      return fetchWithFallback(
+        `rules:${filter.priority || 'all'}`,
+        `/nemesis/rules${priorityParam}`,
+        () => {
+          const allRules = [];
+          for (const filename of Object.values(BLOC_FILES)) {
+            const data = readBlocFile(registreDir, filename);
+            if (data?.atoms) {
+              for (const atom of data.atoms) {
+                if (!filter.priority || atom.priority === filter.priority) {
+                  allRules.push(atom);
+                }
+              }
+            }
+          }
+          return { rules: allRules, count: allRules.length };
+        },
+      );
+    },
+
+    /**
+     * Flowmap — return the full FLOWMAP (steps + exceptions).
+     *
+     * @returns {Promise<{ steps: object[], exception_steps: object[] } | null>}
+     */
+    async flowmap() {
+      return fetchWithFallback(
+        'flowmap',
+        '/nemesis/flowmap',
+        () => {
+          const data = readBlocFile(registreDir, 'FLOWMAP.json');
+          if (!data) return null;
+          return {
+            steps: data.steps || [],
+            exception_steps: data.exception_steps || [],
+          };
+        },
+      );
+    },
+
+    /**
+     * Roles — return the 5 roles + team rules from B05.
+     *
+     * @returns {Promise<{ roles: object[], rules: object[] } | null>}
+     */
+    async roles() {
+      return fetchWithFallback(
+        'roles',
+        '/nemesis/roles',
+        () => {
+          const data = readBlocFile(registreDir, 'B05_equipe.json');
+          if (!data) return null;
+          const atoms = data.atoms || [];
+          const roles = atoms.filter(a => a.sousFamille === 'ROLE');
+          const rules = atoms.filter(a => a.sousFamille === 'EQUIPE');
+          return { roles, rules };
+        },
+      );
+    },
+
+    /**
+     * Transactions — return all transaction rules from B35.
+     *
+     * @returns {Promise<{ atoms: object[], count: number } | null>}
+     */
+    async transactions() {
+      return fetchWithFallback(
+        'transactions',
+        '/nemesis/transactions',
+        () => {
+          const data = readBlocFile(registreDir, 'B35_transactions.json');
+          if (!data) return null;
+          return { atoms: data.atoms || [], count: data.count || 0 };
+        },
+      );
+    },
+
+    /**
+     * QA — return all QA rules from B30.
+     *
+     * @returns {Promise<{ atoms: object[], count: number } | null>}
+     */
+    async qa() {
+      return fetchWithFallback(
+        'qa',
+        '/nemesis/qa',
+        () => {
+          const data = readBlocFile(registreDir, 'B30_qa.json');
+          if (!data) return null;
+          return { atoms: data.atoms || [], count: data.count || 0 };
+        },
+      );
+    },
+
+    /**
+     * Situations — return situation detection patterns.
+     *
+     * @returns {Promise<{ situations: object[] } | null>}
+     */
+    async situations() {
+      return fetchWithFallback(
+        'situations',
+        '/nemesis/situations',
+        () => ({
+          situations: Object.entries(SITUATION_BLOC_MAP).map(([situation, blocId]) => ({
+            situation,
+            bloc: blocId,
+            blocFile: BLOC_FILES[blocId] || null,
+          })),
+        }),
+      );
+    },
+
+    /**
+     * Ping — check if the Nemesis MCP server is reachable.
+     *
+     * @returns {Promise<{ ok: boolean, latency: number, error?: string }>}
+     */
+    async ping() {
+      const start = Date.now();
+      try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        const res = await fetch(`${baseUrl}/health`, { signal: controller.signal });
+        clearTimeout(timer);
+        return { ok: res.ok, latency: Date.now() - start };
+      } catch (err) {
+        return { ok: false, latency: Date.now() - start, error: err.message };
+      }
+    },
+  };
+}
+
+// Re-export for testability
+export { BLOC_FILES, SITUATION_BLOC_MAP, DEFAULT_CACHE_TTL, createCache };

package/lib/sync/service-session.js

@@ -0,0 +1,74 @@
+import { execFileSync } from 'node:child_process';
+import { executeWithFallback } from './fallback-engine.js';
+import { callLlmApi } from './llm-client.js';
+import { debug } from '../core/logger.js';
+
+/**
+ * Send a prompt to Claude via `claude -p` (stateless, no resume).
+ * @param {string} prompt
+ * @param {object} opts - { cwd, model, timeout }
+ * @returns {Promise<string>} response text
+ */
+export async function callSession(_serviceId, prompt, opts = {}) {
+  const timeoutMs = (opts.timeout || 30) * 1000;
+
+  const args = [
+    '-p', prompt,
+    '--output-format', 'json',
+    '--dangerously-skip-permissions',
+  ];
+  if (opts.model) args.push('--model', opts.model);
+
+  const result = execFileSync('claude', args, {
+    cwd: opts.cwd || process.cwd(),
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: timeoutMs,
+    encoding: 'utf-8',
+    env: { ...process.env },
+  });
+
+  // Parse response
+  try {
+    const parsed = JSON.parse(result);
+    return parsed.result || parsed.text || result;
+  } catch (e) {
+    debug(`callSession JSON parse: ${e.message}`);
+    return result;
+  }
+}
+
+/**
+ * Create a service caller for NoteWriter integration.
+ * Returns async (systemPrompt, userPrompt) => responseText
+ * Uses fallback engine for automatic retry across configured connexions.
+ * @param {string} projectRoot - Project root directory
+ * @param {string} serviceId - Service identifier (notes, kairos)
+ * @returns {Function} async (systemPrompt, userPrompt) => string
+ */
+export function createServiceCaller(projectRoot, serviceId) {
+  const caller = async (systemPrompt, userPrompt) => {
+    const { result, degraded, connexion_used, is_fallback } = await executeWithFallback(projectRoot, serviceId, async (ctx) => {
+      if (ctx.callService) {
+        // cli_tools — stateless call (combined prompt)
+        return ctx.callService(`${systemPrompt}\n\n---\n\n${userPrompt}`);
+      }
+      // API provider — direct HTTP call
+      return callLlmApi(ctx.connexion, ctx.credential, ctx.model, systemPrompt, userPrompt);
+    });
+    if (degraded || result === null) {
+      throw new Error('Aucun provider LLM disponible');
+    }
+    caller.lastProvider = connexion_used || null;
+    caller.wasFallback = is_fallback || false;
+    return result;
+  };
+  caller.lastProvider = null;
+  caller.wasFallback = false;
+  return caller;
+}
+
+// Legacy exports — no-op (no sessions to manage)
+export function getOrCreateSession() { return null; }
+export function stopSession() {}
+export function stopAllSessions() {}
+export function getActiveSessions() { return {}; }

package/lib/sync/sync-engine.js

@@ -0,0 +1,178 @@
+import { readdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+import { debug } from '../core/logger.js';
+
+const SYNC_STATE_FILE = '.nemesis-sync-state.json';
+
+const TYPE_PATTERNS = [
+  { pattern: /^ODM-/, type: 'ODM' },
+  { pattern: /^CR-/, type: 'CR' },
+  { pattern: /^MCT-/, type: 'MCT' },
+  { pattern: /^TXN-/, type: 'TXN' },
+  { pattern: /^CONTRIB-/, type: 'CONTRIB' },
+  { pattern: /^REGISTRY-/, type: 'REGISTRY' },
+  { pattern: /^DEC-/, type: 'DECISION' },
+  { pattern: /^INTV-/, type: 'INTERVENTION' },
+  { pattern: /^CONTEXT_PROJECT_/, type: 'CONTEXT' },
+  { pattern: /^NOTE-/, type: 'NOTE' },
+];
+
+/**
+ * Scan a directory recursively, collect JSON files (ignore template_* and legacy_*).
+ */
+export function scanDir(hcmDir) {
+  const results = [];
+
+  function walk(dir) {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        walk(join(dir, entry.name));
+      } else if (
+        entry.name.endsWith('.json') &&
+        !entry.name.startsWith('template_') &&
+        !entry.name.startsWith('legacy_') &&
+        entry.name !== SYNC_STATE_FILE
+      ) {
+        results.push({
+          path: join(dir, entry.name),
+          name: entry.name,
+          relative: relative(hcmDir, join(dir, entry.name)),
+        });
+      }
+    }
+  }
+
+  walk(hcmDir);
+  return results;
+}
+
+/**
+ * Determine the HCM type from a filename.
+ */
+export function matchPattern(filename) {
+  for (const { pattern, type } of TYPE_PATTERNS) {
+    if (pattern.test(filename)) return type;
+  }
+  return 'UNKNOWN';
+}
+
+/**
+ * Compute SHA-256 content hash of a file.
+ */
+export function computeHash(filepath) {
+  const content = readFileSync(filepath, 'utf-8');
+  return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Load sync state (previously synced hashes).
+ */
+export function loadSyncState(hcmDir) {
+  const stateFile = join(hcmDir, SYNC_STATE_FILE);
+  if (!existsSync(stateFile)) return {};
+  try {
+    return JSON.parse(readFileSync(stateFile, 'utf-8'));
+  } catch (e) {
+    debug(`loadSyncState: ${e.message}`);
+    return {};
+  }
+}
+
+/**
+ * Save sync state.
+ */
+export function saveSyncState(hcmDir, state) {
+  const stateFile = join(hcmDir, SYNC_STATE_FILE);
+  writeFileSync(stateFile, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Diff a file against the last known hash.
+ */
+export function diffHash(filepath, syncState) {
+  const currentHash = computeHash(filepath);
+  const previousHash = syncState[filepath] || null;
+  return {
+    changed: currentHash !== previousHash,
+    currentHash,
+    previousHash,
+  };
+}
+
+/**
+ * Sync a single file to HCM API.
+ */
+export async function syncToHcm(file, hcmClient) {
+  const content = readFileSync(file.path, 'utf-8');
+  let data;
+  try {
+    data = JSON.parse(content);
+  } catch (e) {
+    debug(`syncToHcm parse ${file.name}: ${e.message}`);
+    return { ok: false, error: 'Invalid JSON' };
+  }
+
+  const type = matchPattern(file.name);
+  const nodeId = extractNodeId(data, file.name, type);
+
+  try {
+    await hcmClient.deposit({
+      type,
+      label: nodeId,
+      id: `${type.toLowerCase()}:${nodeId}`,
+      data: { content: JSON.stringify(data), source_file: file.relative },
+    });
+    return { ok: true, nodeId, type };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Full sync — scan, match, diff, sync modified files.
+ */
+export async function fullSync(hcmDir, hcmClient) {
+  const files = scanDir(hcmDir);
+  const syncState = loadSyncState(hcmDir);
+  const results = { synced: 0, unchanged: 0, errors: 0, total: files.length, details: [] };
+
+  for (const file of files) {
+    const diff = diffHash(file.path, syncState);
+    if (!diff.changed) {
+      results.unchanged++;
+      results.details.push({ file: file.name, status: 'unchanged' });
+      continue;
+    }
+
+    const syncResult = await syncToHcm(file, hcmClient);
+    if (syncResult.ok) {
+      results.synced++;
+      syncState[file.path] = diff.currentHash;
+      results.details.push({ file: file.name, status: 'synced', type: syncResult.type });
+    } else {
+      results.errors++;
+      results.details.push({ file: file.name, status: 'error', error: syncResult.error });
+    }
+  }
+
+  saveSyncState(hcmDir, syncState);
+  return results;
+}
+
+function extractNodeId(data, filename, type) {
+  switch (type) {
+    case 'ODM': return data.odm_meta?.odm_id || filename.replace('.json', '');
+    case 'CR': return data.metadata?.odm_id || filename.replace('.json', '');
+    case 'MCT': return data.contract_meta?.id || filename.replace('.json', '');
+    case 'TXN': return data.transaction_meta?.txn_id || filename.replace('.json', '');
+    case 'CONTRIB': return data.contributor_meta?.contributor_id || filename.replace('.json', '');
+    case 'REGISTRY': return data.registry_meta?.registry_id || filename.replace('.json', '');
+    case 'DECISION': return data.decision_meta?.decision_id || filename.replace('.json', '');
+    case 'INTERVENTION': return data.intervention_meta?.intervention_id || filename.replace('.json', '');
+    case 'CONTEXT': return data.project_meta?.project_id || filename.replace('.json', '');
+    case 'NOTE': return data.note_meta?.note_id || filename.replace('.json', '');
+    default: return filename.replace('.json', '');
+  }
+}