@dotdrelle/wiki-manager 0.15.34 → 0.15.35

package/src/core/profileServiceStatus.test.js

@@ -0,0 +1,146 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { PROFILE_FLAGS, profileServiceStatus } from './agentsCompose.js';
+
+test('a disabled service says which flag, in which file, and what to do', () => {
+  const status = profileServiceStatus('connectors', { env: {} });
+  assert.equal(status.enabled, false);
+  assert.equal(status.flag, 'CONNECTORS_ENABLED');
+  // Le message d'origine — « unavailable or disabled » — ne disait ni lequel
+  // des deux, ni où regarder : Donna, faute de fait à citer, inventait un
+  // `cme.yaml` et un « manifeste des services actifs ».
+  assert.match(status.message, /CONNECTORS_ENABLED is not set/);
+  assert.match(status.message, /set CONNECTORS_ENABLED=true/);
+  assert.match(status.message, /\/start agents/);
+  assert.match(status.message, /\.env/);
+  // Le piège du profil Compose : le conteneur n'existe pas du tout, ce qui
+  // ressemble à un service planté.
+  assert.match(status.message, /does not exist at all/);
+});
+
+test('a disabled service quotes the value actually found', () => {
+  const status = profileServiceStatus('connectors', { env: { CONNECTORS_ENABLED: 'false' } });
+  assert.equal(status.enabled, false);
+  assert.match(status.message, /CONNECTORS_ENABLED is "false"/);
+});
+
+test('an enabled but unreachable service is a different diagnosis', () => {
+  const status = profileServiceStatus('connectors', { env: { CONNECTORS_ENABLED: 'true' } });
+  assert.equal(status.enabled, true);
+  assert.match(status.message, /enabled .* but not reachable/);
+  assert.doesNotMatch(status.message, /set CONNECTORS_ENABLED=true/);
+});
+
+test('an unknown service is not described as disabled', () => {
+  const status = profileServiceStatus('nope', { env: {} });
+  assert.equal(status.flag, null);
+  assert.match(status.message, /no "nope" service/);
+});
+
+test('/connector reports the reason instead of a bare "unavailable or disabled"', () => {
+  const source = readFileSync(
+    fileURLToPath(new URL('../commands/slash.js', import.meta.url)),
+    'utf8',
+  );
+  assert.match(source, /profileServiceStatus\('connectors'\)\.message/);
+  assert.doesNotMatch(source, /The connectors service is unavailable or disabled\./);
+});
+
+test('every profile flag is documented where the operator will look', () => {
+  const doc = readFileSync(
+    fileURLToPath(new URL('../../../llm-wiki/help-doc/06-troubleshooting.md', import.meta.url)),
+    'utf8',
+  );
+  // Donna répond aux questions produit depuis cette documentation : un drapeau
+  // absent d'ici est un drapeau qu'elle ne peut que deviner.
+  for (const flag of Object.values(PROFILE_FLAGS)) {
+    assert.ok(doc.includes(flag), `${flag} must be documented in help-doc/06-troubleshooting.md`);
+  }
+});
+
+test('stopping the agents resolves the same manager files as starting them', () => {
+  const source = readFileSync(
+    fileURLToPath(new URL('./wikiSetup.js', import.meta.url)),
+    'utf8',
+  );
+  // `stopAgents` n'épinglait pas WIKI_MANAGER_ENV_FILE : le script résolvait
+  // `.env` contre le répertoire du paquet, `connectors_enabled` y lisait un
+  // profil inactif, et `docker compose down` partait sans
+  // `--profile connectors`. Un service à profil inactif étant invisible à
+  // Compose, le conteneur restait debout — `/stop agents` annonçait un succès
+  // en laissant tourner ce qu'il prétendait arrêter.
+  const stopBlock = source.slice(source.indexOf('export async function stopAgents'));
+  for (const key of ['WIKI_MANAGER_ENV_FILE: managerEnvFile()', 'WIKI_MANAGER_ENDPOINTS_FILE: managerMcpEndpointsFile()']) {
+    assert.ok(stopBlock.includes(key), `stopAgents must pin ${key}`);
+  }
+});
+
+test('"all" means the same thing to start and to stop', () => {
+  const slash = readFileSync(fileURLToPath(new URL('../commands/slash.js', import.meta.url)), 'utf8');
+  // `/start all` démarrait les agents, `/stop all` ne les arrêtait pas : la
+  // séquence start/stop ne revenait donc pas à l'état de départ.
+  assert.match(slash, /const startsAgents = service === 'all';/);
+  assert.match(slash, /const stopsAgents = service === 'all';/);
+  assert.match(slash, /if \(stopsAgents\) \{\s*\n\s*const agentsResult = await runAgentCommand\(stopAgents, 'stop'\);/);
+});
+
+test('the addressable agents are read from the compose file, never hard-coded', async () => {
+  const { agentServiceNames, togglableAgentNames } = await import('./agentsCompose.js');
+  const declared = agentServiceNames();
+
+  // Une liste figée annonçait `mailer`, qui ne vit que dans l'exemple
+  // d'override : proposer un service absent, c'est promettre un
+  // « no such service ».
+  assert.ok(declared.includes('connectors'));
+  assert.ok(declared.includes('cme'));
+  assert.ok(!declared.includes('mailer'), 'mailer is not declared until the operator uncomments it');
+
+  // Et seuls les agents à drapeau se proposent un par un dans l'interface.
+  assert.deepEqual(togglableAgentNames(), ['connectors']);
+  for (const name of togglableAgentNames()) {
+    assert.ok(declared.includes(name), `${name} must actually exist in the agents stack`);
+  }
+});
+
+test('an agent can be started and stopped on its own', () => {
+  const setup = readFileSync(fileURLToPath(new URL('./wikiSetup.js', import.meta.url)), 'utf8');
+  const slash = readFileSync(fileURLToPath(new URL('../commands/slash.js', import.meta.url)), 'utf8');
+  const script = readFileSync(fileURLToPath(new URL('../../wiki-workspace', import.meta.url)), 'utf8');
+
+  assert.match(setup, /'agents', 'up', \.\.\.\(options\.services \?\? \[\]\)/);
+  assert.match(setup, /'agents', 'down', \.\.\.\(options\.services \?\? \[\]\)/);
+  // La pile agents est un projet Compose distinct : sans ce routage, `/start
+  // connectors` allait chercher un service inexistant côté workspace.
+  assert.match(slash, /agentServiceNames\(\)\.includes\(service\)/);
+  // `down <service>` supprimerait le réseau commun : Compose impose stop + rm.
+  assert.match(script, /_agents_dc stop "\$@"/);
+  assert.match(script, /_agents_dc rm -f "\$@"/);
+});
+
+test('a connector read tool is not mistaken for the limit of its agent', () => {
+  const graph = readFileSync(fileURLToPath(new URL('../agent/graph.js', import.meta.url)), 'utf8');
+  // « récupère ce mail » et « envoie un mail » ont été refusés comme
+  // impossibles, alors que l'agent connectors déclare `external-source.collect`
+  // et `communication.send-email`. Donna raisonnait sur les outils de lecture
+  // exposés au chat — qui ne rendent que des métadonnées — au lieu de déléguer.
+  assert.match(graph, /direct read tools of a connector are a preview/);
+  assert.match(graph, /delegated through runtime__delegate, not answered from a read tool/);
+  // Et un droit manquant doit être nommé comme tel, pas présenté comme une
+  // fonctionnalité absente.
+  assert.match(graph, /lack of an authorization grant or scope/);
+});
+
+test('the system prompt points product questions at the documentation tools', () => {
+  const graph = readFileSync(
+    fileURLToPath(new URL('../agent/graph.js', import.meta.url)),
+    'utf8',
+  );
+  // Les outils help_* sont exposés (allow-list du mode chat) mais le prompt ne
+  // disait nulle part qu'ils sont LA source des questions produit : Donna
+  // répondait de mémoire, et inventait.
+  assert.match(graph, /bundled product documentation is your source/);
+  assert.match(graph, /call the documentation search\/read tools FIRST/);
+  assert.match(graph, /Configuration facts are never answered from memory/);
+});

package/src/core/wikiSetup.js

@@ -72,7 +72,7 @@ export async function startAgents(options = {}) {
       : await missingAgentImages(composeContext);
     if (absentImages.length > 0) options.onImagesMissing?.(absentImages);
     const exec = options.exec ?? execFileAsync;
-    const { stdout, stderr } = await exec(join(managerRoot(), 'wiki-workspace'), ['agents', 'up'], {
+    const { stdout, stderr } = await exec(join(managerRoot(), 'wiki-workspace'), ['agents', 'up', ...(options.services ?? [])], {
       cwd: managerRoot(),
       env: {
         ...process.env,
@@ -148,11 +148,20 @@ function agentsStartFailure({ downServices = [], missingServices = [], profiles
 
 export async function stopAgents(options = {}) {
   try {
-    const { stdout, stderr } = await execFileAsync(join(managerRoot(), 'wiki-workspace'), ['agents', 'down'], {
+    const { stdout, stderr } = await execFileAsync(join(managerRoot(), 'wiki-workspace'), ['agents', 'down', ...(options.services ?? [])], {
       cwd: managerRoot(),
       env: {
         ...process.env,
         WIKI_WORKSPACES_DIR: workspacesDir(),
+        // Même épinglage que startAgents, et pour la même raison : cwd est la
+        // racine du paquet, donc sans ces variables le script résout `.env`
+        // contre $PWD. `connectors_enabled` lisait alors le .env du PAQUET,
+        // concluait que le profil était inactif, et `docker compose down`
+        // partait sans `--profile connectors` — un service à profil inactif est
+        // invisible à Compose, donc le conteneur restait debout. `/stop agents`
+        // annonçait un succès en laissant tourner ce qu'il prétendait arrêter.
+        WIKI_MANAGER_ENV_FILE: managerEnvFile(),
+        WIKI_MANAGER_ENDPOINTS_FILE: managerMcpEndpointsFile(),
         AGENTS_DATA_DIR: resolveAgentsDataDir(),
       },
       timeout: options.timeout ?? 120_000,

package/src/core/wikiWorkspace.test.js

@@ -66,11 +66,17 @@ test('wiki-workspace provisions connector secrets and persistent state', async (
   assert.match(script, /delete config\.chatAccess\.servers\.connectors/);
 });
 
-test('local connector builds require both public Desktop OAuth values', async () => {
+test('the manager never builds an image, it only runs published ones', async () => {
   const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
 
-  assert.match(script, /for build_key in WIKILLM_GOOGLE_OAUTH_CLIENT_ID WIKILLM_GOOGLE_OAUTH_CLIENT_SECRET/);
-  assert.match(script, /require_connectors_build_credentials/);
+  // Ce script est livré dans le paquet npm, où le dépôt agent-connectors
+  // n'existe pas : il ne peut ni construire l'image, ni lire le
+  // .env.build.local qui porte l'application OAuth. La construction appartient
+  // à build-and-push.sh. Pour utiliser sa propre application Google,
+  // l'opérateur surcharge GOOGLE_OAUTH_CLIENT_ID / _SECRET dans le .env.
+  assert.doesNotMatch(script, /--build\b/);
+  assert.doesNotMatch(script, /\.env\.build\.local/);
+  assert.doesNotMatch(script, /require_connectors_build_credentials/);
 });
 
 test('workspace creation keeps mutable manager files outside the installed package', async () => {

package/src/runtime/lifecycle.js

@@ -1,5 +1,5 @@
 import { execFile, spawn } from 'node:child_process';
-import { readdirSync, statSync } from 'node:fs';
+import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { activeCacertPath } from '../core/cacert.js';
@@ -93,6 +93,19 @@ export async function ensureRuntime({
   }
 
   const runtimeNode = await assertRuntimeNode();
+  // Le fils écrivait sur `stdio: 'ignore'`. Un runtime qui plantait au
+  // démarrage — port pris, état SQLite illisible, config invalide — ne laissait
+  // donc aucune trace, et le shell n'avait qu'un « did not become healthy » à
+  // afficher. On redirige vers le même `runtime.log` que
+  // `wiki-workspace runtime up`, pour que les deux chemins de démarrage se
+  // diagnostiquent de la même façon.
+  const logPath = runtimeLogPath(stateDir);
+  let logFd = null;
+  try {
+    mkdirSync(resolve(stateDir), { recursive: true });
+    logFd = openSync(logPath, 'a');
+  } catch { /* le log est un confort : ne jamais empêcher le démarrage */ }
+
   const child = spawn(runtimeNode.executable, [
     binPath,
     'runtime',
@@ -104,7 +117,7 @@ export async function ensureRuntime({
     stateDir,
   ], {
     detached: true,
-    stdio: 'ignore',
+    stdio: logFd === null ? 'ignore' : ['ignore', logFd, logFd],
     env: {
       ...process.env,
       ...(auth.token ? { WIKI_MANAGER_RUNTIME_TOKEN: auth.token } : {}),
@@ -112,15 +125,104 @@ export async function ensureRuntime({
     },
   });
   child.unref();
+  if (logFd !== null) closeSync(logFd);
+
+  // Le pid manquait : `wiki-workspace runtime down` répondait « not running »
+  // sur un runtime démarré par le shell, et le processus restait sur le port.
+  writeRuntimePidFile(stateDir, child.pid);
+
+  // Un fils qui meurt aussitôt faisait quand même attendre le délai complet.
+  let exited = null;
+  child.once('exit', (code, signal) => { exited = { code, signal }; });
 
   const deadline = Date.now() + timeoutMs;
   let health = null;
   while (Date.now() < deadline) {
     health = await runtimeHealthOrNull(url, auth.token);
     if (health) return { url, started: true, health, pid: child.pid, token: auth.token, tokenPath: auth.tokenPath, node: runtimeNode };
+    if (exited) break;
     await new Promise((resolveDelay) => setTimeout(resolveDelay, 150));
   }
-  throw new Error(`Runtime did not become healthy at ${url}`);
+  if (exited) removeRuntimePidFile(stateDir);
+  throw new Error(await describeRuntimeFailure({ url, token: auth.token, stateDir, exited, logPath }));
+}
+
+export function runtimeLogPath(stateDir = defaultRuntimeStateDir()) {
+  return join(resolve(stateDir), 'runtime.log');
+}
+
+export function runtimePidPath(stateDir = defaultRuntimeStateDir()) {
+  return join(resolve(stateDir), 'runtime.pid');
+}
+
+function writeRuntimePidFile(stateDir, pid) {
+  if (!pid) return;
+  try {
+    mkdirSync(resolve(stateDir), { recursive: true });
+    writeFileSync(runtimePidPath(stateDir), `${pid}\n`, 'utf8');
+  } catch { /* idem : informatif, jamais bloquant */ }
+}
+
+function removeRuntimePidFile(stateDir) {
+  try { unlinkSync(runtimePidPath(stateDir)); } catch { /* déjà absent */ }
+}
+
+/**
+ * Message d'échec du démarrage du runtime.
+ *
+ * `checkRuntimeHealth` rend `null` sur n'importe quelle réponse non-2xx : un
+ * 401 — jeton lu dans un autre `state-dir` que celui du runtime déjà en place —
+ * était donc rigoureusement indiscernable d'un port fermé. Ici on refait la
+ * requête pour distinguer les deux, et on joint la fin du journal.
+ */
+async function describeRuntimeFailure({ url, token, stateDir, exited, logPath }) {
+  const lines = [`Runtime did not become healthy at ${url}`];
+
+  if (exited) {
+    lines.push(
+      `The runtime process exited immediately (${exited.signal ? `signal ${exited.signal}` : `code ${exited.code}`}).`,
+    );
+  }
+
+  const probe = await probeRuntimeHealth(url, token);
+  if (probe.status === 401 || probe.status === 403) {
+    lines.push(
+      `A runtime IS answering on this port but rejected our token (HTTP ${probe.status}).`,
+      `It was started from another state directory: this one is ${resolve(stateDir)}.`,
+      'Stop it (`wiki-workspace runtime down` from that directory, or kill the process holding the port) or export WIKI_MANAGER_RUNTIME_TOKEN with its token.',
+    );
+  } else if (probe.status) {
+    lines.push(`Health endpoint answered HTTP ${probe.status}.`);
+  } else if (probe.error) {
+    lines.push(`Health endpoint unreachable: ${probe.error}`);
+  }
+
+  const tail = readLogTail(logPath, 12);
+  if (tail) lines.push(`Last lines of ${logPath}:`, tail);
+  else lines.push(`No runtime log at ${logPath}.`);
+
+  return lines.join('\n');
+}
+
+async function probeRuntimeHealth(url, token) {
+  try {
+    const response = await fetch(`${String(url).replace(/\/+$/, '')}/health`, {
+      headers: token ? { Authorization: `Bearer ${token}` } : {},
+      signal: AbortSignal.timeout(2000),
+    });
+    return { status: response.status, error: null };
+  } catch (err) {
+    return { status: null, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+function readLogTail(logPath, count) {
+  try {
+    const lines = readFileSync(logPath, 'utf8').split('\n').filter((line) => line.trim() !== '');
+    return lines.slice(-count).map((line) => `  ${line}`).join('\n') || null;
+  } catch {
+    return null;
+  }
 }
 
 async function waitForRuntimeShutdown(url, token, timeoutMs) {

package/src/runtime/lifecycle.test.js

@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createServer } from 'node:http';
+import { existsSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ensureRuntime, runtimeLogPath, runtimePidPath } from './lifecycle.js';
+
+function tempStateDir() {
+  return mkdtempSync(join(tmpdir(), 'wiki-runtime-state-'));
+}
+
+/**
+ * Occupe un port avec un serveur qui répond `status`.
+ *
+ * Deux effets, tous deux voulus : le runtime que `ensureRuntime` va lancer ne
+ * pourra pas se lier au port et sortira aussitôt — c'est le scénario réel du
+ * « port déjà pris » — et la sonde de santé recevra un statut choisi.
+ */
+async function occupiedPort(status) {
+  const server = createServer((_req, res) => res.writeHead(status).end('nope'));
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  return { server, port: server.address().port };
+}
+
+async function failingEnsureRuntime(status) {
+  const stateDir = tempStateDir();
+  const { server, port } = await occupiedPort(status);
+  try {
+    const error = await ensureRuntime({
+      host: '127.0.0.1',
+      port,
+      stateDir,
+      url: `http://127.0.0.1:${port}`,
+      timeoutMs: 3000,
+    }).then(() => null, (err) => err);
+    assert.ok(error, 'ensureRuntime must fail when nothing healthy answers');
+    return { error, stateDir };
+  } finally {
+    server.close();
+  }
+}
+
+test('a failed start reports the captured log instead of a bare message', async () => {
+  const { error, stateDir } = await failingEnsureRuntime(500);
+  assert.match(error.message, /Runtime did not become healthy/);
+  // Le fils écrivait sur `stdio: 'ignore'` : sa sortie — ici l'échec de bind —
+  // était perdue, et l'opérateur n'avait aucune piste.
+  assert.match(error.message, /runtime\.log/);
+  assert.ok(existsSync(runtimeLogPath(stateDir)), 'the child output must be captured to a log file');
+  assert.match(error.message, /exited immediately|Health endpoint answered HTTP 500/);
+});
+
+test('a runtime answering 401 is not reported as unreachable', async () => {
+  // Cas réel : un runtime démarré depuis un autre state-dir répond, mais
+  // rejette notre jeton. `checkRuntimeHealth` rend `null` sur tout non-2xx,
+  // donc ce cas était rigoureusement indiscernable d'un port fermé.
+  const { error, stateDir } = await failingEnsureRuntime(401);
+  assert.match(error.message, /rejected our token \(HTTP 401\)/);
+  assert.match(error.message, /another state directory/);
+  assert.ok(error.message.includes(stateDir), 'the message must name the state dir in use');
+});
+
+test('the pid file path is the one `wiki-workspace runtime down` reads', () => {
+  const stateDir = tempStateDir();
+  assert.equal(runtimePidPath(stateDir), join(stateDir, 'runtime.pid'));
+  assert.equal(runtimeLogPath(stateDir), join(stateDir, 'runtime.log'));
+});